Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Guide 

Appendix A   
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 A-1 covers items that must be completed before attempting to use the Sun Crypto Accelerator board to enhance SSL connection performance.

Table A-1 Prerequisites to Using the Board 



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 the Java Enterprise System Installation Guide 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 Chapter 11, "Managing Authentication and Encryption," both for a discussion of the SSL protocol itself and of SSL certificates, and for instructions on how to use the protocol with Sun Java System servers supporting administration through the Server Console.

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.
  2. $ CryptoPath/bin/secadm

    The default CryptoPath is /opt/SUNWconn/crypto.

  3. Create a realm for the token.
  4. secadm> create realm=dsrealm
    System Administrator Login Required
    Login: super-user
    Realm dsrealm created successfully.

  5. Set the realm in which to create a user.
  6. secadm> set realm=dsrealm
    secadm{dsrealm}> su
    System Administrator Login Required
    Login: super-user

  7. Create the user nobody to use the default slot, supplying the password used when restarting Directory Server with SSL configured.
  8. 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.
  2. $ set LD_LIBRARY_PATH=ServerRoot/lib ; export LD_LIBRARY_PATH

  3. Create a security module database if none exists.
  4. $ cd ServerRoot/shared/bin
    $ ./modutil -create -dbdir ../../alias -dbprefix "slapd-serverID"

  5. Add the external security module to the security module database.
  6. $ ./modutil -add "Crypto Mod" -dbdir ../../alias -nocertdb \
    -libfile CryptoPath/lib/ \
    -mechanisms "RSA:DSA:RC4:DES" -dbprefix "slapd-serverID"

    The default CryptoPath is /opt/SUNWconn/crypto.

  7. List the security modules to ensure the add succeeded.
  8. $ ./modutil -list -dbdir ../../alias -dbprefix "slapd-serverID"

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

  9. Make the external security module the default for RSA, DSA, RC4, and DES.
  10. $ ./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 A-1. Perform the following steps to import the certificates.

  1. Import the server certificate .p12 file.
  2. $ 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

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

  5. List the certificates associated with the token to ensure the imports succeeded.
  6. $ ./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.
  2. Code Example A-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,







    replace: nsCertfile

    nsCertfile: alias/slapd-serverID-cert8.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

    1This nickname is contained in the certificate for Directory Server.

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

  3. Apply the modifications to change Directory Server configuration.
  4. $ 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.

  5. Restart the Directory Server in secure mode.
  6. $ 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 Java System Administration Server and client applications to access Directory Server over SSL through that port. Refer to Chapter 11, "Managing Authentication and Encryption" for details.

Previous      Contents      Index      Next     

Part No: 817-7613-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.