Proving the origin of an add-secret request to the secure guest

Edit online

Use the --user-sign-key option of the pvsecret create command to sign an add-secret request.

Before you begin

You require a certificate and its corresponding private key. Supported key types are:
  • RSA, 2048- or 3072-bit. Due to the size restriction of maximum 512 bytes for the signature and user data, larger key sizes are not supported.
  • Elliptic Curve Digital Signature Algorithm (ECDSA) with secp521r1 curve (NIST P521)
To specify your private key, use a PEM or DER format.

About this task

A generic secure guest must only accept secrets from the owner to whom its ownership has been transferred. Here it is assumed that the owner is represented by a certificate linked to a private key known only to the guest's owner. For the guest to verify ownership of an add-secret request, the request must be signed by the owner's key, and the guest must have access to the owner's certificate.

To achieve this, use the --user-sign-key option of the pvsecret create command to sign an add-secret request. Within the secure guest, use the pvsecret verify command to validate the signature of the add-secret request before submitting it to the ultravisor.

Additionally, you can pass arbitrary user-key-signed and request-TAG verified user data to the secure-execution guest. The use of such data is at your discretion; other than the size restrictions of 128-512 bytes depending on the signing key, there is no limit in usage.

Procedure

  1. On a trusted system, add the extension secret to the pvsecret create command.
    Specify a command of the following form:
    [trusted]# pvsecret create association -k <host_key_document> --se-hdr <SEL_header> 
-o <request_file> -C <CA_certificate> -C <IBM_signing_certificate> 
--user-sign-key <user_key_file>  <name>
    where:
    • association specifies that the add-secret request is for an association secret.
    • -k <host_key_document> specifies the host key document.
    • --hdr <SEL_header> specifies the header of the KVM guest.
    • -o <request_file> specifies the file that contains the generated add-secret request.
    • -C <CA_certificate> specifies the certificate that is used to establish a chain of trust for the verification of the host key documents. Specify this option twice to specify the IBM Z signing-key certificate and the intermediate CA certificate (signed by the root CA).
    • --user-sign-key <user_key_file> uses the content of the specified file as the user-signing key. Adds a signature calculated from the key in the file to the add-secret request.
    • <name> A string that identifies the new secret. Strings are hashed with SHA-256 to form the ID that is used by the ultravisor. The ID is saved in <name>.yaml with white-spaces mapped to underscores ( _ ).
    For example, to use:
    • a host-key document z16.crt
    • a guest header se.hdr
    • a CA certificate DigiCert.crt
    • an IBM signing key ibm-sign.crt
    • a user-signing key myPrivateKey.pem
    and let the command create a random association secret that is named myConfidentialSecret, issue the following command on a trusted system on one line:
    [trusted]# pvsecret create association -k z16.crt --hdr se.hdr -o addSecretReq 
-C DigiCertCA.crt -C ibm-sign.crt 
--user-sign-key myPrivateKey.pem "myConfidentialSecret"
    Optionally, you can add user data from a file by specifying --user-data <FILE>. The maximum size of the user data depends on the signing key that is used. The data can be up to 512 bytes for no user-key, and as little as 128 bytes for an RSA 3072-bit key. For example:
    [trusted]# pvsecret create -k z16.crt --hdr se.hdr -o addSecretReq 
-C DigiCertCA.crt -C ibm-sign.crt 
--user-sign-key myPrivateKey.pem --user-data user_data association "myConfidentialSecret"
    The command generates a new association secret with a random secret and the hash value of myConfidentialSecret as secret identifier. The add-secret request is signed with your user-defined private key myPrivateKey.pem. The command writes the ID to myConfidentialSecret.yaml and the encrypted add-secret request to addSecretReq.
  2. Verify that the request was signed with the guest owner's private key.
    A Secure Execution guest in possession of the guest owner's certificate can use the pvsecret verify command to verify that the request was signed with the guest owner's private key.

    This verification process should be conducted solely within the secure-execution guest. Only upon successful verification, submit the secret to the ultravisor using pvsecret add.

    For example, to verify that the request addSecretReq was signed with the private key that corresponds to the certificate myCert.pem, issue: 
    [secguest]# pvsecret verify --user-cert myCert.pem -o user_data_out addSecretReq
    where:
    • --user-cert myCert.pem specifies a public key in PEM or DER format to verify the user-data signature.
    • -o user_data_out stores the result in user_data_out. If the request contains arbitrary user data, the output includes this data with padded zeros.
    • addSecretReq is the request to be verified.
    If you specified any user data, that user data is part of the output after successful verification. The previous example saves it in user_data_out. By default, the user data is printed to stdout.

What to do next

If the verification fails, the guest must discard the add-secret request. Subsequently, depending on the application, the user data in stdout or user_data_out requires processing.

If neither the verification of the add-secret request fails nor the processing of the user data results in rejection of the add-secret request, then the add-secret request may be submitted to the ultravisor.