Sun Crypto Accelerator 6000 Board User’s Guide for Version 1.1

Configuring Centralized Keystores

This chapter describes how to configure centralized keystores and enable access to a common repository of key material from multiple Sun Crypto Accelerator 6000 boards.

This chapter includes the following sections:

• Centralized Keystore Overview
• Configuring Centralized Keystores
• Troubleshooting CKS Issues

---

Centralized Keystore Overview

The centralized keystore (CKS) feature requires an LDAP server such as the Sun Java System Directory Server to serve as the key repository and to support multiple keystores within a single directory server instance.

FIGURE 4-1 shows machines A, B, and C accessing various keystores stored in the CKS.

FIGURE 4-1 Multiple Machine Access to a Centralized Keystore Repository

Since the Sun Crypto Accelerator 6000 board supports multiple keystores, Machine C in the preceding example can use key objects in Keystore 1 and Keystore 3. A key generated by an application running on Machine C can be accessed by the boards on Machines A and B when their applications authenticate to the keystore.

Client machines with Sun Crypto Accelerator boards can access the keystore with the scakiod service. You must set specific service properties to enable CKS support and other related configuration options such as enabling SSL and SSL client certificate authentication.

The scakiod service authenticates to the directory under a specific distinguished name (DN), called an agent name. Each system must have a unique agent DN, and an agent object with its authentication credentials. These credentials must be created in the directory server before that system can access the centralized keystore.

Keystore Virtualization

Each keystore within a single board is managed separately by its own set of security officers with its own set of users and keys. Each keystore has its own master key and all of its objects are encrypted with that key. Both centralized and local keystores are supported concurrently on the same board. Keystore virtualization allows for per zone keystores using the same board.Centralized Keystore Installation and Configuration

The most important component of the CKS is the repository itself, an LDAP server such as the Sun Java System Directory Server. Install this component according to the product documentation.

---

Configuring Centralized Keystores

This section describes how to set up CKSs.

Configuring the Directory Server With the scakscfg Utility

Once the directory server is installed, you must configure it as a CKS repository. This process includes additions to the standard configuration. This process only needs to be done once. These additions include enabling modification of relative distinguished names (RDNs), and importing the base objects and access control directives for CKS.

The Sun Crypto Accelerator 6000 board provides the scakscfg utility for configuring the Sun Java System Directory Server to support centralized keystores. This utility is located at /usr/sbin/scakscfg (Oracle Solaris) or at /opt/sun/sca6000/sbin/scakscfg (Linux). The command-line usage for scakscfg is as follows:

Usage: scakscfg -b <CKS_DN> [options] config <CFG_FILE>
       scakscfg -b <CKS_DN> [options] makeagent
commands:
   config          Configure directory server for centralized
                   keystore services.  Requires a second argument
                   <CFG_FILE> which is a configuration file.
   makeagent       Create a centralized keystore agent options:
   -b <CKS DN>     DN under which keystore nodes exist [REQUIRED]
   -D <BindDN>     Authentication DN [cn=Directory Manager]
   -h <host/IP>    Directory server hostname [localhost]
   -H              Command help
   -p <port>       Directory server port [389/636 (SSL)]
   -S <dbpath>     Use SSL with certificate database directory
                   [default off]

TABLE 4-1 describes the command-line options for the scakscfg utility.

The following example configures the directory server on host centks and places the centralized keystore under the DN o=SUN,c=US. The following example then creates an agent named agent1 that uses a password for authentication.

> /usr/sbin/scakscfg -b "o=SUN,c=US" -D "cn=Directory Manager" -h iplds config
Bind password for cn=Directory Manager:
modifying entry cn=schema
 
modifying entry cn=userRoot,cn=ldbm database,cn=plugins,cn=config
 
adding new entry ou=scakeystore,o=SUN,c=US
 
adding new entry ou=Agents,ou=scakeystore,o=SUN,c=US
 
adding new entry ou=Keystores,ou=scakeystore,o=SUN,c=US
> /usr/sbin/scakscfg -b "o=SUN,c=US" -D "cn=Directory Manager" -h iplds makeagent
Please enter the name for the agent: agent1
Will the agent use password-based authentication? [Y/N]: y
Please enter the agent password:
Confirm password:
Will the agent use a certificate for authentication? [Y/N]: n
 
========
Summary:
========
Server:                 iplds:389 (LDAP)
Agent:                  cn=agent1,ou=Agents,ou=scakeystore,o=SUN,c=US
Agent Password:         <NOT DISPLAYED>
Agent Certificate:      <NOT APPLICABLE>
========
Continue with Agent add? [Y/N]: y
Bind password for cn=Directory Manager:
adding new entry cn=agent1,ou=Agents,ou=scakeystore,o=SUN,c=US
 

Configuring the scakiod Service to Use CKS

Once the centralized keystore is configured, the next step is to enable the scakiod service to make LDAP calls to a directory server. This process requires modifying specific SMF properties in the config property group on Oracle Solaris systems, or by modifying /etc/opt/sun/sca6000/scakiod.conf on Linux.

scakiod Service Configuration Options

To configure the scakiod service to use CKS, the following properties must be created or modified. See TABLE 4-2 for how to configure these properties:

• Location of the LDAP server or servers (defined in the config/serverlist option)
• Authentication credentials (defined with the config/binddn option)
• Location of the keystore in the directory server (defined with the config/basedn option)
• The method of authentication for the agent (defined with the config/authtype option)
• The SSL certificate database path (defined with the config/certdb option)
• For the clientauth authentication method, the name of the certificate used in SSL client certificate authentication (defined with the config/certname option)
• For the simple authentication method, the password (defined with the passfile option)

1. Use the svccfg utility to configure the scakiod service to use CKS.

The following example configures the scakiod service to communicate with LDAP host centks with password-based (simple) authentication.

# svccfg -s scakiod setprop config/serverlist=astring: ’("ldap://centks")’
# svccfg -s scakiod setprop config/binddn="cn=agent1,ou=Agents,ou=scakeystore,o=SUN,c=US"
# svccfg -s scakiod setprop config/basedn="o=SUN,c=US"

2. Before restarting the scakiod service, check your settings with the listprop option of the svccfg utility:

# svccfg -s scakiod listprop | grep config
config                        application
config/auditloglimit          integer  500
config/authtype               astring  simple
config/certdb                 astring  /var/sca/private
config/certname               astring  authCert
config/keystore_dir           astring  /var/sca/keydata
config/log_file               astring  /var/sca/log/scakiod.log
config/passfile               astring  /var/sca/private/scakiod-pass.conf
config/value_authorization    astring  solaris.smf.modify.sca
config/debuglevel             astring  debug
config/serverlist             astring  ldap://centks
config/binddn                 astring  cn=agent1,ou=Agents,ou=scakeystore,o=SUN,c=US
config/basedn                 astring  o=SUN,c=US

3. Restart the server with the svcadm utility:

# svcadm restart scakiod

1. Edit the /etc/opt/sun/sca6000/scakiod.conf file.

The following example configures the scakiod service to communicate with LDAP host centks with password-based (simple) authentication. Below are examples of entries in scakiod.conf that must be modified.

serverlist     ldap://cks-host
binddn     cn=agent1,ou=Agents,ou=scakeystore,o=SUN,c=US
basedn     o=SUN,c=US

These entries identify cks-host as the centralized keystore host and specify that this system will connect as agent1.

2. Start and stop the sca daemon to activate these settings.

# /etc/init.d/sca stop
# /etc/init.d/sca start

Configuring the scakiod Service to Use SSL With Simple Authentication

The scakiod service can communicate with directory servers using SSL. To enable this communication, an NSS certificate database must be configured. The CA certificate that signs the directory server SSL certificate must be imported into that database. The certificate database must exist in the directory specified in the certdb SMF property. This directory is /var/sca/private by default. You must use the NSS utility certutil to create a database and import the root CA certificate into it.

1. Create a certificate database with the certutil utility:

# certutil -N -d /var/sca/private
Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.
 
Enter new password:
Re-enter password:

2. Add the root CA certificate to the database.

# certutil -A -d /var/sca/private -n certname -t "CT,CT,CT" -a -i certpath

3. Set the ownership on the certificate and key databases to daemon.

# chown daemon:sys cert8.db key3.db secmod.db

4. (Oracle Solaris) Change the URL for the LDAP server in the serverlist to indicate that it is using SSL

# svccfg -s scakiod setprop config/serverlist=astring: ldaps://host[:port]

5. (Linux) Edit the /etc/opt/sun/sca6000/scakiod.conf file modifying the serverlist property as follows:

serverlist   	 		ldaps://host[:port]

6. (Oracle Solaris) Restart the scakiod service so the new values take effect.

# svcadm restart scakiod

7. (Linux) Stop and start the sca services.

/etc/init.d./sca stop
/etc/init.d/sca start

Configuring the scakiod Service to Use SSL With Client Certificate Authentication

By default, the scakiod service uses simple (password-based) authentication. A more secure method of authentication is available for centralized keystore agents. That method uses X.509 certificates to cryptographically authenticate to the directory server. The configuration of this authentication method is more complex, as it requires not only the previous steps for basic SSL configuration. This method also requires that you obtain a digital certificate for the scakiod service, and that the CA that signs that certificate must be trusted by the LDAP server. Further, proper certificate mapping must be set up in the LDAP server so the components in the certificate subject name can be mapped to the agent DN in the LDAP server.

1. Complete all the steps involved in configuring scakiod for simple authentication over SSL in Configuring the scakiod Service to Use SSL With Simple Authentication.

2. (Oracle Solaris) Set the authentication type to clientauth.

# svccfg -s scakiod setprop config/authtype=clientauth

3. (Linux) Edit the /etc/opt/sun/sca6000/scakiod.conf file modifying the authtype property as follows:

authtype			clientauth

4. (Oracle Solaris) Use the certutil utility to create a key and certificate request.

# certutil -R -d /var/sca/private -s <BINDDN> -g 1024 -a -o /var/sca/private/certreq.pem
Enter Password or Pin for "NSS Certificate DB":
 
A random seed must be generated that will be used in the
creation of your key.  One of the easiest ways to create a
random seed is to use the timing of keystrokes on a keyboard.
 
To begin, type keys on the keyboard until this progress meter
is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!
 
 
Continue typing until the progress meter is full:
 
|************************************************************|
 
Finished.  Press enter to continue:
 
Generating key.  This may take a few moments...

5. (Linux) Use the certutil utility to create a key and certificate request.

# certutil -N -d /var/opt/sun/sca6000/private -s <BINDDN> -g 1024 -a -o /var/sca/private/certreq.pem
Enter Password or Pin for "NSS Certificate DB":
 
A random seed must be generated that will be used in the
creation of your key.  One of the easiest ways to create a
random seed is to use the timing of keystrokes on a keyboard.
 
To begin, type keys on the keyboard until this progress meter
is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!
 
 
Continue typing until the progress meter is full:
 
|************************************************************|
 
Finished.  Press enter to continue:
 
Generating key.  This may take a few moments...

6. Submit the certificate request to a certificate authority and get a digital certificate.

Place the digital certificate somewhere on the system where scakiod is running so the certificate can be imported into the certificate database (for example, /var/sca/private/cert.pem).

7. If the issued certificate is in ASCII encoded form, convert it to binary form as follows:

# openssl base64 -d -in /var/sca/private/cert.pem -out /var/sca/private/cert.der

8. Install the resulting certificate and the CA certificate into the NSS certificate database with certutil:

# certutil -A -n nickname -t "u,u,u" -d /var/sca/private -a -i certfile

9. Install the CA certificate that signed the certificate to be used in authentication:

# certutil -A -n canickname -t "C,C," -d /var/sca/private -a -i certfile

Adding the Certificate to the Agent Entry in the Directory Server

You must add the certificate to the agent entry in the directory server. If the agent entry does not exist in the DS, use the scakscfg utility with the makeagent option. When the utility prompts for whether certificate authentication is to be used or not, answer Y. You are prompted for the location of the certificate. Use the binary certificate file you created in the preceding example.

Once the agent entry exists, add the certificate to the entry with the ldapmodify command.

1. Create a modification file with the following info:

dn: cn=agent-dn
		changetype: modify
		replace: usercertificate;binary
		usercertificate;binary: /var/sca/private/cert.der

2. Use ldapmodify to alter the agent entry and add the certificate:

# ldapmodify -h host -b -D dir-adm-dn < modfile
modifying entry cn=geeky,ou=Agents,ou=scakeystore,o=SUN,c=US

3. In the directory server, ensure that the CA certificate used to sign the certificate that scakiod uses for authentication is trusted.

The procedure for this will vary across different DS implentations. Refer to the directory server documentation for details on how to do this.

4. Set up certificate mapping on the directory server.

The procedure for this will vary between DS implementations. The certmap.conf file for Sun directory servers contains a default mapping and zero or more additional mappings tied to the issuer DN for certificates used in authentication. If the default rule cannot be used, you might need to create a separate rule for the issuer DN. That issuer DN will be the same as the issuer DN for the certificate used by the scakiod service for SSL client certificate authentication. In addition, set the verifycert directive to on for the mapping rule you are modifying. In cases where the certificate subject name matches the DN of the agent entry, the DNComps directive can be commented out. If the names differ, then different combinations of the DNComps and FilterComps might be required to get proper certificate mapping.

5. (Oracle Solaris) Restart the scakiod service:

# svcadm restart scakiod

6. (Linux) Start and stop the sca services:

# /etc/init.d/sca stop
# /etc/init.d/sca start

Configuring the Board to Join a Centralized Keystore

Once a centralized keystore is created, other SCA 6000 boards on different systems may then be configured to access the centralized keystore. The following steps must be taken to bring a new board on a different server into the centralized keystore.

1. Make a note of the serverlist, basedn and authtype parameters.

Use similar authentication methods across all your servers if possible.

2. Use the scamgr utility to log into the keystore and export the master key.

scamgr{mca0@localhost, sec_officer}> backup master-key
Full path (including file name) to receive backup file: path-to-backup
Enter a password to protect the data: password
Confirm password: password
Backup to path-to-backup successful.

1. If the board is uninitialized, initialize it using scamgr (See Chapter 3.)

2. Create an agent using the scakscfg utility with the makeagent subcommand.

3. Set the password for the agent in the password configuration file specified by the passfile configuration property.

4. Set the serverlist, basedn, binddn, and authtype for the scakiod service.

5. Restart the scakiod service.

From the system where the backup file was saved, use scamgr to remotely connect to the target machine and board. When the Select Keystore screen is given, choose Load Keystore from Backup and provide the backup file saved previously.

# scamgr -h target-host
Select Keystore:
1. Create new keystore
2. Load keystore from backup
 
Selection (0 to exit)-> 2
Enter the path to the backup file: path-to-backup
Password for restore file:
 
Load Parameters:
----------------------------------------------------------------
Path to backup file: path-to-backup
Keystore name: company-ks.600062
Backup type: Master key
Load type: Master key
Requires Multi-Admin auth: No
----------------------------------------------------------------
 
Is this correct? (Y/Yes/N/No) [No]: y
Restoring data to crypto accelerator board.  This may take a few minutes...
 
company-ks.600062 successfully created.

---

Troubleshooting CKS Issues

The following section describes how to debug misconfigurations with the centralized keystore. Errors are written into the log file referenced by the LogFile property and path used in the /etc/opt/sun/sca6000/scakiod.conf file. For example:

# LogFile               /var/opt/sun/sca6000/log/scakiod.log

The following is an example of the /etc/opt/sun/sca6000/scakiod.conf file:

#
# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#ident  "@(#)scakiod.conf       1.11    07/10/24 SMI"
#
# Configuration file for scakiod(8), see man page for details.
#
# Directives in this configuration file should use the following
# syntax:
#
# <DIRECTIVE>           <VALUE>
#
# Directives should be one-per-line, and if two directives with the same
# name are found in the configuration file, the last one will be the one
# used.  The only exception to this is the HostBind directive, in which
# multiple entries signify additional IP addresses to listen on.  Keystore
# directive names are case-insensitive.
#
 
# user: The user directive tells scakiod to run as that particular user.  The
# value for this directive is a username.  It is recommended that this user
# not be root or any other account with superuser privilege.
#
user                    daemon
 
# logfile: This directive takes a pathname to a file used specifically for
# scakiod logging data.  Regardless of whether this directive is set or not,
# scakiod will send log entries to syslog.
#
logfile         /var/opt/sun/sca6000/log/scakiod.log
 
# keystoredir: The keystoredir directive allows the administrator to set an
# alternate directory for keystore files.  The default value for this is
# /var/opt/sun/sca6000/keydata.  Any alternate location must have read,
# write and execute permissions for the user that the daemon runs as.  It
# is recommended to not allow any permissions for any other user to this
# directory.
#
keystoredir             /var/opt/sun/sca6000/keydata
 
# debuglevel: The debuglevel directive sets the default log mask for scakiod
# logging events.  By default, the level is NOTICE.  The other accepted values,
# in order of increasing verbosity, are INFO and DEBUG (equivalent to -d and
# -dd on the command line, respectively).
#
debugleve       NOTICE
 
# The next set of parameters is specific to centralized keystore configuration
# If there are no centralized keystore servers specified in the serverlist
# directive, then the service will disable centralized keystore functionality
# and only look for local keystores.  All other centralized keystore
# directives will be read but will be ignored.
 
# The serverlist  property is a list of LDAP servers where centralized
# keystores are hosted.  Entries in this property should be in the form of
# an LDAP URL:
#       <proto>://<server>:[<port>]
# Where <proto> is either "ldap" or "ldaps".  <server> is a hostname,
# fully-qualified domain name, or IPv4/v6 address of the LDAP server.
# <port> is the port number and is the only optional value.  If <port> is
# omitted the value is 389 for LDAP, 636 for LDAPS.  Multiple serverlist
# directives may be used.  If more than one is used, the service will attempt
# to bind to the servers in the order they are listed until it successfully
# contacts one.
#
# serverlist            ldap://localhost:389
serverlist              ldaps://nsn104-20
 
# The basedn property sets the base DN for the centralized keystore directory
# tree.  The top of the centralized keystore tree is ou=scakeystore.  You
# will need to append the root DN to this value if such exists.
#
#basedn                 ou=scakeystore
basedn                  o=SUN,c=US
 
# The authtype property sets the type of authentication used by the service
# to the LDAP server.  This can be one of two values, "simple" or "clientauth".
#
authtype                simple
 
# The binddn property is only meaningful if the authtype property is set to
# "simple".  This value is in the form of a distinguished name which
# corresponds to a keystore agent entry.
#
#binddn                 CN=Directory Manager
binddn                  cn=agent1,ou=Agents,ou=scakeystore,o=sun,c=us
 
# The certdb property contains the path to the certificate database directory
# for the service.  This defaults to /var/sca/private if not otherwise defined.
#
certdb                  /var/opt/sun/sca6000/private
 
# The certname property defines the friendly name for the certificate used in
# client certificate authentication.  This value should be just the cert
# friendly name if stored in the NSS internal database.  If the key and
# certificate are stored on an external device, then the value should be the
# PKCS#11 token name, followed by a colon (:), followed by the friendly name.
#
certname                server-cert
 
# The passfile property defines the location for the file that contains a
# password.  If the authtype property is "simple" then that file contains the
# password used during LDAP simple authentication.  If the authtype is
# "clientauth" then the password in this file is used to authenticate to the
# keystore containing the private key for the certificate used to authenticate.
#
passfile                /var/opt/sun/sca6000/private/scakiod-pass.conf
 
# The auditloglimit directive is used for the keystore audit logging facility.
# The value used here is an integer specifying the maximum number of log
# entries before the audit log is rotated.
#
auditloglimit           500
[root@nsn104-57 sca6000]#

Cannot Contact Server

Sep 18 09:33:09 [29290/1]: [info] Cannot contact server vdemo02.west.sun.com:636: Can’t connect to the LDAP server
Sep 18 09:33:09 [29290/1]: [ERROR] Cannot connect to any LDAP server for centralized keystore services.

Possible causes:

• The LDAP servers on all hostnames or IP addresses referenced in the serverlist property are down.
• The referenced server is not a valid hostname or IP address.
• The servers referenced do not have LDAP servers on them.

Initial Keystore Search Failed

Sep 18 12:02:12 [18800/47045332179296]: [info] Successfully bound as cn=vigenere,ou=Agents,ou=scakeystore,o=SUN,c=US
Sep 18 12:02:12 [18800/47045332179296]: [ERROR] Initial keystore search failed: No such object

Possible causes:

• The value for the basedn property is incorrect.
• The LDAP server for the keystore repository has not been configured using the scakscfg utility with the config subcommand.

Failed Binding to Server

Sep 18 12:04:45 [18800/47045332179296]: [ERROR] Failed binding to server vdemo01.west.sun.com:636: No such object

Possible causes:

• The value for the binddn property is incorrect.
• The agent entry has not been created using scakscfg using the makeagent subcommand.

Failed Binding to Server

Sep 18 12:07:06 [18800/47045332179296]: [info] Attempting LDAPS connection to vdemo01.west.sun.com:636
Sep 18 12:07:06 [18800/47045332179296]: [ERROR] Failed binding to server vdemo01.west.sun.com:636: Invalid credentials

Possible causes:

• The password in the config file referenced by the passfile property contains an incorrect password.

Client Authentication Initialization Failed

Sep 18 12:09:58 [18981/47903389276512]: [info] Starting keystore I/O handler
Sep 18 12:09:58 [18981/47903389276512]: [ERROR] Client authentication init failed

Possible causes:

• The ownership or permissions on the certificate database files in the directory referenced by the certdb property are not readable to the UNIX user daemon.
• The certificate database files have not been created in the directory referenced by the certdb property.

Sun Crypto Accelerator 6000 Board User’s Guide for Version 1.1

E39851-01

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.