From e49569db6073ae2efc1c42cfc97c479621c95383 Mon Sep 17 00:00:00 2001 From: Ingo Franzki Date: Fri, 28 Feb 2025 10:58:26 +0100 Subject: [PATCH] rust/pvsecret: Update man page for clarifying the creation of HMAC secrets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Steffen Eiden Signed-off-by: Jan Höppner --- rust/pvsecret/README.md | 2 +- .../man/pvsecret-create-retrievable.1 | 44 +++++++++++++++++-- rust/pvsecret/src/cli.rs | 3 +- 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/rust/pvsecret/README.md b/rust/pvsecret/README.md index 711f81d7..edecb1e7 100644 --- a/rust/pvsecret/README.md +++ b/rust/pvsecret/README.md @@ -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. diff --git a/rust/pvsecret/man/pvsecret-create-retrievable.1 b/rust/pvsecret/man/pvsecret-create-retrievable.1 index 0d7575eb..0f8d75f8 100644 --- a/rust/pvsecret/man/pvsecret-create-retrievable.1 +++ b/rust/pvsecret/man/pvsecret-create-retrievable.1 @@ -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 --type 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 +'\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 '\fP and then \fB'truncate \-\-size 64 +'\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 @@ -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. diff --git a/rust/pvsecret/src/cli.rs b/rust/pvsecret/src/cli.rs index d858fc29..74f6bad2 100644 --- a/rust/pvsecret/src/cli.rs +++ b/rust/pvsecret/src/cli.rs @@ -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.