Using a given secret

Edit online

You can use a given secret instead of a random secret for the association.

Non-random secrets are:

Necessary when an existing secret needs to be reused.
A practical choice for testing scenarios.
Under your control. If you want to control the secret for any reason, such as not trusting the available random generator, you can use a non-random secret.

Procedure

On a trusted Linux instance, issue a pvsecret create command to create the request for adding a given association secret. The request is written to a file that you specify.
Specify a command of the following form:
```
[trusted]# pvsecret create association -k <host_key_doc> --hdr <SEL_header> -o <request_file> 
--crt <CA_certificate> --crt <IBM_signing_certificate>  <name> 
--input-secret <secret>
```
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).
- <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 ( _ ).
- --input-secret <secret> specifies the file from which to read the plaintext secret. A random secret is used if no input file is specified.
For example, to use:
- a host-key document z16.crt
- a guest header se.hdr
- an output file my_addsecreq
- a CA certificate DigiCert.crt
- an IBM signing key ibm-sign.crt
- a secret in the file my_secret.txt
issue the following command on a trusted system:
```
# pvsecret create association -k z16.crt --se-hdr se.hdr -o my_addsecreq 
--crt DigiCertCA.crt --crt ibm-sign.crt --input-secret my_secret.txt 
```
The command creates an add-secret request that contains an association secret with the name my_secret. The name is saved in my_secret.yaml with white spaces mapped to underscore (_). The request is written to my_addsecreq.
Create a pvapconfig configuration file (in YAML format) with an entry that describes your AP queue.
You need the secret ID from the .yaml file created with the pvsecret create command in the previous step, the master key verification pattern of the AP queue from the HSM domain administrator, and optionally the serial number of the Crypto Express adapter.
For example, a simple pvapconfig configuration file file can look like this:
```
- mode: EP11
  mkvp: 0xdb3c3b3c3f097dd55ec7eb0e7fdbcb93
  serialnr: 93AADFK719460083
  secretid: 0x546869732069732061207665727920736563726574207365637265742069642e
```
For details about the syntax of the pvapconfig configuration file, see pvapconfig configuration file.
Transfer the request and configuration file to the secure guest.
You can use secure copy, or a similar program.
For example:
```
[trusted]# scp my_addsecreq seguest:
[trusted]# scp my_apconfig.yaml seguest:  
```
On the KVM guest running in secure-execution mode, add the secret to the ultravisor.
Issue a command of the following form:
```
[se_guest]# pvsecret add <request_file>
```
For example, to use the add-secret request that was created in the previous steps, issue:
```
[se_guest]# pvsecret add my_addsecreq
```

Optionally list the secrets.

The pvsecret list command now displays the secret index and the secret ID.

For example:

[se_guest]# pvsecret list
Total number of secrets: 1

0 Ap-Association:

546869732069732061207665727920736563726574207365637265742069642e

After all association secrets are added, you can prevent anyone from adding more secrets. To do this issue the pvsecret lock command.
After this command, the ultravisor rejects any further add-secret requests for your secure guest.
```
[se_guest]# pvsecret lock
```
Run the pvapconfig command with your .yaml configuration file as input.
The command now checks for AP queues that are available to the secure guest and that satisfy the specifications in the configuration file. The master key verification pattern assures that your guest is not presented with a tampered AP queue.
For example:
```
[se_guest]# pvapconfig my_apconfig.yaml
```
For details about the pvapconfig command, see pvapconfig - Implement an AP queue configuration.