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

   1 # $OpenLDAP$
   2 # Copyright 1999-2008 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 Besides the individual cipher names, the specifiers {{EX:HIGH}},
 117 {{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}}
 118 may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}},
 119 and {{EX:SSLv2}}.
 120
 121 H4: TLSRandFile <filename>
 122
 123 This directive specifies the file to obtain random bits from when
 124 {{FILE:/dev/urandom}} is not available. If the system provides
 125 {{FILE:/dev/urandom}} then this option is not needed, otherwise a
 126 source of random data must be configured.  Some systems (e.g. Linux)
 127 provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris)
 128 require the installation of a patch to provide it, and others may
 129 not support it at all. In the latter case, EGD or PRNGD should be
 130 installed, and this directive should specify the name of the EGD/PRNGD
 131 socket. The environment variable {{EX:RANDFILE}} can also be used
 132 to specify the filename. Also, in the absence of these options, the
 133 {{EX:.rnd}} file in the slapd user's home directory may be used if
 134 it exists. To use the {{EX:.rnd}} file, just create the file and
 135 copy a few hundred bytes of arbitrary data into the file. The file
 136 is only used to provide a seed for the pseudo-random number generator,
 137 and it doesn't need very much data to work.
 138
 139 H4: TLSEphemeralDHParamFile <filename>
 140
 141 This directive specifies the file that contains parameters for
 142 Diffie-Hellman ephemeral key exchange.  This is required in order
 143 to use a DSA certificate on the server side (i.e.
 144 {{EX:TLSCertificateKeyFile}} points to a DSA key).  Multiple sets
 145 of parameters can be included in the file; all of them will be
 146 processed.  Parameters can be generated using the following command
 147
 148 >       openssl dhparam [-dsaparam] -out <filename> <numbits>
 149
 150 H4: TLSVerifyClient { never | allow | try | demand }
 151
 152 This directive specifies what checks to perform on client certificates
 153 in an incoming TLS session, if any. This option is set to {{EX:never}}
 154 by default, in which case the server never asks the client for a
 155 certificate. With a setting of {{EX:allow}} the server will ask
 156 for a client certificate; if none is provided the session proceeds
 157 normally. If a certificate is provided but the server is unable to
 158 verify it, the certificate is ignored and the session proceeds
 159 normally, as if no certificate had been provided. With a setting of
 160 {{EX:try}} the certificate is requested, and if none is provided,
 161 the session proceeds normally. If a certificate is provided and it
 162 cannot be verified, the session is immediately terminated. With a
 163 setting of {{EX:demand}} the certificate is requested and a valid
 164 certificate must be provided, otherwise the session is immediately
 165 terminated.
 166
 167 Note: The server must request a client certificate in order to
 168 use the SASL EXTERNAL authentication mechanism with a TLS session.
 169 As such, a non-default {{EX:TLSVerifyClient}} setting must be configured
 170 before SASL EXTERNAL authentication may be attempted, and the
 171 SASL EXTERNAL mechanism will only be offered to the client if a valid
 172 client certificate was received.
 173
 174 H3: Client Configuration
 175
 176 Most of the client configuration directives parallel the server
 177 directives. The names of the directives are different, and they go
 178 into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their
 179 functionality is mostly the same. Also, while most of these options may
 180 be configured on a system-wide basis, they may all be overridden by
 181 individual users in their {{.ldaprc}} files.
 182
 183 The LDAP Start TLS operation is used in LDAP to initiate TLS
 184 negotiation.  All OpenLDAP command line tools support a {{EX:-Z}}
 185 and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to
 186 be issued.  The latter flag indicates that the tool is to cease
 187 processing if TLS cannot be started while the former allows the
 188 command to continue.
 189
 190 In LDAPv2 environments, TLS is normally started using the LDAP
 191 Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI
 192 scheme ({{EX:ldap://}}).  OpenLDAP command line tools allow either
 193 scheme to used with the {{EX:-H}} flag and with the {{EX:URI}}
 194 {{ldap.conf}}(5) option.
 195
 196
 197 H4: TLS_CACERT <filename>
 198
 199 This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As
 200 noted in the {{SECT:TLS Configuration}} section, a client typically
 201 may need to know about more CAs than a server, but otherwise the
 202 same considerations apply.
 203
 204 H4: TLS_CACERTDIR <path>
 205
 206 This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
 207 specified directory must be managed with the OpenSSL {{c_rehash}}
 208 utility as well.
 209
 210 H4: TLS_CERT <filename>
 211
 212 This directive specifies the file that contains the client certificate.
 213 This is a user-only directive and can only be specified in a user's
 214 {{.ldaprc}} file.
 215
 216 H4: TLS_KEY <filename>
 217
 218 This directive specifies the file that contains the private key
 219 that matches the certificate stored in the {{EX:TLS_CERT}}
 220 file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}}
 221 apply here. This is also a user-only directive.
 222
 223 H4: TLS_RANDFILE <filename>
 224
 225 This directive is the same as the server's {{EX:TLSRandFile}}
 226 option.
 227
 228 H4: TLS_REQCERT { never | allow | try | demand }
 229
 230 This directive is equivalent to the server's {{EX:TLSVerifyClient}}
 231 option. However, for clients the default value is {{EX:demand}}
 232 and there generally is no good reason to change this setting.
 233