Add certificate plugin page
Add a page detailing the certificate plugin, including classes and the interaction of plugin methods with barbican 'core' logic. Change-Id: Iade34e4b021fe12afb7e4eeba107327cbb70e43f
This commit is contained in:
parent
024ce1827a
commit
9a75a4c31b
@ -266,7 +266,22 @@ class CertificatePluginBase(object):
|
|||||||
|
|
||||||
|
|
||||||
class CertificateStatus(object):
|
class CertificateStatus(object):
|
||||||
"""Defines statuses for certificate request process."""
|
"""Defines statuses for certificate request process.
|
||||||
|
|
||||||
|
In particular:
|
||||||
|
|
||||||
|
CERTIFICATE_GENERATED - Indicates a certificate was created
|
||||||
|
|
||||||
|
WAITING_FOR_CA - Waiting for Certificate authority (CA) to complete order
|
||||||
|
|
||||||
|
CLIENT_DATA_ISSUE_SEEN - Problem was seen with client-provided data
|
||||||
|
|
||||||
|
CA_UNAVAILABLE_FOR_REQUEST - CA was not available, will try again later
|
||||||
|
|
||||||
|
REQUEST_CANCELED - The client or CA cancelled this order
|
||||||
|
|
||||||
|
INVALID_OPERATION - Unexpected error seen processing order
|
||||||
|
"""
|
||||||
|
|
||||||
CERTIFICATE_GENERATED = "certificate generated"
|
CERTIFICATE_GENERATED = "certificate generated"
|
||||||
WAITING_FOR_CA = "waiting for CA"
|
WAITING_FOR_CA = "waiting for CA"
|
||||||
@ -277,7 +292,12 @@ class CertificateStatus(object):
|
|||||||
|
|
||||||
|
|
||||||
class ResultDTO(object):
|
class ResultDTO(object):
|
||||||
"""This object is the result data transfer object (DTO)."""
|
"""Result data transfer object (DTO).
|
||||||
|
|
||||||
|
An object of this type is returned by most certificate plugin methods, and
|
||||||
|
is used to guide follow on processing and to provide status feedback to
|
||||||
|
clients.
|
||||||
|
"""
|
||||||
def __init__(self, status, status_message=None, certificate=None,
|
def __init__(self, status, status_message=None, certificate=None,
|
||||||
intermediates=None, retry_msec=RETRY_MSEC, retry_method=None):
|
intermediates=None, retry_msec=RETRY_MSEC, retry_method=None):
|
||||||
"""Creates a new ResultDTO.
|
"""Creates a new ResultDTO.
|
||||||
|
211
doc/source/plugin/certificate.rst
Normal file
211
doc/source/plugin/certificate.rst
Normal file
@ -0,0 +1,211 @@
|
|||||||
|
.. module:: barbican.plugin.interface.certificate_manager
|
||||||
|
|
||||||
|
==============================
|
||||||
|
Certificate Plugin Development
|
||||||
|
==============================
|
||||||
|
|
||||||
|
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.
|
@ -29,3 +29,4 @@ Barbican, as well as configuration and deployment options.
|
|||||||
|
|
||||||
secret_store
|
secret_store
|
||||||
crypto
|
crypto
|
||||||
|
certificate
|
||||||
|
Loading…
x
Reference in New Issue
Block a user