IETF pana WG Y. Kainuma
Internet-Draft F. Teraoka
Intended status: Informational KEIO University
Expires: April 20, 2007 October 20, 2006
The PANA API
draft-hiko-pana-api-02
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 April 20, 2007.
Copyright Notice
Copyright (C) The Internet Society (2006).
Kainuma & Teraoka Expires April 20, 2007 [Page 1]
Internet-Draft PANA API October 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.
Kainuma & Teraoka Expires April 20, 2007 [Page 2]
Internet-Draft PANA API October 2006
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
5.7. Message Management . . . . . . . . . . . . . . . . . . . . 42
6. Security Consideration . . . . . . . . . . . . . . . . . . . . 49
7. Changes from previous version . . . . . . . . . . . . . . . . 50
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52
Intellectual Property and Copyright Statements . . . . . . . . . . 53
Kainuma & Teraoka Expires April 20, 2007 [Page 3]
Internet-Draft PANA API October 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 April 20, 2007 [Page 4]
Internet-Draft PANA API October 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 April 20, 2007 [Page 5]
Internet-Draft PANA API October 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 April 20, 2007 [Page 6]
Internet-Draft PANA API October 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 April 20, 2007 [Page 7]
Internet-Draft PANA API October 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 April 20, 2007 [Page 8]
Internet-Draft PANA API October 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 April 20, 2007 [Page 9]
Internet-Draft PANA API October 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 April 20, 2007 [Page 10]
Internet-Draft PANA API October 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,
PANA_PHASE
} PANASessionAttribute;
Kainuma & Teraoka Expires April 20, 2007 [Page 11]
Internet-Draft PANA API October 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 April 20, 2007 [Page 12]
Internet-Draft PANA API October 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 April 20, 2007 [Page 13]
Internet-Draft PANA API October 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 April 20, 2007 [Page 14]
Internet-Draft PANA API October 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 April 20, 2007 [Page 15]
Internet-Draft PANA API October 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,
PANA_ERR_READ_ONLY
} 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.
Kainuma & Teraoka Expires April 20, 2007 [Page 16]
Internet-Draft PANA API October 2006
PANA_ERR_MISSING_AVP The received message does not have required
AVPs.
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 April 20, 2007 [Page 17]
Internet-Draft PANA API October 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 April 20, 2007 [Page 18]
Internet-Draft PANA API October 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 April 20, 2007 [Page 19]
Internet-Draft PANA API October 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 April 20, 2007 [Page 20]
Internet-Draft PANA API October 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 April 20, 2007 [Page 21]
Internet-Draft PANA API October 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;
uint32_t sessionId_len;
PANADeviceID *pac_deviceId;
uint32_t pac_deviceId_len;
PANA_IP_ADDR *peer_addr;
PANADeviceID *ep_deviceId;
uint32_t ep_deviceId_len;
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;
uint32_t peer_nonce_len;
Nonce *my_nonce;
uint32_t my_nonce_len;
MSK *msk;
uint32_t msk_len;
MSKIdentifier *mskId;
PANA_AUTH_KEY *panaAuthKey;
uint32_t panaAuthKey_len;
PseudoRandomFunction prf;
IntegrityAlgorithm algorithm;
uint32_t ping_timer;
} PANA_Session;
Kainuma & Teraoka Expires April 20, 2007 [Page 22]
Internet-Draft PANA API October 2006
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.
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 23]
Internet-Draft PANA API October 2006
typedef struct sessionList {
PANA_Session *head;
PANA_Session *tail;
} PANASession_List;
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 April 20, 2007 [Page 24]
Internet-Draft PANA API October 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 April 20, 2007 [Page 25]
Internet-Draft PANA API October 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 April 20, 2007 [Page 26]
Internet-Draft PANA API October 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 April 20, 2007 [Page 27]
Internet-Draft PANA API October 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 April 20, 2007 [Page 28]
Internet-Draft PANA API October 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,
uint32_t value_len);
The parameters are:
Kainuma & Teraoka Expires April 20, 2007 [Page 29]
Internet-Draft PANA API October 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.
value_len The length of the attribute value.
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,
char** value,
uint32_t value_len);
The parameters are:
id The pointer to the identifier of the PANA Session.
attributeName The code of the PANA Session attribute.
value The pointer to the pointer to the return value.
value_len The length of the attribute value.
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 30]
Internet-Draft PANA API October 2006
The return values are:
PANA_ERR_SUCCESS The PANA Session is valid.
PANA_ERR_TIMED_OUT The PANA Session has already expired.
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].
Kainuma & Teraoka Expires April 20, 2007 [Page 31]
Internet-Draft PANA API October 2006
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);
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 32]
Internet-Draft PANA API October 2006
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.
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 33]
Internet-Draft PANA API October 2006
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);
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 34]
Internet-Draft PANA API October 2006
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.
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 35]
Internet-Draft PANA API October 2006
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.
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 36]
Internet-Draft PANA API October 2006
PANAReturnCode PANAReauth(PANASessionId *id,
PANAMessageFlag flag,
PANA_AVP_LIST *avp_list);
The parameters are:
id The pointer to the identifier of the PANA Session.
flgs 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-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:
Kainuma & Teraoka Expires April 20, 2007 [Page 37]
Internet-Draft PANA API October 2006
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.
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 38]
Internet-Draft PANA API October 2006
ep An IP address of the EP.
host An IP address of the PaC.
policy Enforced policy on EP.
The return values are:
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 39]
Internet-Draft PANA API October 2006
PANAReturnCode
PANADictionaryEntryFromName(char *avpName,
PANAVendorID vendorId,
PANADictionaryEntry *entry);
The parameters are:
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 40]
Internet-Draft PANA API October 2006
avpCode The code of the AVP.
vendorId The vendor identifier.
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:
pana_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.
Kainuma & Teraoka Expires April 20, 2007 [Page 41]
Internet-Draft PANA API October 2006
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.
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 42]
Internet-Draft PANA API October 2006
PANAReturnCode PANACreateAVP(PANA_AVP **avp,
PANAAVPCode code,
PANAAVPFlag flag,
PANAVendorID vendorId,
char *data,
size_t length);
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:
Kainuma & Teraoka Expires April 20, 2007 [Page 43]
Internet-Draft PANA API October 2006
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.
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 44]
Internet-Draft PANA API October 2006
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);
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 45]
Internet-Draft PANA API October 2006
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:
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 46]
Internet-Draft PANA API October 2006
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:
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.
Kainuma & Teraoka Expires April 20, 2007 [Page 47]
Internet-Draft PANA API October 2006
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:
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 April 20, 2007 [Page 48]
Internet-Draft PANA API October 2006
6. Security Consideration
This document describes an API and therefore depends on the security
mechanisms defined in the PANA protocol.
Kainuma & Teraoka Expires April 20, 2007 [Page 49]
Internet-Draft PANA API October 2006
7. Changes from previous version
This section describes about changes from previous version.
Changes from draft-pana-hiko-api-00 to draft-pana-hiko-api-01:
Submitted date was changed from June to September.
Changes from draft-pana-hiko-api-01 to draft-pana-hiko-api-02:
PANA_PHASE was added to the PANASessionAttribute.
PANA_ERR_READ_ONLY was added to the PANAReturnCode.
Length of the attribute whose length is variable was added to the
PANA_Session structure.
Length of the value was added to the argument of the
PANASetSessionAttribute function.
Value and its length were added to the argument of the
PANAGetSessionAttribute function.
Kainuma & Teraoka Expires April 20, 2007 [Page 50]
Internet-Draft PANA API October 2006
8. References
8.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.
8.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 April 20, 2007 [Page 51]
Internet-Draft PANA API October 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 April 20, 2007 [Page 52]
Internet-Draft PANA API October 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 April 20, 2007 [Page 53]