Provided by: isakmpd_20041012-10build1_amd64 bug

NAME

     isakmpd.policy — policy configuration file for isakmpd

DESCRIPTION

     isakmpd.policy is the policy configuration file for the isakmpd daemon managing security
     association and key management for the ipsec(4) layer of the kernel's networking stack.

     The isakmpd(8) daemon (also known as IKE, for Internet Key Exchange) is used when two
     systems need to automatically set up a pair of Security Associations (SAs) for securely
     communicating using IPsec.  IKE operates in two stages:

     In the first stage (Main or Identity Protection Mode), the two IKE daemons establish a
     secure link between themselves, fully authenticating each other and establishing key
     material for encrypting/authenticating future communications between them.  This step is
     typically only performed once for every pair of IKE daemons.

     In the second stage (also called Quick Mode), the two IKE daemons create the pair of SAs for
     the parties that wish to communicate using IPsec.  These parties may be the hosts the IKE
     daemons run on, a host and a network behind a firewall, or two networks behind their
     respective firewalls.  At this stage, the exact parameters of the SAs (e.g., algorithms to
     use, encapsulation mode, lifetime) and the identities of the communicating parties (hosts,
     networks, etc.) are specified.  The reason for the existence of Quick Mode is to allow for
     fast SA setup, once the more heavy-weight Main Mode has been completed.  Generally, Quick
     Mode uses the key material derived from Main Mode to provide keys to the IPsec transforms to
     be used.  Alternatively, a new Diffie-Hellman computation may be performed (significantly
     slowing down the exchange, but at the same time providing Perfect Forward Secrecy (PFS)).
     Briefly, this means that even should an attacker manage to break long-term keys used in
     other sessions (or, specifically, if an attacker breaks the Diffie-Hellman exchange
     performed during Main Mode), they will not be able to decrypt this traffic.  Normally, no
     PFS is provided (the key material used by the IPsec SAs established as a result of this
     exchange will be derived from the key material of the Main Mode exchange), allowing for a
     faster Quick Mode exchange (no public key computations).

     IKE proposals are "suggestions" by the initiator of an exchange to the responder as to what
     protocols and attributes should be used on a class of packets.  For example, a given
     exchange may ask for ESP with 3DES and MD5 and AH with SHA1 (applied successively on the
     same packet), or just ESP with Blowfish and RIPEMD-160.  The responder examines the
     proposals and determines which of them are acceptable, according to policy and any
     credentials.

     The following paragraphs assume some knowledge of the contents of the keynote(4) and
     keynote(5) man pages.

     In the KeyNote policy model for IPsec, no distinction is currently made based on the
     ordering of AH and ESP in the packet.  Should this change in the future, an appropriate
     attribute (see below) will be added.

     The goal of security policy for IKE is thus to determine, based on local policy (provided in
     the isakmpd.policy file), credentials provided during the IKE exchanges (or obtained through
     other means), the SA attributes proposed during the exchange, and perhaps other (side-
     channel) information, whether a pair of SAs should be installed in the system (in fact,
     whether both the IPsec SAs and the flows should be installed).  For each proposal suggested
     by or to the remote IKE daemon, the KeyNote system is consulted as to whether the proposal
     is acceptable based on local policy (contained in isakmpd.policy, in the form of policy
     assertions) and remote credentials (e.g., KeyNote credentials or X509 certificates provided
     by the remote IKE daemon).

     isakmpd.policy is simply a flat ascii(7) file containing KeyNote policy assertions,
     separated by blank lines (note that KeyNote assertions may not contain blank lines).
     isakmpd.policy is read when isakmpd(8) is first started, and every time it receives a SIGHUP
     signal.  The new policies read will be used for all new Phase 2 (IPsec) SAs established from
     that point on (even if the associated Phase 1 SA was already established when the new
     policies were loaded).  The policy change will not affect already established Phase 2 SAs.

     For more details on KeyNote assertion format, please see keynote(5).  Briefly, KeyNote
     policy assertions used in IKE have the following characteristics:

        The Authorizer field is typically "POLICY" (but see the examples below, for use of
         policy delegation).

        The Licensees field can be an expression of passphrases used for authentication of the
         Main Mode exchanges, and/or public keys (typically, X509 certificates), and/or X509
         distinguished names.

        The Conditions field contains an expression of attributes from the IPsec policy action
         set (see below as well as the keynote syntax man page for more details).

        The ordered return-values set for IPsec policy is "false, true".

     For an explanation of these fields and their semantics, see keynote(5).

     For example, the following policy assertion:

         Authorizer: "POLICY"
         Licensees: "passphrase:foobar" || "x509-base64:abcd==" ||
           "passphrase-md5-hex:3858f62230ac3c915f300c664312c63f" ||
           "passphrase-sha1-hex:8843d7f92416211de9ebb963ff4ce28125932878"
         Conditions: app_domain == "IPsec policy" && esp_present == "yes"
                     && esp_enc_alg != "null" -> "true";

     says that any proposal from a remote host that authenticates using the passphrase "foobar"
     or the public key contained in the X509 certificate encoded as "abcd==" will be accepted, as
     long as it contains ESP with a non-null algorithm (i.e., the packet will be encrypted).  The
     last two authorizers are the MD5 and SHA1 hashes respectively of the passphrase "foobar".
     This form may be used instead of the "passphrase:..." one to protect the passphrase as
     included in the policy file (or as distributed in a signed credential).

     The following policy assertion:

         Authorizer: "POLICY"
         Licensees: "DN:/CN=CA Certificate"
         Conditions: app_domain == "IPsec policy" && esp_present == "yes"
                     && esp_enc_alg != "null" -> "true";

     is similar to the previous one, but instead of including a complete X509 credential in the
     Licensees field, only the X509 certificate's Subject Canonical Name needs to be specified
     (note that the "DN:" prefix is necessary).

     KeyNote credentials have the same format as policy assertions, with one difference: the
     Authorizer field always contains a public key, and the assertion is signed (and thus its
     integrity can be cryptographically verified).  Credentials are used to build chains of
     delegation of authority.  They can be exchanged during an IKE exchange, or can be retrieved
     through some out-of-band mechanism (no such mechanism is currently supported in this
     implementation however).  See isakmpd.conf(5) on how to specify what credentials to send in
     an IKE exchange.

     Passphrases that appear in the Licensees field are encoded as the string "passphrase:",
     followed by the passphrase itself (case-sensitive).  Alternatively (and preferably), they
     may be encoded using the "passphrase-md5-hex:" or "passphrase-sha1-hex:" prefixes, followed
     by the md5(1) or sha1(1) hash of the passphrase itself, encoded as a hexadecimal string
     (using lower-case letters only).

     When X509-based authentication is performed in Main Mode, any X509 certificates received
     from the remote IKE daemon are converted to very simple KeyNote credentials.  The conversion
     is straightforward: the issuer of the X509 certificate becomes the Authorizer of the KeyNote
     credential, the subject becomes the only Licensees entry, while the Conditions field simply
     asserts that the credential is only valid for "IPsec policy" use (see the app_domain action
     attribute below).

     Similarly, any X509 CA certificates present in the directory pointed to by the appropriate
     isakmpd.conf(5) entry, are converted to such pseudo-credentials.  This allows one to write
     KeyNote policies that delegate specific authority to CAs (and the keys those CAs certify,
     recursively).

     For more details on KeyNote assertion format, see keynote(5).

     Information about the proposals, the identity of the remote IKE daemon, the packet classes
     to be protected, etc. are encoded in what is called an action set.  The action set is
     composed of name-value attributes, similar in some ways to shell environment variables.
     These values are initialized by isakmpd before each query to the KeyNote system, and can be
     tested against in the Conditions field of assertions.  See keynote(4) and keynote(5) for
     more details on the format and semantics of the Conditions field.

     Note that assertions and credentials can make references to non-existent attributes without
     catastrophic failures (access may be denied, depending on the overall structure, but will
     not be accidentally granted).  One reason for credentials referencing non-existent
     attributes is that they were defined within a specific implementation or network only.

     In the following attribute set, IPv4 addresses are encoded as ASCII strings in the usual
     dotted-quad format.  However, all quads are three digits long.  For example, the IPv4
     address 10.128.1.12 would be encoded as 010.128.001.012.  Similarly, IPv6 addresses are
     encoded in the standard x:x:x:x:x:x:x:x format, where the 'x's are the hexadecimal values of
     the eight 16-bit pieces of the address.  All 'x's are four digits long.  For example, the
     address 1080:0:12:0:8:800:200C:417A would be encoded as
     1080:0000:0012:0000:0008:0800:200C:417A.

     The following attributes are currently defined:

     app_domain
              Always set to IPsec policy.

     doi      Always set to ipsec.

     initiator
              Set to yes if the local daemon is initiating the Phase 2 SA, no otherwise.

     phase_1  Set to aggressive if aggressive mode was used to establish the Phase 1 SA, or main
              if main mode was used instead.

     pfs      Set to yes if a Diffie-Hellman exchange will be performed during this Quick Mode,
              no otherwise.

     ah_present, esp_present, comp_present
              Set to yes if an AH, ESP, or compression proposal was received respectively, no
              otherwise.

     ah_hash_alg
              One of md5, sha, ripemd, sha2-256, sha2-385, sha2-512, or des, based on the hash
              algorithm specified in the AH proposal.  This attribute describes the generic
              transform to be used in the AH authentication.

     esp_enc_alg
              One of des, des-iv64, 3des, rc4, idea, cast, blowfish, 3idea, des-iv32, rc4, null,
              or aes, based on the encryption algorithm specified in the ESP proposal.

     comp_alg
              One of oui, deflate, lzs, or v42bis, based on the compression algorithm specified
              in the compression proposal.

     ah_auth_alg
              One of hmac-md5, hmac-sha, des-mac, kpdk, hmac-sha2-256, hmac-sha2-385,
              hmac-sha2-512, or hmac-ripemd.  based on the authentication method specified in the
              AH proposal.

     esp_auth_alg
              One of hmac-md5, hmac-sha, des-mac, kpdk, hmac-sha2-256, hmac-sha2-385,
              hmac-sha2-512, or hmac-ripemd based on the authentication method specified in the
              ESP proposal.

     ah_life_seconds, esp_life_seconds, comp_life_seconds
              Set to the lifetime of the AH, ESP, and compression proposal, in seconds.  If no
              lifetime was proposed for the corresponding protocol (e.g., there was no proposal
              for AH), the corresponding attribute will be set to zero.

     ah_life_kbytes, esp_life_kbytes, comp_life_kbytes
              Set to the lifetime of the AH, ESP, and compression proposal, in kbytes of traffic.
              If no lifetime was proposed for the corresponding protocol (e.g., there was no
              proposal for AH), the corresponding attribute will be set to zero.

     ah_encapsulation, esp_encapsulation, comp_encapsulation
              Set to tunnel or transport, based on the AH, ESP, and compression proposal.

     ah_ecn, esp_ecn, comp_ecn
              Set to yes or no, based on whether ECN was requested for the IPsec tunnel.

     comp_dict_size
              Specifies the log2 maximum size of the dictionary, according to the compression
              proposal.

     comp_private_alg
              Set to an integer specifying the private algorithm in use, according to the
              compression proposal.

     ah_key_length, esp_key_length
              The number of key bits to be used by the authentication and encryption algorithms
              respectively (for variable key-size algorithms).

     ah_key_rounds, esp_key length
              The number of rounds of the authentication and encryption algorithms respectively
              (for variable round algorithms).

     ah_group_desc, esp_group_desc, comp_group_desc
              The Diffie-Hellman group identifier from the AH, ESP, and compression proposal,
              used for PFS during Quick Mode (see the pfs attribute above).  If more than one of
              these attributes are set to a value other than zero, they should have the same
              value (in valid IKE proposals).  Valid values are 1 (768-bit MODP), 2 (1024-bit
              MODP), 3 (155-bit EC), 4 (185-bit EC), and 5 (1536-bit MODP).

     phase1_group_desc
              The Diffie-Hellman group identifier used in IKE Phase 1.  Takes the same values as
              ah_group_desc.

     remote_filter_type, local_filter_type, remote_id_type
              Set to IPv4 address, IPv4 range, IPv4 subnet, IPv6 address, IPv6 range, IPv6
              subnet, FQDN, User FQDN, ASN1 DN, ASN1 GN, or Key ID, based on the Quick Mode
              Initiator ID, Quick Mode Responder ID, and Main Mode peer ID respectively.

     remote_filter_addr_upper, local_filter_addr_upper, remote_id_addr_upper
              When the corresponding filter_type is IPv4 address or IPv6 address, these contain
              the respective address.  For IPv4 range or IPv6 range, they contain the upper end
              of the address range.  For IPv4 subnet or IPv6 subnet, they contain the highest
              address in the specified subnet.

     remote_filter_addr_lower, local_filter_addr_lower, remote_id_addr_lower
              When the corresponding filter_type is IPv4 address or IPv6 address, these contain
              the respective address.  For IPv4 range or IPv6 range, these contain the lower end
              of the address range.  For IPv4 subnet or IPv6 subnet, these contain the lowest
              address in the specified subnet.

     remote_filter, local_filter, remote_id
              When the corresponding filter_type specifies an address range or subnet, these are
              set to the upper and lower part of the address space separated by a dash ('-')
              character (if the type specifies a single address, they are set to that address).

              For FQDN and User FQDN types, these are set to the respective string.  For Key ID,
              these are set to the hexadecimal representation of the associated byte string
              (lower-case letters used) if the Key ID payload contains non-printable characters.
              Otherwise, they are set to the respective string.

              For ASN1 DN, these are set to the text encoding of the Distinguished Name in the
              payload sent or received.  The format is the same as that used in the Licensees
              field.

     remote_filter_port, local_filter_port, remote_id_port
              Set to the transport protocol port.

     remote_filter_proto, local_filter_proto, remote_id_proto
              Set to etherip, tcp, udp, or the transport protocol number, depending on the
              transport protocol set in the IDci, IDcr, and Main Mode peer ID respectively.

     remote_negotiation_address
              Set to the IPv4 or IPv6 address of the remote IKE daemon.

     local_negotiation_address
              Set to the IPv4 or IPv6 address of the local interface used by the local IKE daemon
              for this exchange.

     GMTTimeOfDay
              Set to the UTC date/time, in YYYYMMDDHHmmSS format.

     LocalTimeOfDay
              Set to the local date/time, in YYYYMMDDHHmmSS format.

