Return to ipsec.secrets.5.in CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / man

Strongswan

    1: .TH IPSEC.SECRETS 5 "2011-12-14" "@PACKAGE_VERSION@" "strongSwan"
    2: .SH NAME
    3: ipsec.secrets \- secrets for IKE/IPsec authentication
    4: .SH DESCRIPTION
    5: The file \fIipsec.secrets\fP holds a table of secrets.
    6: These secrets are used by the strongSwan Internet Key Exchange (IKE) daemons
    7: pluto (IKEv1) and charon (IKEv2) to authenticate other hosts.
    8: .LP
    9: It is vital that these secrets be protected.  The file should be owned
   10: by the super-user,
   11: and its permissions should be set to block all access by others.
   12: .LP
   13: The file is a sequence of entries and include directives.
   14: Here is an example.
   15: .LP
   16: .RS
   17: .nf
   18: # /etc/ipsec.secrets - strongSwan IPsec secrets file
   19: 192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL"
   20: 
   21: : RSA moonKey.pem
   22: 
   23: alice@strongswan.org : EAP "x3.dEhgN"
   24: 
   25: carol : XAUTH "4iChxLT3"
   26: 
   27: dave  : XAUTH "ryftzG4A"
   28: 
   29: # get secrets from other files
   30: include ipsec.*.secrets
   31: .fi
   32: .RE
   33: .LP
   34: Each entry in the file is a list of optional ID selectors, followed by a secret.
   35: The two parts are separated by a colon (\fB:\fP) that is surrounded
   36: by whitespace. If no ID selectors are specified the line must start with a
   37: colon.
   38: .LP
   39: A selector is an IP address, a Fully Qualified Domain Name, user@FQDN,
   40: \fB%any\fP or \fB%any6\fP (other kinds may come).
   41: .LP
   42: Matching IDs with selectors is fairly straightforward: they have to be
   43: equal.  In the case of a ``Road Warrior'' connection, if an equal
   44: match is not found for the Peer's ID, and it is in the form of an IP
   45: address, a selector of \fB%any\fP will match the peer's IP address if IPV4
   46: and \fB%any6\fP will match a the peer's IP address if IPV6.
   47: Currently, the obsolete notation \fB0.0.0.0\fP may be used in place of
   48: \fB%any\fP.
   49: .LP
   50: In IKEv1 an additional complexity
   51: arises in the case of authentication by preshared secret: the
   52: responder will need to look up the secret before the Peer's ID payload has
   53: been decoded, so the ID used will be the IP address.
   54: .LP
   55: To authenticate a connection between two hosts, the entry that most
   56: specifically matches the host and peer IDs is used.  An entry with no
   57: selectors will match any host and peer.  More specifically, an entry with one
   58: selector will match a host and peer if the selector matches the host's ID (the
   59: peer isn't considered).  Still more specifically, an entry with multiple
   60: selectors will match a host and peer if the host ID and peer ID each match one
   61: of the selectors.  If the key is for an asymmetric authentication technique
   62: (i.e. a public key system such as RSA), an entry with multiple selectors will
   63: match a host and peer even if only the host ID matches a selector (it is
   64: presumed that the selectors are all identities of the host).
   65: It is acceptable for two entries to be the best match as
   66: long as they agree about the secret or private key.
   67: .LP
   68: Authentication by preshared secret requires that both systems find the
   69: identical secret (the secret is not actually transmitted by the IKE
   70: protocol).  If both the host and peer appear in the selector list, the
   71: same entry will be suitable for both systems so verbatim copying
   72: between systems can be used.  This naturally extends to larger groups
   73: sharing the same secret.  Thus multiple-selector entries are best for PSK
   74: authentication.
   75: .LP
   76: Authentication by public key systems such as RSA requires that each host
   77: have its own private key.  A host could reasonably use a different private keys
   78: for different interfaces and for different peers.  But it would not
   79: be normal to share entries between systems.  Thus thus no-selector and
   80: one-selector forms of entry often make sense for public key authentication.
   81: .LP
   82: The key part of an entry must start with a token indicating the kind of
   83: key.  The following types of secrets are currently supported:
   84: .TP
   85: .B PSK
   86: defines a pre-shared key
   87: .TP
   88: .B RSA
   89: defines an RSA private key
   90: .TP
   91: .B ECDSA
   92: defines an ECDSA private key
   93: .TP
   94: .B P12
   95: defines a PKCS#12 container
   96: .TP
   97: .B EAP
   98: defines EAP credentials
   99: .TP
  100: .B NTLM
  101: defines NTLM credentials
  102: .TP
  103: .B XAUTH
  104: defines XAUTH credentials
  105: .TP
  106: .B PIN
  107: defines a smartcard PIN
  108: .LP
  109: Details on each type of secret are given below.
  110: .LP
  111: Whitespace at the end of a line is ignored. At the start of a line or
  112: after whitespace, \fB#\fP and the following text up to the end of the
  113: line is treated as a comment.
  114: .LP
  115: An include directive causes the contents of the named file to be processed
  116: before continuing with the current file.  The filename is subject to
  117: ``globbing'' as in \fIsh\fP(1), so every file with a matching name
  118: is processed.  Includes may be nested to a modest
  119: depth (10, currently).  If the filename doesn't start with a \fB/\fP, the
  120: directory containing the current file is prepended to the name.  The
  121: include directive is a line that starts with the word \fBinclude\fP,
  122: followed by whitespace, followed by the filename (which must not contain
  123: whitespace).
  124: .SS TYPES OF SECRETS
  125: .TP
  126: .B [ <selectors> ] : PSK <secret>
  127: A preshared \fIsecret\fP is most conveniently represented as a sequence of
  128: characters, which is delimited by double-quote characters (\fB"\fP).
  129: The sequence cannot contain newline or double-quote characters.
  130: .br
  131: Alternatively, preshared secrets can be represented as hexadecimal or Base64
  132: encoded binary values. A character sequence beginning with
  133: .B 0x
  134: is interpreted as sequence of hexadecimal digits.
  135: Similarly, a character sequence beginning with
  136: .B 0s
  137: is interpreted as Base64 encoded binary data.
  138: .TP
  139: .B : RSA <private key file> [ <passphrase> | %prompt ]
  140: .TQ
  141: .B : ECDSA <private key file> [ <passphrase> | %prompt ]
  142: For the private key file both absolute paths or paths relative to
  143: \fI/etc/ipsec.d/private\fP are accepted. If the private key file is
  144: encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
  145: .B %prompt
  146: can be used which then causes the daemon to ask the user for the password
  147: whenever it is required to decrypt the key.
  148: .TP
  149: .B : P12 <PKCS#12 file> [ <passphrase> | %prompt ]
  150: For the PKCS#12 file both absolute paths or paths relative to
  151: \fI/etc/ipsec.d/private\fP are accepted. If the container is
  152: encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
  153: .B %prompt
  154: can be used which then causes the daemon to ask the user for the password
  155: whenever it is required to decrypt the container. Private keys, client and CA
  156: certificates are extracted from the container. To use such a client certificate
  157: in a connection set leftid to one of the subjects of the certificate.
  158: .TP
  159: .B <user id> : EAP <secret>
  160: The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets.
  161: .br
  162: \fBEAP\fP secrets are IKEv2 only.
  163: .TP
  164: .B <user id> : NTLM <secret>
  165: The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets, but the
  166: secret is stored as NTLM hash, which is MD4(UTF-16LE(secret)), instead of as
  167: cleartext.
  168: .br
  169: \fBNTLM\fP secrets can only be used with the \fBeap-mschapv2\fP plugin.
  170: .TP
  171: .B [ <servername> ] <username> : XAUTH <password>
  172: The format of \fIpassword\fP is the same as that of \fBPSK\fP secrets.
  173: \fBXAUTH\fP secrets are IKEv1 only.
  174: .TP
  175: .B : PIN %smartcard[<slot nr>[@<module>]]:<keyid> <pin code> | %prompt
  176: The smartcard selector always requires a keyid to uniquely select the correct
  177: key. The slot number defines the slot on the token, the module name refers to
  178: the module name defined in strongswan.conf(5).
  179: Instead of specifying the pin code statically,
  180: .B %prompt
  181: can be specified, which causes the daemon to ask the user for the pin code.
  182: .LP
  183: 
  184: .SH FILES
  185: /etc/ipsec.secrets
  186: .SH SEE ALSO
  187: ipsec.conf(5), strongswan.conf(5), ipsec(8)
  188: .br
  189: .SH HISTORY
  190: Originally written for the FreeS/WAN project by D. Hugh Redelmeier.
  191: Updated and extended for the strongSwan project <http://www.strongswan.org> by
  192: Tobias Brunner and Andreas Steffen.
  193: .SH BUGS
  194: If an ID is \fB0.0.0.0\fP, it will match \fB%any\fP;
  195: if it is \fB0::0\fP, it will match \fB%any6\fP.