Read Me

IMPORTANT - DO NOT USE

The use of SVN and SourceForge for the CMP code has been DISCONTINUED.
This SVN repository is only left online to cater for HISTORIC research.

*** Please use the new GIT repository ***

https://github.com/mpeylo/cmpossl

IMPORTANT - DO NOT USE







README file for the CMP (RFC 4210) extension for OpenSSL

Written by
  - Martin Peylo <martin.peylo at nokia.com>
  - Miikka Viljanen <mviljane at users.sourceforge.net>

With significant contributions by
  - David von Oheimb <David.von.Oheimb at siemens.com>


################################################################################
LICENSES
################################################################################

The CMP for OpenSSL extension uses the same BSD style license as OpenSSL.

OpenSSL uses a BSD style license
 - There are some restrictions on using the library in a product.
   Check this first, before shipping it to your customers!

Cryplib uses a Sleepycat style license
 - This makes it payware for commercial use!


################################################################################
INSTALLATION
################################################################################

Change into the 'src' directory and launch 'make' to build everything.

The Makefile has several handy targets:

- 'all' (default):  download, extract, configure and build everything.
- 'openssl': configure and build the OpenSSL libraries with CMP

Experimental and historic make targets:

- 'openssl_patch_0.9.8g': calculate a CMP extension patch against the offical
                          OpenSSL release version 0.9.8g source.
- 'cryptlib': (not yet download), unzip and build the Cryptlib libary
- 'cmpclient': make openssl, build and install cmpclient
- 'cmpserver': make cryptlib, build and install cmpserver-cl
- 'lighttpd': add the cmpserver module to lighttpd src and compile

Check the Makefiles for more info!


################################################################################
USAGE
################################################################################

A CMP client is available in the /apps/ directory and can be used like
"openssl cmp".  For detailed instractions refer to the "cmp" man page
included in the code (as cmp.pod before manpages are installed).

You can trace and dissect CMP traffic with Wireshark.


################################################################################
USAGE with the historic cryptlib-based CMP server
################################################################################

Note that the cryblib-based CMP server is not properly maintained.  The client
can be used with any CMP server implementation as it comes with e.g. Insta
Certifier or EJBCA.


In the /scripting directory are some examles how to use the applications.

	* You HAVE to adjust the "settings.sh" file to your needs! *


A complete session showing an "Initial Initialization" and a "Key Update" would
look like this:

Create a CA certificate (and key):
	./srv_create_ca_cert.sh

Now copy the CA certificate to the certs directory of your client. This can be
done only once, then the DB has to be purged.

	./srv_add_pki_usr.sh

This produces output like:

	SUCCESS init
	SUCCESS add random
	SUCCESS open certstore
	SUCCESS creating certificate
	SUCCESS storing the PKI User
	User= XZ6XE-DHTBC-VGWAV
	Password= CP9GR-4R88S-KHDLX-W3JNW
	RevPW= X8LYV-45E4X-J2CV3-LH3VQ
	DECODED, HEX: User= F9520CF108A66A0260
	Password= 7E67E9FEF41271AAB4CA1940
	RevPW= 9569EB64D551814F2A3E66E0
	SUCCESS destroying certificate
	SUCCESS close certstore
	SUCCESS shutting down cryptlib

Remember the Values from the "DECODED, HEX: User="- and the following
"Password="-line, don't use the "DECODED" values!

Start the CA as daemon:

	./srv_run_daemon.sh

On the client side we do an "Initial Request", using the user and password value
from above:

	./do_ossl_ir.sh USER PASSWORD

Then we can do a "Key Update":

	./do_ossl_kur.sh



################################################################################
PREREQUISITES to use the histroic cryptlib-based CMP server
################################################################################

The CA using Cryptlib needs a ODBC database to store information about the PKI
users.

The ODBC database has to be named "myodbc". This can be changed in the source of
cmpserver.

The /etc/unixODBC/odbc.ini file on OpenSuSE 10.2 might look like this:

	[myodbc]
	Driver       = /usr/lib/unixODBC/libmyodbc3.so
	Description  = MySQL ODBC 2.50 Driver DSN
	SERVER       = localhost
	PORT         = 3306
	USER         = odbc
	Password     = CqRXRKm39uQUrN:2
	Database     = odbc
	OPTION       = 3
	SOCKET       =

Here the MySQL database has the name "odbc".