M-Vault has long been able to use SSL with LDAP connections, however configuring SSL can be awkward. This technical note describes how to use simple freely available tools (which are also provided in R10.2 and later) to:
- create a certificate authority and a server certificate
- request a server certificate from Verisign
- configure a DSA to support SSL
- configure OpenSSL clients
- configure Microsoft clients
- configure Mac OS X clients
Before describing these tasks, this note will briefly describe certificates and how they are used in SSL.
Certificates and SSL
SSL uses standard X.509 certificates. X.509 certificates have a subject (a DN), an issuer (another DN), a validity period (two dates and times), and use a pair of cryptographic algorithms. The most commonly used cryptographic algorithms used with SSL are RSA with SHA-1.
If a certificate has the same subject as issuer, it is called a self-signed certificate. These are not very secure because the receiver of the certificate must implicitly trust that the user of the certificate is the the entity it claims it is. However it is sometimes useful to create these when testing or in a limited environment.
Normally though, the issuer is not the same as the subject, and then the issuer is called a certification authority, or CA. These certificates are more useful - the same CA can be used to issue multiple certificates and it thus becomes possible to configure client software to "trust" all certificates signed by particular CAs.
You can create your own CA, but this will require that you configure all your SSL clients with knowledge of it. Alternatively there are a number of widely recognized commercial CAs (e.g. Verisign) that all SSL clients already understand, so it can be useful to use certificates signed by them instead.
When using SSL, it is normal for servers to have an SSL certificate and key. When clients connect to an SSL server, the server supplies the client with its certificate and the client must somehow verify that the server's certificate is valid. This allows the client to confirm that it is communicating with the correct server.
It is also possible for clients to have certificates and keys, and to supply the server with them. The server may then be configured to verify that the client's certificate is valid.
Finally, there are two modes in which a server "listens" to SSL. The first mode is that it listens on a different TCP port, and all connections on that port must use SSL. This is the LDAPS port, and the default port used by LDAPS in 636. (Compare with HTTP and HTTPS in web servers.)
The second way to use SSL is on the existing LDAP port. This is the preferred standard way to use SSL, and it works by the LDAP client sending the server a special LDAP message which converts the open LDAP connection on the plain LDAP port into a secure SSL connection on the same port. The special LDAP message is called Start TLS, and uses the standardized version of SSL, called TLS.
The following three sections will describe how to use the provided openssl command-line tool to configure SSL in different scenarios. The examples given all use Linux, but they will also work on Windows and Solaris. Long command lines are split for display purposes using a single \, which should not be entered.
- Using self-signed certificates
- Creating a CA and using its certificates
- Obtaining a commercial certificate from Verisign
As noted above, self-signed certificates are not very secure. However they can be very useful in a restricted environment, because it is relatively easy to configure clients and servers to use them. There is less that can go wrong, which makes using them sensible for testing.
Generating the certificate
Generation of a self-signed certificate is straightforward. The first step is to create a certificate signing request, which involves generating a public/private key pair. Create an empty directory, move into it and type the text in bold:
% openssl req -new -nodes -keyout server.key > server.csr
Generating a 1024 bit RSA private key
writing new private key to 'server.key'
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter em) [AU]:US
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) :.
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example
Organizational Unit Name (eg, section) :.
Common Name (eg, YOUR name) :ldap.example.com
Email Address :.
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password :.
An optional company name :.
Most of the interaction involves entering the subject DN. Different forms of DNs are possible, but require that the openssl.cnf file be edited. To omit a particular RDN enter '.' as suggested. When used with SSL, certificates must have the least significant RDN ofcn set to the hostname that clients use to contact the server, e.g. cn=ldap.example.com.
This command will result in an unprotected (because of the -nodes option) key being written to server.key, and a certificate signing request (which includes the public key) being written to server.csr.
The next step is to use the private key to sign the certificate signing request. Type:
% openssl x509 -in server.csr -out server.pem \ -req -signkey server.key -days 365 Signature ok subject=/C=US/O=Example/CN=ldap.example.com Getting Private key
The directory should now contain a file called server.pem, which is the server's certificate.
Exporting the certificate and key for the DSA
The DSA needs to read the SSL certificate and private key from a single file. This file is in a standard format called PKCS#12, and it is usually encrypted using a password.
To create the PKCS#12 file, type:
% openssl pkcs12 -export -in server.pem -inkey server.key \ -out server.p12 Enter Export Password:dsasecret Verifying - Enter Export Password:dsasecret
The typed password will not be displayed on the screen.
Locate the DSA's configuration path and create an ssl directory inside it.
% mkdir /var/isode/dsa-db/ssl
Copy the PKCS#12 file containing the server's certificate and key into this new directory.
% cp server.p12 /var/isode/dsa-db/ssl/id.p12
You then need to tell the DSA what the password is to decrypt the above file. The password is stored in a file called key.pphr in the same directory as the id.p12 file:
% echo -n "dsasecret" > /var/isode/dsa-db/ssl/key.pphr
The key.pphr file should have a maximum of one line; additional blank lines will prevent the DSA from decrypting the PKCS#12 file. You should make sure that only the DSA process is able to read this file, using the standard OS access control commands (e.g. chmod on Linux and Solaris.)
To tell the DSA to use the certificate and key, use EDM and open the Directory Server's properties. Select the "TLS suites" tab and enter "ssl" in the identity path. Select the appropriate cipher suites on the "Excluded" list and copy them to the "Included" list using the arrow button. The appropriate cipher suites list normally only contains RSA_WITH_3DES_EDE_CBC_SHA, as this is the best combination of strong encryption algorithms in common use.
If you click the "OK" button a notice should appear saying that "TLS/SSL is now operational." If it does not, then the most likely problem is that key.pphr could not be read, or had the wrong password. The dsap.log file may contain additional error messages.
This allows the DSA to support the LDAPv3 Start TLS extended operation. To allow users to connect using SSL on a different port, i.e. using LDAPS, open the Directory Server's properties and change the Presentation address in the General tab to include an LDAPS address. Modifying a DSA's presentation address requires that the DSA be restarted.
CAs can be built using the openssl tool. OpenSSL-based CAs require a particular directory structure. This is configured in theopenssl.cnf file, but the default structure uses a top-level directory called demoCA. The first step is to create this structure, by typing:
% mkdir demoCA demoCA/certs demoCA/crl demoCA/requests % mkdir demoCA/newcerts demoCA/keys % touch demoCA/index.txt % echo '01' > demoCA/serial
The last two lines create an empty file called index.txt, and a text file called serial containing the characters 01. (Serial numbers are embedded in each certificate.)
The next stage is to create a self-signed certificate for the CA. Create the certificate signing request (which generates an encrypted private key):
% openssl req -new -keyout \ demoCA/keys/ca.key > demoCA/requests/ca.csr Generating a 1024 bit RSA private key ..........................................................++++++ ..++++++ writing new private key to 'demoCA/keys/ca.key' Enter PEM pass phrase:casecret Verifying - Enter PEM pass phrase:casecret ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter em) [AU]:US State or Province Name (full name) [Some-State]:. Locality Name (eg, city) :. Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example Organizational Unit Name (eg, section) :. Common Name (eg, YOUR name) :CA Email Address :. Please enter the following 'extra' attributes to be sent with your certificate request A challenge password :. An optional company name :.
As this is not an SSL certificate, the least significant RDN of cn doesn't have to be set to anything particular. Don't forget the PEM pass phrase used to protect the CA's key!
Then use the CA's private key to sign the certificate signing request. Type:
% openssl x509 -in demoCA/requests/ca.csr -out demoCA/certs/ca.pem \ -req -signkey demoCA/keys/ca.key -days 365 Signature ok subject=/C=US/O=Example/CN=CA Getting Private key Enter pass phrase for demoCA/keys/ca.key:casecret
Use the pass phrase entered when you created the certificate signing request, e.g. "casecret".
You now have a CA. You can now create additional certificate signing requests/private keys for users and servers, and sign them with the CA's key.
To create certificates signed by this CA, for example for a DSA using SSL, type:
% openssl req -new -nodes -keyout demoCA/keys/server.key \ -out demoCA/requests/server.csr
Make sure the cn value for the key is the fully qualified name of the DSA machine, eg ldap.example.com. Sign the DSA's certificate signing request using the CA's key by typing:
% openssl ca -policy policy_anything -cert demoCA/certs/ca.pem \ -in demoCA/requests/server.csr -keyfile demoCA/keys/ca.key \ -days 100 -out demoCA/certs/server.pem Using configuration from /etc/isode/ssl/openssl.cnf Enter pass phrase for demoCA/keys/ca.key:casecret Check that the request matches the signature Signature ok Certificate Details: Serial Number: 1 (0x1) Validity Not Before: Mar 23 13:07:41 2004 GMT Not After : Jul 1 13:07:41 2004 GMT Subject: countryName = US organizationName = Example commonName = ldap.example.com X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: 98:3E:25:BA:F6:82:5D:3C:EB:81:1A:81:D5:9B:73:6F:87:4B:1A:F3 X509v3 Authority Key Identifier: DirName:/C=US/O=Example/CN=CA serial:00 Certificate is to be certified until Jul 1 13:07:41 2004 GMT (100 days) Sign the certificate? [y/n]:y 1 out of 1 certificate requests certified, commit? [y/n]y Write out database with 1 new entries Data Base Updated
The last step is to collect the certificate and private key into a file that is configured into the DSA. The file required uses the PKCS#12 format, and it can be generated by typing:
% openssl pkcs12 -export -in demoCA/certs/server.pem \ -out server.p12 -inkey demoCA/keys/server.key
It will prompt for a password which is used to encrypt the file. It is also possible to include the CA's certificate in the PKCS#12 file, which is necessary for some kinds of applications. To do that, generate the PKCS#12 file this way instead:
% openssl pkcs12 -export -out server.p12 -descert \ -in demoCA/certs/server.pem -inkey demoCA/keys/server.key \ -certfile demoCA/certs/ca.pem
Now install the server.p12 file into the DSA, as described earlier.
You should consider purchasing a certificate from Verisign (or some other well-known CA) if you want to allow clients to be able to verify your server's SSL certificate without any additional configuration.
To obtain a certificate from Verisign, you firstly need to create a certificate signing request and private key.
% openssl req -new -nodes -keyout server.key > server.csr Generating a 1024 bit RSA private key .......................++++++ ........................++++++ writing new private key to 'server.key' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter em) [AU]:US State or Province Name (full name) [Some-State]:California Locality Name (eg, city) :San Francisco Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example Organizational Unit Name (eg, section) :Support Common Name (eg, YOUR name) :ldap.example.com Email Address :firstname.lastname@example.org Please enter the following 'extra' attributes to be sent with your certificate request A challenge password :. An optional company name :.
Note that Verisign require you to enter all the RDNs in the standard OpenSSL DN template.
To obtain a signed certificate from Verisign requires that you paste the contents of the server.csr file into a form on Verisign's web site, and pay Verisign several hundred US dollars.
Clients using OpenSSL client libraries will usually try to verify certificates in two ways. The first way is by having knowledge of the server's certificate. This is simply the server.pem file generated above.
The second way is to verify the certificate is signed by a trusted CA. OpenSSL stores all the trusted CA certificates in a single directory, e.g. /usr/share/ssl/CA. Add the CA's certificate (ca.pem) to this directory and then type:
% ln -s ca.pem `openssl x509 -hash -noout < ca.pem`.0
This creates a symbolic link to the certificate, named using the hash of the certificate's subject name.
Clients that use Microsoft SSL libraries will try to verify the server's SSL certificate using the Windows certificate store. The Windows certificate store can be managed by the Microsoft Management Console (MMC) Certificates snap-in. Using this snap-in, you can import either the server's certificate, or the CA's certificate.
To import the server's certificate, you need to convert it into a DER-enemd format using openssl. For example:
% openssl x509 -in demoCA/certs/server.pem -outform DER -out server.crt
Now use the Certificates snap-in and Import the server.crt file. Make sure that the snap-in adds the certificate into the Trusted Publishers store.
If you want to import the CA's certificate instead, and have your clients trust any certificate signed by that CA, then import the CA's certificate instead. You need to convert it first into DER:
% openssl x509 -in demoCA/certs/ca.pem -outform DER -out ca.crt
Use the Certificates snap-in and import the ca.crt file. Make sure that the snap-in adds the certificate into the Trusted Root Certificate Authorities store. You will be asked to verify that you really want to add this certificate to the root store.
Once a certificate has been added to the store, its details can be viewed by double-clicking on it in MMC:
Clients on Mac OS X trust certificates stored in a system-wide keychain called X509Anchors. To add a certificate to this keychain, an administrative user must run Keychain Access.app and use File>Add Keychain... to add/System/Library/Keychains/X509Anchors to their list of viewed keychains. Then with the X509Anchors keychain selected, chooseFile>Import... to import the public key (in PEM format), e.g. demoCA/certs/ca.pem. The administrator will be prompted for their username and password, in order to write to the keychain.
Once a certificate has been added to X509Anchors, its details can be viewed by selecting it in the main view: