From 7533f1c70d8bd3ed5769c1aa5f1cc18a21e5b27e Mon Sep 17 00:00:00 2001 From: Niall Bunting Date: Thu, 23 Jun 2016 09:34:51 +0000 Subject: [PATCH] Add signed images documentation This adds some documentation for creating and uploading signed images. The only other documentation that exists seems to require the use of python for parts of the image creation process, which may not be totally user friendly. Change-Id: I5e4c92c865edd6429986565fe46fbb60756e0d68 --- doc/source/index.rst | 3 +- doc/source/signature.rst | 152 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 doc/source/signature.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index e876e470cc..553055a6b9 100644 --- a/doc/source/index.rst +++ b/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` \ No newline at end of file +* :ref:`search` diff --git a/doc/source/signature.rst b/doc/source/signature.rst new file mode 100644 index 0000000000..c6ca4e0b15 --- /dev/null +++ b/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