diff --git a/doc/source/plugin/crypto.rst b/doc/source/plugin/crypto.rst index af0a91049..e79f785a6 100644 --- a/doc/source/plugin/crypto.rst +++ b/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 `. 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 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: diff --git a/doc/source/plugin/index.rst b/doc/source/plugin/index.rst index dd80c4f00..02cb2d41d 100644 --- a/doc/source/plugin/index.rst +++ b/doc/source/plugin/index.rst @@ -27,4 +27,5 @@ Barbican, as well as configuration and deployment options. .. toctree:: :maxdepth: 1 + secret_store crypto \ No newline at end of file diff --git a/doc/source/plugin/secret_store.rst b/doc/source/plugin/secret_store.rst new file mode 100644 index 000000000..e06dde4e4 --- /dev/null +++ b/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 `. 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 `. 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 ` 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.