# `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. ## Types ### `Algorithm` _record_ ```nupp 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` ```nupp create: function create(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` | | #### Fields ##### `name` ```nupp name: string ``` Canonical authentication algorithm name. ##### `digestSize` ```nupp digestSize: integer ``` Fixed authentication output size in bytes. ### `Mac` _interface_ ```nupp 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` ```nupp close: nosuspend function(takes self: Digest): nil ``` Consumes an unfinished context and releases provider state without suspension. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `Digest` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `algorithm` ```nupp algorithm: function(self: Digest): string ``` Returns the canonical algorithm name retained at creation. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Digest` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `digestSize` ```nupp digestSize: function(self: Digest): integer ``` Returns the fixed output size in bytes. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Digest` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `update` ```nupp update: function(exclusive self: Digest, bytes: string): nil ``` Processes raw bytes without retaining a borrowed input. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Digest` | | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `updateSpan` ```nupp updateSpan: function(exclusive self: Digest, borrows bytes: span.ByteSpan): nil ``` Processes a borrowed byte view without retaining it. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Digest` | | | `borrows bytes` | `span.ByteSpan` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `digest` ```nupp 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` | `Digest` | | | `exclusive destination` | `span.ByteWriteSpan` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `hexDigest` ```nupp hexDigest: function(takes self: Digest): string ``` Consumes this context and returns lowercase hexadecimal, always closing state. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `Digest` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ## Functions ### `algorithm` _function_ ```nupp 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 - when the algorithm is unavailable ### `algorithms` _function_ ```nupp function algorithms(): {string} ``` Lists available canonical MAC names in ascending order. #### Returns | Type | Description | | --- | --- | | `{string}` | the available names | ### `create` _function_ ```nupp function create(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 | ### `digest` _function_ ```nupp 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 | ### `hexDigest` _function_ ```nupp 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 | ### `lookup` _function_ ```nupp 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 |