================
The package ``sucses.tar.gz'' includes source code of SUCSES library for Linux, Security mediator, CA utilities and SAS patch for OpenSSL
libraries.
Platform:
-Linux
-OpenSSL.0.9.6 and its compatible version. To support SAS protocol, OpenSSL source code is required.
Download:
The package can be downloaded from http://sconce.ics.uci.edu/sucses/
Untar/unzip:
Use ``tar -xzf sucses.tar.gz'' to unzip the package. It creates a new directory ``sucses'' and extracts all the files into it.
===================
1.1 Setup OpenSSL path:
The Makefile uses the following for OpenSSL
OPENSSL_DIR = $(HOME)/ssl
OPENSSL_INCLUDE = -I$(OPENSSL_DIR)/include
OPENSSL_LIBS = -L$(OPENSSL_DIR)/lib -lcrypto
You may create a static link ssl in your home directory to OpenSSL, or change the Makefile with your own OpenSSL path.
1.2 SAS Patch for OpenSSL:
If you do not use SAS protocol, skip this part. To let OpenSSL libraries support SAS objects, e.g. X509 extensions for SAS, the
SAS patch should be applied to OpenSSL code.
The patch includes:
a) openssl.c
b) req.c
c) sasobj.h
d) v3_sas_ext.c
e) openssl.cnf
- Merge a) and b) with the original OpenSSL openssl.c and req.c, ( both are in $(OPENSSL_DIR)/apps directory). If you're using openssl.9.6a, simply overwrite the original files.
- Put sasobj.h and v3_sas_ext.c into $(OPENSSL_DIR)/crypto/x509v3 directory. As the other OpenSSL header files, create a static link for sasobj.h in $(OPESSL_INCLUDE).
- Make changes to the Makefile in $(OPENSSL_DIR)/cryto/x509v3 so that v3_sas_ext.c and sasobj.h are complied as part of libcrypto.a
- Rebuild OpenSSL toolkit.
- openssl.cnf is the configuration file for demoCA program. See Section 5 for detailed description.
================
2.1 Chang directory into the newly created sucses directory.
2.2 Run "make -f Makefile" or "make". If it succeed, it outputs the following:
- libsucses/libsucses.a: the sucses library
- ca_tool/make_bundle: the ca utility program to generate mRSA bundles.
- sem/sem: the security mediate (SEM) program
- ibmrsa/ibe: identity-base mRSA tools to create identity-based certificate and key.
- sucses_tool/sas_tool: sas toolkit for generating SAS context and request.
=================
*Synopsis: sem -key <key> -cert <cert> [-crl <crl>] -ca_cert <ca>
*Options:
-key <key>
Specify SEM's private key. This should be a key file in PEM
format.
-cert <cert>
Specify SEM's public key certificate. This should be a X509
certificate file in PEM format.
-crl <crl>
Optional. Specify the current CRL, which is a X509 file in
PEM format.
-ca_cert <ca>
Specify the Issuer's certificate, which is needed for
certificate verification.
*Description:
When sem is up, it listens to udp port 65432. For mRSA, it is a stateless server, i.e. it does not keep state of each client. On the other hand, it is a stateful server for SAS protocol. For each client, it create a subdirectory under "sas" directory with the name being the client's x509 name digest, where it saves the client's certificate, all generated signatures and signed hash tokens.
==================================================
Users in mRSA setting do not generate their RSA private keys by themselves. The trusted party (e.g. CA) generates all keys and issues bundles and certificates.
==========
The CA administrator can run the normal OpenSSL demoCA to generate RSA certificate and key as requested. Then run "make_bundle" utility to issue user bundles, which contains user certificates. The output bundle is in pkcs12 format.
The synopsis of "make_bundle" is the following
*Synopsis: make_bundle -key <mrsakey> -cert <mrsacert> -sem <semcert> -cacert <cacert> -cakey <key> -p <passwd> -out <bundle>
*Options:
-key <mrsakey>
Specify the user's private key to split. It is in PEM format.
-cert <mrsacert>
Specify the user's certificate PEM file.
-sem <semcert>
Specify the certificate of those who can provide mRSA
services to the user.
-cacert <cacert>
Specify the CA's certificate.
-cakey <key>
Specify CA's private key, used in signing bundles
-p passwd
Password used to encrypt the bundle.
-out <bundle>
Specify the output file name.
*Description:
Given a client's private key and certificate, make_bundle program generate the corresponding user bundle which is encrypted with the given password. SEMs' bundles are envelopes, which are signed by CA and encrypted with SEMs' public keys.
An example usage is:
make_bundle -key mrsakey.pem -cert mrsacert.pem semcert1k.pem -cacert cacert.pem -ca_key cakey.pem -p asdf -out bundle.p12
=======================
In identity based mRSA schemes, for each requesting organization the CA administrator first should initialize a RSA setting by generating a RSA certificate and key pair, of which the certificate is the organization certificate and private key contains the factorization of RSA modulus. Note that the organization certificate is a normal X509 certificate. See OpenSSL documents for details of issuing a certificate.
To issue a bundle for an individual user within certain organization, CA first runs "ibe" command to generate a new RSA private key for the client. The synopsis of ibe is the following.
*Synopsis: ibe -new -in <inkey> -out <outkey> -addr <address> -enc -in <msg> -out <cipher> -addr <addr> -org <orgcert>
*Options:
-new
Generate a new RSA private key based on <address> using the same RSA setting as in the given private key <inkey>.
-enc
Encrypt <msg> using RSA. The public exponent is derived from <addr> and RSA modulus is the in <orgcert>
-addr <address>
The user's email address or other identity as an ASCII string.
-in <inkey>
Input file. It is the private key in PEM format for key ID-based key generation or the message to encrypt.
-out <cipher>
Output file. It is the output private key in PEM, corresponding to the give identity <address> or the ciphertext after encryption.
-org <orgcert>
Organization certificate. The public key inside must be RSA public key.
*Description
ibe program can generate a RSA private key. Its corresponding public key is derived from an identity and they share the same RSA setting with a given RSA private key. ibe program can also be used for identity based RSA encryption.
An example usage is:
ibe -in orgkey.pem -out idkey.pem -addr id@abc.com
After getting the new private key, CA runs "make_bundle" to split the key and generate bundle as in normal mRSA. The organization can be used as the user's own certificate in the command line.
===============================
A SAS client needs the following
1. SAS context file -- A file storing the user's hash token and present state.
2. SAS certificate -- A X509 certificate with SAS extensions
========================
A SAS client need to initialize its local setting, including the context , which contains all the hash tokens to use, the sas certificate request. The clients can use "sas_tool" to create those files. Its synopsis is as follows
*Synopsis: sas_tool -c <ctxname> -i <certreq> -ca <cacert>
*Options:
-c <ctxname>
Specify the output context file.
-i <certreq>
Specify the output SAS certificate request file.
-ca <cacert>
Specify the CA certificate file
An example is:
sas_tool -c sasctx -i sasreq.pem -ca cacert.pem
*Description:
To generate the certificate request, sas_tool prompts the client to input the required information for certificate request. Besides those commonly required attributes in OpenSSL request generation, it will prompt the user:
- Hash Type: This specifies the hash algorithm used in generating hash chain. Input 0 for MD5, 1 for SHA1
- Chain Length: This specifies the hash chain length. The default value is 100.
- Server Certificate: Input SEM's certificate file name. The certificate file must exist.
- Server Address: Input the SEM's hostname
All the information is stored in "sasreq.info". Based on them, sas_tool initializes a hash chain and writes it into <ctxname>. It puts the root of the chain (the last generated hash token) into file "sasroot.key". Then it calls script "cert_request" under the same directory to generate a certificate request <certreq>.
Note that openssl.cnf should enable the SAS request attributes section. A sample request section is like the following. See the openssl.cnf in sslpatch directory for a complete version.
[ req_sas_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
SAS_ATTR_KeyPara = The Maximum of Hash Times
SAS_ATTR_KeyId = Input SAS Key File Name
SAS_ATTR_ServerName = Input SAS Server Name:
SAS_ATTR_ServerSN = Input SEM Certificate Serial NO.
SAS_ATTR_HashType = Input SAS Hash Type:
SAS_ATTR_HashType_default = MD5
....
===========================
When the SAS user have the certificate request, it applies to CA to get the certificate.
The command for the CA to issue a SAS certificate is the same as a normal certificate. However, to support SAS extension, the openssl.cnf should include SAS objects in its x509 extension section. A sample section is like the following. See openssl.cnf in sslpath for a complete version.
[ usr_sas_cert ]
# These extensions are added when 'ca' signs a request with sas
# extension
basicConstraints=CA:FALSE
# This will be displayed in Netscape's comment listbox.
nsComment = "OpenSSL Generated Certificate"
# The following SAS extensions are added to X509
SASPublicKeyIdentifier = hash
SASPublicKeyPara = para
SASServerName = name
SASServerSerialNumber = sn
SASHashType = type
...