libdecaf_tuak (libdecaf v3.0.0)
View SourceTUAK 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
-type ak() :: libdecaf_nif:tuak_ak().
A six-byte anonymity key, AK or AK*.
-type amf() :: libdecaf_nif:tuak_amf().
The two-byte authentication management field AMF.
-type ck() :: libdecaf_nif:tuak_ck().
A 16- or 32-byte confidentiality key CK.
-type ck_length() :: libdecaf_nif:tuak_ck_length().
Supported ck length values in bytes; default 16.
-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.
-type ik() :: libdecaf_nif:tuak_ik().
A 16- or 32-byte integrity key IK.
-type ik_length() :: libdecaf_nif:tuak_ik_length().
Supported ik length values in bytes; default 16.
-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.
-type key() :: libdecaf_nif:tuak_key().
A 16- or 32-byte subscriber key K.
-type mac() :: libdecaf_nif:tuak_mac().
An 8-, 16-, or 32-byte authentication code, MAC-A or MAC-S.
-type mac_length() :: libdecaf_nif:tuak_mac_length().
Supported mac length values in bytes; default 8.
-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.
-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.
-type rand() :: libdecaf_nif:tuak_rand().
The 16-byte authentication challenge RAND.
-type res() :: libdecaf_nif:tuak_res().
A 4-, 8-, 16-, or 32-byte authentication response RES.
-type res_length() :: libdecaf_nif:tuak_res_length().
Supported res length values in bytes; default 8.
-type sqn() :: libdecaf_nif:tuak_sqn().
The six-byte sequence number SQN (SQN_MS during resynchronization).
-type top() :: libdecaf_nif:tuak_top().
The 32-byte operator configuration TOP.
-type topc() :: libdecaf_nif:tuak_topc().
The 32-byte subscriber-specific TOPc derived from TOP and K.
Functions
-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.
-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.
-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.
-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.
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.
-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.
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.
-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.
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.
-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.
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.
-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.
-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.
-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.
-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.
-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.
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.
-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.