Using certutil in Directory Server 5.2 for SSL with Server and Client Authentication

Transcription

1 Using certutil in Directory Server 5.2 for SSL with Server and Client Authentication This document provides instructions for using the certutil tool to generate certificates for use in enabling SSL in the Sun ONE Directory Server, as well as to generate certificates that client can use to authenticate to the server. It also discusses the process of configuring the Directory Server to accept SSL-based connections, as well as to allow clients to perform SASL EXTERNAL authentication. The certutil tool is part of the Network Security Services (NSS) library, which is a Mozilla project available at It can be used to manage the certificate databases used by the Directory Server, as well as other products like Messaging Server and Web Server, and also Netscape and Mozilla Web browsers. It is provided with the Directory Server in the shared/bin directory under the server install root. It is also included with the Directory Server Resource Kit in the lib/nss/bin directory. For all examples provided in this document, we will use the certutil tool included with the Directory Server. It is assumed that the Directory Server is running on Solaris, but the same instructions apply for all other UNIX-based platforms. There may be some differences if certutil is to be used on Windows. In the examples presented in this document, a Courier 8-point plain font will be used for prompts and program output. Text that must be entered by the user will be displayed using a Courier 10-point bold italics font. Note that in some cases, particularly for certain passwords, the text entered by the user may not actually be displayed in the terminal. 1

2 Generating a New Certificate Database While it is possible to create a new certificate database through the Directory Server administration console, this can also be done from the command line using certutil and providing the "-N" argument. The following arguments may also be provided: -d {certdir} -- This specifies the directory in which the certificate database files should be placed. If this argument is not provided, the database files will be placed in the ~/.netscape directory. While this is acceptable for Netscape browsers, certificates used by the Directory Server should be placed in the alias directory under the Directory Server install root (the "../../alias" directory relative to the location of the certutil tool). -P {prefix} -- This specifies the prefix that should be used for the certificate database public and private key stores. By default, public keys are stored in the file cert8.db file and private keys in the key3.db file, but if a prefix of "my" is provided, then the files will be named mycert8.db and mykey3.db, respectively. The Directory Server expects a prefix of "slapd- {instancename}-", where {instancename} is the name of the instance with which the certificate database is associated. For example, to generate a new certificate database for use with a Directory Server instance named "ssltest" (i.e., in the slapd-ssltest directory under the install root), then the following command should be used: $./certutil -N -d../../alias -P "slapd-ssltest-" In order to finish creating your database, you must enter a password which will be used to encrypt this key and any future keys. The password must be at least 8 characters long, and must contain at least one non-alphabetic character. Enter new password: password Re-enter password: password $ At this point, the alias directory under the server root should contain the files slapd-ssltestcert8.db, slapd-ssltest-key3.db, and secmod.db (this is the security module database, which is generally used for hardware tokens like the Sun CryptoAccelerator 1000). Generating a New Certificate Database 2

3 Generating a Self-Signed Certificate In order to accept SSL-based connections from clients the Directory Server must have a certificate. Certificates can be obtained from commercial certificate authorities like VeriSign or Thawte, or also from internal certificate authorities, and the process for doing that will be described in the next section. However, it is also possible to use certutil to generate self-signed certificates, which are perfectly fine for testing purposes. The strength of the encryption is just as strong as with commercial certificate authorities, but the certificate will not by default be trusted by any clients that perform any kind of validation. This will be an acceptable limitation in this case. In order to generate a self-signed certificate, certutil should be invoked with the "-S" and "-x" arguments. The other important arguments that may be used include: -n {nickname} -- This specifies the nickname to use for the certificate when it is stored in the certificate database. The directory server will use this nickname to choose the appropriate certificate from the certificate database. By default, it expects to use a nickname of "servercert". -s {subject} -- This specifies the subject to use for the certificate, which is very similar to a DN in the directory server. The format of the subject is specified in RFC 1485, but for a server certificate, it is typically composed from the following attributes: cn -- the common name, which should be the fully-qualified hostname of the server ou -- the organizational unit or department o -- the organization or company l -- the locality or city st -- the state, which should be the full name of the state not the two-character abbreviation c -- the country, which should be the two-character ISO country code -t {trustargs} -- This specifies the trust arguments for the certificate, which are kind of like file permissions in that it describes the kinds of operations in which the certificate may be used. The most important trust arguments include: -P -- Indicates that this certificate is a trusted peer certificate. -T -- Indicates that this certificate is one that is trusted for signing client certificates. -C -- Indicates that this certificate is one that is trusted for signing server certificates. -u -- Indicates that this certificate is a user certificate. -v {monthsvalid} -- This specifies the number of months that the certificate should be valid. By default, generated certificates are valid for three months. Note that any value provided for this argument will actually be added to those three months (so a value of 12 will evaluate to 12+3, or 15 months). Generating a Self-Signed Certificate 3

