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

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