Verifying the host key document

To ensure that the host key document is genuine and provided by IBM®, you need to verify the document manually.

Before you begin

To verify the host key document you need:

The host key document that you received from your cloud provider, HKD-<mmmm-nnnn>.crt, or downloaded from Resource Link®, see Obtaining a host key document from Resource Link.
The DigiCert CA certificate, DigiCertCA.crt
The IBM Z signing-key certificate, ibm-z-host-key-signing.crt
The certificate revocation list (CRL), ibm-z-host-key.crl

You can download the CA certificate, the signing-key certificate, and the CRL from IBM Resource Link:

For IBM z15:

https://www.ibm.com/support/resourcelink/api/content/public/secure-execution-gen1.html

For IBM z16:

https://www.ibm.com/support/resourcelink/api/content/public/secure-execution-gen2.html

Check the genprotimg man for the latest updates to the verification procedure.

About this task

The procedure assumes an Internet connection. The commands download CRLs. For information about working offline, see the OpenSSL documentation.

Tip: Use the sample script available from s390-tools to perform the verification steps:

https://github.com/ibm-s390-tools/s390-tools/tree/master/genprotimg/samples/check_hostkeydoc

Procedure

Verify the CA certificate with the following command:

# openssl verify -crl_download -crl_check DigicertCA.crt

Verify the IBM Z signing-key certificate with the following command:

# openssl verify -crl_download -crl_check -untrusted DigicertCA.crt ibm-z-host-key-signing.crt

Verify the signature of the host key document:
1. Extract the public signing key into a file.
  In this example the file is called pubkey.pem:
```
# openssl x509 -in ibm-z-host-key-signing.crt -pubkey -noout > pubkey.pem
```
2. Extract the host key signature from the host key document.
  The following command returns the offset value <n> of the signature:
```
# openssl asn1parse -in HKD-<mmmm-nnnn>.crt | tail -1 | cut -d : -f 1
```
  Use the resulting value <n> to extract the host key signature into a file called signature:
```
# openssl asn1parse -in HKD-<mmmm-nnnn>.crt -out signature -strparse <n> -noout
```
3. Extract the host key document body into a file called body:
```
# openssl asn1parse -in HKD-<mmmm-nnnn>.crt -out body -strparse 4 -noout
```
4. Verify the signature using the signature and body files:
```
# openssl sha512 -verify pubkey.pem -signature signature body
```
Verify the host key document issuer.
Compare the outputs of the following two commands:
```
# openssl x509 -in HKD-<mmmm-nnnn>.crt -issuer -noout
```
```
# openssl x509 -in ibm-z-host-key-signing.crt -subject -noout
```
The order of the arguments and options might differ, but it is important that all elements are present and their values are the same.
Verify that the host key document is still valid by checking the output of the following command:
```
# openssl x509 -in ibm-z-host-key-signing.crt -dates -noout
```
Verify that the host key has not been revoked.
1. Verify the signature of the CRL file. Follow the steps described in 3, but replace HKD-<mmmm-nnnn>.crt with ibm-z-host-key.crl.
2. Verify the CRL issuer. Follow the steps described in 4, but use the following command to find the CRL issuer:
```
# openssl crl -in ibm-z-host-key.crl -issuer -noout
```
3. Verify that the revocation list is still valid by checking the output of the following command:
```
# openssl crl -in ibm-z-host-key.crl -lastupdate -nextupdate -noout
```
4. Check whether the serial number of the host key is contained in the CRL.
  To find the serial number of all revoked host keys, use the following command:
```
# openssl crl -in ibm-z-host-key.crl -text -noout | grep "Serial Number"
```
  To obtain the serial number of the host key document, use the following command:
```
# openssl x509  -in HKD-<mmmm-nnnn>.crt  -serial -noout
```
  If the host key serial number is contained in the CRL, do not use this host key document.