# TCCSecurity_Functions

#### Purpose

This module supports security based operations e.g. fingerprint generation

#### Module Parameters

-

#### Module depends on

-

#### Current Owner

EFLOATT

#### Last Review Date

-

Summary

TCCSecurity_Functions | This module supports security based operations e.g.
Functions |
f_calculateDigestResponse | Calculate digest response
f_calculateDigestHA1 | Calculate digest H(A1) hash
f__TCCSecurity__hex2char | Computes the 8 bit ASCII representation of an hexstring
f_calculateMD5 | Compute MD5 hash value
f_IMSAKA_f1 | Computes network authentication code MAC-A from key K, random challenge RAND, sequence number SQN and authentication management field AMF.
f_IMSAKA_f2 | Takes key K and random challenge RAND, and returns response RES.
f_IMSAKA_f3 | Takes key K and random challenge RAND, and returns confidentiality key CK.
f_IMSAKA_f4 | Takes key K and random challenge RAND, and returns integrity key IK.
f_IMSAKA_f2345 | Takes key K and random challenge RAND, and returns AK, CK, RES
f_IMSAKA_f5 | Takes key K and random challenge RAND, and returns anonymity key AK.
f_IMSAKA_f1star | Computes resynch authentication code MAC-S from key K, random challenge RAND, sequence number SQN and authentication management field AMF.
f_IMSAKA_f5star | Takes key K and random challenge RAND, and returns resynch anonymity key AK.
f_EAPSIM_A3A8 | Takes key Ki and random challenge RAND, and returns Kc and SRES keys
f_IMSAKA_calculateAUTN | Computes authentication token AUTN from anonymity key AK, random challenge RAND, sequence number SQN and authentication management field AMF.
f_calculateHMACMD5 | Calculate the 128 bit HMAC MD5 value of a message with specified 64 bit key.
f_calculate_HMAC_MD5 | Calculate the HMAC MD5 value of a message with specified key.
f_calculate_HMAC_SHA1 | Calculate the HMAC SHA1 value of a message with specified key.
f_calculate128_EEA3 | Purpose: Encrypt message using the confidentiality algorithm 128-EEA3
f_calculate128_EIA3 | Purpose: Calculate 32 bit message authentication code (MAC) using integrity algorithm 128-EIA3

### Functions

### f_calculateDigestResponse

> external function f_calculateDigestResponse(
> | charstring | nonce,
> | charstring | cnonce,
> | charstring | user,
> | charstring | realm,
> | charstring | passwd,
> | charstring | alg,
> | charstring | nonceCount,
> | charstring | method,
> | charstring | qop,
> | charstring | URI,
> | charstring | HEntity
> ) return charstring

#### Purpose

Calculate digest response

#### Parameters

nonce | in charstring - a server-specified data string which may ` be uniquely generated each time a 401 response is made
cnonce | in charstring - client nonce
user | in charstring - user name
realm | in charstring - user realm
passwd | in charstring - user password
alg | in charstring - a string indicating a pair of algorithms used to produce the digest and a checksum
nonceCount | in charstring - nonce count (8 hex digits)
method | in charstring - method (from the request)
qop | in charstring - qop-value: “”, “auth”, “auth-int”
URI | in charstring - digest URI
HEntity | in charstring - H(entity body) if qop=”auth-int”

#### Return Value

charstring | digest response

#### Errors

-

#### Detailed description

Support HTTP authentication (detailed description in RFC 2617) using uses one-way hash (md5) specified in RFC 1321. When a request arrives to server for an access-protected object, it responds an “401 Unauthorized” status code and a WWW-Authenticate header (encapsulate nonce and other necessary parameters). The client is expected to retry the request, passing an Authorization header with response field calculated with f_calculateDigestResponse().

Overview: http://en.wikipedia.org/wiki/Digest_access_authentication

### f_calculateDigestHA1

> external function f_calculateDigestHA1( | charstring | nonce,
> | charstring | cnonce,
> | charstring | user,
> | charstring | realm,
> | charstring | passwd,
> | charstring | alg | ) return charstring

#### Purpose

Calculate digest H(A1) hash

#### Parameters

nonce | in charstring - a server-specified data string which may ` be uniquely generated each time a 401 response is made
cnonce | in charstring - client nonce
user | in charstring - user name
realm | in charstring - user realm
passwd | in charstring - user password
alg | in charstring - a string indicating a pair of algorithms used to produce the digest and a checksum

