X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Ftls.sdf;h=00bf83ce262872a7a4a35902e476d94a9d1a38fa;hb=1c581612f72f59ec485b6128575afe697a2b5870;hp=9126e06ebea8d2ee58f351e05896b8d926e06c9c;hpb=7cc734e529c75546d4c12828f0fe02386a908f25;p=openldap diff --git a/doc/guide/admin/tls.sdf b/doc/guide/admin/tls.sdf index 9126e06ebe..00bf83ce26 100644 --- a/doc/guide/admin/tls.sdf +++ b/doc/guide/admin/tls.sdf @@ -1,4 +1,5 @@ -# Copyright 1999-2006 The OpenLDAP Foundation, All Rights Reserved. +# $OpenLDAP$ +# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. H1: Using TLS @@ -9,6 +10,8 @@ integrity and confidentiality protections and to support 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 @@ -16,7 +19,8 @@ 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}} documentation. +see the {{PRD:OpenSSL}}, {{PRD:GnuTLS}}, or {{PRD:MozNSS}} documentation, +depending on which TLS implementation libraries you are using. H3: Server Certificates @@ -86,12 +90,37 @@ 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 @@ -101,6 +130,18 @@ 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 @@ -110,11 +151,23 @@ 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 @@ -133,6 +186,8 @@ 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 @@ -144,6 +199,8 @@ 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 @@ -178,7 +235,7 @@ 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 -negotatation. All OpenLDAP command line tools support a {{EX:-Z}} +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 @@ -202,7 +259,7 @@ 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. +utility as well. If using Mozilla NSS, may contain a cert/key database. H4: TLS_CERT @@ -210,6 +267,22 @@ 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