Testing

Testing the support of retrievable secrets

Retrievable secrets are only available within a KVM SEL guest. For testing the support of retrievable secrets on a KVM SEL guest, certain adaptions to the previously described test environment are required.

• You must install the pvsecret utility and provide a text file with the output of the pvsecret list sub-command. See an example in How to create a protected key for libzpc programming.
• The output file name must be made available to the libzpc runtest program using the environment variable ZPC_TEST_PVSECRET_LIST_FILE:

  ZPC_TEST_PVSECRET_LIST_FILE=<list-file>

  The <list-file> must be created with the pvsecret utility as part of s390-tools version 2.37 or later. Perform a pvsecret list command and redirect the output to the list file. Testers may optionally add clear key data, used when creating ultravisor retrievable secrets, to the list file.

  Example:

  
  7 HMAC-SHA-256-KEY: 
  0xb620b6d76f89910aff90ff9 ...      <- the secret ID 
  0xa783830e0bd6f3ae8cade16b3004 ... <- the clear key
  

  For PVSECRET type full-XTS keys, there is a mixed setting of AES_XTS_KEY and AES_KEY definitions, for example:

  
  5 AES-XTS-128-KEY:
  0x8ace2a9b ... <- secret ID
  0xbe0274e3f3b363 ... <- clear AES XTS key (2 x 16 bytes)
  6 AES-XTS-256-KEY:
  0x2b56938 ... <- secret ID
  0xbf8260655f43 ... <- clear AES XTS key (2 x 32 bytes)
  

  If clear key data is available, additional tests (pvsecret_kat) are performed.

  Example:

  export ZPC_TEST_PVSECRET_LIST_FILE=pvsecret-list.out

  A path can be omitted if the file is located in the libzpc/build directory.

• The tester can optionally provide clear key values for secret IDs (retrievable secrets) by adding them manually to the output list file. This is necessary for the public part of an ECC key, because only the private part can be retrieved from the ultravisor. Typically the tester would use OpenSSL to display the key material from the KVM SEL guest setup, like shown in the following example for an ECC key:

  
  # openssl ec -in p384.key -text -noout
  read EC key
  Private-Key: (384 bit)
  priv: 
   03:4c:ce:23:50:1f:4c:d7:9a:0e:3b:bc:51:5a:82:
   0b:a6:23:0e:66:07:78:aa:a8:c7:38:c6:88:43:2e: 
   28:af:18:6c:8a:37:ae:8f:d0:2d:55:66:47:4d:07: 
   21:eb:a9
  pub: 
   04:c7:bb:58:c2:30:24:7f:de:e9:61:be:b8:fd:40: <- Remove the leading 0x04
   96:2f:e1:b3:5d:70:b4:d9:35:00:9d:e7:8e:f9:cf: 
   96:ec:d6:fe:ee:df:7f:e2:0c:59:05:23:71:36:ef:
   dc:00:d5:b0:2b:20:d0:ec:ae:d6:67:d8:4d:ab:4f: 
   90:ad:28:65:42:98:1f:b6:fa:49:80:88:b3:d8:69:
   07:46:2e:a3:ba:46:cc:7e:60:58:98:04:a4:e0:2f: 
   1a:fa:7c:03:58:74:42
  ASN1 OID: secp384r1 
  NIST CURVE: P-384 
  

  Only uncompressed public ECC keys can be added to the output list file and the leading compress indication byte 04 and all colons must be removed. The public key always comes below the secret ID, followed by the private key as shown in Figure 1.

  The clear key material is be added to the output list file like:

  
  10 EC-SECP384R1-PRIVATE-KEY:
   0xf972ce506dad11195af5e2f364723 ... <- pvsecret ID
   0xc7bb58c230247fdee961beb8fd40962fe1b35d70 ... <- public key
   0x034cce23501f4cd79a0e3bbc515a820ba6230e66077 ... <- private key
  11 EC-SECP521R1-PRIVATE-KEY
  ...
  

• Public keys from Edwards curves (ED448 and ED25519) do not have a compress indicator byte.

  
  12 EC-ED25519-PRIVATE-KEY:
   0x3d5f4f95cdb1cdfc71014efa1a669fd42599a0ce2000d914a409e48bccaed584
   0xf898c8e1ba10b2aadc787a713d70a787b40031e75a01c282195d997e1c770d47
   0x3fecd5c7cb294bd89b68a5959cc59d634f51fb6e872ccbfd05148ad89349a0b5
  13 EC-ED448-PRIVATE-KEY:
   0x40159448e5203c70a9ec00f9490ae5c7d60e00bcb1bca2ed32c8b6b1224cd45a
   0x552018d6c5983e83a33c4e4c29 ... 20f86480
   0x47ce6842c7 ...
  

  Note: The total number of secrets in the system is limited and given by /sys/firmware/uv/query/max_secrets. Therefore it is not possible to create new secrets from given clear keys to run all the NIST and Wycheproof known answer tests with hundreds of keys.
• Association and text secrets cannot be used for testing, as they do not have a related protected key.
• Secrets cannot be deleted via the pvsecret utility. When the maximum number of secrets is reached, and you want to create more secrets, reboot the KVM SEL guest to delete all secrets. After rebooting the secure guest, the number of secrets is zero and you can create new secrets again. You can check if a given secret is retrievable with the pvsecret utility:

  # pvsecret retrieve --inform hex 0x8cf9659cdea52a...19a14d8d54297ab5a01562b7b9
  -----BEGIN IBM PROTECTED KEY-----
  kind: AES-128-KEY
  uBccEN0Y5O9DN+RJN2z6SrYZrFbJjfwieXe9mrChP6gCMKLgP7Wio2vpktxWkYWs
  -----END IBM PROTECTED KEY-----
  

  Refer to the pvsecret man page for more information.

Setting environment variables

ZPC_TEST_AES_KEY_TYPE = ZPC_AES_KEY_TYPE_CCA_DATA |
                        ZPC_AES_KEY_TYPE_CCA_CIPHER |
                        ZPC_AES_KEY_TYPE_EP11 |                  
                        ZPC_AES_KEY_TYPE_PVSECRET <- new

ZPC_TEST_EC_KEY_TYPE = ZPC_EC_KEY_TYPE_CCA |
                       ZPC_EC_KEY_TYPE_EP11 |
                       ZPC_EC_KEY_TYPE_PVSECRET <- new

A typical setting for libzpc AES tests using retrievable secrets would look like follows:

export ZPC_DEBUG=0 
export ZPC_TEST_AES_KEY_TYPE=ZPC_AES_KEY_TYPE_PVSECRET 
export ZPC_TEST_AES_KEY_SIZE=128 
/* No APQN or MKVP setting, as these are not applicable for retrievable secrets.

A typical setting for libzpc ECC tests using retrievable secrets would look like follows:

export ZPC_DEBUG=0
export ZPC_TEST_EC_KEY_TYPE=ZPC_EC_KEY_TYPE_PVSECRET
export ZPC_TEST_EC_KEY_CURVE=p521 

Additionally, the ZPC_TEST_PVSECRET_LIST_FILE variable must be set as previously described. The ecdsa_ctx.pvsecret_kat test tries to compare signatures with the ones created by CCA or EP11 type keys with the same key material (clear public and private keys added to the list file). For this, a CCA or EP11 APQN must be specified for the tests. The ecdsa_ctx.pvsecret_kat test creates a second test key according to the APQN type.