Introducing barbican-manage utility command

A new 'barbican-manage' utility command is introduced as Barbican
admin tool. This command interacts with Barbican service for
management operations which usually cannot be accomplished with
REST APIs. This can improve usability and extensibility in the
future.

The related blueprint is https://review.openstack.org/#/c/253719/

This CR includes
1) implementation of barbican_manage.py
2) unit test code
3) document of barbican-manage command

Co-Authored-By: Michael Perng <mperng@us.ibm.com>
Change-Id: I784b46df86742d00d1737e3f8964280514a7fa1b

doc/source/admin-guide-cloud/barbican_manage.rst

@@ -0,0 +1,78 @@
+===================================
+Barbican Service Management Utility
+===================================
+
+Description
+===========
+``barbican-manage`` is a utility that is used to control the barbican key
+manager service database and Hardware Secure Module (HSM) plugin device. Use
+cases include migrating the secret database or generating a Master Key
+Encryption Key (MKEK) in the HSM. This command set should only be executed by
+a user with admin privileges.
+
+Options
+=======
+
+The standard pattern for executing a barbican-manage command is:
+
+``barbican-manage <category> <command> [<args>]``
+
+Running ``barbican-manage`` without arguments shows a list of available command
+categories. Currently, there are 2 supported categories: *db* and *hsm*.
+
+Running with a category argument shows a list of commands in that category:
+
+* ``barbican-manage db --help``
+* ``barbican-manage hsm --help``
+* ``barbican-manage --version`` shows the version number of barbican service.
+
+The following sections describe the available categories and arguments for
+barbican-manage.
+
+Barbican Database
+~~~~~~~~~~~~~~~~~
+
+.. Warning::
+    Before executing **barbican-manage db** commands, make sure you are
+    familiar with `Database Migration`_ first.
+
+``barbican-manage db revision [--db-url] [--message] [--autogenerate]``
+
+    Create a new database version file.
+
+``barbican-manage db upgrade [--db-url] [--version]``
+
+    Upgrade to a future version database.
+
+``barbican-manage db history [--db-url] [--verbose]``
+
+    Show database changeset history.
+
+``barbican-manage db current [--db-url] [--verbose]``
+
+    Show current revision of database.
+
+Barbican PKCS11/HSM
+~~~~~~~~~~~~~~~~~~~
+
+``barbican-manage hsm gen_mkek [--library-path] [--passphrase] [--slot-id] [--label] [--length]``
+
+    Create a new Master key encryption key in HSM.
+    This MKEK will be used to encrypt all project key encryption keys.
+    Its label must be unique.
+
+``barbican-manage hsm gen_hmac [--library-path] [--passphrase] [--slot-id] [--label] [--length]``
+
+    Create a new Master HMAC key in HSM.
+    This HMAC key will be used to generate an authentication tag of encrypted
+    project key encryption keys. Its label must be unique.
+
+``barbican-manage hsm rewrap_pkek [--dry-run]``
+
+    Rewrap project key encryption keys after rotating to new MKEK and/or HMAC
+    key(s) in HSM. The new MKEK and HMAC key should have already been generated
+    using the above commands. The user will have to configure new MKEK and HMAC
+    key labels in /etc/barbican.conf and restart barbican server before
+    executing this command.
+
+.. _Database Migration: http://docs.openstack.org/developer/barbican/contribute/database_migrations.html

doc/source/admin-guide-cloud/index.rst

@@ -10,3 +10,5 @@ management of secrets.
    :maxdepth: 1
 
    access_control.rst
+
+   barbican_manage.rst