From 56a6a445bc5c0b145bcd4409ebcae150780b73cb Mon Sep 17 00:00:00 2001 From: Dave McCowan Date: Tue, 22 Sep 2015 09:54:16 -0400 Subject: [PATCH] Add reference guide documenting Certificate Authorities API Document the APIs and their parameters, attributes, and status codes. Also change the returned status code from 405 to 409 when a user attempts to remove-from-project a preferred CA. Change-Id: I6a0bffa84c8dfb303580b5b050bda8aedb8277ad Partially-implements: blueprint add-cas --- barbican/api/controllers/cas.py | 2 +- barbican/tests/api/controllers/test_cas.py | 2 +- doc/source/api/index.rst | 2 + doc/source/api/reference/cas.rst | 973 ++++++++++++++++++++- doc/source/api/reference/certificates.rst | 2 +- 5 files changed, 974 insertions(+), 7 deletions(-) diff --git a/barbican/api/controllers/cas.py b/barbican/api/controllers/cas.py index d476038d1..c703ac1cc 100644 --- a/barbican/api/controllers/cas.py +++ b/barbican/api/controllers/cas.py @@ -55,7 +55,7 @@ def _requested_preferred_ca_not_a_project_ca(): def _cant_remove_preferred_ca_from_project(): pecan.abort( - 405, + 409, u._('Please change the preferred CA to a different project CA ' 'before removing it.') ) diff --git a/barbican/tests/api/controllers/test_cas.py b/barbican/tests/api/controllers/test_cas.py index fff5e46a0..4a04992a4 100644 --- a/barbican/tests/api/controllers/test_cas.py +++ b/barbican/tests/api/controllers/test_cas.py @@ -276,7 +276,7 @@ class WhenTestingCAsResource(utils.BarbicanAPIBaseTestCase): resp = self.app.post('/cas/{0}/remove-from-project'.format( self.project_ca_ids[1]), expect_errors=True) - self.assertEqual(405, resp.status_int) + self.assertEqual(409, resp.status_int) def test_should_remove_preferred_ca_if_last_project_ca(self): self.create_cas() diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index 1c9a9ac67..c371f4770 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -13,6 +13,7 @@ User Guide ./userguide/acls ./userguide/pkcs11keygeneration ./userguide/certificates + ./userguide/cas ./userguide/dogtag_setup ./userguide/quotas @@ -26,4 +27,5 @@ API Reference ./reference/containers ./reference/acls ./reference/certificates + ./reference/cas ./reference/quotas diff --git a/doc/source/api/reference/cas.rst b/doc/source/api/reference/cas.rst index 274a6924c..cf01283aa 100644 --- a/doc/source/api/reference/cas.rst +++ b/doc/source/api/reference/cas.rst @@ -1,5 +1,970 @@ -**************************** -Certificates API - Reference -**************************** +**************************************** +Certificates Authorities API - Reference +**************************************** -TBD (alee) - To be filled in a subsequent patch this week. +Barbican provides an API to interact with certificate authorities (CAs). For +an introduction to CAs and how Barbican manages them, see the +:doc:`Certificate Authorities User's Guide <../userguide/cas>`. + +Understanding the following concepts, explained in the user's +guide, is important to understanding how to use this API. + +- Certificate Authorities +- Subordinate Certificate Authorities +- Project CAs +- Preferred CAs +- Global Preferred CAs + +This document will focus on the details of the Barbican /v1/cas REST API. + +GET /v1/cas +########### +Any user can request a list of CAs that may be used. Depending on the settings +for the user's project, the returned list may be filtered. +If a project has project CAs configured, the list will only contain only the +project CAs and the subordinate CAs for that project. If not, it will contain +all of the configured CAs and none of the subordinate CAs owned by other +projects. + +.. _get_cas_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas + Headers: + X-Auth-Token: + Accept: application/json + + + Response: + + HTTP/1.1 200 OK + Content-Type: application/json + + {"cas": ["http://localhost:9311/v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54", + "http://localhost:9311/v1/cas/d9e853eb-aea4-4002-9be7-78665062f393"], + "total": 2} + + +.. _get_cas_parameters: + +Parameters +********** + ++--------------+---------+----------------------------------------------------------------+ +| Name | Type | Description | ++==============+=========+================================================================+ +| offset | integer | The starting index within the total list of the project | +| | | CAs that you would like to receive. | ++--------------+---------+----------------------------------------------------------------+ +| limit | integer | The maximum number of records to return. | ++--------------+---------+----------------------------------------------------------------+ +| plugin_name | string | Filter the returned list of CAs based on plugin name | ++--------------+---------+----------------------------------------------------------------+ +| plugin_id | string | Filter the returned list of CAs based on plugin id | ++--------------+---------+----------------------------------------------------------------+ + +.. _get_cas_response_attributes: + +Response Attributes +******************* + ++----------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++================+=========+==============================================================+ +| cas | list | A list of CA references | ++----------------+---------+--------------------------------------------------------------+ +| total | integer | The total number of configured project CAs records. | ++----------------+---------+--------------------------------------------------------------+ +| next | string | A HATEOS url to retrieve the next set of CAs based on | +| | | the offset and limit parameters. This attribute is only | +| | | available when the total number of secrets is greater than | +| | | offset and limit parameter combined. | ++----------------+---------+--------------------------------------------------------------+ +| previous | string | A HATEOS url to retrieve the previous set of CAs based | +| | | on the offset and limit parameters. This attribute is only | +| | | available when the request offset is greater than 0. | ++----------------+---------+--------------------------------------------------------------+ + +.. _get_cas_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ + + +GET /v1/cas/all +############### +A project admin can request a list of CAs that may be used. This returned list will +include root certificates, as well as CAs assigned to the project and subCAs +created for this project. This will allow a project admin to find all CAs that +his project could have access to, so he can manage his project CA list. + +.. _get_cas_all_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas/all + Headers: + X-Auth-Token: + Accept: application/json + + + Response: + + HTTP/1.1 200 OK + Content-Type: application/json + + {"cas": ["http://localhost:9311/v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54", + "http://localhost:9311/v1/cas/d9e853eb-aea4-4002-9be7-78665062f393"], + "total": 2} + + +.. _get_cas_all_parameters: + +Parameters +********** + ++--------------+---------+----------------------------------------------------------------+ +| Name | Type | Description | ++==============+=========+================================================================+ +| offset | integer | The starting index within the total list of the project | +| | | CAs that you would like to receive. | ++--------------+---------+----------------------------------------------------------------+ +| limit | integer | The maximum number of records to return. | ++--------------+---------+----------------------------------------------------------------+ +| plugin_name | string | Filter the returned list of CAs based on plugin name | ++--------------+---------+----------------------------------------------------------------+ +| plugin_id | string | Filter the returned list of CAs based on plugin id | ++--------------+---------+----------------------------------------------------------------+ + +.. _get_cas_all_response_attributes: + +Response Attributes +******************* + ++----------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++================+=========+==============================================================+ +| cas | list | A list of CA references | ++----------------+---------+--------------------------------------------------------------+ +| total | integer | The total number of configured project CAs records. | ++----------------+---------+--------------------------------------------------------------+ +| next | string | A HATEOS url to retrieve the next set of CAs based on | +| | | the offset and limit parameters. This attribute is only | +| | | available when the total number of secrets is greater than | +| | | offset and limit parameter combined. | ++----------------+---------+--------------------------------------------------------------+ +| previous | string | A HATEOS url to retrieve the previous set of CAs based | +| | | on the offset and limit parameters. This attribute is only | +| | | available when the request offset is greater than 0. | ++----------------+---------+--------------------------------------------------------------+ + +.. _get_cas_all_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ + +GET /v1/cas/{CA_ID} +################### +Any user can request details about a CA to which he has permissions. + +.. _get_cas_caid_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54 + Headers: + X-Auth-Token: + Accept: application/json + + + Response: + + HTTP/1.1 200 OK + Content-Type: application/json + + {"status": "ACTIVE", + "updated": "2015-09-22T05:25:35.305647", + "created": "2015-09-22T05:25:35.305647", + "plugin_name": "barbican.plugin.snakeoil_ca.SnakeoilCACertificatePlugin", + "meta": [{"ca_signing_certificate": "-----BEGIN CERTIFICATE----- + MIIC+zCCAeOgAwIBAgIBATANBgkqhkiG9w0BAQsFADA1MR0wGwYDVQQDDBRTbmFr + ZW9pbCBDZXJ0aWZpY2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wHhcNMTUwOTI0 + MDM0MTI4WhcNMTUwOTI0MDQ0MjE4WjA1MR0wGwYDVQQDDBRTbmFrZW9pbCBDZXJ0 + aWZpY2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUA + A4IBDwAwggEKAoIBAQC2OonnytCeizC+2FJlS7rUOjrIukKndwltXex46YUem09T + y2+5ZNvl1QypUN1JXZSjUT27oG9jUTsNUzLHuJe8dW6p3z37WNpBCJY5BOjoDFG9 + ce5ZrzucVs6QDnsuqD9NqtiECVFNg1qQjVvg9n5I0pl81c0mEfjWwqgOJ303W0IY + KnisMByXewyPN57cZuTJQFhUT3fvxF5W1MM03fqILKELL0WE9ALeTThHR9fJRras + QgrJYNnb20RwUZv5hqP21iwsaq3CV2+KODR4IlgglFXRN4gfIzZ9cfst95yy0nhV + pcf6+IOycYZP7enTEU4e1jtfNn40yQPLlKei9/jrAgMBAAGjFjAUMBIGA1UdEwEB + /wQIMAYBAf8CAQUwDQYJKoZIhvcNAQELBQADggEBAEn0wkHsMN7vvDShFLKlpE+1 + twrIqSekgqb5wdAId9sKblXQTojI6caiImCleFVzhKxQvuoS31dpg7hh2zw+I8P1 + U0zvYrJlM8HVunHkWIdFuEuP7hrDnTA2NZbEN7EBSDksNtC+T+hcZcYcIs3hpV7p + PdjhjU9D4IcFd7ooVra7Lt2q3zl2XZ7TCzkIWV9jqCBNrlf7Q6QkLWe41k6kIJUT + bl0HHqk9cRxr9hkwMKTjIO6G6gbPepqOuyEym8qjyVckRCQN8W+HUI3FV/XBcDk5 + FkhWnqzJ6aTjBQD3WxOtnhm421dERi60RHdTInK6l6BKRUstmPyc3nfMouBarH8= + -----END CERTIFICATE----- + "}}, + {"intermediates": "-----BEGIN PKCS7----- + MIIDLAYJKoZIhvcNAQcCoIIDHTCCAxkCAQExADALBgkqhkiG9w0BBwGgggL/MIIC + +zCCAeOgAwIBAgIBATANBgkqhkiG9w0BAQsFADA1MR0wGwYDVQQDDBRTbmFrZW9p + bCBDZXJ0aWZpY2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wHhcNMTUwOTI0MDM0 + MTI4WhcNMTUwOTI0MDQ0MjE4WjA1MR0wGwYDVQQDDBRTbmFrZW9pbCBDZXJ0aWZp + Y2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB + DwAwggEKAoIBAQC2OonnytCeizC+2FJlS7rUOjrIukKndwltXex46YUem09Ty2+5 + ZNvl1QypUN1JXZSjUT27oG9jUTsNUzLHuJe8dW6p3z37WNpBCJY5BOjoDFG9ce5Z + rzucVs6QDnsuqD9NqtiECVFNg1qQjVvg9n5I0pl81c0mEfjWwqgOJ303W0IYKnis + MByXewyPN57cZuTJQFhUT3fvxF5W1MM03fqILKELL0WE9ALeTThHR9fJRrasQgrJ + YNnb20RwUZv5hqP21iwsaq3CV2+KODR4IlgglFXRN4gfIzZ9cfst95yy0nhVpcf6 + +IOycYZP7enTEU4e1jtfNn40yQPLlKei9/jrAgMBAAGjFjAUMBIGA1UdEwEB/wQI + MAYBAf8CAQUwDQYJKoZIhvcNAQELBQADggEBAEn0wkHsMN7vvDShFLKlpE+1twrI + qSekgqb5wdAId9sKblXQTojI6caiImCleFVzhKxQvuoS31dpg7hh2zw+I8P1U0zv + YrJlM8HVunHkWIdFuEuP7hrDnTA2NZbEN7EBSDksNtC+T+hcZcYcIs3hpV7pPdjh + jU9D4IcFd7ooVra7Lt2q3zl2XZ7TCzkIWV9jqCBNrlf7Q6QkLWe41k6kIJUTbl0H + Hqk9cRxr9hkwMKTjIO6G6gbPepqOuyEym8qjyVckRCQN8W+HUI3FV/XBcDk5FkhW + nqzJ6aTjBQD3WxOtnhm421dERi60RHdTInK6l6BKRUstmPyc3nfMouBarH+hADEA + -----END PKCS7----- + "}, + {"description": "Certificate Authority - Snakeoil CA"}, + {"name": "Snakeoil CA"}], + "ca_id": "9277c4b4-2c7a-4612-a693-1e738a83eb54", + "plugin_ca_id": "Snakeoil CA", + "expiration": "2015-09-23T05:25:35.300633"} + + +.. _get_cas_caid_response_attributes: + +Response Attributes +******************* + ++------------------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++========================+=========+==============================================================+ +| status | list | Status of the CA | ++------------------------+---------+--------------------------------------------------------------+ +| updated | time | Date and time CA was last updated . | ++------------------------+---------+--------------------------------------------------------------+ +| created | time | Date and time CA was created | ++------------------------+---------+--------------------------------------------------------------+ +| plugin_name | string | Name of certificate plugin associated with this CA | ++------------------------+---------+--------------------------------------------------------------+ +| meta | list | List of additional information for this CA | ++------------------------+---------+--------------------------------------------------------------+ +| ca_signing_certificate | PEM | Part of meta, the CA signing certificate for this CA | ++------------------------+---------+--------------------------------------------------------------+ +| intermediates | pkcs7 | Part of meta, the intermediate certificate chain for this CA | ++------------------------+---------+--------------------------------------------------------------+ +| description | string | Part of meta, a description given to the CA | ++------------------------+---------+--------------------------------------------------------------+ +| name | string | Part of meta, a given name for a CA | ++------------------------+---------+--------------------------------------------------------------+ +| ca_id | string | ID of this CA | ++------------------------+---------+--------------------------------------------------------------+ +| plugin_ca_id | string | ID of the plugin | ++------------------------+---------+--------------------------------------------------------------+ +| expiration | time | Expiration date of the CA | ++------------------------+---------+--------------------------------------------------------------+ + +.. _get_cas_caid_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ + +GET /v1/cas/{CA_ID}/cacert +########################## +Any user can request the CA signing certificate of a CA to which he has permissions. The +format of the returned certificate will be PEM. + +.. _get_cas_caid_cacert_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/cacert + Headers: + X-Auth-Token: + Accept: */* + + + Response: + + HTTP/1.1 200 OK + Content-Type: text/html + + -----BEGIN CERTIFICATE----- + MIIC+zCCAeOgAwIBAgIBATANBgkqhkiG9w0BAQsFADA1MR0wGwYDVQQDDBRTbmFr + ZW9pbCBDZXJ0aWZpY2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wHhcNMTUwOTI0 + MDM0MTI4WhcNMTUwOTI0MDQ0MjE4WjA1MR0wGwYDVQQDDBRTbmFrZW9pbCBDZXJ0 + aWZpY2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUA + A4IBDwAwggEKAoIBAQC2OonnytCeizC+2FJlS7rUOjrIukKndwltXex46YUem09T + y2+5ZNvl1QypUN1JXZSjUT27oG9jUTsNUzLHuJe8dW6p3z37WNpBCJY5BOjoDFG9 + ce5ZrzucVs6QDnsuqD9NqtiECVFNg1qQjVvg9n5I0pl81c0mEfjWwqgOJ303W0IY + KnisMByXewyPN57cZuTJQFhUT3fvxF5W1MM03fqILKELL0WE9ALeTThHR9fJRras + QgrJYNnb20RwUZv5hqP21iwsaq3CV2+KODR4IlgglFXRN4gfIzZ9cfst95yy0nhV + pcf6+IOycYZP7enTEU4e1jtfNn40yQPLlKei9/jrAgMBAAGjFjAUMBIGA1UdEwEB + /wQIMAYBAf8CAQUwDQYJKoZIhvcNAQELBQADggEBAEn0wkHsMN7vvDShFLKlpE+1 + twrIqSekgqb5wdAId9sKblXQTojI6caiImCleFVzhKxQvuoS31dpg7hh2zw+I8P1 + U0zvYrJlM8HVunHkWIdFuEuP7hrDnTA2NZbEN7EBSDksNtC+T+hcZcYcIs3hpV7p + PdjhjU9D4IcFd7ooVra7Lt2q3zl2XZ7TCzkIWV9jqCBNrlf7Q6QkLWe41k6kIJUT + bl0HHqk9cRxr9hkwMKTjIO6G6gbPepqOuyEym8qjyVckRCQN8W+HUI3FV/XBcDk5 + FkhWnqzJ6aTjBQD3WxOtnhm421dERi60RHdTInK6l6BKRUstmPyc3nfMouBarH8= + -----END CERTIFICATE----- + +.. _get_cas_caid_cacert_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ + +GET /v1/cas/{CA_ID}/intermediates +################################# +Any user can request the certificate chain of a CA to which he has permissions. +The format of the returned chain will be PKCS#7. + +.. _get_cas_caid_intermediates_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/intermediates + Headers: + X-Auth-Token: + Accept: */* + + + Response: + + HTTP/1.1 200 OK + Content-Type: text/html + + -----BEGIN PKCS7----- + MIIDLAYJKoZIhvcNAQcCoIIDHTCCAxkCAQExADALBgkqhkiG9w0BBwGgggL/MIIC + +zCCAeOgAwIBAgIBATANBgkqhkiG9w0BAQsFADA1MR0wGwYDVQQDDBRTbmFrZW9p + bCBDZXJ0aWZpY2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wHhcNMTUwOTI0MDM0 + MTI4WhcNMTUwOTI0MDQ0MjE4WjA1MR0wGwYDVQQDDBRTbmFrZW9pbCBDZXJ0aWZp + Y2F0ZTEUMBIGA1UECgwLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB + DwAwggEKAoIBAQC2OonnytCeizC+2FJlS7rUOjrIukKndwltXex46YUem09Ty2+5 + ZNvl1QypUN1JXZSjUT27oG9jUTsNUzLHuJe8dW6p3z37WNpBCJY5BOjoDFG9ce5Z + rzucVs6QDnsuqD9NqtiECVFNg1qQjVvg9n5I0pl81c0mEfjWwqgOJ303W0IYKnis + MByXewyPN57cZuTJQFhUT3fvxF5W1MM03fqILKELL0WE9ALeTThHR9fJRrasQgrJ + YNnb20RwUZv5hqP21iwsaq3CV2+KODR4IlgglFXRN4gfIzZ9cfst95yy0nhVpcf6 + +IOycYZP7enTEU4e1jtfNn40yQPLlKei9/jrAgMBAAGjFjAUMBIGA1UdEwEB/wQI + MAYBAf8CAQUwDQYJKoZIhvcNAQELBQADggEBAEn0wkHsMN7vvDShFLKlpE+1twrI + qSekgqb5wdAId9sKblXQTojI6caiImCleFVzhKxQvuoS31dpg7hh2zw+I8P1U0zv + YrJlM8HVunHkWIdFuEuP7hrDnTA2NZbEN7EBSDksNtC+T+hcZcYcIs3hpV7pPdjh + jU9D4IcFd7ooVra7Lt2q3zl2XZ7TCzkIWV9jqCBNrlf7Q6QkLWe41k6kIJUTbl0H + Hqk9cRxr9hkwMKTjIO6G6gbPepqOuyEym8qjyVckRCQN8W+HUI3FV/XBcDk5FkhW + nqzJ6aTjBQD3WxOtnhm421dERi60RHdTInK6l6BKRUstmPyc3nfMouBarH+hADEA + -----END PKCS7----- + +.. _get_cas_caid_intermediates_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ + +POST /v1/cas +############ +A project admin can request to create a new subordinate CA for his project. + +.. _post_cas_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + POST /v1/cas + Headers: + X-Auth-Token: + Content-type: application/json + Accept: application/json + + {"name": "Subordinate CA", + "description": "Test Snake Oil Subordinate CA", + "parent_ca_ref": "http://localhost:9311/v1/cas/d9e853eb-aea4-4002-9be7-78665062f393", + "subject_dn": "CN=Subordinate CA, O=example.com"} + + Response: + + HTTP/1.1 201 OK + Content-Type: application/json + + {"ca_ref": "http://localhost:9311/v1/cas/a031dcf4-2e2a-4df1-8651-3b424eb6174e"} + + +.. _post_cas_request_attributes: + +Request Attributes +****************** + ++----------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++================+=========+==============================================================+ +| name | string | A name that can be used to reference this subCA | ++----------------+---------+--------------------------------------------------------------+ +| description | string | A description to be stored with this subCA . | ++----------------+---------+--------------------------------------------------------------+ +| parent_ca_ref | string | A URI referencing the parent CA to be used to issue the | +| | | subordinate CA's signing certificate | ++----------------+---------+--------------------------------------------------------------+ +| subject_dn | string | The subject distinguished name corresponding to this subCA | ++----------------+---------+--------------------------------------------------------------+ + +.. _post_cas_response_attributes: + +Response Attributes +******************* + ++----------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++================+=========+==============================================================+ +| ca_ref | string | A URL that references the created subCA | ++----------------+---------+--------------------------------------------------------------+ + +.. _post_cas_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 201 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad request. The content or format of the request is wrong. | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ +| 404 | The requested entity was not found | ++------+-----------------------------------------------------------------------------+ + +DELETE /v1/cas/{CA_ID} +###################### +A project administrator can delete a subCA that has been created for his project. Root +CAs that are defined in the barbican.conf configuration file can not be deleted. If +there is more than one project CA, the preferred CA can not be deleted until another +project CA has been selected as preferred. + +.. _delete_cas_caid_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + DELETE /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54 + Headers: + X-Auth-Token: + Accept: */* + + + Response: + + HTTP/1.1 204 OK + + +.. _delete_cas_caid_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 204 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action. | +| | This error can occur if a request is made to delete a root CA. | ++------+-----------------------------------------------------------------------------+ +| 404 | The requested entity was not found | ++------+-----------------------------------------------------------------------------+ +| 409 | The requested CA can not be delete because it is currently set as the | +| | project preferred CA. | ++------+-----------------------------------------------------------------------------+ + +GET /v1/cas/preferred +##################### +Any user can request a reference to the preferred CA assigned to his project. When +a preferred CA is set for a project, that is the CA that will be used when a user +of that project requests a certificate and does not specify a CA. For more +information, consult the +:doc:`Certificate Authorities User's Guide <../userguide/cas>` and the +:doc:`Certificates API User's Guide <../userguide/certificates>`. + +.. _get_cas_preferred_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas/preferred + Headers: + X-Auth-Token: + Accept: application/json + + + Response: + + HTTP/1.1 200 OK + Content-Type: application/json + + {"ca_ref": "http://localhost:9311/v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54"} + + +.. _get_cas_preferred_response_attributes: + +Response Attributes +******************* + ++----------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++================+=========+==============================================================+ +| ca_ref | string | A URL that references the preferred CA | ++----------------+---------+--------------------------------------------------------------+ + +.. _get_cas_preferred_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ +| 404 | Not found. No preferred CA has been defined. | ++------+-----------------------------------------------------------------------------+ + +POST /v1/cas/{CA_ID}/add-to-project +################################### +A project administrator can add a CA to his project list. The CA must be a +root CA or a subCA created by that project. When a project administrator +adds a CA to the project list, he limits the number of CA that project users +can use; they will only be able to use CAs that are project CAs or subCAs +of the project. The first created project CA becomes the project's preferred +CA by default. + +For more information, consult the +:doc:`Certificate Authorities User's Guide <../userguide/cas>` and the +:doc:`Certificates API User's Guide <../userguide/certificates>`. + +.. _post_cas_caid_add_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + POST /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/add-to-project + Headers: + X-Auth-Token: + Accept: */* + + + Response: + + HTTP/1.1 204 OK + + +.. _post_cas_caid_add_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 204 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ +| 404 | The requested entity was not found | ++------+-----------------------------------------------------------------------------+ + + +POST /v1/cas/{CA_ID}/remove-from-project +######################################## +A project administrator can remove a CA from his project list. If a project +CA requested for removal is also the preferred CA for the project, and there +are other project CAs, then this command will fail. The project administrator +must first set a new preferred CA before deleting this CA. + +.. _post_cas_caid_remove_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + POST /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/remove-from-project + Headers: + X-Auth-Token: + Accept: */* + + + Response: + + HTTP/1.1 204 OK + + +.. _post_cas_caid_remove_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 204 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action. | ++------+-----------------------------------------------------------------------------+ +| 404 | The requested entity was not found or not part of the project's CA | +| | list | ++------+-----------------------------------------------------------------------------+ +| 409 | Conflict. The remove action was blocked because the requested | +| | CA is set as the project preferred CA. The user must set another CA | +| | to be the preferred CA to remedy this error. | ++------+-----------------------------------------------------------------------------+ + +GET /v1/cas/{CA_ID}/projects +############################ +A service administrator can request a list of project who have the specified CA as +part of their project CA list. + +.. _get_cas_caid_projects_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/projects + Headers: + X-Auth-Token: + Accept: application/json + + + Response: + + HTTP/1.1 200 OK + Content-Type: application/json + + {"projects": ["4d2f8335-2af8-4a88-851f-2e745bd4860c"]} + + +.. _get_cas_caid_projects_response_attributes: + +Response Attributes +******************* + ++----------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++================+=========+==============================================================+ +| projects | list | A list of project IDs associated with the CA | ++----------------+---------+--------------------------------------------------------------+ + +.. _get_cas_caid_projects_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ + +POST /v1/cas/{CA_ID}/set-preferred +################################## +A project administrator can set a CA to be the preferred CA for his project. A +preferred CA must first be assigned as a project CA. There can only be one +preferred CA for a project. Setting a CA as preferred, also removes the +preferred setting from any other project CA. + +.. _post_cas_caid_set_pref_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + POST /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/set-preferred + Headers: + X-Auth-Token: + + Response: + + HTTP/1.1 204 OK + + +.. _post_cas_caid_set_pref_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 204 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad request. The requested CA is not valid to be a preferred CA for this | +| | project | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ +| 404 | The requested entity was not found | ++------+-----------------------------------------------------------------------------+ + +GET /v1/cas/global-preferred +############################ +A service administrator can can request a reference to the CA that has been assigned +to be the global preferred CA. + +.. _get_cas_global_preferred_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + GET /v1/cas/global-preferred + Headers: + X-Auth-Token: + Accept: application/json + + + Response: + + HTTP/1.1 200 OK + Content-Type: application/json + + {"ca_ref": "http://localhost:9311/v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54"} + + +.. _get_cas_global_preferred_response_attributes: + +Response Attributes +******************* + ++----------------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++================+=========+==============================================================+ +| ca_ref | string | A URL that references the global preferred CA | ++----------------+---------+--------------------------------------------------------------+ + +.. _get_cas_global_preferred_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ +| 404 | Not found. No global preferred CA has been defined. | ++------+-----------------------------------------------------------------------------+ + +POST /v1/cas/{CA_ID}/set-global-preferred +######################################### +A service administrator can set the global preferred CA value. When +a global preferred CA is set, that is the CA that will be used when a user +requests a certificate and does not specify a CA and his project does not +have a project preferred CA. + +For more information, consult the +:doc:`Certificate Authorities User's Guide <../userguide/cas>` and the +:doc:`Certificates API User's Guide <../userguide/certificates>`. + +.. _post_cas_caid_set_global_pref_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + POST /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/set-global-preferred + Headers: + X-Auth-Token: + Accept: */* + + + Response: + + HTTP/1.1 204 OK + + +.. _post_cas_caid_set_global_pref_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 204 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad request. The requested CA is not valid to be a global preferred CA | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ +| 404 | The requested entity was not found | ++------+-----------------------------------------------------------------------------+ + +POST /v1/cas/unset-global-preferred +################################### +A service administrator can remove the setting of global preferred CA. + +.. _post_cas_caid_unset_global_pref_request_response: + +Request/Response: +***************** + +.. code-block:: javascript + + Request: + + POST /v1/cas/9277c4b4-2c7a-4612-a693-1e738a83eb54/unset-global-preferred + Headers: + X-Auth-Token: + Accept: */* + + + Response: + + HTTP/1.1 204 OK + + +.. _post_cas_caid_unset_global_pref_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 204 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Authentication error. Missing or invalid X-Auth-Token. | ++------+-----------------------------------------------------------------------------+ +| 403 | The user was authenticated, but is not authorized to perform this action | ++------+-----------------------------------------------------------------------------+ +| 404 | The requested entity was not found | ++------+-----------------------------------------------------------------------------+ diff --git a/doc/source/api/reference/certificates.rst b/doc/source/api/reference/certificates.rst index a47dfe0fd..cd9862ed1 100644 --- a/doc/source/api/reference/certificates.rst +++ b/doc/source/api/reference/certificates.rst @@ -99,7 +99,7 @@ Request: ******** The request below shows a simple CMC request. For examples of each type, -see the :doc:`Certificate Quick Start Guide <../quickstart/certificates>`. +see the :doc:`Certificate User's Guide <../userguide/certificates>`. .. code-block:: javascript