Network Working Group R. Thayer Expire in six months N. Doraswamy Internet Draft April 1997 IPSEC File Import/Export Format Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract Under certain conditions it is necessary to configure hosts running IP Security [RFC-1825] with security parameters and other information in an out-of-band manner. This draft defines a file format that may be used to exchange such information via removable media or distribution via a web server. Thayer,Doraswamy [Page 1] Internet Draft IPSEC Import/Export Format April 1997 TABLE OF CONTENTS STATUS OF THIS MEMO.............................................1 ABSTRACT........................................................1 1.1 TERMS.......................................................4 2. GENERAL FORMATTING...........................................4 2.1 CONFIGURATION LINE FORMATTING RULES.........................5 2.2 KEYWORDS....................................................5 3. BLOCK CONTENTS...............................................6 3.1 CONFIGURATION BLOCK.........................................6 3.2 SECURITY ASSOCIATION BLOCK..................................6 3.3 POLICY BLOCK................................................8 3.4 NAME BLOCK..................................................8 4. APPLICATIONS.................................................9 4.1 USE OF POLICY BLOCKS WITH KEY MANAGEMENT....................9 4.2 CONFIGURATION OF ISAKMP KEY MANAGEMENT......................9 4.3 POLICY DATABASE APPLICATIONS...............................10 5. COMMAND REFERENCE...........................................11 BEGIN..........................................................11 DESTINATION....................................................11 DESTINATION-MASK...............................................11 END............................................................11 PARAMETER......................................................12 allow-local-modification .....................................12 authentication-lifetime ......................................12 encryption-lifetime ..........................................12 export .......................................................12 generated-by .................................................12 group ........................................................13 iv-size ......................................................13 Thayer,Doraswamy [Page 2] Internet Draft IPSEC Import/Export Format April 1997 key-value ....................................................13 kms-authentication ...........................................13 kms-encryption ...............................................13 kms-hash .....................................................13 merge ........................................................14 pfs ..........................................................14 sa-lifetime ..................................................14 skey-value ...................................................14 spi ..........................................................14 window-size ..................................................14 PEER...........................................................15 PRECEDENCE.....................................................15 SOURCE.........................................................15 SOURCE-MASK....................................................16 TRANSFORM......................................................16 6. SECURITY CONSIDERATIONS.....................................16 7. REFERENCES..................................................16 8. AUTHOR'S ADDRESSES..........................................18 APPENDIX.......................................................19 A. EXAMPLE OF SECURITY ASSOCIATION BLOCK.......................19 B. EXAMPLE OF POLICY BLOCK.....................................20 C. REVISION HISTORY............................................23 Thayer,Doraswamy [Page 3] Internet Draft IPSEC Import/Export Format April 1997 1. Introduction There is a need to configure hosts running IP Security through an out-of-band mechanism. This is needed when manually keyed Security Associations are used, when Pre-defined Shared Secrets are used for ISAKMP Key Management [ISAKMP-OAKLEY], and where general security policy information must be distributed from a central site such as a site-wide IPSEC-aware Firewall. 1.1 Terms Line - a single sequence of text terminated by some line terminator. A line may be greater than 80 characters in length. Block - a collection of lines that describes one set of parameters. White Space - space between tokens. White space must be SPACE or TAB characters. 2. General Formatting The format of this file is designed to provide these features: - secure storage with a flexible set of cryptographic mechanisms - able to be migrated forward to ISO 10646 (multi-byte) text The file contains this: revision number -- a 32-bit unsigned integer, in network order, the current value is 0x01000000 option bitmask -- a 32-bit unsigned integer, in network order salt -- 16 bytes of data fingerprint -- 16 bytes of data containing the character string "--SECURITY FILE-". The option bits are: 0x00000001 - RC4-40 encryption 0x00000002 - RC4-128 encryption Thayer,Doraswamy [Page 4] Internet Draft IPSEC Import/Export Format April 1997 0x00000004 - DES encryption 0x00000008 - 3DES encryption 0x80000000 - text is US-ASCII 0x40000000 - text is ISO 10646(?) (Note the IETF-compliant default is DES [DES].) The encrypted data contains text, currently in US-ASCII but can be ISO 10646 in the future. 2.1 Configuration Line Formatting Rules The text consists of lines of arbitrary length. Lines are terminated by one of these line terminators: - Hex 0x00 (Null) - Hex 0x0d (CR) - Hex 0x0a (LF) - Hex 0x0c (FF) There may be blank lines, these are ignored. There may be comment lines. These start with the character '#' as the first character. The text consists of lines of 'commands' grouped into 'blocks'. Commands consist of combinations of keywords and values. These are separated by 'white space', which may be any number of spaces or tabs. There may be any number of blocks in a single file. 2.2 Keywords The keywords listed here, in US English, shall be supported. At a later time other alternative keyword text, possibly in a different language, may be substituted. Keywords are shown in UPPER CASE in this document for clarity. In the actual file the keywords are case-insensitive. If a command contains a keyword that is not recognized by an implementation, the command must be ignored. Thayer,Doraswamy [Page 5] Internet Draft IPSEC Import/Export Format April 1997 3. Block Contents Parameters are organized in one of four possible blocks, Configuration, Security Association, Policy, or Name. Any number of these blocks may appear in a single file. Each block is delimited by a BEGIN...END pair. 3.1 Configuration Block The configuration block covers information not specific to a single Security Association or Policy Statement. There may be only one config block per file. It contains a begin command, one or more parameter commands, and an end command. This block is optional. If there are no parameters it is not required. A block with no parameter commands shall be silently ignored. Example: BEGIN CONFIGURATION PARAMETER END There are one or more PARAMETER statements. Parameters are represented in a name-value format, where is the name of the parameter, and is a value, expresed as a decimal number. 3.2 Security Association Block The security association block is used to fully specify a security association for a host. If you use manual keying you use this. If you use a firewall to dictate the configuration to a client, you would also use this. It must contain: . begin command . source address . destination address . transform . end command It also may contain: Thayer,Doraswamy [Page 6] Internet Draft IPSEC Import/Export Format April 1997 . source mask . destination mask . peer address . precedence . parameter Example: BEGIN SECURITY-ASSOCIATION SOURCE IPv4
SOURCE-MASK IPv4 DESTINATION IPv4
DESTINATION-MASK IPv4 PEER IPv4
TRANSFORM PRECEDENCE PARAMETER END The source and destination address are required. There may be masks specified for either source or destination or both. A peer may be specified if appropriate. The is any text name (must not include separators.) The name must be unique within this file. The name may be a maximum of 40 characters. The parameter name/value pairs are specific to the transform. These keywords are defined, others are allowed: KEY-VALUE IV-SIZE WINDOW-SIZE SPI Values are always in hexadecimal. No leading '0x' is needed. Each PARAMETER command specifies a single value unless otherwise specified in this document. For example, the following specifies a key-value of 12345678abcdef00cafedead: PARAMETER KEY-VALUE 12345678abcdef00cafedead Thayer,Doraswamy [Page 7] Internet Draft IPSEC Import/Export Format April 1997 The PRECEDENCE value indicates the order in which the wrappers should be applied, with precendence 1 (the lowest) meaning the innermost wrapper nearest the payload. 3.3 Policy Block The policy block is similar to the security association block, except 'policy' is advisory in nature and does not specify precise parameters. It is used for situations where key management or other general rules apply to the use of IP Security. There may be several policy blocks specifying alternative choices for a given source/destination/precedence combination. A policy block must contain: . begin command . transform . end command It may also contain: . source addres . destination address . precedence . parameter . peer address . destination mask . source mask 3.4 Name Block The name block contains identity information and also identifies what policy or security association blocks within a single file that it is associated with. It contains a name parameter, used to identify the user, and one or more name-info parameters which are used to store certificate or equivalent information. Example: begin name thing1-identity parameter name system-operator parameter name-info 3082175614568ad34 end Thayer,Doraswamy [Page 8] Internet Draft IPSEC Import/Export Format April 1997 4. Applications 4.1 Use of Policy Blocks with Key Management If a proposal is being built up then there will be one or more policy blocks each of which contains the same source, destination, and precedence but different transforms and parameters. If there are two or more alternative transforms for a given protocol, they must each have unique priorities. In other words, if two policy blocks have: . same name . same source/mask . same destination/mask . same precedence then if they have different transforms of the same protocol (like two different kinds of ESP) then they must have different priorities and they must both have priorities. 4.2 Configuration of ISAKMP Key Management ISAKMP security associations are configured using a variant of the policy block, which can include a KEY-VALUE parameter for pre-shared secrets. See the additional non-DOI names in the TRANSFORM description also. For the ISAKMP/Oakley Security Association negotiation, you would have a Transform of Oakley, an encryption algorithm parameter, a hash algorithm parameter, an authentication parameter, and a pre- shared secret. Since there are multiple possibilities for encryption algorithm, hash algorithm, and authentication scheme, there would be multiple policy blocks. Example: begin policy ed-kms-sample-1 # example ISAKMP/Oakley S-A Proposal (one of a set) transform key-oakley parameter kms-encryption key-encrypt-des parameter kms-hash key-hash-md5 parameter kms-authentication key-auth-pre-shared parameter key-value 313233343536373839 Thayer,Doraswamy [Page 9] Internet Draft IPSEC Import/Export Format April 1997 parameter pfs 1 end 4.3 Policy Database Applications If policy blocks are being used with a database application it may be necessary to specify addressing information separately from configuration information. In this case the names of the blocks are used to identify combinations of blocks that apply to specific node pairs. For example, if a given pair of nodes 10.0.0.1 and 10.0.0.2 are to use either: . ESP DES with HMAC MD5 and replay OR . 1828 AH MD5 and 1829 DES ESP then the following set of blocks would be used: begin policy proposal1 source ipv4 10.0.0.1 destination ipv4 10.0.0.2 end begin policy proposal1 # information for ESP DES with HMAC MD5 here end begin policy proposal2 source ipv4 10.0.0.1 destination ipv4 10.0.0.2 end begin policy proposal2 # information for 1828 AH end begin policy proposal2 # information for 1829 ESP end This can be parsed by detecting that the 'policy1' set occurs before the 'policy2' set and therefore is higher priority, and associating all the 'policy1' blocks together and all the 'policy2' blocks together. Thayer,Doraswamy [Page 10] Internet Draft IPSEC Import/Export Format April 1997 5. Command Reference Each line of a block contains one command. This section contains reference information for each command. See the descriptions of the individual blocks for an explanation of which commands apply to which blocks. BEGIN The BEGIN command marks the beginning of a block. There are three possible formats: BEGIN CONFIGURATION BEGIN SECURITY-ASSOCIATION BEGIN POLICY The name is case sensitive. This is the only value that is case sensitive. DESTINATION The DESTINATION command contains an Ipv4 or Ipv6 destination address. The format is: DESTINATION where addr-type is ipv4 or ipv6. DESTINATION-MASK The DESTINATION-MASK command contains an Ipv4 or Ipv6 network mask. The format is: DESTINATION-MASK where addr-type is ipv4 or ipv6 and addr-mask-value is a mask, in n.n.n.n (i.e. 255.255.255.0 like CIDR [CIDR]) format for ipv4 and . END The END command marks the end of a block. Thayer,Doraswamy [Page 11] Internet Draft IPSEC Import/Export Format April 1997 PARAMETER The PARAMETER command contains a configuration value. The format is: PARAMETER Private parameters are allowed, as well as the following general parameters: allow-local-modification ALLOW-LOCAL-MODIFICATION <1 or 0> means this file may be edited locally if 1, default is 1 authentication-lifetime AUTHENTICATION-LIFETIME Lifetime of authentication key. First argument is soft limit (in hex, remember), second argument is hard limit, and third argument is 'SEC' if units are seconds, or 'KB' if units are kilobytes. encryption-lifetime ENCRYPTION-LIFETIME Lifetime of encryption key. First argument is soft limit (in hex, remember), second argument is hard limit, and third argument is 'SEC' if units are seconds, or 'KB' if units are kilobytes. export export <1 or 0> means this file is intended to be safe for export use relative to the country in which the file was generated. Note it would be a good idea to use comments near this parameter. generated-by GENERATED-BY Thayer,Doraswamy [Page 12] Internet Draft IPSEC Import/Export Format April 1997 specifies vendor/component that generated the file. OPTIONALLY this may be an SNMP object identifier to mark the software that generated the file, e.g. enterprise.252.2.1 group GROUP <1> specifies Oakley Default Group. Must be a 1. iv-size iv-size <20 or 40> Number of bits in initial vector for DES encryption schemes. Note the number is in hex. key-value key-value Represents the key value for this block, in hex, as a number. kms-authentication KMS-AUTHENTICATION Authentication scheme for ISAKMP/OAKLEY. Possible values are key-auth-dss, key-auth-rsa, key-auth-rsa-encrypt. kms-encryption KMS-ENCRYPTION Encryption scheme for ISAKMP/OAKLEY. Possible values are key- encrypt-des, key-encrypt-idea, or key-encrypt-blowfish. kms-hash KMS-HASH Thayer,Doraswamy [Page 13] Internet Draft IPSEC Import/Export Format April 1997 Hashing scheme for ISAKMP/OAKLEY. Possible values are key-hash- md5 or key-hash-sha or key-hash-tiger. merge MERGE <1 or 0> If 1, means this file may be merged into existing local security information store if that is relevant. If 0, means overwrite the default value if no merge parameter is specified shall be 1 (allow merge) pfs PFS <1 or 0> If 1, ISAKMP/OAKLEY will use Perfect Forward Secrecy. sa-lifetime SA-LIFETIME Lifetime of security association. First argument is soft value (in hex, remember), second argument is hard value, and third argument is 'SEC' if units are seconds, or 'KB' if units are kilobytes. skey-value skey-value used when key is stored using S/Key. spi spi this is the SPI number for security association blocks. window-size WINDOW-SIZE Thayer,Doraswamy [Page 14] Internet Draft IPSEC Import/Export Format April 1997 This is the window size for transforms that use replay options. PEER The PEER command specifies the other end of an Ipv4 or Ipv6 tunnel. The format is: PEER where addr-type is ipv4 or ipv6. PRECEDENCE The PRECEDENCE command specifies the order in which security protocol headers are placed in an IP packet. For example, a regular Ipv4 packet looks like this: IP Header -- Payload Then, adding one AH header, you have IP Header -- AH Header -- Payload If there are multiple headers, the order must be specified to avoid confusion. The 'precedence' does this. The INNER-MOST security header, the one nearest the payload, is numbered ONE. For example, a packet with AH and two ESP headers, like this: IP -- AH[x] -- ESP[y] -- ESP[z] -- Payload has precedence 1 for ESP[z], precedence 2 for ESP[y], and precedence 3 for AH[x]. SOURCE The SOURCE command contains an Ipv4 or Ipv6 source address. The format is: SOURCE where addr-type is ipv4 or ipv6. Thayer,Doraswamy [Page 15] Internet Draft IPSEC Import/Export Format April 1997 SOURCE-MASK The SOURCE-MASK command contains an Ipv4 or Ipv6 network mask. The format is: SOURCE-MASK where addr-type is ipv4 or ipv6 and addr-mask-value is a mask, in n.n.n.n (i.e. 255.255.255.0 like CIDR [CIDR]) format for ipv4 and . TRANSFORM The TRANSFORM command specifies what cryptographic transform is to be used. The field of the TRANSFORM entry is a name from [DOI], currently these include: AH-1828 AH-HMAC-MD5-REPLAY AH-HMAC-SHA-REPLAY ESP-1829-TRANSPORT ESP-1829-TUNNEL ESP-DES-CBC-HMAC-REPLAY (DENY-ALL) (ALLOW-CLEAR) KEY-OAKLEY 6. Security Considerations This file format is used to store security information (e.g. keys) used for IP Security between hosts. It therefore must be protected appropriately. For this reason the file is always stored in an encrypted manner using one of the defined encryption schemes. 7. References [CIDR] Classless Inter-Domain Routing (CIDR): an Address Assignment and Aggregation Strategy, RFC 1519. [DES] US National Bureau of Standards, "Data Encryption Standard", Federal Information Processing Standard (FIPS) Publication 46, January, 1977. Thayer,Doraswamy [Page 16] Internet Draft IPSEC Import/Export Format April 1997 [DOI] D. Piper, "The Internet IP Security Domain of Interpretation for ISAKMP", draft-ietf-ipsec-doi-01.txt. [ISAKMP-OAKLEY] D.Harkins, D.Carrel, "The resolution of ISAKMP with Oakley", draft-ietf-ipsec-isakmp-oakley-02.txt. [RFC-1825] R. Atkinson, "Security Architecture for the Internet Protocol", 08/09/1995. (Pages=22) (Format=.txt) Thayer,Doraswamy [Page 17] Internet Draft IPSEC Import/Export Format April 1997 8. Author's Addresses Rodney Thayer Sable Technology Corporation 246 Walnut Street Newton Massachusetts 02160 rodney@sabletech.com +1 617 332 7292 Fax +1 617 332 7970 Naganand Doraswamy FTP Software 2 High Street North Andover, Massachusetts naganand@ftp.com +1 508 685 4000 Thayer,Doraswamy [Page 18] Internet Draft IPSEC Import/Export Format April 1997 Appendix A. Example of Security Association Block Here is an example of an Import/Export File, before encryption and ASCII Armoring. # Sample IPSEC Import/Export File BEGIN CONFIGURATION PARAMETER ALLOW-LOCAL-MODIFICATION 1 PARAMETER generated-by enterprise.252.2.1 END BEGIN SECURITY-ASSOCIATION sample-ah SOURCE IPV4 10.0.0.1 DESTINATION IPV4 10.2.0.0 DESTINATION-MASK IPV4 255.255.255.0 PEER IPV4 10.0.0.2 TRANSFORM AH-1828 PRECEDENCE 2 PARAMETER SPI 11110001 PARAMETER KEY-VALUE 12345678123456781234567812345678 END BEGIN SECURITY-ASSOCIATION sample-esp SOURCE IPV4 10.0.0.1 DESTINATION IPV4 10.2.0.0 DESTINATION-MASK IPV4 255.255.255.0 PEER IPV4 10.0.0.2 TRANSFORM ESP-1829 PRECEDENCE 1 PARAMETER SPI 11110002 PARAMETER KEY-VALUE 9999888877776666 PARAMETER IV-SIZE 20 END Thayer,Doraswamy [Page 19] Internet Draft IPSEC Import/Export Format April 1997 B. Example of Policy Block # this says it's export-controlled, can be locally modified, # and sable.2.1 is it's oid watermark # BEGIN CONFIGURATION PARAMETER EXPORT 0 PARAMETER ALLOW-LOCAL-MODIFICATION 1 PARAMETER generated-by enterprise.252.2.1 END # # this says 10.1.0.1 to 10.1.0.2 uses either md5 or sha1 for AH # note spi and key are set by the key management component # BEGIN POLICY thing1-thing2-ah SOURCE IPV4 10.1.0.1 DESTINATION IPV4 10.1.0.2 transform ah-1828 precedence 2 END begin policy thing1-thing2-ah source ipv4 10.1.0.1 destination ipv4 10.1.0.2 transform ah-sha1 precedence 2 end Thayer,Doraswamy [Page 20] Internet Draft IPSEC Import/Export Format April 1997 # # this says 10.1.0.2 to 10.1.0.1 uses either md5 or sha1 for AH # note spi and key are set by the key management component # BEGIN POLICY thing2-thing1-ah SOURCE IPV4 10.1.0.2 DESTINATION IPV4 10.1.0.1 transform ah-1828 precedence 2 END begin policy thing2-thing1-ah source ipv4 10.1.0.2 destination ipv4 10.1.0.1 transform ah-sha1 precedence 2 end # # this says 10.1.0.1 to 10.1.0.2 uses des with iv32 for ESP # begin policy thing1-thing2-esp source ipv4 10.1.0.1 destination ipv4 10.1.0.2 transform esp-1829-transport precedence 1 # check the doi to make sure IV is expressed in bits parameter iv-size 20 end # # this says 10.1.0.2 to 10.1.0.1 uses des with iv32 for ESP # begin policy thing2-thing1-esp source ipv4 10.1.0.2 destination ipv4 10.1.0.1 transform esp-1829-transport precedence 1 # don't need priority, there's only one choice parameter iv-size 20 end # this entry says client 10.1.0.3 uses a tunnel to 10.3.0.99 for # subnet 10.2.0.0/255.255.0.0 Thayer,Doraswamy [Page 21] Internet Draft IPSEC Import/Export Format April 1997 begin policy thing3 source ipv4 10.1.0.3 destination ipv4 10.2.0.0 destination-mask ipv4 255.255.0.0 peer ipv4 10.3.0.99 precedence 1 # don't need priority, there's only one choice transform esp-des-cbc-hmac-replay parameter window-size 8 end Thayer,Doraswamy [Page 22] Internet Draft IPSEC Import/Export Format April 1997 C. Revision History This is revision 00 of this document. Thayer,Doraswamy [Page 23]