Merge "Add signed images documentation"

doc/source/index.rst

@@ -97,6 +97,7 @@ Using Glance
    glanceapi
    glanceclient
    glancemetadefcatalogapi
+   signature
 
 Glance Manual Pages
 ===================
@@ -121,4 +122,4 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+* :ref:`search`

doc/source/signature.rst

@@ -0,0 +1,152 @@
+..
+      Copyright 2016 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Image Signature Verification
+=============================
+
+Glance has the ability to perform image validation using a digital
+signature and asymmetric cryptography.  To trigger this, you must define
+specific image properties (described below), and have stored a
+certificate signed with your private key in a local Barbican installation.
+
+When the image properties exist on an image, Glance will validate
+the uploaded image data against these properties before storing it.
+If validation is unsuccessful, the upload will fail and the image will
+be deleted.
+
+Additionally, the image properties may be used by other services (for
+example, Nova) to perform data verification when the image is downloaded
+from Glance.
+
+Requirements
+------------
+Barbican key manager - See http://docs.openstack.org/developer/barbican/setup/devstack.html
+
+Using the Signature Verification
+--------------------------------
+
+An image will need a few properties for signature verification to be enabled,
+these are::
+
+  img_signature
+  img_signature_hash_method
+  img_signature_key_type
+  img_signature_certificate_uuid
+
+Property img_signature
+~~~~~~~~~~~~~~~~~~~~~~
+This is the signature of your image.
+
+.. note:: The max character limit is 255.
+
+Property img_signature_hash_method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Hash methods is the method you hash with.
+
+Current ones you can use are:
+
+* SHA-224
+* SHA-256
+* SHA-384
+* SHA-512
+
+Property img_signature_key_type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is the key_types you can use for your image.
+
+Current ones you can use are:
+
+* RSA-PSS
+* DSA
+* ECC-CURVES
+
+ * SECT571K1
+ * SECT409K1
+ * SECT571R1
+ * SECT409R1
+ * SECP521R1
+ * SECP384R1
+
+.. Note:: ECC curves - Only keysizes above 384 are included.
+          Not all ECC curves may be supported by the back end.
+
+Property img_signature_certificate_uuid
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is the UUID of the certificate that you upload to Barbican.
+
+Therefore the type passed to glance is:
+
+* UUID
+
+.. Note:: The supported certificate types are:
+
+          * X_509
+
+Example Usage
+-------------
+
+Follow these instructions to create your keys::
+
+  $ openssl genrsa -out private_key.pem 1024
+  Generating RSA private key, 1024 bit long modulus
+  ...............................................++++++
+  ..++++++
+  e is 65537 (0x10001)
+
+  $ openssl rsa -pubout -in private_key.pem -out public_key.pem
+  writing RSA key
+
+  $ openssl req -new -key private_key.pem -out cert_request.csr
+  You are about to be asked to enter information that will be incorporated
+  into your certificate request.
+
+  $ openssl x509 -req -days 14 -in cert_request.csr -signkey private_key.pem -out new_cert.crt
+  Signature ok
+  subject=/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd
+  Getting Private key
+
+Upload your certificate. This only has to be done once as you can use
+the same ``Secret href`` for many images until it expires::
+
+  $ openstack secret store --name test --algorithm RSA --expiration 2016-06-29 --secret-type certificate --payload-content-type "application/octet-stream" --payload-content-encoding base64 --payload "$(base64 new_cert.crt)"
+  +---------------+-----------------------------------------------------------------------+
+  | Field         | Value                                                                 |
+  +---------------+-----------------------------------------------------------------------+
+  | Secret href   | http://127.0.0.1:9311/v1/secrets/cd7cc675-e573-419c-8fff-33a72734a243 |
+
+  $ cert_uuid=cd7cc675-e573-419c-8fff-33a72734a243
+
+Get an image and create the signature::
+
+  $ echo This is a dodgy image > myimage
+
+  $ openssl dgst -sha256 -sign private_key.pem -sigopt rsa_padding_mode:pss -out myimage.signature myimage
+
+  $ base64 myimage.signature > myimage.signature.b64
+
+  $ image_signature=$(cat myimage.signature.b64)
+
+Create the image::
+
+  $ glance image-create --name mySignedImage --container-format bare --disk-format qcow2 --property img_signature="$image_signature" --property img_signature_certificate_uuid="$cert_uuid" --property img_signature_hash_method='SHA-256' --property img_signature_key_type='RSA-PSS' < myimage
+
+.. note:: Creating the image can fail if validation does not succeeed.
+          This will cause the image to be deleted.
+
+Other Links
+-----------
+* https://etherpad.openstack.org/p/mitaka-glance-image-signing-instructions
+* http://docs.openstack.org/ops-guide/ops_user_facing_operations.html