libdecaf_tuak (libdecaf v3.0.0)

View Source

TUAK authentication and key generation from 3GPP TS 35.231.

Derive the subscriber-specific TOPc from the subscriber key Key and the operator's configuration TOP, then reuse it for authentication and key agreement. Keys contain 16 or 32 bytes; TOP and TOPc contain 32 bytes. RAND contains 16 bytes, SQN six bytes, and AMF two bytes. All fields are binaries in the byte order printed in the 3GPP test vectors.

f1/5,6 returns the network authentication code MAC-A; f1_star/5,6 returns the resynchronization code MAC-S. f2345/3,4 computes {RES, CK, IK, AK} together, while f2, f3, f4, and f5 return the individual components. f5_star/3,4 produces the resynchronization anonymity key AK*.

Options are maps with optional, named settings. Lengths are in bytes: MAC lengths are 8, 16, or 32; RES lengths are 4, 8, 16, or 32; CK and IK lengths are 16 or 32. Defaults are MAC=8, RES=8, CK=16, IK=16, and iterations=1.

Output-length choices participate in TUAK's domain separation. In particular, use the same res_length, ck_length, and ik_length with all the individual f2–f5 calls that belong to one authentication exchange. Use the same positive iteration count for TOPc derivation and subsequent operations. Each iteration applies a complete 24-round Keccak-f[1600] permutation.

This example uses test set 1 from the specification's conformance data:

Key = binary:copy(<<16#AB>>, 16),
TOP = binary:copy(<<16#55>>, 32),
RAND = binary:copy(<<16#42>>, 16),
SQN = binary:copy(<<16#11>>, 6),
AMF = <<16#FF, 16#FF>>,
TOPc = libdecaf_tuak:topc(Key, TOP),
MAC_A = libdecaf_tuak:f1(Key, TOPc, RAND, SQN, AMF),
<<"F9A54E6AEAA8618D">> = binary:encode_hex(MAC_A),
{RES, CK, IK, AK} = libdecaf_tuak:f2345(Key, TOPc, RAND, #{res_length => 4}),
<<"657ACD64">> = binary:encode_hex(RES),
16 = byte_size(CK),
16 = byte_size(IK),
6 = byte_size(AK).

The implementation follows TS 35.231 Release 19. Secrets and derived keys should be kept private; temporary native state is erased after each computation. Native calls use dirty CPU schedulers.

Summary

Types

A six-byte anonymity key, AK or AK*.

The two-byte authentication management field AMF.

A 16- or 32-byte confidentiality key CK.

Supported ck length values in bytes; default 16.

Optional settings for this TUAK operation. Unspecified settings use the configured defaults; unknown or inapplicable keys raise badarg. Lengths participate in domain separation.

A 16- or 32-byte integrity key IK.

Supported ik length values in bytes; default 16.

Number of complete 24-round Keccak-f[1600] permutations; default 1. Use the same count for TOPc derivation and its subsequent operations. Long evaluations yield between bounded batches and stop when their caller is terminated.

A 16- or 32-byte subscriber key K.

An 8-, 16-, or 32-byte authentication code, MAC-A or MAC-S.

Supported mac length values in bytes; default 8.

Optional settings for this TUAK operation. Unspecified settings use the configured defaults; unknown or inapplicable keys raise badarg. Lengths participate in domain separation.

Optional settings for this TUAK operation. Unspecified settings use the configured defaults; unknown or inapplicable keys raise badarg. Lengths participate in domain separation.

The 16-byte authentication challenge RAND.

A 4-, 8-, 16-, or 32-byte authentication response RES.

Supported res length values in bytes; default 8.

The six-byte sequence number SQN (SQN_MS during resynchronization).

The 32-byte operator configuration TOP.

The 32-byte subscriber-specific TOPc derived from TOP and K.

Functions

Compute the network authentication code MAC-A over RAND, SQN, and AMF. Use the configured defaults, equivalent to passing #{} to the next arity. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

Compute the network authentication code MAC-A over RAND, SQN, and AMF. Accepted options: mac_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

Compute the resynchronization authentication code MAC-S. Pass the mobile station's sequence number as SQN and the protocol's resynchronization AMF. Use the configured defaults, equivalent to passing #{} to the next arity. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

Compute the resynchronization authentication code MAC-S. Pass the mobile station's sequence number as SQN and the protocol's resynchronization AMF. Accepted options: mac_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

Compute the authentication response RES for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

Compute the authentication response RES for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

Compute the confidentiality key CK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

Compute the confidentiality key CK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

Compute the integrity key IK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

Compute the integrity key IK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

Compute the six-byte anonymity key AK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

Compute the six-byte anonymity key AK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

Compute the six-byte resynchronization anonymity key AK* for RAND. Use the configured defaults, equivalent to passing #{} to the next arity.

Compute the six-byte resynchronization anonymity key AK* for RAND. Accepted options: iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

Compute the response RES, confidentiality key CK, integrity key IK, and anonymity key AK together in one TUAK evaluation. Return {RES, CK, IK, AK}. Use the configured defaults, equivalent to passing #{} to the next arity.

Compute the response RES, confidentiality key CK, integrity key IK, and anonymity key AK together in one TUAK evaluation. Return {RES, CK, IK, AK}. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

Derive the subscriber-specific TOPc from the subscriber key and the operator's TOP. Reuse TOPc with the same key and iteration count for subsequent TUAK operations. Use the configured defaults, equivalent to passing #{} to the next arity.

Derive the subscriber-specific TOPc from the subscriber key and the operator's TOP. Reuse TOPc with the same key and iteration count for subsequent TUAK operations. Accepted options: iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

Types

ak()

-type ak() :: libdecaf_nif:tuak_ak().

A six-byte anonymity key, AK or AK*.

amf()

-type amf() :: libdecaf_nif:tuak_amf().

The two-byte authentication management field AMF.

ck()

-type ck() :: libdecaf_nif:tuak_ck().

A 16- or 32-byte confidentiality key CK.

ck_length()

-type ck_length() :: libdecaf_nif:tuak_ck_length().

Supported ck length values in bytes; default 16.

derive_options()

-type derive_options() :: libdecaf_nif:tuak_derive_options().

Optional settings for this TUAK operation. Unspecified settings use the configured defaults; unknown or inapplicable keys raise badarg. Lengths participate in domain separation.

ik()

-type ik() :: libdecaf_nif:tuak_ik().

A 16- or 32-byte integrity key IK.

ik_length()

-type ik_length() :: libdecaf_nif:tuak_ik_length().

Supported ik length values in bytes; default 16.

iterations()

-type iterations() :: libdecaf_nif:tuak_iterations().

Number of complete 24-round Keccak-f[1600] permutations; default 1. Use the same count for TOPc derivation and its subsequent operations. Long evaluations yield between bounded batches and stop when their caller is terminated.

key()

-type key() :: libdecaf_nif:tuak_key().

A 16- or 32-byte subscriber key K.

mac()

-type mac() :: libdecaf_nif:tuak_mac().

An 8-, 16-, or 32-byte authentication code, MAC-A or MAC-S.

mac_length()

-type mac_length() :: libdecaf_nif:tuak_mac_length().

Supported mac length values in bytes; default 8.

mac_options()

-type mac_options() :: libdecaf_nif:tuak_mac_options().

Optional settings for this TUAK operation. Unspecified settings use the configured defaults; unknown or inapplicable keys raise badarg. Lengths participate in domain separation.

options()

-type options() :: libdecaf_nif:tuak_options().

Optional settings for this TUAK operation. Unspecified settings use the configured defaults; unknown or inapplicable keys raise badarg. Lengths participate in domain separation.

rand()

-type rand() :: libdecaf_nif:tuak_rand().

The 16-byte authentication challenge RAND.

res()

-type res() :: libdecaf_nif:tuak_res().

A 4-, 8-, 16-, or 32-byte authentication response RES.

res_length()

-type res_length() :: libdecaf_nif:tuak_res_length().

Supported res length values in bytes; default 8.

sqn()

-type sqn() :: libdecaf_nif:tuak_sqn().

The six-byte sequence number SQN (SQN_MS during resynchronization).

top()

-type top() :: libdecaf_nif:tuak_top().

The 32-byte operator configuration TOP.

topc()

-type topc() :: libdecaf_nif:tuak_topc().

The 32-byte subscriber-specific TOPc derived from TOP and K.

Functions

f1(Key, TOPc, RAND, SQN, AMF)

-spec f1(Key, TOPc, RAND, SQN, AMF) -> MAC_A
            when
                Key :: key(), TOPc :: topc(), RAND :: rand(), SQN :: sqn(), AMF :: amf(), MAC_A :: mac().

Compute the network authentication code MAC-A over RAND, SQN, and AMF. Use the configured defaults, equivalent to passing #{} to the next arity. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

f1(Key, TOPc, RAND, SQN, AMF, Options)

-spec f1(Key, TOPc, RAND, SQN, AMF, Options) -> MAC_A
            when
                Key :: key(),
                TOPc :: topc(),
                RAND :: rand(),
                SQN :: sqn(),
                AMF :: amf(),
                Options :: mac_options(),
                MAC_A :: mac().

Compute the network authentication code MAC-A over RAND, SQN, and AMF. Accepted options: mac_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

f1_star(Key, TOPc, RAND, SQN, AMF)

-spec f1_star(Key, TOPc, RAND, SQN, AMF) -> MAC_S
                 when
                     Key :: key(),
                     TOPc :: topc(),
                     RAND :: rand(),
                     SQN :: sqn(),
                     AMF :: amf(),
                     MAC_S :: mac().

Compute the resynchronization authentication code MAC-S. Pass the mobile station's sequence number as SQN and the protocol's resynchronization AMF. Use the configured defaults, equivalent to passing #{} to the next arity. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

f1_star(Key, TOPc, RAND, SQN, AMF, Options)

-spec f1_star(Key, TOPc, RAND, SQN, AMF, Options) -> MAC_S
                 when
                     Key :: key(),
                     TOPc :: topc(),
                     RAND :: rand(),
                     SQN :: sqn(),
                     AMF :: amf(),
                     Options :: mac_options(),
                     MAC_S :: mac().

Compute the resynchronization authentication code MAC-S. Pass the mobile station's sequence number as SQN and the protocol's resynchronization AMF. Accepted options: mac_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg. The default MAC length is 8 bytes. The same key, TOPc, iteration count, and input fields must be used when checking the received authentication code.

f2(Key, TOPc, RAND)

-spec f2(Key, TOPc, RAND) -> RES when Key :: key(), TOPc :: topc(), RAND :: rand(), RES :: res().

Compute the authentication response RES for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

f2(Key, TOPc, RAND, Options)

-spec f2(Key, TOPc, RAND, Options) -> RES
            when Key :: key(), TOPc :: topc(), RAND :: rand(), Options :: derive_options(), RES :: res().

Compute the authentication response RES for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

f3(Key, TOPc, RAND)

-spec f3(Key, TOPc, RAND) -> CK when Key :: key(), TOPc :: topc(), RAND :: rand(), CK :: ck().

Compute the confidentiality key CK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

f3(Key, TOPc, RAND, Options)

-spec f3(Key, TOPc, RAND, Options) -> CK
            when Key :: key(), TOPc :: topc(), RAND :: rand(), Options :: derive_options(), CK :: ck().

Compute the confidentiality key CK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

f4(Key, TOPc, RAND)

-spec f4(Key, TOPc, RAND) -> IK when Key :: key(), TOPc :: topc(), RAND :: rand(), IK :: ik().

Compute the integrity key IK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

f4(Key, TOPc, RAND, Options)

-spec f4(Key, TOPc, RAND, Options) -> IK
            when Key :: key(), TOPc :: topc(), RAND :: rand(), Options :: derive_options(), IK :: ik().

Compute the integrity key IK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

f5(Key, TOPc, RAND)

-spec f5(Key, TOPc, RAND) -> AK when Key :: key(), TOPc :: topc(), RAND :: rand(), AK :: ak().

Compute the six-byte anonymity key AK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Use the configured defaults, equivalent to passing #{} to the next arity.

f5(Key, TOPc, RAND, Options)

-spec f5(Key, TOPc, RAND, Options) -> AK
            when Key :: key(), TOPc :: topc(), RAND :: rand(), Options :: derive_options(), AK :: ak().

Compute the six-byte anonymity key AK for RAND. All three output-length choices affect the shared f2/f3/f4/f5 computation, so use the same options for each function. Use f2345 to obtain all four outputs together. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

f5_star(Key, TOPc, RAND)

-spec f5_star(Key, TOPc, RAND) -> AK_Star
                 when Key :: key(), TOPc :: topc(), RAND :: rand(), AK_Star :: ak().

Compute the six-byte resynchronization anonymity key AK* for RAND. Use the configured defaults, equivalent to passing #{} to the next arity.

f5_star(Key, TOPc, RAND, Options)

-spec f5_star(Key, TOPc, RAND, Options) -> AK_Star
                 when
                     Key :: key(), TOPc :: topc(), RAND :: rand(), Options :: options(), AK_Star :: ak().

Compute the six-byte resynchronization anonymity key AK* for RAND. Accepted options: iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

f2345(Key, TOPc, RAND)

-spec f2345(Key, TOPc, RAND) -> Outputs
               when Key :: key(), TOPc :: topc(), RAND :: rand(), Outputs :: {res(), ck(), ik(), ak()}.

Compute the response RES, confidentiality key CK, integrity key IK, and anonymity key AK together in one TUAK evaluation. Return {RES, CK, IK, AK}. Use the configured defaults, equivalent to passing #{} to the next arity.

f2345(Key, TOPc, RAND, Options)

-spec f2345(Key, TOPc, RAND, Options) -> Outputs
               when
                   Key :: key(),
                   TOPc :: topc(),
                   RAND :: rand(),
                   Options :: derive_options(),
                   Outputs :: {res(), ck(), ik(), ak()}.

Compute the response RES, confidentiality key CK, integrity key IK, and anonymity key AK together in one TUAK evaluation. Return {RES, CK, IK, AK}. Accepted options: res_length, ck_length, ik_length, iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.

topc(Key, TOP)

-spec topc(Key, TOP) -> TOPc when Key :: key(), TOP :: top(), TOPc :: topc().

Derive the subscriber-specific TOPc from the subscriber key and the operator's TOP. Reuse TOPc with the same key and iteration count for subsequent TUAK operations. Use the configured defaults, equivalent to passing #{} to the next arity.

topc(Key, TOP, Options)

-spec topc(Key, TOP, Options) -> TOPc
              when Key :: key(), TOP :: top(), Options :: options(), TOPc :: topc().

Derive the subscriber-specific TOPc from the subscriber key and the operator's TOP. Reuse TOPc with the same key and iteration count for subsequent TUAK operations. Accepted options: iterations. Unknown keys, unsupported lengths, zero iterations, and incorrectly sized fields raise badarg.