Skip to content

NAME

hmackeys - utility program for generating HMAC keys of various lengths

SYNOPSIS

hmackeys [ key_length_in_bytes ] [ key_names_file ]

DESCRIPTION

hmackeys is a convenience utility that writes files containing cryptographically secure random key values. These keys are suitable for use in support of BPv7 Bundle Protocol Security (BPSec), Bundle Relay Service (BRS), or any other function that requires symmetric keyed-hash authentication.

The key length is configurable via a command-line argument, specified in bytes. If no length is provided, it defaults to 32 bytes (256 bits), which is appropriate for HMAC-SHA-256. The key material is sourced from the best available platform-native entropy source (e.g., getrandom(), BCryptGenRandom, /dev/urandom) for maximum security and portability.

One key file is written for each key name provided to hmackeys. The content of each file is the raw binary key data, and the name given to each file is "keyname.hmk".

hmackeys operates in response to the key names found in the file keynames_filename, one name per line, if provided. If no file is given, hmackeys prints a simple prompt (:) so that you can type key names directly into standard input.

When the program is run in interactive mode, enter 'q' or press Ctrl-C to terminate.

EXIT STATUS

  • "0"

    Successful completion of key generation for all provided names.

  • "-1"

    Failure due to invalid arguments, system error (e.g., file creation), or inability to generate secure random data. Check stderr for a descriptive error message.

EXAMPLES

  • hmackeys

    Enter interactive key generation mode using the default key length of 32 bytes (256 bits), suitable for HMAC-SHA-256.

  • hmackeys 64

    Enter interactive mode to generate keys with a custom length of 64 bytes (512 bits), suitable for HMAC-SHA-512.

  • hmackeys 20 legacy_keys.txt

    Create a 20-byte (160-bit) key file, suitable for HMAC-SHA-1, for each key name listed in the legacy_keys.txt file.

FILES

Key files are created in the current working directory with a .hmk extension. No other files are used in the operation of hmackeys.

ENVIRONMENT

No environment variables apply.

DIAGNOSTICS

The following diagnostics may be issued to standard error:

  • Can't open keynames file...

    The keynames_filename specified on the command line could not be opened.

  • Failed to allocate memory for key.

    The program was unable to allocate sufficient memory for the requested key length.

  • Could not generate key material: [reason]

    The underlying entropy source failed. The reason will indicate the specific system error.

  • Can't write key to [file]: [reason]

    The program was unable to write the generated key to its destination file.

BUGS

Report bugs to https://github.com/nasa-jpl/ION-DTN/issues

SEE ALSO

brsscla(1), ionsecadmin(1), poll_entropy_src(3)