mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
Finn Callies
c803cb925e
Add two new command-line options to pvsecret create for Early Boot
Customization (EBC) Table of Contents (TOC) support:
1. --policy FILE
Links an Add-Secret-Request (ASR) to a policy file by embedding a
PolicyReference in the ASR's user data field. The PolicyReference
contains the relative file path and SHA512 hash of the policy file,
enabling integrity verification of the policy. This option conflicts
with --user-data as both use the same user data field in the ASR
structure.
2. --toc-policy FILE
Appends the AES-GCM authentication tag (MAC tag - last 16 bytes of
the encrypted ASR) to the specified TOC policy file. This enables
the TOC policy to maintain a list of all ASR MAC tags for
completeness verification during boot. The TOC can verify that all
expected ASRs are present and unmodified by checking their MAC tags
against this list. This option also conflicts with --user-data.
Both options support the EBC multi-party workflow where an ISV/CSP builds
a generic SEL image and customers customize it with their own secrets. The
TOC mechanism ensures the integrity and completeness of all EBC resources
during the boot process.
Assisted-by: IBM Bob:1.0.1
Acked-by: Holger Dengler <dengler@linux.ibm.com>
Reviewed-by: Steffen Eiden <seiden@linux.ibm.com>
Signed-off-by: Finn Callies <fcallies@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
247 lines
7.3 KiB
Groff
247 lines
7.3 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-02-12" "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 to a policy file.
|
||
This option embeds a reference to a policy in the add\-secret request user data field. The
|
||
reference includes the relative file path and the SHA-512 hash of the
|
||
policy file, enabling verification of the policy file’s integrity.
|
||
This option conflicts with \fB\-\-user\-data\fR, because both options use the
|
||
same user data field in the add\-secret request structure.
|
||
.RE
|
||
.RE
|
||
.PP
|
||
\-\-toc\-policy <FILE>
|
||
.RS 4
|
||
Adds the AES\-GCM authentication tag to a table-of-contents (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 add\-secret request MAC tags for
|
||
completeness verification during boot. During verification, the TOC checks the
|
||
AES\-GCM tags against this list to ensure that all expected add\-secret request 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)
|