openstack
/
barbican
Code Issues Proposed changes

Merge "Remove Certificate Orders and CAs from Documentation"

This commit is contained in:
Jenkins 2017-05-23 13:34:57 +00:00 committed by Gerrit Code Review
parent e6b21ed6e4 3f6c24a4ef
commit 8e9b0601d5
11 changed files with 6 additions and 1947 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
api-guide/source/cas.rst
View File

@ -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

336
api-guide/source/certificates.rst
View File

@ -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

12
api-guide/source/dogtag_setup.rst
View File

@ -197,14 +197,4 @@ server certificate for the CA.
Testing the Setup
*****************
Once all the above is set up, you can test the CA and KRA plugins by making a
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.
TODO

2
api-guide/source/index.rst
View File

@ -10,8 +10,6 @@ Contents
containers
acls
pkcs11keygeneration
certificates
cas
dogtag_setup
quotas
consumers

12
api-guide/source/orders.rst
View File

@ -3,27 +3,17 @@ Orders API - User Guide
***********************
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
public/private key pairs.
This is also very helpful for requesting the creation of public/private key pairs.
The orders resource supports the following types:
* symmetric 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.
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
`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:
Creating an Order

2
doc/source/api/index.rst
View File

@ -20,8 +20,6 @@ API Reference
./reference/store_backends.rst
./reference/containers
./reference/acls
./reference/certificates
./reference/cas
./reference/quotas
./reference/consumers
./reference/orders

978
doc/source/api/reference/cas.rst
View File

@ -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 |
+------+-----------------------------------------------------------------------------+

156
doc/source/api/reference/certificates.rst
View File

@ -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 |
+------+-----------------------------------------------------------------------------+

214
doc/source/plugin/certificate.rst
View File

@ -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.

10
doc/source/plugin/index.rst
View File

@ -52,11 +52,10 @@ Architecture
============
Barbican's plugin architecture enables developers to create their own
implementations of features such as secret storage and generation, X.509
certificate generation, and event handling. The plugin pattern used defines an
abstract class, whose methods are invoked by Barbican logic (referred to as
Barbican 'core' in this guide) in a particular sequence. Typically plugins do
not interact with Barbican's data model directly, so Barbican core also handles
implementations of features such as secret storage and generation and event handling.
The plugin pattern used defines an abstract class, whose methods are invoked by Barbican
logic (referred to as Barbican 'core' in this guide) in a particular sequence. Typically
plugins do not interact with Barbican's data model directly, so Barbican core also handles
persisting any required information on the plugin's behalf.
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
crypto
certificate

24
doc/source/setup/certificate.rst
View File

@ -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.