mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
Steffen Eiden
03b73ab3f9
man and README got out of sync with --help over time. Resync them. Reviewed-by: Jan Höppner <hoeppner@linux.ibm.com> Signed-off-by: Steffen Eiden <seiden@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
248 lines
7.2 KiB
Groff
248 lines
7.2 KiB
Groff
.\" Copyright 2023, 2024 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" "2026-05-19" "s390-tools" "UV\-Secret Manual"
|
||
.nh
|
||
.ad l
|
||
.SH NAME
|
||
pvsecret-create \- Create a new add-secret request
|
||
.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 "PVSECRET CREATE COMMANDS"
|
||
.PP
|
||
|
||
\fBpvsecret create\-meta(1)\fR
|
||
.RS 4
|
||
Create a meta secret
|
||
.RE
|
||
|
||
.PP
|
||
|
||
\fBpvsecret create\-association(1)\fR
|
||
.RS 4
|
||
Create an association secret
|
||
.RE
|
||
|
||
.PP
|
||
|
||
\fBpvsecret create\-retrievable(1)\fR
|
||
.RS 4
|
||
Create a retrievable secret
|
||
.RE
|
||
|
||
.PP
|
||
|
||
\fBpvsecret create\-update\-cck(1)\fR
|
||
.RS 4
|
||
Update customer communication key
|
||
.RE
|
||
|
||
.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
|
||
specified 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 (CRL). 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 \fBpvimg/genprotimg\fR or an extracted IBM Secure Execution header.
|
||
.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
|
||
\-\-policy <FILE>
|
||
.RS 4
|
||
Links an Add‑Secret\-Request (ASR) to a policy file. This option embeds a
|
||
PolicyReference in the ASR user data field. The PolicyReference includes the
|
||
relative file path and the SHA‑512 hash of the policy file, allowing the
|
||
policy’s integrity to be verified.
|
||
|
||
This option conflicts with \-\-user\-data, because both options use the same
|
||
user data field in the ASR structure.
|
||
.RE
|
||
.RE
|
||
.PP
|
||
\-\-toc\-policy <FILE>
|
||
.RS 4
|
||
Adds the AES‑GCM authentication tag to a TOC policy file. This option appends
|
||
the AES‑GCM authentication tag to the specified TOC policy file. This allows
|
||
the TOC policy to maintain a list of all ASR MAC tags for completeness
|
||
verification during boot. During verification, the TOC checks the MAC tags
|
||
against this list to ensure that all expected ASRs are present and unmodified.
|
||
.RE
|
||
.RE
|
||
.PP
|
||
\-\-user\-sign\-key <FILE>
|
||
.RS 4
|
||
Use the content of FILE as user signing key. Adds a signature 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
|
||
.PP
|
||
\-\-use\-name
|
||
.RS 4
|
||
Do not hash the name, use it directly as secret ID. Ignored for meta\-secrets.
|
||
.RE
|
||
.RE
|
||
.PP
|
||
\-h, \-\-help
|
||
.RS 4
|
||
Print help (see a summary with \fB\-h\fR).
|
||
.RE
|
||
.RE
|
||
|
||
.SH "SEE ALSO"
|
||
.sp
|
||
\fBpvsecret\fR(1) \fBpvsecret\-create\-meta\fR(1) \fBpvsecret\-create\-association\fR(1) \fBpvsecret\-create\-retrievable\fR(1) \fBpvsecret\-create\-update\-cck\fR(1)
|