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>
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-05-20" "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)
|