#### Return Value

charstring | digest response

#### Errors

-

#### Detailed description

Overview: http://en.wikipedia.org/wiki/Digest_access_authentication

### f__TCCSecurity__hex2char

#### Purpose

Computes the 8 bit ASCII representation of an hexstring

#### Parameters

hex | in charstring - input value
str | out charstring - output value

#### Return Value

-

#### Errors

-

#### Detailed description

-

### f_calculateMD5

> external function f_calculateMD5( | in | charstring | pszHashInput | ) return charstring

#### Purpose

Compute MD5 hash value

#### Parameters

pszHashInput | in charstring - input value to compute MD5 hash

#### Return Value

charstring | hexa hash value of input

#### Errors

-

#### Detailed description

- MD5() is an openssl specific function, should be found under openssl/md5.h

### f_IMSAKA_f1

> external function f_IMSAKA_f1( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand,
> | in | octetstring | pl_sqn,
> | in | octetstring | pl_amf | ) return octetstring

#### Purpose

Computes network authentication code MAC-A from key K, random challenge RAND, sequence number SQN and authentication management field AMF.

#### Parameters

pl_k | in octetstring - key
pl_rand | in octetstring - random challenge
pl_sqn | in octetstring - sequence number
pl_amf | in octetstring - authentication management field

#### Return Value

octetstring | network authentication code MAC-A

#### Errors

-

#### Detailed description

-

### f_IMSAKA_f2

> external function f_IMSAKA_f2 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

#### Purpose

Takes key K and random challenge RAND, and returns response RES.

#### Parameters

pl_k | in octetstring - key
pl_rand | in octetstring - random challenge

#### Return Value

octetstring | response RES

#### Errors

-

#### Detailed description

-

### f_IMSAKA_f3

> external function f_IMSAKA_f3 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

#### Purpose

Takes key K and random challenge RAND, and returns confidentiality key CK.

#### Parameters

pl_k | in octetstring - key
pl_rand | in octetstring - random challenge

#### Return Value

octetstring | confidentiality key CK

#### Errors

-

#### Detailed description

-

### f_IMSAKA_f4

> external function f_IMSAKA_f4 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

#### Purpose

Takes key K and random challenge RAND, and returns integrity key IK.

#### Parameters

pl_k | in octetstring - key
pl_rand | in octetstring - random challenge

#### Return Value

octetstring | integrity key IK

#### Errors

-

#### Detailed description

-

### f_IMSAKA_f2345

> external function f_IMSAKA_f2345 (
> | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand
> ) return TCCSecurity_Keys

#### Purpose

Takes key K and random challenge RAND, and returns AK, CK, RES

#### Parameters

pl__OP | in octetstring - the operator variant algorithm configuration field
pl__k | in octetstring - key
pl__rand | in octetstring - random challenge

#### Return Value

TCCSecurity_Keys typed value Errors: -

#### Detailed description

-

### f_IMSAKA_f5

> external function f_IMSAKA_f5 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

#### Purpose

Takes key K and random challenge RAND, and returns anonymity key AK.

#### Parameters

pl_k | in octetstring - key
pl_rand | in octetstring - random challenge

#### Return Value

octetstring | anonymity key AK

#### Errors

-

#### Detailed description

-

### f_IMSAKA_f1star

> external function f_IMSAKA_f1star ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand,
> | in | octetstring | pl_sqn,
> | in | octetstring | pl_amf | ) return octetstring

#### Purpose

Computes resynch authentication code MAC-S from key K, random challenge RAND, sequence number SQN and authentication management field AMF.

#### Parameters