4 -f {passwordfile} -- This specifies the path to the file containing the password used to access the certificate database. If no password file is provided, then the password will be requested interactively. -d {certdir} -- This specifies the path to the directory containing the certificate database files. As before, it should be the "../../alias" directory. -P {prefix} -- This specifies the prefix for the cert8.db and key3.db files. As when creating a new certificate database, this should be "slapd-{instancename}-" This makes it possible to select the Netscape certificate extension(s) to include in the certificate. If this option is selected, then an interactive menu will be displayed when A server certificate should include at least the Netscape SSL server extension. The available Netscape extensions include: SSL Client -- This indicates that the certificate will be used by a client to authenticate itself to a server over SSL. SSL Server -- This indicates that the certificate will be used by a server to accept SSLbased connections from clients. S/MIME -- This indicates that the certificate will be used to sign and/or encrypt messages. Object Signing -- This indicates that the certificate will be used to sign objects to ensure authenticity and to provide tamper resistance. SSL CA -- This indicates that the certificate will be used to sign other certificates that may be used for SSL communication. S/MIME CA -- This indicates that the certificate will be used to sign other certificates that may be used for signing and encryption. Object Signing CA -- This indicates that the certificate will be used to sign other certificates that may be used for object signing. The command to use to generate a valid self-signed certificate might look like: $./certutil -S -x -n "server-cert" -s "cn=directory.example.com,ou=directory Services,o=Example Corp,l=Austin,st=Texas,c=US" -t CTPu -v 12 -d../../alias -P "slapdssltest-" -5 A random seed must be generated that will be used in the creation of your key. One of the easiest ways to create a random seed is to use the timing of keystrokes on a keyboard. To begin, type keys on the keyboard until this progress meter is full. DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD! Continue typing until the progress meter is full: ************************************************************ Finished. Press enter to continue: Enter Password or Pin for "NSS Certificate DB": password Generating a Self-Signed Certificate 4

5 Generating key. This may take a few moments SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish 0 - SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish 9 Is this a critical extension [y/n]? n Generating a Self-Signed Certificate 5

6 Viewing Certificate Database Contents After the previous command, the server certificate should have been generated and added into the certificate database. To verify this, we can use certutil to view the contents of that database. This can be done using the "-L" argument. The other options available include: -d {certdir} -- This specifies the path to the directory containing the certificate database files. -P {prefix} -- This specifies the prefix to use for the cert8.db and key3.db files. -n {nickname} -- This specifies the nickname of the certificate to display. If this argument is not provided, then a list of all certificates in the database will be provided. -a -- This indicates that the certificate with the specified nickname should be printed in the ASCII encoding specified in RFC The output may be displayed on the screen or redirected to a file. -r -- This indicates that the certificate with the specified nickname should be printed in the binary DER encoding. This output should be redirected to a file. To simply list the certificates in the database, the following command may be used: $./certutil -L -d../../alias -P "slapd-ssltest-" Certificate Name server-cert Trust Attributes CTPu,, p Valid peer P Trusted peer (implies p) c Valid CA T Trusted CA to issue client certs (implies c) C Trusted CA to certs(only server certs for ssl) (implies c) u User cert w Send warning In this case, we can see that there is only one certificate in the database, with a nickname of "server-cert". To list the details of this certificate, we can provide the nickname of that certificate on the command line: $./certutil -L -d../../alias -P "slapd-ssltest-" -n server-cert Certificate: Data: Version: 3 (0x2) Serial Number: 00:e3:55:72:0e Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: CN=directory.example.com, OU=Directory Services, O=Example Corp, L=Austin, ST=Texas, C=US Validity: Not Before: Sun Aug 15 16:34: Not After: Tue Nov 15 16:34: Subject: CN=directory.example.com, OU=Directory Services, O=Example Corp, L=Austin, ST=Texas, C=US Viewing Certificate Database Contents 6

