Document HSM usage for members identity and encryption keys (#1884)

jumaffre · web-flow · commit ebda2365aa71 · 2020-11-16T13:02:06.000Z
diff --git a/doc/members/adding_member.rst b/doc/members/adding_member.rst
@@ -3,11 +3,13 @@ Adding New Members
 
 It is possible for existing members to add new members to the consortium after a CCF network has been started.
 
-.. note:: The maximum number of active consortium members at any given time is 255.
+.. note:: The maximum number of allowed active recovery members (i.e. those with a recovery share) at any given time is 255.
 
 Generating Member Keys and Certificates
 ---------------------------------------
 
+.. note:: See :doc:`/members/hsm_keys` for a guide on how to used member keys and certificate store in Azure Key Vault.
+
 First, the identity and encryption public and private key pairs of the new member should be created.
 
 The ``keygenerator.sh`` script can be used to generate the member’s certificate and associated private key as well as their encryption public and private keys.
diff --git a/doc/members/akv_identity_cert_policy.json b/doc/members/akv_identity_cert_policy.json
@@ -0,0 +1,30 @@
+{
+  "issuerParameters": {
+    "certificateTransparency": null,
+    "name": "Self"
+  },
+  "keyProperties": {
+    "curve": "P-384",
+    "exportable": true,
+    "keyType": "EC",
+    "reuseKey": true
+  },
+  "lifetimeActions": [
+    {
+      "action": {
+        "actionType": "AutoRenew"
+      },
+      "trigger": {
+        "daysBeforeExpiry": 90
+      }
+    }
+  ],
+  "secretProperties": {
+    "contentType": "application/x-pkcs12"
+  },
+  "x509CertificateProperties": {
+    "keyUsage": ["digitalSignature"],
+    "subject": "CN=Member",
+    "validityInMonths": 12
+  }
+}
diff --git a/doc/members/hsm_keys.rst b/doc/members/hsm_keys.rst
@@ -0,0 +1,126 @@
+Using Member Keys Stored in HSM
+===============================
+
+This page explains how members' identity certificates and encryption keys stored in an `HSM <https://en.wikipedia.org/wiki/Hardware_security_module>`_ can be used with CCF. The following guide describes the usage of `Azure Key Vault <https://azure.microsoft.com/en-gb/services/key-vault>`_
+
+.. note::
+
+    It is assumed that CCF members already have access to an existing Azure Key Vault. See `here <https://docs.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal#create-a-vault>`_ for more details on how to create one. Using the `Azure CLI <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>`_, it is possible to check the list of available Key Vault instances:
+
+    .. code-block:: bash
+
+        $ az keyvault list
+        # Outputs list of available vaults, including name
+        $ export VAULT_NAME="<vault_name>"
+
+Certificate and Key Generation
+------------------------------
+
+Members' identity certificates should be generated on the `secp384r1` elliptic curve, using the `az keyvault certificate create <https://docs.microsoft.com/en-us/cli/azure/keyvault/certificate?view=azure-cli-latest#az_keyvault_certificate_create>`_ command, with the following ``identity_cert_policy_example.json`` policy:
+
+.. include:: akv_identity_cert_policy.json
+    :literal:
+
+.. code-block:: bash
+
+    $ export IDENTITY_CERT_NAME="<identity-cert-name>"
+    $ az keyvault certificate create --vault-name $VAULT_NAME -n $IDENTITY_CERT_NAME -p @identity_cert_policy_example.json
+    # Outputs certificate details
+
+    # Corresponding private key is accessible at the same URL (substituting /certificate/ with /key/)
+    $ az keyvault key show --vault-name $VAULT_NAME --name $IDENTITY_CERT_NAME
+    # Outputs key information, including kid url
+
+Members' encryption keys should be RSA 2048 keys, generated with the `az keyvault key create <https://docs.microsoft.com/en-us/cli/azure/keyvault/key?view=azure-cli-latest#az_keyvault_key_create>`_ command:
+
+.. code-block:: bash
+
+    $ export ENCRYPTION_KEY_NAME="<encryption-key-name>"
+    $ az keyvault key create --vault-name $VAULT_NAME --name $ENCRYPTION_KEY_NAME --kty RSA --ops decrypt
+    # Outputs key details, including kid url
+
+The identity certificate and public encryption key can be downloaded to a PEM file and be passed on to members to be registered in a CCF service as a trusted member identity (see :ref:`members/adding_member:Registering a New Member`). Alternatively, if the service has not yet been started, the public member identity can be passed on to operators and registered via the ``cchost --member-info`` option (see :ref:`operators/start_network:Starting the First Node`):
+
+.. code-block:: bash
+
+    $ az keyvault certificate download --file $IDENTITY_CERT_NAME.pem --vault-name $VAULT_NAME --name $IDENTITY_CERT_NAME
+    # Downloads PEM identity certificate
+
+    $ az keyvault key download --file $ENCRYPTION_KEY_NAME.pem --vault-name $VAULT_NAME --name $ENCRYPTION_KEY_NAME
+    # Downloads PEM encryption public key
+
+HTTP Request Signature
+----------------------
+
+As the Azure CLI (``az keyvault ...``) does not currently support signing/verifying, it is required to use the `corresponding REST API <https://docs.microsoft.com/en-us/rest/api/keyvault/sign/sign>`_ instead. To do so, it is necessary to create a service principal that will be used for authentication:
+
+.. code-block:: bash
+
+    $ export SP_NAME="<sp-name>"
+    $ az ad sp create-for-rbac --name $SP_NAME
+    # Returns client id (appId), client secret (password)
+
+.. note:: To retrieve the service principal credentials after its creation, the credentials should be refreshed:
+
+    .. code-block:: bash
+
+        $ az ad sp credential reset --name <app_id>
+        # Returns client id (appId), updated client secret (password)
+
+Once created, the service principal should be given access to Key Vault in Azure. This can be done through the Azure Portal, under the "Access policies" setting of the vault. The service principal should be given access to the vault with "Sign" key permission. See `here <https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy-portal>`_ for more details.
+
+Then, the following command should be run to retrieve an access token, replacing the values for ``<appid>``, ``<password>`` and ``<tenant>`` with the service principal credentials:
+
+.. code-block:: bash
+
+    export AZ_TOKEN=$(curl -X POST -d "grant_type=client_credentials&client_id=<appid>&client_secret=<password>&resource=https://vault.azure.net" https://login.microsoftonline.com/<tenant>/oauth2/token | jq -r .access_token)
+
+The member's identity key is now ready to be used for signing HTTP requests. The ``scurl.sh`` script can be used with the ``--print-digest-to-sign`` option to print the SHA384 to be signed as well as the required headers for HTTP signatures (following the scheme described `here <https://tools.ietf.org/html/draft-cavage-http-signatures-12>`_):
+
+.. code-block:: bash
+
+    # First, retrieve the hash to be signed
+    $ scurl.sh https://<ccf-node-address>/gov/<endpoint> -X [GET|POST] --cert $IDENTITY_CERT_NAME.pem --print-digest-to-sign
+    Hash to sign: <hash_to_sign> # To be signed by AKV
+    Request headers:
+    -H 'Digest: SHA-256=...'
+    -H 'Authorization: Signature keyId="...",signature_algorithm="hs2019",headers="(request-target) digest content-length",signature="<insert_base64_signature_here>"' # Replace signature with AKV signature here
+    -H 'content-length: 0'
+
+    # Then, retrieve the kid url for the identity key
+    $ export IDENTITY_AKV_KID=$(az keyvault key show --vault-name $VAULT_NAME --name $IDENTITY_CERT_NAME --query key.kid --output tsv)
+
+    # Then, sign the request hash to be signed (as output by scurl.sh --print-digest-to-sign)
+    $ export base64url_signature=$(curl -s -X POST $IDENTITY_AKV_KID/sign?api-version=7.1 --data '{alg: "ES384", "value": "<hash_to_sign>"}' -H "Authorization: Bearer ${AZ_TOKEN}" -H "Content-Type: application/json" | jq -r .value)
+
+.. note:: The signatures returned by AKV are returned as a `JWS signature <https://tools.ietf.org/html/rfc7518#section-3.4>`_ and encoded in `base64url <https://tools.ietf.org/html/rfc4648#section-5>`_ format and are not directly compatible with the signatures supported by CCF.
+
+The `jws_to_der.py <https://github.com/microsoft/CCF/blob/master/doc/members/jws_to_der.py>`_ Python script can be used to convert a JWS signature generated by AKV to a DER signature compatible with CCF:
+
+.. code-block:: bash
+
+    $ pip install pyasn1
+    $ export ccf_signature=$(python3.8 jws_to_der.py $base64url_signature)
+
+Finally, the signed HTTP request can be issued, using the request headers printed by ``scurl.sh --print-digest-to-sign``:
+
+.. code-block:: bash
+
+    $ curl https://<ccf-node-address>/gov/<endpoint> -X [GET|POST] --cert $IDENTITY_CERT_NAME.pem \
+    -H 'Digest: SHA-256=...' \
+    -H 'Authorization: Signature keyId="...",signature_algorithm="hs2019",headers="(request-target) digest content-length",signature="$ccf_signature"' \
+    -H 'content-length: <content-length>'
+
+Recovery Share Decryption
+-------------------------
+
+To retrieve their encrypted recovery share, a member should issue a signed HTTP request against the ``/gov/recovery_share`` endpoint (see :ref:`members/accept_recovery:Submitting Recovery Shares`). Signing the request will allow the member to authenticate themself to CCF (see :ref:`members/hsm_keys:HTTP Request Signature`).
+
+The retrieved encrypted recovery share can be decrypted with the encryption key stored in Key Vault:
+
+.. code-block::
+
+    $ az keyvault key decrypt --vault-name $VAULT_NAME --name $ENCRYPTION_KEY_NAME --algorithm RSA-OAEP-256 --value <base64_encrypted_share>
+    # Outputs base64 decrypted share
+
+The decrypted recovery share can then be submitted to the CCF recovered service (see :ref:`members/accept_recovery:Submitting Recovery Shares`).
diff --git a/doc/members/index.rst b/doc/members/index.rst
@@ -15,6 +15,7 @@ Before creating a new CCF network, the identity of the initial member(s) of the
     accept_recovery
     common_member_operations
     adding_member
+    hsm_keys
     member_rpc_api
 
 
diff --git a/doc/members/jws_to_der.py b/doc/members/jws_to_der.py
@@ -0,0 +1,31 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the Apache 2.0 License.
+import sys
+
+from pyasn1.type.namedtype import NamedTypes, NamedType
+from pyasn1.type.univ import Integer, Sequence
+from pyasn1.codec.der.encoder import encode
+import base64
+
+
+class DERSignature(Sequence):
+    componentType = NamedTypes(
+        NamedType("r", Integer()),
+        NamedType("s", Integer()),
+    )
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Error: base64url signature should be specified as first argument")
+        sys.exit(1)
+
+    jws_raw = base64.urlsafe_b64decode(sys.argv[1])
+    jws_raw_len = len(jws_raw)
+
+    sig = DERSignature()
+    sig["r"] = int.from_bytes(jws_raw[: int(jws_raw_len / 2)], byteorder="big")
+    sig["s"] = int.from_bytes(jws_raw[-int(jws_raw_len / 2) :], byteorder="big")
+    output_buf = encode(sig)
+
+    print(base64.b64encode(output_buf).decode())
diff --git a/python/utils/scurl.sh b/python/utils/scurl.sh
@@ -14,6 +14,7 @@ next_is_cert=false
 
 url=$1
 command="post"
+is_print_digest_to_sign=false
 
 fwd_args=()
 for item in "$@" ; do
@@ -64,14 +65,18 @@ for item in "$@" ; do
             continue
         fi
     fi
+    if [ "$item" == "--print-digest-to-sign" ]; then
+        is_print_digest_to_sign=true
+        continue
+    fi
     fwd_args+=("$item")
 done
 
 if [ -z "$cert" ]; then
     echo "Error: No certificate found in arguments (--cert)"
     exit 1
 fi
-if [ -z "$privk" ]; then
+if [ -z "$privk" ] && [ "$is_print_digest_to_sign" == false ]; then
     echo "Error: No private key found in arguments (--key)"
     exit 1
 fi
@@ -108,12 +113,22 @@ content-length: $content_length"
 # https://tools.ietf.org/html/draft-cavage-http-signatures-12#appendix-E.2
 signature_algorithm="hs2019"
 
-# Compute signature
-signed_raw=$(echo -n "$string_to_sign" | openssl dgst -sha384 -sign "$privk" | openssl base64 -A)
-
 # Compute key ID
 key_id=$(openssl dgst -sha256 "$cert" | cut -d ' ' -f 2)
 
+if [ "$is_print_digest_to_sign" == true ]; then
+    hash_to_sign=$(echo -n "$string_to_sign" | openssl dgst -binary -sha384 | openssl base64 -A)
+    echo "Hash to sign: $hash_to_sign"
+    echo "Request headers:"
+    echo "-H 'Digest: SHA-256=$req_digest'"
+    echo "-H 'Authorization: Signature keyId=\"$key_id\",signature_algorithm=\"$signature_algorithm\",headers=\"(request-target) digest content-length\",signature=\"<insert_base64_signature_here>\"'"
+    echo "${additional_curl_args[@]}"
+    exit 0
+fi
+
+# Compute signature
+signed_raw=$(echo -n "$string_to_sign" | openssl dgst -sha384 -sign "$privk" | openssl base64 -A)
+
 curl \
 -H "Digest: SHA-256=$req_digest" \
 -H "Authorization: Signature keyId=\"$key_id\",signature_algorithm=\"$signature_algorithm\",headers=\"(request-target) digest content-length\",signature=\"$signed_raw\"" \
