Security Policy Management API, Version 1 o the security policy management API was extended to the PF_KEY v2 Security Architecture for the Internet Protocol [RFC2401] does not define the structure of the security policy database (SPD), the parameters to be managed by the local system, and the application interface to manage the SPD. that is why there are several implementation to manage the SPD. FreeS/WAN, KAME, OpenBSD (and Solaris (i'm not sure)) have something in common with this API. all of them are based on the PF_KEY version 2 [RFC2367]. however, they are slightly different from each of them. o question, requirement and consideration - security policy management(SPM) API between applications and a kernel should be unified for portability of applications on userland. - SPM API should be separated from PF_KEY API because SPD management is basically different from SAD management. - if SPM API was implemented to a kernel, the API must not obstruct the existing security policy API based on the PF_KEY. - the selectors in SPD must be compared to traffics by same orders in anytime. - a securitty policy describes the way to process a traffic matched with either of the selectors belonging to it. the processing in the kernel, dicard, bypass and ipsec is defined by RFC2401, multiple SAs might belong to a security policy. it is necessary that an SA is not allowed to use other policies. a SA might be used by multiple policies. the following picture describes the relation between the selectors, the policies and the SAs. 1. selector1 --- policy1 --- sa1 2. selector2 --- policy2 --- sa2 \ +- sa3 3. selector3 -+ \ selector4 --- policy3 -+- sa4 4. selector5 --- policy4 --- sa5 / selector6 --- policy5 -+ the type no.4 might not be used for IKEv2 negotiation. - multiple identical SAs for multiple ends behind SGWs should be established between two SGWs. end11 SA1 for both end11 and end21 end21 \ ============================== / +- SGW1 SGW2 -+ / ============================== \ end12 SA1 for both end12 and end22 end22 - a selector of security policy in the SPD can identify a single security policy. a selector of security policy is a set of parameters like below: source address source address prefix length source port number destination address destination address prefix length destination port number upper layer protocol it might be necessary to specify a security policy simply without using a selector of security policy like listed above. - is a lifetime or some expiration processing necessary ? security policies with a limit by time or bytes might be necessary in some situation. - an application need to know what a security policy for some packet is. - an application need to know what happens to some packet related to itself. an userland security policy mangement(USPM) API between an application and security policy management process might be necessary. - SPD must have the range selector for the security policy. and the kernel must process the range selctor too. - is it required that the SPM messages are to be bound to 64bits length ? - this document uses the word "SPM API" as the security policy management API. instead, it might be called PF_POLICY API. o conceptual model +------------+ +----------------+ +--------------+ | key | | policy | | | | management |----[USPM API] management [USPM API]----| application | | process | | process | | | +------------+ +----------------+ +--------------+ | | | | | | | | | ===[PF_KEY]===================[SPM API?]=================[PF_INET]=== | | | | | | | | | +------------+ +------------+ +------------+ | SAD | | SPD | | TCP/IP | | management |-------------| management |--------------| | | engine | | engine | | engine | +------------+ +------------+ +------------+ \ \ (SADB) (SPDB) RFC2367 defines PF_KEY API to maintain the SADB in the kernel. in above picture, the key management process can maintain the SADB in the kernel through PF_KEY API. similarly, the policy management process maintains the SPD in the kernel through SPM API. applications which is not interested in its security policy simply send packets through the PF_INET. in this case, appropriate security policy might be installed by other application before that. then the SPD management engine determines the way to process the packet. SPD management engine request SAD management engine to take apropriate SA(s) for the packets if the policy requires IPsec of the packet. when the SA(s) are not found, SAD management engine request to establish SA(s) to the key management process through the PF_KEY API. the key management process ask the policy management process what the policy including SA bundle is for the request with the policy index which is passed by the PF_KEY API. some applications are interested in its own security policy. in this case, the application sends security policy to the policy management process with its identity. the policy management process then installs the policy and return a security policy index to the application, or error status if some trouble happened. the application is able to track both the state of own security policy and SA state belonging to the policy because the application can ask to the policy management process with the policy index. when the key management process needs the identity of the application, the key management process ask the policy management process with the policy index. for an implementation idea, it is useful that the key management process and the policy management process are to be single process. o Selector Sequence Number a implementation might needs to list security policies sequentially in order to compare between a packet and a selector. Policy Sequence Number is 32 bits length for this purpose. it must be unique in the SPD, however, it is unnecessary to be monotonical. 0 is reserved. policy sequence numbers might be renumbered sometime. note that all implementation do not need to implement it. o Security Policy Index Security Policy Index is 32 bits length to identify a security policy. it must not be used in the outside of the local system. both of 0 and 0xffffffff are reserved. o Security Association Index each security association is distinguished by all of destination address, security protocol and security parameter index even when the SAs belong to a single security policy. a security policy uses these SAs chronologically. Secrutiy Association Index is 32 bits length to bind an SA to a security policy. in other word, SAs chronologically used by a security policy is grouped by Security Association Index. the parameters in the SAD might have the Security Association Indexes because it could be used to specify a security policy which the SA belongs to. o Security Policy Selector what a member of the selector of the SPD is an implementation issue. however, the following parameters should be included in the selector. source address source prefix source port source address range source port range destination address destination prefix destination port destination address range destination port range upper layer protocol number icmp type icmp code ipv6 extension header type ipv4 option type o Security Policy Rule as RFC2401 defineds, a security policy must have three behaviors of the kernel when the kernel processes a packet. bypass discard ipsec o SPM payload and naming. spdb_ spdb_x_ o Base message header format of SPM API struct spdb_msg { u_int8_t spdb_msg_version; u_int8_t spdb_msg_type; u_int8_t spdb_msg_errno; u_int8_t spdb_msg_reserved; u_int32_t spdb_msg_len; u_int32_t spdb_msg_pid; }; spdb_msg_version; 1 spdb_msg_type; it describes below. spdb_msg_len the total message length of bytes. spdb_msg_pid indicates which process is bound for the message. or which process is originated this message o Extension message header format of SPM API + Security policy extension Security policy extension header specifies the way to process a traffic. this structure also includes the direction of a traffic. struct spdb_policy { u_int16_t spdb_policy_len; u_int16_t spdb_policy_exttype; u_int16_t spdb_policy_type; u_int16_t spdb_policy_flags; u_int32_t spdb_policy_index; }; spdb_policy_len length of the header in 64 bit words. it is always 2. spdb_policy_exttype SPDB_EXT_POLICY spdb_policy_type the type of the policy. SPDB_POLICY_DISCARD SPDB_POLICY_IPSEC SPDB_POLICY_BYPASS spdb_policy_flags it specifies functions to be required for the security policy. SPDB_POLICY_FLAGS_UDPENCAP 0x0001 spdb_policy_index it contains a Security Policy Index. + Selector Extension Selector Extension contains a base information of selectors for a security policy. struct spdb_selector { u_int16_t spdb_selector_len; u_int16_t spdb_selector_exttype; u_int8_t spdb_selector_dir; u_int8_t spdb_selector_counts; u_int16_t spdb_selector_seq; }; spdb_selector_exttype; SPDB_EXT_SELECTOR spdb_selector_dir the direction of the packet which the policy matches with. SPDB_SELECTOR_DIR_INBOUND SPDB_SELECTOR_DIR_OUTBOUND spdb_selector_counts a count of selectors included in the security policy. + Selector Element Extension struct spdb_element { u_int16_t spdb_element_len; u_int16_t spdb_element_exttype; u_int8_t spdb_element_which; u_int8_t spdb_element_family; u_int16_t spdb_element_type; }; spdb_element_which SPDB_ELEMENT_SRC 1 SPDB_ELEMENT_DST 2 spdb_element_family SPDB_AF_IPV4 1 SPDB_AF_IPV6 2 spdb_element_type SPDB_ELEMENT_ADDRESS 1 4 or 16 bytes is followed. SPDB_ELEMENT_ADDRESS_NETWORK 2 two of 4 bytes or two of 16 bytes are followed. the first contains an ip address. the second contains a network mask. SPDB_ELEMENT_ADDRESS_RANGE 3 two of 4 bytes or two of 16 bytes are followed. the first contains the begin of address range. the second contains the end of address range. SPDB_ELEMENT_PORT_NUMBER 4 4 bytes is followed. it contains a port number in network byte order. spdb_element_ipv must be set 0 SPDB_ELEMENT_ICMP 5 two of 2 bytes is followed. the first contains an icmp type. the other contains an icmp code. SPDB_ELEMENT_EXTENSION_TYPE 6 spdb_element_value contains an ipv6 extension header or an ipv4 option code. 4 bytes is followd. it contains an number of an ipv6 extension header or an ipv4 option code. SPDB_ELEMENT_PROTOCOL 7 4 bytes is followd. it contains a protocol number. spdb_element_ipv must be set 0 SPDB_ELEMENT_REAL 8 4 or 16 bytes is followed. for UDP encapsulation, it contains an ip address that specifies the address before NAT is applyed. + Security protocol extension header Security protocol extension header specifies the information about a single SA. This extension header is used only when security protocol is required. In other words, when spdb_policy_type in the security policy extension header is SPDB_POLICY_IPSEC, this extension headers MUST be required. In the case of SA bundle, multiple Security protocol extension headers must exist in a single SPM message. The security protocol extension header of the most of innner SA is located to the top of these headers. For example, when ESP is applied to a outbound packet and then AH applys to to the packet, the packet format is like [IP|AH|ESP|data], the extension header about ESP must be placed first, then the extension header about AH must be next. A single security protocol extension header is constructed by two parts. the second part must immediately follows the first part. the First part specifies the security protocol to be used including an ipsec mode, an address family of the addresses of the end point of the SA, a level of the SA and a SA identifier. the second part specifies addresses of the end point of the security association. The second part may not be needed when the ipsec mode is transport mode. the second part is constructed by the source IP address of the SA and immediately followed by the destination IP address of the SA. These are packed into two 4 or 16 bytes. struct spdb_ipsecpolicy { u_int16_t spdb_ipsecpolicy_len; u_int16_t spdb_ipsecpolicy_proto; u_int8_t spdb_ipsecpolicy_mode; u_int8_t spdb_ipsecpolicy_family; u_int8_t spdb_ipsecpolicy_level; u_int8_t spdb_ipsecpolicy_reserved; u_int32_t spdb_ipsecpolicy_said; }; spdb_ipsecpolicy_len length of the ipsecpolicy spdb_ipsecpolicy_proto the security protocol of the security association to be used. SPDB_IPSECPOLICY_PROTO_ESP 1 SPDB_IPSECPOLICY_PROTO_AH 2 SPDB_IPSECPOLICY_PROTO_IPCOMP 3 spdb_ipsecpolicy_mode the protocol mode of the securitfy association to be used. SPDB_IPSECPOLICY_MODE_ANY 1 SPDB_IPSECPOLICY_MODE_TRANSPORT 2 SPDB_IPSECPOLICY_MODE_TUNNEL 3 spdb_ipsecpolicy_family SPDB_AF_IPV4 1 SPDB_AF_IPV6 2 spdb_ipsecpolicy_level the security level of the security association to be used. SPDB_IPSECPOLICY_LEVEL_DEFAULT 1 reference to system default SPDB_IPSECPOLICY_LEVEL_USE 2 use SA if present. SPDB_IPSECPOLICY_LEVEL_REQUIRE 3 require SA. SPDB_IPSECPOLICY_LEVEL_UNIQUE 4 unique SA. spdb_ipsecpolicy_said; the identifier of the security association to be used. this is not security parameter index. this value MUST be zero when the security level is not SPDB_IPSECPOLICY_LEVEL_UNIQUE. +-----------------+-----------------+-----------------+-----------------+ | len | proto | +-----------------+-----------------+-----------------+-----------------+ | mode | family | level | reserved | +-----------------+-----------------+-----------------+-----------------+ | said | +-----------------------------------------------------------------------+ | src address of the SA | +-----------------------------------------------------------------------+ | dst address of the SA | +-----------------------------------------------------------------------+ + Lifetime Extension Lifetime Extension specifies lifetime variants for this security policy. If no Lifetime extension is present the policy has an infinite lifetime. struct spdb_lifetime { u_int16_t spdb_lifetime_len; u_int16_t spdb_lifetime_exttype; u_int32_t spdb_lifetime_allocations; u_int64_t spdb_lifetime_bytes; u_int64_t spdb_lifetime_addtime; u_int64_t spdb_lifetime_usetime; }; spdb_lifetime_exttype SPDB_EXT_LIFETIME_HARD SPDB_EXT_LIFETIME_SORT SPDB_EXT_LIFETIME_CURRENT + Supported Functions Extension Supported Functions Extension contains what functions the kernel supports. struct sadb3_supported { u_int16_t sadb3_supported_len; u_int16_t sadb3_supported_exttype; u_int32_t sadb3_supported_flags; }; sadb3_supported_flags SPDB_SUPPORTED_NAT_T o Message Types SPDB_ADD the SPDB_ADD message allows a process to add the information of a security policy into the SPD in the kernel. when the spdb_policy_index in the message is 0, the kernel defines the policy index for the security policy, and and the kernel return the policy index to all listening process. user -> kernel kernel -> user SPDB_UPDATE the SPDB_UPDATE message allows a process to update the information in an existing security policy in the kernel. the policy index must be specified. user -> kernel kernel -> user SPDB_DELETE the SPDB_DELETE message allows a process to delete an existing security policy from the SPD in the kernel. a process can send a request to delete a mount of security policies. to specify a amount of security policies, the following list is enable. other specification is disable. policy(dir) policy(index) address(S) address(D) none none none none x none none none none x none none none none x none none none none x user -> kernel kernel -> user user -> kernel kernel -> user user -> kernel kernel -> user SPDB_GET the SPDB_GET message allows a process to retrieve a copy of a security policy from the SPD in the kernel. the kernel must return a mount of security policies that are matched with the selectors exactly. to specify a amount of security policies, the following list is enable. other specification is disable. policy(dir) policy(index) address(S) address(D) none none none none x none none none none x none none none none x none none none none x user -> kernel kernel -> user SPDB_REGISTER the SPDB_REGISTER message allows a process to register its socket as able to listen to SPM messages and to send SPM messages to the kernel. the kernel must return the status if to register the socket is sucessful or not, and return a support function list to the process. send it from an user process to the kernel. return it to the socket that sent the above message. SPDB_EXPIRE the kernel tells all registered processes that a security policy expires by using the SPDB_EXPIRE message. kernel -> user kernel -> user SPDB_QUERY the SPDB_QUERY message allows a process to retrieve a security policy index with which a traffic matches. the selector must contain neither IP addresses range nor network addresses. it is normally used when a user wants to know which security policy matches with a packet. user -> kernel policy_index == 0 user -> kernel policy_index != 0 $Id: memo-pfpolicy-spec.txt,v 1.2 2003/06/06 08:09:00 sakane Exp $