path: root/doc/EAP_CNL133722_1551_1.adoc

---
Author: Máté Kovács
Version: 1551-CNL 113 722, Rev. E
Date: 2017-02-02

---
= EAP Protocol Module for TTCN-3 Toolset with TITAN, Description
:author: Máté Kovács
:revnumber: 1551-CNL 113 722, Rev. E
:revdate: 2017-02-02
:toc:

== Presumed Knowledge

To use this protocol module the knowledge of the TTCN-3 language <<_1, [1]>> is essential.

== System Requirements

Protocol modules are a set of TTCN-3 source code files that can be used as part of TTCN-3 test suites only. Hence, protocol modules alone do not put specific requirements on the system used. However, in order to compile and execute a TTCN-3 test suite using the set of protocol modules the following system requirements must be satisfied:

Titan TTCN-3 Test Executor version CRL 113 200 R7A (1.7.pl0) or higher installed. For Installation Guide see <<_2, [2]>>.

NOTE: This version of the test port is not compatible with Titan releases earlier than CRL 113 200 R7A.

= Usage

== Overview

Protocol modules implement the messages structure of the related protocol in a formalized way, using the standard specification language TTCN-3. This allows defining of test data (templates) in the TTCN-3 language <<_1, [1]>> and correctly encoding/decoding messages when executing test suites using the TITAN TTCN-3 test environment.

Protocol modules are using TITAN’s RAW encoding attributes <<_2, [2]>> and hence is usable with the TITAN test toolset only.

== Installation

The set of protocol modules can be used in developing TTCN-3 test suites using any text editor; however, to make the work more efficient a TTCN3enabled text editor is recommended (for example nedit, xemacs). Since the GTPv2 v10.6.0 protocol is used as a part of a TTCN-3 test suite, this requires TTCN-3 Test Executor be installed before the module can be compiled and executed together with other parts of the test suite. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, [2]>>.

== Configuration

None.

== Implemented Protocols

This set of protocol modules implements protocol messages and constants of RFCs of EAP, EAP-AKA, EAP-AKA’, EAP-SIM, EAP-TTLS.

== Implemented Messages

The following messages will be implemented: All message defined in <<_3, [3]>>, <<_4, [4]>>, <<_5, [5]>>, <<_6, [6]>> and <<_7, [7]>>.

[[protocol-modifications-deviations]]
== Protocol Modifications/Deviations

There are currently no deviations from the mentioned standards.

== Backward Incompatibilities

None.

= Implementation Specifics

The `enc_EAP_PDU` and `dec_EAP_PDU` are used to encode and decode the given TTCN PDU_EAP type to octetsting and vice versa respectedly.

The other functions implemented in the Protocol Module are used in junction with the EAP protocol to compute the various parameters in the EAP messages. A usage example can be found in section <<implemented_encoding_and_decoding_functions, Implemented Encoding and Decoding Functions>>. List of the functions implemented can be found in the Function Specification.

= Interface Description

[[encoding-decoding-and-other-related-functions]]
== Encoding/Decoding and Other Related Functions

This product also contains encoding/decoding functions that assure correct encoding of messages when sent from Titan and correct decoding of messages when received by Titan. Other implemented functions are used with the EAP protocol parameter computing.

[[implemented_encoding_and_decoding_functions]]
== Implemented Encoding and Decoding Functions

[cols=3*,options=header]
|===

|Name
|Type of formal parameters
|Type of return value

|`enc_PDU_EAP`
|PDU_EAP
|octetstringdec_PDU_EAP octetstring

|`dec_PDU_EAP`
|octetstring
|PDU_EAP

|`enc_AKA_Attrib`
|EAP_AKA_Attrib_List
|octetstring

|`dec_AKA_Attrib`
|octetstring
|EAP_AKA_Attrib_List

|`f_enc_eap_sim_attrib_list`
|EAP_SIM_Attrib_List
|octetstring

|`f_dec_eap_sim_attrib_list`
|octetstring
|EAP_SIM_Attrib_List

|`f_enc_eap_aka_attrib_list`
|EAP_AKA_Attrib_List
|octetstring

|`f_dec_eap_aka_attrib_list`
|octetstring
|EAP_AKA_Attrib_List

|`f_enc_tls_handshakeData`
|TLS_HandshakeData
|octetstring

|`f_dec_tls_handshakeData`
|octetstring
|TLS_HandshakeData_t

|`eap_sim_derive_mk`
|octetstring
|octetstring

|`fips186_2_prf`
|octetstring
|octetstring

|`eap_aka_derive_mk`
|octetstring
|octetstring

|`eap_aka_derive_reauth_msk_emsk`
|octetstring
|octetstring

|`eap_akaprime_derive_mk`
|octetstring
|octetstring

|`Calculate_AT_CheckCode`
|octetstring
|octetstring

|`f_calc_Kaut`
|octetstring
|octetstring

|`f_calc_AKA_Keys`
|octetstring
|octetstring

|`f_get_ServersPublicKey`
|octetstring
|octetstring

|`f_prf`
|octetstring
|octetstring
|===

== Authentication and Encryption Key Generation

The following functions are implemented in TCCUsefulFunctions_CNL113472 <<_8, [8]>> / `TCCSecurity_Functions` module, which were earlier part of the EAP Protocol Module:

[cols=2*,options=header]
|===

|Deleted
|Use this from `TCCSecurity_Functions`

|A3A8
|`f_EAPSIM_A3A8`

|hmac_sha1_128_vector
|`f_calculate_HMAC_SHA1`

|aes_128_cbc_decrypt
|`f_AES_CBC_128_Decrypt_OpenSSL`

|aes_128_cbc_encrypt
|`f_AES_CBC_128_Encrypt_OpenSSL`

|f1
|`f_IMSAKA_f1`

