Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide

Managing Certificates

This section describes how to manage SSL certificates in Directory Server.

To run SSL on Directory Server, you must either use a self-signed certificate or a Public Key Infrastructure (PKI) solution.

The PKI solution involves an external Certificate Authority (CA). For a PKI solution, you need a CA-signed server certificate, which contains both a public key and a private key. This certificate is specific to one Directory Server. You also need a trusted CA certificate, which contains a public key. The trusted CA certificate ensures that all server certificates from your CA are trusted. This certificate is sometimes called a CA root key or root certificate.


Note –

If you are using certificates for test purposes, you probably want to use self-signed certificates. However, in production, using self-signed certificates is not very secure. In production, use trusted Certificate Authority (CA) certificates.


The procedures in this section use the dsadm and dsconf commands. For information about these commands, see the dsadm(1M) and dsconf(1M) man pages.

This section provides the following information about configuring certificates on Directory Server:

ProcedureTo View the Default Self-Signed Certificate

When a Directory Server instance is first created, it contains a default self-signed certificate. A self-signed certificate is a public and private key pair, where the public key is signed by the private key. A self-signed certificate is valid for three months.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To view the default self-signed certificate, use this command:


    $ dsadm show-cert instance-path defaultCert

ProcedureTo Manage Self-Signed Certificates

When you create a Directory Server instance, a default self-signed certificate is automatically provided.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To create a self-signed certificate with non-default settings, use this command:


    $ dsadm add-selfsign-cert instance-path cert-alias
    

    Where cert-alias is a name that you provide to identify your certificate.

    To see all the options for this command, see the dsadm(1M) man page or the command-line help:.


    $ dsadm add-selfsign-cert --help
  2. When your self-signed certificate expires, stop the server instance and renew the certificate.


    $ dsadm stop instance-path
    $ dsadm renew-selfsign-cert instance-path cert-alias
    
  3. Restart the server instance.


    $ dsadm start instance-path
    

ProcedureTo Request a CA-Signed Server Certificate

This procedure explains how to request and install a CA-signed server certificate for use with Directory Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Generate a CA-signed server certificate request.


    $ dsadm request-cert [-W cert-pwd-file] {-S DN | --name name [--org org] \
      [--org-unit org-unit] [--city city] [--state state] [--country country]} \
      [-o output-file] [-F format] instance-path
    

    For example, to request a CA-signed server certificate for the Example company, use this command:


    $ dsadm request-cert --name host1 --org Example --org-unit Marketing \
     -o my_cert_request_file /local/ds

    In order to completely identify the server, Certificate Authorities might require all of the attributes that are shown in this example. For a description of each attribute, see the dsadm(1M) man page.

    When you request a certificate by using dsadm request-cert, the resulting certificate request is a binary certificate request unless you specify ASCII as output format. If you specify ASCII, the resulting certificate request is a PKCS #10 certificate request in PEM format. PEM is the Privacy Enhanced Mail format specified by RFCs 1421 through 1424 (http://www.ietf.org/rfc/rfc1421.txt) and is used to represent a base64-encoded certificate request in US-ASCII characters. The content of the request looks similar to the following example:


    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIBrjCCARcCAQAwbjELMAkGA1UBhMCVXMxEzARBgNVBAgTCkNBElGT1JOSUExLD
    AqBgVBAoTI25ldHNjYXBlIGNvb11bmljYXRpb25zIGNvcnBvcmF0aWuMRwwGgYDV
    QQDExNtZWxsb24umV0c2NhcGUuY29tMIGfMA0GCSqGSIb3DQEBAUAA4GNADCBiQK
    BgCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7u0EfgSLR0f+K41eNqqWRftGR83e
    mqPLDOf0ZLTLjVGJaHJn4l1gG+JDf/n/zMyahxtV7+T8GOFFigFfuxJaxMjr2j7I
    vELlxQ4IfZgwqCm4qQecv3G+N9YdbjveMVXW0v4XwIDAQABAAwDQYJKoZIhvcNAQ
    EEBQADgYEAZyZAm8UmP9PQYwNy4Pmypk79t2nvzKbwKVb97G+MT/gw1pLRsuBoKi
    nMfLgKp1Q38K5Py2VGW1E47/rhm3yVQrIiwV+Z8Lcc=
    -----END NEW CERTIFICATE REQUEST-----
  2. Transmit the certificate request to your Certificate Authority, according to its procedures.

    The process for obtaining your Certificate Authority certificate depends on the certificate authority that you use. Some commercial CAs provide a website that allows you to automatically download the certificate. Other CAs will send it to you in email upon request.

    After you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, the CA might only take a day or two to respond to your request. If your selected CA is external to your company, the CA could take several weeks to respond to your request.

  3. Save the certificate that you receive from the Certificate Authority.

    Back up your certificates in a safe location. If you ever lose the certificates, you can reinstall them by using your backup file. You can save them in text files. The PKCS #11 certificate in PEM format looks similar to the following example:


    -----BEGIN CERTIFICATE-----
    MIICjCCAZugAwIBAgICCEEwDQYJKoZIhKqvcNAQFBQAwfDELMAkGA1UEBhMCVVMx
    IzAhBgNVBAoGlBhbG9a2FWaWxsZGwSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX
    aWRnZXQgTW3FrZXJzICdSJyBVczEpMCcGAx1UEAxgVGVzdCBUXN0IFRlc3QgVGVz
    dCBUZXN0IFlc3QgQ0EswHhcNOTgwMzEyMDIzMzUWhcNOTgwMzI2MDIzMpzU3WjBP
    MQswCYDDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZN0b3J5VIFB1Ymxp
    Y2F0aW9uczEWMB4QGA1UEAxMNZHVgh49dq2tLNvbjTBaMA0GCSqGSIb3DQEBAQUA
    A0kAMEYkCQCksMR/aLGdfp4m0OiGgijG5KgOsyRNvwGYW7kfW+8mmijDtZaRjYNj
    jcgpF3VnlbxbclX9LVjjNLC5737XZdAgEDozYwpNDARBglghkgBhvhCEAQEEBAMC
    APAwHkwYDVR0jBBgwFAU67URjwCaGqZHUpSpdLxlzwJKiMwDQYJKoZIhQvcNAQEF
    BQADgYEAJ+BfVem3vBOPBveNdLGfjlb9hucgmaMcQa9FA/db8qimKT/ue9UGOJqL
    bwbMKBBopsDn56p2yV3PLIsBgrcuSoBCuFFnxBnqSiTS7YiYgCWqWaUA0ExJFmD6
    6hBLseqkSWulk+hXHN7L/NrViO+7zNtKcaZLlFPf7d7j2MgX4Bo=
    -----END CERTIFICATE-----

