ns_hmac(n) 5.0.0a naviserver "NaviServer Built-in Commands"

Name

ns_hmac - Returns a string containing a keyed-hash message authentication code (HMAC)

Table Of Contents

• Table Of Contents
• Synopsis
• Description
• COMMANDS
• OPTIONS
• LOW LEVEL COMMANDS
• See Also
• Keywords

Synopsis

Description

These functions return a keyed-hash message authentication code (HMAC) for the specified key and message, using the specified message digest algorithm. An HMAC is a message authentication code of a key (secret) with a message. It may be used to simultaneously verify both the data integrity and the authentication of a message. For details of HMAC, consult RFC 4231.

The provided commands provide a one-step interface and an incremental interface, where the latter one can be used to incrementally compute a HMAC e.g. by reading data from a file. This is especially important for computing a HMAC on content which is too large to be kept in memory.

The listed commands are available in installations when NaviServer is compiled with OpenSSL support and where the NSF package is installed.

COMMANDS

ns_hmac string ?-digest value? ?-encoding value? key message

Returns the HMAC based on the provided secret key and the string message.

ns_hmac file ?-digest value? ?-encoding value? key filename ...

Returns the HMAC from the provided secret key, the file filename and the optional provided additional filenames in args. The files are read incrementally to keep storage requirements for large files low. The resulting HMAC is calculated cumulatively.

ns_hmac new ?-digest value? -key value

Creates and returns a new HMAC object for incremental operations. The option -digest defaults to "sha256" the option -key has to be always specified.

$hmac_object add data

Adds data incrementally to the HMAC object, which was created previously with ns_hmac new.

$hmac_object get ?-encoding encoding?

Returns the current HMAC value from the HMAC object, to which data was added previously with the method add.

$hmac_object destroy

Deletes the HMAC object (used for incremental operations).

OPTIONS

-digest digest

Digest algorithm for the checksum computation. The available algorithms are implemented in OpenSSL. The current versions of OpenSSL supports the following message digest algorithms: "blake2b512 blake2s256 md4 md5 md5-sha1 mdc2 ripemd160 sha1 sha224 sha256 sha3-224 sha3-256 sha3-384 sha3-512 sha384 sha512 sha512-224 sha512-256 shake128 shake256 sm3 whirlpool". The default value is "sha256"

-encoding encoding

The option -encoding encoding specifies the output encoding used for the resulting values of the dict. Possible encodings are hex, base64url, base64, or binary. Default is hex.

  nscp 2> ns_hmac string -digest sha256 "Jefe" "what do ya want for nothing?"
  5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

LOW LEVEL COMMANDS

While the command ns_hmac provides a high-level, object oriented interface mostly based on the MD objects, the lower level implementation provides more options for certain specialized operations.

ns_crypto::hmac add ?-binary? ?--? ctx message

ns_crypto::hmac free ctx

ns_crypto::hmac get ?-encoding hex|base64url|base64|binary? ctx

ns_crypto::hmac new ?-binary? ?--? digest key

ns_crypto::hmac string ?-binary? ?-digest value? ?-encoding hex|base64url|base64|binary? ?--? key message

Example for an HMAC based on sha384 with key Jefe:

 % ns_crypto::hmac string -digest sha384 "Jefe" "what do ya want for nothing?"
 af45d2e376484031617f78d2b58a6b1b9c7ef464f5a01b47e42ec3736322445e8e2240ca5e69e2c78b3239ecfab21649

See Also

ns_crypt, ns_crypto, ns_hotp, ns_md, ns_md5, ns_rand, ns_sha, ns_sha1, ns_totp, nsd

Keywords

HMAC, crypto, encoding, nsf