swanctl: Document identity type prefixes
[strongswan.git] / src / swanctl / swanctl.opt
index 40265d0..5783555 100644 (file)
@@ -161,13 +161,13 @@ connections.<conn>.send_certreq = yes
        of the initial IKE packets.
 
 connections.<conn>.send_cert = ifasked
-       Send certificate payloads (_yes_, _no_ or _ifasked_).
+       Send certificate payloads (_always_, _never_ or _ifasked_).
 
        Send certificate payloads when using certificate authentication. With the
        default of _ifasked_ the daemon sends certificate payloads only if
-       certificate requests have been received. _no_ disables sending of
-       certificate payloads, _yes_ always sends certificate payloads whenever
-       certificate authentication is used.
+       certificate requests have been received. _never_ disables sending of
+       certificate payloads altogether, _always_ causes certificate payloads to be
+       sent unconditionally whenever certificate authentication is used.
 
 connections.<conn>.keyingtries = 1
        Number of retransmission sequences to perform during initial connect.
@@ -194,6 +194,11 @@ connections.<conn>.unique = no
        EAP or XAuth authentication is involved, the EAP-Identity or XAuth username
        is used to enforce the uniqueness policy instead.
 
+       On initiators this setting specifies whether an INITIAL_CONTACT notify is
+       sent during IKE_AUTH if no existing connection is found with the remote
+       peer (determined by the identities of the first authentication round).
+       Only if set to _keep_ or _replace_ will the client send a notify.
+
 connections.<conn>.reauth_time = 0s
        Time to schedule IKE reauthentication.
 
@@ -298,6 +303,22 @@ connections.<conn>.local<suffix>.id =
        authentication, the IKE identity must be contained in the certificate,
        either as subject or as subjectAltName.
 
+       The identity can be an IP address, a fully-qualified domain name, an email
+       address or a Distinguished Name for which the ID type is determined
+       automatically and the string is converted to the appropriate encoding. To
+       enforce a specific identity type, a prefix may be used, followed by a colon
+       (:). If the number sign (#) follows the colon, the remaining data is
+       interpreted as hex encoding, otherwise the string is used as-is as the
+       identification data. Note that this implies that no conversion is performed
+       for non-string identities. For example, _ipv4:10.0.0.1_ does not create a
+       valid ID_IPV4_ADDR IKE identity, as it does not get converted to binary
+       0x0a000001. Instead, one could use _ipv4:#0a000001_ to get a valid identity,
+       but just using the implicit type with automatic conversion is usually
+       simpler. The same applies to the ASN1 encoded types. The following prefixes
+       are known: _ipv4_, _ipv6_, _rfc822_, _email_, _userfqdn_, _fqdn_, _dns_,
+       _asn1dn_, _asn1gn_ and _keyid_. Custom type prefixes may be specified by
+       surrounding the numerical type value by curly brackets.
+
 connections.<conn>.local<suffix>.eap_id = id
        Client EAP-Identity to use in EAP-Identity exchange and the EAP method.
 
@@ -309,7 +330,7 @@ connections.<conn>.local<suffix>.aaa_id = remote-id
        This identity may differ from the IKE identity, especially when EAP
        authentication is delegated from the IKE responder to an AAA backend.
 
-       For EAP-(T)TLS, this defines the identity for wich the server must provide
+       For EAP-(T)TLS, this defines the identity for which the server must provide
        a certificate in the TLS exchange.
 
 connections.<conn>.local<suffix>.xauth_id = id
@@ -330,9 +351,8 @@ connections.<conn>.remote<suffix> {}
 connections.<conn>.remote<suffix>.id = %any
        IKE identity to expect for authentication round.
 
-       IKE identity to expect for authentication round. When using certificate
-       authentication, the IKE identity must be contained in the certificate,
-       either as subject or as subjectAltName.
+       IKE identity to expect for authentication round. Refer to the _local_ _id_
+       section for details.
 
 connections.<conn>.remote<suffix>.groups =
        Authorization group memberships to require.
@@ -349,7 +369,7 @@ connections.<conn>.remote<suffix>.certs =
        The certificates may use a relative path from the **swanctl** _x509_
        directory, or an absolute path.
 
-connections.<conn>.remote<suffix>.cacert =
+connections.<conn>.remote<suffix>.cacerts =
        Comma separated list of CA certificates to accept for authentication.
 
        Comma separated list of CA certificates to accept for authentication.
@@ -664,11 +684,17 @@ connections.<conn>.children.<child>.close_action = none
        failures. Use trap policies to reliably re-create failed CHILD_SAs.
 
 secrets { # }
-       Section defining secrets for IKE and EAP/XAuth authentication.
+       Section defining secrets for IKE/EAP/XAuth authentication and private
+       key decryption.
 
-       Section defining secrets for IKE and EAP/XAuth authentication. The
-       **secrets** section takes sub-sections having a specific prefix which
-       defines the secret type.
+       Section defining secrets for IKE/EAP/XAuth authentication and private key
+       decryption. The **secrets** section takes sub-sections having a specific
+       prefix which defines the secret type.
+
+       It is not recommended to define any private key decryption passphrases,
+       as then there is no real security benefit in having encrypted keys. Either
+       store the key unencrypted, or enter the keys manually when loading
+       credentials.
 
 secrets.eap<suffix> { # }
        EAP secret section for a specific secret.
@@ -718,6 +744,33 @@ secrets.ike<suffix>.id<suffix> =
        may be specified, each having an _id_ prefix, if a secret is shared between
        multiple peers.
 
+secrets.rsa<suffix> { # }
+       Private key decryption passphrase for a key in the _rsa_ folder.
+
+secrets.rsa<suffix>.file =
+       File name in the _rsa_ folder for which this passphrase should be used.
+
+secrets.rsa<suffix>.secret
+       Value of decryption passphrase for RSA key.
+
+secrets.ecdsa<suffix> { # }
+       Private key decryption passphrase for a key in the _ecdsa_ folder.
+
+secrets.ecdsa<suffix>.file =
+       File name in the _ecdsa_ folder for which this passphrase should be used.
+
+secrets.ecdsa<suffix>.secret
+       Value of decryption passphrase for ECDSA key.
+
+secrets.pkcs8<suffix> { # }
+       Private key decryption passphrase for a key in the _pkcs8_ folder.
+
+secrets.pkcs8<suffix>.file =
+       File name in the _pkcs8_ folder for which this passphrase should be used.
+
+secrets.pkcs8<suffix>.secret
+       Value of decryption passphrase for PKCS#8 key.
+
 pools { # }
        Section defining named pools.