mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
Marc Hartmayer
238ca83b99
Update pvattest and pvsecret mapnages and README.md, as for example the 'pvsecret create update-cck' was not documented. Reviewed-by: Steffen Eiden <seiden@linux.ibm.com> Signed-off-by: Marc Hartmayer <marc@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
110 lines
3.9 KiB
Groff
110 lines
3.9 KiB
Groff
.\" Copyright 2024, 2025 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-RETRIEVABLE" "1" "2026-02-12" "s390-tools" "UV\-Secret Manual"
|
|
.nh
|
|
.ad l
|
|
.SH NAME
|
|
pvsecret-create-retrievable \- Create a retrievable secret
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.fam C
|
|
pvsecret create retrievable [OPTIONS] \-\-secret <SECRET\-FILE> \-\-type <TYPE> <NAME>
|
|
pvsecret create retr [OPTIONS] \-\-secret <SECRET\-FILE> \-\-type <TYPE> <NAME>
|
|
.fam C
|
|
.fi
|
|
.SH DESCRIPTION
|
|
A retrievable secret is stored in the per\-guest storage of the Ultravisor. A
|
|
SE\-guest can retrieve the secret at runtime and use it. All retrievable
|
|
secrets, but the plaintext secret, are retrieved as wrapped/protected key
|
|
objects and only usable inside the current, running SE\-guest instance. The
|
|
input file may contain up to 8190 bytes for the plaintext secret. For the
|
|
symmetric keys (AES, AES\-XTS, HMAC) the file must contain a byte pattern for
|
|
the key with the key\-size as file size. For the EC private keys the file must
|
|
be either in PEM or DER format and contain an \fBEC PRIVATE KEY\fP with one of
|
|
the following curves: secp256r1, secp384r1, secp521r1, ed25519, or ed448.
|
|
.PP
|
|
\fBHMAC\-SHA preprocessing\fP
|
|
|
|
.RS 2
|
|
The \fBHMAC\-SHA\fP key supplied in the plain bytes file is the key \fBK_0\fP
|
|
as of \fBFIPS\-198\-1\fP, i.e. the key \fBK\fP after any necessary
|
|
pre\-processing. The pre\-processing must be performed by the user prior to
|
|
creating the retrievable secret.
|
|
.PP Pre\-processing means that if the key \fBK\fP is shorter than the block
|
|
size of the to\-be\-used HMAC digest, then the key must be padded with binary
|
|
zeros to the right up to the block size. The block size of SHA\-224 and
|
|
SHA\-256 is 512 bits (64 bytes) and the bock size of SHA\-384 and SHA\-512 is
|
|
1024 bits (128 bytes). Such padding can for example be achieved by using the
|
|
\fBtruncate\fP command with the desired size in bytes, e.g. \fB'truncate
|
|
\-\-size 64 <key\-file>'\fP for creating a \fBK_0\fP key for HMAC\-SHA\-224
|
|
and HMAC\-SHA\-256.
|
|
.PP
|
|
In case key \fBK\fP is longer than the block size of the to\-be\-used HMAC
|
|
digest, then key \fBK\fP must first be hashed with the to\-be\-used HMAC
|
|
digest, and the result must then be padded with binary zeros to the right up to
|
|
the block size of the digest. This can be achieved by using the following
|
|
OpenSSL command followed by the \fBtruncate\fP command: \fB'openssl sha256
|
|
\-binary \-out <key2\-file> <key\-file>'\fP and then \fB'truncate \-\-size
|
|
64 <key2\-file>'\fP for creating a \fBK_0\fP key for HMAC\-SHA\-256.
|
|
.PP
|
|
\fBATTENTION:\fP The digest used for hashing the key \fBK\fP must be the exact
|
|
same as the later to\-be\-used HMAC digest! If the pre\-processing and the
|
|
HMAC calculation use different digests, then a wrong MAC is calculated!
|
|
.RE
|
|
|
|
.SH OPTIONS
|
|
.PP
|
|
<NAME>
|
|
.RS 4
|
|
String that identifies the new secret. The actual secret is set with
|
|
\fB\-\-secret\fR. The name is saved in `NAME.yaml` with white\-spaces mapped to
|
|
`_`.
|
|
.RE
|
|
.RE
|
|
|
|
.PP
|
|
\-\-stdout
|
|
.RS 4
|
|
Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-\-secret <SECRET\-FILE>
|
|
.RS 4
|
|
Use SECRET\-FILE as retrievable secret.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-\-type <TYPE>
|
|
.RS 4
|
|
Specify the secret type. Limitations to the input data apply depending on the
|
|
secret type.
|
|
|
|
Possible values:
|
|
.RS 4
|
|
\- \fBplain\fP: A plaintext secret. Can be any file up to 8190 bytes long.
|
|
|
|
\- \fBaes\fP: An AES key. Must be a plain byte file 128, 192, or 256 bit long.
|
|
|
|
\- \fBaes-xts\fP: An AES-XTS key. Must be a plain byte file 256, or 512 bit long.
|
|
|
|
\- \fBhmac-sha\fP: A HMAC-SHA key. Must be a plain byte file 512, or 1024 bit long. Special care is required when creating HMAC-SHA keys. For more Information refer to the DESCRIPTION section of the man file.
|
|
|
|
\- \fBec\fP: An elliptic curve private key. Must be a PEM or DER file.
|
|
|
|
.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\fR(1)
|