pvsecret-create-retrievable - Man Page
Create a retrievable secret
Synopsis
pvsecret create retrievable [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME> pvsecret create retr [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME>
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 EC PRIVATE KEY with one of the following curves: secp256r1, secp384r1, secp521r1, ed25519, or ed448.
HMAC-SHA preprocessing
The HMAC-SHA key supplied in the plain bytes file is the 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.
Pre-processing means that if the key K 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 truncate command with the desired size in bytes, e.g. 'truncate --size 64 <key-file>' for creating a K_0 key for HMAC-SHA-224 and HMAC-SHA-256.
In case key K is longer than the block size of the to-be-used HMAC digest, then key K 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 truncate command: 'openssl sha256 -binary -out <key2-file> <key-file>' and then 'truncate --size 64 <key2-file>' for creating a K_0 key for HMAC-SHA-256.
ATTENTION: The digest used for hashing the key K 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!
Options
- <NAME>
String that identifies the new secret. The actual secret is set with --secret. The name is saved in `NAME.yaml` with white-spaces mapped to `_`.
- --stdout
Print the hashed name to stdout. The hashed name is not written to `NAME.yaml`
- --secret <SECRET-FILE>
Use SECRET-FILE as retrievable secret.
- --type <TYPE>
Specify the secret type. Limitations to the input data apply depending on the secret type.
Possible values:
- 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 256, or 512 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.
- -h, --help
Print help (see a summary with -h).