`nupp.mac`

Keyed hashes, for bytes somebody could have tampered with.

Same shape as nupp.digest, plus a key.

const mac = nupp.mac

print(mac.hexDigest("hmac-sha256", key, "hello"))

local running = mac.newMac("hmac-sha256", key)

running:write("hel")
running:write("lo")

print(running:hexDigest())

The key is raw bytes. A context is an io.Writer, as a digest is. Finalizing consumes the context; create another context to authenticate another message.

Built-in algorithms#

Name	Output	Construction
`hmac-sha256`	32 bytes	HMAC over SHA-256

hmac-sha256 names the HMAC construction over SHA-256. Smithy's httpChecksum trait does not define MAC algorithms. AWS KMS uses HMAC_SHA_256 for this construction, while AWS4-HMAC-SHA256 identifies the complete SigV4 signing scheme.

A host may supply its own catalog through nupp.mac.spi, chosen by priority when this module initializes. It is read once, at load.

Submodules

Module	Description
`nupp.mac.spi`	Implementation interfaces for keyed authentication algorithm catalogs.

Module contents

Types

Type	Kind	Description
`Algorithm`	record	Immutable MAC metadata and a keyed context factory.
`Mac`	interface	An owned keyed context with consuming digest finalization.

Functions

Function	Kind	Description
`algorithm`	function	Requires an available MAC descriptor.
`algorithms`	function	Lists available canonical MAC names in ascending order.
`digest`	function	Computes a raw message authentication code.
`hexDigest`	function	Computes a lowercase hexadecimal message authentication code.
`lookup`	function	Looks up MAC metadata before initializing a keyed context.
`newMac`	function	Creates independent owned state initialized with a key.

Types#

`Algorithm`record#

record Algorithm ...

Immutable MAC metadata and a keyed context factory.

Members

Name	Kind	Description
`name`	field	Canonical authentication algorithm name.
`digestSize`	field	Fixed authentication output size in bytes.
`implementation`	field
`newMac`	method	Creates independent owned state initialized with the raw-byte key.

`name`field#

name: string

@readonly

Canonical authentication algorithm name.

`digestSize`field#

digestSize: integer

@readonly

Fixed authentication output size in bytes.

`implementation`field#

implementation: provider.Algorithm

@private

`newMac`method#

newMac: function newMac(self, key: string): Mac

Creates independent owned state initialized with the raw-byte key.

Arguments

Name	Type	Description
`self`	`any`
`key`	`string`

Returns

Type	Description
`Mac`	the unfinished keyed context

Raises

Type	Condition
`string`	when provider initialization fails

`Mac`interface#

interface Mac is Writer ...

An owned keyed context with consuming digest finalization.

Members

Name	Kind	Description
`close`	method	Consumes an unfinished context and releases provider state without suspension.
`algorithm`	method	Returns the canonical algorithm name retained at creation.
`digestSize`	method	Returns the fixed output size in bytes.
`write`	method	Absorbs raw bytes without retaining a borrowed input.
`writeSpan`	method	Absorbs a borrowed byte view without retaining it.
`flush`	method	Nothing is buffered behind a digest, so this only returns true.
`digest`	method	Consumes this context and returns raw bytes, or writes the fixed-size prefix of destination and returns its byte count.
`hexDigest`	method	Consumes this context and returns lowercase hexadecimal, always closing state.

`close`method#

close: @nosuspend function(takes self: Digest): nil

Consumes an unfinished context and releases provider state without suspension.

Arguments

Name	Type	Description
`takes self`	`Mac`

Returns

Type	Description
`nil`

`algorithm`method#

algorithm: function(self: Digest): string

Returns the canonical algorithm name retained at creation.

Arguments

Name	Type	Description
`self`	`Mac`

Returns

Type	Description
`string`

`digestSize`method#

digestSize: function(self: Digest): integer

Returns the fixed output size in bytes.

Arguments

Name	Type	Description
`self`	`Mac`

Returns

Type	Description
`integer`

`write`method#

write: function(exclusive self: Digest, bytes: string): (boolean, string?)

Absorbs raw bytes without retaining a borrowed input.

Arguments

Name	Type	Description
`exclusive self`	`Mac`
`bytes`	`string`

Returns

Type	Description
`boolean`	true, since a digest takes every byte it is given
`string?`

`writeSpan`method#

writeSpan: function(exclusive self: Digest, borrows bytes: span.ByteSpan): (integer?, string?)

Absorbs a borrowed byte view without retaining it.

