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

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