Merge remote-tracking branch 'origin/mdb.master'

[openldap] / doc / guide / admin / tls.sdf

diff --git a/doc/guide/admin/tls.sdf b/doc/guide/admin/tls.sdf
index c1b22a6aa94e8e7a531320f6cb5eba0566710057..00bf83ce262872a7a4a35902e476d94a9d1a38fa 100644 (file)
--- a/doc/guide/admin/tls.sdf
+++ b/doc/guide/admin/tls.sdf
@@ -1,5 +1,5 @@
 # $OpenLDAP$
 # $OpenLDAP$

-# Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.

 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Using TLS
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Using TLS


@@ -10,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}}.
 
 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
 H2: TLS Certificates
 
 TLS uses {{TERM:X.509}} certificates to carry client and server


@@ -17,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,
 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
 
 
 H3: Server Certificates
 


@@ -87,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.
 
 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 <path> -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 <filename>
 
 This directive specifies the file that contains the slapd server
 certificate. Certificates are generally public information and
 require no special protection.
 
 H4: TLSCertificateFile <filename>
 
 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 <filename>
 
 This directive specifies the file that contains the private key
 H4: TLSCertificateKeyFile <filename>
 
 This directive specifies the file that contains the private key


@@ -102,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.
 
 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 <cipher-suite-spec>
 
 This directive configures what ciphers will be accepted and the
 H4: TLSCipherSuite <cipher-suite-spec>
 
 This directive configures what ciphers will be accepted and the


@@ -111,11 +151,23 @@ specification for OpenSSL. You can use the command
 >      openssl ciphers -v ALL
 
 to obtain a verbose list of available cipher specifications.
 >      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}}.
 
 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 <filename>
 
 This directive specifies the file to obtain random bits from when
 H4: TLSRandFile <filename>
 
 This directive specifies the file to obtain random bits from when


@@ -134,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.
 
 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 <filename>
 
 This directive specifies the file that contains parameters for
 H4: TLSEphemeralDHParamFile <filename>
 
 This directive specifies the file that contains parameters for


@@ -145,6 +199,8 @@ processed.  Parameters can be generated using the following command
 
 >      openssl dhparam [-dsaparam] -out <filename> <numbits>
 
 
 >      openssl dhparam [-dsaparam] -out <filename> <numbits>
 

+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
 H4: TLSVerifyClient { never | allow | try | demand }
 
 This directive specifies what checks to perform on client certificates


@@ -179,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
 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
 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


@@ -203,7 +259,7 @@ H4: TLS_CACERTDIR <path>
 
 This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
 specified directory must be managed with the OpenSSL {{c_rehash}}
 
 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, <path> may contain a cert/key database.

 
 H4: TLS_CERT <filename>
 
 
 H4: TLS_CERT <filename>
 


@@ -211,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.
 
 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 <filename>
 
 This directive specifies the file that contains the private key
 H4: TLS_KEY <filename>
 
 This directive specifies the file that contains the private key