pl_k | in octetstring - key
pl_rand | in octetstring - random challenge
pl_sqn | in octetstring - sequence number
pl_amf | in octetstring - authentication management field

#### Return Value

octetstring | resynch authentication code MAC-S

#### Errors

-

#### Detailed description

-

### f_IMSAKA_f5star

> external function f_IMSAKA_f5star ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

#### Purpose

Takes key K and random challenge RAND, and returns resynch anonymity key AK.

#### Parameters

pl_k | in octetstring - key
pl_rand | in octetstring - random challenge

#### Return Value

octetstring | resynch anonymity key AK

#### Errors

-

#### Detailed description

-

### f_EAPSIM_A3A8

> external function f_EAPSIM_A3A8( | in | OCT_16 | Ki,
> |  | OCT_16 | rand,
> | out | octetstring | sres,
> | out | octetstring | Kc | )

#### Purpose

Takes key Ki and random challenge RAND, and returns Kc and SRES keys

#### Parameters

pl__Ki | in OCT_16 - the shared key
pl__rand | in octetstring - random challenge
pl__sres | out octetstring - authentication result param
pl__Kc | out octetstring - encryption key

#### Return Value

-

#### Errors

-

#### Detailed description

-

### f_IMSAKA_calculateAUTN

> external function f_IMSAKA_calculateAUTN( | in | OCT_6 | SQN,
> | in | OCT_6 | AK,
> | in | OCT_2 | AMF,
> | in | OCT_8 | MAC | ) return octetstring

#### Purpose

Computes authentication token AUTN from anonymity key AK, random challenge RAND, sequence number SQN and authentication management field AMF.

#### Parameters

pl__SQN | in OCT_6 - sequence number
pl__AK | in OCT_6 - anonymity key
pl__AMF | in OCT_2 - authentication management field
pl__MAC | in OCT_8 - encryption key

#### Return Value

octetstring | Authentication token - AUTN

#### Errors

-

#### Detailed description

-

### f_calculateHMACMD5

> external function f_calculateHMACMD5( | in | octetstring | msg,
> | in | OCT_64 | key | ) return octetstring

#### Purpose

Calculate the 128 bit HMAC MD5 value of a message with specified 64 bit key.

#### Parameters

msg | in octetstring - message to be hashed
key | in OCT_64 - 64 bit key of the hash function

#### Return Value

octetstring | Hash value (16 octet)

#### Errors

-

#### Detailed description

- key should be 64 bit long, output is 128 bit long

### f_calculate_HMAC_MD5

> external function f_calculate_HMAC_MD5(
> | in | octetstring | pl_key,
> | in | octetstring | pl_input,
> | in | integer | pl_length
> ) return octetstring

#### Purpose

Calculate the HMAC MD5 value of a message with specified key.

#### Parameters

pl_key | in octetstring - key of the hash function
pl_input | in octetstring - message to be hashed
pl_length | in integer - length of the output hash value (should be 16 in most of the cases)

#### Return Value

octetstring | Hash value

#### Errors

-

#### Detailed description

- key can be any length
- the length of output can be set in pl_length

### f_calculate_HMAC_SHA1

> external function f_calculate_HMAC_SHA1(
> | in | octetstring | pl_key,
> | in | octetstring | pl_input,
> | in | integer | pl_length
> ) return octetstring

#### Purpose

Calculate the HMAC SHA1 value of a message with specified key.

#### Parameters

pl_key | in octetstring - key of the hash function
pl_input | in octetstring - message to be hashed
pl_length | in integer - length of the output hash value (should be 16 in most of the cases)

#### Return Value

octetstring | Hash value

#### Errors

-

#### Detailed description

- key can be any length
- the length of output can be set in pl_length

### f_calculate128_EEA3

Purpose: Encrypt message using the confidentiality algorithm 128-EEA3

#### Parameters

key | in OCT_16 - confidentiality key
count | in OCT_4 - counter
bearer | in INT_5 - bearer identity
direction | in BIT_1 - direction of transmission
msg | in BIT_1_65504 - input bit stream (message to be encrypted)