7 Subject Public Key Info: Public Key Algorithm: PKCS #1 RSA Encryption RSA Public Key: Modulus: 00:b7:b4:96:5d:a8:54:f2:cd:a8:4d:27:61:11:4a: 1e:4e:59:96:84:ee:b7:59:f0:57:a3:6f:30:ac:c9: 7b:5b:e7:9b:d0:d3:03:2e:19:b6:9e:0a:3e:10:03: d3:55:14:c2:bc:85:d1:56:99:85:5c:b9:f0:c7:10: 87:89:0c:b4:92:df:f4:cd:62:a8:6f:41:01:55:ed: a2:27:f3:35:0c:04:d2:05:13:4a:ce:ea:4c:61:b5: 9e:16:fe:49:3d:89:e0:92:e9:5c:0e:07:9f:73:c6: ed:f5:df:60:a4:c4:f0:f5:c2:91:a3:6d:cf:ef:31: 8b:77:6a:5a:85:36:eb:4e:d3 Exponent: (0x10001) Signed Extensions: Name: Certificate Type Critical: False Data: <SSL Server> Fingerprint (MD5): D4:1D:8C:D9:8F:00:B2:04:E9:80:09:98:EC:F8:42:7E Fingerprint (SHA1): DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09 Signature Algorithm: PKCS #1 MD5 With RSA Encryption Signature: 6f:43:72:0c:87:71:92:1f:02:7c:6f:88:8f:cc:05:f6:c9:30: aa:39:54:9d:6f:74:9d:a3:5a:ff:f1:bc:62:06:bd:29:c8:48: 50:45:ba:4d:96:7c:b9:ec:f0:00:95:7d:04:58:4c:9d:c2:98: dc:cc:82:8f:ac:79:a8:e8:dc:59:71:c4:9f:cd:e6:93:16:cc: 4c:81:ea:f1:6a:eb:7b:74:81:ae:f7:a6:d9:38:1c:82:49:fa: 9d:31:4b:09:4d:11:c9:91:2e:0a:c2:4f:de:0c:2a:84:cb:54: e6:c4:3c:4f:2d:c5:17:7f:a4:bc:81:5e:14:1a:6f:29:5b:8a: d5:0e Certificate Trust Flags: SSL Flags: Valid Peer Trusted Valid CA Trusted CA User Trusted Client CA Flags: Object Signing Flags: Further, to display it in ASCII form, the "-a" argument can be added to the command line: $./certutil -L -d../../alias -P "slapd-ssltest-" -n server-cert -a -----BEGIN CERTIFICATE----- MIICmDCCAgGgAwIBAgIFAONVcg4wDQYJKoZIhvcNAQEEBQAwgYIxCzAJBgNVBAYT AlVTMQ4wDAYDVQQIEwVUZXhhczEPMA0GA1UEBxMGQXVzdGluMRUwEwYDVQQKEwxF egftcgxlienvcnaxgzazbgnvbastekrpcmvjdg9yesbtzxj2awnlczeembwga1ue AxMVZGlyZWN0b3J5LmV4YW1wbGUuY29tMB4XDTA0MDgxNTE2MzQyOVoXDTA1MTEx NTE2MzQyOVowgYIxCzAJBgNVBAYTAlVTMQ4wDAYDVQQIEwVUZXhhczEPMA0GA1UE BxMGQXVzdGluMRUwEwYDVQQKEwxFeGFtcGxlIENvcnAxGzAZBgNVBAsTEkRpcmVj dg9yesbtzxj2awnlczeembwga1ueaxmvzglyzwn0b3j5lmv4yw1wbguuy29tmigf MA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3tJZdqFTyzahNJ2ERSh5OWZaE7rdZ 8FejbzCsyXtb55vQ0wMuGbaeCj4QA9NVFMK8hdFWmYVcufDHEIeJDLSS3/TNYqhv QQFV7aIn8zUMBNIFE0rO6kxhtZ4W/kk9ieCS6VwOB59zxu3132CkxPD1wpGjbc/v MYt3alqFNutO0wIDAQABoxgwFjAUBglghkgBhvhCAQEBAf8EBAMCBkAwDQYJKoZI hvcnaqeebqadgyeab0nydidxkh8cfg+ij8wf9skwqjlunw90nana//g8yga9kchi UEW6TZZ8uezwAJV9BFhMncKY3MyCj6x5qOjcWXHEn83mkxbMTIHq8Wrre3SBrvem 2Tgcgkn6nTFLCU0RyZEuCsJP3gwqhMtU5sQ8Ty3FF3+kvIFeFBpvKVuK1Q4= -----END CERTIFICATE----- Viewing Certificate Database Contents 7

8 Generating a Certificate Signing Request Although using a self-signed certificate is fine for testing purposes, most production environments will want to use certificates signed by external certificate authorities (CAs) so that they will be more likely to be trusted by the clients accessing the server over SSL. To do this, it is necessary to generate a certificate signing request (CSR) that can be signed by such an external CA. This can also be done using certutil, by providing the "-R" option. The other options that may be used include: -s {subject} -- This specifies the subject to use for the certificate. It should be in the same format as was used when creating a self-signed request. -a -- This specifies that the certificate signing request should be written in ASCII format as per RFC By default, it will be written in DER form. Note that if certutil is to be used to sign the request, then it must be output in binary form rather than ASCII. -o {outputfile} -- This specifies the output file to which the request should be written. By default, it will be written to standard output. -f {passwordfile} -- This specifies the path to the file containing the password to use to access the private key store. By default, it will be interactively requested from the user. -d {certdir} -- This specifies the path to the directory containing the certificate database files. -P {prefix} -- This specifies the prefix to use for the cert8.db and key3.db files. The following command provides an example of generating such a request: $./certutil -R -s "cn=directory.example.com,ou=directory Services,o=Example Corp,l=Austin,st=Texas,c=US" -o /tmp/certrequest.der -d../../alias -P "slapd-ssltest-" A random seed must be generated that will be used in the creation of your key. One of the easiest ways to create a random seed is to use the timing of keystrokes on a keyboard. To begin, type keys on the keyboard until this progress meter is full. DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD! Continue typing until the progress meter is full: ************************************************************ Finished. Press enter to continue: Enter Password or Pin for "NSS Certificate DB": Generating key. This may take a few moments... Generating a Certificate Signing Request 8

9 At this point, the file /tmp/certrequest.der should contain the DER-encoded certificate signing request in a format that may be signed using certutil or some external CA. Generating a Certificate Signing Request 9