|f2345
|`f_IMSAKA_f2345`

|f1star
|`f_IMSAKA_f1star`

|f5star
|`f_IMSAKA_f5star`

|akaprime_hmac_sha256_vector
|`f_calculate_HMAC_SHA256`

|f_calc_SRES
|`f_EAPSIM_A3A8`

|f_sha1_256
|`f_calculate_HMAC_SHA256`

|f_sha1
|`f_calculate_HMAC_SHA1`

|f_md5
|`f_calculateMD5`

|f_calc_EAPSIM_Keys
|`f_EAPSIM_A3A8`
|===

A `Master Key` is derived from the underlying GSM authentication values (`Kc keys`), the `nonce_mt`, and other relevant context as follows.

[source]
----
function eap_sim_derive_mk(octetstring identity, octetstring nonce_mt,integer selected_version, octetstring ver_list, octetstring kc) return octetstring;
----

On EAP-AKA full authentication, a `Master Key (MK)` is derived from the underlying AKA values (`CK` and `IK keys`), and the identity, as follows.

[source]
function eap_aka_derive_mk(octetstring identity, octetstring ik, octetstring ck) return octetstring;

On EAP-AKA fast re-authentication, the `XKEY’` as the seed value of the pseudo-random generator for the `Master Session Key (MSK)` and the `Extended Master Session Key (EMSK)` is derived from the underlying AKA value (`Master Key`), the `nonce_s` and the counter values and the identity, as follows.

[source]
----
function eap_aka_derive_reauth_msk_emsk(octetstring identity, octetstring counter, octetstring nonce_s, octetstring mk) return octetstring;
----

The `_checkcode_` is a hash value, calculated with SHA1 [SHA-1], over all EAP-Request/AKA-Identity and EAP-Response/AKA-Identity packets exchanged in the authentication exchange.

[source]
function Calculate_AT_CheckCode(octetstring rcveap,octetstring sendeap) return octetstring;

When generating `Kaut` and `Kenc` the input octetstring is concatenated from `identifier, A3A8, nonce_mt, version list` and `selected version`.

[source]
function f_calc_Kaut(in octetstring input,inout octetstring kencr) return octetstring;

The function below calculates `XDOUT`, `Kencr`, `Kaut` and `AK` values. `Kaut` is used when calculating MAC values, `Kencr` is used for encryption and decryption of `AT_ENCR_DATA` attributes, and `AK` is used for calculating and verifying `AT_AUTN` and `AT_AUTS` values.

[source]
----
function f_calc_AKA_Keys(in octetstring pl_eap_identity, in octetstring pl_AKA_K,in octetstring pl_rand, inout octetstring pl_AK,inout octetstring pl_Kaut,inout octetstring pl_Kencr) return octetstring

eap_sim_derive_mk rfc4186
eap_aka_derive_mk rfc4187
eap_aka_derive_reauth_msk_emsk rfc4187
Calculate_AT_CheckCode rfc4187
f_calc_Kaut rfc5448
f_get_ServersPublicKey rfc5247
f_prf rfc5281
----

= Examples

== EAP Packet Encoding and Decoding

The following example shows how an EAP packet can be encoded and decoded.

[source]
----
var PDU_EAP v_EAP_PDU;
var octetstring data;

data:= enc_PDU_EAP(v_EAP_PDU);

v_EAP_PDU := dec_PDU_EAP(data);
----

== Computation of MAC Parameter in an EAP Message

The following example shows how an EAP packet MAC parameter can be computed with the

[source]
----
import from TCCSecurity_Functions all;
[…]
var EAP_PDU v_packetToSend_EAP;
var octetstring v_ck, v_ik, v_name;

var octetstring vl_mk:= eap_akaprime_derive_mk(v_name, v_ik,v_ck);
var octetstring vl_k_aut := substr(vl_mk,16,32);
var octetstring vl_macFull :=
f_calculate_HMAC_SHA256 (vl_k_aut,enc_PDU_EAP(v_packetToSend_EAP),32);
var octetstring vl_mac :=substr(vl_macFull,0,16);
----

= Terminology

== Abbreviations

EAP Extensible Authentication Protocol

PDU Protocol Data Unit

IETF Internet Engineering Task Force

TTCN-3 Testing and Test Control Notation version 3

[[terminology-0]]
== Terminology

TITAN TTCN-3 Test Executor (see <<_2, [2]>>).

= References

[[_1]]
[1] ETSI ES 201 873-1 v4.5.1 (2013-04) The Testing and Test Control Notation version 3. Part 1: Core Language

[[_2]]
[2] User Guide for TITAN TTCN-3 Test Executor

[[_3]]
[3] IETF https://tools.ietf.org/html/rfc3748[RFC 3748] +
Extensible Authentication Protocol (EAP)

[[_4]]
[4] IETF https://tools.ietf.org/html/rfc4187[RFC 4187] +
Extensible Authentication Protocol Method for 3rd Generation Authentication and Key Agreement (EAP-AKA)

[[_5]]
[5] IETF https://tools.ietf.org/html/rfc5448[RFC 5448] +
Improved Extensible Authentication Protocol Method for 3rd Generation Authentication and Key Agreement (EAP-AKA')

[[_6]]
[6] IETF https://tools.ietf.org/html/rfc4186[RFC 4186] +
Extensible Authentication Protocol Method for Global System for Mobile Communications (GSM) Subscriber Identity Modules (EAP-SIM)

[[_7]]
[7] IETF https://tools.ietf.org/html/rfc768[RFC 5281] +
Extensible Authentication Protocol Tunneled Transport Layer Security-Authenticated Protocol Version 0 (EAP-TTLSv0)

[[_8]]
[8] TCC Useful Functions for TTCN-3 Toolset with TITAN