spki.demo
Class KeyChain

java.lang.Object
  |
  +--spki.demo.KeyChain

public class KeyChain

extends Object

spki.demo KeyChain class.

Version:

$Id: KeyChain.java,v 1.11 2002/07/26 09:02:59 tep Exp $

Author:

Tep Narula <tep@win.trlabs.ca>

Field Summary

private static String	__ME This class's full name.
private HashDB	authchain_db the authorization-chain database object.
(package private) static String	AUTHCHAIN_DBNAME the authorization-chain database filename suffix.
private static String	CERT_DBNAME the live master certificates database filename suffix.
private static int	CERT_INDEX the position of the master certificate in each element of the place-holder database.
static String	CERTIFICATION_TAG_STRING
private PublicKey	certifier the key-chain certifier's public key.
private static String	CERTIFIER_KEY_DBKEY the certifier public key's database index key.
private String	db_id
static String	DBPATH databases's pathname prefix.
static int	DEFAULT_KEY_LENGTH
static String	DEFAULT_PUB_ALG
private HashDB	holder_db the place-holder database object.
private static String	HOLDER_DBNAME the place-holder database filename suffix.
private HashDB	issuer_db the issuers' public keys database object.
private static String	ISSUER_DBNAME the issuers' public keys database filename suffix.
private int	key_length the key-chain default key-length in bits.
private static String	KEY_LENGTH_DBKEY the key-length's database index key.
private HashDB	keypool_db the key-pool database object.
private static String	KEYPOOL_DBNAME the key-pool database filename suffix.
private HashDB	main_db the main database object.
private static String	MAIN_DBNAME the main database filename suffix.
private Certificate	master_cert the key-chain master key-pair's certificate.
private static String	MASTER_CERT_DBKEY the master certificate's database index key.
private String	master_keyid the key-chain master key-pair's key-id.
private static String	MASTER_KEYPAIR_DBKEY the master key-pair's database index key.
private PrivateKey	master_privkey the key-chain master key-pair's private key.
private PublicKey	master_pubkey the key-chain master key-pair's public key.
private HashDB	mastercert_db the live master certificates database object.
static int	MINIMUM_CODELENGTH
static int	MINIMUM_POOLSIZE
private String	passcode the key-chain access-control passcode.
private static char[]	PASSCODE_ALPHABET the alphabet of valid digits for the initial random passcode, which simply consists of lower-case hexadecial digits (0-9 and a-f).
private static String	PASSCODE_DBKEY the passcode's database index key.
private HashDB	privkey_db the live private-keys database object.
private static String	PRIVKEY_DBNAME the live private-keys database filename suffix.
private static int	PRIVKEY_INDEX the position of the private key in each element of the keypool and place-holder database.
private String	pub_alg the key-chain's public-key algorithm-id.
private static String	PUB_ALG_DBKEY the public-key algorithm-id's database index key.
private HashDB	pubkey_db the live public-keys database object.
private static String	PUBKEY_DBNAME the live public-keys database filename suffix.
private static int	PUBKEY_INDEX the position of the public key in each element of the keypool and place-holder database.
private int	state
static int	STATE_ALIVE
static int	STATE_DEAD
static int	STATE_INITIALIZED
static int	STATE_PERSONALIZED
static int	STATE_REGISTERED
static String[]	STATES

Constructor Summary

KeyChain()
Create a brand new key-chain, using the default algorithm and key-length.

KeyChain(String db_id)
Restore a live key-chain with the specified database id.

KeyChain(String pub_alg, int key_length)
Create a brand new key-chain, using the specified algorithm and key-length.

Method Summary

private void	activateKeyPair(String passcode, String keyid) activate the key-pair specified by the given key-id.
void	addAuthChain(String passcode, Sequence chain) add a new authorization chain to the key-chain's database, add the root issuer to the issuer list if neccessary, and activate the associated subject principal.
private void	addIssuer(String passcode, PublicKey issuer) store a new issuer's public key in the issuer database.
(package private) boolean	authenticate(String passcode) verify the given passcode.
private String	buildDBname(String dbname)
void	changePassCode(String oldcode, String newcode) change the passcode to the given one.
private void	closeDB() to be used by the finalize() method only!
private void	construct()
private void	deactivateKeyPair(String passcode, String keyid) deactivate (read: permanently purge the private key) the key-pair specified by the given key-id.
private PrivateKey	fetchActivePrivateKey(String keyid) search a private key with the given key-id from the active private key database.
private PublicKey	fetchActivePublicKey(String keyid) search a public key with the given key-id from the active private key database.
Sequence	fetchNewKeyPair(String passcode) get a fresh key-pair from the key-pool.
protected void	finalize()
Sequence	getAuthChain(String passcode, String chainid) search and return an authorization chain with the given chain-id.
Principal	getCertifier() get the certifier's principal.
String	getDBId() get this key-chain's database id.
int	getKeyPoolSize(String passcode) get the current key-pool size.
Certificate	getMasterCert() get the master-key's certificate.
PublicKey	getMasterKey() get this key-chain's master public-key.
Certificate	getNewPrincipal(String passcode) get a fresh unused principal.
int	getState() get the current state.
String	initialize(PublicKey certifier, Certificate cert) initialize this key-chain with the given cretifier and certificate.
private void	openDB() to be used by construct() and restore() only!
void	personalize(String oldcode, String newcode, int poolsize) personalize this key-chain with the given new passcode and initial key-pool size.
void	refreshKeyPool(String passcode, int poolsize) create/refresh the key-pool to the given pool-size or MINIMUM_POOLSIZE constant, whichever is bigger.
RegistrationRequest	register(String passcode, PublicKey issuer, Sexp nonce, Tag capability) create a registration request with the given issuer's public-key, registration nonce, and capability.
AuthorizationRequest	request(String passcode, Principal monitor, String chainid, Sexp nonce, Principal issuer, Tag capability) create an authorization request for the given monitor's princpal, authorization chain-id, request nonce, issuer's principal, and capability.
void	restore(String db_id)
Certificate	transfer(String passcode, String keyid, RegistrationRequest request) transfer a capability from a principal of this key-chain to another principal according to the request and purge the issuing private key.

