Add secret store plugin page

Add a Sphinx document page detailing the secret store plugin. Also add
cross references between this page and the crypto plugin page.

Change-Id: I59f66440eb5d247197ac47dd0994b44b4a9eec4b

doc/source/plugin/crypto.rst

@@ -1,21 +1,22 @@
 .. module:: barbican.plugin.crypto.crypto
 
-==================================
+================================
 Cryptographic Plugin Development
-==================================
+================================
 
 This guide describes how to develop a custom cryptographic plugin for use by
 Barbican.
 
-Barbican supports two storage modes for secrets. This document focuses on the
-mode that stores encrypted secrets in Barbican's data store, utilizing a
-cryptographic process or appliance (such as a hardware security module (HSM))
-to perform the encryption/decryption.
+Barbican supports two storage modes for secrets: a cryptographic mode (detailed
+on this page), and a :doc:`secret store mode </plugin/secret_store>`. The
+cryptograpic mode stores encrypted secrets in Barbican's data store, utilizing
+a cryptographic process or appliance (such as a hardware security module (HSM))
+to perform the encryption/decryption. Barbican includes a PKCS11-based
+interface to SafeNet HSMs.
 
-The other secret storage mode is detailed in the 'secret store' section. Note
-that cryptographic plugins are invoked from within the context of a 'secret
-store' plugin via an adapter class, further described in the 'secret store'
-section.
+Note that cryptographic plugins are not invoked directly from Barbican core,
+but rather via a :doc:`secret store mode </plugin/secret_store>` plugin adapter
+class, further described in :ref:`plugin-secret-store-crypto-adapter-label`.
 
 ``crypto`` Module
 =================
@@ -56,10 +57,12 @@ portion of this guide.
    :members:
 
 Barbican Core Plugin Sequence
-===============================
+=============================
 
-The sequence that Barbican invokes methods on ``CryptoPluginBase``
-depends on the requested action as detailed next.
+Barbican invokes a different sequence of methods on the ``CryptoPluginBase``
+plugin depending on the requested action. Note that these actions are invoked
+via the secret store adapter class ``StoreCryptoAdapterPlugin`` which is further
+described in :ref:`plugin-secret-store-crypto-adapter-label`.
 
 **For secret storage actions**, Barbican core calls the following methods:
 
@@ -82,8 +85,8 @@ depends on the requested action as detailed next.
 
 **For secret decryptions and retrievals**, Barbican core will select the same
 plugin as was used to store the secret, and then invoke its ``decrypt()``
-method, providing both the persisted encrypted secret data as well as the same
-project-ID KEK used to encrypt the secret above.
+method, providing it both the previously-persisted encrypted secret data as well
+as the project-ID KEK used to encrypt the secret.
 
 **For symmetric key generation**, Barbican core calls the following methods:
 

doc/source/plugin/index.rst

@@ -27,4 +27,5 @@ Barbican, as well as configuration and deployment options.
 .. toctree::
    :maxdepth: 1
 
+   secret_store
    crypto

doc/source/plugin/secret_store.rst

