mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
a8a3e7d49c
Acked-by: Marc Hartmayer <marc@linux.ibm.com> Reviewed-by: Christoph Schlameuss <schlameuss@linux.ibm.com> Signed-off-by: Steffen Eiden <seiden@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
218 lines
6.2 KiB
Groff
218 lines
6.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" "2024-12-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
|
|
|
|
.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
|
|
\-\-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)
|