1# $OpenLDAP$ 2# Copyright 1999-2017 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: TLSDHParamFile <filename> 192 193This directive specifies the file that contains parameters for 194Diffie-Hellman ephemeral key exchange. This is required in order 195to use DHE-based cipher suites, including all DSA-based suites (i.e. 196{{EX:TLSCertificateKeyFile}} points to a DSA key), and RSA when the 'key 197encipherment' key usage is not specified in the certificate. Parameters can be 198generated using the following command 199 200> openssl dhparam [-dsaparam] -out <filename> <numbits> 201or 202> certtool --generate-dh-params --bits <numbits> --outfile <filename> 203 204This directive is ignored with Mozilla NSS. 205 206H4: TLSVerifyClient { never | allow | try | demand } 207 208This directive specifies what checks to perform on client certificates 209in an incoming TLS session, if any. This option is set to {{EX:never}} 210by default, in which case the server never asks the client for a 211certificate. With a setting of {{EX:allow}} the server will ask 212for a client certificate; if none is provided the session proceeds 213normally. If a certificate is provided but the server is unable to 214verify it, the certificate is ignored and the session proceeds 215normally, as if no certificate had been provided. With a setting of 216{{EX:try}} the certificate is requested, and if none is provided, 217the session proceeds normally. If a certificate is provided and it 218cannot be verified, the session is immediately terminated. With a 219setting of {{EX:demand}} the certificate is requested and a valid 220certificate must be provided, otherwise the session is immediately 221terminated. 222 223Note: The server must request a client certificate in order to 224use the SASL EXTERNAL authentication mechanism with a TLS session. 225As such, a non-default {{EX:TLSVerifyClient}} setting must be configured 226before SASL EXTERNAL authentication may be attempted, and the 227SASL EXTERNAL mechanism will only be offered to the client if a valid 228client certificate was received. 229 230H3: Client Configuration 231 232Most of the client configuration directives parallel the server 233directives. The names of the directives are different, and they go 234into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their 235functionality is mostly the same. Also, while most of these options may 236be configured on a system-wide basis, they may all be overridden by 237individual users in their {{.ldaprc}} files. 238 239The LDAP Start TLS operation is used in LDAP to initiate TLS 240negotiation. All OpenLDAP command line tools support a {{EX:-Z}} 241and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to 242be issued. The latter flag indicates that the tool is to cease 243processing if TLS cannot be started while the former allows the 244command to continue. 245 246In LDAPv2 environments, TLS is normally started using the LDAP 247Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI 248scheme ({{EX:ldap://}}). OpenLDAP command line tools allow either 249scheme to used with the {{EX:-H}} flag and with the {{EX:URI}} 250{{ldap.conf}}(5) option. 251 252 253H4: TLS_CACERT <filename> 254 255This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As 256noted in the {{SECT:TLS Configuration}} section, a client typically 257may need to know about more CAs than a server, but otherwise the 258same considerations apply. 259 260H4: TLS_CACERTDIR <path> 261 262This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The 263specified directory must be managed with the OpenSSL {{c_rehash}} 264utility as well. If using Mozilla NSS, <path> may contain a cert/key database. 265 266H4: TLS_CERT <filename> 267 268This directive specifies the file that contains the client certificate. 269This is a user-only directive and can only be specified in a user's 270{{.ldaprc}} file. 271 272When using Mozilla NSS, if using a cert/key database (specified with 273{{EX:TLS_CACERTDIR}}), this directive specifies 274the name of the certificate to use: 275 276> TLS_CERT Certificate for Sam Carter 277 278. If using a token other than the internal built in token, specify the 279. token name first, followed by a colon: 280 281> TLS_CERT my hardware device:Certificate for Sam Carter 282 283. Use {{EX:certutil -L}} to list the certificates by name: 284 285> certutil -d /path/to/certdbdir -L 286 287 288H4: TLS_KEY <filename> 289 290This directive specifies the file that contains the private key 291that matches the certificate stored in the {{EX:TLS_CERT}} 292file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}} 293apply here. This is also a user-only directive. 294 295H4: TLS_RANDFILE <filename> 296 297This directive is the same as the server's {{EX:TLSRandFile}} 298option. 299 300H4: TLS_REQCERT { never | allow | try | demand } 301 302This directive is equivalent to the server's {{EX:TLSVerifyClient}} 303option. However, for clients the default value is {{EX:demand}} 304and there generally is no good reason to change this setting. 305 306