Documentation for PKCS11 Key Generation script

Adding documentation to accompany the pkcs11 key generation script. Change-Id: I3c60cc8806b37c83f2f9bb7d6b37cb815c2c953a
2015-06-08 10:37:14 -05:00
parent 2fbc7f69a3
commit 050594ab67
2 changed files with 90 additions and 0 deletions
@@ -11,6 +11,7 @@ Quick Start
   ./quickstart/secrets
   ./quickstart/containers
   ./quickstart/acls
+   ./quickstart/pkcs11keygeneration


 API Reference
@@ -0,0 +1,89 @@
+***********************************
+PKCS11 Key Generation - Quick Start
+***********************************
+
+The Key Generation script was written with the Deployer in mind. It allows the
+deployer to create an MKEK and HMAC signing key for their HSM setup. This
+script is intended to be used initially or for key rotation scenarios.
+
+Setup
+#####
+
+Initially, the deployer will need to examine the settings in their
+barbican-api.conf file under the "Crypto plugin" settings section. Set these
+values to whichever defaults you need. This will be used for both the script
+and your usage of Barbican.
+
+The following items are required to use the PKCS11 plugin:
+
+  * Library Path
+  * Login Passphrase (Password to HSM)
+  * Slot ID (on HSM)
+
+The following will need to be provided to generate the HMAC and MKEK:
+  * MKEK Label
+  * MKEK Length
+  * HMAC Label
+
+
+Usage
+#####
+
+Viewing the help page can give some awareness to the structure of the script
+as well as inform you of any changes.
+
+.. code-block:: bash
+
+    $ python pkcs11-key-generation.py --help
+
+    usage: pkcs11-key-generation.py [-h] [--library-path LIBRARY_PATH]
+                                [--passphrase PASSPHRASE] [--slot-id SLOT_ID]
+                                {mkek,hmac} ...
+
+    Barbican MKEK & HMAC Generator
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --library-path LIBRARY_PATH
+                            Path to vendor PKCS11 library
+      --passphrase PASSPHRASE
+                            Password to login to PKCS11 session
+      --slot-id SLOT_ID     HSM Slot id (Should correspond to a configured PKCS11
+                            slot)
+
+    subcommands:
+      Action to perform
+
+      {mkek,hmac}
+        mkek                Generates a new MKEK.
+        hmac                Generates a new HMAC.
+
+**Note:** The user is able to pass the password in as an option or they
+can leave the flag out and will be prompted for the password upon submission
+of the command.
+
+Generating an MKEK
+******************
+
+To generate an MKEK, the user must provide a length and a label for the MKEK.
+
+.. code-block:: bash
+
+    $ python pkcs11-key-generation.py --library-path {library_path here}
+    --passphrase {HSM password here} --slot-id {HSM slot here} mkek --length 32
+    --label 'HMACLabelHere'
+    MKEK successfully generated!
+
+
+Generating an HMAC
+******************
+
+To generate an HMAC, the user must provide a label for the HMAC.
+
+.. code-block:: bash
+
+    $ python pkcs11-key-generation.py --library-path {library_path here}
+    --passphrase {HSM password here} --slot-id {HSM slot here} hmac
+    --label 'HMACLabelHere'
+    HMAC successfully generated!
+