Remove Certificate Orders and CAs from Documentation
Removes the documentation and links to domcumentation for Certificate Orders and CAs. Change-Id: I4cd3c21ac4f82eeb76d700426374cec898be4125
This commit is contained in:
parent
23d064f134
commit
3f6c24a4ef
@ -1,207 +0,0 @@
|
|||||||
*****************************************
|
|
||||||
Certificate Authorities API - User Guide
|
|
||||||
*****************************************
|
|
||||||
|
|
||||||
Barbican is used as an interface to interact with Certificate Authorities (both
|
|
||||||
public and private) to issue, renew and revoke certificates. In PKI parlance,
|
|
||||||
barbican acts as a Registration Authority for these CAs.
|
|
||||||
|
|
||||||
This interaction is done through certificate plugins, which in turn, can talk
|
|
||||||
to one or more CAs. Details about the CA each plugin communicates with are
|
|
||||||
updated by the plugins. This includes details like the CA name, description,
|
|
||||||
signing cert and PKCS#7 certificate chain.
|
|
||||||
|
|
||||||
Some certificate plugins also provide the ability to create subordinate CAs.
|
|
||||||
These are CAs which are generated on request by a client, which have signing
|
|
||||||
certificates which have been signed by another CA maintained by that plugin
|
|
||||||
(the parent CA). More details will be provided below.
|
|
||||||
|
|
||||||
The CAs made available to barbican by the plugins are exposed to the client
|
|
||||||
through the /cas REST API, which is detailed in the
|
|
||||||
`Certificate Authorities API reference <http://docs.openstack.org/developer/barbican/api/reference/cas.html>`__.
|
|
||||||
|
|
||||||
This guide will provide some examples on how to use each of the supported
|
|
||||||
operations. It assumes that you will be using a local running development
|
|
||||||
environment of barbican. If you need assistance with getting set up, please
|
|
||||||
reference the
|
|
||||||
`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
|
|
||||||
|
|
||||||
.. _listing_the_cas:
|
|
||||||
|
|
||||||
Listing CAs
|
|
||||||
###########
|
|
||||||
|
|
||||||
To see the list of CAs that are currently configured, you can query the cas
|
|
||||||
resource:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas
|
|
||||||
|
|
||||||
This should provide a response like the following:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
{"cas": ["http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581"], "total": 1}
|
|
||||||
|
|
||||||
.. _getting_ca_details:
|
|
||||||
|
|
||||||
Getting Details about a CA
|
|
||||||
##########################
|
|
||||||
|
|
||||||
More details on each CA can be obtained by querying the specific CA:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581
|
|
||||||
|
|
||||||
The output shows the status of the CA and the plugin used to communicate with it:
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
|
||||||
"status": "ACTIVE",
|
|
||||||
"updated": "2015-05-09T05:55:37.745132",
|
|
||||||
"created": "2015-05-09T05:55:37.745132",
|
|
||||||
"plugin_name": "barbican.plugin.dogtag.DogtagCAPlugin",
|
|
||||||
"meta": [
|
|
||||||
{"name": "Dogtag CA"},
|
|
||||||
{"description": "Certificate Authority - Dogtag CA"}
|
|
||||||
],
|
|
||||||
"ca_id": "3a2a533d-ed4d-4c68-a418-2ee79f4c9581",
|
|
||||||
"plugin_ca_id": "Dogtag CA",
|
|
||||||
"expiration": "2015-05-10T05:55:37.740211"
|
|
||||||
}
|
|
||||||
|
|
||||||
To get the signing certificate of the CA in PEM format (for importing into a
|
|
||||||
client), use the cacert sub-resource:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581/cacert
|
|
||||||
|
|
||||||
To get the PKCS#7 certificate chain (which contains the signing certificate and
|
|
||||||
all intermediate certificates), use the intermediates sub-resource.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581/intermediates
|
|
||||||
|
|
||||||
.. _managing_project_cas:
|
|
||||||
|
|
||||||
Managing Project CAs
|
|
||||||
####################
|
|
||||||
|
|
||||||
It is possible to specify a set of CAs to be used for a particular project.
|
|
||||||
A project administrator can add or remove CAs from this list. If this list
|
|
||||||
exists for a given project, then certificate orders will be routed only to those
|
|
||||||
CAs. Any requests to other CAs (as specified by the ca_id in the order
|
|
||||||
metadata) will be rejected.
|
|
||||||
|
|
||||||
To add a CA to a particular project, a project administrator would do:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581/add-to-project
|
|
||||||
|
|
||||||
To remove the CA from the set of project CAs, a project administrator would do:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581/remove-from-project
|
|
||||||
|
|
||||||
The first CA added to the project will be designated as the preferred CA. This
|
|
||||||
is the CA to which requests that do not explicitly specify the ca_id will be
|
|
||||||
routed. It is possible for project administrators to specify another project
|
|
||||||
CA as the preferred CA as follows:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581/set-preferred
|
|
||||||
|
|
||||||
As a global administrator, it is possible to determine which projects a CA
|
|
||||||
belongs (ie. has been designated as a project CA) by querying the projects
|
|
||||||
sub-resource:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X GET -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581/projects
|
|
||||||
|
|
||||||
.. _setting_a_global_preferred_ca:
|
|
||||||
|
|
||||||
Setting a Global Preferred CA
|
|
||||||
#############################
|
|
||||||
|
|
||||||
It is possible for an administrator to set a global preferred CA. This is the
|
|
||||||
CA to which certificate orders are routed if project CAs are not defined (see
|
|
||||||
previous section) and no ca_id is defined in the order. If no global preferred
|
|
||||||
CA is defined, requests will be routed to the first configured certificate
|
|
||||||
plugin.
|
|
||||||
|
|
||||||
To set a global preferred CA plugin, do:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581/set-global-preferred
|
|
||||||
|
|
||||||
.. _creating_a_subca:
|
|
||||||
|
|
||||||
Creating a subordinate CA
|
|
||||||
#########################
|
|
||||||
|
|
||||||
As mentioned above, some certificate plugins (Dogtag and snake oil in
|
|
||||||
particular) allow projects to create new subordinate CAs on-the-fly.
|
|
||||||
These are CAs which have been signed by another CA (the "parent CA") exposed
|
|
||||||
by the same certificate plugin.
|
|
||||||
|
|
||||||
To determine if a particular CA can be used as a parent CA, get details about
|
|
||||||
the CA as exemplified in the :ref:`Getting Details<getting_ca_details>` section
|
|
||||||
above. The attribute "can_create_subordinates" will be set to True if this CA
|
|
||||||
can be used as a subordinate CA.
|
|
||||||
|
|
||||||
A subordinate CA can then be created as follows:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" -d '{
|
|
||||||
"parent_ca_ref": "http://localhost:9311/cas/422e6ad3-24ae-45e3-b165-4e9487cd0ded",
|
|
||||||
"subject_dn": "cn=Subordinate CA Signing Certificate, o=example.com",
|
|
||||||
'name': "Subordinate CA"
|
|
||||||
}' http://localhost:9311/v1/cas
|
|
||||||
|
|
||||||
The result of this JSON request will be a Certificate Authority reference,
|
|
||||||
which can be queried as above.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
{"order_ref": "http://localhost:9311/v1/cas/df1d1a0f-8454-46ca-9287-c57ced0418e7"}
|
|
||||||
|
|
||||||
.. _access_restrictions_on_sub_cas:
|
|
||||||
|
|
||||||
Access Restrictions on Subordinate CAs
|
|
||||||
######################################
|
|
||||||
|
|
||||||
Subordinate CAs are restricted to the project of the creator. That is, the
|
|
||||||
creator's project_id is stored with the subordinate CA, and only members of the
|
|
||||||
creator's project are able to list, get details for or submit certificate
|
|
||||||
orders to a given subordinate CA.
|
|
||||||
|
|
||||||
Subordinate CAs can be distinguished from regular CAs by the presence of the
|
|
||||||
project_id and user_id in the CA details.
|
|
||||||
|
|
||||||
Subordinate CAs may be deleted by the user or a project administrator as
|
|
||||||
follows:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X DEL -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581
|
|
@ -1,336 +0,0 @@
|
|||||||
******************************
|
|
||||||
Certificates API - User Guide
|
|
||||||
******************************
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
DEPRECATION WARNING: The Certificates API has been deprecated and will
|
|
||||||
be removed in the P release.
|
|
||||||
|
|
||||||
Barbican will be used to manage the lifecycle of x509 certificates covering
|
|
||||||
operations such as initial certificate issuance, certificate re-issuance,
|
|
||||||
certificate renewal and certificate revocation. At present, only the issuance of
|
|
||||||
certificates is implemented.
|
|
||||||
|
|
||||||
This guide will provide some examples on how to use each of the supported operations.
|
|
||||||
It assumes that you will be using a local running development environment of barbican.
|
|
||||||
If you need assistance with getting set up, please reference the
|
|
||||||
`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
|
|
||||||
|
|
||||||
Barbican can be used to request certificate issuance from a number of private and
|
|
||||||
public Certificate Authorities (CAs). This is done through the Orders interface.
|
|
||||||
|
|
||||||
There are several types of certificate orders available:
|
|
||||||
* :ref:`Simple CMC<simple_cmc_order>`
|
|
||||||
* :ref:`Full CMC<full_cmc_order>`
|
|
||||||
* :ref:`Stored Key<stored_key_order>`
|
|
||||||
* :ref:`Custom<custom_certificate_order>`
|
|
||||||
|
|
||||||
An example of each kind of certificate request will be provided below.
|
|
||||||
|
|
||||||
When the certificate order is received, a certificate order is generated and the client
|
|
||||||
will be provided an order reference. This order will be in PENDING state. Once the
|
|
||||||
certificate order has been fulfilled and the certificate is issued, the
|
|
||||||
order state will be updated to ACTIVE, and the order will be updated to include
|
|
||||||
a reference to a Certificate Container.
|
|
||||||
|
|
||||||
.. _what_is_a_cert_container:
|
|
||||||
|
|
||||||
What is a Certificate Container?
|
|
||||||
################################
|
|
||||||
|
|
||||||
A completed certificate order contains a reference to certificate container
|
|
||||||
as shown below:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/orders/df1d1a0f-8454-46ca-9287-c57ced0418e7
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
|
||||||
"status": "ACTIVE",
|
|
||||||
"sub_status": "cert_generated",
|
|
||||||
"updated": "2015-05-09T22:40:05.007512",
|
|
||||||
"created": "2015-05-09T22:40:01.556689",
|
|
||||||
"container_ref": "http://localhost:9311/v1/containers/1e71dc2b-cf63-4aa4-91f7-41ea1a9e5493",
|
|
||||||
"order_ref": "http://localhost:9311/v1/orders/df1d1a0f-8454-46ca-9287-c57ced0418e7",
|
|
||||||
"meta": {
|
|
||||||
"profile": "caServerCert",
|
|
||||||
"request_data": "LS0tLS1CRUdJ...VC0tLS0tCg==",
|
|
||||||
"request_type": "simple-cmc",
|
|
||||||
"ca_id": "422e6ad3-24ae-45e3-b165-4e9487cd0ded"
|
|
||||||
},
|
|
||||||
"sub_status_message": "Certificate has been generated",
|
|
||||||
"type": "certificate"
|
|
||||||
}
|
|
||||||
|
|
||||||
Getting the container provides references to secrets for the certificate,
|
|
||||||
any intermediate certificate chain in PKCS7 format, and potentially references
|
|
||||||
to the private and any passphrase used to encrypt the private key (if it is stored in
|
|
||||||
barbican).
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/containers/1e71dc2b-cf63-4aa4-91f7-41ea1a9e5493
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
|
||||||
"status": "ACTIVE",
|
|
||||||
"updated": "2015-05-09T22:40:05.003296",
|
|
||||||
"name": null,
|
|
||||||
"consumers": [],
|
|
||||||
"created": "2015-05-09T22:40:05.003296",
|
|
||||||
"container_ref": "http://localhost:9311/v1/containers/1e71dc2b-cf63-4aa4-91f7-41ea1a9e5493",
|
|
||||||
"creator_id": null,
|
|
||||||
"secret_refs": [
|
|
||||||
{
|
|
||||||
"secret_ref": "http://localhost:9311/v1/secrets/acd47891-9e72-4542-b9de-be66cc343610",
|
|
||||||
"name": "certificate"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"secret_ref": "http://localhost:9311/v1/secrets/a871baa4-6ef2-42db-ba01-13414ab60d9e",
|
|
||||||
"name": "intermediates"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"type": "certificate"
|
|
||||||
}
|
|
||||||
|
|
||||||
You can get the certificate itself by extracting the payload of the secret_ref pointed to by the label "certificate".
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
-H "Accept:application/pkix-cert" \
|
|
||||||
http://localhost:9311/v1/secrets/acd47891-9e72-4542-b9de-be66cc343610/payload
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
-----BEGIN CERTIFICATE-----
|
|
||||||
MIIDcTCCAlmgAwIBAgIBWDANBgkqhkiG9w0BAQsFADA/MRwwGgYDVQQKDBNwa2kt
|
|
||||||
dG9tY2F0MjYgZG9tYWluMR8wHQYDVQQDDBZDQSBTaWduaW5nIENlcnRpZmljYXRl
|
|
||||||
MB4XDTE1MDUwOTIyNDAwMVoXDTE3MDQyODIyNDAwMVowIDEeMBwGA1UEAwwVc2Vy
|
|
||||||
....
|
|
||||||
HIG28XVygTC93uQmk1mAUTsIpFsk
|
|
||||||
-----END CERTIFICATE-----
|
|
||||||
|
|
||||||
.. _finding_the_cas:
|
|
||||||
|
|
||||||
What CAs are Available?
|
|
||||||
#######################
|
|
||||||
|
|
||||||
Barbican communicates with public and private CAs through CA plugins that are
|
|
||||||
configured to communicate with one or more CAs. CA plugins are configured and
|
|
||||||
enabled in **barbican.conf**.
|
|
||||||
|
|
||||||
To see the list of CA's that are currently configured, you can query the cas
|
|
||||||
resource:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas
|
|
||||||
|
|
||||||
This should provide a response like the following:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
{"cas": ["http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581"], "total": 1}
|
|
||||||
|
|
||||||
More details on each CA can be obtained by querying the specific CA:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/cas/3a2a533d-ed4d-4c68-a418-2ee79f4c9581
|
|
||||||
|
|
||||||
The output shows the status of the CA and the plugin used to communicate with it:
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
|
||||||
"status": "ACTIVE",
|
|
||||||
"updated": "2015-05-09T05:55:37.745132",
|
|
||||||
"created": "2015-05-09T05:55:37.745132",
|
|
||||||
"plugin_name": "barbican.plugin.dogtag.DogtagCAPlugin",
|
|
||||||
"meta": [
|
|
||||||
{"name": "Dogtag CA"},
|
|
||||||
{"description": "Certificate Authority - Dogtag CA"}
|
|
||||||
],
|
|
||||||
"ca_id": "3a2a533d-ed4d-4c68-a418-2ee79f4c9581",
|
|
||||||
"plugin_ca_id": "Dogtag CA",
|
|
||||||
"expiration": "2015-05-10T05:55:37.740211"
|
|
||||||
}
|
|
||||||
|
|
||||||
A snake-oil CA plugin is included with the barbican source code for basic testing.
|
|
||||||
In addition, a robust, enterprise-ready CA plugin is provided for the Dogtag CA.
|
|
||||||
Instructions for setting up the CA are provided at :doc:`Dogtag Setup Instructions <./dogtag_setup>`.
|
|
||||||
|
|
||||||
More details can be found in the
|
|
||||||
`certificate reference <http://docs.openstack.org/developer/barbican/api/reference/certificates.html>`__.
|
|
||||||
|
|
||||||
.. _order_certificate:
|
|
||||||
|
|
||||||
How to Order a Certificate
|
|
||||||
##########################
|
|
||||||
|
|
||||||
As mentioned above, several types of certificate orders are available. This
|
|
||||||
section details each one.
|
|
||||||
|
|
||||||
.. _simple_cmc_order:
|
|
||||||
|
|
||||||
Simple CMC Certificate Order
|
|
||||||
****************************
|
|
||||||
|
|
||||||
The easiest way to obtain a certificate is to provide a simple CMC request to the
|
|
||||||
server using a Simple CMC Order type. In the example below, we will use openssl
|
|
||||||
commands to generate an RSA key pair and use that key pair to create a CSR.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
openssl genrsa -out private.pem 2048
|
|
||||||
|
|
||||||
openssl req -new -key private.pem -out csr.pem -subj '/CN=server1,o=example.com'
|
|
||||||
|
|
||||||
base64 ./csr.pem |tr -d '\r\n'
|
|
||||||
|
|
||||||
The output of the last command will be a base64 encoded string that can be pasted
|
|
||||||
into a JSON request for a Simple CMC Certificate order.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" -d '{
|
|
||||||
"type": "certificate",
|
|
||||||
"meta": {
|
|
||||||
"request_data": "LS0tLS1CRUdJT..... oK2Fkh6dXBTVC0tLS0tCg==",
|
|
||||||
"request_type": "simple-cmc",
|
|
||||||
"ca_id": "422e6ad3-24ae-45e3-b165-4e9487cd0ded",
|
|
||||||
"profile": "caServerCert"
|
|
||||||
}
|
|
||||||
}' http://localhost:9311/v1/orders
|
|
||||||
|
|
||||||
The ca_id and profile parameters are not required. The profile represents a specific
|
|
||||||
kind of certificate product (a three year server cert, for instance) as defined by the
|
|
||||||
CA and CA plugin. For a Dogtag CA, "caServerCert" is usually a profile that corresponds
|
|
||||||
to a server cert and which is automatically approved and issued. More details can be
|
|
||||||
found in :doc:`Dogtag Setup Instructions <./dogtag_setup>`.
|
|
||||||
|
|
||||||
The result of this JSON request will be an order reference, which, when fulfilled
|
|
||||||
will contain a reference to a certificate container. The certificate can be extracted
|
|
||||||
as shown above.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
{"order_ref": "http://localhost:9311/v1/orders/df1d1a0f-8454-46ca-9287-c57ced0418e7"}
|
|
||||||
|
|
||||||
.. _full_cmc_order:
|
|
||||||
|
|
||||||
Full CMC Certificate Order
|
|
||||||
**************************
|
|
||||||
|
|
||||||
This type has not yet been implemented.
|
|
||||||
|
|
||||||
.. _stored_key_order:
|
|
||||||
|
|
||||||
Stored Key Certificate Order
|
|
||||||
****************************
|
|
||||||
|
|
||||||
Stored Key certificate orders take advantage of the fact that barbican is also
|
|
||||||
a repository for secrets. RSA private keys can be either generated on the client
|
|
||||||
and stored in barbican beforehand using the secrets interface, or generated in
|
|
||||||
barbican directly using the orders interface.
|
|
||||||
|
|
||||||
All that is required for the certificate order is the reference to the secret container
|
|
||||||
for the RSA key pair and any parameters needed to generate a CSR. Barbican will
|
|
||||||
retrieve the RSA key pair (assuming the user has permission to access it) and will generate
|
|
||||||
the CSR on the user's behalf. The CSR will then be submitted to a back-end CA. This
|
|
||||||
may be particularly useful for provisioning flows.
|
|
||||||
|
|
||||||
In the example below, we will generate a RSA key pair using the Orders interface, and
|
|
||||||
use this generated secret to create a Stored Key Order.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" -d '{
|
|
||||||
"type": "asymmetric",
|
|
||||||
"meta": {
|
|
||||||
"algorithm": "rsa",
|
|
||||||
"bit_length": 2048
|
|
||||||
}
|
|
||||||
}' http://localhost:9311/v1/orders
|
|
||||||
|
|
||||||
This should provide a response as follows:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
{"order_ref": "http://localhost:9311/v1/orders/cb3c43d6-e30c-40c0-b28c-b0dd58a6209d"}
|
|
||||||
|
|
||||||
We can retrieve the reference to the container containing the RSA key pair from the order.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
|
|
||||||
http://localhost:9311/v1/orders/cb3c43d6-e30c-40c0-b28c-b0dd58a6209d
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
|
||||||
"status": "ACTIVE",
|
|
||||||
"updated": "2015-05-09T22:40:05.007512",
|
|
||||||
"created": "2015-05-09T22:40:01.556689",
|
|
||||||
"container_ref": "http://localhost:9311/v1/containers/1e71dc2b-cf63-4aa4-91f7-41ea1a9e5493",
|
|
||||||
"order_ref": "http://localhost:9311/v1/orders/cb3c43d6-e30c-40c0-b28c-b0dd58a6209d",
|
|
||||||
"meta": {
|
|
||||||
"algorithm": "rsa",
|
|
||||||
"bit_length": 2048
|
|
||||||
},
|
|
||||||
"type": "asymmetric"
|
|
||||||
}
|
|
||||||
|
|
||||||
Now that we have a reference to the container, we can create a stored-key request.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" -d '{
|
|
||||||
"type": "certificate",
|
|
||||||
"meta": {
|
|
||||||
"container_ref": "http://localhost:9311/v1/containers/1e71dc2b-cf63-4aa4-91f7-41ea1a9e5493",
|
|
||||||
"subject_dn": "cn=server1, o=example.com",
|
|
||||||
"request_type": "stored-key",
|
|
||||||
"ca_id": "422e6ad3-24ae-45e3-b165-4e9487cd0ded",
|
|
||||||
"profile": "caServerCert"
|
|
||||||
}
|
|
||||||
}' http://localhost:9311/v1/orders
|
|
||||||
|
|
||||||
As noted in the previous section, ca_id and profile are optional. The response will be a reference to the
|
|
||||||
created order.
|
|
||||||
|
|
||||||
|
|
||||||
.. _custom_certificate_order:
|
|
||||||
|
|
||||||
Custom Certificate Order
|
|
||||||
########################
|
|
||||||
|
|
||||||
A custom certificate order (which is also the order type assumed when no certificate
|
|
||||||
order type is provided) is an order in which any request attributes are submitted to
|
|
||||||
the back-end CA unchanged. This is useful if you wish to communicate with a specific CA
|
|
||||||
and wish to provide parameters that are specific to that CA. Because this request
|
|
||||||
contains parameters that are CA specific, the ca_id is required.
|
|
||||||
|
|
||||||
The example below is a custom request for a server cert from a Dogtag CA. As usual,
|
|
||||||
the response is an order reference.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" -d '{
|
|
||||||
"type": "certificate",
|
|
||||||
"meta": {
|
|
||||||
"request_data": "LS0tLS1CRUdJT..... oK2Fkh6dXBTVC0tLS0tCg==",
|
|
||||||
"request_type": "custom",
|
|
||||||
"ca_id": "422e6ad3-24ae-45e3-b165-4e9487cd0ded",
|
|
||||||
"profile": "caServerCert"
|
|
||||||
}
|
|
||||||
}' http://localhost:9311/v1/orders
|
|
@ -197,14 +197,4 @@ server certificate for the CA.
|
|||||||
Testing the Setup
|
Testing the Setup
|
||||||
*****************
|
*****************
|
||||||
|
|
||||||
Once all the above is set up, you can test the CA and KRA plugins by making a
|
TODO
|
||||||
request for a certificate using a pre-approved profile. As the issued certs are
|
|
||||||
stored in the secret_store, this indirectly tests the KRA plugin as well.
|
|
||||||
|
|
||||||
First, follow the instructions in :ref:`finding_the_cas` to find the ca_id of
|
|
||||||
the Dogtag CA.
|
|
||||||
|
|
||||||
Second, submit a simple CMC request as detailed in :ref:`simple_cmc_order`.
|
|
||||||
|
|
||||||
The request should be automatically approved, and you should be able to extract
|
|
||||||
the certificate from the certificate container in the order.
|
|
||||||
|
@ -10,8 +10,6 @@ Contents
|
|||||||
containers
|
containers
|
||||||
acls
|
acls
|
||||||
pkcs11keygeneration
|
pkcs11keygeneration
|
||||||
certificates
|
|
||||||
cas
|
|
||||||
dogtag_setup
|
dogtag_setup
|
||||||
quotas
|
quotas
|
||||||
consumers
|
consumers
|
||||||
|
@ -3,27 +3,17 @@ Orders API - User Guide
|
|||||||
***********************
|
***********************
|
||||||
|
|
||||||
The orders resource allows the user to request barbican to generate a secret.
|
The orders resource allows the user to request barbican to generate a secret.
|
||||||
This is also very helpful for requesting the creation of certificates and
|
This is also very helpful for requesting the creation of public/private key pairs.
|
||||||
public/private key pairs.
|
|
||||||
|
|
||||||
The orders resource supports the following types:
|
The orders resource supports the following types:
|
||||||
* symmetric keys
|
* symmetric keys
|
||||||
* asymmetric keys
|
* asymmetric keys
|
||||||
* certificates
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
DEPRECATION WARNING: The Certificates Order resource has been deprecated
|
|
||||||
and will be removed in the P release.
|
|
||||||
|
|
||||||
This user guide provides high level examples of the orders resource.
|
This user guide provides high level examples of the orders resource.
|
||||||
It will assume you will be using a local running development environment of barbican.
|
It will assume you will be using a local running development environment of barbican.
|
||||||
If you need assistance with getting set up, please reference the
|
If you need assistance with getting set up, please reference the
|
||||||
`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
|
`development guide <http://docs.openstack.org/developer/barbican/setup/dev.html>`__.
|
||||||
|
|
||||||
For a more in depth explanation on how to order a certificate, reference
|
|
||||||
the :ref:`How to Order a Certificate <order_certificate>` documentation.
|
|
||||||
|
|
||||||
.. _create_order:
|
.. _create_order:
|
||||||
|
|
||||||
Creating an Order
|
Creating an Order
|
||||||
|
@ -20,8 +20,6 @@ API Reference
|
|||||||
./reference/store_backends.rst
|
./reference/store_backends.rst
|
||||||
./reference/containers
|
./reference/containers
|
||||||
./reference/acls
|
./reference/acls
|
||||||
./reference/certificates
|
|
||||||
./reference/cas
|
|
||||||
./reference/quotas
|
./reference/quotas
|
||||||
./reference/consumers
|
./reference/consumers
|
||||||
./reference/orders
|
./reference/orders
|
||||||
|
@ -1,978 +0,0 @@
|
|||||||
****************************************
|
|
||||||
Certificates Authorities API - Reference
|
|
||||||
****************************************
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
DEPRECATION WARNING: The Certificates Authorities API has been deprecated
|
|
||||||
and will be removed in the P release.
|
|
||||||
|
|
||||||
Barbican provides an API to interact with certificate authorities (CAs). For
|
|
||||||
an introduction to CAs and how Barbican manages them, see the
|
|
||||||
`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__.
|
|
||||||
|
|
||||||
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:<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 HATEOAS 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 HATEOAS 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:<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 HATEOAS 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 HATEOAS 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:<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:<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:<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:<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:<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
|
|
||||||
`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__
|
|
||||||
and the
|
|
||||||
`Certificates API User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`__.
|
|
||||||
|
|
||||||
.. _get_cas_preferred_request_response:
|
|
||||||
|
|
||||||
Request/Response:
|
|
||||||
*****************
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
Request:
|
|
||||||
|
|
||||||
GET /v1/cas/preferred
|
|
||||||
Headers:
|
|
||||||
X-Auth-Token:<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
|
|
||||||
`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__
|
|
||||||
and the
|
|
||||||
`Certificates API User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`__.
|
|
||||||
|
|
||||||
.. _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:<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:<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:<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:<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 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:<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
|
|
||||||
`Certificate Authorities User's Guide <http://developer.openstack.org/api-guide/key-manager/cas.html>`__
|
|
||||||
and the
|
|
||||||
`Certificates API User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`__.
|
|
||||||
|
|
||||||
.. _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:<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:<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 |
|
|
||||||
+------+-----------------------------------------------------------------------------+
|
|
@ -1,156 +0,0 @@
|
|||||||
****************************
|
|
||||||
Certificates API - Reference
|
|
||||||
****************************
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
DEPRECATION WARNING: The Certificates API has been deprecated and will
|
|
||||||
be removed in the P release.
|
|
||||||
|
|
||||||
.. _reference_post_certificate_orders:
|
|
||||||
|
|
||||||
POST /v1/orders
|
|
||||||
###############
|
|
||||||
Certificates are requested using the Orders interface. Detailed description of this interface
|
|
||||||
is deferred to the Orders API reference. This reference identifies the parameters that are specific
|
|
||||||
to each of the certificate order types i.e. those orders for which the parameter *type*
|
|
||||||
is "certificate".
|
|
||||||
|
|
||||||
All orders contain a required parameter *meta*, which is a dictionary containing key-value
|
|
||||||
parameters which specify the details of an order request. All the parameters below are passed
|
|
||||||
in the *meta* dictionary.
|
|
||||||
|
|
||||||
The result of this operation is an order for a certificate, returned to the client as an order
|
|
||||||
reference. Upon completion, the order will contain a reference to a Certificate Container,
|
|
||||||
see `Certificate Containers <http://developer.openstack.org/api-guide/key-manager/containers.html#certificate-containers>`__.
|
|
||||||
|
|
||||||
|
|
||||||
Common Attributes
|
|
||||||
*****************
|
|
||||||
|
|
||||||
Certificate orders have the same attributes that are common to all orders. The table below lists
|
|
||||||
those parameters that are specific to certificate orders in particular.
|
|
||||||
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| Attribute Name | Type | Description | Default |
|
|
||||||
+============================+=========+==============================================+============+
|
|
||||||
| request_type | string | (optional) The type of certificate order | custom |
|
|
||||||
| | | Possible values are stored-key, simple-cmc, | |
|
|
||||||
| | | full-cmc and custom | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| ca_id | string | (optional) The UUID of the CA to which this | None |
|
|
||||||
| | | certificate order should be sent. This | |
|
|
||||||
| | | UUID can be obtained from the cas interface. | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| profile | string | (optional) Identifier indicating the | None |
|
|
||||||
| | | certificate product being requested. | |
|
|
||||||
| | | eg. a 3 year server certificate with certain | |
|
|
||||||
| | | extensions. This identifier is CA specific. | |
|
|
||||||
| | | Therefore, ca_id is required if the profile | |
|
|
||||||
| | | is provided. | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| requestor_name | string | (optional) Requestor name | None |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| requestor_email | string | (optional) Requestor email | None |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| requestor_phone | string | (optional) Requestor phone | None |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
|
|
||||||
Attributes for Simple CMC Orders
|
|
||||||
********************************
|
|
||||||
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| Attribute Name | Type | Description | Default |
|
|
||||||
+============================+=========+==============================================+============+
|
|
||||||
| request_data | string | The base64 encoded simple CMC request with | None |
|
|
||||||
| | | no line breaks. Simple CMC is the same as | |
|
|
||||||
| | | a PKCS10 CSR. (RFC 5272) | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
|
|
||||||
Attributes for Stored Key Requests
|
|
||||||
**********************************
|
|
||||||
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| Attribute Name | Type | Description | Default |
|
|
||||||
+============================+=========+==============================================+============+
|
|
||||||
| source_container_ref | string | Reference to the RSA container already | None |
|
|
||||||
| | | stored in Barbican containing the private | |
|
|
||||||
| | | and public keys. | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| subject_dn | string | Subject DN for the certificate. This | None |
|
|
||||||
| | | value must comply with RFC 1485. | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| extensions | string | (optional) Base 64 DER encoded ASN.1 values | None |
|
|
||||||
| | | for requested certificate extensions, | |
|
|
||||||
| | | Currently, this value is not parsed. | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
|
|
||||||
Attributes for Custom Orders
|
|
||||||
****************************
|
|
||||||
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
| Attribute Name | Type | Description | Default |
|
|
||||||
+============================+=========+==============================================+============+
|
|
||||||
| (Varies - depends on CA) | (Varies)| Custom certificate orders pass arbitrary | None |
|
|
||||||
| | | parameters through the CA unchanged. It is | |
|
|
||||||
| | | up to the CA to interpret the parameters. | |
|
|
||||||
| | | Note that as the request parameters are CA | |
|
|
||||||
| | | specific, *ca_id* is required for this | |
|
|
||||||
| | | request type. | |
|
|
||||||
+----------------------------+---------+----------------------------------------------+------------+
|
|
||||||
|
|
||||||
|
|
||||||
Request:
|
|
||||||
********
|
|
||||||
|
|
||||||
The request below shows a simple CMC request. For examples of each type,
|
|
||||||
see the `Certificate User's Guide <http://developer.openstack.org/api-guide/key-manager/certificates.html>`.
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
POST /v1/orders
|
|
||||||
Headers:
|
|
||||||
Content-Type: application/json
|
|
||||||
X-Auth-Token: <token>
|
|
||||||
|
|
||||||
Content:
|
|
||||||
{
|
|
||||||
"type": "certificate",
|
|
||||||
"meta": {
|
|
||||||
"request_data": "... base 64 encoded simple CMC ...",
|
|
||||||
"request_type": "simple-cmc",
|
|
||||||
"ca_id": "422e6ad3-24ae-45e3-b165-4e9487cd0ded",
|
|
||||||
"profile": "caServerCert"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
Response:
|
|
||||||
*********
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
201 Created
|
|
||||||
|
|
||||||
{
|
|
||||||
"order_ref": "https://{barbican_host}/v1/orders/{order_uuid}"
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
HTTP Status Codes
|
|
||||||
*****************
|
|
||||||
|
|
||||||
+------+-----------------------------------------------------------------------------+
|
|
||||||
| Code | Description |
|
|
||||||
+======+=============================================================================+
|
|
||||||
| 201 | Successfully created an Order |
|
|
||||||
+------+-----------------------------------------------------------------------------+
|
|
||||||
| 400 | Bad Request |
|
|
||||||
+------+-----------------------------------------------------------------------------+
|
|
||||||
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
|
||||||
+------+-----------------------------------------------------------------------------+
|
|
||||||
| 403 | Forbidden. The user has been authenticated, but is not authorized to |
|
|
||||||
| | create an order. This can be based on the user's role or the project's |
|
|
||||||
| | quota. |
|
|
||||||
+------+-----------------------------------------------------------------------------+
|
|
||||||
| 415 | Unsupported media type |
|
|
||||||
+------+-----------------------------------------------------------------------------+
|
|
@ -1,214 +0,0 @@
|
|||||||
.. module:: barbican.plugin.interface.certificate_manager
|
|
||||||
|
|
||||||
==============================
|
|
||||||
Certificate Plugin Development
|
|
||||||
==============================
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
DEPRECATION WARNING: The Certificates Plugin has been deprecated and will
|
|
||||||
be removed in the P release.
|
|
||||||
|
|
||||||
This guide describes how to develop a custom certificate plugin for use by
|
|
||||||
Barbican.
|
|
||||||
|
|
||||||
Barbican core orchestrates generating SSL certificates, delegating to
|
|
||||||
certificate plugins any required actions. Certificate actions include
|
|
||||||
initiating a certificate order, checking for order updates, and retrieving
|
|
||||||
generated certificates. Barbican plans to include the following certificate
|
|
||||||
plugins:
|
|
||||||
|
|
||||||
1. A Red Hat Dogtag certificate authority (CA) plugin capable of generating
|
|
||||||
certificates once the order is initiated.
|
|
||||||
|
|
||||||
2. A Symantec plugin able to interact with the Symantec CA service, requiring
|
|
||||||
periodic status updates to see if certificates are ready.
|
|
||||||
|
|
||||||
3. A DigiCert plugin able to interact with the DigiCert CA service, with a
|
|
||||||
similar interactions as with Symantec.
|
|
||||||
|
|
||||||
|
|
||||||
``certificate_manager`` Module
|
|
||||||
==============================
|
|
||||||
|
|
||||||
The ``barbican.plugin.interface.certificate_manager`` module contains the
|
|
||||||
classes needed to implement a custom plugin. These classes include the
|
|
||||||
``CertificatePluginBase`` abstract base class which custom plugins should
|
|
||||||
inherit from, as well as any Data Transfer Object (DTO) classes used to pass
|
|
||||||
information into and from plugin methods.
|
|
||||||
|
|
||||||
|
|
||||||
Data Transfer Objects
|
|
||||||
=====================
|
|
||||||
|
|
||||||
The DTO classes are used to wrap data that is passed from Barbican to the
|
|
||||||
plugin as well as data that is returned from the plugin back to Barbican.
|
|
||||||
They provide a level of isolation between the plugins and Barbican's internal
|
|
||||||
data models.
|
|
||||||
|
|
||||||
.. autoclass:: ResultDTO
|
|
||||||
|
|
||||||
|
|
||||||
.. _plugin-certificate-status-label:
|
|
||||||
|
|
||||||
Certificate Status Class
|
|
||||||
========================
|
|
||||||
|
|
||||||
When certificate plugin methods are invoked, they return a ``ResultDTO`` that
|
|
||||||
includes one of the status response constants defined by the
|
|
||||||
``CertificateStatus`` class. As detailed in the
|
|
||||||
:ref:`plugin-certificate-sequence-label` section below Barbican core directs
|
|
||||||
follow on processing for a certificate order based on these returned status
|
|
||||||
constants.
|
|
||||||
|
|
||||||
.. autoclass:: CertificateStatus
|
|
||||||
:members:
|
|
||||||
|
|
||||||
|
|
||||||
Certificate Parameter Objects
|
|
||||||
=============================
|
|
||||||
|
|
||||||
Two dictionaries are available to most certificate plugin methods:
|
|
||||||
|
|
||||||
1. ``order_meta`` - A dictionary of values provided by the client when they
|
|
||||||
initiated the Barbican certificate order, including information needed to
|
|
||||||
create a certificate, such as CSR.
|
|
||||||
|
|
||||||
2. ``plugin_meta`` - A dictionary of values determined by the plugin itself
|
|
||||||
on behalf of a specific certificate order. Barbican core persists this
|
|
||||||
dictionary into the Barbican data store for a given order, and then provides
|
|
||||||
this data back plugin method invocations thereafter.
|
|
||||||
|
|
||||||
Plugins are free to update this data as required, or else ignore to it if not
|
|
||||||
required. For example, plugins that interact with remote CAs could store the
|
|
||||||
CA's unique order ID, for use with future interactions with that CA.
|
|
||||||
|
|
||||||
|
|
||||||
Plugin Base Class
|
|
||||||
=================
|
|
||||||
|
|
||||||
Barbican secret store plugins should implement the abstract base class
|
|
||||||
``CertificatePluginBase``. Concrete plugin implementations of
|
|
||||||
``CertificatePluginBase`` should be exposed to Barbican using ``stevedore``
|
|
||||||
mechanisms explained in the configuration portion of this guide.
|
|
||||||
|
|
||||||
.. autoclass:: CertificatePluginBase
|
|
||||||
:members:
|
|
||||||
|
|
||||||
|
|
||||||
Barbican Order's Status Versus ResultDTO's Status
|
|
||||||
=================================================
|
|
||||||
|
|
||||||
When Barbican starts processing orders, it sets the order's ``status``
|
|
||||||
attribute to ``PENDING``. Barbican will invoke methods on the certificate
|
|
||||||
plugin to process the order, and most of those methods return a ``ResultDTO``
|
|
||||||
result object, which also has a ``status`` field. Barbican core uses the
|
|
||||||
result's ``status`` to determine follow on processing for the order as
|
|
||||||
detailed in :ref:`plugin-certificate-sequence-label` below.
|
|
||||||
|
|
||||||
The result's ``status`` field should be set to one of the constants defined
|
|
||||||
in ``CertificateStatus``, per :ref:`plugin-certificate-status-label` above. If
|
|
||||||
the result's ``status`` calls for terminating the order, Barbican core will set
|
|
||||||
the order's status to either ``ACTIVE`` or ``ERROR``. Otherwise the order's
|
|
||||||
``status`` will stay ``PENDING``, and the order's ``sub_status`` and
|
|
||||||
``sub_status_message`` will be updated with the result's ``status`` and
|
|
||||||
``status_message`` respectively.
|
|
||||||
|
|
||||||
Clients that wish to track the progress of potentially long running certificate
|
|
||||||
orders can poll the order, using the ``sub_status`` and ``sub_status_message``
|
|
||||||
to track the results. Hence plugins should provide a meaningful
|
|
||||||
message for ``sub_status_message``, especially on error conditions.
|
|
||||||
|
|
||||||
|
|
||||||
.. _plugin-certificate-sequence-label:
|
|
||||||
|
|
||||||
Barbican Core Plugin Sequence
|
|
||||||
=============================
|
|
||||||
|
|
||||||
The sequence that Barbican invokes methods on ``CertificatePluginBase`` is
|
|
||||||
detailed next. Note that these methods are invoked via the
|
|
||||||
``barbican.tasks.certificate_resources`` module, which in turn is invoked via
|
|
||||||
Barbican's Worker processes.
|
|
||||||
|
|
||||||
Barbican core calls the following methods:
|
|
||||||
|
|
||||||
1. ``supports()`` - Asks the plugin if it can support generating a certificate
|
|
||||||
based on the Barbican order's ``order_meta``.
|
|
||||||
|
|
||||||
2. ``issue_certificate_request()`` - Asks the plugin to initiate a certificate
|
|
||||||
order from the provided ``order_meta`` parameter information. An empty
|
|
||||||
dictionary is passed in for the ``plugin_meta`` parameter, which the plugin
|
|
||||||
can update as it sees fit. Barbican core will persist and then provide the
|
|
||||||
``plugin_meta`` for subsequent method calls for this order.
|
|
||||||
|
|
||||||
The plugin method returns a ``ResultDTO`` instance which Barbican core uses
|
|
||||||
to determine subsequent order processing based on its ``status`` field. This
|
|
||||||
``status`` field should be set to one of the constants defined in
|
|
||||||
``CertificateStatus`` per :ref:`plugin-certificate-status-label` above.
|
|
||||||
|
|
||||||
If ``status`` is ``CertificateStatus.WAITING_FOR_CA`` then Barbican core
|
|
||||||
will invoke the ``check_certificate_status`` method after the delay
|
|
||||||
specified in the result's ``retry_msec`` field.
|
|
||||||
|
|
||||||
If ``status`` is ``CertificateStatus.CERTIFICATE_GENERATED`` then Barbican
|
|
||||||
core expects that this order is completed and sets its ``status`` to
|
|
||||||
``ACTIVE``. Barbican also expects that the result's ``certificate`` and
|
|
||||||
(optionally) ``intermediates`` fields are filled out with PEM-formatted SSL
|
|
||||||
certificate data. Barbican will then create a
|
|
||||||
``barbican.model.models.Container`` record with
|
|
||||||
``barbican.model.models.Secret`` records to hold the certificate data.
|
|
||||||
|
|
||||||
If ``status`` is ``CertificateStatus.CA_UNAVAILABLE_FOR_REQUEST`` then
|
|
||||||
Barbican core will invoke the same method after the delay specified in the
|
|
||||||
result's ``retry_msec`` field. This condition typically means that a remote
|
|
||||||
CA was not available, so should be retried in the future.
|
|
||||||
|
|
||||||
If ``status`` is set to ``CertificateStatus.CLIENT_DATA_ISSUE_SEEN`` then
|
|
||||||
Barbican considers the order to have problems with the client-provided data,
|
|
||||||
but otherwise the order is viable. Barbican will keep the order in the
|
|
||||||
``PENDING`` state, and update the order's ``sub_status`` to
|
|
||||||
``CertificateStatus.CLIENT_DATA_ISSUE_SEEN`` and ``sub_status_message`` to
|
|
||||||
the result's ``status_message``.
|
|
||||||
|
|
||||||
Note that client data issues can include missing or incorrect information
|
|
||||||
that the CA reports on. The CA still considers the order open, but clients
|
|
||||||
must provide updates to correct the data. Since the client could either
|
|
||||||
update this order via Barbican, or else work directly with a remote CA,
|
|
||||||
Barbican will invoke the ``check_certificate_status`` method after the delay
|
|
||||||
specified in the result's ``retry_msec`` field.
|
|
||||||
|
|
||||||
If ``status`` is set to ``CertificateStatus.REQUEST_CANCELED`` then Barbican
|
|
||||||
core expects that this order is completed and sets its ``status`` to
|
|
||||||
``ACTIVE``. It also updates the order's ``sub_status`` and
|
|
||||||
``sub_status_message`` to the result's status information. This condition
|
|
||||||
could arise (for example) if a remote CA indicated that the certificate
|
|
||||||
order is cancelled.
|
|
||||||
|
|
||||||
If ``status`` is set to ``CertificateStatus.INVALID_OPERATION`` (or else
|
|
||||||
the plugin raises an exception) then Barbican core considers this a failed
|
|
||||||
order and sets the order's ``status`` to ``ERROR``. It also updates the
|
|
||||||
order's ``sub_status`` and ``sub_status_message`` to the result's status
|
|
||||||
information.
|
|
||||||
|
|
||||||
3. ``check_certificate_status()`` - This method is called as needed after the
|
|
||||||
``issue_certificate_request()`` method and is intended to allow plugins to
|
|
||||||
check to see if a certificate has been issued yet.
|
|
||||||
|
|
||||||
The result's ``status`` is processed similarly to the
|
|
||||||
``issue_certificate_request()`` method.
|
|
||||||
|
|
||||||
4. ``modify_certificate_request`` - This method is invoked if clients provide
|
|
||||||
updates to the order metadata after the certificate order has been
|
|
||||||
initiated.
|
|
||||||
|
|
||||||
The result's ``status`` is processed similarly to the
|
|
||||||
``issue_certificate_request()`` method.
|
|
||||||
|
|
||||||
5. ``cancel_certificate_request`` - This method is invoked if clients delete
|
|
||||||
or cancel a certificate order.
|
|
||||||
|
|
||||||
Note that if a remote CA is involved the cancellation may not be processed
|
|
||||||
immediately, in which case Barbican core will invoke the
|
|
||||||
``check_certificate_status`` method after the delay specified in the
|
|
||||||
result's ``retry_msec`` field. Otherwise the result's ``status`` is
|
|
||||||
processed similarly to the ``issue_certificate_request()`` method.
|
|
@ -52,11 +52,10 @@ Architecture
|
|||||||
============
|
============
|
||||||
|
|
||||||
Barbican's plugin architecture enables developers to create their own
|
Barbican's plugin architecture enables developers to create their own
|
||||||
implementations of features such as secret storage and generation, X.509
|
implementations of features such as secret storage and generation and event handling.
|
||||||
certificate generation, and event handling. The plugin pattern used defines an
|
The plugin pattern used defines an abstract class, whose methods are invoked by Barbican
|
||||||
abstract class, whose methods are invoked by Barbican logic (referred to as
|
logic (referred to as Barbican 'core' in this guide) in a particular sequence. Typically
|
||||||
Barbican 'core' in this guide) in a particular sequence. Typically plugins do
|
plugins do not interact with Barbican's data model directly, so Barbican core also handles
|
||||||
not interact with Barbican's data model directly, so Barbican core also handles
|
|
||||||
persisting any required information on the plugin's behalf.
|
persisting any required information on the plugin's behalf.
|
||||||
|
|
||||||
In general, Barbican core will invoke a variation of the plugin's
|
In general, Barbican core will invoke a variation of the plugin's
|
||||||
@ -72,4 +71,3 @@ Barbican, as well as configuration and deployment options.
|
|||||||
|
|
||||||
secret_store
|
secret_store
|
||||||
crypto
|
crypto
|
||||||
certificate
|
|
||||||
|
@ -1,24 +0,0 @@
|
|||||||
Setting up Certificate Plugins
|
|
||||||
==============================
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
DEPRECATION WARNING: The Certificates Plugin has been deprecated and will
|
|
||||||
be removed in the P release.
|
|
||||||
|
|
||||||
Using the SnakeOil CA plugin
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
To evaluate Barbican certificate management, you can enable the snakeoil_ca
|
|
||||||
certificate plugin. This is not suitable for production environment, but it can
|
|
||||||
be useful as a development tool.
|
|
||||||
|
|
||||||
To do so, you simply need to set ``enabled_certificate_plugins`` in
|
|
||||||
``barbican.conf``.
|
|
||||||
|
|
||||||
.. code-block:: text
|
|
||||||
|
|
||||||
enabled_certificate_plugins = snakeoil_ca
|
|
||||||
|
|
||||||
And then restart your Barbican server. It will automatically generate an
|
|
||||||
in-memory CA to create certificates.
|
|
Loading…
x
Reference in New Issue
Block a user