Methods inherited from class java.lang.Object

, clone, equals, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

__ME

private static final String __ME

This class's full name.

DBPATH

public static final String DBPATH

databases's pathname prefix.

MAIN_DBNAME

private static final String MAIN_DBNAME

the main database filename suffix.

main_db

private HashDB main_db

the main database object.

KEYPOOL_DBNAME

private static final String KEYPOOL_DBNAME

the key-pool database filename suffix.

keypool_db

private HashDB keypool_db

the key-pool database object.

MINIMUM_POOLSIZE

public static final int MINIMUM_POOLSIZE

HOLDER_DBNAME

private static final String HOLDER_DBNAME

the place-holder database filename suffix.

holder_db

private HashDB holder_db

the place-holder database object.

PRIVKEY_DBNAME

private static final String PRIVKEY_DBNAME

the live private-keys database filename suffix.

privkey_db

private HashDB privkey_db

the live private-keys database object.

PUBKEY_DBNAME

private static final String PUBKEY_DBNAME

the live public-keys database filename suffix.

pubkey_db

private HashDB pubkey_db

the live public-keys database object.

CERT_DBNAME

private static final String CERT_DBNAME

the live master certificates database filename suffix.

mastercert_db

private HashDB mastercert_db

the live master certificates database object.

ISSUER_DBNAME

private static final String ISSUER_DBNAME

the issuers' public keys database filename suffix.

issuer_db

private HashDB issuer_db

the issuers' public keys database object.

AUTHCHAIN_DBNAME

static final String AUTHCHAIN_DBNAME

the authorization-chain database filename suffix.

authchain_db

private HashDB authchain_db

the authorization-chain database object.

db_id

private String db_id

PRIVKEY_INDEX

private static final int PRIVKEY_INDEX

the position of the private key in each element of the keypool and place-holder database.

PUBKEY_INDEX

private static final int PUBKEY_INDEX

the position of the public key in each element of the keypool and place-holder database.

CERT_INDEX

private static final int CERT_INDEX

the position of the master certificate in each element of the place-holder database.

MASTER_KEYPAIR_DBKEY

private static final String MASTER_KEYPAIR_DBKEY

the master key-pair's database index key.

PASSCODE_DBKEY

private static final String PASSCODE_DBKEY

the passcode's database index key.

CERTIFIER_KEY_DBKEY

private static final String CERTIFIER_KEY_DBKEY

the certifier public key's database index key.

MASTER_CERT_DBKEY

private static final String MASTER_CERT_DBKEY

the master certificate's database index key.

PUB_ALG_DBKEY

private static final String PUB_ALG_DBKEY

the public-key algorithm-id's database index key.

KEY_LENGTH_DBKEY

private static final String KEY_LENGTH_DBKEY

the key-length's database index key.

certifier

private PublicKey certifier

the key-chain certifier's public key.

master_pubkey

private PublicKey master_pubkey

the key-chain master key-pair's public key.

master_privkey

private PrivateKey master_privkey

the key-chain master key-pair's private key.

master_keyid

private String master_keyid

the key-chain master key-pair's key-id.

master_cert

private Certificate master_cert

the key-chain master key-pair's certificate.

DEFAULT_PUB_ALG

public static final String DEFAULT_PUB_ALG

pub_alg

private String pub_alg

the key-chain's public-key algorithm-id.

DEFAULT_KEY_LENGTH

public static final int DEFAULT_KEY_LENGTH

key_length

private int key_length

the key-chain default key-length in bits.

STATE_DEAD

public static final int STATE_DEAD

STATE_ALIVE

public static final int STATE_ALIVE

STATE_INITIALIZED

public static final int STATE_INITIALIZED

STATE_PERSONALIZED

public static final int STATE_PERSONALIZED

STATE_REGISTERED

public static final int STATE_REGISTERED

state

private int state

STATES

public static final String[] STATES

passcode

private String passcode

the key-chain access-control passcode.

MINIMUM_CODELENGTH

public static final int MINIMUM_CODELENGTH

PASSCODE_ALPHABET

private static final char[] PASSCODE_ALPHABET

