Add install guide

Install Guides are maintained within the project and are linked
to the official docs.

This commit adds the framework and some initial content.

Change-Id: Iff18f0e866d95ff4b8b490511c2acf3209690b69

install-guide/source/barbican-backend.rst

@@ -0,0 +1,174 @@
+.. _barbican_backend:
+
+Secret Store Back-ends
+~~~~~~~~~~~~~~~~~~~~~~
+
+The Key Manager service has a plugin architecture that allows the deployer to
+store secrets in one or more secret stores.  Secret stores can be software-based
+such as a software token,  or hardware devices such as a hardware security
+module (HSM).
+
+This section describes the plugins that are currently available
+and how they might be configured.
+
+Crypto Plugins
+--------------
+
+These types of plugins store secrets as encrypted blobs within the
+Barbican database.  The plugin is invoked to encrypt the secret on secret
+storage, and decrypt the secret on secret retrieval.
+
+To enable these plugins, add ``store_crypto`` to the list of enabled
+secret store plugins in the ``[secret_store]`` section of
+``/etc/barbican/barbican.conf`` :
+
+    .. code-block:: ini
+
+       [secretstore]
+       namespace = barbican.secretstore.plugin
+       enabled_secretstore_plugins = store_crypto
+
+There are two flavors of storage plugins currently available: the Simple
+Crypto plugin and the PKCS#11 crypto plugin.
+
+Simple Crypto Plugin
+^^^^^^^^^^^^^^^^^^^^
+
+This crypto plugin is configured by default in barbican.conf.  This plugin
+is completely insecure and is only suitable for development testing.
+
+.. warning::
+
+   THIS PLUGIN IS NOT SUITABLE FOR PRODUCTION DEPLOYMENTS.
+
+This plugin uses single symmetric key (kek - or 'key encryption key')
+- which is stored in plain text in the ``barbican.conf`` file to encrypt
+and decrypt all secrets.
+
+The configuration for this plugin in ``barbican.conf`` is as follows:
+
+    .. code-block:: ini
+
+       # ================= Secret Store Plugin ===================
+       [secretstore]
+       ..
+       enabled_secretstore_plugins = store_crypto
+
+       # ================= Crypto plugin ===================
+       [crypto]
+       ..
+       enabled_crypto_plugins = simple_crypto
+
+       [simple_crypto_plugin]
+       # the kek should be a 32-byte value which is base64 encoded
+       kek = 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY='
+
+PKCS#11 Crypto Plugin
+^^^^^^^^^^^^^^^^^^^^^
+
+This crypto plugin can be used to interface with a Hardware Security Module (HSM)
+using the PKCS#11 protocol.
+
+Secrets are encrypted (and decrypted on retrieval) by a project specific
+Key Encryption Key (KEK), which resides in the HSM.
+
+The configuration for this plugin in ``barbican.conf`` with settings shown for
+use with a SafeNet HSM is as follows:
+
+    .. code-block:: ini
+
+       # ================= Secret Store Plugin ===================
+       [secretstore]
+       ..
+       enabled_secretstore_plugins = store_crypto
+
+       [p11_crypto_plugin]
+       # Path to vendor PKCS11 library
+       library_path = '/usr/lib/libCryptoki2_64.so'
+       # Password to login to PKCS11 session
+       login = 'mypassword'
+       # Label to identify master KEK in the HSM (must not be the same as HMAC label)
+       mkek_label = 'an_mkek'
+       # Length in bytes of master KEK
+       mkek_length = 32
+       # Label to identify HMAC key in the HSM (must not be the same as MKEK label)
+       hmac_label = 'my_hmac_label'
+       # HSM Slot id (Should correspond to a configured PKCS11 slot). Default: 1
+       # slot_id = 1
+       # Enable Read/Write session with the HSM?
+       # rw_session = True
+       # Length of Project KEKs to create
+       # pkek_length = 32
+       # How long to cache unwrapped Project KEKs
+       # pkek_cache_ttl = 900
+       # Max number of items in pkek cache
+       # pkek_cache_limit = 100
+
+KMIP Plugin
+-----------
+
+This secret store plugin is used to communicate with a KMIP device.
+The secret is securely stored in the KMIP device directly, rather than in the
+Barbican database.  The Barbican database maintains a reference to the
+secret's location for later retrieval.
+
+The plugin can be configured to authenticate to the KMIP device using either
+a username and password, or using a client certificate.
+
+The configuration for this plugin in ``barbican.conf`` is as follows:
+
+    .. code-block:: ini
+
+       [secretstore]
+       ..
+       enabled_secretstore_plugins = kmip_crypto
+
+       [kmip_plugin]
+       username = 'admin'
+       password = 'password'
+       host = localhost
+       port = 5696
+       keyfile = '/path/to/certs/cert.key'
+       certfile = '/path/to/certs/cert.crt'
+       ca_certs = '/path/to/certs/LocalCA.crt'
+
+Dogtag Plugin
+-------------
+
+Dogtag is the upstream project corresponding to the Red Hat Certificate System.
+a robust, full-featured PKI solution that contains a Certificate Manager (CA)
+and a Key Recovery Authority (KRA) which is used to securely store secrets.
+
+The KRA stores secrets as encrypted blobs in its internal database, with the
+master encryption keys being stored either in a software-based NSS security
+database, or in a Hardware Security Module (HSM).
+
+Note that the software-based NSS database configuration provides a secure option for
+those deployments that do not require or cannot afford an HSM.  This is the only
+current plugin to provide this option.
+
+The KRA communicates with HSMs using PKCS#11.  For a list of certified HSMs,
+see the latest `release notes <https://access.redhat.com/documentation/en-US/Red_Hat_Certificate_System/9/html/Release_Notes/Release_Notes-Deployment_Notes.html>`_.  Dogtag and the KRA meet all the relevant Common Criteria and FIPS specifications.
+
+The KRA is a component of FreeIPA.  Therefore, it is possible to configure the plugin
+with a FreeIPA server.  More detailed instructions on how to set up Barbican with FreeIPA
+are provided `here <https://vakwetu.wordpress.com/2015/11/30/barbican-and-dogtagipa/>`_.
+
+The plugin communicates with the KRA using a client certificate for a trusted KRA agent.
+That certificate is stored in an NSS database as well as a PEM file as seen in the
+configuration below.
+
+The configuration for this plugin in ``barbican.conf`` is as follows:
+
+    .. code-block:: ini
+
+       [secretstore]
+       ..
+       enabled_secretstore_plugins = dogtag_crypto
+
+       [dogtag_plugin]
+       pem_path = '/etc/barbican/kra_admin_cert.pem'
+       dogtag_host = localhost
+       dogtag_port = 8443
+       nss_db_path = '/etc/barbican/alias'
+       nss_password = 'password123'