FILES

     /etc/isakmpd/isakmpd.policy  The default isakmpd policy configuration file.

     /usr/share/ipsec/isakmpd/policy
                                  A sample isakmpd policy configuration file.

EXAMPLES

         Authorizer: "POLICY"
         Comment: This bare-bones assertion accepts everything

         Authorizer: "POLICY"
         Licensees: "passphrase-md5-hex:10838982612aff543e2e62a67c786550"
         Comment: This policy accepts anyone using shared-secret
                  authentication using the password mekmitasisgoat,
                  and does ESP with some form of encryption (not null).
         Conditions: app_domain == "IPsec policy" &&
                     esp_present == "yes" &&
                     esp_enc_alg != "null" -> "true";

         Authorizer: "POLICY"
         Licensees: "subpolicy1" || "subpolicy2"
         Comment: Delegate to two other sub-policies, so we
                  can manage our policy better. Since these subpolicies
                  are not "owned" by a key (and are thus unsigned), they
                  have to be in isakmpd.policy.
         Conditions: app_domain == "IPsec policy";

         KeyNote-Version: 2
         Licensees: "passphrase-md5-hex:9c42a1346e333a770904b2a2b37fa7d3"
         Conditions: esp_present == "yes" -> "true";
         Authorizer: "subpolicy1"

         Conditions: ah_present == "yes" ->
                        {
                            ah_auth_alg == "md5" -> "true";
                            ah_auth_alg == "sha" &&
                            esp_present == "no" -> "true";
                        };
         Licensees: "passphrase:otherpassword" ||
            "passphrase-sha1-hex:f5ed6e4abd30c36a89409b5da7ecb542c9fbf00f"
         Authorizer: "subpolicy2"

         keynote-version: 2
         comment: this is an example of a policy delegating to a CN.
         authorizer: "POLICY"
         licensees: "DN:/CN=CA Certificate/emailAddress=ca@foo.bar.com"

         keynote-version: 2
         comment: This is an example of a policy delegating to a key.
         authorizer: "POLICY"
         licensees: "x509-base64:MIICGDCCAYGgAwIBAgIBADANBgkqhkiG9w0BAQQ\
                     FADBSMQswCQYDVQQGEwJHQjEOMAwGA1UEChMFQmVuQ28xETAPBg\
                     NVBAMTCEJlbkNvIENBMSAwHgYJKoZIhvcNAQkBFhFiZW5AYWxnc\
                     m91cC5jby51azAeFw05OTEwMTEyMjQ5MzhaFw05OTExMTAyMjQ5\
                     MzhaMFIxCzAJBgNVBAYTAkdCMQ4wDAYDVQQKEwVCZW5DbzERMA8\
                     GA1UEAxMIQmVuQ28gQ0ExIDAeBgkqhkiG9w0BCQEWEWJlbkBhbG\
                     dyb3VwLmNvLnVrMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBg\
                     QCxyAte2HEVouXg1Yu+vDihbnjDRn+6k00Rv6cZqbwA3BQ30mC/\
                     3TFJ09VGXCaM0UKfpnxIpkBYLmOA3FWkKI0RvPU7E1AhKkhC1Ds\
                     PSBFjYHrB15T5lYzgfwKJCIxTDzZDx2iobUgPa0FRNGVUjpQ4/k\
                     MJ2BF4Wh7zY3X08rMzsQIDAQABMA0GCSqGSIb3DQEBBAUAA4GBA\
                     DWJ5pbTcE7iKHWLQTMYiz8i9jGi5+Eo1yr1Bab90tgaGQV0zrRH\
                     jDHgAAy1h8WSXuyQrXfgbx2rnWFPhx9CfmuAXn7sZmQE3mnUqeP\
                     ZL2dW87jdBGqtoUdNcoz5zKBkC943yasNui/O01MiqgadTThTJH\
                     d1Pn17LbJC1ZVRNjR5"
         conditions: app_domain == "IPsec policy" && doi == "ipsec" &&
                 pfs == "yes" && esp_present == "yes" && ah_present == "no" &&
                 (esp_enc_alg == "3des" || esp_enc_alg == "aes") -> "true";

         keynote-version: 2
         comment: This is an example of a credential, the signature does
                  not really verify (although the keys are real).
         licensees: "x509-base64:MIICGDCCAYGgAwIBAgIBADANBgkqhkiG9w0BAQQ\
                     FADBSMQswCQYDVQQGEwJHQjEOMAwGA1UEChMFQmVuQ28xETAPBg\
                     NVBAMTCEJlbkNvIENBMSAwHgYJKoZIhvcNAQkBFhFiZW5AYWxnc\
                     m91cC5jby51azAeFw05OTEwMTEyMzA2MjJaFw05OTExMTAyMzA2\
                     MjJaMFIxCzAJBgNVBAYTAkdCMQ4wDAYDVQQKEwVCZW5DbzERMA8\
                     GA1UEAxMIQmVuQ28gQ0ExIDAeBgkqhkiG9w0BCQEWEWJlbkBhbG\
                     dyb3VwLmNvLnVrMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBg\
                     QDaCs+JAB6YRKAVkoi1NkOpE1V3syApjBj0Ahjq5HqYAACo1JhM\
                     +QsPwuSWCNhBT51HX6G6UzfY3mOUz/vou6MJ/wor8EdeTX4nucx\
                     NSz/r6XI262aXezAp+GdBviuJZx3Q67ON/IWYrB4QtvihI4bMn5\
                     E55nF6TKtUMJTdATvs/wIDAQABMA0GCSqGSIb3DQEBBAUAA4GBA\
                     MaQOSkaiR8id0h6Zo0VSB4HpBnjpWqz1jNG8N4RPN0W8muRA2b9\
                     85GNP1bkC3fK1ZPpFTB0A76lLn11CfhAf/gV1iz3ELlUHo5J8nx\
                     Pu6XfsGJm3HsXJOuvOog8Aean4ODo4KInuAsnbLzpGl0d+Jqa5u\
                     TZUxsyg4QOBwYEU92H"
         authorizer: "x509-base64:MIICGDCCAYGgAwIBAgIBADANBgkqhkiG9w0BAQQ\
                      FADBSMQswCQYDVQQGEwJHQjEOMAwGA1UEChMFQmVuQ28xETAPBg\
                      NVBAMTCEJlbkNvIENBMSAwHgYJKoZIhvcNAQkBFhFiZW5AYWxnc\
                      m91cC5jby51azAeFw05OTEwMTEyMjQ5MzhaFw05OTExMTAyMjQ5\
                      MzhaMFIxCzAJBgNVBAYTAkdCMQ4wDAYDVQQKEwVCZW5DbzERMA8\
                      GA1UEAxMIQmVuQ28gQ0ExIDAeBgkqhkiG9w0BCQEWEWJlbkBhbG\
                      dyb3VwLmNvLnVrMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBg\
                      QCxyAte2HEVouXg1Yu+vDihbnjDRn+6k00Rv6cZqbwA3BQ30mC/\
                      3TFJ09VGXCaM0UKfpnxIpkBYLmOA3FWkKI0RvPU7E1AhKkhC1Ds\
                      PSBFjYHrB15T5lYzgfwKJCIxTDzZDx2iobUgPa0FRNGVUjpQ4/k\
                      MJ2BF4Wh7zY3X08rMzsQIDAQABMA0GCSqGSIb3DQEBBAUAA4GBA\
                      DWJ5pbTcE7iKHWLQTMYiz8i9jGi5+Eo1yr1Bab90tgaGQV0zrRH\
                      jDHgAAy1h8WSXuyQrXfgbx2rnWFPhx9CfmuAXn7sZmQE3mnUqeP\
                      ZL2dW87jdBGqtoUdNcoz5zKBkC943yasNui/O01MiqgadTThTJH\
                      d1Pn17LbJC1ZVRNjR5"
     conditions: app_domain == "IPsec policy" && doi == "ipsec" &&
                 pfs == "yes" && esp_present == "yes" && ah_present == "no" &&
                 (esp_enc_alg == "3des" || esp_enc_alg == "aes") -> "true";
     Signature: "sig-x509-sha1-base64:ql+vrUxv14DcBOQHR2jsbXayq6T\
                 mmtMiUB745a8rjwSrQwh+KIVDlUrghPnqhSIkWSDi9oWWMbfg\
                 mkdudZ0wjgeTLMI2NI4GibMMsToakOKMex/0q4cpdpln3DKcQ\
                 IcjzRv4khDws69FT3QfELjcpShvbLrXmh1Z00OFmxjyqDw="

SEE ALSO

     ipsec(4), keynote(4), keynote(5), isakmpd(8)

BUGS

     A more sane way of expressing IPv6 address ranges is needed.