Runtime options for sample SSL programs

General Comments

The programs do have some flexibility, but I tried to keep the examples small, and so the run-time options you have are limited. As much as possible, the way you specify these options is the same for Java and C. The things you can choose at run-time are:

What classes of cipher suites you want to use
What version of the SSL protocol to use
What certificate you want a server to send, and where clients should look for a source of trusted certificates (for cipher suites that require server authentication)
What kind of run-time tracing you want enabled

There are some examples at the end of this page.

Cipher Suites

There are three "classes" of cipher suites that the progams know about, which you specify by using a series of characters in the "ciphers" argument. These are:

Suites that require server authentication using a certificate (indicated by using a 'c' in the command-line). The SSL handshake in this case will involve the server sending a certificate to the client, and the client checking that it's happy with the CA of the certificate.
Suites that require no server authentication (indicated by using a 'a' in the command-line). Such suites ("anonymous") have the advantage that you don't need to muck about with certificate/key/passwords but are less secure, see all the warnings in the docs
Suites that have no encryption or authentication (indicated by using a 'n' in the command-line). These offer no security, and so I believe they are meant to be used for testing purposes. These are only available in OpenSSL (I don't think the standard JSSE implementation offers them).

When using the programs, you use combinations of these letters to indicate what suites you want, e.g. "cn" would mean use types 1 and 3. By turning on tracing, you can get the programs to display what ciphers are in effect.

Top

Protocols

There are different SSL protocols available depending on whether you're using OpenSSL or JSSE. The programs expect you to use a number, where appropriate, to indicate what protocol you're interested in:

TLSv1 is indicated using "1"
SSLV2 is indicated using "2"
SSLv3 is indicated using "3"
SSLv23 is indicated using "4"

The client programs require that you specify what protocol you want to communicate with. For OpenSSL, you also have to provide this information for the server, but if you use "4" then the server will accept SSLv2, SSLv3 and TLSv1. JSSE just accepts whatever is sent in.

For JSSE, 1 and 3 are available; OpenSSL lets you specify any of the four. See the documentation for SSL_CTX_new(3) for more info.

Top

Server Certificates

If you're using non-anonymous cipher suites, then the server program will want to send a certificate to the client, and you have to tell the server where to find the certificate, and the client what certificates it should trust. Typically a server will also require a private key, as well as a password for that key.

So when you run one of the server programs you may have to provide these three pieces of information:

For the JSSE environment, you use runtime properties to provide the information to the program:

javax.net.ssl.keyStore points at the keystore containing a server certificate and private key
javax.net.ssl.keyStorePassword is the password for the keystore

For VMS/UNIX, you use DCL symbols/environment variables to provide this information:

servercert points to a PEM file containing the server certificate
privatekey points to a PEM file containing the server certificate's private key
serverpwd is the password for the private key. If you don't specify one, then OpenSSL will prompt interactively

When you run one of the client programs, you may have to provide information about where it can find trusted certificates. On Java you use:

javax.net.ssl.trustStore to point at a keystore containing a source of trusted certificates

For VMS/UNIX, you use the DCL symbol/environment variable:

truststore to point to a PEM file containing one or more trusted certificates.

Top

Runtime tracing

All the programs can display information about what they're doing at run-time. You can turn this on by specifying 't' in the trace argument for each program. Additionally for the Java programs you can use 'j' which will enable Java SSL debugging messages (which can be useful, but voluminous). I didn't come across an equivalent OpenSSL run-time trace facility.

Top

Examples

The commands shown for running the C programs are valid for VMS or UNIX, but require you to define a suitable foreign command on VMS, e.g. $ ExampleSSLServer:==$disk:[dir]ExampleSSLServer.exe. Note that some of the commands are split on to several lines for readability.

Run the C server, listening on port 6000 for TLSv1 protocol, enabling anonymous ciphers and turning on program tracing:
```
  $ ExampleSSLServer 6000 a 1 t
```
Run the JSSE client, talking to "server:6000" in the previous example:
```
  > java ExampleSSLClient server 6000 a 1
```
Run the JSSE server, listening on port 6000, enabling non-anonymous ciphers, and providing the location of a certificate keystore and password:
```
  > java -Djavax.net.ssl.keyStore="my.keystore" 
         -Djavax.net.ssl.keyStorePassword="mypassword" ExampleSSLServer 6000 c
```
Run the C client on UNIX, talking to "server:6000" in the previous example, providing the location of a PEM file containing a CA chain:
```
  csh> setenv truststore cacert.pem
  csh> ExampleSSLClient server 6000 c 3
```
Run the C server on VMS, listening on port 6000 for any SSL protocol, enabling non-anonymous ciphers, and providing the location of a server certificate keystore and password:
```
  $ servercert="server-cert.pem"
  $ privatekey="private-key.pem"
  $ serverpwd="password"
  $ ExampleSSLServer 6000 c 4
```
Run the JSSE client with all tracing turned on, talking to "server:6000" using TLSv1 in the previous example, and providing the location of a trustworthy CA chain:
```
  > java -Djavax.net.ssl.trustStore="trust.keystore" ExampleSSLClient server 6000 c 1 jt
```

Top

Go back to Nick's JSSE and OpenSSL notes