install-guide/source/common_configure.rst

@@ -0,0 +1,92 @@
+2. Edit the ``/etc/barbican/barbican.conf`` file and complete the following
+   actions:
+
+   * In the ``[database]`` section, configure database access:
+
+     .. code-block:: none
+
+        [database]
+        ...
+        connection = mysql+pymysql://barbican:BARBICAN_DBPASS@controller/barbican
+
+     Replace ``BARBICAN_DBPASS`` with the password you chose for the
+     Key Manager service database.
+
+   * In the ``[DEFAULT]`` and ``[oslo_messaging_rabbit]`` sections,
+     configure ``RabbitMQ`` message queue access:
+
+     .. code-block:: ini
+
+        [DEFAULT]
+        ...
+        rpc_backend = rabbit
+
+        [oslo_messaging_rabbit]
+        ...
+        rabbit_host = controller
+        rabbit_userid = openstack
+        rabbit_password = RABBIT_PASS
+
+     Replace ``RABBIT_PASS`` with the password you chose for the
+     ``openstack`` account in ``RabbitMQ``.
+
+   * In the ``[keystone_authtoken]`` section, configure Identity
+     service access:
+
+     .. code-block:: ini
+
+        [keystone_authtoken]
+        ...
+        auth_uri = http://controller:5000
+        auth_url = http://controller:35357
+        memcached_servers = controller:11211
+        auth_type = password
+        project_domain_name = default
+        user_domain_name = default
+        project_name = service
+        username = barbican
+        password = BARBICAN_PASS
+
+     Replace ``BARBICAN_PASS`` with the password you chose for the
+     ``barbican`` user in the Identity service.
+
+     .. note::
+
+        Comment out or remove any other options in the
+        ``[keystone_authtoken]`` section.
+
+#. Edit the ``/etc/barbican/barbican-api-paste.ini`` file and complete the
+   following actions:
+
+   * In the ``[pipeline:barbican_api]`` section, configure the pipeline to
+     use the Identity Service auth token.
+
+     .. code-block:: ini
+
+        [pipeline:barbican_api]
+        pipeline = cors authtoken context apiapp
+
+#. Populate the Key Manager service database:
+
+   The Key Manager service database will be automatically populated
+   when the service is first started.  To prevent this, and run the
+   database sync manually, edit the ``/etc/barbican/barbican.conf`` file
+   and set db_auto_create in the ``[DEFAULT]`` section to False.
+
+   Then populate the database as below:
+
+   .. code-block:: console
+
+      $ su -s /bin/sh -c "barbican-manage db_sync" barbican
+
+   .. note::
+
+      Ignore any deprecation messages in this output.
+
+#.  Barbican has a plugin architecture which allows the deployer to store secrets in
+    a number of different back-end secret stores.  By default, Barbican is configured to
+    store secrets in a basic file-based keystore.  This key store is NOT safe for
+    production use.
+
+    For a list of supported plugins and detailed instructions on how to configure them,
+    see :ref:`barbican_backend`

