kata-containers/s390-tools
1
0
Fork 0
mirror of https://github.com/ibm-s390-linux/s390-tools.git synced 2026-08-05 02:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

rust/pvsecret: Update man page for clarifying the creation of HMAC secrets

Browse Source 
The key supplied in the plain bytes file with 'pvsecret create retrievable'
with type 'hmac-sha' is they key 'K_0' as of FIPS-198-1, i.e. the key 'K'
after any necessary pre-processing. The pre-processing must be performed
by the user prior to creating the retrievable secret.

Describe in detail how that pre-processing must be performed.

Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Ingo Franzki
2025-02-28 10:58:26 +01:00
committed by Jan Höppner
parent b3055154db
commit e49569db60
3 changed files with 43 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
rust/pvsecret/README.md
View File

@@ -368,7 +368,7 @@ secret type.
- **plain**: A plaintext secret. Can be any file up to 8190 bytes long.
- **aes**: An AES key. Must be a plain byte file 128, 192, or 256 bit long.
- **aes-xts**: An AES-XTS key. Must be a plain byte file 512, or 1024 bit long.
- **hmac-sha**: A HMAC-SHA key. Must be a plain byte file 512, or 1024 bit long.
- **hmac-sha**: 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.
- **ec**: An elliptic curve private key. Must be a PEM or DER file.
</ul>

44
rust/pvsecret/man/pvsecret-create-retrievable.1
View File

@@ -1,9 +1,9 @@
.\" Copyright 2024 IBM Corp.
.\" 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" "2024-12-19" "s390-tools" "UV-Secret Manual"
.TH "PVSECRET-CREATE-RETRIEVABLE" "1" "2025-02-28" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
@@ -19,7 +19,43 @@ pvsecret create retr [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME>
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.
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>
@@ -56,7 +92,7 @@ Possible values:
\- \fBaes-xts\fP: An AES-XTS key. Must be a plain byte file 512, or 1024 bit long.
\- \fBhmac-sha\fP: A HMAC-SHA key. Must be a plain byte file 512, or 1024 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.

3
rust/pvsecret/src/cli.rs
View File

@@ -231,7 +231,8 @@ pub enum RetrieveableSecretInpKind {
/// Must be a plain byte file 512, or 1024 bit long.
AesXts,
/// A HMAC-SHA key.
/// Must be a plain byte file 512, or 1024 bit long.
/// 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.
HmacSha,
/// An elliptic curve private key.
/// Must be a PEM or DER file.