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.