#### Return Value

BIT_1_65504 | output bit stream (encrypted message)

#### Errors

-

#### Detailed description

-

### f_calculate128_EIA3

Purpose: Calculate 32 bit message authentication code (MAC) using integrity algorithm 128-EIA3

#### Parameters

key | in OCT_16 - integrity key key
count | in OCT_4 - counter
bearer | in INT_5 - bearer identity
direction | in BIT_1 - direction of transmission
msg | in BIT_1_65504 - input bit stream (the message)

#### Return Value

BIT_32 | message authentication code (MAC)

#### Errors

-

#### Detailed description

-

> external function f_calculateDigestResponse(
> | charstring | nonce,
> | charstring | cnonce,
> | charstring | user,
> | charstring | realm,
> | charstring | passwd,
> | charstring | alg,
> | charstring | nonceCount,
> | charstring | method,
> | charstring | qop,
> | charstring | URI,
> | charstring | HEntity
> ) return charstring

Calculate digest response

> external function f_calculateDigestHA1( | charstring | nonce,
> | charstring | cnonce,
> | charstring | user,
> | charstring | realm,
> | charstring | passwd,
> | charstring | alg | ) return charstring

Calculate digest H(A1) hash

> external function f_calculateMD5( | in | charstring | pszHashInput | ) return charstring

Compute MD5 hash value

> external function f_IMSAKA_f1( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand,
> | in | octetstring | pl_sqn,
> | in | octetstring | pl_amf | ) return octetstring

Computes network authentication code MAC-A from key K, random challenge RAND, sequence number SQN and authentication management field AMF.

> external function f_IMSAKA_f2 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

Takes key K and random challenge RAND, and returns response RES.

> external function f_IMSAKA_f3 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

Takes key K and random challenge RAND, and returns confidentiality key CK.

> external function f_IMSAKA_f4 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

Takes key K and random challenge RAND, and returns integrity key IK.

> external function f_IMSAKA_f2345 (
> | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand
> ) return TCCSecurity_Keys

Takes key K and random challenge RAND, and returns AK, CK, RES

> external function f_IMSAKA_f5 ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

Takes key K and random challenge RAND, and returns anonymity key AK.

> external function f_IMSAKA_f1star ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand,
> | in | octetstring | pl_sqn,
> | in | octetstring | pl_amf | ) return octetstring

Computes resynch authentication code MAC-S from key K, random challenge RAND, sequence number SQN and authentication management field AMF.

> external function f_IMSAKA_f5star ( | in | octetstring | pl_OP,
> | in | octetstring | pl_k,
> | in | octetstring | pl_rand | ) return octetstring

Takes key K and random challenge RAND, and returns resynch anonymity key AK.

> external function f_EAPSIM_A3A8( | in | OCT_16 | Ki,
> |  | OCT_16 | rand,
> | out | octetstring | sres,
> | out | octetstring | Kc | )

Takes key Ki and random challenge RAND, and returns Kc and SRES keys

> external function f_IMSAKA_calculateAUTN( | in | OCT_6 | SQN,
> | in | OCT_6 | AK,
> | in | OCT_2 | AMF,
> | in | OCT_8 | MAC | ) return octetstring

Computes authentication token AUTN from anonymity key AK, random challenge RAND, sequence number SQN and authentication management field AMF.

> external function f_calculateHMACMD5( | in | octetstring | msg,
> | in | OCT_64 | key | ) return octetstring

Calculate the 128 bit HMAC MD5 value of a message with specified 64 bit key.

> external function f_calculate_HMAC_MD5(
> | in | octetstring | pl_key,
> | in | octetstring | pl_input,
> | in | integer | pl_length
> ) return octetstring

Calculate the HMAC MD5 value of a message with specified key.

> external function f_calculate_HMAC_SHA1(
> | in | octetstring | pl_key,
> | in | octetstring | pl_input,
> | in | integer | pl_length
> ) return octetstring

Calculate the HMAC SHA1 value of a message with specified key.