10 Generating a CA Certificate and Using It to Sign Requests Once a certificate signing request has been generated, it can be signed by an external CA. This may be a commercial CA like those provided by VeriSign or Thawte, or it may be signed by an internal CA using software from companies like VeriSign, RSA, or Entrust. However, this task can also be accomplished using free software like OpenSSL and certutil. In this case, certutil will be used to accomplish this task. The fist thing to do is to generate the CA certificate. This will be a self-signed certificate with the appropriate Netscape SSL CA extension. The process for generating this certificate is similar to generating a self-signed SSL server certificate and therefore the options available will not be described in detail. Note, however, that in a production environment the private key for the CA certificate must be carefully guarded (and therefore contained in its own certificate database) because anyone that has access to this private key can sign their own certificate requests to generate certificates that will be trusted by any client that trusts the CA certificate. This helps make man-in-the-middle attacks easier to perform, which could allow a malicious user to set up their own server to intercept and potentially alter intercepted communication. It would also make it possible to generate trusted client certificates, which could be used to authenticate to the Directory Server or other applications as another user. The following example shows the process of creating a new certificate database and the CA certificate to include in that database: $ mkdir cacertdb $./certutil -N -d cacertdb -P "ca-" In order to finish creating your database, you must enter a password which will be used to encrypt this key and any future keys. The password must be at least 8 characters long, and must contain at least one non-alphabetic character. Enter new password: password Re-enter password: password $./certutil -S -x -n "ca-cert" -s "cn=ca Certificate,ou=Directory Services,o=Example Corp,l=Austin,st=Texas,c=US" -t CTPu -v 120 -d cacertdb -P "ca-" -5 A random seed must be generated that will be used in the creation of your key. One of the easiest ways to create a random seed is to use the timing of keystrokes on a keyboard. To begin, type keys on the keyboard until this progress meter is full. DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD! Continue typing until the progress meter is full: ************************************************************ Finished. Press enter to continue: Enter Password or Pin for "NSS Certificate DB": password Generating a CA Certificate and Using It to Sign Requests 10

11 Generating key. This may take a few moments SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish 0 - SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish 9 Is this a critical extension [y/n]? n Once this CA certificate has been generated, it can be used to sign CSRs, particularly DERencoded requests. This can be done using the "-C" option to certutil. The following arguments may also be used: -c {nickname} -- This specifies the nickname of the CA certificate in the certificate database to use to sign the request. -i {inputfile} -- This specifies the path to the DER-encoded certificate request. -o {outputfile} -- This specifies the path to the output file in which to write the signed certificate. If this is not provided, then the DER-encoded certificate will be written to standard output. -v {monthsvalid} -- This specifies the number of months beyond the default of three that the certificate should be considered valid. -f {passwordfile} -- This specifies the path to the file containing the password needed to access the private key information. If this is not provided, then it will be interactively requested from the user. -d {certdir} -- This specifies the path to the certificate database containing the CA certificate. -P {prefix} -- This specifies the prefix for the cert8.db and key3.db files in the database containing the CA certificate This indicates that one or more Netscape certificate extensions should be added to the certificate. Generating a CA Certificate and Using It to Sign Requests 11

12 The following provides an example of this process: $./certutil -C -c "ca-cert" -i /tmp/certrequest.der -o /tmp/signedcert.der -v 12 -d cacertdb -P "ca-" SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish 9 Is this a critical extension [y/n]? n Enter Password or Pin for "NSS Certificate DB": password At this point, the file /tmp/signedcert.der should contain a valid signed certificate that may be imported into the certificate database that was used to generate this request. Note that while this certificate may be imported into any certificate database, it can only actually be used as an SSL server certificate in the database that was used to generate the request because that is the only one that contains the corresponding private key. The next section provides information on the process for importing this certificate into a certificate database. Generating a CA Certificate and Using It to Sign Requests 12

13 Importing an Externally-Signed Certificate into the Database Once a certificate has been signed, it can be added into the certificate database. This can be done using the certutil "-A" option. The other arguments that may be used include: -n {nickname} -- This specifies the nickname for the new certificate in the certificate database. If this certificate is for the Directory Server, then it should be named "server-cert". If it is another certificate (e.g., the CA certificate) then it can use another name. -t {trustargs} -- This specifies the trust arguments to use for the certificate. -i {inputfile} -- This specifies the input file that contains the certificate to import. If this is not provided, then it is expected that the certificate data will be provided on standard input. -a -- This specifies that the certificate being imported is in ASCII (RFC 1113) format. By default, it is expected to be in binary (DER) format. -d {certdir} -- This specifies the path to the directory containing the certificate database files. -P {prefix} -- This specifies the prefix to use for the cert8.db and key3.db files. For example, the following command can be used to import the certificate signed in the previous section into the Directory Server's certificate database: $./certutil -A -n "server-cert" -i /tmp/signedcert.der -t Pu -d../../alias -P "slapd-ssltest-" Note that this operation does not require a password because there is no need to access any private key information. There is also no output generated unless there is an error of some kind, so if there is no output, then the certificate was imported successfully. However, this can be confirmed by listing the contents of the certificate database: $./certutil -L -d../../alias -P "slapd-ssltest-" Certificate Name server-cert Trust Attributes Pu,, p Valid peer P Trusted peer (implies p) c Valid CA T Trusted CA to issue client certs (implies c) C Trusted CA to certs(only server certs for ssl) (implies c) u User cert w Send warning Note that if this certificate was signed using an internal rather than a commercial CA, it is likely that clients will not trust this certificate by default and it will therefore be necessary to import the Importing an Externally-Signed Certificate into the Database 13

