SASL-CA Deployment Guide

Derek Morr
derekmorr@psu.edu

Introduction

The SASL-CA is an online Certificate Authority. It is a CA server which issues short-term certificates to end users who authenticate via SASL. It is currently at version 0.4. Included is the SASL-CA server, as well as a sample command-line client application.

At present, the SASL-CA client has been tested on Solaris, Linux, Mac OS X and Windows with Java 5. Its Kerberos compatibility has been tested with MIT Kerberos 5 and Microsoft Active Directory. The server has only been tested on Solaris and Linux with the Sun JVM, but it should operate on other Unix-based platforms.

This document assumes that you have a working knowledge of Kerberos and are familiar with Public Key Infrastructure.

For notes on using the SASL-CA with Active Directory, please consult the appendix.

SASL Mechanism Support

SASL is a pluggable framework for authenticating users. Many SASL mechanisms are registered with IANA (see http://www.iana.org/assignments/sasl-mechanisms), but not all SASL implementations support all of these mechanisms.

This document discusses the following SASL mechanisms:

Mechanism Name    Description
PLAIN    sends a cleartext username and password to the server
GSSAPI    sends a Kerberos service ticket to the server
CRAM-MD5    send a weakly encoded password to the server
DIGEST-MD5    improved version of CRAM-MD5

Sun's implementation  in Java 5 only supports GSSAPI, CRAM-MD5 and DIGEST-MD5.  The SASL-CA comes with a plugin for the SASL PLAIN mechanism which lets clients tunnel a username and password to the SASL-CA (preferrably over a TLS tunnel). See the section “PLAIN and STARTTLS” for information on configuring this option.

Most of this document will focus on the SASL GSSAPI mechanism.

 
General Setup Notes

For all machines:

1    If you are using the GSSAPI mechanim, you should have a working Kerberos environment to use the SASL-CA. Please ensure that you have a working Kerberos configuration (krb5.conf) on your machine. Be sure kinit works! If you are not using GSSAPI, please see the “PLAIN and STARTTLS” section.

1    If you are using Sun's JVM, you should install the JCE Unlimited Strength Jurisdiction Policy Files. These files are recommended for the clients, and mandatory for the server. The default server configuration will not function without these policy files installed. To obtain the files, go to http://java.sun.com/j2se/1.5.0/download.jsp. Note that you may need to reinstall these files each time you upgrade your JVM.

1    It is highly recommended that the SASL-CA and all clients' clocks be synchronized to a trusted time source. Many of the security mechanisms employed by the SASL-CA employ replay attack prevention techniques based on the local time. Further, the SASL-CA needs to set certificate timestamps to a correct time. Use NTP or the Windows Time Service to synchronize the clock.



 
Server configuration


The SASL-CA server is highly configurable. It feature configurable logging (via
log4j), pluggable authentication modules, directory access modules, authorization modules, name mapping modules, and serial number generators. Fortunately, default values are provided for most of these options.

Sample configuration files are provided in the sample_config/server directory. There are four files there:

Filename    Description
jaas_server.conf    JAAS configuration file for the SASL-CA
log4j.properties    log4j configuration file
resolver.xml    attribute resolver configuration
sasl-ca.properties    main SASL-CA configuration file

You should copy these files to the apps/server directory and edit them according to the instructions below. If you are using Active Directory for Kerberos and LDAP, do not use the sample configuration files in sample_config/server. Instead, use the files in sample_config/ad/server. These files have been preconfigured to use AD's defaults and will require much less customization.


General Setup

You will need to set the hostname, port and maximum number of worker threads for the SASL-CA. The defaults are to listen on port 4088, and to spawn up to 20 worker threads to handle requests.

Edit apps/server/sasl-ca.properties:

saslca.ServerName = saslca.hostname.here
saslca.ServerPort = 4088
saslca.MaxConnections = 20
 
KeyStore Setup
 
The SASL-CA needs a keystore to store its signing cert and private key. If you are using Shibboleth, you should copy the handle.jks keystore from your IdP to the SASL-CA's apps/server directory.

You can either import an existing certificate and private key, or generate a self-signed certificate. Use the Java keytool utility to do this. The keystore should be in the apps/server directory. Make a note of the keystore's password. You will need it later.

If you don't have a PKI:

To make a self-signed cert (recommended for testing purposes only), run the following command from the sasl-ca/ directory:
 
keytool -genkey -alias SASL-CA -keyalg RSA -keysize 2048 \
     -validity 365 -keystore apps/server/handle.jks \
    -storetype JKS

Edit apps/server/sasl-ca.properties and set the following options:

saslca.Keystore.Password = keystorePassword
saslca.keystore.PrivateKeyPassword = privateKeyPassword


If you have a PKI:

If your organization runs a PKI or participates in a federation (such as Internet2's InQueue or InCommon federations), you will need to generate a Certificate Signing Request (CSR). To do so, run the following commands from the sasl-ca/ directory:

keytool -genkey -alias SASL-CA -keyalg RSA -keysize 2048 \
     -validity 365 -keystore apps/server/handle.jks \
     -storetype JCEKS

keytool -certreq -alias SASL-CA -file file.csr \
    -keystore apps/server/handke.jks \
    -storetype JCEKS

You will then need to send file.csr to your CA. Your CA will send you back a signed certificate, which you import by using this command:

keytool -import -file signed.cert.file -alias SASL-CA \
     -keystore apps/server/handle.jks \
     -storetype JCEKS

Depending on the format of signed.cert file, you may need to import the CA's root cert first. Please note that when you import the reply, you must use the same value for -alias that you used with -certreq.

Edit apps/server/sasl-ca.properties and set the following options:

saslca.Keystore.Password = keystorePassword
saslca.keystore.PrivateKeyPassword = privateKeyPassword

Authentication Setup - Kerberos

Create a Kerberos service principal for the SASL-CA. The service principal must be named sasl-ca/hostname@realm. Create a keytab for this principal and export it to the SASL-CA server. You don't have to import the keytab into your system-wide keytab file.

Edit apps/server/jaas_server.conf. You'll need to fill in the principal and keyTab fields. For reference, this is a sample server-side jaas.conf entry for Kerberos 5:

SASL-CA {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache="true" 
    debug="false"
    renewTGT="true"
    refreshKrb5Config="true"
    storeKey="true"
    principal="sasl-ca/hostname.of.saslca.server@REALM"
    keyTab="/path/to/your/keytab"
    useKeyTab="true"; 
};

For production use, you will probably want to set debug to false.

For more information on JAAS login configuration files, see
http://java.sun.com/j2se/1.5.0/docs/guide/security/jgss/tutorials/LoginConfigFile.html



 
Authentication Setup – SASL-CA

The SASL-CA supports one or more authentication mechanisms for authenticating users. These are configured in the sasl-ca.properties file. Edit the file and set the  saslca.SaslMechanisms property.

For each SASL mechanism enable, you also need exactly one principal-mapping class. This class is used to convert principal names into a form usable by your directory. For instance, a Kerberos principal name has the form user/instance@REALM, but you generally only want to lookup the user part in your directory. The SASL-CA comes with a Kerberos principal mapper class that does this conversion.

PrincipalMappers should be registered by creating a property named saslca.PrincipalMapper.mechanismName; the property's value should be the name of a Java class that maps the princpal name. The SASL-CA comes with two PrincipalMapper classes:

•    edu.psu.sasl_ca.util.KerberosPrincipalMapper

This plugin strips the instance and realm fields off a Kerberos principal, leaving the bare principal name.

•    edu.psu.sasl_ca.util.EchoPrincipalMapper

This plugin performs no processing on the SASL principal name; it simply echos the value.

If you are using Kerberos, include the following lines in your sasl-ca.properties file.

saslca.SaslMechanisms = GSSAPI
saslca.PrincipalMapper.GSSAPI = \
    edu.psu.sasl_ca.util.KerberosPrincipalMapper

(Note, in the above example, the saslca.PrincipalMapper.GSSAPI entry is split across two lines. This is due to formatting limitations of this document. It should be on one line in sasl-ca.properties).
 
Directory Setup

When building identity certificates, the SASL-CA needs to consult one or more directories for attributes to build an X.500 Distinguished Name string. This string looks something like this:

 C=US ST=Pennsylvania L=UNIVERSITY PARK \
    O=Pennsylvania State University \
    OU=ACADEMIC SERV & EMERGING TECH \
    CN=DEREK VAUGHAN MORR(dvm105@psu.edu)/derekmorr@psu.edu

Please note that the differences in case between the fields is not important. It's an artifact of Penn State's directory system.

The string is composed of several tag-value pairs:
 
C = country
ST = state
L = city,
O = Organization,
OU = Organizational Unit ("department")
CN = common name

Most of these attributes can be fetched from a directory, but some, like C, ST, L and O will probably be fixed strings that are the same for all users (and may not be stored in your directory at all). The SASL-CA lets you set which elements of the DN are fixed strings and which are attributes to be fetched from a directory.

The sasl-ca.properties file contains several entries like this:

saslca.C = string
saslca.C.value = US
saslca.OU = attribute
saslca.OU.value = psDepartment

This means that the C value is a fixed string (saslca.C is string). Specifically, that string is US. However, the OU value is an attribute to be fetched from the directory (saslca.OU is attribute). Specifically, the value for the OU tag is stored in the psDepartment attribute (in Penn State's LDAP schema, psDepartment stores an individual's department. The name of this attribute will probably be different at your institution). There are entries like this for all of the X.500 DN tags in sasl-ca.properties.

Here is an excerpt from my sasl-ca.properties, configured for Penn State's environment. Your setup will most likely be different.

saslca.C = string
saslca.C.value = US
saslca.ST = string
saslca.ST.value = Pennsylvania
saslca.L = attribute
saslca.L.value = urn:mace:dir:attribute-def:psCampus
saslca.O = string
saslca.O.value = Pennsylvania State University
saslca.OU = attribute
saslca.OU.value = urn:mace:dir:attribute-def:psDepartment
saslca.CN = attribute
saslca.CN.value = urn:mace:dir:attribute-def:displayName
saslca.mail = attribute
saslca.mail.value = urn:mace:dir:attribute-def:mail
saslca.URL = attribute
saslca.URL.value = urn:mace:dir:attribute-def:labeledURI
saslca.Principal = attribute
saslca.Principal.value = \
    urn:mace:dir:attribute-def:eduPersonPrincipalName

(Note, in the above example, the saslca.Principal.value entry is split across two lines. This is due to formatting limitations of this document. It should be on one line in sasl-ca.properties).

For reference, Penn State's LDAP schema may be viewed at  http://aset.its.psu.edu/ldap/ldap_attributes.html


Mandatory Attributes

When building an identity certificate, the SASL-CA will omit any attributes it is unable to resolve in your directory. To make certain attribute mandatory, set the saslca.MandatoryAttributes property. This should be a space-seperated list of mandatory attribute names. For example, to require that identity certs have an eduPersonPrincipalName:

saslca.MandatoryAttributes = \
    urn:mace:dir:attribute-def:eduPersonPrincipalName

(Note, in the above example, the saslca.SerialNumberGenerator entry is split across two lines. This is due to formatting limitations of this document. It should be on one line in sasl-ca.properties).

Note that mandatoryAttributes operates on attributes, not DN components (such as C, ST or OU).
 
Shibboleth Integration

The SASL-CA also needs a symmetric ("secret") key to generate encrypted handles for opaque certificates.  If you are using Shibboleth, this key will come from the handke.jks keystore you copied to the SASL-CA.

If you accepted the Shibboleth defaults when installing your IdP, you can ignore the rest of this section.

If you customized the values for the handle.jks keystore, you will need to enter those values in sasl-ca.properties. Specifically, the following options may need to be set:

saslca.KeyStore.EncryptionKeyAlias = handleKey
saslca.KeyStore.EncryptionKeyPassword = shibhs
saslca.KeyStore.MACKeyAlias = handleKey
saslca.KeyStore.MACKeyPassword = shibhs

If you selected a custom alias for the symmetric key, enter that value for saslca.KeyStore.EncryptionKeyAlias and saslca.KeyStore.MACKeyAlias. If you selected a custom password for the symmetric key, enter that value for saslca.KeyStore.EncryptionKeyPassword and saslca.KeyStore.MACKeyPassword.


Logging Setup

The SASL-CA uses log4j to control logging. The default configuration logs informational messages into a text file, apps/server/sasl-ca.log, which is rotated and daily. To change these settings, edit apps/server/log4j.properties and restart the SASL-CA.


CA Setup

The sasl-ca.properties file contains several options that how the SASL-CA builds certificates. By default, opaque and identity certificates have an 8 hour lifetime, and peerserver certificates are valid for one year. If you wish to change these values, edit sasl-ca.properties and adjust the these settings:

saslca.OpaqueCertLifetime = 28800
saslca.IdentityCertLifetime = 28800
saslca.PeerServerCertLifetime = 31536000

Note that the values are in seconds.
 
SerialNumberGenerator Setup

Each certificate made by the SASL-CA must have a unique serial number. The SASL-CA supports a plugin interface for serial number generators. Several plugins are provided with the SASL-CA. If you do not specify a SerialNumberGenerator plugin, a reasonable default is chosen. This default is unlikey to generate duplicate serial numbers, but uniqueness is not guaranteed.

The SASL-CA ships with three serial number plugins:

•     edu.psu.sasl_ca.serial.SequentialSerialNumberGenerator

This plugin uses a simple counter to generate serial numbers. Some researchers have expressed concerns that this approach may pose a security risk, but it is included for simplicity's sake.

SequentialSerialNumberGenerator takes the following options:

saslca.SerialNumberGenerator.SeqSNG.File (Mandatory)
The plugin stores the last serial number it generated in a file. This property must contain the fully qualified path to the backing file.

saslca.SerialNumberGenerator.SeqSNG.Min (Optional)
The minimum serial number to generate.

saslca.SerialNumberGenerator.SeqSNG.Max (Optional)
The maximum serial number to generate.

•     edu.psu.sasl_ca.serial.HashedTimeSerialNumberGenerator

This plugin takes the current Unix epoch (the number of milliseconds seconds since midnight, Jan 1, 1970 UTC), combines that with a pseudorandom pad, and hashes the mix using SHA-1. This is the default SerialNumberGenerator if none is specified.

HashedTimeSerialNumberGenerator takes the following options:

saslca.SerialNumberGenerator.HashedTimeSNG.DigestAlgorithm (Optional)
The JCE algorithm name for the hash function. Setting this to a stronger hash (SHA-256, etc) could adversely affect performance and has not been performance tested. If not set, SHA-1 is used.

saslca.SerialNumberGenerator.HashedTimeSNG.DigestProvider (Optional)
The JCE provider for the hash function. It is recommended to leave this option unset unless you have a good reason to change it.

saslca.SerialNumberGenerator.HashedTimeSNG.PRNGAlgorithm (Optional)
The JCE algorithm name for the PRNG. It is recommended to leave this option unset unless you have a good reason to change it.

saslca.SerialNumberGenerator.HashedTimeSNG.PRNGProvider (Optional)
The JCE provider name for the PRNG. It is recommended to leave this option unset unless you know have a good reason to change it.

•    edu.psu.sasl_ca.serial.UUIDSerialNumberGenerator

This plugin generates a type 2 (DCE) UUID for the serial number. It is essentially a stronger version of HashedTimeSerialNumberGenerator. Its output is provably unique. This plugin requires the MAC address of the SASL-CA's NIC.

UUIDSerialNumberGenerator takes the following options:

saslca.SerialNumberGenerator.UUIDSNG.MAC (Mandatory)
The MAC address of the SASL-CA's NIC, formatted as a colon-sperated hex-string (e.g. 0:3:ba:b0:1b:aa).

saslca.SerialNumberGenerator.UUIDSNG.PRNGAlgorithm (Optional)
The JCE algorithm name for the PRNG. It is recommended to leave this option unset unless you have a good reason to change it.

saslca.SerialNumberGenerator.UUIDSNG.PRNGProvider (Optional)
The JCE provider name for the PRNG. It is recommended to leave this option unset unless you have a good reason to change it.

There is also an interface, edu.psu.sasl_ca.serial.SerialNumberGenerator, which you can implement, should you want to write your own serial number generator.

It is recommended that you select the UUIDSerialNumberGenerator, since it genreates provably unique serial numbers. To do so, edit apps/server/sasl-ca.properties and set the following options:

saslca.SerialNumberGenerator = \
    edu.psu.sasl_ca.serial.UUIDSerialNumberGenerator
saslca.SerialNumberGenerator.UUIDSNG.MAC = macAddress

(Note, in the above example, the saslca.SerialNumberGenerator entry is split across two lines. This is due to formatting limitations of this document. It should be on one line in sasl-ca.properties).
 
PLAIN and STARTTLS

The SASL-CA supports authentication via plaintext username/password pairs (via the SASL PLAIN mechanism). The mechanism transmits data in the clear. If enabled, the SASL-CA client will automatically try to establish a TLS tunnel to the server and will abort the connection if unable to do so.

The PLAIN mechanism is enabled by editing apps/server/sasl-ca.properties and setting the saslca.SaslMechanisms property to include PLAIN:

saslca.SaslMechanisms = PLAIN

Note that more than one SASL mechanism can be supported, e.g.:

saslca.SaslMechanisms = GSSAPI PLAIN

Once the SASL-CA has the username and password, it must validate them. It uses the JAAS  framework to do this. You must specify one or more JAAS modules that will validate a username and password. To do so, edit apps/server/jaas_server.conf and create a new Login Configuration called PLAIN, and configure it to use the desired JAAS LoginModule(s). Please note that a full discussion of JAAS is outside the scope of this document.

Here is an example Login Configuration that checks a username and password against a Kerberos realm:

PLAIN {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache="false" 
    debug="false"
    renewTGT="false"
    storeKey=”false”
    refreshKrb5Config="true";
}; 

Using the above setup would allow users to authenticate with a Kerberos service ticket (GSSAPI) or with their Kerberos username and password (PLAIN).

There are many JAAS LoginModules available, for authentication against Kerberos, LDAP, NIS, etc.  Note that the PLAIN Login Configuration must appear outside of the SASL-CA Login Configuration in jaas_server.conf.

Since the PLAIN mechanism sends data in the clear, the SASL-CA will automatically use STARTTLS. STARTTLS is a way of starting an SSL/TLS connection between two machines. The first time the SASL-CA is started it will automatically create a certificate and private key to secure plaintext authentication mechanisms. This certificate will be stored in the SASL-CA's keystore with the alias starttls and password starttls.

The SASL-CA client will automatically try to use STARTTLS when using plaintext authentication, and will abort authentication if unable establish a TLS tunnel.

If you wish to provide fine-grained control over the SSL/TLS tunnel, you may set the following options in sasl-ca.properties:

saslca.STARTTLS.Protocols = TLSv1 SSLv3
saslca.STARTTLS.CipherSuites = TLS_RSA_WITH_AES_128_CBC_SHA

If these options are not set, TLSv1 will be used for the SSL protocol, and the JVM defaults will be used for the ciphersuite. If set, the options should contain a space-seperated list of SSL protocols and cipher suites, respectively.


 
Authorization Support

The SASL-CA supports pluggable authorization modules. Modules are enabled by listening them in the sasl-ca.authz property (in apps/server/sasl-ca.properties). For example:

saslca.authz = edu.psu.sasl_ca.authz.PeerServer \        
    edu.psu.sasl_ca.authz.BannedUsers

(Note, in the above example, the saslca.authz entry is split across two lines. This is due to formatting limitations of this document. It should be on one line in sasl-ca.properties).

It comes with two authorization modules:

•    edu.psu.sasl_ca.authz.BannedUsers

This is a simple banned users lists. If a userid appears in this module's backing file, that user is prohibited from obtaining opaque and identity certificates. This mechanism has a default allow policy. It is not necessary to restart the SASL-CA when changes to the backing file are made; the module monitors the filesystem and will reload the banned user list automatically.

BannedUsers takes the following option:

BannedUsers.File (Mandatory)
The path to the banned users file. The file should contain one username per line. The username should be in the format produced by the PrincipalMapper (for Kerberos, it should contain a bare usename, without an instance and realm).

•    edu.psu.sasl_ca.authz.PeerServer

This module controls authorization for PeerServer CSRs. It is a default deny module. It is not necessary to restart the SASL-CA when changes to the backing file are made; the module monitors the filesystem and will reload the permitted user list automatically.

PeerServer takes the following option:

PeerServer.File (Mandatory)
The path to the permitted users file. The file should contain one username-hostname pair per line. The username should be in the format produced by the PrincipalMapper (for Kerberos, it should contain a bare usename, without an instance and realm). For example, “dvm105 : lionshare.its.psu.edu” would permit user dvm105 to obtain a peerserver certificate for host lionshare.its.psu.edu.
Running the Server

To run the server, run ant runserver from the main sasl-ca directory.


Optional Server Configuration

The SASL-CA has several optional parameters which can improve security and performance. You do not need to set any of these values for the SASL-CA to work properly. These are provided for experienced system administrators who want more control over the SASL-CA's functionality. Each of these steps can be performed independently, as they do not depend on one another.

•    SASL-CA uses log4j for logging. It ships with a sample configuration file in apps/server/log4j.properties. You may want to edit this file to reflect your site's logging requirements. Please consult http://logging.apache.org/log4j/docs/ for more information on log4j.

•    The SASL-CA performs PKI operations (signing new certificates). The JVM tends to perform poorly if too many digital signature operations are performed in parallel.The SASL-CA can limit the number of these operations it performs concurrently. To do so, set saslca.MaxPKIOps in sasl-ca.properties. If you do not set a value, it will default to 10.
 
•    When the SASL-CA creates a new certificate, it sets the notBefore field to the current time. If the SASL-CA's clock and the client's clock differ (specifically, if the server's clock is ahead of the client), it is possible that the client will receive a cert that is not yet valid (according to the client's clock). This is possible even if both the client and server synchronize their clocks against the same source. The SASL-CA skews the notBefore field to 5 minutes before the current time when it creates a certificate. To adjust this skew factor, set saslca.CertSkewSeconds.



 
Issuing Peerserver Certificates

There are two ways for peerserver administrators to obtain Peerserver certificates: they can generate a CSR themselves and use the sasl-ca client to have them signed, or they can generate a CSR and email it to the SASL-CA administrator to have it signed.

Option 1: Generate the CSR themselves

This is the easier option for the Peerserver administrator. The SASL-CA client comes with an ant target to generate the CSR (including formatting the DN correctly), connect to the SASL-CA to have the CSR signed, and then install the signed certificate and private key into the appropriate keystore.

A Peerserver administrator will need to email the SASL-CA administrator with his username and PeerServer hostname. These values will need to be added into the apps/sasl-ca/peerserver.authz file. For example, the entry:

dvm105:testpeerserver.mydomain.edu

authorizes user dvm105 to obtain a peerserver certificate for hostname testpeerserver.mydomain.edu. Note, the SASL-CA does not need to be restarted after the peerserver.authz file is edited; it will notice the change and update itself automatically.

Once the SASL-CA has authorized the Peerserver administrator to obtain the certificate, the Peerserver administrator should run ant makePeerServerCert from the sasl-ca/ directory. This will prompt the PeerServer administrator for the hostname and keystore parameters. It will then install the trust root and signed certs into the keystore.


Option 2: Manually generated CSR

If a Peerserver administrator prefers to manually create a CSR (perhaps using OpenSSL), he will email it to the SASL-CA administrator. The SASL-CA administrator will need to authorize himself to request the Peerserver certificate in apps/sasl-ca/peerserver.authz, as described above. He will then run ant signcsr. This ant target will prompt the administrator for the CSR filename, and will output the signed certificate in the file signed.cert. Note, this target does not currently export the trust chain for the SASL-CA.

The CSR may be in PEM or DER format. The signed certificate is output in DER format.
 
Client Configuration

The SASL-CA includes a sample command-line client application. This is a useful diagnostic tool for the SASL-CA server. The client will connect to a SASL-CA, authenticate, obtain identity and opaque certificates, validate those certificates, and attempt to renew the opaque certificate. If the sample client completes successfully, you have a fully functional SASL-CA.

Copy the sample client configuration files from sample_config/sample_client to apps/sample_client. To configure the sample client, perform the following steps:

1) Configure jaas_client.conf to use the appropriate JAAS LoginModule. This LoginModule must be able to provide the correct credentials to SASL, so you're going to have to do some fudging (i.e., if you know that you'll be configuring the server to use Kerberos, then use the Krb5LoginModule in JAAS).

If you are using Kerberos 5, then you can use the copy of jaas_client.conf included with the SASL-CA.

This is a sample jaas_client.conf for a client using Kerberos 5:

SASL-CA {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache="true"
    debug="true"
    refreshKrb5Config="true";
};

Note: The entry in jaas_client.conf must be labeled SASL-CA.

For more information on JAAS login configuration file, see
http://java.sun.com/j2se/1.5.0/docs/guide/security/jgss/tutorials/LoginConfigFile.html

Just a word of warning - if you are using the command-line sample client
application to test JAAS, Java will echo your password to the screen. If you're using Kerberos, you probably want to kinit first -- Java can read MIT Kerberos credential caches, and it will use the cached credentials rather than prompting you for a password.

2) Configure apps/sample_client/sasl-ca-client.properties to point to the SASL-CA. Here is an example:

saslca.ServerName = saslca.hostname.here
saslca.ServerPort = 4088
saslca.KeyAlgorithm = RSA
saslca.KeyStrength = 1024

To run the client, run kinit to obtain Kerberos credentials, then run ant runclient from the sasl-ca directory. The client will write its certificate chains and private keys to files in the sasl-ca directory.

These certificate chains are saved to the files named identity.cert.X and opaque.cert.X,  where X is a incrementing integer. For example, if the SASL-CA sends back an identity certificate and two other certificates (for its chain), these will be stored as identity.cert.0, identity.cert.1 and identity.cert.2. The end-entity certificate will be always be stored in .0 file. The matching private keys are stored in apps/sample_client/identity.key and apps/sample_client/opaque.key. The
private keys are not encrypted. All of the output files are DER-encoded.

To inspect the certificates, use openssl. For example:

dvm105@clarknova sasl-ca $ openssl x509 -inform der -noout -text -in identity.cert.0
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            4d:28:bc:a8:4d:56:ee:25:67:b2:ff:fc:45:4f:e4:56
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: C=US, ST=PS, L=UP, O=PSU, OU=ET, CN=sasl-ca/clarknova.et-test.psu.edu
        Validity
            Not Before: Mar 13 15:49:47 2006 GMT
            Not After : Mar 13 15:49:47 2007 GMT
        Subject: CN=DEREK VAUGHAN MORR(dvm105@psu.edu)/dvm105@psu.edu, OU=ACADEMIC SERV & EMERGING TECH, O=Pennsylvania State University, L=UNIVERSITY PARK, ST=Pennsylvania, C=US
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (1024 bit)
                Modulus (1024 bit):
                <omitted for brevity>
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DirName:/CN=DEREK VAUGHAN MORR(dvm105@psu.edu)/dvm105@psu.edu/OU=ACADEMIC SERV & EMERGING TECH/O=Pennsylvania State University/L=UNIVERSITY PARK/ST=Pennsylvania/C=US, email:dvm105@psu.edu
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment, Data Encipherment
            X509v3 Extended Key Usage: critical
                Time Stamping, TLS Web Server Authentication, TLS Web Client Authentication
    Signature Algorithm: sha1WithRSAEncryption
            <omitted for brevity>
 
Appendix – Active Directory Notes


Although it is possible to run the SASL-CA server on Windows, that setup is not recommended due to problems with the Apache Commons Daemon code on Windows. This limitation should be removed in a future version of the SASL-CA. These instructions assume the SASL-CA is running on a Unix/Linux host and cover how to configure it to use an Active Directory realm.

Requirements:

You must install the Support Tools  on your Domain Controller.

Authentication Setup

If you are using Active Directory, you will most likely want to use Kerberos as your authentication mechanism for the SASL-CA (since Active Directory uses Kerberos natively). There are a few extra steps that you will need to perform to make Active Directory work with Java 1.5.

These instructions have only been tested on Windows 2003. If you find they do not work on Windows 2000, please contact Derek Morr with a correction.

Please note: Due to an incompatbility between Sun's Java 1.5 and Windows 2000/2003, you can only use a single DES key for your Kebreros tickets. This is a rather serious security problem. This will be fixed in Sun's Java 1.6 and in the next version of Microsoft's Windows servers (Vista). IBM's Java 1.5 also supports the RC4 enctype, but their 1.5 JVM has not been tested with the SASL-CA. In the meantime, you should regularly generate a new random key for the SASL-CA's keytab created below.

To configure the SASL-CA to use Active Directory for authentication, perform the following steps on the Domain Controller:

•    Create a user principal for the SASL-CA in the MMC Active Directory Users & Groups snap-in.
•    Open a command prompt (Start Menu → Run → cmd.exe)
•    Change to the directory where you installed the Support Tools. By default, this directory is C:\Program Files\Support Tools
•    You will need to map the SASL-CA Active Directory account onto a Kerberos 5 principal name and create a keytab for this principal. The principal name MUST be named sasl-ca/fully-qualified-hostname@REALM. Use this command to create the principal:

ktpass.exe /princ sasl-ca/hostname@NAME.OF.REALM \
       /mapuser ad.user.name +rndPass \
       /out keytab.file /crypto DES-CBC-MD5

Note: ktpass is very particular about syntax. The rndPass argument must be prefixed with a + not a /.

Example: I have an Active Directory realm called TEST.EDU, and I've created a SASL-CA AD account called sasl-ca. If I want to run the SASL-CA on the host myserver.test.edu, then I would issue this command:

ktpass.exe /princ sasl-ca/myserver.test.edu@TEST.EDU \
       /mapuser sasl-ca +rndPass /out my.keytab \
     /crypto DES-CBC-MD5

This command will generate a keytab file named my.keytab.

Microsoft's TechNet site  has the exact syntax of the ktpass command on Windows 2003. For more information on the ktpass command (and the other Support Tools), go to Microsoft's Kerberos site .

Now, copy your new keytab to the SASL-CA in the sasl-ca/apps/server directory.  On the SASL-CA, edit the sasl-ca/apps/server/jaas_server.conf file. The file should look like this:

SASL-CA {
       com.sun.security.auth.module.Krb5LoginModule required
       useTicketCache="true" 
       debug="false"
       renewTGT="true"
       refreshKrb5Config="true"
       storeKey="true"
       principal="sasl-ca/hostname.of.saslca.server@REALM"
       useKeyTab="true"
       keyTab="/path/to/your/keytab/goes/here";
};


Fill in the principal and keyTab lines with the correct values. The principal value will be the value you passed to ktutil's -princ argument. The keyTab field should have the  path to the SASL-CA's keytab.

Note: After following the above directions, you may skip the “Authentication Setup – SASL-CA” section.
 
Directory Setup

The SASL-CA requires access to a directory to build Identity certificates. Microsoft Active Directory provides an LDAP directory server.  The sasl-ca.properties file in sample_config/ad/server is prefconfigured to use ActiveDirectory's LDAP schema, so you may ignore the “Directory Setup” section of this document.

Enabling Access to LDAP

Windows 2003 does not allow anonymous binds to LDAP by default. If you wish to enable anonymous binds, consult Microsoft Knowledge Base document 326690 .

Note, Windows 2000 allows anonymous LDAP binds. If you are running Windows 2000, you can ignore the following paragraph.

If you do not wish to enable anonymous binds, you can configure Active Directory to use LDAP over SSL. If your institution already has a non-Microsoft PKI in place, please consult Microsoft knowledge Base document 321051  for instructions on using a certificate issued from that PKI. If you do not have an existing PKI, you can use the Microsoft Certificate Services module. To do so, consult appendix section “LDAP-over-SSL guide”.

Configuring resolver.xml

Open the sasl-ca/apps/server/resolver.xml file. At the bottom of the file, you will see a section like this:

<JNDIDirectoryDataConnector id="activeDirectory">
    <Search filter="sAMAccountName=%PRINCIPAL%">
        <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
    </Search>
    <Property name="java.naming.factory.initial"    
    value="com.sun.jndi.ldap.LdapCtxFactory" />
    <Property name="java.naming.provider.url"
    value="ldap://your.server:636/cn=Users,dc=YOUR,dc=REALM" />
    <Property name="java.naming.security.protocol" value="ssl" />
    <Property name="java.naming.security.principal"
    value="cn=USERNAME cn=Users, DC=YOUR, DC=REALM" />
    <Property name="java.naming.security.credentials"
    value="YOUR PASSWORD" />
</JNDIDirectoryDataConnector> 

If you are using Windows 2003, fill in the appropriate values for your domain. The java.naming.provider.url property should contain the hostname of a Domain Controller and the name of your domain in the dc= elements. The java.naming.security.principal property should contain the username of a user with permission to read the cn=Users tree in AD. The java.naming.security.credentials property should contain the password for the user in java.naming.security.principal.

If you are using Windows 2000, remove the lines with java.naming.security.protocol, java.naming.security.credentials and java.naming.security.principal. Also, on the java.naming.provider.url line, remove the :636 after the server name.


 
Creating User Accounts

The SASL-CA will automatically make use of certain fields in Active Directory. When you are creating user accounts in the Active Directory Users and Computers snap-in, you may want to populate the following fields:

 

 

 
LDAP-over-SSL guide

These instructions were written for Windows 2003, but they should apply to Windows 2000 as well. If you are using Windows 2000 and experience difficulties, please consult Microsoft Knowledge Base document 320711 .

Setup the Domain Controller

To enable LDAP over SSL on a Windows 2003 Domain Controller, perform these steps:

•    Enable File and Printer Sharing for Microsoft Networks on all active network interfaces on your server. (Start → Control Panel → Network Connections → interface → Properties. Enable File and Printer Sharing for Microsoft Networks.)

•    Install and enable IIS and ASP. (Start → Control Panel → Add or Remove Programs → Add/Remove Windows Components → Application Server → IIS). If you have already installed IIS, ensure that it's enabled.

•    Enable the following services:
•    HTTP
•    HTTP SSL
•     IIS Admin Service
•    Remote Procedure Call (RPC)
•    Security Accounts Manager

•    Now, install Certificate Services. (Start → Control Panel → Add or Remove Programs → Add/Remove Windows Components → Certificate Services). Follow the on-screen instructions for configuring Certificate Services. Be sure to configure it as an Enterprise Root CA, assuming your organization does not already have such a machine.

•    Configure your CA to automatically issue certificates to services. (Start → Administrative Tools → Domain Controller Security Policy → Public Key Policies → Automatic Certificate Request.) Right-click in the right pane of the window, choose New -> Automatic Certificate Request. in the Automatic Certificate Request Setup Wizard, choose "Computer".

•    Wait. Active Directory components will now automatically connect to your CA and obtain certificates. This can take several minutes.

•    Create a user that can read attributes in the CN=Users,dc=your,dc=domain,dc=name tree. Use the ADSI Edit tool in the Windows Support Tools to give this user read-only access to the CN=Users tree. Make a note of the user's username and password, as you'll need it later to configure resolver.xml.

•    To test if the steps above succeeded, use the ldp.exe tool in C:\Program Files\Windows Support Tools to perform an SSL bind to LDAP. In the File → Connect dialog, be sure to enable SSL, change the port to 686 and use the userid and password you created in the previous step.


Setup the SASL-CA

You are now ready to configure the SASL-CA to connect to a Domain Controller.

•    Copy the CA's signing cert to your SASL-CA machine (if they're on different machines). The signing cert will be in C:\fully.qualified.hostname.crt on the Domain Controller running the Enterprise CA.

•    You need to put this .crt file into a JKS-formatted Java keystore on the SASL-CA. On the SASL-CA server, change to the sasl-ca directory and issue this command:

keytool -import -file fully.qualified.hostname.crt \
    -keystore ldap.jks

You will be asked if you wish to trust this certificate. Select "yes". Next, you will be prompted for a password on the keystore. Enter a password and make a note of it. Finally, copy the keystore into the sasl-ca/apps/server directory.

(Note, the next step involves editing the master control script for the SASL-CA. Make a backup of sasl-ca/build.xml first!)

•    Edit sasl-ca/build.xml. Scroll to the <target name="runserver"> line. Following it, you should see several lines that start with <jvmarg. You will need to insert the following two lines after the last <jvmarg:

<jvmarg value="-Djavax.net.ssl.trustStore=${server_conf_dir}/ldap.jks" />
<jvmarg value="-Djavax.net.ssl.trustStorePassword=keystorePassword" />

Where keystorePassword is the password you assigned to ldap.jks in the previous step.