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: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 name of the file containing 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 80H4: TLSCACertificatePath <path> 81 82This directive specifies the path of a directory that contains 83individual {{TERM:CA}} certificates in separate files. In addition, 84this directory must be specially managed using the OpenSSL {{c_rehash}} 85utility. When using this feature, the OpenSSL library will attempt to 86locate certificate files based on a hash of their name and serial number. 87The {{c_rehash}} utility is used to generate symbolic links with the 88hashed names that point to the actual certificate files. As such, 89this option can only be used with a filesystem that actually supports 90symbolic links. In general, it is simpler to use the 91{{EX:TLSCACertificateFile}} directive instead. 92 93When using Mozilla NSS, this directive can be used to specify the 94path of the directory containing the NSS certificate and key database 95files. The {{certutil}} command can be used to add a {{TERM:CA}} certificate: 96 97> certutil -d <path> -A -n "name of CA cert" -t CT,, -a -i /path/to/cacertfile.pem 98 99. This command will add a CA certficate stored in the PEM (ASCII) formatted 100. file named /path/to/cacertfile.pem. {{EX:-t CT,,}} means that the certificate is 101. trusted to be a CA issuing certs for use in TLS clients and servers. 102 103H4: TLSCertificateFile <filename> 104 105This directive specifies the file that contains the slapd server 106certificate. Certificates are generally public information and 107require no special protection. 108 109When using Mozilla NSS, if using a cert/key database (specified with 110{{EX:TLSCACertificatePath}}), this directive specifies 111the name of the certificate to use: 112 113> TLSCertificateFile Server-Cert 114 115. If using a token other than the internal built in token, specify the 116. token name first, followed by a colon: 117 118> TLSCertificateFile my hardware device:Server-Cert 119 120. Use {{EX:certutil -L}} to list the certificates by name: 121 122> certutil -d /path/to/certdbdir -L 123 124H4: TLSCertificateKeyFile <filename> 125 126This directive specifies the file that contains the private key 127that matches the certificate stored in the {{EX:TLSCertificateFile}} 128file. Private keys themselves are sensitive data and are usually 129password encrypted for protection. However, the current implementation 130doesn't support encrypted keys so the key must not be encrypted 131and the file itself must be protected carefully. 132 133When using Mozilla NSS, this directive specifies the name of 134a file that contains the password for the key for the certificate specified with 135{{EX:TLSCertificateFile}}. The modutil command can be used to turn off password 136protection for the cert/key database. For example, if {{EX:TLSCACertificatePath}} 137specifes /etc/openldap/certdb as the location of the cert/key database, use 138modutil to change the password to the empty string: 139 140> modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB' 141 142. You must have the old password, if any. Ignore the WARNING about the running 143. browser. Press 'Enter' for the new password. 144 145H4: TLSCipherSuite <cipher-suite-spec> 146 147This directive configures what ciphers will be accepted and the 148preference order. {{EX:<cipher-suite-spec>}} should be a cipher 149specification for OpenSSL. You can use the command 150 151> openssl ciphers -v ALL 152 153to obtain a verbose list of available cipher specifications. 154 155Besides the individual cipher names, the specifiers {{EX:HIGH}}, 156{{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}} 157may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}}, 158and {{EX:SSLv2}}. 159 160To obtain the list of ciphers in GnuTLS use: 161 162> gnutls-cli -l 163 164When using Mozilla NSS, the OpenSSL cipher suite specifications are used and 165translated into the format used internally by Mozilla NSS. There isn't an easy 166way to list the cipher suites from the command line. The authoritative list 167is in the source code for Mozilla NSS in the file sslinfo.c in the structure 168 169> static const SSLCipherSuiteInfo suiteInfo[] 170 171H4: TLSRandFile <filename> 172 173This directive specifies the file to obtain random bits from when 174{{FILE:/dev/urandom}} is not available. If the system provides 175{{FILE:/dev/urandom}} then this option is not needed, otherwise a 176source of random data must be configured. Some systems (e.g. Linux) 177provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris) 178require the installation of a patch to provide it, and others may 179not support it at all. In the latter case, EGD or PRNGD should be 180installed, and this directive should specify the name of the EGD/PRNGD 181socket. The environment variable {{EX:RANDFILE}} can also be used 182to specify the filename. Also, in the absence of these options, the 183{{EX:.rnd}} file in the slapd user's home directory may be used if 184it exists. To use the {{EX:.rnd}} file, just create the file and 185copy a few hundred bytes of arbitrary data into the file. The file 186is only used to provide a seed for the pseudo-random number generator, 187and it doesn't need very much data to work. 188 189This directive is ignored with GnuTLS and Mozilla NSS. 190 191H4: TLSEphemeralDHParamFile <filename> 192 193This directive specifies the file that contains parameters for 194Diffie-Hellman ephemeral key exchange. This is required in order 195to use a DSA certificate on the server side (i.e. 196{{EX:TLSCertificateKeyFile}} points to a DSA key). Multiple sets 197of parameters can be included in the file; all of them will be 198processed. Parameters can be generated using the following command 199 200> openssl dhparam [-dsaparam] -out <filename> <numbits> 201 202This directive is ignored with GnuTLS and Mozilla NSS. 203 204H4: TLSVerifyClient { never | allow | try | demand } 205 206This directive specifies what checks to perform on client certificates 207in an incoming TLS session, if any. This option is set to {{EX:never}} 208by default, in which case the server never asks the client for a 209certificate. With a setting of {{EX:allow}} the server will ask 210for a client certificate; if none is provided the session proceeds 211normally. If a certificate is provided but the server is unable to 212verify it, the certificate is ignored and the session proceeds 213normally, as if no certificate had been provided. With a setting of 214{{EX:try}} the certificate is requested, and if none is provided, 215the session proceeds normally. If a certificate is provided and it 216cannot be verified, the session is immediately terminated. With a 217setting of {{EX:demand}} the certificate is requested and a valid 218certificate must be provided, otherwise the session is immediately 219terminated. 220 221Note: The server must request a client certificate in order to 222use the SASL EXTERNAL authentication mechanism with a TLS session. 223As such, a non-default {{EX:TLSVerifyClient}} setting must be configured 224before SASL EXTERNAL authentication may be attempted, and the 225SASL EXTERNAL mechanism will only be offered to the client if a valid 226client certificate was received. 227 228H3: Client Configuration 229 230Most of the client configuration directives parallel the server 231directives. The names of the directives are different, and they go 232into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their 233functionality is mostly the same. Also, while most of these options may 234be configured on a system-wide basis, they may all be overridden by 235individual users in their {{.ldaprc}} files. 236 237The LDAP Start TLS operation is used in LDAP to initiate TLS 238negotiation. All OpenLDAP command line tools support a {{EX:-Z}} 239and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to 240be issued. The latter flag indicates that the tool is to cease 241processing if TLS cannot be started while the former allows the 242command to continue. 243 244In LDAPv2 environments, TLS is normally started using the LDAP 245Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI 246scheme ({{EX:ldap://}}). OpenLDAP command line tools allow either 247scheme to used with the {{EX:-H}} flag and with the {{EX:URI}} 248{{ldap.conf}}(5) option. 249 250 251H4: TLS_CACERT <filename> 252 253This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As 254noted in the {{SECT:TLS Configuration}} section, a client typically 255may need to know about more CAs than a server, but otherwise the 256same considerations apply. 257 258H4: TLS_CACERTDIR <path> 259 260This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The 261specified directory must be managed with the OpenSSL {{c_rehash}} 262utility as well. If using Mozilla NSS, <path> may contain a cert/key database. 263 264H4: TLS_CERT <filename> 265 266This directive specifies the file that contains the client certificate. 267This is a user-only directive and can only be specified in a user's 268{{.ldaprc}} file. 269 270When using Mozilla NSS, if using a cert/key database (specified with 271{{EX:TLS_CACERTDIR}}), this directive specifies 272the name of the certificate to use: 273 274> TLS_CERT Certificate for Sam Carter 275 276. If using a token other than the internal built in token, specify the 277. token name first, followed by a colon: 278 279> TLS_CERT my hardware device:Certificate for Sam Carter 280 281. Use {{EX:certutil -L}} to list the certificates by name: 282 283> certutil -d /path/to/certdbdir -L 284 285 286H4: TLS_KEY <filename> 287 288This directive specifies the file that contains the private key 289that matches the certificate stored in the {{EX:TLS_CERT}} 290file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}} 291apply here. This is also a user-only directive. 292 293H4: TLS_RANDFILE <filename> 294 295This directive is the same as the server's {{EX:TLSRandFile}} 296option. 297 298H4: TLS_REQCERT { never | allow | try | demand } 299 300This directive is equivalent to the server's {{EX:TLSVerifyClient}} 301option. However, for clients the default value is {{EX:demand}} 302and there generally is no good reason to change this setting. 303 304