14 CA certificate into the database along with the server certificate. The process for importing the CA certificate is very similar to the process for importing the server certificate, with the exception of the trust arguments and the nickname. The following example demonstrates the process of importing a CA certificate stored in ASCII format in the file /tmp/cacert.txt into the server's certificate database: $./certutil -A -n "ca-cert" -i /tmp/cacert.txt -a -t CT -d../../alias -P "slapd-ssltest-" Again, there will be no output generated, but we can list the certificates to verify that it was imported successfully: $./certutil -L -d../../alias -P "slapd-ssltest-" Certificate Name server-cert ca-cert Trust Attributes Pu,, CT,, p Valid peer P Trusted peer (implies p) c Valid CA T Trusted CA to issue client certs (implies c) C Trusted CA to certs(only server certs for ssl) (implies c) u User cert w Send warning Importing an Externally-Signed Certificate into the Database 14

15 Enabling SSL in the Directory Server Now that the Directory Server's certificate database has the appropriate certificates (regardless of the way they got there), the server can be configured to accept SSL-based connections. This is a three-step process: 1. Add a new "cn=rsa,cn=encryption,cn=config" entry to the server that provides basic information about the certificate to use in the certificate database. 2. Update the "cn=encryption,cn=config" entry to provide information about the location of the certificate database files and which algorithms are enabled. 3. Update the "cn=config" entry to specify the port on which the server should listen for SSLbased connections, and to indicate that it should enable SSL. These modifications can be made with the server online (although it will be necessary to restart for the changes to take effect) using the ldapmodify utility. The following provides an example of this: $./ldapmodify -D "cn=directory Manager" -w password dn: cn=rsa,cn=encryption,cn=config changetype: add objectclass: top objectclass: nsencryptionmodule cn: RSA nsssltoken: internal (software) nssslpersonalityssl: server-cert nssslactivation: on adding new entry cn=rsa,cn=encryption,cn=config dn: cn=encryption,cn=config changetype: modify replace: nsssl2 nsssl2: on - replace: nsssl3 nsssl3: on - replace: nssslclientauth nssslclientauth: allowed - replace: nscertfile nscertfile: alias/slapd-ssltest-cert8.db - replace: nskeyfile nskeyfile: alias/slapd-ssltest-key3.db modifying entry cn=encryption,cn=config dn: cn=config Enabling SSL in the Directory Server 15

16 changetype: modify replace: nsslapd-secureport nsslapd-secureport: replace: nsslapd-security nsslapd-security: on modifying entry cn=config In the "cn=rsa,cn=encryption,cn=config" entry, the important attributes are: nsssltoken -- This specifies the token to use to access the certificate database. This indicates which security module to use, and may be different if the server is configured to use the Sun CryptoAccelerator 1000 or some other hardware token. However, for most cases the default of "internal (software)" should be used. nssslpersonalityssl -- This specifies the nickname of the certificate in the certificate database that should be used to accept SSL-based connections to clients. In most cases, the default of "server-cert" should be used. nssslactivation -- This indicates whether this certificate should be considered available for use in accepting SSL-based connections. This must have a value of "on" if SSL is to be enabled. The important attributes of the "cn=encryption,cn=config" entry are: nsssl2 -- This indicates whether the server should accept connections from clients using the SSLv2 protocol. This is older and less secure than SSLv3 and therefore in some environments it may be desirable to disable it, although in others it may be necessary to support older clients. nsssl3 -- This indicates whether the server should accept connections from clients using the SSLv3 protocol. In general, this should be enabled. nssslclientauth -- This specifies the policy that the server should use regarding SSL client authentication. The values that may be provided for this attribute are "off", which specifies that the server will not request client authentication, "allowed", which specifies that the server will request client authentication but will allow connections in which no client certificate is provided, or "required" in which the server will request client authentication and will not allow connections from clients that do not present their own certificates. nscertfile -- This specifies the path and name of the certificate trust store. This path is relative to the server installation root, and the value should be "alias/slapd-{instancename}- cert8.db". Enabling SSL in the Directory Server 16

