git.sur5r.net Git - openldap/blob - doc/guide/admin/tls.sdf

   1 # Copyright 1999-2006 The OpenLDAP Foundation, All Rights Reserved.
   2 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   3
   4 H1: Using TLS
   5
   6 OpenLDAP clients and servers are capable of using the
   7 {{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide
   8 integrity and confidentiality protections and to support
   9 LDAP authentication using the {{TERM:SASL}} EXTERNAL mechanism.
  10
  11 H2: TLS Certificates
  12
  13 TLS uses {{TERM:X.509}} certificates to carry client and server
  14 identities. All servers are required to have valid certificates,
  15 whereas client certificates are optional. Clients must have a
  16 valid certificate in order to authenticate via SASL EXTERNAL.
  17 For more information on creating and managing certificates,
  18 see the {{PRD:OpenSSL}} documentation.
  19
  20 H3: Server Certificates
  21
  22 The DN of a server certificate must use the CN attribute
  23 to name the server, and the {{EX:CN}} must carry the server's
  24 fully qualified domain name. Additional alias names and wildcards
  25 may be present in the {{EX:subjectAltName}} certificate extension.
  26 More details on server certificate names are in {{REF:RFC2830}}.
  27
  28 H3: Client Certificates
  29
  30 The DN of a client certificate can be used directly as an
  31 authentication DN.
  32 Since X.509 is a part of the {{TERM:X.500}} standard and LDAP
  33 is also based on X.500, both use the same DN formats and
  34 generally the DN in a user's X.509 certificate should be
  35 identical to the DN of their LDAP entry. However, sometimes
  36 the DNs may not be exactly the same, and so the mapping
  37 facility described in
  38 {{SECT:Mapping Authentication identities to LDAP entries}}
  39 can be applied to these DNs as well.
  40
  41 H2: TLS Configuration
  42
  43 After obtaining the required certificates, a
  44 number of options must be configured on both the client
  45 and the server to enable TLS and make use of the certificates.
  46 At a minimum, the clients must be configured with the filename
  47 containing all of the {{TERM[expand]CA}} (CA) certificates it
  48 will trust. The server must be configured with the {{TERM:CA}}
  49 certificates and also its own server certificate and private key.
  50
  51 Typically a single CA will have issued the server certificate
  52 and all of the trusted client certificates, so the server only
  53 needs to trust that one signing CA. However, a client may wish
  54 to connect to a variety of secure servers managed by different
  55 organizations, with server certificates generated by many
  56 different CAs. As such, a client is likely to need a list of
  57 many different trusted CAs in its configuration.
  58
  59 H3: Server Configuration
  60
  61 The configuration directives for slapd belong in the global directives
  62 section of {{slapd.conf}}(5).
  63
  64 H4: TLSCACertificateFile <filename>
  65
  66 This directive specifies the {{TERM:PEM}}-format file containing
  67 certificates for the CA's that slapd will trust. The certificate for
  68 the CA that signed the server certificate must be included among
  69 these certificates. If the signing CA was not a top-level (root) CA,
  70 certificates for the entire sequence of CA's from the signing CA to
  71 the top-level CA should be present. Multiple certificates are simply
  72 appended to the file; the order is not significant.
  73
  74 H4: TLSCACertificatePath <path>
  75
  76 This directive specifies the path of a directory that contains
  77 individual {{TERM:CA}} certificates in separate files.  In addition,
  78 this directory must be specially managed using the OpenSSL {{c_rehash}}
  79 utility. When using this feature, the OpenSSL library will attempt to
  80 locate certificate files based on a hash of their name and serial number.
  81 The {{c_rehash}} utility is used to generate symbolic links with the
  82 hashed names that point to the actual certificate files. As such,
  83 this option can only be used with a filesystem that actually supports
  84 symbolic links. In general, it is simpler to use the
  85 {{EX:TLSCACertificateFile}} directive instead.
  86
  87 H4: TLSCertificateFile <filename>
  88
  89 This directive specifies the file that contains the slapd server
  90 certificate. Certificates are generally public information and
  91 require no special protection.
  92
  93 H4: TLSCertificateKeyFile <filename>
  94
  95 This directive specifies the file that contains the private key
  96 that matches the certificate stored in the {{EX:TLSCertificateFile}}
  97 file. Private keys themselves are sensitive data and are usually
  98 password encrypted for protection. However, the current implementation
  99 doesn't support encrypted keys so the key must not be encrypted
 100 and the file itself must be protected carefully.
 101
 102 H4: TLSCipherSuite <cipher-suite-spec>
 103
 104 This directive configures what ciphers will be accepted and the
 105 preference order. {{EX:<cipher-suite-spec>}} should be a cipher
 106 specification for OpenSSL. You can use the command
 107
 108 >       openssl ciphers -v ALL
 109
 110 to obtain a verbose list of available cipher specifications.
 111 Besides the individual cipher names, the specifiers {{EX:HIGH}},
 112 {{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}}
 113 may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}},
 114 and {{EX:SSLv2}}.
 115
 116 H4: TLSRandFile <filename>
 117
 118 This directive specifies the file to obtain random bits from when
 119 {{EX:/dev/urandom}} is not available. If the
 120 system provides {{EX:/dev/urandom}} then this option is not needed,
 121 otherwise a source of random data must be configured.
 122 Some systems (e.g. Linux)
 123 provide {{EX:/dev/urandom}} by default, while others (e.g. Solaris)
 124 require the installation of a patch to provide it, and others may
 125 not support it at all. In the latter case, EGD or PRNGD should be
 126 installed, and this directive should specify the name of the EGD/PRNGD
 127 socket. The environment variable {{EX:RANDFILE}} can also be used to specify
 128 the filename. Also, in the absence of these options, the {{EX:.rnd}}
 129 file in the slapd user's home directory may be used if it exists. To
 130 use the {{EX:.rnd}} file, just create the file and copy a few hundred
 131 bytes of arbitrary data into the file. The file is only used to
 132 provide a seed for the pseudo-random number generator, and it doesn't
 133 need very much data to work.
 134
 135 H4: TLSEphemeralDHParamFile <filename>
 136
 137 This directive specifies the file that contains parameters for Diffie-Hellman
 138 ephemeral key exchange.  This is required in order to use a DSA certificate on
 139 the server side (i.e. {{EX:TLSCertificateKeyFile}} points to a DSA key).
 140 Multiple sets of parameters can be included in the file; all of them will
 141 be processed.  Parameters can be generated using the following command
 142
 143 >       openssl dhparam [-dsaparam] -out <filename> <numbits>
 144
 145 H4: TLSVerifyClient { never | allow | try | demand }
 146
 147 This directive specifies what checks to perform on client certificates
 148 in an incoming TLS session, if any. This option is set to {{EX:never}}
 149 by default, in which case the server never asks the client for a
 150 certificate. With a setting of {{EX:allow}} the server will ask
 151 for a client certificate; if none is provided the session proceeds
 152 normally. If a certificate is provided but the server is unable to
 153 verify it, the certificate is ignored and the session proceeds
 154 normally, as if no certificate had been provided. With a setting of
 155 {{EX:try}} the certificate is requested, and if none is provided,
 156 the session proceeds normally. If a certificate is provided and it
 157 cannot be verified, the session is immediately terminated. With a
 158 setting of {{EX:demand}} the certificate is requested and a valid
 159 certificate must be provided, otherwise the session is immediately
 160 terminated.
 161
 162 Note: The server must request a client certificate in order to
 163 use the SASL EXTERNAL authentication mechanism with a TLS session.
 164 As such, a non-default {{EX:TLSVerifyClient}} setting must be configured
 165 before SASL EXTERNAL authentication may be attempted, and the
 166 SASL EXTERNAL mechanism will only be offered to the client if a valid
 167 client certificate was received.
 168
 169 H3: Client Configuration
 170
 171 Most of the client configuration directives parallel the server
 172 directives. The names of the directives are different, and they go
 173 into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their
 174 functionality is mostly the same. Also, while most of these options may
 175 be configured on a system-wide basis, they may all be overridden by
 176 individual users in their {{.ldaprc}} files.
 177
 178 The LDAP Start TLS operation is used in LDAP to initiate TLS
 179 negotatation.  All OpenLDAP command line tools support a {{E:-Z}}
 180 and {{E:-ZZ}} flag to indicate whether a Start TLS operation is to
 181 be issued.  The latter flag indicates that the tool is to cease
 182 processing if TLS cannot be started while the former allows the
 183 command to continue.
 184
 185 In LDAPv2 environments, TLS is normally started using the LDAP
 186 Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI
 187 scheme ({{EX:ldap://}}).  OpenLDAP command line tools allow either
 188 scheme to used with the {{EX:-U}} flag and with the {{EX:URI}}
 189 {{ldap.conf}}(5) option.
 190
 191
 192 H4: TLS_CACERT <filename>
 193
 194 This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As
 195 noted in the {{SECT:TLS Configuration}} section, a client typically
 196 may need to know about more CAs than a server, but otherwise the
 197 same considerations apply.
 198
 199 H4: TLS_CACERTDIR <path>
 200
 201 This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
 202 specified directory must be managed with the OpenSSL {{c_rehash}}
 203 utility as well.
 204
 205 H4: TLS_CERT <filename>
 206
 207 This directive specifies the file that contains the client certificate.
 208 This is a user-only directive and can only be specified in a user's
 209 {{.ldaprc}} file.
 210
 211 H4: TLS_KEY <filename>
 212
 213 This directive specifies the file that contains the private key
 214 that matches the certificate stored in the {{EX:TLS_CERT}}
 215 file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}}
 216 apply here. This is also a user-only directive.
 217
 218 H4: TLS_RANDFILE <filename>
 219
 220 This directive is the same as the server's {{EX:TLSRandFile}}
 221 option.
 222
 223 H4: TLS_REQCERT { never | allow | try | demand }
 224
 225 This directive is equivalent to the server's {{EX:TLSVerifyClient}}
 226 option. However, for clients the default value is {{EX:demand}}
 227 and there generally is no good reason to change this setting.
 228