install-guide/source/common_prerequisites.rst

@@ -0,0 +1,87 @@
+Prerequisites
+-------------
+
+Before you install and configure the Key Manager service,
+you must create a database, service credentials, and API endpoints.
+
+#. To create the database, complete these steps:
+
+   * Use the database access client to connect to the database
+     server as the ``root`` user:
+
+     .. code-block:: console
+
+        $ mysql -u root -p
+
+   * Create the ``barbican`` database:
+
+     .. code-block:: mysql
+
+        CREATE DATABASE barbican;
+
+   * Grant proper access to the ``barbican`` database:
+
+     .. code-block:: mysql
+
+        GRANT ALL PRIVILEGES ON barbican.* TO 'barbican'@'localhost' \
+          IDENTIFIED BY 'BARBICAN_DBPASS';
+        GRANT ALL PRIVILEGES ON barbican.* TO 'barbican'@'%' \
+          IDENTIFIED BY 'BARBICAN_DBPASS';
+
+     Replace ``BARBICAN_DBPASS`` with a suitable password.
+
+   * Exit the database access client.
+
+     .. code-block:: mysql
+
+        exit;
+
+#. Source the ``admin`` credentials to gain access to
+   admin-only CLI commands:
+
+   .. code-block:: console
+
+      $ source admin-openrc
+
+#. To create the service credentials, complete these steps:
+
+   * Create the ``barbican`` user:
+
+     .. code-block:: console
+
+        $ openstack user create --domain default --password-prompt barbican
+
+   * Add the ``admin`` role to the ``barbican`` user:
+
+     .. code-block:: console
+
+        $ openstack role add --project service --user barbican admin
+
+   * Create the ``creator`` role:
+
+     .. code-block:: console
+
+        $ openstack role create creator
+
+   * Add the ``creator`` role to the ``barbican`` user:
+
+     .. code-block:: console
+
+        $ openstack role add --project service --user barbican creator
+
+   * Create the barbican service entities:
+
+     .. code-block:: console
+
+        $ openstack service create --name barbican --description "Key Manager" key-manager
+
+#. Create the Key Manager service API endpoints:
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        key-manager public http://controller:9311/v1/%\(tenant_id\)s
+      $ openstack endpoint create --region RegionOne \
+        key-manager internal http://controller:9311/v1/%\(tenant_id\)s
+      $ openstack endpoint create --region RegionOne \
+        key-manager admin http://controller:9311/v1/%\(tenant_id\)s