nupp.mac

Keyed message authentication. Keys are raw bytes. HMAC-SHA256 is built in; setup selects a typed catalog through nupp.runtime.services.mac before this module loads. Algorithm lookup and state creation use retained descriptors.

Module contents

Types

TypeKindDescription
AlgorithmrecordImmutable MAC metadata and a keyed context factory.
MacinterfaceAn owned keyed context with consuming digest finalization.

Functions

FunctionKindDescription
algorithmfunctionRequires an available MAC descriptor.
algorithmsfunctionLists available canonical MAC names in ascending order.
createfunctionCreates independent owned state initialized with a key.
digestfunctionComputes a raw message authentication code.
hexDigestfunctionComputes a lowercase hexadecimal message authentication code.
lookupfunctionLooks up MAC metadata before initializing a keyed context.

Types#

Algorithmrecord#

record Algorithm
    readonly name: string
    readonly digestSize: integer
    function create(self, key: string): Mac end
end

Immutable MAC metadata and a keyed context factory.

Methods

create#
create: function create(self, key: string): Mac

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

Arguments
NameTypeDescription
selfany
keystring
Returns
TypeDescription
Mac

Fields

name#
name: string

Canonical authentication algorithm name.

digestSize#
digestSize: integer

Fixed authentication output size in bytes.

Macinterface#

affine interface Mac is nupp.Closeable
    terminal close: nosuspend function(takes self: Digest): nil
    algorithm: function(self: Digest): string
    digestSize: function(self: Digest): integer
    update: function(exclusive self: Digest, bytes: string): nil
    updateSpan: function(exclusive self: Digest, borrows bytes: span.ByteSpan): nil
    digest: function(takes self: Digest): string
        & function(takes self: Digest, exclusive destination: span.ByteWriteSpan): integer
    hexDigest: function(takes self: Digest): string
end

An owned keyed context with consuming digest finalization.

Methods

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

Consumes an unfinished context and releases provider state without suspension.

Arguments
NameTypeDescription
takes selfDigest
Returns
TypeDescription
nil
algorithm#
algorithm: function(self: Digest): string

Returns the canonical algorithm name retained at creation.

Arguments
NameTypeDescription
selfDigest
Returns
TypeDescription
string
digestSize#
digestSize: function(self: Digest): integer

Returns the fixed output size in bytes.

Arguments
NameTypeDescription
selfDigest
Returns
TypeDescription
integer
update#
update: function(exclusive self: Digest, bytes: string): nil

Processes raw bytes without retaining a borrowed input.

Arguments
NameTypeDescription
exclusive selfDigest
bytesstring
Returns
TypeDescription
nil
updateSpan#
updateSpan: function(exclusive self: Digest, borrows bytes: span.ByteSpan): nil

Processes a borrowed byte view without retaining it.

Arguments
NameTypeDescription
exclusive selfDigest
borrows bytesspan.ByteSpan
Returns
TypeDescription
nil
digest#
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
NameTypeDescription
takes selfDigest
exclusive destinationspan.ByteWriteSpan
Returns
TypeDescription
integer
hexDigest#
hexDigest: function(takes self: Digest): string

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

Arguments
NameTypeDescription
takes selfDigest
Returns
TypeDescription
string

Functions#

algorithmfunction#

function algorithm(name: string): Algorithm

Requires an available MAC descriptor.

Arguments

NameTypeDescription
namestring

the canonical MAC algorithm name

Returns

TypeDescription
Algorithm

the selected descriptor

Raises

  • when the algorithm is unavailable

algorithmsfunction#

function algorithms(): {string}

Lists available canonical MAC names in ascending order.

Returns

TypeDescription
{string}

the available names

createfunction#

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

Creates independent owned state initialized with a key.

Arguments

NameTypeDescription
namestring

the canonical MAC algorithm name

keystring

the raw-byte secret key

Returns

TypeDescription
Mac

an unfinished keyed context

digestfunction#

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

Computes a raw message authentication code.

Arguments

NameTypeDescription
namestring

the canonical MAC algorithm name

keystring

the raw-byte secret key

bytesstring

the message bytes

Returns

TypeDescription
string

the raw fixed-size authentication code

hexDigestfunction#

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

Computes a lowercase hexadecimal message authentication code.

Arguments

NameTypeDescription
namestring

the canonical MAC algorithm name

keystring

the raw-byte secret key

bytesstring

the message bytes

Returns

TypeDescription
string

the lowercase hexadecimal authentication code

lookupfunction#

function lookup(name: string): Algorithm?

Looks up MAC metadata before initializing a keyed context.

Arguments

NameTypeDescription
namestring

the canonical MAC algorithm name

Returns

TypeDescription
Algorithm?

the descriptor, or nil when unavailable