IETF pana WG Y. Kainuma Internet-Draft F. Teraoka Intended status: Informational KEIO University Expires: December 3, 2006 June 2006 The PANA API draft-hiko-pana-api-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on December 3, 2006. Copyright Notice Copyright (C) The Internet Society (2006). Kainuma & Teraoka Expires December 3, 2006 [Page 1] Internet-Draft PANA API June 2006 Abstract Protocol for carrying Authentication for Network Access (PANA) provides support for authentication for network access between end- user and the Internet. This document proposes the design a standardised API for the PANA protocol. The API is defined in the C language. The goal of the API is to foster extensible PANA implementation. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. API specifications . . . . . . . . . . . . . . . . . . . . . . 5 2.1. MultiThread . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Result Reporting . . . . . . . . . . . . . . . . . . . . . 5 2.3. List Structures . . . . . . . . . . . . . . . . . . . . . 5 2.4. EP Control . . . . . . . . . . . . . . . . . . . . . . . . 6 2.5. Configuration Files . . . . . . . . . . . . . . . . . . . 6 3. Data Type Definitions . . . . . . . . . . . . . . . . . . . . 7 3.1. Constant Types . . . . . . . . . . . . . . . . . . . . . . 7 3.2. Timer Event Handle . . . . . . . . . . . . . . . . . . . . 14 3.3. Filtering Policy on the EP . . . . . . . . . . . . . . . . 14 3.4. Result Code AVP Value . . . . . . . . . . . . . . . . . . 14 3.5. Return Code . . . . . . . . . . . . . . . . . . . . . . . 15 3.6. Callback Location Codes . . . . . . . . . . . . . . . . . 17 3.7. AVP Data Type Codes . . . . . . . . . . . . . . . . . . . 17 3.8. Search Direction Type . . . . . . . . . . . . . . . . . . 18 4. Structure Definitions . . . . . . . . . . . . . . . . . . . . 19 4.1. AVP Structure . . . . . . . . . . . . . . . . . . . . . . 19 4.2. ISP/NAP-Information AVP Value . . . . . . . . . . . . . . 19 4.3. Notification AVP Value . . . . . . . . . . . . . . . . . . 20 4.4. AVP List . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.5. PANA Message . . . . . . . . . . . . . . . . . . . . . . . 20 4.6. PANA Session . . . . . . . . . . . . . . . . . . . . . . . 22 4.7. PANA Session List . . . . . . . . . . . . . . . . . . . . 23 4.8. Dictionary Entry . . . . . . . . . . . . . . . . . . . . . 24 5. API Definitions . . . . . . . . . . . . . . . . . . . . . . . 25 5.1. Initialization and Configuration . . . . . . . . . . . . . 25 5.2. Registering Callbacks . . . . . . . . . . . . . . . . . . 26 5.3. PANA Session Management . . . . . . . . . . . . . . . . . 28 5.4. PANA Operation . . . . . . . . . . . . . . . . . . . . . . 31 5.5. EP Control . . . . . . . . . . . . . . . . . . . . . . . . 38 5.6. Dictionary Lookup . . . . . . . . . . . . . . . . . . . . 39 Kainuma & Teraoka Expires December 3, 2006 [Page 2] Internet-Draft PANA API June 2006 5.7. Message Management . . . . . . . . . . . . . . . . . . . . 41 6. Security Consideration . . . . . . . . . . . . . . . . . . . . 49 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 Intellectual Property and Copyright Statements . . . . . . . . . . 52 Kainuma & Teraoka Expires December 3, 2006 [Page 3] Internet-Draft PANA API June 2006 1. Introduction Protocol for carrying Authentication for Network Access (PANA) provides secure network access [1]. This document describes the design of an API in C for applications to implement PANA. PANA is used with an Authorization, Authentication and Accounting (AAA) protocol such as Diameter and Radius. So the PANA API must be compatible with Diameter and Radius. This API is designed to combine with Diameter API which is proposed in [2]. This API will help to implement the AAA architecture using PANA and Diameter. PANA is developing protocol and may be changed partially. This API provides only the basic function and depends on the implementation for some function (e.g. PAA-EP communication, NAP/ISP authentication, EP driven PAA discover, and so on). This means that API users can extend PANA protocol to suite your goals using this API. We provide a simple example of an implementation of the PANA protocol using this API at the tail of this document. Kainuma & Teraoka Expires December 3, 2006 [Page 4] Internet-Draft PANA API June 2006 2. API specifications 2.1. MultiThread PANA API uses multithread. PANA API's operation includes listening the messages, manegement of the timer, executing the callback, and so on. They should be performed by different thread because they may be performed at one time. Conflicts of data-access may occur in the system using multithread. Thus, API implementers must be careful not to create a situation where one PANA Session interferes with other PANA Sessions. 2.2. Result Reporting PANA API reports results which contain detailed descriptions of any errors. API implementers are encouraged to output errors to log files so that API users can be made aware of why errors has occurring. 2.3. List Structures The PANA API defines list structures. This section describes how these structures are used. 2.3.1. PANA Sessions The PAA can have multiple PANA Sessions. The PAA must distinguish PANA Sessions in individual cases. PANA Sessions are distinguished by a session identifier. The session identifier of a PANA Session is initialized by the PAA and is globally and eternally unique. The method of how to initialize the session identifier is the same as the method defined in Diameter [3]. A PANA Session must be added to the PANA Session List when the session is initialized, and must be deleted from the PANA Session List when the session is terminated. 2.3.2. AVPs All PANA Messages have many AVPs in an AVP List. The PaC and PAA refer to the AVP List when they parce the PANA Messages. AVP List is initialized when a PANA Message is created. 2.3.3. Callbacks PANA API defines callbacks which are called by events when receiving messages and passing times. Callbacks are identified by a PANACallBackHandle, which is generated when the callback is registered. Kainuma & Teraoka Expires December 3, 2006 [Page 5] Internet-Draft PANA API June 2006 2.3.3.1. Message Callback If Message Callback is registered, registered callback is called when the PANA Messages are received. Callbacks are registered with PANA Message Code. 2.3.3.2. Timer Callback If a Timer Callback is registered, it is called when a block of time has passed. Callbacks are registered with a Timer Event Handle. 2.4. EP Control The function of an EP is per-packet policy enforcement. A PAA tells an EP how policies are enforced. [4] details that SNMP is used for EP-PAA communication. But how to communicate with EP is implementation dependent. And [1] details that an EP may trigger PaC discovery. This API does not define how to discover PaC's. Thus, this function is implementation dependent. 2.5. Configuration Files The PANA API uses configuration files. This section describes how these configuration files are used. These configuration files should be written in XML due to the existence of many available XML parsing libraries. 2.5.1. Dictionary File PANA Messages are created and parsed by the PaC or PAA. The Pac and PAA can identify which PANA Messages and AVPs are supported from the contents of the Message Dictionary File. The location and name of Message Dictionary File are platform-specific. 2.5.2. Configuration File The PaC and PAA can learn how to initialize PANA Sessions and PANA Messagesfrom the contents of the Configuration File. The Configuration File contains environment-specific information (e.g. IP address, device identifier) and operational information (e.g. how to discover the PAA). Kainuma & Teraoka Expires December 3, 2006 [Page 6] Internet-Draft PANA API June 2006 3. Data Type Definitions 3.1. Constant Types 3.1.1. IP address and Port typedef struct sockaddr_storage PANA_IP_ADDR; PANA_IP_ADDR provides a way of referring to IP address and port information. This data supports both IPv4 and IPv6. 3.1.2. Vendor Identifier typedef uint32_t PANAVendorID; PANAVendorID provides a way of referring to the vendor identification code. This is used when creating messages and registering callbacks. 3.1.3. Value Type Identifier typedef uint32_t PANAValue; PANAValue provides a way of referring to particular dictionary- defined values. This is used when looking up the dictionary. 3.1.4. Device Identifier typedef void PANADeviceID; PANADeviceID provides a way of referring to the device identifier such as MAC address. This is used as one of the PANA Session parameters. 3.1.5. Session Identifier typedef void PANASessionID; PANASessionID is an identifier for a particular PANA Session. The format of session identifier is same as is defined in [3] 3.1.6. Cookie typedef void Cookie; Cookie is a random value that is generated according to [6]. This is used for making PAA discovery robust against blind resource consumption DoS attacks. Kainuma & Teraoka Expires December 3, 2006 [Page 7] Internet-Draft PANA API June 2006 3.1.7. Callback Handle typedef void PANACallbackHandle; The PANACallbackHandle is a type for representing the callback handle returned to the client when a callback is registered. This handle is used when de-registering a callback from the Callbacl List. 3.1.8. Message Authentication Code typedef void MACvalue; MACValue is an encrypted message used for ensuring message integrity. This is a cipher of the PANA Message using the session key and a particular configured algorithm. 3.1.9. Provider Information 3.1.9.1. Provider Identifier typedef uint32_t PANAProviderID; PANAProviderID provides a way of referring to the Provider identification code. The value of Provider identifier is assigned by IANA. This is used in the ISP-Information AVP of NAP-Information AVP. 3.1.9.2. Provider Name typedef void PANAProviderName; PANAProviderName is of type UTF8String, and contains the UTF8-encoded name of the provider. This is used in the ISP-Information AVP or NAP-Information AVP. 3.1.10. Key Materials 3.1.10.1. Key Identifier typedef uint32_t MSKIdentifier; MSKIdentifier provides a way of referring to the MSK using an Identifier code. This value is assigned by the PAA and must be unique within the PANA Session. Kainuma & Teraoka Expires December 3, 2006 [Page 8] Internet-Draft PANA API June 2006 3.1.10.2. MSK typedef void MSK; MSK is a key generated by an EAP method. This is one of the materials that derives all keys used in the PANA Session. 3.1.10.3. PANA-AUTH-KEY typedef void PANAAuthKey; PANA-AUTH-KEY is a key derived from the MSK. the length of a PANAAuthKey varies depending on which algorithm is used to calculate the PANA-AUTH-KEY. This key is used to generate a Message Authentication Code. 3.1.10.4. PaC-EP-Master-Key typedef void PaCEPMasterKey; PaC-EP-Master-Key is a key derived from the MSK. The length of the PaCEPMasterKey is 64 octets. This key is used to filter packets between a PaC and EP. 3.1.10.5. nonce typedef void Nonce; Nonce has random value and the length of Nonce must be between 8 and 256 octets inclusive. This is one of the materials of which all keys used in the PANA Session are derived. 3.1.11. PANA Message Type typedef uint16_t PANAMessageType; PANAMessageType contains 2 octets of data and is managed by IANA. This value is used to communicate the message type associated with the message. 3.1.12. Pseudo-random Function The following values are difined in [7]. The Pseudo-random Function is one of the PANA Session attributes. This is used when deciding the function that derives the PANA-AUTH-KEY and PaC-EP-Master-Key. All PANA implementations must support PRF_HMAC_SHA1: Kainuma & Teraoka Expires December 3, 2006 [Page 9] Internet-Draft PANA API June 2006 typedef enum { PRF_HMAC_MD5, PRF_HMAC_SHA1, PRF_HMAC_TIGER, PRF_AES128_CBC } PseudoRandomFunction; 3.1.13. Integrity Algorithm The following values are defined in [7]. The Integrity Algorithm is used for computing the AUTH AVP value. All PANA implementations must support AUTH_HMAC_SHA1_160: typedef enum { NONE, AUTH_HMAC_MD5_96, AUTH_HMAC_SHA1_96, AUTH_DES_MAC, AUTH_KDPK_MD5, AUTH_AES_XCBC_96, AUTH_HMAC_SHA1_160 } IntegrityAlgorithm; 3.1.14. AVP Codes The following values are AVP Codes which are used in PANA. They are defined in the PANA specification [1]: typedef enum { AVP_ALGORITHM = 1, AVP_AUTH, AVP_COOKIE, AVP_DEVICE_ID, AVP_EAP_PAYLOAD, AVP_FAILED, AVP_ISP_INFORMATION, AVP_KEY_ID, AVP_NAP_INFORMATION, AVP_NONCE, AVP_NOTIFICATION, AVP_PPAC, AVP_PROTECTION_CAPABILITY, AVP_PROVIDER_IDENTIFIER, AVP_PROVIDER_NAME, AVP_RESULT_CODE, AVP_SESSION_ID, AVP_SESSION_LIFETIME, AVP_TERMINATION_CAUSE Kainuma & Teraoka Expires December 3, 2006 [Page 10] Internet-Draft PANA API June 2006 } PANAAVPCode; 3.1.15. PANA Message Codes The following values are PANA Message Codes which are used in PANA. They are defined in the PANA specification [1]: typedef enum { PANA_CLIENT_INITIATION = 1, PANA_START, PANA_AUTH, PANA_REAUTH, PANA_BIND, PANA_PING, PANA_TERMINATION, PANA_ERROR, PANA_UPDATE } PANAMessageCode; 3.1.16. PANA Session Attributes The following values are used for specifing PANA Session attributes. PANA Session attributes are defined in [1]: typedef enum { SESSION_IDENTIFIER, DEVICE_IDENTIFIER_PAC, IP_ADDR_PEER, DEVICE_IDENTIFIER_EP, SEQUENCE_NUMBER_TRANSMIT, SEQUENCE_NUMBER_RECEIVE, PANA_MESSAGE, RETRANSMISSION_INTERVAL, SESSION_LIFETIME, PPAC, NONCE_LOCAL, NONCE_PEER, MSK, MSK_IDENTIFIER, PANA_AUTH_KEY, PSEUDO_RANDOM_FUNCTION, INTEGRITY_ALGORITHM, PANA_PING_TIME } PANASessionAttribute; Kainuma & Teraoka Expires December 3, 2006 [Page 11] Internet-Draft PANA API June 2006 3.1.17. PANA Message Flags The following values are used for PANA Message flags. PANA Message flags are contained in the PANA header and specify how PANA works: typedef enum { REQUEST = 0x8000, STATELESS_HANDSHAKE = 0x4000, NOTSET = 0x0000 } PANAMessageFlag; REQUEST This message is a request. STATELESS_HANDSHAKE The PAA is performing stateless discovery. This flag is contained in the PANA-Start-Request message. If this flag is set, Coolie AVP must be included in the PANA-Start Messages. NOTSET No flags is set. 3.1.18. Protection Capability The following values are used for Protection-Capability AVP value. Protection-Capability indicates the cryptographic data protection capability supported and required by the EPs: typedef enum { L2_PROTECTION, IPSEC_PROTECTION } ProtectionCapabilityCode; 3.1.19. AVP Flags The following values are used for AVP flags. AVP flags are contained in AVP header and specify how AVPs are handled: typedef enum { PANA_AVP_FLAG_NONE = 0x0000, PANA_AVP_FLAG_MANDATORY = 0x8000, PANA_AVP_FLAG_VENDOR = 0x4000 } PANAAVPFlag; PANA_AVP_FLAG_NONE No AVP flags are set. PANA_AVP_FLAG_MANDATORY If either the AVP or its value is unrecognized, the message must be rejected and receiver must send a PANA-Error-Request message. Kainuma & Teraoka Expires December 3, 2006 [Page 12] Internet-Draft PANA API June 2006 PANA_AVP_FLAG_VENDOR This AVP has optional Vendor-ID field in the AVP header. 3.1.20. Termination Cause The following values are used for value of the Termination-Cause AVP. Termination Cause indicates the reason why a session is terminated: typedef enum { LOGOUT, ADMINISTRATIVE, SESSION_TIMEOUT } TerminationCauseCode; LOGOUT The PaC initiated termination of the PANA Session. ADMINISTRATIVE The PaC initiated termination of the PANA Session, due to administrative reasons. SESSION_TIMEOUT The PANA Session has timed out. 3.1.21. PPAC The following values are used for value of the PPAC AVP. PPAC indicates available types of post-PANA IP address configuration mechanisms: typedef enum { NO_CONFIGURATION = 0x80000000, DHCPV4 = 0x40000000, DHCPV6 = 0x20000000, STATELESS_AUTOCONFIGURATION = 0x10000000, DHCPV4_WITH_IPSEC_TUNNEL = 0x08000000, IKEV2 = 0x04000000 } IntegrityAlgorithm; The PaC deos not configure a new IP address after PANA. DHCPV4 The PaC will use DHCPv4 to configure a new IPv4 address after PANA. DHCPV6 The PaC will use DHCPv6 to configure a new IPv6 address after PANA. STATELESS_AUTOCONFIGRATION The PaC will use stateless IPv6 address autoconfiguration to configure a new IPv6 address after PANA. Kainuma & Teraoka Expires December 3, 2006 [Page 13] Internet-Draft PANA API June 2006 DHCPV4_WITH_IPSEC_TUNNEL The PaC will use to configure a new IPv4 address after PANA. IKEV2 The PaC will use IKEv2 to configure a new IP address after PANA. 3.2. Timer Event Handle The following values are used for registering Timer Callback. typedef enum { TIMER_PANA_PING, TIMER_PANA_SESSION_LIFETIME, TIMER_RETRANSMISSION_INTERVAL } TimerEventHandle; TIMER_PANA_PING This event managements the exchange of the PANA-Ping messages. TIMER_PANA_SESSION_LIFETIME This event managements the lifetime of the specific PANA Session. TIMER_RETRANSMISSION_INTERVAL This event managements the retransmission of the request messages. 3.3. Filtering Policy on the EP The following values are used for filtering on the EP. This is used when the PANA Session is initialized, authentication is successful, and the PANA Session is terminated: typedef enum { ALL_NODE_DROP, ALL_DROP, ALL_PASS } PANAFilteringFlag; ALL_NODE_DROP The EP drops all packets. ALL_DROP The EP drops all packets from or to a specific IP address. ALL_PASS The EP pass all packets from or to a specific IP address. 3.4. Result Code AVP Value The following values are used for reporting whether an EAP authentication had completed successfully or whether an error had occurred. They correspond directory to the valuesdefined in the PANA Kainuma & Teraoka Expires December 3, 2006 [Page 14] Internet-Draft PANA API June 2006 specification [1]. typedef enum { PANA_SUCCESS = 2001, PANA_AUTHENTICATION_REJECTED = 4001, PANA_AUTHORIZATION_REJECTED = 5003, PANA_MESSAGE_UNSUPPORTED = 3001, PANA_UNABLE_TO_DELIVER = 3002, PANA_INVALID_HDR_BITS = 3008, PANA_INVALID_AVP_FLAGS = 3009, PANA_AVP_UNSUPPORTED = 5001, PANA_UNKNOWN_SESSION_ID = 5002, PANA_INVALID_AVP_DATA = 5004, PANA_MISSING_AVP = 5005, PANA_RESOURCES_EXCEEDED = 5006, PANA_CONTRADICTING_AVPS = 5007, PANA_AVP_NOt_ALLOWED = 5008, PANA_AVP_OCCURS_TOO_MANY_TIMES = 5009, PANA_UNSUPPORTED_VERSION = 5011, PANA_UNABLE_TO_COMPLY = 5012, PANA_INVALID_AVP_LENGTH = 5014, PANA_INVALID_MESSAGE_LENGTH = 5015, PANA_PROTECTION_CAPABILITY_UNSUPPORTED = 5016, PANA_PPAC_CAPABILITY_UNSUPPORTED = 5017 } PANAResultCode; 3.5. Return Code The following values are used to report result returned by functions in the PANA API. They correspond directoly to values defined in the Diameter API specification [2]: Kainuma & Teraoka Expires December 3, 2006 [Page 15] Internet-Draft PANA API June 2006 typedef enum { PANA_ERR_NOT_FOUND = -2, PANA_ERR_FAILURE = -1, PANA_ERR_SUCCESS = 0, PANA_ERR_NOMEM, PANA_ERR_PROTO, PANA_ERR_SECURITY, PANA_ERR_PARAMETER, PANA_ERR_CONFIG, PANA_ERR_UNKNOWN_CMD, PANA_ERR_MISSING_AVP, PANA_ERR_ALREADY_INIT, PANA_ERR_TIMED_OUT, PANA_ERR_CANNOT_SEND_MSG, PANA_ERR_ALREADY_REGISTERED, PANA_ERR_CANNOT_REGISTER, PANA_ERR_NOT_INITIATED, PANA_ERR_NETWORK_ERROR } PANAReturnCode; The following is a description of the error codes and the reasons why they can be returned: PANA_ERR_NOT_FOUND A handle or identifier was not found. PANA_ERR_FAILURE Unspecified failure occurred during the PANA operation. PANA_ERR_SUCCESS The PANA operation succeeded. PANA_ERR_NOMEM There is no available memory. PANA_ERR_PROTO PANA protocol error occurred. PANA_ERR_SECURITY A security check failed or another security error occurred. PANA_ERR_PARAMETER An Invalid parameter was passed to the function. PANA_ERR_CONFIG An error was encountered in a Configuration File. PANA_ERR_UNKNOWN_MSG The library received the PANA Message which is not registered. PANA_ERR_MISSING_AVP The received message does not have required AVPs. Kainuma & Teraoka Expires December 3, 2006 [Page 16] Internet-Draft PANA API June 2006 PANA_ERR_ALREADY_INIT Initialization is already done. PANA_ERR_TIMED_OUT Lifetime is expired. PANA_ERR_CANNOT_SEND_MSG The library can not send a message. PANA_ERR_ALREADY_REGISTERED Callback or other structure is already registered. PANA_ERR_CANNOT_REGISTER Callback or other structure can not be registered. PANA_ERR_NOT_INITIALIZED The library did not initialized. PANA_ERR_NETWORK_ERROR An error occured in networking. 3.6. Callback Location Codes The following values are used to indicate where a callback should be added to the Callback List: typedef enum { PANA_APP_INSTALL_FIRST, PANA_APP_INSTALL_ANYWHERE, PANA_APP_INSTALL_LAST } PANACallbackLocation; PANA_APP_INSTALL_FIRST Add this callback as the first callback in the Callback List. PANA_APP_INSTALL_ANYWHERE Add this callback anywhere in the Callback List. PANA_APP_INSTALL_LAST Add this callback as the last callback in the Callback List. 3.7. AVP Data Type Codes The following values are used to specify the AVP data type. They correspond directly to the AVP data types outlined in the PANA specification [1]. Kainuma & Teraoka Expires December 3, 2006 [Page 17] Internet-Draft PANA API June 2006 typedef enum { PANA_AVP_DATA_TYPE, PANA_AVP_STRING_TYPE, PANA_AVP_ADDRESS_TYPE, PANA_AVP_INTEGER32_TYPE, PANA_AVP_INTEGER64_TYPE, PANA_AVP_TIME_TYPE, PANA_AVP_GROUP_TYPE } PANAAVPDataType; 3.8. Search Direction Type The following values are used to specify which direction to search for an AVP in the AVP List: typedef enum { PANA_FORWARD_SEARCH, PANA_BACKWARD_SEARCH } PANASearchType; Kainuma & Teraoka Expires December 3, 2006 [Page 18] Internet-Draft PANA API June 2006 4. Structure Definitions 4.1. AVP Structure The following structure contains the AVP header and value: typedef struct avp { enum { PANA_RADIUS, PANA_DIAMETER } packetType; PANAAVPCode code; uint16_t length; PANAAVPFlag flags; PANAAVPDataType type; PANAVendorID vendorId; void *data; } PANA_AVP; The fields have the following definitions: packetType Indicates whether the backend protocol is Diameter or Radius. If the backend protocol is Radius, flags and vendorId fields are null. code The AVP Code. Identifies this AVP. length The length of the AVP's data field. flags The AVP flags. type The AVP's data type. vendorId The Vendor ID. If the AVP is not vendor-specific, this field is set to PANA_NO_VENDOR_ID. data The AVP data, in host byte order. 4.2. ISP/NAP-Information AVP Value The following structure contains an ISP/NAP-Information AVP value. The ISP/NAP-Information AVP is defined in : typedef struct informationAvpValue { PANAProviderID providerId; PANAProviderName providerName; } PANAInformationAVPValue; Kainuma & Teraoka Expires December 3, 2006 [Page 19] Internet-Draft PANA API June 2006 The fields have the following definitions: providerId An identifier of a NAP or ISP. providerName A name of a NAP or ISP. 4.3. Notification AVP Value The following structure contains a Notification AVP value. The Notification AVP is defined in [1]: typedef struct notificationAvpValue { uint16_t length; char *tag; char *displayableString; } PANANotificationAvpValue; The fields have the following definitions: length The length of the Language Tag in octets. tag The Language Tag defined in [8] to indicate the language used for the displayable string. displayableString UTF-8 encoded ISO 10464 value with characters using the Language Tag. The length of this data is determined by the AVP Length field and the Language Tag Length field. 4.4. AVP List The following structure is used for representing lists of AVPs in the message: typedef struct avpList { PANA_AVP *head; PANA_AVP *tail; } PANA_AVP_List; 4.5. PANA Message The following structure contains the PANA header and information which is used to send the PANA Message: Kainuma & Teraoka Expires December 3, 2006 [Page 20] Internet-Draft PANA API June 2006 typedef struct message { uint8_t version; uint16_t length; PANAMessageFlag flags; PANAMessageType type; uint32_t sequence_num; uint8_t count_retransmit; PANAVendorID vendorId; PANAResultCode resultCode; PANA_IP_ADDR sender; PANA_AVP_List *avpList; PANAMessageCode messageCode; uint32_t time_retransmit; time_t startTime; PANA_IP_ADDR destination; } PANA_Message; The fields have the following definitions: version The version number of PANA. length The length of the PANA Message including the header fields. flags PANA header flags type Message type. sequence_num The sequence number which is initialized with each PANA Session. count_retransmit Count of retransmission. vendorId The vendor identifier of the PANA Message. resultCode The Result Code indicating the result of the request. originator The IP address of the message's originator. sender The IP address of the message's sender. avpList The AVP List in the message. messageCode The PANA Message Code. time_retransmit The retransmission time of the request message. Kainuma & Teraoka Expires December 3, 2006 [Page 21] Internet-Draft PANA API June 2006 startTime The number of seconds at which the message was started. destination The IP address the message is sent to. 4.6. PANA Session The following structure contains PANA Session attributes. PANA Session attributes are defined in [1]: typedef struct panaSession { enum { PANA_PHASE_NONE = 0, PANA_PHASE_HANDSHAKE, PANA_PHASE_AUTHANDAUTH, PANA_PHASE_ACCESS, PANA_PHASE_TERMINATION } PANASessionPhase; PANASessionID *sessionId; PANADeviceID *pac_deviceId; PANA_IP_ADDR *peer_addr; PANADeviceID *ep_deviceId; uint32_t sequence_num_transmit; uint32_t sequence_num_receive; PANA_Message *message; uint32_t time_retransmit; uint32_t session_lifetime; ProtectionCapabilityCode pcCode; Nonce *peer_nonce; Nonce *my_nonce; MSK *msk; MSKIdentifier *mskId; PANA_AUTH_KEY *panaAuthKey; PseudoRandomFunction prf; IntegrityAlgorithm algorithm; uint32_t ping_timer; } PANA_Session; sessionId The identifier of the PANA Session. pac_deviceId The identifier of the device of the PaC. peer_addr The IP address and Port number of the peer node. Kainuma & Teraoka Expires December 3, 2006 [Page 22] Internet-Draft PANA API June 2006 ep_deviceId The identifier of the device of the EP. sequence_num_transmit The sequence number of the last transmitted request. sequence_num_receive The sequence number of the last received request. message The last transmitted message. time_retransmit The interval from the last transmission of the request to retransmission. session_lifetime The length of lifetime until the PANA Session is expired. pcCode The code which indicates Protection-Capability. peer_nonce The random value that is generated by the peer node for deriving the PANA_AUTH_KEY. my_nonce The random value which is generated by myself for deriving the PANA_AUTH_KEY. aaaKey The key that is generated by the EAP authentication. aaaKeyId The identifier that spesifies MSK. panaAuthKey The key that is derived from MSK. prf The function to be used for deriving PANA_AUTH_KEY. algorithm The algorithm to be used for computing AUTH AVP. ping_timer The interval of the PANA-Ping-Request. 4.7. PANA Session List The following structure is used for representing lists of PANA Sessions: typedef struct sessionList { PANA_Session *head; PANA_Session *tail; } PANASession_List; Kainuma & Teraoka Expires December 3, 2006 [Page 23] Internet-Draft PANA API June 2006 4.8. Dictionary Entry The following structure is returned by the dictionary entry lookup functions. It contains information about a particular AVP in the dictionary: typedef struct dictionaryEntry { PANAAVPCode avpCode; char *avpName; PANAAVPDataType avpType; PANAVendorID vendorId; PANAAVPFlag flags; } PANADictionaryEntry; Kainuma & Teraoka Expires December 3, 2006 [Page 24] Internet-Draft PANA API June 2006 5. API Definitions 5.1. Initialization and Configuration This section describes the initialization and configuration functions of PANA API. 5.1.1. PANAOpen() The following function is used to open and configure the PANA library: PANAReturnCode PANAOpen(char *configFileName); This function must be called before any other PANA functions are called. Operations performed by this function are loading AVPs, initiating filters on the EP, and loading dictionary and configuration files. The parameter is a pointer to the full pathname for the Configuration File. If the value is null or an empty string, the API loads the configuration file in the default pathname. The return values are: PANA_ERR_SUCCESS If initialization has succeeded. PANA_ERR_ALREADY_INIT If the library is already initialized. PANA_ERR_NETWORK_ERROR If the PAA can not access the EP. PANA_ERR_NOMEM If no memory was available. PANA_ERR_CONFIG If processing the dictionary or configuration information failed. 5.1.2. PANAClose() The following function is used to close the PANA library: PANAReturnCode PANAClose(); After this function is called, all other PANA functions are unavailable. The return values are: Kainuma & Teraoka Expires December 3, 2006 [Page 25] Internet-Draft PANA API June 2006 PANA_ERR_SUCCESS If termination has succeeded. PANA_ERR_NOT_INITIALIZED If PANA was not initialized. 5.1.3. PANAGetDefaultConfigFileName() The following function is used to get the default path of the Configuration File: const char *PANAGetDefaultConfigFileName(); The return value is a pointer to the full pathname of the Configuration File. 5.2. Registering Callbacks This section describes the registration functions of callbacks. 5.2.1. PANARegisterMessageCallback() The following function is used to register callbacks for specific PANA Messages: PANACallbackHandle *PANARegisterMessageCallback(PANAMessageCode messageCode, PANAMessageFlag requestFlag, PANAVendorID vendorId, char *messageName, PANACallback callback, PANACallbackLocation position); The parameters are: messageCode The code of the PANA Message processed by the callback. requestFlag The flags. vendorId The vendor identifier of the PANA Message. messageName The pointer to the name of the PANA Message. callback The callback function to perform processing. position The position of the callback in the Message Callback List. The return value is a handle that identifies the registered callback. Kainuma & Teraoka Expires December 3, 2006 [Page 26] Internet-Draft PANA API June 2006 5.2.2. PANARegisterTimerCallback() The following function is used to register callbacks for timer events: PANACallbackHandle *PANARegisterTimerCallback(TimerEventHandle handle, PANACallback callback, PANACallbackLocation position); The parameters are: handle The code of the timer event processed by the callback. callback The callback function to perform processing. position The position of the callback in the Timer Callback List. The return value is a handle that identifies registered callback. 5.2.3. PANADeregisterMessageCallback() The following function is used to delete callbacks from the Message Callback List: PANAReturnCode PANADeregisterMessageCallback(PANACallbackHandle *handle); The parameter is the handle of the callback to be deleted. The return values are: PANA_ERR_SUCCESS Deletion has succeeded. PANA_ERR_FAILURE Deletion has failed. The callback is not deleted. PANA_ERR_NOT_FOUND Specified handle was not found. 5.2.4. PANADeregisterTimerCallback() The following function is used to delete callbacks from the Timer Callback List: PANAReturnCode PANADeregisterTimerCallback(PANACallbackHandle *handle); The parameter is the handle of the timer callback to be deleted. Kainuma & Teraoka Expires December 3, 2006 [Page 27] Internet-Draft PANA API June 2006 The return values are: PANA_ERR_SUCCESS Deletion has succeeded. PANA_ERR_FAILURE Deletion has failed. The callback is not deleted. PANA_ERR_NOT_FOUND Specified handle was not found. 5.3. PANA Session Management This section describes the management function of the PANA Session. Management of the PANA Session contains initialization, configuration, and termination. 5.3.1. PANANewSession() The following function is used to initialize the PANA Session and return a pointer to the identifier of the initialized PANA Session. The initialized PANA Session is added to the PANA Session List: PANAReturnCode PANANewSession(PANA_IP_ADDR peer_addr, PANASessionId **id); At that time a PANA Session is initialized, the PAA computes the session identifier of the PANA Session. A PANA Session is initialized after the PAA has received the PANA-Start-Answer message or after PaC has received the PANA-Auth-Request message. The parameters are: peer_addr An IP address of the peer. id The pointer to the pointer to the identifier of the PANA Session. The return values are: PANA_ERR_SUCCESS Initialization has succeeded. PANA_ERR_NOMEM If no memory is available. PANA_ERR_PARAMETER Some parameters are invalid. 5.3.2. PANAFreeSession() The following function is used to release the PANA Session and delete from the PANA Session List: PANAReturnCode PANAFreeSession(PANASessionId *id); Kainuma & Teraoka Expires December 3, 2006 [Page 28] Internet-Draft PANA API June 2006 The parameter is the pointer to the identifier of the PANA Session. The return values are: PANA_ERR_SUCCESS Termination of the PANA Session has succeeded. PANA_ERR_FAILED Termination of the PANA Session has failed. 5.3.3. PANARegisterSession() The following function is used to register as assigned session from the given message. This function is used by PaC. PANAReturnCode PANARegisterSession(PANAMessage *message, PANASessionId **id); The parameters are: message The pointer to the message. id The pointer to the pointer to the session identifier of the PANA Session. The return values are: PANA_ERR_SUCCESS The PANA Session was registered successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_MISSING_AVP The message did not have enough AVPs. PANA_ERR_ALREADY_REGISTERED The PANA Session is already registered. 5.3.4. PANASetSessionAttribute() The following function is used to configure the PANA Session. This function can set the value to PANA Session attributes of the specific PANA Session: PANAReturnCode PANASetSessionAttribute(PANASessionId *id, PANASessionAttribute attributeName, void *value); The parameters are: Kainuma & Teraoka Expires December 3, 2006 [Page 29] Internet-Draft PANA API June 2006 id The pointer to the identifier of the PANA Session. attributeName The code of the PANA Session attribute. value The value to be set with the attributeName in the PANA Session attributes. The return values are: PANA_ERR_SUCCESS Attribute was set successfully. PANA_ERR_FAILUERE Attribute was not set. 5.3.5. PANAGetSessionAttribute The following funtion is used to get attributes from the PANA Session: void *PANAGetSessionAttribute(PANASessionId *id, PANASessionAttributeCode attributeName); The parameters are: id The pointer to the identifier of the PANA Session. attributeName The code of the PANA Session attribute. The return value is a pointer to the specified AVP value. 5.3.6. PANASessionValidityCheck() The following function is used to check whether the PANA Session is valid. The criteria is whether the PANA Session attributes are valid and whether the PANA Session lifetime has expired: PANAReturnCode PANASessionValidityCheck(PANASessionId *id); The parameter is a pointer to the identifier of the PANA Session. The return values are: PANA_ERR_SUCCESS The PANA Session is valid. PANA_ERR_TIMED_OUT The PANA Session has already expired. Kainuma & Teraoka Expires December 3, 2006 [Page 30] Internet-Draft PANA API June 2006 PANA_ERR_PARAMETER Some of the PANA Session attributes are invalid. 5.3.7. PANADeriveAuthKey() The following function is used to derive the PANA-AUTH-KEY from the MSK and set the PANA-AUTH-KEY as a PANA Session attribute: PANAReturnCode *PANADeriveAuthKey(PANASessionId *id); The parameter is a pointer to the identifier of the PANA Session. The return values are: PANA_ERR_SUCCESS The PANA-AUTH-KEY was derived successfully. PANA_ERR_PARAMETER Some of key materials are invalid. 5.3.8. PANADeriveMasterKey() The following function is used to derive the PaC-EP-Master-Key from the MSK and set the PaC-EP-Master-Key to the EP: PANAReturnCode *PANADeriveMasterKey(PANASessionId *id); The parameter is a pointer to the identifier of the PANA Session. The return values are: PANA_ERR_SUCCESS The PaC-EP-Master-Key was derived successfully. PANA_ERR_NETWORK_ERROR The PaC-EP-Master-Key was not dsitributed to the EP. PANA_ERR_PARAMETER Some of key materials are invalid. 5.4. PANA Operation This section describes PANA operation function. PANA operation includes creating messages and sending messages. PANA messages are created and sent according to [5]. 5.4.1. PANAClientInitiation() The following function is used to initiate the handshake with PAA. Ths PaC sends the PANA-Client-Initiation message to the PAA: PANAReturnCode PANAClientInitiation(PANA_IP_ADDR *ip, PANA_AVP_LIST *avp_list); Kainuma & Teraoka Expires December 3, 2006 [Page 31] Internet-Draft PANA API June 2006 The parameters are: ip The PAA's unicast address. If this parameter contains NULL, the PaC attempts to get PAA's IP address through DHCP. avp_list The pointer to the AVP list which is inserted to the message. The return values are: PANA_ERR_SUCCESS The PANA-Client-Initiation message was sent successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_CANNOT_SEND_MSG The PaC could not send the PANA-Client- Initiation message. 5.4.2. PANAStart() The following function is used to initialize the PANA Session. In the case of the PAA, the PAA sends the PANA-Start-Request message to the PaC. In the case of the PaC, the PaC sends the PANA-Start-Answer message to the PAA. Initial EAP exchange is supported to reduce redundant messages. The PAA must be an initiator of the PANA-Start messages: PANAReturnCode PANAStart(PANA_IP_ADDR dest, PANAMessageFlag flag, PANA_AVP_LIST *avp_list); The parameters are: dest Destination IP address. flag Flags that indicate how this message is handled. avp_list The pointer to the AVP list which is inserted to the message. The return values are: PANA_ERR_SUCCESS The PANA-Start messages were sent successfully. PANA_ERR_NOMEM There is no memory available. Kainuma & Teraoka Expires December 3, 2006 [Page 32] Internet-Draft PANA API June 2006 PANA_ERR_CANNOT_SEND_MSG The PANA-Start messages can not be sent. PANA_ERR_PARAMETER The parameters are invalid. 5.4.3. PANAAuth() The following function is used to authenticate and authorize the PaC. In the case of the PAA, the PAA sends the PANA-Auth-Request or PANA- Auth-Answer message to the PaC. In the case of the PaC, the PaC sends the PANA-Auth-Anser and PANA-Auth-Request message to the PAA. The PAA must be the initiator of the PANA-Auth messages: PANAReturnCode PANAAuth(PANASessionId *id, PANAMessageFlag flag, PANA_AVP_LIST *avp_list); The parameters are: id The pointer to the identifier of the PANA Session. flag Flags that indicate how this message is handled. avp_list The pointer to the AVP list which is inserted to the message. The return values are: PANA_ERR_SUCCESS The PANA-Auth messages were sent successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_CANNOT_SEND_MSG The PANA-Auth messages can not be sent. PANA_ERR_PARAMETER The parameters are invalid. PANA_ERR_NOT_FOUND The session identifier is not exist. 5.4.4. PANABind() The following function is used to deliver the result of authentication, and bind device identifiers of the PaC and EP, to the PANA Session. The PAA must be the initiator of the PANA-Bind messages: PANAReturnCode PANABind(PANASessionId *id, PANAResultCode code, PANAMessageFlag flag, PANA_AVP_LIST *avp_list); Kainuma & Teraoka Expires December 3, 2006 [Page 33] Internet-Draft PANA API June 2006 The parameters are: id The pointer to the identifier of the PANA Session. code The Result Code of the PaC's authentication. flag Flags that indicate how this message is handled. avp_list The pointer to the AVP list which is inserted to the message. The return values are: PANA_ERR_SUCCESS The PANA-Bind messages were sent successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_CANNOT_SEND_MSG The PANA-Bind messages can not be sent. PANA_ERR_PARAMETER The parameters are valid. PANA_ERR_NOT_FOUND The session identifier is not exist. 5.4.5. PANAPing() The following function is used to check availability of the PAA or PaC respectively. Both PAA and PaC can be the initiator of the PANA- Ping messages: PANAReturnCode PANAPing(PANASessionId *id, PANAMessageFlag flag, PANA_AVP_LIST *avp_list); The parameters are: session The pointer to the identifier of the PANA Session. flag Flags that indicate how this message is handled. avp_list The pointer to the AVP list. The return values are: PANA_ERR_SUCCESS The PANA-Ping messages are sent successfully. Kainuma & Teraoka Expires December 3, 2006 [Page 34] Internet-Draft PANA API June 2006 PANA_ERR_NOMEM There is no memory available. PANA_ERR_CANNOT_SEND_MSG The PANA-Ping messages can not be sent. PANA_ERR_PARAMETER The parameters are invalid. PANA_ERR_NOT_FOUND The session identifier is not exist. 5.4.6. PANATermination() The following function is used to terminate the PANA Session. Both PAA and PaC can be the initiator of the PANA-Termination messages: PANAReturnCode PANATermination(PANASessionId *id, PANATerminationCauseCode code, PANAMessageFlag flag, PANA_AVP_LIST *avp_list); The parameters are: id The pointer to the identifier of the PANA Session. code The Termination Cause Code. The cause of the PANA Session termination. flag Flags that indicate how this message is handled. avp_list The pointer to the AVP list. The return values are: PANA_ERR_SUCCESS The PANA-Termination messages were sent successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_CANNOT_SEND_MSG The PANA-Termination messages can not be sent. PANA_ERR_PARAMETER The parameters are invalid. PANA_ERR_NOT_FOUND The session identifier is not exist. Kainuma & Teraoka Expires December 3, 2006 [Page 35] Internet-Draft PANA API June 2006 5.4.7. PANAError() The following function is used to report an error with the last received PANA Message. Both PAA and PaC can be the initiator of the PANA-Error messages: PANAReturnCode PANAError(PANASessionId *id, PANAResultCode code, PANAMessageFlag flag, PANA_AVP_LIST *avp_list); The parameters are: id The pointer to the identifier of the PANA Session. code The error Result Code. flag Flags that indicate how this message is handled. avp_list The pointer to the AVP list. The return values are: PANA_ERR_SUCCESS The PANA-Error messages were sent succcessfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_CANNOT_SEND_MSG The PANA-Error messages can not be sent. PANA_ERR_PARAMETER The parameters are invalid. PANA_ERR_NOT_FOUND The session identifier is not exist. 5.4.8. PANAReauth() The following function is used to re-authentication of the PaC. The PAA must be the initiator of the PANA-Reauth messages: PANAReturnCode PANAReauth(PANASessionId *id, PANAMessageFlag flag); The parameters are: id The pointer to the identifier of the PANA Session. Kainuma & Teraoka Expires December 3, 2006 [Page 36] Internet-Draft PANA API June 2006 flgs Flags that indicate how this message is handled. The return values are: PANA_ERR_SUCCESS The PANA-Reauth messages were sent successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_CANNOT_SEND_MSG The PANA-Reauth messages can not be sent. PANA_ERR_PARAMETER The parameters are invalid. PANA_ERR_NOT_FOUND The session identifier is not exist. 5.4.9. PANAUpdate() The following function is used to update the PaC's IP address. The PaC must be the initiator of the PANA-Update messages: PANAReturnCode PANAUpdate(PANASessionId *id, PANA_IP_ADDR updateAddr, PANAMessageFlag flag, PANA_AVP_LIST *avp_list); The parameters are: id The pointer to the identifier of the PANA Session. updateAddr The new IP address of the PaC. flag Flags that indicate how this message is handled. avp_list The pointer to the AVP list. The return values are: PANA_ERR_SUCCESS The PANA-Update messages were sent successfully. PANA_ERR_NOMEM There is no memory available PANA_ERR_CANNOT_SEND_MSG The PANA-Update messages can not be sent. PANA_ERR_PARAMETER The parameters are invalid. PANA_ERR_NOT_FOUND The session identifier is not exist. Kainuma & Teraoka Expires December 3, 2006 [Page 37] Internet-Draft PANA API June 2006 5.5. EP Control This section describes the EP control functions. EP control includes setting the PaC-EP-Master-Key to the EP and delivering policy to the EP: 5.5.1. PANASetMasterKey() The following function is used to set the PaC-EP-Master-Key to the EP: PANAReturnCode PANASetMasterKey(PANA_IP_ADDR ep, PaC-EP-Master-Key *masterKey); The parameters are: ep The IP address of the EP. masterKey The pointer to the PaC-EP-Master-Key. The return values are: PANA_ERR_SUCCESS PaC-EP-Master-Key was set successfully. PANA_ERR_NETWORK_ERROR PaC-EP-Master-Key could not be sent to the EP. 5.5.2. PANASetEP() The following function is used to enforce policy on the EP. PANAReturnCode PANASetEP(PANA_IP_ADDR ep, PANA_IP_ADDR host, PANAFilteringFlag policy); The parameters are: ep An IP address of the EP. host An IP address of the PaC. policy Enforced policy on EP. The return values are: Kainuma & Teraoka Expires December 3, 2006 [Page 38] Internet-Draft PANA API June 2006 PANA_ERR_SUCCESS Policy was enforced successfully. PANA_ERR_NETWORK_ERROR Policy can not be sent to the EP. 5.6. Dictionary Lookup This section describes the Dictionary lookup functions. Dictionary lookup includes looking up AVPs and messages in the Dictionary File. The same functions that are defined in section 3.4.4. of [2] may be applicable. 5.6.1. PANADictionaryEntryFromAVPCode() The following function is used to look up a adictionary entry using a message code and a vendor identifier: PANAReturnCode PANADictionaryEntryFromAVPCode(PANAAVPCode avpCode, PANAVendorID vendorId, PANADictionaryEntry *entry); The parameters are: avpCode The code number of the AVP. vendorId The vendor identifier of the AVP entry A PANADictionaryEntry structure for returning the entry. The return values are: PANA_ERR_SUCCESS The query succeeded. PANA_ERR_FAILURE No matching dictionary entry was found. 5.6.2. PANADictionaryEntryFromName() The following function is used to look up a dictionary entry using a message name and a vendor identifier: PANAReturnCode PANADictionaryEntryFromName(char *avpName, PANAVendorID vendorId, PANADictionaryEntry *entry); The parameters are: Kainuma & Teraoka Expires December 3, 2006 [Page 39] Internet-Draft PANA API June 2006 avpName The name of the AVP. vendorId The vendor identifier of the AVP. entry A PANADictionaryEntry structure for returning the entry. The return values are: PANA_ERR_SUCCESS The query succeeded. PANA_ERR_FAILURE No matching dictionary entry was found. 5.6.3. PANAValueFromName() The following function is used to look up an AVP value using the AVP name and a vendor identifier: PANAValue PANAValueFromName(char *avpName, char *vendorName, char *valueName); The parameters are: avpName The name of the AVP. vendorName The name of the vendor. valueName The name of the value. The return value is the identifier of the AVP. 5.6.4. PANAValueFromAVPCode() The following function is used to look up an AVP value using the AVP code and a vendor identifier: PANAValue PANAValueFromAVPCode(PANAAVPCode avpCode, PANAVendorID vendorId, char *valueName); The parameters are: avpCode The code of the AVP. vendorId The vendor identifier. Kainuma & Teraoka Expires December 3, 2006 [Page 40] Internet-Draft PANA API June 2006 valueName The name of the value. The return value is the identifier of the AVP. 5.6.5. PANALookupValueNameUsingValue() The following function returns the AVP value name: const char *PANALookupValueNameUsingValue(PANAAVPCode avpCode, PANAVendorID vendorId, PANAValue value); The parameters are: avpCode The code of the AVP. vendorId The vendor identifier. value The value. The return value is the value name. 5.6.6. PANAGetMessageCode() The following function returns the message code and vendor identifier: boolean_t PANAGetMessageCode(char *messageName, PANAMessageCode *messageCode, PANAVendorID *vendorId); The parameters are: messageName The string containing the message name. messageCode The pointer to the message code. vendorId The pointer to the vendor identifier. The return value is _B_TRUE if the command was found. 5.7. Message Management This section describes the AVP management functions. Message manamement includes creating messages, adding AVPs, traversing AVP Lists, and releasing messages. The same functions that are defined in section 3.4.5. of [2] may be applicable. Kainuma & Teraoka Expires December 3, 2006 [Page 41] Internet-Draft PANA API June 2006 5.7.1. PANANewMessage() The following function allocates a PANAMessageand returns a pointer to it: PANAMessage *PANANewMessage(PANAMessageCode messageCode, PANASessionID *id PANAVendorID vendorId, PANAMessage *request, PANAMessageFlag flg); The parameters are: messageCode The code of the message. id The pointer to the session identifier of the PANA Session. vendorId The vendor identifier. request The pointer to the request message. This is used when the message is created as a answer. flg The flag of the message. The return value is the pointer to the allocated message. 5.7.2. PANAFreeMessage() The following function releases a message allocated through PANANewMessage(): PANAReturnCode PANAFreeMessage(PANAMessage **message); The parameter is a pointer to a pointer to the allocated message. The return value is PANA_ERR_SUCCESS. 5.7.3. PANACreateAVP() The following function is used to create an AVP and returns a pointer to it: PANAReturnCode PANACreateAVP(PANA_AVP **avp, PANAAVPCode code, PANAAVPFlag flag, PANAVendorID vendorId, char *data, size_t length); Kainuma & Teraoka Expires December 3, 2006 [Page 42] Internet-Draft PANA API June 2006 The parameters are: avp The pointer to a pointer to the allocated AVP code The code of the AVP. flag The flag of the AVP. vendorId The vendor identifier. data The pointer to the AVP value. length The length of the AVP value. The return values are: PANA_ERR_SUCCESS An AVP is allocated successfully. PANA_ERR_PARAMETER Some parameters are invalid. PANA_ERR_PROTO Protocol error occured. PANA_ERR_NOMEM There is no memory available. 5.7.4. PANACreateAndAddAVPToList() The following function creates an AVP and adds it to the AVP List: PANAReturnCode PANACreateAndAddAVPToList(PANA_AVP_List **avpList, PANAAVPCode code, PANAAVPFlag flag, PANAVendorID vendorId, char *data, size_t length, PANA_AVP *position); The parameters are: avpList The list to which the allocated AVP added. code The code of the AVP. flag The flag of the AVP. vendorId The vendor identifier. Kainuma & Teraoka Expires December 3, 2006 [Page 43] Internet-Draft PANA API June 2006 data The pointer to the AVP value. length The length of the AVP value. The return values are: PANA_ERR_SUCCESS An AVP is allocated and added to the list successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_PARAMETER Some parameters are invalid. 5.7.5. PANAAddAVPToList() The following function is used to add the AVP to the AVP List: PANAReturnCode PANAAddAVPToList(PANA_AVP_List **avpList, PANA_AVP *avp, PANA_AVP *position); The parameters are: avpList The list to which the AVP added. avp The pointer to the AVP. position The pointer to the position the AVP will be added. The return values are: PANA_ERR_SUCCESS The AVP added successfully. PANA_ERR_NOMEM There is no memory available. PANA_ERR_PARAMETER Sone of parameters are invalid. 5.7.6. PANAFindMatchingAVP() The following function is used to find an AVP with matching code and vendor identifier: PANA_AVP *PANAFindMatchingAVP(PANA_AVP_List **avpList, PANA_AVP *startAVP, PANAAVPCode avpCode, PANAVendorID vendorId, PANASearchType searchType); Kainuma & Teraoka Expires December 3, 2006 [Page 44] Internet-Draft PANA API June 2006 The parameters are: avpList The List in which the searching AVP is. startAVP The pointer to the head of the AVP List. avpCode The code of the AVP. vendorId The vendor identifier. searchType The search type to specify which direction to search in the List. The return value is a pointer to the found AVP. 5.7.7. PANAJoinAVPLists() The following function joins together two AVP Lists: PANAReturnCode PANAJoinAVPLists(PANA_AVP_List *dest, PANA_AVP_List *source, PANA_AVP *position); The parameters are: dest The destination AVP List. source The source AVP List to be added to dest. position The position to add the AVPs to. The return values are: PANA_ERR_SUCCESS The AVP Lists were added successfully. PANA_ERR_PARAMETER Some parameters are invalid. 5.7.8. PANARemoveAVPFromList() The following function is used to remove the AVP from the AVP List: PANAReturnCode PANARemoveAVPFromList(PANA_AVP_List *avpList, PANA_AVP *avp); The parameters are: Kainuma & Teraoka Expires December 3, 2006 [Page 45] Internet-Draft PANA API June 2006 avpList The list from which to remove the AVP. avp The pointer to the AVP which will be removed. The return values are: PANA_ERR_SUCCESS The AVP was removed from the AVP List. PANA_ERR_PARAMETER Some parameters are invalid. 5.7.9. PANAFreeAVP() The following function is used to released an AVP: PANAReturnCode PANAFreeAVP(PANA_AVP **avp); The paramer is a pointer to a pointer to the AVP to release. The return values are: PANA_ERR_SUCCESS The AVP was released. PANA_ERR_PARAMETER Some parameters are invalid. 5.7.10. PANAGetFirstAVP() The following function is used to get the first AVP in the AVP List: PANA_AVP *PANAGetFirstAVP(PANA_AVP_List *avpList); The parameter is a pointer to the AVP List. The return value is a pointer to the first AVP in the AVP List. 5.7.11. PANAGetLastAVP() The following function is used to get the last AVP in the AVP List: PANA_AVP *PANAGetLastAVP(PANA_AVP_List *avpList); The parameter is a pointer to the AVP List. The return value is a pointer to the last AVP in the AVP List. 5.7.12. PANAGetNextAVP() The following function is used to get the next AVP in the AVP List: Kainuma & Teraoka Expires December 3, 2006 [Page 46] Internet-Draft PANA API June 2006 PANA_AVP *PANAGetNextAVP(PANA_AVP *avp); The parameter is a pointer to the AVP prior to the searching one. The return value is a pointer to the next AVP. 5.7.13. PANAGetPrevAVP() The following function is used to get the previous AVP in the AVP List: PANA_AVP *PANAGetPrevAVP(PANA_AVP *avp); The parameter is a pointer to the AVP next to the searching one. The return value is a pointer to the previous AVP. 5.7.14. PANAConvertAVPToString() The following function is used to convert the value of the AVP to a format suitable for log or displayable characters: char *PANAConvertAVPToString(PANA_AVP *avp, char *dest, size_t destLen); The parameters are: avp The pointer to the AVP to display. dest The buffer in which the converted value will be contained. destLen The length of the destination buffer. The return value is the converted data. 5.7.15. PANASetMessageResultCode() The following function is used to set the Result Code value: PANAReturnCode PANASetMessageResultCode(PANAMessage *message, PANAResultCode resultCode); The parameters are: Kainuma & Teraoka Expires December 3, 2006 [Page 47] Internet-Draft PANA API June 2006 message The pointer to the PANA Message to which the Result Code is set. resultCode The value of the Result Code AVP. The return values are: PANA_ERR_SUCCESS The value of the Result Code AVP was set to the PANA Message. PANA_ERR_PARAMETER Some parameters are invalid. 5.7.16. PANAComputeAuthAVP() The following function is used to compute the value of the AUTH AVP. The computed value is set to the AUTH AVP: PANAReturnCode PANAComputeAuthAVP(PANAMessage *message, PANASessionID *session); The parameters are: message The pointer to the PANA Message. session The pointer to the PANA Session. The return values are: PANA_ERR_SUCCESS The AUTH AVP value was set successfully. PANA_ERR_FAILURE The AUTH AVP value was not set. Kainuma & Teraoka Expires December 3, 2006 [Page 48] Internet-Draft PANA API June 2006 6. Security Consideration This document describes an API and therefore depends on the security mechanisms defined in the PANA protocol. Kainuma & Teraoka Expires December 3, 2006 [Page 49] Internet-Draft PANA API June 2006 7. References 7.1. Normative References [1] Forsberg, D., Ohba, Y., Patil, B., Tschofenig, H., and A. Yegin, "Protocol for Carrying Authentication for Network access (PANA)", draft-ietf-pana-pana-12 (work in progress), August 2006. [2] Calhoun, P., Frascone, D., and J. Kempf, "The Diameter API", draft-ietf-dime-diameter-api-00 (work in progress), February 2006. [3] Calhoun, P., Loughney, J., Arkko, J., Guttman, E., and G. Zorn, "Diameter Base Protocol", RFC RFC3588, September 2003. [4] Mghazli, Y., Ohba, Y., and J. Bournelle, "SNMP usage for PAA-EP interface", draft-ietf-pana-snmp-05 (work in progress), January 2006. [5] Fajardo, V., Ohba, Y., and R. Lopez, "State Machines for Protocol for Carrying Authentication for Network Access (PANA)", draft-ietf-pana-statemachine-04 (work in progress), May 2006. 7.2. Informative References [6] Eastlake, D., Schiller, J., and S. Crocker, "Randomness Requirements for Security", RFC RFC4086, June 2005. [7] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", RFC RFC4306, December 2005. [8] Phillips, A. and M. Davis, "Tags for Identifying Languages", draft-ietf-ltru-registry-14 (work in progress), October 2005. Kainuma & Teraoka Expires December 3, 2006 [Page 50] Internet-Draft PANA API June 2006 Authors' Addresses Yoshihiko Kainuma Graduate School of Science and Technology, KEIO University 3-14-1 Hiyoshi, Kohoku-ku Yokohama, Kanagawa 223-8522 Japan Phone: +81-45-566-1425 Email: hiko@tera.ics.keio.ac.jp URI: http://www.tera.ics.keio.ac.jp/ Fumio Teraoka Graduate School of Science and Technology, KEIO University 3-14-1 Hiyoshi, Kohoku-ku Yokohama, Kanagawa 223-8522 Japan Phone: +81-45-566-1425 Email: tera@ics.keio.ac.jp URI: http://www.tera.ics.keio.ac.jp/ Kainuma & Teraoka Expires December 3, 2006 [Page 51] Internet-Draft PANA API June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Kainuma & Teraoka Expires December 3, 2006 [Page 52]