ProcedureTo Add the CA-Signed Server Certificate and the Trusted CA Certificate

This procedure explains how to install the CA-signed server certificate and trusted CA certificates for use with Directory Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Add the CA-signed server certificate.


    $ dsadm add-cert --ca instance-path cert-alias cert-file
    

    Where cert-alias is a name that you provide to identify your certificate, and cert-file is the text file that contains the PKCS #11 certificate in PEM format.

    For example, to install a CA-signed server certificate, you might use a command similar to this:


    $ dsadm add-cert /local/ds server-cert /local/safeplace/serv-cert-file

    The certificate is now installed, but is not yet trusted. To trust the CA-signed server certificate, you must install the Certificate Authority certificate.

  2. Add the trusted Certificate Authority certificate.


    $ dsadm add-cert --ca instance-path cert-alias cert-file
    

    The --ca option indicates that the certificate is a trusted Certificate Authority certificate.

    For example, to install a trusted certificate from a Certificate Authority, you might use this command:


    $ dsadm add-cert --ca /local/ds CA-cert /local/safeplace/ca-cert-file
  3. (Optional) Verify your installed certificates.

    • To list all server certificates and to display their validity dates and aliases, type:


      $ dsadm list-certs instance-path
      

      For example:


      $ dsadm list-certs /local/ds1
      Enter the certificate database password:
      Alias       Valid from Expires on Self-   Issued by          Issued to
                                        signed?                                     
      ----------- ---------- ---------- ------- -----------------  -----------------
      serverCert  2000/11/10 2011/02/10 n       CN=CA-Signed Cert, CN=Test Cert,
                  18:13      18:13              OU=CA,O=com        dc=example,dc=com
      defaultCert 2006/05/18 2006/08/18 y       CN=host1,CN=DS,    Same as issuer
                  16:28      16:28              dc=example,dc=com
      2 certificates found

      By default, an instance of Directory Proxy Server contains a default server certificate called defaultCert. The text Same as issuer indicates that the default certificate is a self-signed server certificate.

    • To list trusted CA certificates, type:


      $ dsadm list-certs -C instance-path
      

      For example:


      $ dsadm list-certs -C /local/ds1
      Enter the certificate database password:
      Alias   Valid from Expires on Self-   Issued by           Issued to
                                    signed?                                   
      ------- ---------- ---------- ------- -----------------   --------------
      CA-cert 2000/11/10 2011/02/10 y       CN=Trusted CA Cert, Same as issuer
              18:12      18:12              OU=CA,O=com
      1 certificate found
    • To view the details of a certificate, including the certificate expiration date, type:


      $ dsadm show-cert instance-path cert-alias
      

      For example, to view a server certificate, type:


      $ dsadm show-cert /local/ds1 "Server-Cert"
      Enter the certificate database password:
      Certificate:
          Data:
              Version: 3 (0x2)
              Serial Number: 2 (0x2)
              Signature Algorithm: PKCS #1 MD5 With RSA Encryption
              Issuer:
                  "CN=Server-Cert,O=Sun,C=US"
              Validity:
                  Not Before: Fri Nov 10 18:12:20 2000
                  Not After : Thu Feb 10 18:12:20 2011
              Subject:
                  "CN=CA Server Cert,OU=ICNC,O=Sun,C=FR"
              Subject Public Key Info:
                  Public Key Algorithm: PKCS #1 RSA Encryption
                  RSA Public Key:
                      Modulus:
                          bd:76:fc:29:ca:06:45:df:cd:1b:f1:ce:bb:cc:3a:f7:
                          77:63:5a:82:69:56:5f:3d:3a:1c:02:98:72:44:36:e4:
                          68:8c:22:2b:f0:a2:cb:15:7a:c4:c6:44:0d:97:2d:13:
                          b7:e3:bf:4e:be:b5:6a:df:ce:c4:c3:a4:8a:1d:fa:cf:
                          99:dc:4a:17:61:e0:37:2b:7f:90:cb:31:02:97:e4:30:
                          93:5d:91:f7:ef:b0:5a:c7:d4:de:d8:0e:b8:06:06:23:
                          ed:5f:33:f3:f8:7e:09:c5:de:a5:32:2a:1b:6a:75:c5:
                          0b:e3:a5:f2:7a:df:3e:3d:93:bf:ca:1f:d9:8d:24:ed
                      Exponent: 65537 (0x10001)
          Signature Algorithm: PKCS #1 MD5 With RSA Encryption
          Signature:
              85:92:42:1e:e3:04:4d:e5:a8:79:12:7d:72:c0:bf:45:
              ea:c8:f8:af:f5:95:f0:f5:83:23:15:0b:02:73:82:24:
              3d:de:1e:95:04:fb:b5:08:17:04:1c:9d:9c:9b:bd:c7:
              e6:57:6c:64:38:8b:df:a2:67:f0:39:f9:70:e9:07:1f:
              33:48:ea:2c:18:1d:f0:30:d8:ca:e1:29:ec:be:a3:43:
              6f:df:03:d5:43:94:8f:ec:ea:9a:02:82:99:5a:54:c9:
              e4:1f:8c:ae:e2:e8:3d:50:20:46:e2:c8:44:a6:32:4e:
              51:48:15:d6:44:8c:e6:d2:0d:5f:77:9b:62:80:1e:30
          Fingerprint (MD5):
              D9:FB:74:9F:C3:EC:5A:89:8F:2C:37:47:2F:1B:D8:8F
          Fingerprint (SHA1):
              2E:CA:B8:BE:B6:A0:8C:84:0D:62:57:85:C6:73:14:DE:67:4E:09:56
      
          Certificate Trust Flags:
              SSL Flags:
                  Valid CA
                  Trusted CA
                  User
                  Trusted Client CA
              Email Flags:
                  User
              Object Signing Flags:
                  User

