git.sur5r.net Git - openldap/blob - doc/guide/admin/tls.sdf

   1 # $OpenLDAP$
   2 # Copyright 1999-2011 The OpenLDAP Foundation, All Rights Reserved.
   3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   4
   5 H1: Using TLS
   6
   7 OpenLDAP clients and servers are capable of using the
   8 {{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide
   9 integrity and confidentiality protections and to support
  10 LDAP authentication using the {{TERM:SASL}} {{TERM:EXTERNAL}} mechanism.
  11 TLS is defined in {{REF:RFC4346}}.
  12
  13 Note: For generating certifcates, please reference {{URL:http://www.openldap.org/faq/data/cache/185.html}}
  14
  15 H2: TLS Certificates
  16
  17 TLS uses {{TERM:X.509}} certificates to carry client and server
  18 identities.  All servers are required to have valid certificates,
  19 whereas client certificates are optional.  Clients must have a
  20 valid certificate in order to authenticate via SASL EXTERNAL.
  21 For more information on creating and managing certificates,
  22 see the {{PRD:OpenSSL}} documentation.
  23
  24 H3: Server Certificates
  25
  26 The {{TERM:DN}} of a server certificate must use the {{EX:CN}}
  27 attribute to name the server, and the {{EX:CN}} must carry the
  28 server's fully qualified domain name. Additional alias names and
  29 wildcards may be present in the {{EX:subjectAltName}} certificate
  30 extension.  More details on server certificate names are in
  31 {{REF:RFC4513}}.
  32
  33 H3: Client Certificates
  34
  35 The DN of a client certificate can be used directly as an
  36 authentication DN.
  37 Since X.509 is a part of the {{TERM:X.500}} standard and LDAP
  38 is also based on X.500, both use the same DN formats and
  39 generally the DN in a user's X.509 certificate should be
  40 identical to the DN of their LDAP entry. However, sometimes
  41 the DNs may not be exactly the same, and so the mapping
  42 facility described in
  43 {{SECT:Mapping Authentication Identities}}
  44 can be applied to these DNs as well.
  45
  46 H2: TLS Configuration
  47
  48 After obtaining the required certificates, a number of options must
  49 be configured on both the client and the server to enable TLS and
  50 make use of the certificates.  At a minimum, the clients must be
  51 configured with the name of the file containing all of the
  52 {{TERM[expand]CA}} (CA) certificates it will trust. The server must
  53 be configured with the {{TERM:CA}} certificates and also its own
  54 server certificate and private key.
  55
  56 Typically a single CA will have issued the server certificate
  57 and all of the trusted client certificates, so the server only
  58 needs to trust that one signing CA. However, a client may wish
  59 to connect to a variety of secure servers managed by different
  60 organizations, with server certificates generated by many
  61 different CAs. As such, a client is likely to need a list of
  62 many different trusted CAs in its configuration.
  63
  64 H3: Server Configuration
  65
  66 The configuration directives for slapd belong in the global directives
  67 section of {{slapd.conf}}(5).
  68
  69 H4: TLSCACertificateFile <filename>
  70
  71 This directive specifies the {{TERM:PEM}}-format file containing
  72 certificates for the CA's that slapd will trust. The certificate for
  73 the CA that signed the server certificate must be included among
  74 these certificates. If the signing CA was not a top-level (root) CA,
  75 certificates for the entire sequence of CA's from the signing CA to
  76 the top-level CA should be present. Multiple certificates are simply
  77 appended to the file; the order is not significant.
  78
  79 H4: TLSCACertificatePath <path>
  80
  81 This directive specifies the path of a directory that contains
  82 individual {{TERM:CA}} certificates in separate files.  In addition,
  83 this directory must be specially managed using the OpenSSL {{c_rehash}}
  84 utility. When using this feature, the OpenSSL library will attempt to
  85 locate certificate files based on a hash of their name and serial number.
  86 The {{c_rehash}} utility is used to generate symbolic links with the
  87 hashed names that point to the actual certificate files. As such,
  88 this option can only be used with a filesystem that actually supports
  89 symbolic links. In general, it is simpler to use the
  90 {{EX:TLSCACertificateFile}} directive instead.
  91
  92 H4: TLSCertificateFile <filename>
  93
  94 This directive specifies the file that contains the slapd server
  95 certificate. Certificates are generally public information and
  96 require no special protection.
  97
  98 H4: TLSCertificateKeyFile <filename>
  99
 100 This directive specifies the file that contains the private key
 101 that matches the certificate stored in the {{EX:TLSCertificateFile}}
 102 file. Private keys themselves are sensitive data and are usually
 103 password encrypted for protection. However, the current implementation
 104 doesn't support encrypted keys so the key must not be encrypted
 105 and the file itself must be protected carefully.
 106
 107 H4: TLSCipherSuite <cipher-suite-spec>
 108
 109 This directive configures what ciphers will be accepted and the
 110 preference order. {{EX:<cipher-suite-spec>}} should be a cipher
 111 specification for OpenSSL. You can use the command
 112
 113 >       openssl ciphers -v ALL
 114
 115 to obtain a verbose list of available cipher specifications.
 116
 117 To obtain the list of ciphers in GNUtls use:
 118
 119 >       gnutls-cli -l
 120
 121 Besides the individual cipher names, the specifiers {{EX:HIGH}},
 122 {{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}}
 123 may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}},
 124 and {{EX:SSLv2}}.
 125
 126 H4: TLSRandFile <filename>
 127
 128 This directive specifies the file to obtain random bits from when
 129 {{FILE:/dev/urandom}} is not available. If the system provides
 130 {{FILE:/dev/urandom}} then this option is not needed, otherwise a
 131 source of random data must be configured.  Some systems (e.g. Linux)
 132 provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris)
 133 require the installation of a patch to provide it, and others may
 134 not support it at all. In the latter case, EGD or PRNGD should be
 135 installed, and this directive should specify the name of the EGD/PRNGD
 136 socket. The environment variable {{EX:RANDFILE}} can also be used
 137 to specify the filename. Also, in the absence of these options, the
 138 {{EX:.rnd}} file in the slapd user's home directory may be used if
 139 it exists. To use the {{EX:.rnd}} file, just create the file and
 140 copy a few hundred bytes of arbitrary data into the file. The file
 141 is only used to provide a seed for the pseudo-random number generator,
 142 and it doesn't need very much data to work.
 143
 144 H4: TLSEphemeralDHParamFile <filename>
 145
 146 This directive specifies the file that contains parameters for
 147 Diffie-Hellman ephemeral key exchange.  This is required in order
 148 to use a DSA certificate on the server side (i.e.
 149 {{EX:TLSCertificateKeyFile}} points to a DSA key).  Multiple sets
 150 of parameters can be included in the file; all of them will be
 151 processed.  Parameters can be generated using the following command
 152
 153 >       openssl dhparam [-dsaparam] -out <filename> <numbits>
 154
 155 H4: TLSVerifyClient { never | allow | try | demand }
 156
 157 This directive specifies what checks to perform on client certificates
 158 in an incoming TLS session, if any. This option is set to {{EX:never}}
 159 by default, in which case the server never asks the client for a
 160 certificate. With a setting of {{EX:allow}} the server will ask
 161 for a client certificate; if none is provided the session proceeds
 162 normally. If a certificate is provided but the server is unable to
 163 verify it, the certificate is ignored and the session proceeds
 164 normally, as if no certificate had been provided. With a setting of
 165 {{EX:try}} the certificate is requested, and if none is provided,
 166 the session proceeds normally. If a certificate is provided and it
 167 cannot be verified, the session is immediately terminated. With a
 168 setting of {{EX:demand}} the certificate is requested and a valid
 169 certificate must be provided, otherwise the session is immediately
 170 terminated.
 171
 172 Note: The server must request a client certificate in order to
 173 use the SASL EXTERNAL authentication mechanism with a TLS session.
 174 As such, a non-default {{EX:TLSVerifyClient}} setting must be configured
 175 before SASL EXTERNAL authentication may be attempted, and the
 176 SASL EXTERNAL mechanism will only be offered to the client if a valid
 177 client certificate was received.
 178
 179 H3: Client Configuration
 180
 181 Most of the client configuration directives parallel the server
 182 directives. The names of the directives are different, and they go
 183 into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their
 184 functionality is mostly the same. Also, while most of these options may
 185 be configured on a system-wide basis, they may all be overridden by
 186 individual users in their {{.ldaprc}} files.
 187
 188 The LDAP Start TLS operation is used in LDAP to initiate TLS
 189 negotiation.  All OpenLDAP command line tools support a {{EX:-Z}}
 190 and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to
 191 be issued.  The latter flag indicates that the tool is to cease
 192 processing if TLS cannot be started while the former allows the
 193 command to continue.
 194
 195 In LDAPv2 environments, TLS is normally started using the LDAP
 196 Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI
 197 scheme ({{EX:ldap://}}).  OpenLDAP command line tools allow either
 198 scheme to used with the {{EX:-H}} flag and with the {{EX:URI}}
 199 {{ldap.conf}}(5) option.
 200
 201
 202 H4: TLS_CACERT <filename>
 203
 204 This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As
 205 noted in the {{SECT:TLS Configuration}} section, a client typically
 206 may need to know about more CAs than a server, but otherwise the
 207 same considerations apply.
 208
 209 H4: TLS_CACERTDIR <path>
 210
 211 This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
 212 specified directory must be managed with the OpenSSL {{c_rehash}}
 213 utility as well.
 214
 215 H4: TLS_CERT <filename>
 216
 217 This directive specifies the file that contains the client certificate.
 218 This is a user-only directive and can only be specified in a user's
 219 {{.ldaprc}} file.
 220
 221 H4: TLS_KEY <filename>
 222
 223 This directive specifies the file that contains the private key
 224 that matches the certificate stored in the {{EX:TLS_CERT}}
 225 file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}}
 226 apply here. This is also a user-only directive.
 227
 228 H4: TLS_RANDFILE <filename>
 229
 230 This directive is the same as the server's {{EX:TLSRandFile}}
 231 option.
 232
 233 H4: TLS_REQCERT { never | allow | try | demand }
 234
 235 This directive is equivalent to the server's {{EX:TLSVerifyClient}}
 236 option. However, for clients the default value is {{EX:demand}}
 237 and there generally is no good reason to change this setting.
 238