Arguments

Name	Type	Description
`exclusive self`	`Mac`
`borrows bytes`	`span.ByteSpan`

Returns

Type	Description
`integer?`	how many bytes it absorbed, which is all of them
`string?`

`flush`method#

flush: function(self: Digest): (boolean, string?)

Nothing is buffered behind a digest, so this only returns true.

Arguments

Name	Type	Description
`self`	`Mac`

Returns

Type	Description
`boolean`
`string?`

`digest`method#

digest: function(takes self: Digest): string
& function(takes self: Digest, exclusive destination: span.ByteWriteSpan): integer

Consumes this context and returns raw bytes, or writes the fixed-size prefix of destination and returns its byte count. Always closes state.

Arguments

Name	Type	Description
`takes self`	`Mac`
`exclusive destination`	`span.ByteWriteSpan`

Returns

Type	Description
`integer`

`hexDigest`method#

hexDigest: function(takes self: Digest): string

Consumes this context and returns lowercase hexadecimal, always closing state.

Arguments

Name	Type	Description
`takes self`	`Mac`

Returns

Type	Description
`string`

Functions#

`algorithm`function#

function algorithm(name: string): Algorithm

Requires an available MAC descriptor.

Arguments

Name	Type	Description
`name`	`string`	the canonical MAC algorithm name

Returns

Type	Description
`Algorithm`	the selected descriptor

Raises

Type	Condition
`string`	when the algorithm is unavailable

`algorithms`function#

function algorithms(): {string}

Lists available canonical MAC names in ascending order.

Returns

Type	Description
`{string}`	the available names

`digest`function#

function digest(name: string, key: string, bytes: string): string

Computes a raw message authentication code.

Arguments

Name	Type	Description
`name`	`string`	the canonical MAC algorithm name
`key`	`string`	the raw-byte secret key
`bytes`	`string`	the message bytes

Returns

Type	Description
`string`	the raw fixed-size authentication code

Raises

Type	Condition
`string`	when lookup or a provider operation fails

`hexDigest`function#

function hexDigest(name: string, key: string, bytes: string): string

Computes a lowercase hexadecimal message authentication code.

Arguments

Name	Type	Description
`name`	`string`	the canonical MAC algorithm name
`key`	`string`	the raw-byte secret key
`bytes`	`string`	the message bytes

Returns

Type	Description
`string`	the lowercase hexadecimal authentication code

Raises

Type	Condition
`string`	when lookup or a provider operation fails

`lookup`function#

function lookup(name: string): Algorithm?

Looks up MAC metadata before initializing a keyed context.

Arguments

Name	Type	Description
`name`	`string`	the canonical MAC algorithm name

Returns

Type	Description
`Algorithm?`	the descriptor, or nil when unavailable

`newMac`function#

function newMac(name: string, key: string): Mac

Creates independent owned state initialized with a key.

Arguments

Name	Type	Description
`name`	`string`	the canonical MAC algorithm name
`key`	`string`	the raw-byte secret key

Returns

Type	Description
`Mac`	an unfinished keyed context

Raises

Type	Condition
`string`	when lookup or provider initialization fails

nupp.mac

Built-in algorithms#

Submodules

Module contents

Types

Functions

Types#

Algorithmrecord#

Members

namefield#

digestSizefield#

implementationfield#

newMacmethod#

Arguments

Returns

Raises

Macinterface#

Members

closemethod#

Arguments

Returns

algorithmmethod#

Arguments

Returns

digestSizemethod#

Arguments

Returns

writemethod#

Arguments

Returns

writeSpanmethod#

Arguments

Returns

flushmethod#

Arguments

Returns

digestmethod#

Arguments

Returns

hexDigestmethod#

Arguments

Returns

Functions#

algorithmfunction#

Arguments

Returns

Raises

algorithmsfunction#

Returns

digestfunction#

Arguments

Returns

Raises

hexDigestfunction#

Arguments

Returns

Raises

lookupfunction#

Arguments

Returns

newMacfunction#

Arguments

Returns

Raises

`nupp.mac`

`Algorithm`record#

`name`field#

`digestSize`field#

`implementation`field#

`newMac`method#

`Mac`interface#

`close`method#

`algorithm`method#

`digestSize`method#

`write`method#

`writeSpan`method#

`flush`method#

`digest`method#

`hexDigest`method#

`algorithm`function#

`algorithms`function#

`digest`function#

`hexDigest`function#

`lookup`function#

`newMac`function#