Karp H. Wang, Ed. Internet-Draft Y. Wei Intended status: Standards Track X. Liang Expires: January 6, 2011 ZTE Corporation July 5, 2010 Discussion of the Application Program Interface for KARP framework draft-wang-karp-api-00 Abstract The karp working group aims to secure the packets on the wire of the routing protocol exchanges (i.e. it addresses Keying and Authentication for Routing Protocols) and proposed the framework of Karp. This document discusses the output of KMP function and function of the API used in karp framework and gives the functions call in these APIs. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." This Internet-Draft will expire on January 6, 2011. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of Wang, et al. Expires January 6, 2011 [Page 1] Internet-Draft Discussion of the API for KARP framework July 2010 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. APIs in the Karp framework . . . . . . . . . . . . . . . . . . 4 2.1. KMP-to-RoutingProtocol API . . . . . . . . . . . . . . . . 4 2.2. KeyStore-to-RoutingProtocol API . . . . . . . . . . . . . 4 2.3. KMP-to-KeyStore API . . . . . . . . . . . . . . . . . . . 4 3. KMP-to-RoutingProtocol API . . . . . . . . . . . . . . . . . . 4 3.1. GSA_create_call() . . . . . . . . . . . . . . . . . . . . 4 4. KeyStore-to-RoutingProtocol API . . . . . . . . . . . . . . . 5 4.1. RTSA_inquire_call (): . . . . . . . . . . . . . . . . . . 5 4.2. RTSA_update_call (): . . . . . . . . . . . . . . . . . . . 6 4.3. RTSA_create_call (): . . . . . . . . . . . . . . . . . . . 7 5. KMP-to-KeyStore API . . . . . . . . . . . . . . . . . . . . . 7 5.1. GSA_create_call (): . . . . . . . . . . . . . . . . . . . 7 5.2. Key_inquire_call (): . . . . . . . . . . . . . . . . . . . 8 6. The transfer from GSA to Routing SA . . . . . . . . . . . . . 8 6.1. Generic SA . . . . . . . . . . . . . . . . . . . . . . . . 8 6.2. Routing SA . . . . . . . . . . . . . . . . . . . . . . . . 10 7. IANA considerations . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 9. Normative References . . . . . . . . . . . . . . . . . . . . . 10 Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 Wang, et al. Expires January 6, 2011 [Page 2] Internet-Draft Discussion of the API for KARP framework July 2010 1. Introduction The karp working group aims to secure the packets on the wire of the routing protocol exchanges (i.e. it addresses Keying and Authentication for Routing Protocols). Currently, there are a variety of routing protocols, and their requirements for authentication mechanisms are different. To address it, the karp working group categorizes routing protocols into groups, and believes that the groupings will have like requirements for their authentication mechanisms, and that reuse of authentication mechanisms will be greatest within these grouping. [draft-ietf-karp-design-guide-00] defines four types of messaging transactions used on the wire by the base Routing Protocol (i.e. One-to-One, One-to-Many, peer keying, group keying). This document focuses on One-to-One peer keying scenario, in which a one-to-one, unique keying security association (SA) is to be established between the two routers. For the One-to-One peer keying scenario, there are a variety of keying material definitions. Every routing protocol security mechanism defines its own set of keying materials. So it is hard for the KMP to take all those keying material sets into count. To address this, it is desired to split the kmp design work into two parts: generic security association (GSA) establishment, and GSA conversion. For the generic security association (GSA) establishment part, the KMP just generates generic keying materials (i.e. GSA), and puts it into the KeyStore, which may be used by one or more protocols. For the GSA conversion part, the keystore-to- routingprotocol API converts GSA to specific keying materials (we name it Routing SA) required by specific routing protocol security mechanisms. By splitting the kmp design work into two parts, the kmp designers need only focus on the management of GSA, and the keystore-to- routingprotocol API designers need only focus on the generating of specific keying material for specific routing protocol security mechanisms. Therefore, both of these two tasks are simplified. [draft-karp-sa-def-00] discussed the definition of GSA. However, it does not define the use of GSA in the karp framework [draft-ietf-karp-framework-00], where the GSA is generated by the KMP, used by routing protocol security mechanisms. This document focuses on the definition of APIs, which specifies the use of GSA and is a bridge among kmp, KeyStore, and specific routing protocol security mechanisms. Wang, et al. Expires January 6, 2011 [Page 3] Internet-Draft Discussion of the API for KARP framework July 2010 2. APIs in the Karp framework There are mainly three kinds of APIs which are described in the [draft-ietf-karp-framework-00]. The functions for these APIs are described as follows: 2.1. KMP-to-RoutingProtocol API KMP-to-RoutingProtocol API is responsible for communicating between KMP function and routing protocol security mechanism entity. When routing protocol security mechanism entity needs session key material to protect routing protocol traffic, it triggers KMP functions to create SA. When KMP entity creates GSA successfully, KMP will call KeyStore-to-RoutingProtocol API for storing GSA to KeyStore entity. 2.2. KeyStore-to-RoutingProtocol API KeyStore-to-RoutingProtocol API is responsible for communicating between KeyStore entity and routing protocol security mechanism entity. When routing protocol security mechanism entity needs session key material to protect routing protocol traffic, it will inquire Routing SA, if GSA exists, routing protocol security mechanism entity convert GSA to Routing SA and fetches session key material from Routing SA to protect routing protocol traffic. If there is not corresponded GSA, routing protocol security mechanism entity requires KeyStore entity to create GSA. If the session key material in Routing SA is timeout, KeyStore entity updates the session key material by generating new Routing SA and sending it to routing protocol security mechanism entity. 2.3. KMP-to-KeyStore API KMP-to-KeyStore API is responsible for communicating between KMP function and KeyStore entity. During authentication procedure, KMP function may get authentication information from KeyStore entity. When authentication is finished successfully, KMP function creates GSA and sends it to KeyStore function. 3. KMP-to-RoutingProtocol API The function Call (GSA update call) is defined in this API. 3.1. GSA_create_call() This function mainly aims to trigger to create GSA. When router wants to use session key material to protect routing protocol packets Wang, et al. Expires January 6, 2011 [Page 4] Internet-Draft Discussion of the API for KARP framework July 2010 but can not find the right Routing SA, it calls this function to create GSA. Inputs: o RouterInfoType RouterInfo Outputs: o STATUSTYPE major_status, o GenericSAInfoType GenericSAInfo STATUSTYPE is integer type. Return major_status codes: GenericSA_create_Success indicates the GSA is created successfully. GenericSA_create_Fail indicates the GSA is not created. GenericSAInfoType includes the SA Identifier by which router fetches the right routing SA. 4. KeyStore-to-RoutingProtocol API Two call functions are defined, i.e., RTSA_update_call() and RTSA_inquire_call (). 4.1. RTSA_inquire_call (): This function mainly focuses on inquiring Routing SA to protect the routing protocol packets. When router wants to use session key material to protect routing protocol packets and finds that there is Routing SA for routing protocol packets, router uses this function to get Routing SA and fetches key material from Routing SA. When KeyStore entity receives this function call, it finds the right GSA and converts to routing SA and sends it to routing protocol mechanism. Inputs: o RoutingSAIDType routingSA_ID, o RoutingType routingtype Wang, et al. Expires January 6, 2011 [Page 5] Internet-Draft Discussion of the API for KARP framework July 2010 RoutingSAIDType is the ID attribute for Routing SA. The routingSA_ID is used to find the right Routing SA. RoutingType is the type of Routing protocol. Outputs: o STATUSTYPE major_status, o RoutingSAType routingSAcreateHandle STATUSTYPE is integer type. Return major_status codes: RoutingSA_inquire_Success indicates that Routing SA is found. RoutingSA_inquire_Fail indicates that no Routing SA is found. 4.2. RTSA_update_call (): This function mainly focuses on updating Routing SA to getting new session key material. The session key material used for routing protocol packets is not valid anymore (i.e. the lifetime is timeout). Routing SA gets new session key material by calling this function. Inputs: o RoutingSAType routingSAcreateHandle o RoutingProtocolType routingprotocoltype Outputs: o STATUSTYPE major_status, o RoutingSAType routingSAcreateHandle STATUSTYPE is integer type. Return major_status codes: RoutingSA_update_Success indicates that Routing SA is updated successfully. RoutingSA_ update_Fail indicates that Routing SA fails in updating. In this case, router needs to call RTSA_create_call () to get new Routing SA. Wang, et al. Expires January 6, 2011 [Page 6] Internet-Draft Discussion of the API for KARP framework July 2010 4.3. RTSA_create_call (): This function mainly focuses on creating Routing SA. When router fails to update routing SA, router needs to call RTSA_create_call () to get new Routing SA. Outputs: o STATUSTYPE major_status, o RoutingSAType routingSAcreateHandle STATUSTYPE is integer type. Return major_status codes: RoutingSA_ create_Success indicates that Routing SA is created successfully. RoutingSA_ create_Fail indicates that Routing SA fails in creation. 5. KMP-to-KeyStore API Two call functions are defined, i.e., GSA_create_call () and Key_inquire_call (). 5.1. GSA_create_call (): This function mainly focuses on creating GSA. When authentication is finished, KMP function generates parameters for GSA, and uses GSA_create_call () to create GSA and send GSA to KeyStore entity. Inputs: o RoutingSAType routingSAcreateHandle o RoutingProtocolType routingprotocoltype Outputs: o STATUSTYPE major_status, o RoutingSAType routingSAcreateHandle STATUSTYPE is integer type. Wang, et al. Expires January 6, 2011 [Page 7] Internet-Draft Discussion of the API for KARP framework July 2010 Return major_status codes: GenericSA_create_Success indicates that GSA is created successfully. GenericSA_create_Fail indicates that GSA fails to create. 5.2. Key_inquire_call (): This function mainly focuses on retrieving key material in KeyStore entitiy. During authentication, KMP function uses Key_inquire_call () to fetch key material in KeyStore entity for authentication and generating such parameters as session key materials for ROUTING SA. Inputs: o RouterID routerID routerID is router information used in authentication. Outputs: o STATUSTYPE major_status, o AuthenticationHandle authenticationHandle STATUSTYPE is integer type. Return major_status codes: RoutingSA_Success indicates that Router Key information is fetched successfully. RoutingSA_Fail indicates that Routing Key information fails to be fetched. AuthenticationHandle: authenticationHandle is key material for authentication information. 6. The transfer from GSA to Routing SA 6.1. Generic SA GSA is generated by KMP and can be used for routing protocol security mechanism. Since the security associations for all routing protocol Wang, et al. Expires January 6, 2011 [Page 8] Internet-Draft Discussion of the API for KARP framework July 2010 security mechanism are different, GSA could be designed appropriately so that it can be fit for all kinds of routing protocol security mechanism. The simple way to deal with GSA is that GSA should be the superset for all the routing protocol security association. GSA includes the elements as follows: Key_ID: the security association ID. Auth_Alg_ID: The AlgID field indicates which authentication algorithm to be used with the security protocol for the specified peer. KDF_ID: The KDF field indicates which key derivation function is used to generate short-lived keys from the long-lived value in the Key field. KDF_inputs: The KDF_inputs field stores supplementary data for KDF. Key: The KDF field stores the symmetric cryptographic key. Lifetime: This field indicates the lifetime for key. Some attributes are used to specific routing protocol. Whether all of these attributes should be added to GSA is needed to be considered later. These attributes are as follows: Auth_len: this field indicates the length of authentication header. This field is optional. KeyStartAccept: The time that the router will start accepting packets which have been created with the given key. This field is optional. KeyStartGenerate: The time that the router will start using the key for packet generation. This field is optional. KeyStopGenerate: The time that the router will stop using the key for packet generation. This field is optional. KeyStopAccept: The time that the router will stop accepting packets which have been created with the given key. This field is optional. Connection_ID: this field indicates the connection attributes. The attribute can be used to generate session key material. This field is optional. Wang, et al. Expires January 6, 2011 [Page 9] Internet-Draft Discussion of the API for KARP framework July 2010 6.2. Routing SA Routing SA is converted from Generic SA. Some of GSA attributes such as key_ID, Auth_Alg_ID, lifetime can be copied to Routing SA directly. Some of Routing SA attribute is derived from GSA such as Key. Session key can be derived based on KDF_ID, KDF inputs and key in GSA. According to specific routing protocol, the Routing SA gets different attributes from Generic SA. For example, OSPFv2 SA needs to get such attributes as Auth_len, KeyStartAccept, KeyStartGenerate, KeyStopGenerate and KeyStopAccept from GSA. 7. IANA considerations TBD 8. Security Considerations TBD 9. Normative References [I-D.ietf-karp-design-guide] Lebovitz, G. and M. Bhatia, "Keying and Authentication for Routing Protocols (KARP) Design Guidelines", Feb 2010. Appendix A. Additional Stuff Authors' Addresses Hongyan Wang (editor) ZTE Corporation Nanjing, 210012 China Phone: +86 25 52877993 Email: wang.hongyan4@zte.com.cn Wang, et al. Expires January 6, 2011 [Page 10] Internet-Draft Discussion of the API for KARP framework July 2010 Yinxing Wei ZTE Corporation Nanjing, 210012 China Phone: +86 25 52877993 Email: wei.yinxing@zte.com.cn Xiaoping Liang ZTE Corporation Nanjing, 210012 China Phone: +86 25 52877993 Email: liang.xiaoping@zte.com.cn Wang, et al. Expires January 6, 2011 [Page 11]