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

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 3096-bit
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 up to you; other than the size restrictions of 128-512 bytes depending on the signing key, there is no limit in usage.

Procedure

On a trusted system, add the extension secret to the pvsecret create command.
Specify a command of the following form:
```
[trusted]# pvsecret create -k <host_key_document> --se-hdr <secure_exe_header> -o <request_file> \
-C <CA_certificate> -C <IBM_signing_certificate> \
--user-sign-key <user_key_file> association <string> 
```
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 association "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 3096 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.
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
```
If you specified any user data, that user data is part of the output after a successful verification. The previous example saves it at 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.