Network Working Group R. Thayer
Expire in six months N. Doraswamy
Internet Draft April 1997
IPSEC File Import/Export Format
<draft-thayer-sec-exp-00.txt>
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 <name>
PARAMETER <param-name> <value>
END
There are one or more PARAMETER statements. Parameters are
represented in a name-value format, where <param-name> is the
name of the parameter, and <value> 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 <name>
SOURCE IPv4 <address>
SOURCE-MASK IPv4 <mask>
DESTINATION IPv4 <address>
DESTINATION-MASK IPv4 <mask>
PEER IPv4 <address>
TRANSFORM <doi-name>
PRECEDENCE <value>
PARAMETER <param-name> <param-value>
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 <name> 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 <name>
BEGIN SECURITY-ASSOCIATION <name>
BEGIN POLICY <name>
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 <addr-type> <addr-value>
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 <addr-type> <addr-mask-value>
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
<appropriate stuff for ipv6>.
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 <param-name> <value>
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 <value1> <value2> <sec or kb>
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 <value1> <value2> <sec or kb>
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 <component>
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 <key in hex>
Represents the key value for this block, in hex, as a number.
kms-authentication
KMS-AUTHENTICATION <auth-scheme-name>
Authentication scheme for ISAKMP/OAKLEY. Possible values are
key-auth-dss, key-auth-rsa, key-auth-rsa-encrypt.
kms-encryption
KMS-ENCRYPTION <encryption-name>
Encryption scheme for ISAKMP/OAKLEY. Possible values are key-
encrypt-des, key-encrypt-idea, or key-encrypt-blowfish.
kms-hash
KMS-HASH <hash-name>
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 <value1> <value2> <sec or kb>
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 <stuff>
used when key is stored using S/Key.
spi
spi <value in hex>
this is the SPI number for security association blocks.
window-size
WINDOW-SIZE <value>
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 <addr-type> <addr-value>
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 <addr-type> <addr-value>
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 <addr-type> <addr-mask-value>
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
<appropriate stuff for ipv6>.
TRANSFORM
The TRANSFORM command specifies what cryptographic transform is
to be used. The <doi-name> 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]