the alphabet of valid digits for the initial random passcode, which simply consists of lower-case hexadecial digits (0-9 and a-f).

CERTIFICATION_TAG_STRING

public static final String CERTIFICATION_TAG_STRING

Constructor Detail

KeyChain

public KeyChain()
         throws SPKIException

Create a brand new key-chain, using the default algorithm and key-length. This constructor performs the following tasks:

generate and store the master key-pair,

initialize all the databases used by the key-chain.

See Also:

KeyChain(String,int)

KeyChain

public KeyChain(String pub_alg,
                int key_length)
         throws SPKIException

Create a brand new key-chain, using the specified algorithm and key-length.

See Also:

KeyChain()

KeyChain

public KeyChain(String db_id)
         throws SPKIException

Restore a live key-chain with the specified database id.

See Also:

KeyChain(), KeyChain(String,int)

Method Detail

finalize

protected void finalize()

Overrides:

finalize in class Object

getState

public int getState()

get the current state.

getDBId

public String getDBId()

get this key-chain's database id.

getMasterKey

public PublicKey getMasterKey()

get this key-chain's master public-key.

initialize

public String initialize(PublicKey certifier,
                         Certificate cert)
                  throws SPKIException

initialize this key-chain with the given cretifier and certificate.

Returns:

the initial random passcode.

getCertifier

public Principal getCertifier()

get the certifier's principal.

getMasterCert

public Certificate getMasterCert()

get the master-key's certificate.

personalize

public void personalize(String oldcode,
                        String newcode,
                        int poolsize)
                 throws SPKIException

personalize this key-chain with the given new passcode and initial key-pool size.

changePassCode

public void changePassCode(String oldcode,
                           String newcode)
                    throws SPKIException

change the passcode to the given one.

refreshKeyPool

public void refreshKeyPool(String passcode,
                           int poolsize)
                    throws SPKIException

create/refresh the key-pool to the given pool-size or MINIMUM_POOLSIZE constant, whichever is bigger.

getKeyPoolSize

public int getKeyPoolSize(String passcode)
                   throws SPKIException

get the current key-pool size.

register

public RegistrationRequest register(String passcode,
                                    PublicKey issuer,
                                    Sexp nonce,
                                    Tag capability)
                             throws SPKIException

create a registration request with the given issuer's public-key, registration nonce, and capability.

getAuthChain

public Sequence getAuthChain(String passcode,
                             String chainid)
                      throws SPKIException

search and return an authorization chain with the given chain-id. the chain-id is simply the hash value of the whole chain.

addAuthChain

public void addAuthChain(String passcode,
                         Sequence chain)
                  throws SPKIException

add a new authorization chain to the key-chain's database, add the root issuer to the issuer list if neccessary, and activate the associated subject principal.

getNewPrincipal

public Certificate getNewPrincipal(String passcode)
                            throws SPKIException

get a fresh unused principal.

Returns:

a certificate certifying the fresh principal issued by the key-chain's master key-pair (which was certifier by the certifier during initialization).

transfer

public Certificate transfer(String passcode,
                            String keyid,
                            RegistrationRequest request)
                     throws SPKIException

transfer a capability from a principal of this key-chain to another principal according to the request and purge the issuing private key.

Returns:

a transfer certificate.

request

public AuthorizationRequest request(String passcode,
                                    Principal monitor,
                                    String chainid,
                                    Sexp nonce,
                                    Principal issuer,
                                    Tag capability)
                             throws SPKIException

create an authorization request for the given monitor's princpal, authorization chain-id, request nonce, issuer's principal, and capability.

authenticate

boolean authenticate(String passcode)

verify the given passcode.

Returns:

true if the given passcode is valid, false otherwise.

fetchActivePrivateKey

private PrivateKey fetchActivePrivateKey(String keyid)
                                  throws SPKIException

search a private key with the given key-id from the active private key database. the key-ic is the hash value of the associated public key.

fetchActivePublicKey

private PublicKey fetchActivePublicKey(String keyid)
                                throws SPKIException

search a public key with the given key-id from the active private key database. the key-ic is the hash value of the key itself.

openDB

private void openDB()
             throws SPKIException

to be used by construct() and restore() only!

closeDB

private void closeDB()
              throws SPKIException

to be used by the finalize() method only!

buildDBname

private String buildDBname(String dbname)
                    throws SPKIException

construct

private void construct()
                throws Exception

restore

public void restore(String db_id)
             throws Exception

fetchNewKeyPair

public Sequence fetchNewKeyPair(String passcode)
                         throws SPKIException

get a fresh key-pair from the key-pool.

activateKeyPair

private void activateKeyPair(String passcode,
                             String keyid)
                      throws SPKIException

activate the key-pair specified by the given key-id.

deactivateKeyPair

private void deactivateKeyPair(String passcode,
                               String keyid)
                        throws SPKIException

deactivate (read: permanently purge the private key) the key-pair specified by the given key-id. TODO: move the associated public key, certificate(s), and authorization chains to the archive database?

addIssuer

private void addIssuer(String passcode,
                       PublicKey issuer)
                throws SPKIException

store a new issuer's public key in the issuer database.