X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Ftls.sdf;h=00bf83ce262872a7a4a35902e476d94a9d1a38fa;hb=1c581612f72f59ec485b6128575afe697a2b5870;hp=51d5c84906b3b794386d0ccf0cf03692f8812cc8;hpb=0d6c14b41dae95d12a0c7439b5cbb788de0ba097;p=openldap diff --git a/doc/guide/admin/tls.sdf b/doc/guide/admin/tls.sdf index 51d5c84906..00bf83ce26 100644 --- a/doc/guide/admin/tls.sdf +++ b/doc/guide/admin/tls.sdf @@ -1,17 +1,303 @@ -# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. +# $OpenLDAP$ +# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. H1: Using TLS -OpenLDAP clients and servers are capable of using -Transport Layer Security {{TERM:TLS}} framework to provide +OpenLDAP clients and servers are capable of using the +{{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide integrity and confidentiality protections and to support -LDAP authentication via SASL EXTERNAL. +LDAP authentication using the {{TERM:SASL}} {{TERM:EXTERNAL}} mechanism. +TLS is defined in {{REF:RFC4346}}. + +Note: For generating certifcates, please reference {{URL:http://www.openldap.org/faq/data/cache/185.html}} + +H2: TLS Certificates TLS uses {{TERM:X.509}} certificates to carry client and server -identities. All servers are required to have valid certificates, -whereas client certificates are optional. Clients must have a -valid certificate in order to authenticate using the SASL EXTERNAL -mechanism. +identities. All servers are required to have valid certificates, +whereas client certificates are optional. Clients must have a +valid certificate in order to authenticate via SASL EXTERNAL. +For more information on creating and managing certificates, +see the {{PRD:OpenSSL}}, {{PRD:GnuTLS}}, or {{PRD:MozNSS}} documentation, +depending on which TLS implementation libraries you are using. + +H3: Server Certificates + +The {{TERM:DN}} of a server certificate must use the {{EX:CN}} +attribute to name the server, and the {{EX:CN}} must carry the +server's fully qualified domain name. Additional alias names and +wildcards may be present in the {{EX:subjectAltName}} certificate +extension. More details on server certificate names are in +{{REF:RFC4513}}. + +H3: Client Certificates + +The DN of a client certificate can be used directly as an +authentication DN. +Since X.509 is a part of the {{TERM:X.500}} standard and LDAP +is also based on X.500, both use the same DN formats and +generally the DN in a user's X.509 certificate should be +identical to the DN of their LDAP entry. However, sometimes +the DNs may not be exactly the same, and so the mapping +facility described in +{{SECT:Mapping Authentication Identities}} +can be applied to these DNs as well. + +H2: TLS Configuration + +After obtaining the required certificates, a number of options must +be configured on both the client and the server to enable TLS and +make use of the certificates. At a minimum, the clients must be +configured with the name of the file containing all of the +{{TERM[expand]CA}} (CA) certificates it will trust. The server must +be configured with the {{TERM:CA}} certificates and also its own +server certificate and private key. + +Typically a single CA will have issued the server certificate +and all of the trusted client certificates, so the server only +needs to trust that one signing CA. However, a client may wish +to connect to a variety of secure servers managed by different +organizations, with server certificates generated by many +different CAs. As such, a client is likely to need a list of +many different trusted CAs in its configuration. + +H3: Server Configuration + +The configuration directives for slapd belong in the global directives +section of {{slapd.conf}}(5). + +H4: TLSCACertificateFile + +This directive specifies the {{TERM:PEM}}-format file containing +certificates for the CA's that slapd will trust. The certificate for +the CA that signed the server certificate must be included among +these certificates. If the signing CA was not a top-level (root) CA, +certificates for the entire sequence of CA's from the signing CA to +the top-level CA should be present. Multiple certificates are simply +appended to the file; the order is not significant. + +H4: TLSCACertificatePath + +This directive specifies the path of a directory that contains +individual {{TERM:CA}} certificates in separate files. In addition, +this directory must be specially managed using the OpenSSL {{c_rehash}} +utility. When using this feature, the OpenSSL library will attempt to +locate certificate files based on a hash of their name and serial number. +The {{c_rehash}} utility is used to generate symbolic links with the +hashed names that point to the actual certificate files. As such, +this option can only be used with a filesystem that actually supports +symbolic links. In general, it is simpler to use the +{{EX:TLSCACertificateFile}} directive instead. + +When using Mozilla NSS, this directive can be used to specify the +path of the directory containing the NSS certificate and key database +files. The {{certutil}} command can be used to add a {{TERM:CA}} certificate: + +> certutil -d -A -n "name of CA cert" -t CT,, -a -i /path/to/cacertfile.pem + +. This command will add a CA certficate stored in the PEM (ASCII) formatted +. file named /path/to/cacertfile.pem. {{EX:-t CT,,}} means that the certificate is +. trusted to be a CA issuing certs for use in TLS clients and servers. + +H4: TLSCertificateFile + +This directive specifies the file that contains the slapd server +certificate. Certificates are generally public information and +require no special protection. + +When using Mozilla NSS, if using a cert/key database (specified with +{{EX:TLSCACertificatePath}}), this directive specifies +the name of the certificate to use: + +> TLSCertificateFile Server-Cert + +. If using a token other than the internal built in token, specify the +. token name first, followed by a colon: + +> TLSCertificateFile my hardware device:Server-Cert + +. Use {{EX:certutil -L}} to list the certificates by name: + +> certutil -d /path/to/certdbdir -L + +H4: TLSCertificateKeyFile + +This directive specifies the file that contains the private key +that matches the certificate stored in the {{EX:TLSCertificateFile}} +file. Private keys themselves are sensitive data and are usually +password encrypted for protection. However, the current implementation +doesn't support encrypted keys so the key must not be encrypted +and the file itself must be protected carefully. + +When using Mozilla NSS, this directive specifies the name of +a file that contains the password for the key for the certificate specified with +{{EX:TLSCertificateFile}}. The modutil command can be used to turn off password +protection for the cert/key database. For example, if {{EX:TLSCACertificatePath}} +specifes /etc/openldap/certdb as the location of the cert/key database, use +modutil to change the password to the empty string: + +> modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB' + +. You must have the old password, if any. Ignore the WARNING about the running +. browser. Press 'Enter' for the new password. + +H4: TLSCipherSuite + +This directive configures what ciphers will be accepted and the +preference order. {{EX:}} should be a cipher +specification for OpenSSL. You can use the command + +> openssl ciphers -v ALL + +to obtain a verbose list of available cipher specifications. + +Besides the individual cipher names, the specifiers {{EX:HIGH}}, +{{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}} +may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}}, +and {{EX:SSLv2}}. + +To obtain the list of ciphers in GnuTLS use: + +> gnutls-cli -l + +When using Mozilla NSS, the OpenSSL cipher suite specifications are used and +translated into the format used internally by Mozilla NSS. There isn't an easy +way to list the cipher suites from the command line. The authoritative list +is in the source code for Mozilla NSS in the file sslinfo.c in the structure + +> static const SSLCipherSuiteInfo suiteInfo[] + +H4: TLSRandFile + +This directive specifies the file to obtain random bits from when +{{FILE:/dev/urandom}} is not available. If the system provides +{{FILE:/dev/urandom}} then this option is not needed, otherwise a +source of random data must be configured. Some systems (e.g. Linux) +provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris) +require the installation of a patch to provide it, and others may +not support it at all. In the latter case, EGD or PRNGD should be +installed, and this directive should specify the name of the EGD/PRNGD +socket. The environment variable {{EX:RANDFILE}} can also be used +to specify the filename. Also, in the absence of these options, the +{{EX:.rnd}} file in the slapd user's home directory may be used if +it exists. To use the {{EX:.rnd}} file, just create the file and +copy a few hundred bytes of arbitrary data into the file. The file +is only used to provide a seed for the pseudo-random number generator, +and it doesn't need very much data to work. + +This directive is ignored with GnuTLS and Mozilla NSS. + +H4: TLSEphemeralDHParamFile + +This directive specifies the file that contains parameters for +Diffie-Hellman ephemeral key exchange. This is required in order +to use a DSA certificate on the server side (i.e. +{{EX:TLSCertificateKeyFile}} points to a DSA key). Multiple sets +of parameters can be included in the file; all of them will be +processed. Parameters can be generated using the following command + +> openssl dhparam [-dsaparam] -out + +This directive is ignored with GnuTLS and Mozilla NSS. + +H4: TLSVerifyClient { never | allow | try | demand } + +This directive specifies what checks to perform on client certificates +in an incoming TLS session, if any. This option is set to {{EX:never}} +by default, in which case the server never asks the client for a +certificate. With a setting of {{EX:allow}} the server will ask +for a client certificate; if none is provided the session proceeds +normally. If a certificate is provided but the server is unable to +verify it, the certificate is ignored and the session proceeds +normally, as if no certificate had been provided. With a setting of +{{EX:try}} the certificate is requested, and if none is provided, +the session proceeds normally. If a certificate is provided and it +cannot be verified, the session is immediately terminated. With a +setting of {{EX:demand}} the certificate is requested and a valid +certificate must be provided, otherwise the session is immediately +terminated. + +Note: The server must request a client certificate in order to +use the SASL EXTERNAL authentication mechanism with a TLS session. +As such, a non-default {{EX:TLSVerifyClient}} setting must be configured +before SASL EXTERNAL authentication may be attempted, and the +SASL EXTERNAL mechanism will only be offered to the client if a valid +client certificate was received. + +H3: Client Configuration + +Most of the client configuration directives parallel the server +directives. The names of the directives are different, and they go +into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their +functionality is mostly the same. Also, while most of these options may +be configured on a system-wide basis, they may all be overridden by +individual users in their {{.ldaprc}} files. + +The LDAP Start TLS operation is used in LDAP to initiate TLS +negotiation. All OpenLDAP command line tools support a {{EX:-Z}} +and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to +be issued. The latter flag indicates that the tool is to cease +processing if TLS cannot be started while the former allows the +command to continue. + +In LDAPv2 environments, TLS is normally started using the LDAP +Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI +scheme ({{EX:ldap://}}). OpenLDAP command line tools allow either +scheme to used with the {{EX:-H}} flag and with the {{EX:URI}} +{{ldap.conf}}(5) option. + + +H4: TLS_CACERT + +This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As +noted in the {{SECT:TLS Configuration}} section, a client typically +may need to know about more CAs than a server, but otherwise the +same considerations apply. + +H4: TLS_CACERTDIR + +This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The +specified directory must be managed with the OpenSSL {{c_rehash}} +utility as well. If using Mozilla NSS, may contain a cert/key database. + +H4: TLS_CERT + +This directive specifies the file that contains the client certificate. +This is a user-only directive and can only be specified in a user's +{{.ldaprc}} file. + +When using Mozilla NSS, if using a cert/key database (specified with +{{EX:TLS_CACERTDIR}}), this directive specifies +the name of the certificate to use: + +> TLS_CERT Certificate for Sam Carter + +. If using a token other than the internal built in token, specify the +. token name first, followed by a colon: + +> TLS_CERT my hardware device:Certificate for Sam Carter + +. Use {{EX:certutil -L}} to list the certificates by name: + +> certutil -d /path/to/certdbdir -L + + +H4: TLS_KEY + +This directive specifies the file that contains the private key +that matches the certificate stored in the {{EX:TLS_CERT}} +file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}} +apply here. This is also a user-only directive. + +H4: TLS_RANDFILE + +This directive is the same as the server's {{EX:TLSRandFile}} +option. + +H4: TLS_REQCERT { never | allow | try | demand } +This directive is equivalent to the server's {{EX:TLSVerifyClient}} +option. However, for clients the default value is {{EX:demand}} +and there generally is no good reason to change this setting.