17 nskeyfile -- This specifies the path and name of the certificate key store. This path is relative to the server installation root, and the value should be "alias/slapd-{instancename}- key3.db". nsssl3ciphers -- This specifies the set of ciphers that will be enabled for SSLv3 communication. By default, all ciphers will be enabled and if that is desirable then no value needs to be provided. Consult the Directory Server Administrator's Guide for details on the available ciphers. The important attributes related to SSL configuration in the "cn=config" entry are: nsslapd-secureport -- This specifies the port number that should be used for accepting SSL-based connections. The standard port for SSL-based LDAP communication is 636, although other ports may be used (for example, if an unprivileged port needs to be used so the server can be started as a non-root user). nsslapd-securelistenhost -- This specifies the address on which the server should listen for SSL-based connections. By default, a value of " " will be used, which means that it will listen on all addresses on the system. If a specific address is specified, then the server will only listen on that address for SSL-based connections. nsslapd-security -- This indicates whether SSL is enabled in the Directory Server. Once the configuration changes have been applied, the server must be restarted to begin listening for SSL-based connections: $../../slapd-config/stop-slapd $../../slapd-config/start-slapd Enter PIN for Internal (Software) Token: password As can be seen, once the server starts with SSL enabled, it needs to have the password to access the private key in the certificate database. In many cases, this is undesirable because it means that the server cannot be automatically be started at system boot or by other external processes like through the administration server. To address this, it is possible to store this password in a file that the server will try to read on startup to determine the password. This password should be placed in a file named slapd-{instancename}-pin.txt under the alias directory under the Directory Server install root, and the contents of this file should be: Internal (Software) Token:password Note that there should not be any spaces on either side of the colon. If this file exists, then the server will read the password from it on startup and if that password is correct then it will not need to interactively request it from the user. Enabling SSL in the Directory Server 17

18 Using ldapsearch to Test SSL Communication If the Directory Server is able to start successfully with SSL enabled, then it should accept any connections from secure clients. However, to actually test this it is necessary to communicate with the server. The ldapsearch command-line utility can be used to accomplish this. The options related to SSL-based communication using server authentication include: -p {port} -- This specifies the port number to use to communicate with the Directory Server. If SSL is to be used, then this should be the secure port of the server. -Z -- This indicates that ldapsearch should use SSL to communicate with the server. -P {certdb} -- This specifies the path to the certificate trust store to use to determine whether to trust the certificate presented by the Directory Server. This should be the path to the cert8.db file that the client should use. In a production environment, the client would have its own copy of the certificate database that had been configured to trust the CA certificate that was used to sign the server's certificate. However, for testing purposes it is possible to use the certificate database provided with the Directory Server. For example: $./ldapsearch -p 636 -Z -P../../alias/slapd-ssltest-cert8.db -b "dc=example,dc=com" -s base "(objectclass=*)" version: 1 dn: dc=example,dc=com dc: example objectclass: top objectclass: domain The access log shows that this connection was in fact over SSL: [15/Aug/2004:21:13: ] conn=1 op=-1 msgid=-1 - fd=24 slot=24 LDAPS connection from to [15/Aug/2004:21:13: ] conn=1 op=-1 msgid=-1 - SSL 128-bit RC4 [15/Aug/2004:21:13: ] conn=1 op=0 msgid=1 - SRCH base="dc=example,dc=com" scope=0 filter="(objectclass=*)" attrs=all [15/Aug/2004:21:13: ] conn=1 op=0 msgid=1 - RESULT err=0 tag=101 nentries=1 etime=0 [15/Aug/2004:21:13: ] conn=1 op=1 msgid=2 - UNBIND [15/Aug/2004:21:13: ] conn=1 op=1 msgid=-1 - closing - U1 [15/Aug/2004:21:13: ] conn=1 op=-1 msgid=-1 - closed. Here, the first two lines provide the information necessary to confirm that the communication was performed over SSL. The first indicates that it was an LDAPS (LDAP over SSL) connection, and the second indicates that the client and server agreed upon using the RC4 cipher with a 128-bit key. The remainder of the log information for the connection will be exactly the same as if the communication had not been secured. Using ldapsearch to Test SSL Communication 18

19 Enabling SSL Client Authentication in the Directory Server Once SSL with server authentication is working, then clients have the ability to communicate securely with the Directory Server. However, the means of authenticating to the server will still be the same as if the connection were not secured (e.g., LDAP simple authentication). However, if the clients have their own certificates, then it is also possible to use those certificates to authenticate to the server using SASL EXTERNAL authentication. In this case, the connection and authentication process will happen as follows: 1. The client will establish a connection to the server and initiates the SSL negotiation. 2. The server sends its certificate to the client, and also requests that the client provide its own certificate. 3. The client determines whether it wants to trust the server's certificate, and if so then the client will send its own certificate to the Directory Server. 4. The server determines whether it wants to trust the client's certificate, and if so then the server and client will complete the SSL negotiation process. 5. The client will send a SASL bind request to the Directory Server with no bind DN, a mechanism of "EXTERNAL", and no SASL credentials. 6. The server will ask the underlying SSL library for information about the certificate that the client used to authenticate. It will then take that information and try to map it to exactly one user in the directory. Optionally, it will also verify that the certificate presented by the client matches a certificate stored in the user's entry. 7. The server will send an LDAP bind response to the client indicating whether the authentication was successful. Based on this sequence of events, there are two elements of the Directory Server configuration that need to be performed: configuring the server so that it will ask the client to provide its own certificate during the SSL negotiation, and configuring the server so that it can uniquely map that certificate to a user. The first of these is the easiest, and if SSL is already enabled in the Directory Server then it will likely already be done. Whether or not the server requests a certificate from the client is controlled by the nssslclientauth attribute of the "cn=encryption,cn=config" entry. If this has a value of "allowed" then the server will request that the client provide its own certificate, but will not abort the connection if the client does not provide one (although it will not be possible to perform SASL EXTERNAL authentication in this case). If this entry has a value of "required", then the server will request that the client provide its own certificate and will not accept the connection if the client does not Enabling SSL Client Authentication in the Directory Server 19

