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

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