@@ -0,0 +1,141 @@
+.. module:: barbican.plugin.interface.secret_store
+
+===============================
+Secret Store Plugin Development
+===============================
+
+This guide describes how to develop a custom secret store plugin for use by
+Barbican.
+
+Barbican supports two storage modes for secrets: a secret store mode (detailed
+on this page), and a :doc:`cryptographic mode </plugin/crypto>`. The secret
+store mode offloads both encryption/decryption and encrypted secret storage to
+the plugin implementation. Barbican includes plugin interfaces to a Red Hat
+Dogtag service and to a Key Management Interoperability Protocol (KMIP)
+compliant security appliance.
+
+Since the secret store mode defers the storage of encrypted secrets to plugins,
+Barbican core does not need to store encrypted secrets into its data store,
+unlike the :doc:`cryptographic mode </plugin/crypto>`. To accommodate the
+discrepancy between the two secret storage modes, a secret store to
+cryptographic plugin adapter has been included in Barbican core, as detailed in
+:ref:`plugin-secret-store-crypto-adapter-label` section below.
+
+
+``secret_store`` Module
+=======================
+
+The ``barbican.plugin.interface.secret_store`` module contains the classes
+needed to implement a custom plugin.  These classes include the
+``SecretStoreBase`` abstract base class which custom plugins should inherit
+from, as well as several Data Transfer Object (DTO) classes used to transfer
+data between Barbican and the plugin.
+
+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:: SecretDTO
+
+.. autoclass:: AsymmetricKeyMetadataDTO
+
+Secret Parameter Objects
+========================
+
+The secret parameter classes encapsulate information about secrets to be stored
+within Barbican and/or its plugins.
+
+
+.. autoclass:: SecretType
+
+.. autoclass:: KeyAlgorithm
+
+.. autoclass:: KeySpec
+
+
+Plugin Base Class
+=================
+
+Barbican secret store plugins should implement the abstract base class
+``SecretStoreBase``.  Concrete implementations of this class should be exposed
+to Barbican using ``stevedore`` mechanisms explained in the configuration
+portion of this guide.
+
+.. autoclass:: SecretStoreBase
+   :members:
+
+Barbican Core Plugin Sequence
+=============================
+
+The sequence that Barbican invokes methods on ``SecretStoreBase``
+depends on the requested action as detailed next. Note that these actions are
+invoked via the ``barbican.plugin.resources`` module, which in turn is invoked
+via Barbican's API and Worker processes.
+
+**For secret storage actions**, Barbican core calls the following methods:
+
+1. ``get_transport_key()`` - If a transport key is requested to upload secrets
+   for storage, this method asks the plugin to provide the transport key.
+
+2. ``store_secret_supports()`` - Asks the plugin if it can support storing a
+   secret based on the ``KeySpec`` parameter information as described above.
+
+3. ``store_secret()`` - Asks the plugin to perform encryption of an unencrypted
+   secret payload as provided in the ``SecretDTO`` above, and then to store
+   that secret. The plugin then returns a dictionary of information about that
+   secret (typically a unique reference to that stored secret that only makes
+   sense to the plugin). Barbican core will then persist this dictionary as a
+   JSON attribute within its data store, and also hand it back to the plugin for
+   secret retrievals later. The name of the plugin used to perform this storage
+   is also persisted by Barbican core, to ensure we retrieve this secret only
+   with this plugin.
+
+**For secret retrievals**, Barbican core will select the same plugin as was
+used to store the secret, and then invoke its ``get_secret()``
+method to return the unencrypted secret.
+
+**For symmetric key generation**, Barbican core calls the following methods:
+
+1. ``generate_supports()`` -  Asks the plugin if it can support generating a
+   symmetric key based on the ``KeySpec`` parameter information as described
+   above.
+
+2. ``generate_symmetric_key()`` - Asks the plugin to both generate and store a
+   symmetric key based on the ``KeySpec`` parameter information. The plugin can
+   then return a dictionary of information for the stored secret similar to
+   the storage process above, which Barbican core will persist for later
+   retrieval of this generated secret.
+
+**For asymmetric key generation**, Barbican core calls the following methods:
+
+1. ``generate_supports()`` - Asks the plugin if it can support generating an
+   asymmetric key based on the ``KeySpec`` parameter information as described
+   above.
+
+2. ``generate_asymmetric_key()`` - Asks the plugin to both generate and store
+   an asymmetric key based on the ``KeySpec`` parameter information. The plugin
+   can then return an ``AsymmetricKeyMetadataDTO`` object as described above,
+   which contains secret metadata for each of the three secrets generated and
+   stored by this plugin: private key, public key and an optional passphrase.
+   Barbican core will then persist information for these secrets, and also
+   create a container to group them.
+
+.. _plugin-secret-store-crypto-adapter-label:
+
+The Cryptographic Plugin Adapter
+================================
+
+Barbican core includes a specialized secret store plugin used to adapt to
+cryptographic plugins, called ``StoreCryptoAdapterPlugin``. This plugin
+functions as a secret store plugin, but it directs secret related operations to
+:doc:`cryptographic plugins </plugin/crypto>` for
+encryption/decryption/generation operations. Because cryptographic plugins do
+not store encrypted secrets, this adapter plugin provides this storage
+capability via Barbican's data store.
+
+This adapter plugin also uses ``stevedore`` to access and utilize cryptographic
+plugins that can support secret operations.