Messaging and Directory Server software used around the world in the Government, Military, Aviation and Commercial sectors.
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.
Tasks
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
Using Self-Signed Certificates
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 code) [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
of cn 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.
Configuring the DSA
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.
Creating a CA and Server Certificates
CAs can be built using the openssl tool. OpenSSL-based CAs require
a particular directory structure. This is configured in the openssl.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 code) [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.
Getting a certificate from Verisign
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 code) [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 []:your.name@example.com 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.
Configuring OpenSSL clients
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.
Configuring Microsoft clients
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-encoded 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:
Configuring Mac OS X clients
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, choose File>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:
