diff --git a/pvattest/man/pvattest-create.1 b/pvattest/man/pvattest-create.1 index 915fa68d..4de543eb 100644 --- a/pvattest/man/pvattest-create.1 +++ b/pvattest/man/pvattest-create.1 @@ -9,16 +9,22 @@ \fBpvattest [OPTION?] create [OPTIONS] \fP- create an attestation measurement request \fB .SH DESCRIPTION -Prepare attestation measurement requests for an IBM Secure Execution guest. Only prepare attestation requests in a trusted environment, such as your workstation. The 'pvattest create' command creates a randomly generated key to protect the attestation request. This key is only valid for this specific request.In order to avoid compromising the attestation, do not publish the protection key and delete it after verification. Every 'create' command generates a new, random protection key. +Prepare attestation measurement requests for an IBM Secure Execution guest. +Only prepare attestation requests in a trusted environment, such as your workstation. +The 'pvattest create' command creates a randomly generated key to protect the attestation request. +This key is only valid for this specific request. In order to avoid compromising the attestation, +do not publish the protection key and delete it after verification. +Every 'create' command generates a new, random protection key. .SH OPTIONS .TP .B \fB-h\fP, \fB--help\fP -Show help options +Prints usage information, then exits. .TP .B \fB-k\fP, \fB--host-key-document\fP=\fBFILE\fP -Specify one or more host key documents. +Specify one or more host key documents. At least one is required. +Specify this option multiple times to enable the image to run on more than one host. .TP .B \fB-C\fP, \fB--cert\fP=\fBFILE\fP @@ -26,11 +32,14 @@ Specifies the certificate that is used to establish a chain of trust for the v .TP .B \fB--crl\fP=\fBFILE\fP -Specify \fBFILE\fP to be a certificate revocation list (optional). +Specifies the revocation list that is used to check whether a certificate of the chain of trust is +revoked. Specify this option multiple times to use multiple CRLs (optional). .TP .B \fB--root-ca\fP=\fBFILE\fP -Use \fBFILE\fP as the trusted root CA instead the root CAs that are installed on the system (optional). +Specifies the root CA certificate for the verification. If omitted, +the system wide root CAs installed on the system are used. Use +this only if you trust the specified certificate. Optional. .TP .B \fB-o\fP, \fB--output\fP=\fBFILE\fP @@ -42,15 +51,16 @@ Save the protection key as GCM-AES256 key in \fBFILE\fP Do not publish this key, .TP .B \fB--no-verify\fP -Disable the host-key-document verification. Does not require the host-key documents to be valid. For testing purposes, do not use for a production image. (Optional) +Disable the host-key document verification. Does not require the host-key documents to be valid. Do +not use for a production request unless you verified the host-key document before (optional). .TP .B \fB--offline\fP -Don't download CRLs (optional). +Specifies offline mode, in which no attempt is made to download CRLs. (optional). .TP .B \fB-V\fP, \fB--verbose\fP -Provide more detailed output (optional) +Provide more detailed output (optional). .SH EXAMPLE Create an attestation request with the protection key 'arp.key', write the request to 'arcb.bin', and verify the host-key document using the CA-signed key 'DigiCertCA.crt' and the intermediate key 'IbmSigningKey.crt'. .PP diff --git a/pvattest/man/pvattest-perform.1 b/pvattest/man/pvattest-perform.1 index 1e50d1d5..d3ed7926 100644 --- a/pvattest/man/pvattest-perform.1 +++ b/pvattest/man/pvattest-perform.1 @@ -9,7 +9,10 @@ \fBpvattest [OPTION?] perform [OPTIONS] \fP- execute an attestation measurement request \fB .SH DESCRIPTION -Run a measurement of this system using '/dev/uv'. Works only if this device is available and the attestation Ultravisor facility is present. The input must be an attestation request created with 'pvattest create'. Output will contain the original request, the attestation measurement result, the configuration UID, and if requested in the request Additional Data. +Run a measurement of this system using '/dev/uv'. Works only if this device is +available and the attestation Ultravisor facility is present. +The input must be an attestation request created with 'pvattest create'. +Output will contain the original request and the response from the Ultravisor. .RE .PP diff --git a/pvattest/src/argparse.c b/pvattest/src/argparse.c index 93b64ab5..06bf90f8 100644 --- a/pvattest/src/argparse.c +++ b/pvattest/src/argparse.c @@ -156,76 +156,75 @@ static gboolean hex_str_toull(const char *nptr, uint64_t *dst, GError **error) /************************* SHARED OPTIONS *************************************/ /* NOTE REQUIRED */ -#define _entry_host_key_document(__arg_data, __indent) \ - { \ - .long_name = "host-key-document", .short_name = 'k', .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ - .description = "Specify one or more host key documents.\n", \ - .arg_description = "FILE", \ +#define _entry_host_key_document(__arg_data, __indent) \ + { \ + .long_name = "host-key-document", .short_name = 'k', .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ + .description = \ + "FILE specifies a host-key document. At least one is required.\n" __indent \ + "Specify this option multiple times to enable the request for\n" __indent \ + "more than one host.\n", \ + .arg_description = "FILE", \ } /* NOTE REQUIRED */ -#define _entry_certs(__arg_data, __indent) \ - { \ - .long_name = "cert", .short_name = 'C', .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ - .description = \ - "Specifies the certificate that is used to establish a chain\n" __indent \ - "of trust for the verification of the host-key documents. Specify\n" __indent \ - "this option twice to specify the IBM Z signing key and the\n" __indent \ - "intermediate CA certificate (signed by the root CA). Required.\n" __indent \ - "Ignored when --no-verify is specified.\n", \ - .arg_description = "FILE", \ +#define _entry_certs(__arg_data, __indent) \ + { \ + .long_name = "cert", .short_name = 'C', .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ + .description = "FILE contains a certificate that is used to\n" __indent \ + "establish a chain of trust for the verification\n" __indent \ + "of the host-key documents. The IBM Z signing\n" __indent \ + "key and intermediate CA certificate (signed\n" __indent \ + "by the root CA) are required.\n", \ + .arg_description = "FILE", \ } /* NOTE REQUIRED */ -#define _entry_crls(__arg_data, __indent) \ - { \ - .long_name = "crl", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ - .description = "Specify FILE to be a certificate revocation list\n" __indent \ - "(optional).", \ - .arg_description = "FILE", \ +#define _entry_crls(__arg_data, __indent) \ + { \ + .long_name = "crl", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ + .description = "FILE contains a certificate revocation list (optional).\n", \ + .arg_description = "FILE", \ } /* NOTE REQUIRED */ -#define _entry_root_ca(__arg_data, __indent) \ - { \ - .long_name = "root-ca", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ - .description = "Use FILE as the trusted root CA instead the\n" __indent \ - "root CAs that are installed on the system (optional).", \ - .arg_description = "FILE", \ +#define _entry_root_ca(__arg_data, __indent) \ + { \ + .long_name = "root-ca", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_FILENAME_ARRAY, .arg_data = __arg_data, \ + .description = "Use FILE as the trusted root CA instead the\n" __indent \ + "root CAs that are installed on the system (optional).\n", \ + .arg_description = "FILE", \ } /* NOTE REQUIRED */ -#define _entry_guest_hdr(__arg_data, __indent) \ - { \ - .long_name = "hdr", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_FILENAME, .arg_data = __arg_data, \ - .description = \ - "Specify the header of the guest image. Exactly one is required.\n", \ - .arg_description = "FILE", \ +#define _entry_guest_hdr(__arg_data, __indent) \ + { \ + .long_name = "hdr", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_FILENAME, .arg_data = __arg_data, \ + .description = "FILE specifies the header of the guest image.\n" __indent \ + "Exactly one is required.\n", \ + .arg_description = "FILE", \ } /* NOTE REQUIRED */ -#define _entry_input(__arg_data, __additional_text, __indent) \ - { \ - .long_name = "input", .short_name = 'i', .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_FILENAME, .arg_data = __arg_data, \ - .description = "FILE specifies the " __additional_text "\n" __indent \ - " as input.\n", \ - .arg_description = "FILE", \ +#define _entry_input(__arg_data, __additional_text, __indent) \ + { \ + .long_name = "input", .short_name = 'i', .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_FILENAME, .arg_data = __arg_data, \ + .description = "FILE specifies the " __additional_text " as input.\n", \ + .arg_description = "FILE", \ } /* NOTE REQUIRED */ -#define _entry_output(__arg_data, __additional_text, __indent) \ - { \ - .long_name = "output", .short_name = 'o', .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_FILENAME, .arg_data = __arg_data, \ - .description = "FILE specifies the output for the\n" __indent __additional_text \ - ".\n", \ - .arg_description = "FILE", \ +#define _entry_output(__arg_data, __additional_text, __indent) \ + { \ + .long_name = "output", .short_name = 'o', .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_FILENAME, .arg_data = __arg_data, \ + .description = "FILE specifies the output for the " __additional_text "\n", \ + .arg_description = "FILE", \ } /* NOTE REQUIRED */ @@ -254,7 +253,7 @@ static gboolean hex_str_toull(const char *nptr, uint64_t *dst, GError **error) { \ .long_name = "x-phkh-img", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ .arg = G_OPTION_ARG_NONE, .arg_data = __arg_data, \ - .description = "add the public host key hash of the\n" __indent \ + .description = "Add the public host key hash of the\n" __indent \ "image header used to decrypt\n" __indent \ "the secure guest to the measurement. (optional)\n" \ } @@ -263,34 +262,31 @@ static gboolean hex_str_toull(const char *nptr, uint64_t *dst, GError **error) { \ .long_name = "x-phkh-att", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ .arg = G_OPTION_ARG_NONE, .arg_data = __arg_data, \ - .description = "add the public host key hash of the\n" __indent \ + .description = "Add the public host key hash of the\n" __indent \ "attestation header used to decrypt\n" __indent \ "the attestation request to the measurement. (optional)\n" \ } -#define _entry_no_verify(__arg_data, __indent) \ - { \ - .long_name = "no-verify", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ - .arg = G_OPTION_ARG_NONE, .arg_data = __arg_data, \ - .description = \ - "Disable the host-key-document verification.\n" __indent \ - "Does not require the host-key documents to be valid.\n" __indent \ - "For testing purposes, do not use for a production image.\n" __indent \ - "(optional)\n", \ +#define _entry_no_verify(__arg_data, __indent) \ + { \ + .long_name = "no-verify", .short_name = 0, .flags = G_OPTION_FLAG_NONE, \ + .arg = G_OPTION_ARG_NONE, .arg_data = __arg_data, \ + .description = "Disable the host-key document verification.\n" __indent \ + "(optional)\n", \ } #define _entry_offline_maps_to_online(__arg_data, __indent) \ { \ .long_name = "offline", .short_name = 0, .flags = G_OPTION_FLAG_REVERSE, \ .arg = G_OPTION_ARG_NONE, .arg_data = __arg_data, \ - .description = "Don't download CRLs (optional).\n", \ + .description = "Don't download CRLs. (optional)\n", \ } #define _entry_verbose(__indent) \ { \ .long_name = "verbose", .short_name = 'V', .flags = G_OPTION_FLAG_NO_ARG, \ .arg = G_OPTION_ARG_CALLBACK, .arg_data = &increase_log_lvl, \ - .description = "Provide more detailed output (optional)\n", \ + .description = "Provide more detailed output. (optional)\n", \ .arg_description = NULL, \ }