LibIpv6_ExternalFunctions.ttcn

/*
 *	@author 	STF 276
 *  @version 	$Id$
 *	@desc		This module collects external functions available
 *              to any function implementation in the IPv6 lirbary or
 *              ATS. Notice that the test case execution is only possible
 *              if a Platform Adapter with their implementation is used
 *              by the test system.
 */
 module LibIpv6_ExternalFunctions {
	
	//LibCommon
	import from LibCommon_BasicTypesAndValues all;
	import from LibCommon_DataStrings all;
	import from LibCommon_VerdictControl all;
	//LibIpv6
	import from LibIpv6_CommonRfcs_TypesAndValues { type all };
	import from LibIpv6_Interface_TypesAndValues all;
	import from LibIpv6_Rfc4306Ikev2_TypesAndValues all;

	/* @desc    This external function translates an IPv4 address string
	 *          in its octetstring representation.
	 * @param   p_address charstring representation of an IPv4 address
	 * @return  Ipv4Address octetstring representation
	*/
	external function fx_translateIpv4Address( in charstring p_address ) 
	return Ipv4Address;

	/* @desc    This external function translates an IPv6 address string
	 *          in its octetstring representation.
	 * @param   p_address charstring representation of an IPv6 address
	 * @return  Ipv6Address octetstring representation
	*/
	external function fx_translateIpv6Address( in charstring p_address ) 
	return Ipv6Address;

	/* @desc    This external function calculates the payload length
	 *			of a IPv6 packet. If ESP Hdr is used, then payload is encrypted before calculation of the length.
	 * @param   p_msg Ipv6 packet
	 * @return  payload length in bytes
	*/
	external function fx_payloadLength( in template Ipv6Packet p_msg ) 
	return UInt16;

	/* @desc    This external function calculates the total length
	 *			of a IPv4 packet.
	 * @param   p_msg Ipv4 packet
	 * @return  payload length in bytes
	*/
	external function fx_ipv4PacketTotalLength( in template Ipv4Packet p_msg ) 
	return UInt16;
	
	/* @desc    This external function calculates the payload length
	 *			of a IPv6 packet
	 * @param   p_msg Ipv6 packet
	 * @param   p_entry Nr of Tunnelled packet within the IPv6Packet
	 * @return  payload length in bytes
	*/
	external function fx_tunnelledPayloadLength( template Ipv6Packet p_msg, in UInt8 p_entry ) 
	return UInt16;
	
	/* @desc   Calculates the checksum over the IPv6 payload
	 * @param  p_srcAddress Source Address
	 * @param  p_dstAddress Destination Address
	 * @param  p_payload Checksum is calculated over this
	 * @param  p_nextHeader Needed for the checksum calculation
	 * @return checksum value
	*/
	external function fx_calcPayloadChecksum(in template Ipv6Address p_srcAddress,	
											 in template Ipv6Address p_dstAddress, 
											 in template Ipv6Payload p_payload,
											 in UInt8 p_nextHeader) 
	return Oct2;

	/* @desc   Calculates the checksum over the IPv4 payload
	 * @param  p_payload Checksum is calculated over this
	 * @return checksum value
	*/
	external function fx_calcIpv4PayloadChecksum(in template Ipv4Payload p_payload) 
	return Oct2;

	/* @desc   Calculates the header checksum (HCS) over the IPv4 header
	 * @param  p_ipv4Header Checksum is calculated over this
	 * @return checksum value
	*/
	external function fx_calcIpv4Hcs(in template Ipv4Header p_ipv4Header) 
	return Oct2;
	
	/* @desc 	This external function runs the Ipv6Packet through Codec and returns 
	 *			the octetstring representing the Ipv6Packet
	*/
	external function fx_encodeMessage (in template Ipv6Packet p_msg)
	return octetstring;

	/* @desc   This external function calculates the checksum for MIPv6 Header.
	 *	       If HomeAddressOption present, then this external function is called with the
	 *		   HomeAddress as Source Address
	 * @param  p_srcAddr Source Address to be used for Checksum calculation
	 * @param  p_dstAddr MobileHeader
	 * @param  p_mobileHeader MobileHeader
	 * @return MIPv6 Header checksum
	*/
	external function fx_mipHeaderChecksum( in Ipv6Address p_srcAddr,
											in Ipv6Address p_dstAddr,
											in MobileHeader p_mobileHeader) 
	return Oct2;

	/* @desc   This external function calculates the length of MIPv6 Header.
	 * @param  p_mobileHeader MobileHeader
	 * @return MIPv6 Header length
	*/
	external function fx_mipHeaderLength( in  MobileHeader p_mobileHeader) 
	return UInt8;

	/* @desc 	This external function runs the MobileHeader through Codec and returns 
	 *			the octetstring representing the MobileHeader
	 *			
	 * @param 	p_mobileHeader Mip Header to be encoded to octetstring
	 * @return 	octetstring
	*/
	external function fx_mipHdrToOct(MobileHeader p_mobileHeader)
	return octetstring;

	/* @desc    Apply indicated Integrity algorithm to the message. Message is an octetstring.
	 *			If e_sha1_96 is chosen, then the key input shall be ignored.
	 *			
	 * @param  p_integrityAlgo Cryptographic function used to compute MAC
	 * @param  p_key Key used to compute the MAC
	 * @param  p_message Octetstring message
	 * @return Message HMAC
	*/
	external function fx_mac( IntegrityAlgo p_integrityAlgo, in octetstring p_key, in octetstring p_message) 
	return octetstring;

	/* @desc 	This external function sets the test adapter with the relevant security parameters
	*			
	* @param 	p_sa Security Association
	* @return 	FncRetCode
	*/
	external function fx_setSecurityParameters(in Sad p_sa)
	return FncRetCode;

	/* @desc 	This external function sets the test adapter with the relevant security parameters
	*			
	* @param 	p_IkeSa IKE Security Association
	* @return 	FncRetCode
	*/
	external function fx_setIkeSecurityParameters(in IkeSa p_ikeSa)
	return FncRetCode;
	
	/* @desc    This external function calculates the payload length
	 *			of an IPv6 authentication header
	 * @param   p_authHeader Authentication Header
	 * @return  payload length in 32-bits words
	*/
	external function fx_authHeaderPayloadLength(in template AuthHeader p_authHeader) return UInt8;

	/* @desc	This external function implements the negotiated
	 *         	pseudo random function and calcutes pseudo random value
	 *			based on the two input strings.
	 * @param   p_prf negotiated PseudoRandomFunction
	 *			choice is:
	 *			e_prfHmacMd5(1),
	 *			e_prfHmacSha1(2),
	 *			e_prfHmacTiger(3),
	 *			e_prfAes128Xcbc(4)
	 * @param   p_first, p_second input values to pseudo random function
	 * @return  pseudo random value 
	*/
	external function fx_pseudoRandom( in PseudoRandomFunction p_prf,
									   in octetstring p_first,
									   in octetstring p_second ) 
	return octetstring;

	/* @desc	This external function implements the negotiated
	 *         	pseudo random function and calcutes the seven secrets
	 *			based on the two input strings.
	 *			SK_d  = prf (p_first, S | 0x01)
   	 *			SK_ai = prf (p_first, SK_d  | p_second | 0x02)
   	 *			SK_ar = prf (p_first, SK_ai | p_second | 0x03)
  	 *			SK_ei = prf (p_first, SK_ar | p_second | 0x04)
  	 *			SK_er = prf (p_first, SK_ei | p_second | 0x05)
  	 *			SK_pi = prf (p_first, SK_er | p_second | 0x06)
  	 *			SK_pr = prf (p_first, SK_pi | p_second | 0x07)
	 *			The key lenghts of Encryption Key, Integrity Key and PRF Key must be set in IkeSa before fx_pseudoRandomPlus is called.
	 * @param   p_ikeSa containing negotiated PseudoRandomFunction
	 *			choice is:
	 *			e_prfHmacMd5(1),
	 *			e_prfHmacSha1(2),
	 *			e_prfHmacTiger(3),
	 *			e_prfAes128Xcbc(4)
	 * @param   p_first, p_second input values to pseudo random function
	 * @return  pseudo random value 
	*/
	external function fx_pseudoRandomPlus( in IkeSa p_ikeSa,
									  	   in octetstring p_first,
									   	   in octetstring p_second ) 
	return SevenSecrets;
	
	/* @desc	This external function implements the negotiated
	 *         	pseudo random function and calcutes pseudo random value
	 *			based on the two input strings.
	 * @param   p_prf negotiated PseudoRandomFunction
	 *			choice is:
	 *			e_prfHmacMd5(1),
	 *			e_prfHmacSha1(2),
	 *			e_prfHmacTiger(3),
	 *			e_prfAes128Xcbc(4)
	 * @param   p_first, p_second input values to pseudo random function
	 * @param   p_EncIntKeys input/output value carries a record of 
	 *          encryption and integrity key lengths and key values
	 *          Input value contains only the key lengths, 
	 *          length values set to 0 indicate that no correspondent keys need to be calculated.
	 *          Output value contains key values taken from KEYMAT
	 *          according to the rules of RFC4306, clause 2.17.
	*/
	external function fx_calculateKEYMATandDistribute ( in PseudoRandomFunction p_prf,
									   in octetstring p_first,
									   in octetstring p_second,
									   inout EncIntKeys p_encIntKeys) 
	return FncRetCode;

	/* @desc	This external function implements the Diffie-Hellman procedure
	 *         	and calculates the key for the Key Exchange payload to be sent to the 
	 *			peer based on the private key and the number of the Diffie-Hellman group.
	 *			Prime and generator for the Diffie-Hellman groups are found in:
	 *			Group 1 and 2: RFC4306 Appendix B
	 *			Group 5, 14, 15, 16, 17 and 18: RFC3526
	 * @param   p_diffieHellmanGroup chosen Diffie-Hellman group
	 * @param   p_diffieHellmanPrivKey private key taken from PIXIT value
	*/
	external function fx_dHKeyToSend( in DiffieHellmanGroup p_diffieHellmanGroup,
									  in octetstring p_diffieHellmanPrivKey ) 
	return octetstring;

	/* @desc	This external function implements the Diffie-Hellman procedure
	 *         	and calculates the shared secret based on the private key,
	 *			the received key from the Key Exchange payload and the number
	 *			of the Diffie-Hellman group.
	 *			Prime and generator for the Diffie-Hellman groups are found in:
	 *			Group 1 and 2: RFC4306 Appendix B
	 *			Group 5, 14, 15, 16, 17 and 18: RFC3526
	 * @param   p_diffieHellmanGroup chosen Diffie-Hellman group
	 * @param   p_diffieHellmanPrivKey private key taken from PIXIT value
	 * @return  p_receivedKey received key taken from Key Exchange payload 
	*/
	external function fx_dHSharedSecret( in DiffieHellmanGroup p_diffieHellmanGroup,
									     in octetstring p_diffieHellmanPrivKey,
									     in octetstring p_receivedKey) 
	return octetstring;

	/* @desc 	This external function runs the IkePayloadList through Codec and returns 
	 *			the octetstring representing the IkePayloadList. If encrypted payload is part of the payload list,
	 *			then the ecncrypted octet string is returned.
	 *			
	 * @param 	p_ikev2Header Ikev2Header to be encoded to octetstring
	 * @return 	octetstring
	*/
	external function fx_ikePayloadListToOct(in IkePayloadList p_ikePayloadList)
	return octetstring;

	/* @desc 	This external function runs the Ikev2Header through Codec and returns 
	 *			the octetstring representing the Ikev2Header
	 *			
	 * @param 	p_ikev2Header Ikev2Header to be encoded to octetstring
	 * @return 	octetstring
	*/
	external function fx_ikev2HeaderToOct(Ikev2Header p_ikev2Header)
	return octetstring;

	/* @desc    This external function calculates the payload length
	 *			of the IKE encrypted payload. Before calculating the length, the payload is encrypted in the test adapter.
	 * @param   p_msg Ipv6 packet
	 * @return  payload length in bytes
	*/
	external function fx_ikeEncPayloadLength( in Ipv6Packet p_msg ) 
	return UInt16;

}// end module LibIpv6_ExternalFunctions