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

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