Annotation of embedaddon/strongswan/man/ipsec.secrets.5.in, revision 1.1
1.1 ! misho 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>