idnits 2.17.1 draft-hiko-pana-api-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2194. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2205. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2212. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2218. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 739 has weird spacing: '...ataType type...' == Line 824 has weird spacing: '...ultCode resul...' == Line 1375 has weird spacing: '...ageFlag flag,...' == Line 1407 has weird spacing: '...ultCode code...' == Line 1408 has weird spacing: '...ageFlag flag,...' == (14 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 20, 2006) is 6396 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-18) exists of draft-ietf-pana-pana-12 == Outdated reference: A later version (-08) exists of draft-ietf-dime-diameter-api-00 ** Obsolete normative reference: RFC 3588 (ref. '3') (Obsoleted by RFC 6733) == Outdated reference: A later version (-06) exists of draft-ietf-pana-snmp-05 == Outdated reference: A later version (-13) exists of draft-ietf-pana-statemachine-04 -- Obsolete informational reference (is this intentional?): RFC 4306 (ref. '7') (Obsoleted by RFC 5996) Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IETF pana WG Y. Kainuma 3 Internet-Draft F. Teraoka 4 Intended status: Informational KEIO University 5 Expires: April 20, 2007 October 20, 2006 7 The PANA API 8 draft-hiko-pana-api-02 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on April 20, 2007. 35 Copyright Notice 37 Copyright (C) The Internet Society (2006). 39 Abstract 41 Protocol for carrying Authentication for Network Access (PANA) 42 provides support for authentication for network access between end- 43 user and the Internet. This document proposes the design a 44 standardised API for the PANA protocol. The API is defined in the C 45 language. The goal of the API is to foster extensible PANA 46 implementation. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 2. API specifications . . . . . . . . . . . . . . . . . . . . . . 5 53 2.1. MultiThread . . . . . . . . . . . . . . . . . . . . . . . 5 54 2.2. Result Reporting . . . . . . . . . . . . . . . . . . . . . 5 55 2.3. List Structures . . . . . . . . . . . . . . . . . . . . . 5 56 2.4. EP Control . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.5. Configuration Files . . . . . . . . . . . . . . . . . . . 6 59 3. Data Type Definitions . . . . . . . . . . . . . . . . . . . . 7 60 3.1. Constant Types . . . . . . . . . . . . . . . . . . . . . . 7 61 3.2. Timer Event Handle . . . . . . . . . . . . . . . . . . . . 14 62 3.3. Filtering Policy on the EP . . . . . . . . . . . . . . . . 14 63 3.4. Result Code AVP Value . . . . . . . . . . . . . . . . . . 14 64 3.5. Return Code . . . . . . . . . . . . . . . . . . . . . . . 15 65 3.6. Callback Location Codes . . . . . . . . . . . . . . . . . 17 66 3.7. AVP Data Type Codes . . . . . . . . . . . . . . . . . . . 17 67 3.8. Search Direction Type . . . . . . . . . . . . . . . . . . 18 69 4. Structure Definitions . . . . . . . . . . . . . . . . . . . . 19 70 4.1. AVP Structure . . . . . . . . . . . . . . . . . . . . . . 19 71 4.2. ISP/NAP-Information AVP Value . . . . . . . . . . . . . . 19 72 4.3. Notification AVP Value . . . . . . . . . . . . . . . . . . 20 73 4.4. AVP List . . . . . . . . . . . . . . . . . . . . . . . . . 20 74 4.5. PANA Message . . . . . . . . . . . . . . . . . . . . . . . 20 75 4.6. PANA Session . . . . . . . . . . . . . . . . . . . . . . . 22 76 4.7. PANA Session List . . . . . . . . . . . . . . . . . . . . 23 77 4.8. Dictionary Entry . . . . . . . . . . . . . . . . . . . . . 24 79 5. API Definitions . . . . . . . . . . . . . . . . . . . . . . . 25 80 5.1. Initialization and Configuration . . . . . . . . . . . . . 25 81 5.2. Registering Callbacks . . . . . . . . . . . . . . . . . . 26 82 5.3. PANA Session Management . . . . . . . . . . . . . . . . . 28 83 5.4. PANA Operation . . . . . . . . . . . . . . . . . . . . . . 31 84 5.5. EP Control . . . . . . . . . . . . . . . . . . . . . . . . 38 85 5.6. Dictionary Lookup . . . . . . . . . . . . . . . . . . . . 39 86 5.7. Message Management . . . . . . . . . . . . . . . . . . . . 42 88 6. Security Consideration . . . . . . . . . . . . . . . . . . . . 49 90 7. Changes from previous version . . . . . . . . . . . . . . . . 50 92 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 51 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 95 Intellectual Property and Copyright Statements . . . . . . . . . . 53 97 1. Introduction 99 Protocol for carrying Authentication for Network Access (PANA) 100 provides secure network access [1]. This document describes the 101 design of an API in C for applications to implement PANA. PANA is 102 used with an Authorization, Authentication and Accounting (AAA) 103 protocol such as Diameter and Radius. So the PANA API must be 104 compatible with Diameter and Radius. This API is designed to combine 105 with Diameter API which is proposed in [2]. This API will help to 106 implement the AAA architecture using PANA and Diameter. 108 PANA is developing protocol and may be changed partially. This API 109 provides only the basic function and depends on the implementation 110 for some function (e.g. PAA-EP communication, NAP/ISP 111 authentication, EP driven PAA discover, and so on). This means that 112 API users can extend PANA protocol to suite your goals using this 113 API. We provide a simple example of an implementation of the PANA 114 protocol using this API at the tail of this document. 116 2. API specifications 118 2.1. MultiThread 120 PANA API uses multithread. PANA API's operation includes listening 121 the messages, manegement of the timer, executing the callback, and so 122 on. They should be performed by different thread because they may be 123 performed at one time. Conflicts of data-access may occur in the 124 system using multithread. Thus, API implementers must be careful not 125 to create a situation where one PANA Session interferes with other 126 PANA Sessions. 128 2.2. Result Reporting 130 PANA API reports results which contain detailed descriptions of any 131 errors. API implementers are encouraged to output errors to log 132 files so that API users can be made aware of why errors has 133 occurring. 135 2.3. List Structures 137 The PANA API defines list structures. This section describes how 138 these structures are used. 140 2.3.1. PANA Sessions 142 The PAA can have multiple PANA Sessions. The PAA must distinguish 143 PANA Sessions in individual cases. PANA Sessions are distinguished 144 by a session identifier. The session identifier of a PANA Session is 145 initialized by the PAA and is globally and eternally unique. The 146 method of how to initialize the session identifier is the same as the 147 method defined in Diameter [3]. A PANA Session must be added to the 148 PANA Session List when the session is initialized, and must be 149 deleted from the PANA Session List when the session is terminated. 151 2.3.2. AVPs 153 All PANA Messages have many AVPs in an AVP List. The PaC and PAA 154 refer to the AVP List when they parce the PANA Messages. AVP List is 155 initialized when a PANA Message is created. 157 2.3.3. Callbacks 159 PANA API defines callbacks which are called by events when receiving 160 messages and passing times. Callbacks are identified by a 161 PANACallBackHandle, which is generated when the callback is 162 registered. 164 2.3.3.1. Message Callback 166 If Message Callback is registered, registered callback is called when 167 the PANA Messages are received. Callbacks are registered with PANA 168 Message Code. 170 2.3.3.2. Timer Callback 172 If a Timer Callback is registered, it is called when a block of time 173 has passed. Callbacks are registered with a Timer Event Handle. 175 2.4. EP Control 177 The function of an EP is per-packet policy enforcement. A PAA tells 178 an EP how policies are enforced. [4] details that SNMP is used for 179 EP-PAA communication. But how to communicate with EP is 180 implementation dependent. And [1] details that an EP may trigger PaC 181 discovery. This API does not define how to discover PaC's. Thus, 182 this function is implementation dependent. 184 2.5. Configuration Files 186 The PANA API uses configuration files. This section describes how 187 these configuration files are used. These configuration files should 188 be written in XML due to the existence of many available XML parsing 189 libraries. 191 2.5.1. Dictionary File 193 PANA Messages are created and parsed by the PaC or PAA. The Pac and 194 PAA can identify which PANA Messages and AVPs are supported from the 195 contents of the Message Dictionary File. The location and name of 196 Message Dictionary File are platform-specific. 198 2.5.2. Configuration File 200 The PaC and PAA can learn how to initialize PANA Sessions and PANA 201 Messagesfrom the contents of the Configuration File. The 202 Configuration File contains environment-specific information (e.g. 203 IP address, device identifier) and operational information (e.g. how 204 to discover the PAA). 206 3. Data Type Definitions 208 3.1. Constant Types 210 3.1.1. IP address and Port 212 typedef struct sockaddr_storage PANA_IP_ADDR; 214 PANA_IP_ADDR provides a way of referring to IP address and port 215 information. This data supports both IPv4 and IPv6. 217 3.1.2. Vendor Identifier 219 typedef uint32_t PANAVendorID; 221 PANAVendorID provides a way of referring to the vendor identification 222 code. This is used when creating messages and registering callbacks. 224 3.1.3. Value Type Identifier 226 typedef uint32_t PANAValue; 228 PANAValue provides a way of referring to particular dictionary- 229 defined values. This is used when looking up the dictionary. 231 3.1.4. Device Identifier 233 typedef void PANADeviceID; 235 PANADeviceID provides a way of referring to the device identifier 236 such as MAC address. This is used as one of the PANA Session 237 parameters. 239 3.1.5. Session Identifier 241 typedef void PANASessionID; 243 PANASessionID is an identifier for a particular PANA Session. The 244 format of session identifier is same as is defined in [3] 246 3.1.6. Cookie 248 typedef void Cookie; 250 Cookie is a random value that is generated according to [6]. This is 251 used for making PAA discovery robust against blind resource 252 consumption DoS attacks. 254 3.1.7. Callback Handle 256 typedef void PANACallbackHandle; 258 The PANACallbackHandle is a type for representing the callback handle 259 returned to the client when a callback is registered. This handle is 260 used when de-registering a callback from the Callbacl List. 262 3.1.8. Message Authentication Code 264 typedef void MACvalue; 266 MACValue is an encrypted message used for ensuring message integrity. 267 This is a cipher of the PANA Message using the session key and a 268 particular configured algorithm. 270 3.1.9. Provider Information 272 3.1.9.1. Provider Identifier 274 typedef uint32_t PANAProviderID; 276 PANAProviderID provides a way of referring to the Provider 277 identification code. The value of Provider identifier is assigned by 278 IANA. This is used in the ISP-Information AVP of NAP-Information 279 AVP. 281 3.1.9.2. Provider Name 283 typedef void PANAProviderName; 285 PANAProviderName is of type UTF8String, and contains the UTF8-encoded 286 name of the provider. This is used in the ISP-Information AVP or 287 NAP-Information AVP. 289 3.1.10. Key Materials 291 3.1.10.1. Key Identifier 293 typedef uint32_t MSKIdentifier; 295 MSKIdentifier provides a way of referring to the MSK using an 296 Identifier code. This value is assigned by the PAA and must be 297 unique within the PANA Session. 299 3.1.10.2. MSK 301 typedef void MSK; 303 MSK is a key generated by an EAP method. This is one of the 304 materials that derives all keys used in the PANA Session. 306 3.1.10.3. PANA-AUTH-KEY 308 typedef void PANAAuthKey; 310 PANA-AUTH-KEY is a key derived from the MSK. the length of a 311 PANAAuthKey varies depending on which algorithm is used to calculate 312 the PANA-AUTH-KEY. This key is used to generate a Message 313 Authentication Code. 315 3.1.10.4. PaC-EP-Master-Key 317 typedef void PaCEPMasterKey; 319 PaC-EP-Master-Key is a key derived from the MSK. The length of the 320 PaCEPMasterKey is 64 octets. This key is used to filter packets 321 between a PaC and EP. 323 3.1.10.5. nonce 325 typedef void Nonce; 327 Nonce has random value and the length of Nonce must be between 8 and 328 256 octets inclusive. This is one of the materials of which all keys 329 used in the PANA Session are derived. 331 3.1.11. PANA Message Type 333 typedef uint16_t PANAMessageType; 335 PANAMessageType contains 2 octets of data and is managed by IANA. 336 This value is used to communicate the message type associated with 337 the message. 339 3.1.12. Pseudo-random Function 341 The following values are difined in [7]. The Pseudo-random Function 342 is one of the PANA Session attributes. This is used when deciding 343 the function that derives the PANA-AUTH-KEY and PaC-EP-Master-Key. 344 All PANA implementations must support PRF_HMAC_SHA1: 346 typedef enum { 347 PRF_HMAC_MD5, 348 PRF_HMAC_SHA1, 349 PRF_HMAC_TIGER, 350 PRF_AES128_CBC 351 } PseudoRandomFunction; 353 3.1.13. Integrity Algorithm 355 The following values are defined in [7]. The Integrity Algorithm is 356 used for computing the AUTH AVP value. All PANA implementations must 357 support AUTH_HMAC_SHA1_160: 359 typedef enum { 360 NONE, 361 AUTH_HMAC_MD5_96, 362 AUTH_HMAC_SHA1_96, 363 AUTH_DES_MAC, 364 AUTH_KDPK_MD5, 365 AUTH_AES_XCBC_96, 366 AUTH_HMAC_SHA1_160 367 } IntegrityAlgorithm; 369 3.1.14. AVP Codes 371 The following values are AVP Codes which are used in PANA. They are 372 defined in the PANA specification [1]: 374 typedef enum { 375 AVP_ALGORITHM = 1, 376 AVP_AUTH, 377 AVP_COOKIE, 378 AVP_DEVICE_ID, 379 AVP_EAP_PAYLOAD, 380 AVP_FAILED, 381 AVP_ISP_INFORMATION, 382 AVP_KEY_ID, 383 AVP_NAP_INFORMATION, 384 AVP_NONCE, 385 AVP_NOTIFICATION, 386 AVP_PPAC, 387 AVP_PROTECTION_CAPABILITY, 388 AVP_PROVIDER_IDENTIFIER, 389 AVP_PROVIDER_NAME, 390 AVP_RESULT_CODE, 391 AVP_SESSION_ID, 392 AVP_SESSION_LIFETIME, 393 AVP_TERMINATION_CAUSE 395 } PANAAVPCode; 397 3.1.15. PANA Message Codes 399 The following values are PANA Message Codes which are used in PANA. 400 They are defined in the PANA specification [1]: 402 typedef enum { 403 PANA_CLIENT_INITIATION = 1, 404 PANA_START, 405 PANA_AUTH, 406 PANA_REAUTH, 407 PANA_BIND, 408 PANA_PING, 409 PANA_TERMINATION, 410 PANA_ERROR, 411 PANA_UPDATE 412 } PANAMessageCode; 414 3.1.16. PANA Session Attributes 416 The following values are used for specifing PANA Session attributes. 417 PANA Session attributes are defined in [1]: 419 typedef enum { 420 SESSION_IDENTIFIER, 421 DEVICE_IDENTIFIER_PAC, 422 IP_ADDR_PEER, 423 DEVICE_IDENTIFIER_EP, 424 SEQUENCE_NUMBER_TRANSMIT, 425 SEQUENCE_NUMBER_RECEIVE, 426 PANA_MESSAGE, 427 RETRANSMISSION_INTERVAL, 428 SESSION_LIFETIME, 429 PPAC, 430 NONCE_LOCAL, 431 NONCE_PEER, 432 MSK, 433 MSK_IDENTIFIER, 434 PANA_AUTH_KEY, 435 PSEUDO_RANDOM_FUNCTION, 436 INTEGRITY_ALGORITHM, 437 PANA_PING_TIME, 438 PANA_PHASE 439 } PANASessionAttribute; 441 3.1.17. PANA Message Flags 443 The following values are used for PANA Message flags. PANA Message 444 flags are contained in the PANA header and specify how PANA works: 446 typedef enum { 447 REQUEST = 0x8000, 448 STATELESS_HANDSHAKE = 0x4000, 449 NOTSET = 0x0000 450 } PANAMessageFlag; 452 REQUEST This message is a request. 454 STATELESS_HANDSHAKE The PAA is performing stateless discovery. This 455 flag is contained in the PANA-Start-Request message. If this flag 456 is set, Coolie AVP must be included in the PANA-Start Messages. 458 NOTSET No flags is set. 460 3.1.18. Protection Capability 462 The following values are used for Protection-Capability AVP value. 463 Protection-Capability indicates the cryptographic data protection 464 capability supported and required by the EPs: 466 typedef enum { 467 L2_PROTECTION, 468 IPSEC_PROTECTION 469 } ProtectionCapabilityCode; 471 3.1.19. AVP Flags 473 The following values are used for AVP flags. AVP flags are contained 474 in AVP header and specify how AVPs are handled: 476 typedef enum { 477 PANA_AVP_FLAG_NONE = 0x0000, 478 PANA_AVP_FLAG_MANDATORY = 0x8000, 479 PANA_AVP_FLAG_VENDOR = 0x4000 480 } PANAAVPFlag; 482 PANA_AVP_FLAG_NONE No AVP flags are set. 484 PANA_AVP_FLAG_MANDATORY If either the AVP or its value is 485 unrecognized, the message must be rejected and receiver must send 486 a PANA-Error-Request message. 488 PANA_AVP_FLAG_VENDOR This AVP has optional Vendor-ID field in the 489 AVP header. 491 3.1.20. Termination Cause 493 The following values are used for value of the Termination-Cause AVP. 494 Termination Cause indicates the reason why a session is terminated: 496 typedef enum { 497 LOGOUT, 498 ADMINISTRATIVE, 499 SESSION_TIMEOUT 500 } TerminationCauseCode; 502 LOGOUT The PaC initiated termination of the PANA Session. 504 ADMINISTRATIVE The PaC initiated termination of the PANA Session, 505 due to administrative reasons. 507 SESSION_TIMEOUT The PANA Session has timed out. 509 3.1.21. PPAC 511 The following values are used for value of the PPAC AVP. PPAC 512 indicates available types of post-PANA IP address configuration 513 mechanisms: 515 typedef enum { 516 NO_CONFIGURATION = 0x80000000, 517 DHCPV4 = 0x40000000, 518 DHCPV6 = 0x20000000, 519 STATELESS_AUTOCONFIGURATION = 0x10000000, 520 DHCPV4_WITH_IPSEC_TUNNEL = 0x08000000, 521 IKEV2 = 0x04000000 522 } IntegrityAlgorithm; 524 The PaC deos not configure a new IP address after PANA. 526 DHCPV4 The PaC will use DHCPv4 to configure a new IPv4 address after 527 PANA. 529 DHCPV6 The PaC will use DHCPv6 to configure a new IPv6 address after 530 PANA. 532 STATELESS_AUTOCONFIGRATION The PaC will use stateless IPv6 address 533 autoconfiguration to configure a new IPv6 address after PANA. 535 DHCPV4_WITH_IPSEC_TUNNEL The PaC will use to configure a new IPv4 536 address after PANA. 538 IKEV2 The PaC will use IKEv2 to configure a new IP address after 539 PANA. 541 3.2. Timer Event Handle 543 The following values are used for registering Timer Callback. 545 typedef enum { 546 TIMER_PANA_PING, 547 TIMER_PANA_SESSION_LIFETIME, 548 TIMER_RETRANSMISSION_INTERVAL 549 } TimerEventHandle; 551 TIMER_PANA_PING This event managements the exchange of the PANA-Ping 552 messages. 554 TIMER_PANA_SESSION_LIFETIME This event managements the lifetime of 555 the specific PANA Session. 557 TIMER_RETRANSMISSION_INTERVAL This event managements the 558 retransmission of the request messages. 560 3.3. Filtering Policy on the EP 562 The following values are used for filtering on the EP. This is used 563 when the PANA Session is initialized, authentication is successful, 564 and the PANA Session is terminated: 566 typedef enum { 567 ALL_NODE_DROP, 568 ALL_DROP, 569 ALL_PASS 570 } PANAFilteringFlag; 572 ALL_NODE_DROP The EP drops all packets. 574 ALL_DROP The EP drops all packets from or to a specific IP address. 576 ALL_PASS The EP pass all packets from or to a specific IP address. 578 3.4. Result Code AVP Value 580 The following values are used for reporting whether an EAP 581 authentication had completed successfully or whether an error had 582 occurred. They correspond directory to the valuesdefined in the PANA 583 specification [1]. 585 typedef enum { 586 PANA_SUCCESS = 2001, 587 PANA_AUTHENTICATION_REJECTED = 4001, 588 PANA_AUTHORIZATION_REJECTED = 5003, 589 PANA_MESSAGE_UNSUPPORTED = 3001, 590 PANA_UNABLE_TO_DELIVER = 3002, 591 PANA_INVALID_HDR_BITS = 3008, 592 PANA_INVALID_AVP_FLAGS = 3009, 593 PANA_AVP_UNSUPPORTED = 5001, 594 PANA_UNKNOWN_SESSION_ID = 5002, 595 PANA_INVALID_AVP_DATA = 5004, 596 PANA_MISSING_AVP = 5005, 597 PANA_RESOURCES_EXCEEDED = 5006, 598 PANA_CONTRADICTING_AVPS = 5007, 599 PANA_AVP_NOt_ALLOWED = 5008, 600 PANA_AVP_OCCURS_TOO_MANY_TIMES = 5009, 601 PANA_UNSUPPORTED_VERSION = 5011, 602 PANA_UNABLE_TO_COMPLY = 5012, 603 PANA_INVALID_AVP_LENGTH = 5014, 604 PANA_INVALID_MESSAGE_LENGTH = 5015, 605 PANA_PROTECTION_CAPABILITY_UNSUPPORTED = 5016, 606 PANA_PPAC_CAPABILITY_UNSUPPORTED = 5017 607 } PANAResultCode; 609 3.5. Return Code 611 The following values are used to report result returned by functions 612 in the PANA API. They correspond directoly to values defined in the 613 Diameter API specification [2]: 615 typedef enum { 616 PANA_ERR_NOT_FOUND = -2, 617 PANA_ERR_FAILURE = -1, 618 PANA_ERR_SUCCESS = 0, 619 PANA_ERR_NOMEM, 620 PANA_ERR_PROTO, 621 PANA_ERR_SECURITY, 622 PANA_ERR_PARAMETER, 623 PANA_ERR_CONFIG, 624 PANA_ERR_UNKNOWN_CMD, 625 PANA_ERR_MISSING_AVP, 626 PANA_ERR_ALREADY_INIT, 627 PANA_ERR_TIMED_OUT, 628 PANA_ERR_CANNOT_SEND_MSG, 629 PANA_ERR_ALREADY_REGISTERED, 630 PANA_ERR_CANNOT_REGISTER, 631 PANA_ERR_NOT_INITIATED, 632 PANA_ERR_NETWORK_ERROR, 633 PANA_ERR_READ_ONLY 634 } PANAReturnCode; 636 The following is a description of the error codes and the reasons why 637 they can be returned: 639 PANA_ERR_NOT_FOUND A handle or identifier was not found. 641 PANA_ERR_FAILURE Unspecified failure occurred during the PANA 642 operation. 644 PANA_ERR_SUCCESS The PANA operation succeeded. 646 PANA_ERR_NOMEM There is no available memory. 648 PANA_ERR_PROTO PANA protocol error occurred. 650 PANA_ERR_SECURITY A security check failed or another security error 651 occurred. 653 PANA_ERR_PARAMETER An Invalid parameter was passed to the function. 655 PANA_ERR_CONFIG An error was encountered in a Configuration File. 657 PANA_ERR_UNKNOWN_MSG The library received the PANA Message which is 658 not registered. 660 PANA_ERR_MISSING_AVP The received message does not have required 661 AVPs. 663 PANA_ERR_ALREADY_INIT Initialization is already done. 665 PANA_ERR_TIMED_OUT Lifetime is expired. 667 PANA_ERR_CANNOT_SEND_MSG The library can not send a message. 669 PANA_ERR_ALREADY_REGISTERED Callback or other structure is already 670 registered. 672 PANA_ERR_CANNOT_REGISTER Callback or other structure can not be 673 registered. 675 PANA_ERR_NOT_INITIALIZED The library did not initialized. 677 PANA_ERR_NETWORK_ERROR An error occured in networking. 679 3.6. Callback Location Codes 681 The following values are used to indicate where a callback should be 682 added to the Callback List: 684 typedef enum { 685 PANA_APP_INSTALL_FIRST, 686 PANA_APP_INSTALL_ANYWHERE, 687 PANA_APP_INSTALL_LAST 688 } PANACallbackLocation; 690 PANA_APP_INSTALL_FIRST Add this callback as the first callback in 691 the Callback List. 693 PANA_APP_INSTALL_ANYWHERE Add this callback anywhere in the Callback 694 List. 696 PANA_APP_INSTALL_LAST Add this callback as the last callback in the 697 Callback List. 699 3.7. AVP Data Type Codes 701 The following values are used to specify the AVP data type. They 702 correspond directly to the AVP data types outlined in the PANA 703 specification [1]. 705 typedef enum { 706 PANA_AVP_DATA_TYPE, 707 PANA_AVP_STRING_TYPE, 708 PANA_AVP_ADDRESS_TYPE, 709 PANA_AVP_INTEGER32_TYPE, 710 PANA_AVP_INTEGER64_TYPE, 711 PANA_AVP_TIME_TYPE, 712 PANA_AVP_GROUP_TYPE 713 } PANAAVPDataType; 715 3.8. Search Direction Type 717 The following values are used to specify which direction to search 718 for an AVP in the AVP List: 720 typedef enum { 721 PANA_FORWARD_SEARCH, 722 PANA_BACKWARD_SEARCH 723 } PANASearchType; 725 4. Structure Definitions 727 4.1. AVP Structure 729 The following structure contains the AVP header and value: 731 typedef struct avp { 732 enum { 733 PANA_RADIUS, 734 PANA_DIAMETER 735 } packetType; 736 PANAAVPCode code; 737 uint16_t length; 738 PANAAVPFlag flags; 739 PANAAVPDataType type; 740 PANAVendorID vendorId; 741 void *data; 742 } PANA_AVP; 744 The fields have the following definitions: 746 packetType Indicates whether the backend protocol is Diameter or 747 Radius. If the backend protocol is Radius, flags and vendorId 748 fields are null. 750 code The AVP Code. Identifies this AVP. 752 length The length of the AVP's data field. 754 flags The AVP flags. 756 type The AVP's data type. 758 vendorId The Vendor ID. If the AVP is not vendor-specific, this 759 field is set to PANA_NO_VENDOR_ID. 761 data The AVP data, in host byte order. 763 4.2. ISP/NAP-Information AVP Value 765 The following structure contains an ISP/NAP-Information AVP value. 766 The ISP/NAP-Information AVP is defined in : 768 typedef struct informationAvpValue { 769 PANAProviderID providerId; 770 PANAProviderName *providerName; 771 } PANAInformationAVPValue; 773 The fields have the following definitions: 775 providerId An identifier of a NAP or ISP. 777 providerName A name of a NAP or ISP. 779 4.3. Notification AVP Value 781 The following structure contains a Notification AVP value. The 782 Notification AVP is defined in [1]: 784 typedef struct notificationAvpValue { 785 uint16_t length; 786 char *tag; 787 char *displayableString; 788 } PANANotificationAvpValue; 790 The fields have the following definitions: 792 length The length of the Language Tag in octets. 794 tag The Language Tag defined in [8] to indicate the language used 795 for the displayable string. 797 displayableString UTF-8 encoded ISO 10464 value with characters 798 using the Language Tag. The length of this data is determined by 799 the AVP Length field and the Language Tag Length field. 801 4.4. AVP List 803 The following structure is used for representing lists of AVPs in the 804 message: 806 typedef struct avpList { 807 PANA_AVP *head; 808 PANA_AVP *tail; 809 } PANA_AVP_List; 811 4.5. PANA Message 813 The following structure contains the PANA header and information 814 which is used to send the PANA Message: 816 typedef struct message { 817 uint8_t version; 818 uint16_t length; 819 PANAMessageFlag flags; 820 PANAMessageType type; 821 uint32_t sequence_num; 822 uint8_t count_retransmit; 823 PANAVendorID vendorId; 824 PANAResultCode resultCode; 825 PANA_IP_ADDR sender; 826 PANA_AVP_List *avpList; 827 PANAMessageCode messageCode; 828 uint32_t time_retransmit; 829 time_t startTime; 830 PANA_IP_ADDR destination; 831 } PANA_Message; 833 The fields have the following definitions: 835 version The version number of PANA. 837 length The length of the PANA Message including the header fields. 839 flags PANA header flags 841 type Message type. 843 sequence_num The sequence number which is initialized with each PANA 844 Session. 846 count_retransmit Count of retransmission. 848 vendorId The vendor identifier of the PANA Message. 850 resultCode The Result Code indicating the result of the request. 852 originator The IP address of the message's originator. 854 sender The IP address of the message's sender. 856 avpList The AVP List in the message. 858 messageCode The PANA Message Code. 860 time_retransmit The retransmission time of the request message. 862 startTime The number of seconds at which the message was started. 864 destination The IP address the message is sent to. 866 4.6. PANA Session 868 The following structure contains PANA Session attributes. PANA 869 Session attributes are defined in [1]: 871 typedef struct panaSession { 873 enum { 874 PANA_PHASE_NONE = 0, 875 PANA_PHASE_HANDSHAKE, 876 PANA_PHASE_AUTHANDAUTH, 877 PANA_PHASE_ACCESS, 878 PANA_PHASE_TERMINATION 879 } PANASessionPhase; 881 PANASessionID *sessionId; 882 uint32_t sessionId_len; 883 PANADeviceID *pac_deviceId; 884 uint32_t pac_deviceId_len; 885 PANA_IP_ADDR *peer_addr; 886 PANADeviceID *ep_deviceId; 887 uint32_t ep_deviceId_len; 888 uint32_t sequence_num_transmit; 889 uint32_t sequence_num_receive; 890 PANA_Message *message; 891 uint32_t time_retransmit; 892 uint32_t session_lifetime; 893 ProtectionCapabilityCode pcCode; 894 Nonce *peer_nonce; 895 uint32_t peer_nonce_len; 896 Nonce *my_nonce; 897 uint32_t my_nonce_len; 898 MSK *msk; 899 uint32_t msk_len; 900 MSKIdentifier *mskId; 901 PANA_AUTH_KEY *panaAuthKey; 902 uint32_t panaAuthKey_len; 903 PseudoRandomFunction prf; 904 IntegrityAlgorithm algorithm; 905 uint32_t ping_timer; 906 } PANA_Session; 908 sessionId The identifier of the PANA Session. 910 pac_deviceId The identifier of the device of the PaC. 912 peer_addr The IP address and Port number of the peer node. 914 ep_deviceId The identifier of the device of the EP. 916 sequence_num_transmit The sequence number of the last transmitted 917 request. 919 sequence_num_receive The sequence number of the last received 920 request. 922 message The last transmitted message. 924 time_retransmit The interval from the last transmission of the 925 request to retransmission. 927 session_lifetime The length of lifetime until the PANA Session is 928 expired. 930 pcCode The code which indicates Protection-Capability. 932 peer_nonce The random value that is generated by the peer node for 933 deriving the PANA_AUTH_KEY. 935 my_nonce The random value which is generated by myself for deriving 936 the PANA_AUTH_KEY. 938 aaaKey The key that is generated by the EAP authentication. 940 aaaKeyId The identifier that spesifies MSK. 942 panaAuthKey The key that is derived from MSK. 944 prf The function to be used for deriving PANA_AUTH_KEY. 946 algorithm The algorithm to be used for computing AUTH AVP. 948 ping_timer The interval of the PANA-Ping-Request. 950 4.7. PANA Session List 952 The following structure is used for representing lists of PANA 953 Sessions: 955 typedef struct sessionList { 956 PANA_Session *head; 957 PANA_Session *tail; 958 } PANASession_List; 960 4.8. Dictionary Entry 962 The following structure is returned by the dictionary entry lookup 963 functions. It contains information about a particular AVP in the 964 dictionary: 966 typedef struct dictionaryEntry { 967 PANAAVPCode avpCode; 968 char *avpName; 969 PANAAVPDataType avpType; 970 PANAVendorID vendorId; 971 PANAAVPFlag flags; 972 } PANADictionaryEntry; 974 5. API Definitions 976 5.1. Initialization and Configuration 978 This section describes the initialization and configuration functions 979 of PANA API. 981 5.1.1. PANAOpen() 983 The following function is used to open and configure the PANA 984 library: 986 PANAReturnCode PANAOpen(char *configFileName); 988 This function must be called before any other PANA functions are 989 called. Operations performed by this function are loading AVPs, 990 initiating filters on the EP, and loading dictionary and 991 configuration files. 993 The parameter is a pointer to the full pathname for the Configuration 994 File. If the value is null or an empty string, the API loads the 995 configuration file in the default pathname. 997 The return values are: 999 PANA_ERR_SUCCESS If initialization has succeeded. 1001 PANA_ERR_ALREADY_INIT If the library is already initialized. 1003 PANA_ERR_NETWORK_ERROR If the PAA can not access the EP. 1005 PANA_ERR_NOMEM If no memory was available. 1007 PANA_ERR_CONFIG If processing the dictionary or configuration 1008 information failed. 1010 5.1.2. PANAClose() 1012 The following function is used to close the PANA library: 1014 PANAReturnCode PANAClose(); 1016 After this function is called, all other PANA functions are 1017 unavailable. 1019 The return values are: 1021 PANA_ERR_SUCCESS If termination has succeeded. 1023 PANA_ERR_NOT_INITIALIZED If PANA was not initialized. 1025 5.1.3. PANAGetDefaultConfigFileName() 1027 The following function is used to get the default path of the 1028 Configuration File: 1030 const char *PANAGetDefaultConfigFileName(); 1032 The return value is a pointer to the full pathname of the 1033 Configuration File. 1035 5.2. Registering Callbacks 1037 This section describes the registration functions of callbacks. 1039 5.2.1. PANARegisterMessageCallback() 1041 The following function is used to register callbacks for specific 1042 PANA Messages: 1044 PANACallbackHandle 1045 *PANARegisterMessageCallback(PANAMessageCode messageCode, 1046 PANAMessageFlag requestFlag, 1047 PANAVendorID vendorId, 1048 char *messageName, 1049 PANACallback callback, 1050 PANACallbackLocation position); 1052 The parameters are: 1054 messageCode The code of the PANA Message processed by the callback. 1056 requestFlag The flags. 1058 vendorId The vendor identifier of the PANA Message. 1060 messageName The pointer to the name of the PANA Message. 1062 callback The callback function to perform processing. 1064 position The position of the callback in the Message Callback List. 1066 The return value is a handle that identifies the registered callback. 1068 5.2.2. PANARegisterTimerCallback() 1070 The following function is used to register callbacks for timer 1071 events: 1073 PANACallbackHandle 1074 *PANARegisterTimerCallback(TimerEventHandle handle, 1075 PANACallback callback, 1076 PANACallbackLocation position); 1078 The parameters are: 1080 handle The code of the timer event processed by the callback. 1082 callback The callback function to perform processing. 1084 position The position of the callback in the Timer Callback List. 1086 The return value is a handle that identifies registered callback. 1088 5.2.3. PANADeregisterMessageCallback() 1090 The following function is used to delete callbacks from the Message 1091 Callback List: 1093 PANAReturnCode 1094 PANADeregisterMessageCallback(PANACallbackHandle *handle); 1096 The parameter is the handle of the callback to be deleted. 1098 The return values are: 1100 PANA_ERR_SUCCESS Deletion has succeeded. 1102 PANA_ERR_FAILURE Deletion has failed. The callback is not deleted. 1104 PANA_ERR_NOT_FOUND Specified handle was not found. 1106 5.2.4. PANADeregisterTimerCallback() 1108 The following function is used to delete callbacks from the Timer 1109 Callback List: 1111 PANAReturnCode 1112 PANADeregisterTimerCallback(PANACallbackHandle *handle); 1114 The parameter is the handle of the timer callback to be deleted. 1116 The return values are: 1118 PANA_ERR_SUCCESS Deletion has succeeded. 1120 PANA_ERR_FAILURE Deletion has failed. The callback is not deleted. 1122 PANA_ERR_NOT_FOUND Specified handle was not found. 1124 5.3. PANA Session Management 1126 This section describes the management function of the PANA Session. 1127 Management of the PANA Session contains initialization, 1128 configuration, and termination. 1130 5.3.1. PANANewSession() 1132 The following function is used to initialize the PANA Session and 1133 return a pointer to the identifier of the initialized PANA Session. 1134 The initialized PANA Session is added to the PANA Session List: 1136 PANAReturnCode PANANewSession(PANA_IP_ADDR peer_addr, 1137 PANASessionId **id); 1139 At that time a PANA Session is initialized, the PAA computes the 1140 session identifier of the PANA Session. A PANA Session is 1141 initialized after the PAA has received the PANA-Start-Answer message 1142 or after PaC has received the PANA-Auth-Request message. 1144 The parameters are: 1146 peer_addr An IP address of the peer. 1148 id The pointer to the pointer to the identifier of the PANA Session. 1150 The return values are: 1152 PANA_ERR_SUCCESS Initialization has succeeded. 1154 PANA_ERR_NOMEM If no memory is available. 1156 PANA_ERR_PARAMETER Some parameters are invalid. 1158 5.3.2. PANAFreeSession() 1160 The following function is used to release the PANA Session and delete 1161 from the PANA Session List: 1163 PANAReturnCode PANAFreeSession(PANASessionId *id); 1165 The parameter is the pointer to the identifier of the PANA Session. 1167 The return values are: 1169 PANA_ERR_SUCCESS Termination of the PANA Session has succeeded. 1171 PANA_ERR_FAILED Termination of the PANA Session has failed. 1173 5.3.3. PANARegisterSession() 1175 The following function is used to register as assigned session from 1176 the given message. This function is used by PaC. 1178 PANAReturnCode 1179 PANARegisterSession(PANAMessage *message, 1180 PANASessionId **id); 1182 The parameters are: 1184 message The pointer to the message. 1186 id The pointer to the pointer to the session identifier of the PANA 1187 Session. 1189 The return values are: 1191 PANA_ERR_SUCCESS The PANA Session was registered successfully. 1193 PANA_ERR_NOMEM There is no memory available. 1195 PANA_ERR_MISSING_AVP The message did not have enough AVPs. 1197 PANA_ERR_ALREADY_REGISTERED The PANA Session is already registered. 1199 5.3.4. PANASetSessionAttribute() 1201 The following function is used to configure the PANA Session. This 1202 function can set the value to PANA Session attributes of the specific 1203 PANA Session: 1205 PANAReturnCode 1206 PANASetSessionAttribute(PANASessionId *id, 1207 PANASessionAttribute attributeName, 1208 void *value, 1209 uint32_t value_len); 1211 The parameters are: 1213 id The pointer to the identifier of the PANA Session. 1215 attributeName The code of the PANA Session attribute. 1217 value The value to be set with the attributeName in the PANA Session 1218 attributes. 1220 value_len The length of the attribute value. 1222 The return values are: 1224 PANA_ERR_SUCCESS Attribute was set successfully. 1226 PANA_ERR_FAILUERE Attribute was not set. 1228 5.3.5. PANAGetSessionAttribute 1230 The following funtion is used to get attributes from the PANA 1231 Session: 1233 void 1234 *PANAGetSessionAttribute(PANASessionId *id, 1235 PANASessionAttributeCode attributeName, 1236 char** value, 1237 uint32_t value_len); 1239 The parameters are: 1241 id The pointer to the identifier of the PANA Session. 1243 attributeName The code of the PANA Session attribute. 1245 value The pointer to the pointer to the return value. 1247 value_len The length of the attribute value. 1249 The return value is a pointer to the specified AVP value. 1251 5.3.6. PANASessionValidityCheck() 1253 The following function is used to check whether the PANA Session is 1254 valid. The criteria is whether the PANA Session attributes are valid 1255 and whether the PANA Session lifetime has expired: 1257 PANAReturnCode PANASessionValidityCheck(PANASessionId *id); 1259 The parameter is a pointer to the identifier of the PANA Session. 1261 The return values are: 1263 PANA_ERR_SUCCESS The PANA Session is valid. 1265 PANA_ERR_TIMED_OUT The PANA Session has already expired. 1267 PANA_ERR_PARAMETER Some of the PANA Session attributes are invalid. 1269 5.3.7. PANADeriveAuthKey() 1271 The following function is used to derive the PANA-AUTH-KEY from the 1272 MSK and set the PANA-AUTH-KEY as a PANA Session attribute: 1274 PANAReturnCode PANADeriveAuthKey(PANASessionId *id); 1276 The parameter is a pointer to the identifier of the PANA Session. 1278 The return values are: 1280 PANA_ERR_SUCCESS The PANA-AUTH-KEY was derived successfully. 1282 PANA_ERR_PARAMETER Some of key materials are invalid. 1284 5.3.8. PANADeriveMasterKey() 1286 The following function is used to derive the PaC-EP-Master-Key from 1287 the MSK and set the PaC-EP-Master-Key to the EP: 1289 PANAReturnCode PANADeriveMasterKey(PANASessionId *id); 1291 The parameter is a pointer to the identifier of the PANA Session. 1293 The return values are: 1295 PANA_ERR_SUCCESS The PaC-EP-Master-Key was derived successfully. 1297 PANA_ERR_NETWORK_ERROR The PaC-EP-Master-Key was not dsitributed to 1298 the EP. 1300 PANA_ERR_PARAMETER Some of key materials are invalid. 1302 5.4. PANA Operation 1304 This section describes PANA operation function. PANA operation 1305 includes creating messages and sending messages. PANA messages are 1306 created and sent according to [5]. 1308 5.4.1. PANAClientInitiation() 1310 The following function is used to initiate the handshake with PAA. 1311 Ths PaC sends the PANA-Client-Initiation message to the PAA: 1313 PANAReturnCode PANAClientInitiation(PANA_IP_ADDR *ip, 1314 PANA_AVP_LIST *avp_list); 1316 The parameters are: 1318 ip The PAA's unicast address. If this parameter contains NULL, the 1319 PaC attempts to get PAA's IP address through DHCP. 1321 avp_list The pointer to the AVP list which is inserted to the 1322 message. 1324 The return values are: 1326 PANA_ERR_SUCCESS The PANA-Client-Initiation message was sent 1327 successfully. 1329 PANA_ERR_NOMEM There is no memory available. 1331 PANA_ERR_CANNOT_SEND_MSG The PaC could not send the PANA-Client- 1332 Initiation message. 1334 5.4.2. PANAStart() 1336 The following function is used to initialize the PANA Session. In 1337 the case of the PAA, the PAA sends the PANA-Start-Request message to 1338 the PaC. In the case of the PaC, the PaC sends the PANA-Start-Answer 1339 message to the PAA. Initial EAP exchange is supported to reduce 1340 redundant messages. The PAA must be an initiator of the PANA-Start 1341 messages: 1343 PANAReturnCode PANAStart(PANA_IP_ADDR dest, 1344 PANAMessageFlag flag, 1345 PANA_AVP_LIST *avp_list); 1347 The parameters are: 1349 dest Destination IP address. 1351 flag Flags that indicate how this message is handled. 1353 avp_list The pointer to the AVP list which is inserted to the 1354 message. 1356 The return values are: 1358 PANA_ERR_SUCCESS The PANA-Start messages were sent successfully. 1360 PANA_ERR_NOMEM There is no memory available. 1362 PANA_ERR_CANNOT_SEND_MSG The PANA-Start messages can not be sent. 1364 PANA_ERR_PARAMETER The parameters are invalid. 1366 5.4.3. PANAAuth() 1368 The following function is used to authenticate and authorize the PaC. 1369 In the case of the PAA, the PAA sends the PANA-Auth-Request or PANA- 1370 Auth-Answer message to the PaC. In the case of the PaC, the PaC 1371 sends the PANA-Auth-Anser and PANA-Auth-Request message to the PAA. 1372 The PAA must be the initiator of the PANA-Auth messages: 1374 PANAReturnCode PANAAuth(PANASessionId *id, 1375 PANAMessageFlag flag, 1376 PANA_AVP_LIST *avp_list); 1378 The parameters are: 1380 id The pointer to the identifier of the PANA Session. 1382 flag Flags that indicate how this message is handled. 1384 avp_list The pointer to the AVP list which is inserted to the 1385 message. 1387 The return values are: 1389 PANA_ERR_SUCCESS The PANA-Auth messages were sent successfully. 1391 PANA_ERR_NOMEM There is no memory available. 1393 PANA_ERR_CANNOT_SEND_MSG The PANA-Auth messages can not be sent. 1395 PANA_ERR_PARAMETER The parameters are invalid. 1397 PANA_ERR_NOT_FOUND The session identifier is not exist. 1399 5.4.4. PANABind() 1401 The following function is used to deliver the result of 1402 authentication, and bind device identifiers of the PaC and EP, to the 1403 PANA Session. The PAA must be the initiator of the PANA-Bind 1404 messages: 1406 PANAReturnCode PANABind(PANASessionId *id, 1407 PANAResultCode code, 1408 PANAMessageFlag flag, 1409 PANA_AVP_LIST *avp_list); 1411 The parameters are: 1413 id The pointer to the identifier of the PANA Session. 1415 code The Result Code of the PaC's authentication. 1417 flag Flags that indicate how this message is handled. 1419 avp_list The pointer to the AVP list which is inserted to the 1420 message. 1422 The return values are: 1424 PANA_ERR_SUCCESS The PANA-Bind messages were sent successfully. 1426 PANA_ERR_NOMEM There is no memory available. 1428 PANA_ERR_CANNOT_SEND_MSG The PANA-Bind messages can not be sent. 1430 PANA_ERR_PARAMETER The parameters are valid. 1432 PANA_ERR_NOT_FOUND The session identifier is not exist. 1434 5.4.5. PANAPing() 1436 The following function is used to check availability of the PAA or 1437 PaC respectively. Both PAA and PaC can be the initiator of the PANA- 1438 Ping messages: 1440 PANAReturnCode PANAPing(PANASessionId *id, 1441 PANAMessageFlag flag, 1442 PANA_AVP_LIST *avp_list); 1444 The parameters are: 1446 session The pointer to the identifier of the PANA Session. 1448 flag Flags that indicate how this message is handled. 1450 avp_list The pointer to the AVP list. 1452 The return values are: 1454 PANA_ERR_SUCCESS The PANA-Ping messages are sent successfully. 1456 PANA_ERR_NOMEM There is no memory available. 1458 PANA_ERR_CANNOT_SEND_MSG The PANA-Ping messages can not be sent. 1460 PANA_ERR_PARAMETER The parameters are invalid. 1462 PANA_ERR_NOT_FOUND The session identifier is not exist. 1464 5.4.6. PANATermination() 1466 The following function is used to terminate the PANA Session. Both 1467 PAA and PaC can be the initiator of the PANA-Termination messages: 1469 PANAReturnCode 1470 PANATermination(PANASessionId *id, 1471 PANATerminationCauseCode code, 1472 PANAMessageFlag flag, 1473 PANA_AVP_LIST *avp_list); 1475 The parameters are: 1477 id The pointer to the identifier of the PANA Session. 1479 code The Termination Cause Code. The cause of the PANA Session 1480 termination. 1482 flag Flags that indicate how this message is handled. 1484 avp_list The pointer to the AVP list. 1486 The return values are: 1488 PANA_ERR_SUCCESS The PANA-Termination messages were sent 1489 successfully. 1491 PANA_ERR_NOMEM There is no memory available. 1493 PANA_ERR_CANNOT_SEND_MSG The PANA-Termination messages can not be 1494 sent. 1496 PANA_ERR_PARAMETER The parameters are invalid. 1498 PANA_ERR_NOT_FOUND The session identifier is not exist. 1500 5.4.7. PANAError() 1502 The following function is used to report an error with the last 1503 received PANA Message. Both PAA and PaC can be the initiator of the 1504 PANA-Error messages: 1506 PANAReturnCode PANAError(PANASessionId *id, 1507 PANAResultCode code, 1508 PANAMessageFlag flag, 1509 PANA_AVP_LIST *avp_list); 1511 The parameters are: 1513 id The pointer to the identifier of the PANA Session. 1515 code The error Result Code. 1517 flag Flags that indicate how this message is handled. 1519 avp_list The pointer to the AVP list. 1521 The return values are: 1523 PANA_ERR_SUCCESS The PANA-Error messages were sent succcessfully. 1525 PANA_ERR_NOMEM There is no memory available. 1527 PANA_ERR_CANNOT_SEND_MSG The PANA-Error messages can not be sent. 1529 PANA_ERR_PARAMETER The parameters are invalid. 1531 PANA_ERR_NOT_FOUND The session identifier is not exist. 1533 5.4.8. PANAReauth() 1535 The following function is used to re-authentication of the PaC. The 1536 PAA must be the initiator of the PANA-Reauth messages: 1538 PANAReturnCode PANAReauth(PANASessionId *id, 1539 PANAMessageFlag flag, 1540 PANA_AVP_LIST *avp_list); 1542 The parameters are: 1544 id The pointer to the identifier of the PANA Session. 1546 flgs Flags that indicate how this message is handled. 1548 avp_list The pointer to the AVP list. 1550 The return values are: 1552 PANA_ERR_SUCCESS The PANA-Reauth messages were sent successfully. 1554 PANA_ERR_NOMEM There is no memory available. 1556 PANA_ERR_CANNOT_SEND_MSG The PANA-Reauth messages can not be sent. 1558 PANA_ERR_PARAMETER The parameters are invalid. 1560 PANA_ERR_NOT_FOUND The session identifier is not exist. 1562 5.4.9. PANAUpdate() 1564 The following function is used to update the PaC's IP address. The 1565 PaC must be the initiator of the PANA-Update messages: 1567 PANAReturnCode PANAUpdate(PANASessionId *id, 1568 PANA_IP_ADDR updateAddr, 1569 PANAMessageFlag flag, 1570 PANA_AVP_LIST *avp_list); 1572 The parameters are: 1574 id The pointer to the identifier of the PANA Session. 1576 updateAddr The new IP address of the PaC. 1578 flag Flags that indicate how this message is handled. 1580 avp_list The pointer to the AVP list. 1582 The return values are: 1584 PANA_ERR_SUCCESS The PANA-Update messages were sent successfully. 1586 PANA_ERR_NOMEM There is no memory available 1588 PANA_ERR_CANNOT_SEND_MSG The PANA-Update messages can not be sent. 1590 PANA_ERR_PARAMETER The parameters are invalid. 1592 PANA_ERR_NOT_FOUND The session identifier is not exist. 1594 5.5. EP Control 1596 This section describes the EP control functions. EP control includes 1597 setting the PaC-EP-Master-Key to the EP and delivering policy to the 1598 EP: 1600 5.5.1. PANASetMasterKey() 1602 The following function is used to set the PaC-EP-Master-Key to the 1603 EP: 1605 PANAReturnCode PANASetMasterKey(PANA_IP_ADDR ep, 1606 PaC-EP-Master-Key *masterKey); 1608 The parameters are: 1610 ep The IP address of the EP. 1612 masterKey The pointer to the PaC-EP-Master-Key. 1614 The return values are: 1616 PANA_ERR_SUCCESS PaC-EP-Master-Key was set successfully. 1618 PANA_ERR_NETWORK_ERROR PaC-EP-Master-Key could not be sent to the 1619 EP. 1621 5.5.2. PANASetEP() 1623 The following function is used to enforce policy on the EP. 1625 PANAReturnCode PANASetEP(PANA_IP_ADDR ep, 1626 PANA_IP_ADDR host, 1627 PANAFilteringFlag policy); 1629 The parameters are: 1631 ep An IP address of the EP. 1633 host An IP address of the PaC. 1635 policy Enforced policy on EP. 1637 The return values are: 1639 PANA_ERR_SUCCESS Policy was enforced successfully. 1641 PANA_ERR_NETWORK_ERROR Policy can not be sent to the EP. 1643 5.6. Dictionary Lookup 1645 This section describes the Dictionary lookup functions. Dictionary 1646 lookup includes looking up AVPs and messages in the Dictionary File. 1647 The same functions that are defined in section 3.4.4. of [2] may be 1648 applicable. 1650 5.6.1. PANADictionaryEntryFromAVPCode() 1652 The following function is used to look up a adictionary entry using a 1653 message code and a vendor identifier: 1655 PANAReturnCode 1656 PANADictionaryEntryFromAVPCode(PANAAVPCode avpCode, 1657 PANAVendorID vendorId, 1658 PANADictionaryEntry *entry); 1660 The parameters are: 1662 avpCode The code number of the AVP. 1664 vendorId The vendor identifier of the AVP 1666 entry A PANADictionaryEntry structure for returning the entry. 1668 The return values are: 1670 PANA_ERR_SUCCESS The query succeeded. 1672 PANA_ERR_FAILURE No matching dictionary entry was found. 1674 5.6.2. PANADictionaryEntryFromName() 1676 The following function is used to look up a dictionary entry using a 1677 message name and a vendor identifier: 1679 PANAReturnCode 1680 PANADictionaryEntryFromName(char *avpName, 1681 PANAVendorID vendorId, 1682 PANADictionaryEntry *entry); 1684 The parameters are: 1686 avpName The name of the AVP. 1688 vendorId The vendor identifier of the AVP. 1690 entry A PANADictionaryEntry structure for returning the entry. 1692 The return values are: 1694 PANA_ERR_SUCCESS The query succeeded. 1696 PANA_ERR_FAILURE No matching dictionary entry was found. 1698 5.6.3. PANAValueFromName() 1700 The following function is used to look up an AVP value using the AVP 1701 name and a vendor identifier: 1703 PANAValue PANAValueFromName(char *avpName, 1704 char *vendorName, 1705 char *valueName); 1707 The parameters are: 1709 avpName The name of the AVP. 1711 vendorName The name of the vendor. 1713 valueName The name of the value. 1715 The return value is the identifier of the AVP. 1717 5.6.4. PANAValueFromAVPCode() 1719 The following function is used to look up an AVP value using the AVP 1720 code and a vendor identifier: 1722 PANAValue PANAValueFromAVPCode(PANAAVPCode avpCode, 1723 PANAVendorID vendorId, 1724 char *valueName); 1726 The parameters are: 1728 avpCode The code of the AVP. 1730 vendorId The vendor identifier. 1732 valueName The name of the value. 1734 The return value is the identifier of the AVP. 1736 5.6.5. PANALookupValueNameUsingValue() 1738 The following function returns the AVP value name: 1740 const char *PANALookupValueNameUsingValue(PANAAVPCode avpCode, 1741 PANAVendorID vendorId, 1742 PANAValue value); 1744 The parameters are: 1746 avpCode The code of the AVP. 1748 vendorId The vendor identifier. 1750 value The value. 1752 The return value is the value name. 1754 5.6.6. PANAGetMessageCode() 1756 The following function returns the message code and vendor 1757 identifier: 1759 pana_boolean_t PANAGetMessageCode(char *messageName, 1760 PANAMessageCode *messageCode, 1761 PANAVendorID *vendorId); 1763 The parameters are: 1765 messageName The string containing the message name. 1767 messageCode The pointer to the message code. 1769 vendorId The pointer to the vendor identifier. 1771 The return value is _B_TRUE if the command was found. 1773 5.7. Message Management 1775 This section describes the AVP management functions. Message 1776 manamement includes creating messages, adding AVPs, traversing AVP 1777 Lists, and releasing messages. The same functions that are defined 1778 in section 3.4.5. of [2] may be applicable. 1780 5.7.1. PANANewMessage() 1782 The following function allocates a PANAMessageand returns a pointer 1783 to it: 1785 PANAMessage *PANANewMessage(PANAMessageCode messageCode, 1786 PANASessionID *id 1787 PANAVendorID vendorId, 1788 PANAMessage *request, 1789 PANAMessageFlag flg); 1791 The parameters are: 1793 messageCode The code of the message. 1795 id The pointer to the session identifier of the PANA Session. 1797 vendorId The vendor identifier. 1799 request The pointer to the request message. This is used when the 1800 message is created as a answer. 1802 flg The flag of the message. 1804 The return value is the pointer to the allocated message. 1806 5.7.2. PANAFreeMessage() 1808 The following function releases a message allocated through 1809 PANANewMessage(): 1811 PANAReturnCode PANAFreeMessage(PANAMessage **message); 1813 The parameter is a pointer to a pointer to the allocated message. 1815 The return value is PANA_ERR_SUCCESS. 1817 5.7.3. PANACreateAVP() 1819 The following function is used to create an AVP and returns a pointer 1820 to it: 1822 PANAReturnCode PANACreateAVP(PANA_AVP **avp, 1823 PANAAVPCode code, 1824 PANAAVPFlag flag, 1825 PANAVendorID vendorId, 1826 char *data, 1827 size_t length); 1829 The parameters are: 1831 avp The pointer to a pointer to the allocated AVP 1833 code The code of the AVP. 1835 flag The flag of the AVP. 1837 vendorId The vendor identifier. 1839 data The pointer to the AVP value. 1841 length The length of the AVP value. 1843 The return values are: 1845 PANA_ERR_SUCCESS An AVP is allocated successfully. 1847 PANA_ERR_PARAMETER Some parameters are invalid. 1849 PANA_ERR_PROTO Protocol error occured. 1851 PANA_ERR_NOMEM There is no memory available. 1853 5.7.4. PANACreateAndAddAVPToList() 1855 The following function creates an AVP and adds it to the AVP List: 1857 PANAReturnCode PANACreateAndAddAVPToList(PANA_AVP_List **avpList, 1858 PANAAVPCode code, 1859 PANAAVPFlag flag, 1860 PANAVendorID vendorId, 1861 char *data, 1862 size_t length, 1863 PANA_AVP *position); 1865 The parameters are: 1867 avpList The list to which the allocated AVP added. 1869 code The code of the AVP. 1871 flag The flag of the AVP. 1873 vendorId The vendor identifier. 1875 data The pointer to the AVP value. 1877 length The length of the AVP value. 1879 The return values are: 1881 PANA_ERR_SUCCESS An AVP is allocated and added to the list 1882 successfully. 1884 PANA_ERR_NOMEM There is no memory available. 1886 PANA_ERR_PARAMETER Some parameters are invalid. 1888 5.7.5. PANAAddAVPToList() 1890 The following function is used to add the AVP to the AVP List: 1892 PANAReturnCode PANAAddAVPToList(PANA_AVP_List **avpList, 1893 PANA_AVP *avp, 1894 PANA_AVP *position); 1896 The parameters are: 1898 avpList The list to which the AVP added. 1900 avp The pointer to the AVP. 1902 position The pointer to the position the AVP will be added. 1904 The return values are: 1906 PANA_ERR_SUCCESS The AVP added successfully. 1908 PANA_ERR_NOMEM There is no memory available. 1910 PANA_ERR_PARAMETER Sone of parameters are invalid. 1912 5.7.6. PANAFindMatchingAVP() 1914 The following function is used to find an AVP with matching code and 1915 vendor identifier: 1917 PANA_AVP *PANAFindMatchingAVP(PANA_AVP_List **avpList, 1918 PANA_AVP *startAVP, 1919 PANAAVPCode avpCode, 1920 PANAVendorID vendorId, 1921 PANASearchType searchType); 1923 The parameters are: 1925 avpList The List in which the searching AVP is. 1927 startAVP The pointer to the head of the AVP List. 1929 avpCode The code of the AVP. 1931 vendorId The vendor identifier. 1933 searchType The search type to specify which direction to search in 1934 the List. 1936 The return value is a pointer to the found AVP. 1938 5.7.7. PANAJoinAVPLists() 1940 The following function joins together two AVP Lists: 1942 PANAReturnCode PANAJoinAVPLists(PANA_AVP_List *dest, 1943 PANA_AVP_List *source, 1944 PANA_AVP *position); 1946 The parameters are: 1948 dest The destination AVP List. 1950 source The source AVP List to be added to dest. 1952 position The position to add the AVPs to. 1954 The return values are: 1956 PANA_ERR_SUCCESS The AVP Lists were added successfully. 1958 PANA_ERR_PARAMETER Some parameters are invalid. 1960 5.7.8. PANARemoveAVPFromList() 1962 The following function is used to remove the AVP from the AVP List: 1964 PANAReturnCode PANARemoveAVPFromList(PANA_AVP_List *avpList, 1965 PANA_AVP *avp); 1967 The parameters are: 1969 avpList The list from which to remove the AVP. 1971 avp The pointer to the AVP which will be removed. 1973 The return values are: 1975 PANA_ERR_SUCCESS The AVP was removed from the AVP List. 1977 PANA_ERR_PARAMETER Some parameters are invalid. 1979 5.7.9. PANAFreeAVP() 1981 The following function is used to released an AVP: 1983 PANAReturnCode PANAFreeAVP(PANA_AVP **avp); 1985 The paramer is a pointer to a pointer to the AVP to release. 1987 The return values are: 1989 PANA_ERR_SUCCESS The AVP was released. 1991 PANA_ERR_PARAMETER Some parameters are invalid. 1993 5.7.10. PANAGetFirstAVP() 1995 The following function is used to get the first AVP in the AVP List: 1997 PANA_AVP *PANAGetFirstAVP(PANA_AVP_List *avpList); 1999 The parameter is a pointer to the AVP List. 2001 The return value is a pointer to the first AVP in the AVP List. 2003 5.7.11. PANAGetLastAVP() 2005 The following function is used to get the last AVP in the AVP List: 2007 PANA_AVP *PANAGetLastAVP(PANA_AVP_List *avpList); 2009 The parameter is a pointer to the AVP List. 2011 The return value is a pointer to the last AVP in the AVP List. 2013 5.7.12. PANAGetNextAVP() 2015 The following function is used to get the next AVP in the AVP List: 2017 PANA_AVP *PANAGetNextAVP(PANA_AVP *avp); 2019 The parameter is a pointer to the AVP prior to the searching one. 2021 The return value is a pointer to the next AVP. 2023 5.7.13. PANAGetPrevAVP() 2025 The following function is used to get the previous AVP in the AVP 2026 List: 2028 PANA_AVP *PANAGetPrevAVP(PANA_AVP *avp); 2030 The parameter is a pointer to the AVP next to the searching one. 2032 The return value is a pointer to the previous AVP. 2034 5.7.14. PANAConvertAVPToString() 2036 The following function is used to convert the value of the AVP to a 2037 format suitable for log or displayable characters: 2039 char *PANAConvertAVPToString(PANA_AVP *avp, 2040 char *dest, 2041 size_t destLen); 2043 The parameters are: 2045 avp The pointer to the AVP to display. 2047 dest The buffer in which the converted value will be contained. 2049 destLen The length of the destination buffer. 2051 The return value is the converted data. 2053 5.7.15. PANASetMessageResultCode() 2055 The following function is used to set the Result Code value: 2057 PANAReturnCode 2058 PANASetMessageResultCode(PANAMessage *message, 2059 PANAResultCode resultCode); 2061 The parameters are: 2063 message The pointer to the PANA Message to which the Result Code is 2064 set. 2066 resultCode The value of the Result Code AVP. 2068 The return values are: 2070 PANA_ERR_SUCCESS The value of the Result Code AVP was set to the 2071 PANA Message. 2073 PANA_ERR_PARAMETER Some parameters are invalid. 2075 5.7.16. PANAComputeAuthAVP() 2077 The following function is used to compute the value of the AUTH AVP. 2078 The computed value is set to the AUTH AVP: 2080 PANAReturnCode PANAComputeAuthAVP(PANAMessage *message, 2081 PANASessionID *session); 2083 The parameters are: 2085 message The pointer to the PANA Message. 2087 session The pointer to the PANA Session. 2089 The return values are: 2091 PANA_ERR_SUCCESS The AUTH AVP value was set successfully. 2093 PANA_ERR_FAILURE The AUTH AVP value was not set. 2095 6. Security Consideration 2097 This document describes an API and therefore depends on the security 2098 mechanisms defined in the PANA protocol. 2100 7. Changes from previous version 2102 This section describes about changes from previous version. 2104 Changes from draft-pana-hiko-api-00 to draft-pana-hiko-api-01: 2106 Submitted date was changed from June to September. 2108 Changes from draft-pana-hiko-api-01 to draft-pana-hiko-api-02: 2110 PANA_PHASE was added to the PANASessionAttribute. 2112 PANA_ERR_READ_ONLY was added to the PANAReturnCode. 2114 Length of the attribute whose length is variable was added to the 2115 PANA_Session structure. 2117 Length of the value was added to the argument of the 2118 PANASetSessionAttribute function. 2120 Value and its length were added to the argument of the 2121 PANAGetSessionAttribute function. 2123 8. References 2125 8.1. Normative References 2127 [1] Forsberg, D., Ohba, Y., Patil, B., Tschofenig, H., and A. Yegin, 2128 "Protocol for Carrying Authentication for Network access 2129 (PANA)", draft-ietf-pana-pana-12 (work in progress), 2130 August 2006. 2132 [2] Calhoun, P., Frascone, D., and J. Kempf, "The Diameter API", 2133 draft-ietf-dime-diameter-api-00 (work in progress), 2134 February 2006. 2136 [3] Calhoun, P., Loughney, J., Arkko, J., Guttman, E., and G. Zorn, 2137 "Diameter Base Protocol", RFC RFC3588, September 2003. 2139 [4] Mghazli, Y., Ohba, Y., and J. Bournelle, "SNMP usage for PAA-EP 2140 interface", draft-ietf-pana-snmp-05 (work in progress), 2141 January 2006. 2143 [5] Fajardo, V., Ohba, Y., and R. Lopez, "State Machines for 2144 Protocol for Carrying Authentication for Network Access (PANA)", 2145 draft-ietf-pana-statemachine-04 (work in progress), May 2006. 2147 8.2. Informative References 2149 [6] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 2150 Requirements for Security", RFC RFC4086, June 2005. 2152 [7] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2153 RFC RFC4306, December 2005. 2155 [8] Phillips, A. and M. Davis, "Tags for Identifying Languages", 2156 draft-ietf-ltru-registry-14 (work in progress), October 2005. 2158 Authors' Addresses 2160 Yoshihiko Kainuma 2161 Graduate School of Science and Technology, KEIO University 2162 3-14-1 Hiyoshi, Kohoku-ku 2163 Yokohama, Kanagawa 223-8522 2164 Japan 2166 Phone: +81-45-566-1425 2167 Email: hiko@tera.ics.keio.ac.jp 2168 URI: http://www.tera.ics.keio.ac.jp/ 2170 Fumio Teraoka 2171 Graduate School of Science and Technology, KEIO University 2172 3-14-1 Hiyoshi, Kohoku-ku 2173 Yokohama, Kanagawa 223-8522 2174 Japan 2176 Phone: +81-45-566-1425 2177 Email: tera@ics.keio.ac.jp 2178 URI: http://www.tera.ics.keio.ac.jp/ 2180 Full Copyright Statement 2182 Copyright (C) The Internet Society (2006). 2184 This document is subject to the rights, licenses and restrictions 2185 contained in BCP 78, and except as set forth therein, the authors 2186 retain all their rights. 2188 This document and the information contained herein are provided on an 2189 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2190 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2191 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2192 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2193 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2194 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2196 Intellectual Property 2198 The IETF takes no position regarding the validity or scope of any 2199 Intellectual Property Rights or other rights that might be claimed to 2200 pertain to the implementation or use of the technology described in 2201 this document or the extent to which any license under such rights 2202 might or might not be available; nor does it represent that it has 2203 made any independent effort to identify any such rights. Information 2204 on the procedures with respect to rights in RFC documents can be 2205 found in BCP 78 and BCP 79. 2207 Copies of IPR disclosures made to the IETF Secretariat and any 2208 assurances of licenses to be made available, or the result of an 2209 attempt made to obtain a general license or permission for the use of 2210 such proprietary rights by implementers or users of this 2211 specification can be obtained from the IETF on-line IPR repository at 2212 http://www.ietf.org/ipr. 2214 The IETF invites any interested party to bring to its attention any 2215 copyrights, patents or patent applications, or other proprietary 2216 rights that may cover technology that may be required to implement 2217 this standard. Please address the information to the IETF at 2218 ietf-ipr@ietf.org. 2220 Acknowledgment 2222 Funding for the RFC Editor function is provided by the IETF 2223 Administrative Support Activity (IASA).