1# $OpenLDAP$ 2# Copyright 1999-2011 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Using TLS 6 7OpenLDAP clients and servers are capable of using the 8{{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide 9integrity and confidentiality protections and to support 10LDAP authentication using the {{TERM:SASL}} {{TERM:EXTERNAL}} mechanism. 11TLS is defined in {{REF:RFC4346}}. 12 13Note: For generating certifcates, please reference {{URL:http://www.openldap.org/faq/data/cache/185.html}} 14 15H2: TLS Certificates 16 17TLS uses {{TERM:X.509}} certificates to carry client and server 18identities. All servers are required to have valid certificates, 19whereas client certificates are optional. Clients must have a 20valid certificate in order to authenticate via SASL EXTERNAL. 21For more information on creating and managing certificates, 22see the {{PRD:SecureTransport}}, {{PRD:OpenSSL}}, {{PRD:GnuTLS}}, or {{PRD:MozNSS}} documentation, 23depending on which TLS implementation libraries you are using. 24 25H3: Server Certificates 26 27The {{TERM:DN}} of a server certificate must use the {{EX:CN}} 28attribute to name the server, and the {{EX:CN}} must carry the 29server's fully qualified domain name. Additional alias names and 30wildcards may be present in the {{EX:subjectAltName}} certificate 31extension. More details on server certificate names are in 32{{REF:RFC4513}}. 33 34H3: Client Certificates 35 36The DN of a client certificate can be used directly as an 37authentication DN. 38Since X.509 is a part of the {{TERM:X.500}} standard and LDAP 39is also based on X.500, both use the same DN formats and 40generally the DN in a user's X.509 certificate should be 41identical to the DN of their LDAP entry. However, sometimes 42the DNs may not be exactly the same, and so the mapping 43facility described in 44{{SECT:Mapping Authentication Identities}} 45can be applied to these DNs as well. 46 47H2: TLS Configuration 48 49After obtaining the required certificates, a number of options must 50be configured on both the client and the server to enable TLS and 51make use of the certificates. At a minimum, the clients must be 52configured with the all of the 53{{TERM[expand]CA}} (CA) certificates it will trust. The server must 54be configured with the {{TERM:CA}} certificates and also its own 55server certificate and private key. 56 57Typically a single CA will have issued the server certificate 58and all of the trusted client certificates, so the server only 59needs to trust that one signing CA. However, a client may wish 60to connect to a variety of secure servers managed by different 61organizations, with server certificates generated by many 62different CAs. As such, a client is likely to need a list of 63many different trusted CAs in its configuration. 64 65H3: Server Configuration 66 67The configuration directives for slapd belong in the global directives 68section of {{slapd.conf}}(5). 69 70H4: TLSCACertificateFile <filename> 71 72This directive specifies the {{TERM:PEM}}-format file containing 73certificates for the CA's that slapd will trust. The certificate for 74the CA that signed the server certificate must be included among 75these certificates. If the signing CA was not a top-level (root) CA, 76certificates for the entire sequence of CA's from the signing CA to 77the top-level CA should be present. Multiple certificates are simply 78appended to the file; the order is not significant. 79 80When using SecureTransport this directive is not used. Instead use the {{EX:TLSTrustedCerts}} directive. 81 82H4: TLSCACertificatePath <path> 83 84This directive specifies the path of a directory that contains 85individual {{TERM:CA}} certificates in separate files. In addition, 86this directory must be specially managed using the OpenSSL {{c_rehash}} 87utility. When using this feature, the OpenSSL library will attempt to 88locate certificate files based on a hash of their name and serial number. 89The {{c_rehash}} utility is used to generate symbolic links with the 90hashed names that point to the actual certificate files. As such, 91this option can only be used with a filesystem that actually supports 92symbolic links. In general, it is simpler to use the 93{{EX:TLSCACertificateFile}} directive instead. 94 95When using Mozilla NSS, this directive can be used to specify the 96path of the directory containing the NSS certificate and key database 97files. The {{certutil}} command can be used to add a {{TERM:CA}} certificate: 98 99> certutil -d <path> -A -n "name of CA cert" -t CT,, -a -i /path/to/cacertfile.pem 100 101. This command will add a CA certficate stored in the PEM (ASCII) formatted 102. file named /path/to/cacertfile.pem. {{EX:-t CT,,}} means that the certificate is 103. trusted to be a CA issuing certs for use in TLS clients and servers. 104 105When using SecureTransport this directive is not used. Instead use the {{EX:TLSTrustedCerts}} directive. 106 107H4: TLSCertificateFile <filename> 108 109This directive specifies the file that contains the slapd server 110certificate. Certificates are generally public information and 111require no special protection. 112 113When using Mozilla NSS, if using a cert/key database (specified with 114{{EX:TLSCACertificatePath}}), this directive specifies 115the name of the certificate to use: 116 117> TLSCertificateFile Server-Cert 118 119. If using a token other than the internal built in token, specify the 120. token name first, followed by a colon: 121 122> TLSCertificateFile my hardware device:Server-Cert 123 124. Use {{EX:certutil -L}} to list the certificates by name: 125 126> certutil -d /path/to/certdbdir -L 127 128When using SecureTransport this directive is not used. Instead use the {{EX:TLSIdentity}} directive. 129 130H4: TLSCertificateKeyFile <filename> 131 132This directive specifies the file that contains the private key 133that matches the certificate stored in the {{EX:TLSCertificateFile}} 134file. Private keys themselves are sensitive data and are usually 135password encrypted for protection. However, the current implementation 136doesn't support encrypted keys so the key must not be encrypted 137and the file itself must be protected carefully. 138 139When using Mozilla NSS, this directive specifies the name of 140a file that contains the password for the key for the certificate specified with 141{{EX:TLSCertificateFile}}. The modutil command can be used to turn off password 142protection for the cert/key database. For example, if {{EX:TLSCACertificatePath}} 143specifes /etc/openldap/certdb as the location of the cert/key database, use 144modutil to change the password to the empty string: 145 146> modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB' 147 148. You must have the old password, if any. Ignore the WARNING about the running 149. browser. Press 'Enter' for the new password. 150 151When using SecureTransport this directive is not used. Instead use the {{EX:TLSIdentity}} directive. 152 153H4: TLSCipherSuite <cipher-suite-spec> 154 155This directive configures what ciphers will be accepted and the 156preference order. {{EX:<cipher-suite-spec>}} should be a cipher 157specification for OpenSSL. You can use the command 158 159> openssl ciphers -v ALL 160 161to obtain a verbose list of available cipher specifications. 162 163Besides the individual cipher names, the specifiers {{EX:HIGH}}, 164{{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}} 165may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}}, 166and {{EX:SSLv2}}. 167 168To obtain the list of ciphers in GnuTLS use: 169 170> gnutls-cli -l 171 172When using Mozilla NSS, the OpenSSL cipher suite specifications are used and 173translated into the format used internally by Mozilla NSS. There isn't an easy 174way to list the cipher suites from the command line. The authoritative list 175is in the source code for Mozilla NSS in the file sslinfo.c in the structure 176 177> static const SSLCipherSuiteInfo suiteInfo[] 178 179When using SecureTransport this directive uses cipher names known to the Security framework unless you prefix the value with {{EX:OpenSSL:}} in which case it uses cipher names known to OpenSSL. 180 181H4: TLSRandFile <filename> 182 183This directive specifies the file to obtain random bits from when 184{{FILE:/dev/urandom}} is not available. If the system provides 185{{FILE:/dev/urandom}} then this option is not needed, otherwise a 186source of random data must be configured. Some systems (e.g. Linux) 187provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris) 188require the installation of a patch to provide it, and others may 189not support it at all. In the latter case, EGD or PRNGD should be 190installed, and this directive should specify the name of the EGD/PRNGD 191socket. The environment variable {{EX:RANDFILE}} can also be used 192to specify the filename. Also, in the absence of these options, the 193{{EX:.rnd}} file in the slapd user's home directory may be used if 194it exists. To use the {{EX:.rnd}} file, just create the file and 195copy a few hundred bytes of arbitrary data into the file. The file 196is only used to provide a seed for the pseudo-random number generator, 197and it doesn't need very much data to work. 198 199This directive is ignored with SecureTransport, GnuTLS and Mozilla NSS. 200 201H4: TLSEphemeralDHParamFile <filename> 202 203This directive specifies the file that contains parameters for 204Diffie-Hellman ephemeral key exchange. This is required in order 205to use a DSA certificate on the server side (i.e. 206{{EX:TLSCertificateKeyFile}} points to a DSA key). Multiple sets 207of parameters can be included in the file; all of them will be 208processed. Parameters can be generated using the following command 209 210> openssl dhparam [-dsaparam] -out <filename> <numbits> 211 212This directive is ignored with GnuTLS and Mozilla NSS. 213 214H4: TLSVerifyClient { never | allow | try | demand } 215 216This directive specifies what checks to perform on client certificates 217in an incoming TLS session, if any. This option is set to {{EX:never}} 218by default, in which case the server never asks the client for a 219certificate. With a setting of {{EX:allow}} the server will ask 220for a client certificate; if none is provided the session proceeds 221normally. If a certificate is provided but the server is unable to 222verify it, the certificate is ignored and the session proceeds 223normally, as if no certificate had been provided. With a setting of 224{{EX:try}} the certificate is requested, and if none is provided, 225the session proceeds normally. If a certificate is provided and it 226cannot be verified, the session is immediately terminated. With a 227setting of {{EX:demand}} the certificate is requested and a valid 228certificate must be provided, otherwise the session is immediately 229terminated. 230 231Note: The server must request a client certificate in order to 232use the SASL EXTERNAL authentication mechanism with a TLS session. 233As such, a non-default {{EX:TLSVerifyClient}} setting must be configured 234before SASL EXTERNAL authentication may be attempted, and the 235SASL EXTERNAL mechanism will only be offered to the client if a valid 236client certificate was received. 237 238H4: TLSIdentity <name> 239 240When using SecureTransport this directive replaces the {{EX:TLSCertificateFile}} and {{EX:TLSCertificateKeyFile}} directives. It names an identity in 241the system keychain. An identity is a certificate paired with a private key. Beware application-restricted private keys; make sure the one you use 242is available to all applications. 243 244This directive is ignored with OpenSSL, GnuTLS and Mozilla NSS. 245 246H4: TLSTrustedCerts <list> 247 248When using SecureTransport this directive replaces the {{EX:TLSCACertificateFile}} and {{EX:TLSCACertificatePath}} directives. It lists names of 249certificates in the system keychain, separated by '|' characters. For example: {{EX:TLSTrustedCerts Frobozz, Inc.|Widgets R Us|www.example.com}} 250 251This directive is ignored with OpenSSL, GnuTLS and Mozilla NSS. 252 253H3: Client Configuration 254 255Most of the client configuration directives parallel the server 256directives. The names of the directives are different, and they go 257into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their 258functionality is mostly the same. Also, while most of these options may 259be configured on a system-wide basis, they may all be overridden by 260individual users in their {{.ldaprc}} files. 261 262The LDAP Start TLS operation is used in LDAP to initiate TLS 263negotiation. All OpenLDAP command line tools support a {{EX:-Z}} 264and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to 265be issued. The latter flag indicates that the tool is to cease 266processing if TLS cannot be started while the former allows the 267command to continue. 268 269In LDAPv2 environments, TLS is normally started using the LDAP 270Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI 271scheme ({{EX:ldap://}}). OpenLDAP command line tools allow either 272scheme to used with the {{EX:-H}} flag and with the {{EX:URI}} 273{{ldap.conf}}(5) option. 274 275 276H4: TLS_CACERT <filename> 277 278This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As 279noted in the {{SECT:TLS Configuration}} section, a client typically 280may need to know about more CAs than a server, but otherwise the 281same considerations apply. 282 283When using SecureTransport this directive is not used. Instead use the {{EX:TLS_TRUSTED_CERTS}} directive. 284 285H4: TLS_CACERTDIR <path> 286 287This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The 288specified directory must be managed with the OpenSSL {{c_rehash}} 289utility as well. If using Mozilla NSS, <path> may contain a cert/key database. 290 291When using SecureTransport this directive is not used. Instead use the {{EX:TLS_TRUSTED_CERTS}} directive. 292 293H4: TLS_CERT <filename> 294 295This directive specifies the file that contains the client certificate. 296This is a user-only directive and can only be specified in a user's 297{{.ldaprc}} file. 298 299When using Mozilla NSS, if using a cert/key database (specified with 300{{EX:TLS_CACERTDIR}}), this directive specifies 301the name of the certificate to use: 302 303> TLS_CERT Certificate for Sam Carter 304 305. If using a token other than the internal built in token, specify the 306. token name first, followed by a colon: 307 308> TLS_CERT my hardware device:Certificate for Sam Carter 309 310. Use {{EX:certutil -L}} to list the certificates by name: 311 312> certutil -d /path/to/certdbdir -L 313 314When using SecureTransport this directive is not used. Instead use the {{EX:TLS_IDENTITY}} directive. 315 316H4: TLS_KEY <filename> 317 318This directive specifies the file that contains the private key 319that matches the certificate stored in the {{EX:TLS_CERT}} 320file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}} 321apply here. This is also a user-only directive. 322 323When using SecureTransport this directive is not used. Instead use the {{EX:TLS_IDENTITY}} directive. 324 325H4: TLS_RANDFILE <filename> 326 327This directive is the same as the server's {{EX:TLSRandFile}} 328option. 329 330H4: TLS_REQCERT { never | allow | try | demand } 331 332This directive is equivalent to the server's {{EX:TLSVerifyClient}} 333option. However, for clients the default value is {{EX:demand}} 334and there generally is no good reason to change this setting. 335 336H4: TLS_IDENTITY <name> 337 338This directive is equivalent to the server's {{EX:TLSIdentity}} option. When using SecureTransport it replaces the {{EX:TLS_CERT}} and {{EX:TLS_KEY}} directives. 339 340H4: TLS_TRUSTED_CERTS <list> 341 342This directive is equivalent to the server's {{EX:TLS_TRUSTED_CERTS}} option. When using SecureTransport it replaces the {{EX:TLS_CACERT}} and {{EX:TLS_CACERTDIR}} directives. 343 344