s390-tools/rust/pvsecret/man/pvsecret-create.1

.\" Copyright 2023 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"

.TH pvsecret-create 1 "2024-01-30" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
\fBpvsecret create\fP - Create a new add-secret request
\fB
.SH SYNOPSIS
.nf
.fam C
pvsecret create [OPTIONS] --host-key-document <FILE> --hdr <FILE> --output <FILE> <--no-verify|--cert <FILE>> <COMMAND>
.fam C
.fi
.SH DESCRIPTION
Create add-secret requests for IBM Secure Execution guests. Only create these
requests in a trusted environment, such as your workstation. The \fBpvattest
create\fR command creates a randomly generated key to protect the request. The
generated requests can then be added on an IBM Secure Execution guest using
\fBpvsecret add\fR. The guest can then use the secrets with the use case
depending on the secret type.
Such a request is bound to a specific IBM Secure Execution image specified with
\fB--hdr\fR. Optionally, the request can be bound to a specific instance when
bound to the Configuration Unique ID from \fBpvattest\fR using \fB--cuid\fR

.SH OPTIONS
.PP
\-k, \-\-host-key-document <FILE>
.RS 4
Use FILE as a host-key document. Can be specified multiple times and must be
used at least once.
.RE
.RE
.PP
\-\-no-verify
.RS 4
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 beforehand.
.RE
.RE
.PP
\-C, \-\-cert <FILE>
.RS 4
Use FILE as a certificate to verify the host key or keys. The certificates are
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 and the
intermediate CA certificate (signed by the root CA).
.RE
.RE
.PP
\-\-crl <FILE>
.RS 4
Use FILE as a certificate revocation list. The list is used to check whether a
certificate of the chain of trust is revoked. Specify this option multiple times
to use multiple CRLs.
.RE
.RE
.PP
\-\-offline
.RS 4
Make no attempt to download CRLs.
.RE
.RE
.PP
\-\-root-ca <ROOT_CA>
.RS 4
Use FILE as 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.
.RE
.RE
.PP
\-\-hdr <FILE>
.RS 4
Specifies the header of the guest image. Can be an IBM Secure Execution image
created by genprotimg or an extracted IBM Secure Execution header. The header
must start at a page boundary.
.RE
.RE
.PP
\-f, \-\-force
.RS 4
Force the generation of add-secret requests on IBM Secure Execution guests. If
the program detects that it is running on an IBM Secure Execution guest, it
denies the generation of add-secret requests. The force flag overwrites this
behavior.
.RE
.RE
.PP
\-o, \-\-output <FILE>
.RS 4
Write the generated request to FILE.
.RE
.RE
.PP
\-\-extension-secret <FILE>
.RS 4
Use the content of FILE as an extension secret. The file must be exactly 32
bytes long. If this request is the first, all subsequent requests must have the
same extension secret. Only makes sense if bit 1 of the secret control flags of
the IBM Secure Execution header is 0. Otherwise the ultravisor rejects the
request.
.RE
.RE
.PP
\-\-cck <FILE>
.RS 4
Use the content of FILE as the customer-communication key (CCK) to derive the
extension secret. The file must contain exactly 32 bytes of data. If the target
guest was started with bit 1 of the secret control flag set, the ultravisor also
derives the secret from the CCK. Otherwise, the ultravisor interprets the
extension secret as a normal one. This still works if you use the same CCK for
all requests.
.RE
.RE
.PP
\-\-cuid-hex <HEXSTRING>
.RS 4
Use HEXSTRING as the Configuration Unique ID. Must be a hex 128-bit unsigned big
endian number string. Leading zeros must be provided. If specified, the value
must match with the Config-UID from the attestation result of that guest. If not
specified, the CUID will be ignored by the ultravisor during the verification of
the request.
.RE
.RE
.PP
\-\-cuid <FILE>
.RS 4
Use the content of FILE as the Configuration Unique ID. The file must contain
exactly 128 bit of data or a yaml with a `cuid` entry. If specified, the value
must match the Config-UID from the attestation result of that guest. If not
specified, the CUID will be ignored by the Ultravisor during the verification
of the request.
.RE
.RE
.PP
\-\-flags <FLAGS>
.RS 4
Flags for the add-secret request.

Possible values:
.RS 4
- \fBdisable-dump\fP: Disables host-initiated dumping for the target guest instance.

.RE
.RE
.PP
\-\-user-data <FILE>
.RS 4
Use the content of FILE as user-data. Passes user data defined in <FILE> through
the add-secret request to the ultravisor. The user data can be up to 512 bytes
of arbitrary data, and the maximum size depends on the size of the user-signing
key:

 - No key: user data can be 512 bytes.

 - EC(secp521r1) or RSA 2048 keys: user data can be 256 bytes.

 - RSA 3072 key: user data can be 128 bytes.

The firmware ignores this data, but the request tag protects the user-data.
Optional. No user-data by default.
.RE
.RE
.PP
\-\-user-sign-key <FILE>
.RS 4
Use the content of FILE as user signing key. Adds a signature defined calculated
from the key in <FILE> to the add-secret request. The file must be in DER or PEM
format containing a private key. Supported are RSA 2048 & 3072-bit and
EC(secp521r1) keys. The firmware ignores the content, but the request tag
protects the signature. The user-signing key signs the request. The location of
the signature is filled with zeros during the signature calculation. The request
tag also secures the signature. See man pvsecret verify for more details.
Optional. No signature by default.
.RE
.RE

.SH "SEE ALSO"
.sp
\fBpvsecret\fR(1) \fBpvsecret-create-meta\fR(1) \fBpvsecret-create-association\fR(1)