1# $OpenLDAP$ 2# Copyright 1999-2021 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 certificates, 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}} or {{PRD:GnuTLS}} 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 {{rehash}} 85command. When using this feature, the OpenSSL library will attempt to 86locate certificate files based on a hash of their name and serial number. 87The OpenSSL {{rehash}} command 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 93H4: TLSCertificateFile <filename> 94 95This directive specifies the file that contains the slapd server 96certificate. Certificates are generally public information and 97require no special protection. 98 99H4: TLSCertificateKeyFile <filename> 100 101This directive specifies the file that contains the private key 102that matches the certificate stored in the {{EX:TLSCertificateFile}} 103file. Private keys themselves are sensitive data and are usually 104password encrypted for protection. However, the current implementation 105doesn't support encrypted keys so the key must not be encrypted 106and the file itself must be protected carefully. 107 108H4: TLSCipherSuite <cipher-suite-spec> 109 110This directive configures what ciphers will be accepted and the 111preference order. {{EX:<cipher-suite-spec>}} should be a cipher 112specification for OpenSSL. You can use the command 113 114> openssl ciphers -v ALL 115 116to obtain a verbose list of available cipher specifications. 117 118Besides the individual cipher names, the specifiers {{EX:HIGH}}, 119{{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}} 120may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}}, 121and {{EX:SSLv2}}. 122 123To obtain the list of ciphers in GnuTLS use: 124 125> gnutls-cli -l 126 127H4: TLSRandFile <filename> 128 129This directive specifies the file to obtain random bits from when 130{{FILE:/dev/urandom}} is not available. If the system provides 131{{FILE:/dev/urandom}} then this option is not needed, otherwise a 132source of random data must be configured. Some systems (e.g. Linux) 133provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris) 134require the installation of a patch to provide it, and others may 135not support it at all. In the latter case, EGD or PRNGD should be 136installed, and this directive should specify the name of the EGD/PRNGD 137socket. The environment variable {{EX:RANDFILE}} can also be used 138to specify the filename. Also, in the absence of these options, the 139{{EX:.rnd}} file in the slapd user's home directory may be used if 140it exists. To use the {{EX:.rnd}} file, just create the file and 141copy a few hundred bytes of arbitrary data into the file. The file 142is only used to provide a seed for the pseudo-random number generator, 143and it doesn't need very much data to work. 144 145This directive is ignored with GnuTLS. 146 147H4: TLSDHParamFile <filename> 148 149This directive specifies the file that contains parameters for 150Diffie-Hellman ephemeral key exchange. This is required in order 151to use DHE-based cipher suites, including all DSA-based suites (i.e. 152{{EX:TLSCertificateKeyFile}} points to a DSA key), and RSA when the 'key 153encipherment' key usage is not specified in the certificate. Parameters can be 154generated using the following command 155 156> openssl dhparam [-dsaparam] -out <filename> <numbits> 157or 158> certtool --generate-dh-params --bits <numbits> --outfile <filename> 159 160H4: TLSECName <name> 161 162This directive specifies the curve to use for Elliptic Curve 163Diffie-Hellman ephemeral key exchange. This is required in order 164to use ECDHE-based cipher suites in OpenSSL. The names of supported 165curves may be shown using the following command 166 167> openssl ecparam -list_curves 168 169This directive is not used for GnuTLS. 170For GnuTLS the curves may be specified in the ciphersuite. 171 172H4: TLSVerifyClient { never | allow | try | demand } 173 174This directive specifies what checks to perform on client certificates 175in an incoming TLS session, if any. This option is set to {{EX:never}} 176by default, in which case the server never asks the client for a 177certificate. With a setting of {{EX:allow}} the server will ask 178for a client certificate; if none is provided the session proceeds 179normally. If a certificate is provided but the server is unable to 180verify it, the certificate is ignored and the session proceeds 181normally, as if no certificate had been provided. With a setting of 182{{EX:try}} the certificate is requested, and if none is provided, 183the session proceeds normally. If a certificate is provided and it 184cannot be verified, the session is immediately terminated. With a 185setting of {{EX:demand}} the certificate is requested and a valid 186certificate must be provided, otherwise the session is immediately 187terminated. 188 189Note: The server must request a client certificate in order to 190use the SASL EXTERNAL authentication mechanism with a TLS session. 191As such, a non-default {{EX:TLSVerifyClient}} setting must be configured 192before SASL EXTERNAL authentication may be attempted, and the 193SASL EXTERNAL mechanism will only be offered to the client if a valid 194client certificate was received. 195 196H3: Client Configuration 197 198Most of the client configuration directives parallel the server 199directives. The names of the directives are different, and they go 200into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their 201functionality is mostly the same. Also, while most of these options may 202be configured on a system-wide basis, they may all be overridden by 203individual users in their {{.ldaprc}} files. 204 205The LDAP Start TLS operation is used in LDAP to initiate TLS 206negotiation. All OpenLDAP command line tools support a {{EX:-Z}} 207and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to 208be issued. The latter flag indicates that the tool is to cease 209processing if TLS cannot be started while the former allows the 210command to continue. 211 212In LDAPv2 environments, TLS is normally started using the LDAP 213Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI 214scheme ({{EX:ldap://}}). OpenLDAP command line tools allow either 215scheme to used with the {{EX:-H}} flag and with the {{EX:URI}} 216{{ldap.conf}}(5) option. 217 218 219H4: TLS_CACERT <filename> 220 221This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As 222noted in the {{SECT:TLS Configuration}} section, a client typically 223may need to know about more CAs than a server, but otherwise the 224same considerations apply. 225 226H4: TLS_CACERTDIR <path> 227 228This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The 229specified directory must be managed with the OpenSSL {{rehash}} 230command as well. 231 232H4: TLS_CERT <filename> 233 234This directive specifies the file that contains the client certificate. 235This is a user-only directive and can only be specified in a user's 236{{.ldaprc}} file. 237 238H4: TLS_KEY <filename> 239 240This directive specifies the file that contains the private key 241that matches the certificate stored in the {{EX:TLS_CERT}} 242file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}} 243apply here. This is also a user-only directive. 244 245H4: TLS_RANDFILE <filename> 246 247This directive is the same as the server's {{EX:TLSRandFile}} 248option. 249 250H4: TLS_REQCERT { never | allow | try | demand } 251 252This directive is equivalent to the server's {{EX:TLSVerifyClient}} 253option. However, for clients the default value is {{EX:demand}} 254and there generally is no good reason to change this setting. 255 256