Appendix B      Using the Sun Crypto Accelerator Board

This appendix provides instructions on using a Sun Crypto Accelerator board with Directory Server to enhance performance for connections using the Secure Sockets Layer (SSL) protocol with certificate-based authentication.

Before You Start

---

Table B-1 covers items that must be completed before attempting to use the Sun Crypto Accelerator board to enhance SSL connection performance.

Table B-1    Prerequisites to Using the Board 

Prerequisite	Remarks
Board installation	Refer to the product documentation provided for the board when installing the hardware, drivers, patches, and administrative utilities on the host.
Directory Server installation	Refer to Chapter 1 "Installing Sun ONE Directory Server," for instructions.
Server cert. (PKCS#12 format)	Obtain a server certificate for Directory Server as a .p12 file
CA cert. (PEM format)	Obtain the CA certificate for your Certificate Authority (CA) as a Privacy Enhanced Mail (PEM) format file.

Refer to Sun ONE Server Console Server Management Guide both for a discussion of the SSL protocol itself and of SSL certificates, and for instructions on how to use the protocol with Sun ONE servers supporting Sun ONE Server Console administration.

Creating a Token

---

Directory Server uses a token and password to access the appropriate cryptographic key material on the accelerator board. The token takes the form user@realm, where user is a user in terms of the accelerator board — an owner of cryptographic keying material — and realm is a realm in terms of the accelerator board — a logical partition of users and their keying material. The accelerator board user need not bear any relation to a user account on the system. It is specific to the board. Refer to the accelerator board product documentation for further explanation of users and realms.

You may create a user and realm for the token using the secadm(1M) utility provided for use with the board. The accelerator board also permits creation of multiple slots to manage tokens for multiple applications. It is assumed here that for performance reasons, you dedicate the host to Directory Server and therefore use only one slot, the default. Refer to the accelerator board product documentation for details on using the board with multiple software applications.

Perform the following steps to create the user and realm for a token to access the default slot.

1. Start the secadm utility.

$ CryptoPath/bin/secadm

The default CryptoPath is /opt/SUNWconn/crypto.

2. Create a realm for the token.

secadm> create realm=dsrealm
System Administrator Login Required
Login: super-user
Password:
Realm dsrealm created successfully.

3. Set the realm in which to create a user.

secadm> set realm=dsrealm
secadm{dsrealm}> su
System Administrator Login Required
Login: super-user
Password:
secadm{root@dsrealm}#

4. Create the user nobody to use the default slot, supplying the password used when restarting Directory Server with SSL configured.

secadm{root@dsrealm}# create user=nobody
Initial password: password
Confirm password: password
User nobody created successfully.
secadm{root@dsrealm}# exit

At this point you have created the user and realm for the token nobody@dsrealm, and supplied a password used when restarting Directory Server.

Generating Bindings for the Board

---

Bindings for the accelerator board take the form of an external security module you generate so Directory Server may bind to the board. Perform the following steps to generate a binding between the external security module and Directory Server certificate database with support for several SSL algorithms.

1. Set LD_LIBRARY_PATH before using modutil.

$ set LD_LIBRARY_PATH=ServerRoot/lib ; export LD_LIBRARY_PATH

2. Create a security module database if none exists.

$ cd ServerRoot/shared/bin
$ ./modutil -create -dbdir ../../alias -dbprefix "slapd-serverID"

3. Add the external security module to the security module database.

$ ./modutil -add "Crypto Mod" -dbdir ../../alias -nocertdb \
-libfile CryptoPath/lib/libpkcs11.so \
-mechanisms "RSA:DSA:RC4:DES" -dbprefix "slapd-serverID"

The default CryptoPath is /opt/SUNWconn/crypto.

4. List the security modules to ensure the add succeeded.

$ ./modutil -list -dbdir ../../alias -dbprefix "slapd-serverID"

You should see an entry for the Crypto Mod you added in Step 3.

5. Make the external security module the default for RSA, DSA, RC4, and DES.

$ ./modutil -default "Crypto Mod" -dbdir ../../alias \
-mechanisms "RSA:DSA:RC4:DES" -dbprefix "slapd-serverID"

This should successfully change the default security module.

At this point you have generated bindings for the accelerator board and may import certificates.

Importing Certificates

---

Before configuring SSL, you must import the server and CA certificates you obtained as described in Table B-1. Perform the following steps to import the certificates.

1. Import the server certificate .p12 file.

$ cd ServerRoot/shared/bin
$ ./pk12util -i ServerCert.p12 -d ../../alias -P "slapd-serverID" \
-h "nobody@dsrealm"
Enter Password or Pin for "nobody@dsrealm": password
Enter Password for PKCS12 file: password

2. Import the CA certificate.

$ ./certutil -A -n "Crypto CA Cert" -t CT -i CACert.txt \
-d ../../alias -P "slapd-serverID" -h "nobody@dsrealm"

3. List the certificates associated with the token to ensure the imports succeeded.

$ ./certutil -L -d ../../alias -P "slapd-serverID" \
-h "nobody@dsrealm"

You should see entries for the certificates you added in Step 1 and Step 2.

At this point you have imported the certificates and may configure Directory Server to listen for SSL connections.

Configuring SSL

---

Using the token and password you created, bindings you generated between the external security module and Directory Server certificate database, and the certificates you imported, you may configure Directory Server to start in secure mode. Perform these steps to configure SSL and restart Directory Server in secure mode.

1. Create a file, ssl.ldif, of modifications to change SSL related Directory Server configuration entries.



---

Code Example B-1    Modifications to Activate SSL Using the Board (ssl.ldif)

dn: cn=RSA,cn=encryption,cn=config

changetype: add

objectclass: top

objectclass: nsEncryptionModule

cn: RSA

nsSSLToken: nobody@dsrealm

nsSSLPersonalitySSL: ServerCertNickname1

nsSSLActivation: on

dn: cn=encryption,cn=config

changetype: modify

replace: nsSSL3

nsSSL3: on

-

replace: nsSSLClientAuth

nsSSLClientAuth: allowed

-

replace: nsSSL3Ciphers

nsSSL3Ciphers: -rsa_null_md5,+rsa_rc4_128_md5,+rsa_rc4_40_md5,

+rsa_rc2_40_md5,+rsa_des_sha,+rsa_fips_des_sha,+rsa_3des_sha,

+rsa_fips_3des_sha,+fortezza,+fortezza_rc4_128_sha,

+fortezza_null,+tls_rsa_export1024_with_rc4_56_sha,

+tls_rsa_export1024_with_rc4_56_sha,

+tls_rsa_export1024_with_des_cbc_sha

-

replace: nsCertfile

nsCertfile: alias/slapd-serverID-cert7.db

-

replace: nsKeyFile

nsKeyFile: alias/slapd-serverID-key3.db

dn: cn=config

changetype: modify

replace: nsslapd-secureport

nsslapd-secureport: port

-

replace: nsslapd-security

nsslapd-security: on

Here port, the value of nsslapd-secureport, is the port on which Directory Server listens for SSL connections once started in secure mode.

2. Apply the modifications to change Directory Server configuration.

$ ldapmodify -p currPort -D "cn=directory manager" -w password -f ssl.ldif

where currPort is the number of the port on which the Directory Server currently listens for client requests.

3. Restart the Directory Server in secure mode.

$ ServerRoot/slapd-serverID/restart-slapd
Enter PIN for nobody@dsrealm: password

Here password is the user password for nobody provided when the token nobody@dsrealm was created.

At this point, Directory Server listens for SSL traffic over the port you specified. You may configure Sun ONE Administration Server and client applications to access Directory Server over SSL through that port. Refer to the Sun ONE Directory Server Administration Guide for details.