Configuring the RI
Description: This document describes how to use the development kit for the Java Card 3 Platform, Connected Edition, Version 3.0.2, to develop applet applications, web applications, servlets, and extended applets
Date: December 2009

C H A P T E R 12

Configuring the RI

This chapter describes the options used to configure a custom RI. This chapter is useful only if you have a source release of the development kit. For real cards, there are a few items such as Protection Domains and Certificates that must be setup at manufacturing time. The RI provides a means of configuring some factory settings by using the `config.properties` file under the `lib` folder.

This chapter contains the following sections:

- Configuring Authenticators

- Creating Custom Protection Domains

- Configuring SSL Support

##

Configuring Authenticators

In the `lib\config.properties` file, the following properties must be added to add an authenticator:

- `authenticator`.index.`uri`

- `authenticator`.index.`factory`

- `authenticator`.index.`pin`

- `authenticator`.index.`digest`

The following items describe the contents of the preceding list of properties:

- index is a zero based number. At startup, the RI starts reading these properties beginning with index zero and creates authenticators until the sequence is broken.

- The `URI` property provides the SIO uri used for this authenticator.

- The `factory` property provides the factory class. For example, `com.sun.javacard.security.PINSessionAuthenticatorFactory.`

- The `pin` property provides the pin for this authenticator.

- The `digest` property is set to `true` or `false` depending on if the provided authenticator is of type `digest` or not.

##

Creating Custom Protection Domains

The Java Card 3 platform RI assigns a protection domain to an application based on the certificate used to sign the application bundle with the Packager tool. In the `lib\config.properties` file the following properties must be added to add a new protection domain:

- `pd.`pd-index`.certificate`

- `pd.`pd-index`.include.`include-index

- `pd.`pd-index`.exclude.`exclude-index

The following items describe the contents of the preceding list of properties:

- All the indexes (pd-index, include-index, and exclude-index) are zero based numbers.

- The `certificate` property provides the BASE-64 encoded certificate.

- The include.include-index property provides a list of permissions that should be included for this protection domain.

- The exclude.exclude-index property provides a list of permissions that should be excluded for this protection domain.

### Creating a Custom Keystore

A custom keystore can be crested by using the `keytool` command to generate the certificates and private keys. The `keytool` command runs in batch mode without prompting for input values.

Enter the following `keytool` command and options on the command line:

    keytool -genkey -alias alias -keyalg RSA
    keytool -selfcert -alias alias
    keytool -list -rfc
    java DumpPrivateKey

This is how the `PolicyManager.java` certificate and key were generated.

For scripting, use the following `keytool` command:

    keytool -keystore keystore -storepass keystore-password \
    	-alias alias -keypass alias-password -genkey \
    	-keyalg RSA -dname "cn=X, ou=U, o=O, c=US"

##

Configuring SSL Support

An SSL implementation requires four algorithms:

- digital signature

- key establishment

- bulk encryption

- message digest

Note - It is beyond the scope of this document to fully describe SSL configuration and setup. There are many excellent books on this subject, and we direct advanced users to this literature.

### Adding SSL Support

The Java Card 3 platform implements the SSL key establishment algorithm through the use of the following set of certificates and keys as key=value pairs in `lib\config.properties`. In the file `lib\config.properties`, the following properties must be added to add SSL support:

- `ssl.trusted.ca.#` - Index-based property to specify BASE-64 encoded certificates of the CA root that Java Card 3 RI trusts. Used in the normal SSL handshake. This property is index based. User can configure multiple CA roots by appending the index at the end of the property, such as `ssl.trusted.ca.0`, `ssl.trusted.ca.1`, and `ssl.trusted.ca.2`. The indexes are assumed to be in sequence starting with zero. When the sequence is broken, it is assumed the properties have ended.

- `ssl.accepted.issuer.#` - Index based property to specify BASE-64 encoded accepted issuer's certificates. Used only in client authentication handshake. User can configure multiple issuer certificates by appending the index at the end of the property, such as `ssl.accepted.issuer.0`, `ssl.accepted.issuer.1`, and `ssl.accepted.issuer.2`. The indexes are assumed to be in sequence starting with zero. When the sequence is broken, it is assumed the properties have ended.

- `ssl.selfIdentityAsServer` - BASE-64 encoded server certificate. This is the certificate that the Java Card 3 platform uses to identify itself when operating in SSL server mode.

- `ssl.selfIdentitySSLPrivateKeyExp` - BASE-64 encoded private key (exponent) of the server certificate.

- `ssl.selfIdentitySSLPrivateKeyMod` - BASE-64 encoded private key (modulus) of the server certificate.

- PSKIdentityHint - String value used in the PSK protocol as a server side identity hint.

### Custom Certificates and Keys

Custom implementations require that the developer generate corresponding custom certificates and keys. The certificates and keys are used by the Card Manager to verify the digital signature of a WAR file and are used in SSL and HTTPS transactions.

Generating an SSL Certificate

1. Generate a server key and certificate signing request (csr):

`openssl genrsa -out s.key 1024`

`openssl req -new -key s.key -out server.csr`

2. Generate a CA key and self-signed certificate:

`openssl genrsa -out ca.key 1024`

`openssl -req new -x509 -days 365 -key ca.key -out ca.crt`

3. Sign the csr and create the certificate:

`sign.sh server.csr`

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.