20 do so. If this entry has a value of "off", then the server will not request a client certificate and therefore SASL EXTERNAL authentication will never be allowed. Assuming that the client did provide its own certificate to the server, then the server will need to map the information in that certificate to exactly one user entry in the directory. The way that this is done is controlled by the information in the shared/config/certmap.conf configuration file under the Directory Server install root. The format of this configuration file is documented in the Administration Server Administration Guide (not the Directory Server Administration Guide), but the primary options available are as follows: Any line starting with an octothorpe (#) character is a comment and is ignored by the parser. The first non-comment line should start with the word "certmap" to indicate that it defines a set of certificate mapping criteria, and that word should then be followed by the name of the mapping and the subject of the issuer certificate to which this mapping should apply. This makes it possible to perform different kinds of mapping for each CA certificate that might be used to sign client certificates. The value "default" specifies the mapping that should be used if the client certificate was not signed by any of the other listed issuers. Each property associated with this certificate mapping policy should be prefixed by the name of the mapping followed by a colon. The DNComps configuration property makes it possible to tell the server where to start looking in the directory for the user's entry. For example, if you specify a value of "o, c" for this property, then the server will take the values of the o and c attributes from the certificate subject and use them as the base DN for the search to find the appropriate user entry. While this is useful if the certificate subject contains the same structure as the user's entry in the directory, this is rarely the case in modern deployments and therefore may not be suitable. Therefore, in most cases, it would be better to have a DNComps property present but with no value, which means that the certificate mapping process should search the entire directory for possible matches. If the DNComps property is not there at all (including if it is commented out), then the server will assume that the subject of the certificate is the same as the DN of the user's entry in the directory, which will not be the case in most deployments. The FilterComps configuration property makes it possible to construct an LDAP search filter to use to find the matching user entry based on attributes in the certificate subject. For example, if the subject of the certificate contains the user's address (which is very common for client certificates), then that would be a good choice. The following attributes are supported for use in the FilterComps property: cn -- The value of the cn attribute of the certificate's subject should match the value of the cn attribute of the user's entry. ou -- The value of the ou attribute of the certificate's subject should match the value of the ou attribute of the user's entry. o -- The value of the o attribute of the certificate's subject should match the value of the o attribute of the user's entry. Enabling SSL Client Authentication in the Directory Server 20

21 c -- The value of the c attribute of the certificate's subject should match the value of the c attribute of the user's entry. l -- The value of the l attribute of the certificate's subject should match the value of the l attribute of the user's entry. st -- The value of the st attribute of the certificate's subject should match the value of the st attribute of the user's entry. uid -- The value of the uid attribute of the certificate's subject should match the value of the uid attribute of the user's entry. Note, however, that the use of uid as an attribute in certificate subjects has been deprecated, so it may not be likely to appear in the subject. e or mail -- The value of the e attribute of the certificate's subject should match the value of the mail attribute in the user's entry. Note that either e or mail can be used in the FilterComps definition but not both. The CmapLdapAttr configuration property specifies the name of an attribute in the user's entry that should hold the subject(s) of any certificate(s) that the user might use to try to authenticate to the Directory Server. This can be any attribute (including custom attributes), but it is strongly recommended that it be given a DN syntax and that it be indexed for equality. This is probably the best choice if the certificate's subject does not have sufficient information to uniquely map the certificate to a user's entry with either the DNComps or FilterComps properties. The VerifyCert configuration property indicates whether the certificate that the client presented to the certificate should be matched against a certificate in the user's entry once a unique mapping has been established. If this is set to "on", then the user's entry must have the certificate presented by the client as one of the values of the usercertificate attribute in order for the authentication to be successful. If it is set to "off", then it will be considered sufficient for the user's certificate to map to a unique entry in the directory and that entry may or may not contain any certificates and even if it does then the certificate presented by the client may or may not match one of them. It is slightly more expensive to perform this comparison, but it does offer an additional layer of protection in the case that a malicious user is somehow able to generate a certificate with an arbitrary subject that will be trusted by the Directory Server (e.g., if that user was able to obtain the private key for the CA certificate). The Library and InitFn properties can be used to specify a custom external library that will be invoked to perform this mapping. Using this capability is outside the scope of this document. For example, consider the case in which the default mapping should attempt to match the address from the certificate subject to a user's entry anywhere in the directory, and once that mapping has been established then the presented certificate should be verified against a certificate stored in the user's entry. A valid certmap.conf file that could be used to achieve this might look like the following: certmap default default:dncomps default:filtercomps default:verifycert default e on Enabling SSL Client Authentication in the Directory Server 21

22 Once this configuration file has been updated, it is necessary to restart the Directory Server for the change to take effect. Also note that if the VerifyCert option has been enabled, user entries must be updated to include any certificates that might be used in the authentication process. The method for doing this will be described in the next section. Enabling SSL Client Authentication in the Directory Server 22

23 Using ldapsearch to Test SSL Client Authentication Once the Directory Server has been configured to allow for SSL client authentication via SASL EXTERNAL, we can verify that it is actually working by using ldapsearch to test it. However, this process involves a few steps, including: Add a new user entry to the directory that will be used for the authentication. Create a new certificate database for that user and use it to request a client certificate. Have that certificate signed by an external CA that is trusted by the Directory Server. Import the signed certificate and the CA certificate into the client's certificate database. Add the signed certificate to the user's entry in the directory. Use ldapsearch to authenticate as that user via SASL EXTERNAL. The first step in this process is very simple. Simply use ldapmodify to add a new user to the directory. We will assume that the certmap.conf file specified in the previous section is in use, and therefore it is necessary to ensure that the user entry added has an address. However, since we will be using SASL EXTERNAL authentication, no password is necessary: $./ldapmodify -D "cn=directory Manager" -w password dn: uid=test.user,ou=people,dc=example,dc=com changetype: add objectclass: top objectclass: person objectclass: organizationalperson objectclass: inetorgperson uid: test.user givenname: Test sn: User cn: Test User mail: test.user@example.com adding entry uid=test.user,ou=people,dc=example,dc=com Next, we can create a new certificate database for the user and use it to generate a new certificate request. Note that in this case we will use a different certificate database than the one used by the Directory Server, since real-world clients would each have their own certificate databases. The process used to do this is as follows: $ mkdir /tmp/clientcertdb $./certutil -N -d /tmp/clientcertdb In order to finish creating your database, you must enter a password which will be used to encrypt this key and any future keys. The password must be at least 8 characters long, and must contain at least one non-alphabetic character. Enter new password: password Re-enter password: password Using ldapsearch to Test SSL Client Authentication 23

24 $./certutil -R -s Corp,l=Austin,st=Texas,c=US" -o /tmp/userrequest.der -d /tmp/clientcertdb A random seed must be generated that will be used in the creation of your key. One of the easiest ways to create a random seed is to use the timing of keystrokes on a keyboard. To begin, type keys on the keyboard until this progress meter is full. DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD! Continue typing until the progress meter is full: ************************************************************ Finished. Press enter to continue: Enter Password or Pin for "NSS Certificate DB": password Generating key. This may take a few moments... Note that the certificate request includes the address in the subject. This is necessary to ensure that the certificate mapping will succeed. At this point, the certificate request has been generated and written to /tmp/usercert.der and we can send it off to an external CA to be signed. In this case, we will use the CA certificate that we generated in a previous section: $./certutil -C -c ca-cert -i /tmp/userrequest.der -o /tmp/usercert.der -v 12 -d cacertdb -P "ca-" SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish SSL Client 1 - SSL Server 2 - S/MIME 3 - Object Signing 4 - Reserved for futuer use 5 - SSL CA 6 - S/MIME CA 7 - Object Signing CA Other to finish 9 Is this a critical extension [y/n]? n Enter Password or Pin for "NSS Certificate DB": password As can be seen here, the signing process made sure to include the SSL client extension in the certificate. If this is not done, then the server will not accept the client's certificate. Once the certificate has been signed, then the client can import that certificate and the CA certificate into its certificate database: Using ldapsearch to Test SSL Client Authentication 24

25 $./certutil -A -n client-cert -t Pu -i /tmp/usercert.der -d /tmp/clientcertdb $./certutil -A -n ca-cert -t CT -i /tmp/cacert.txt -a -d /tmp/clientcertdb Next, since VerifyCert is on, we need to make sure that certificate is present in the user's entry in the directory. It should be placed in the usercertificate attribute, and as per RFC 2252 it should make sure to use the binary encoding (i.e,. usercertificate;binary). Since the binary certificate is already available as a file on the filesystem, then we can simply tell ldapmodify where that certificate is using the -b option to indicate that any attribute value stating with a forward slash should be interpreted as the name of the file from which to retrieve the value: $./ldapmodify -D 'cn=directory Manager' -w password -b dn: uid=test.user,ou=people,dc=example,dc=com changetype: modify add: usercertificate;binary usercertificate;binary: /tmp/usercert.der modifying entry uid=test.user,ou=people,dc=example,dc=com Finally, now that all the pieces are in place, it is possible to use ldapsearch to use the new client certificate to authenticate to the Directory Server using SASL EXTERNAL. The important options to provide to ldapsearch in this case include: -p {port} -- This specifies the port to use to communicate with the Directory Server. Since the communication will be over SSL, then this should be the server's secure port. -Z -- This indicates that the communication with the Directory Server should be performed over SSL. -P {certdb} -- This specifies the path to the certificate trust store (i.e., the cert8.db file) that the client should use to determine whether to trust the certificate presented by the Directory Server. -K {keydb} -- This specifies the path to the certificate key store (i.e., the key3.db file) that contains the private key for the certificate that the client needs to present to the server for SSL client authentication. -N {nickname} -- This specifies the nickname for the certificate in the client's certificate database that should be used for client authentication. -W {certpassword} -- This specifies the password needed to access the private key information in the client's certificate database. An example of using ldapsearch to authenticate using SASL EXTERNAL is as follows: Using ldapsearch to Test SSL Client Authentication 25