ProcedureTo Renew an Expired CA-Signed Server Certificate

When your CA-signed server certificate (public key and private key) expires, renew it by using this procedure.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Obtain an updated CA-signed server certificate from your Certificate Authority.

  2. When you receive the updated certificate, stop the server instance and install the certificate.


    $ dsadm stop instance-path
    $ dsadm renew-cert instance-path cert-alias cert-file
    
  3. Restart the server instance.


    $ dsadm start instance-path
    

ProcedureTo Export and Import a CA-Signed Server Certificate

In some cases you might want to export the public and private keys of a certificate so that you can later import the certificate. For example, you might want the certificate to be used by another server.

The commands in this procedure can be used with certificates that contain wild cards, for example "cn=*,o=example".

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Export the certificate.


    $ dsadm export-cert [-o output-file] instance-path cert-alias
    

    For example:


    $ dsadm export-cert -o /tmp/first-certificate /local/ds1 "First Certificate"
    $ dsadm export-cert -o /tmp/first-ca-server-certificate /local/ds1/ defaultCert
    Choose the PKCS#12 file password:
    Confirm the PKCS#12 file password:
    $ ls /tmp
    first-ca-server-certificate
     
  2. Import the certificate.


    $ dsadm import-cert instance-path cert-file
    

    For example, to import the certificate to a server instance:


    $ dsadm import-cert /local/ds2 /tmp/first-ca-server-certificate
    Enter the PKCS#12 file password:
     
  3. (Optional) If you have imported the certificate to a server, configure the server to use the imported certificate.


    $ dsconf set-server-prop -e -h host -p port ssl-rsa-cert-name:server-cert

Configuring the Certificate Database Password

By default, Directory Server manages the SSL certificate database password internally through a stored password. When managing certificates, the user does not need to type a certificate password or specify the password file. This option is not very secure because the password is only hidden, not encrypted.

However, if you want to have more control over the use of certificates, you can configure the server so that the user is prompted for a password on the command line. In this case, the user must type the certificate database password for all dsadm subcommands except autostart, backup, disable-service, enable-service, info, reindex, restore, and stop. The certificate database is located in the directory instance-path/alias.

ProcedureTo Configure the Server So the User is Prompted for a Certificate Password

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Stop the server.


    $ dsadm stop instance-path
    
  2. Set the password prompt flag to on.


    $ dsadm set-flags instance-path cert-pwd-prompt=on

    You are asked to choose a new certificate password.

  3. Start the server.


    $ dsadm start instance-path
    

Backing Up and Restoring the Certificate Database for Directory Server

When you back up an instance of Directory Server, you back up the Directory Server configuration and the certificates. The backed up certificates are stored in the archive-path/alias directory.

For information about how to back up and restore Directory Server, see To Make a Backup for Disaster Recovery.