com.iplanet.trustbase.security.store
Class TokenKeyStore

java.lang.Object
  |
  +--com.iplanet.trustbase.security.store.TokenKeyStore

public abstract class TokenKeyStore

extends java.lang.Object

TokenKeyStore is similar to the JCA notion of a KeyStore, but implements function more appropriate to implementation by hardware tokens

TokenKeyStore supports two types of entries: KeyEntrys and TrustedCertificateEntrys Either type of entry is associated with at least one aliases. An alias which is the RFC 2253 encoding of the subject name in the certificate is guaranteed to be associated with the entry. Support for additional aliases is implementation dependent

Field Summary

static java.lang.String

PROVIDER_PROPERTY the Provider property which specifies implementations of TokenKeyStores

Constructor Summary

TokenKeyStore()

Method Summary

abstract TrustedCertificateEntry	addTrustedCertificateEntry(java.lang.String alias, java.security.cert.X509Certificate cert) import a trusted certificate.
abstract java.util.Set	aliases() get a list of all the aliases in use in this TokenKeyStore
abstract java.security.cert.X509Certificate[]	completeCertificateChain(java.security.cert.X509Certificate[] partialChain) complete a certificate chain, given a partial chain
abstract void	deleteEntry(TokenKeyStoreEntry entry) delete an entry from the TokenKeyStore
abstract void	doCommand(java.lang.String commandVerb, java.lang.String[] arguments) perform an implementation specific command
abstract byte[]	exportPKCS12KeyEntry(java.lang.String alias, PasswordCallback callback) export a KeyEntry to a PKCS#12 archive
abstract KeyEntry	generateKeyPair(java.lang.String alias, java.lang.String subjectName, java.lang.String algorithm, int keysize) generate a KeyPair on the token, using default parameters for the specified algorithm.
abstract java.util.Set	getAllEntries() get all TokenKeySTore entries
abstract java.util.Set	getAllKeyEntries() get all KeyEntries from the KeyStore
abstract java.util.Set	getAllTrustedCertificateEntries() list all TrustedCertificateEntries on the token
abstract TokenKeyStoreEntry	getEntry(java.lang.String alias) get the entry with a given alias
abstract TokenKeyStoreEntry	getEntry(java.lang.String issuer, java.math.BigInteger serialNo) get an entry whose certificate has the given issuer and serial number
abstract TokenKeyStoreEntry	getEntry(java.security.cert.X509Certificate cert) get an entry whose certificate matches the provided cert
static TokenKeyStore	getInstance(java.lang.String type, java.lang.String location, PasswordCallback callback) get a TokenKeyStore
abstract KeyEntry	getKeyEntry(java.lang.String alias) get a KeyEntry from the store
abstract KeyEntry	getKeyEntry(java.lang.String issuer, java.math.BigInteger serialNo) get a KeyEntry whose subject certificate has the given issuer and serial number
abstract TrustedCertificateEntry	getTrustedCertificateEntry(java.lang.String alias) get a TrustedCertificateEntry
abstract TrustedCertificateEntry	getTrustedCertificateEntry(java.lang.String issuer, java.math.BigInteger serialNo) get a TrustedCertificateEntry whose issuer and serial number match those specified
abstract KeyEntry	importPKCS12KeyEntry(java.lang.String alias, byte[] encodedEntry, PasswordCallback callback) import a PKCS#12 PrivateKey and associated certificate chain.
static void	main(java.lang.String[] args) provides useful debug output.
abstract void	updateEntry(TokenKeyStoreEntry entry) update an entry on the TokenKeyStore
void	validate(java.security.cert.X509Certificate[] chain, java.util.Date date)
abstract void	validate(java.security.cert.X509Certificate[] chain, KeyUsages purpose, java.util.Date date) validate a certificate chain for a given purpose, on a given data

Methods inherited from class java.lang.Object

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

Field Detail

PROVIDER_PROPERTY

public static final java.lang.String PROVIDER_PROPERTY

the Provider property which specifies implementations of TokenKeyStores

Constructor Detail

TokenKeyStore

public TokenKeyStore()

Method Detail

getInstance

public static TokenKeyStore getInstance(java.lang.String type,
                                        java.lang.String location,
                                        PasswordCallback callback)
                                 throws TokenKeyStoreException

get a TokenKeyStore

Parameters:

type - the type of the TokenKeyStore, e.g. "JSS". not null

location - a URL, can be null

callback - PasswordCallback for logon to token, and also for use if other actions requiring a password don't explicitly receive a PasswordCallback. may be null

Returns:

a TokenKeyStore object. not null

main

public static void main(java.lang.String[] args)
                 throws java.lang.Throwable

provides useful debug output. If run with no parameters, lists all installed TokenKeyStore implementations from all Providers.

If instantiated as

TokenKeyStore [ ]

instantiate the TokenKeyStore of the given type, at the given location using the optional password to authenticate. Then dump a summary of all entries in the TokenKeyStore

aliases

public abstract java.util.Set aliases()

get a list of all the aliases in use in this TokenKeyStore

Returns:

a Set of Strings. not null

getEntry

public abstract TokenKeyStoreEntry getEntry(java.lang.String alias)
                                     throws NoSuchEntryException,
                                            TokenKeyStoreException

get the entry with a given alias

Parameters:

the - alias of the entry to get. not null

Returns:

a TokenKeyStore entry: one of a KeyEntry or a TrustedCertificateEntry. not null

getEntry

public abstract TokenKeyStoreEntry getEntry(java.security.cert.X509Certificate cert)
                                     throws NoSuchEntryException,
                                            TokenKeyStoreException

get an entry whose certificate matches the provided cert

Parameters:

cert - the cert to match. not null

Returns:

a TokenKeyStoreEntry: either a KeyEntry or a TrustedCertificateEntry. not null

getEntry

public abstract TokenKeyStoreEntry getEntry(java.lang.String issuer,
                                            java.math.BigInteger serialNo)
                                     throws NoSuchEntryException,
                                            TokenKeyStoreException

get an entry whose certificate has the given issuer and serial number

Parameters:

issuer - an RFC2253 encoded certificate issuer distinguished name

a - certificate serial number

Returns:

a TokenKeyStoreEntry: either a KeyEntry or a TrustedCertificateEntry. not null

getAllEntries

public abstract java.util.Set getAllEntries()
                                     throws TokenKeyStoreException

get all TokenKeySTore entries

Returns:

a Set of TokenKeyStoreEntry Objects

updateEntry

public abstract void updateEntry(TokenKeyStoreEntry entry)
                          throws NoSuchEntryException,
                                 TokenKeyStoreException

update an entry on the TokenKeyStore

Parameters:

entry - the entry to update. not null

deleteEntry

public abstract void deleteEntry(TokenKeyStoreEntry entry)
                          throws NoSuchEntryException,
                                 TokenKeyStoreException

delete an entry from the TokenKeyStore

Parameters:

entry - the entry to delete. not null

getKeyEntry

public abstract KeyEntry getKeyEntry(java.lang.String alias)
                              throws NoSuchEntryException,
                                     TokenKeyStoreException

get a KeyEntry from the store

Parameters:

alias - the alias of the entry. not null

Returns:

a KeyEntry. not null

getKeyEntry

public abstract KeyEntry getKeyEntry(java.lang.String issuer,
                                     java.math.BigInteger serialNo)
                              throws NoSuchEntryException,
                                     TokenKeyStoreException

get a KeyEntry whose subject certificate has the given issuer and serial number

Parameters:

issuer - an RFC2253 encoded certificate issuer distinguished name

a - certificate serial number

Returns:

a KeyEntry. not null

getAllKeyEntries

public abstract java.util.Set getAllKeyEntries()

get all KeyEntries from the KeyStore

Returns:

an Enumeration of KeyEntry Objects. not null

generateKeyPair

public abstract KeyEntry generateKeyPair(java.lang.String alias,
                                         java.lang.String subjectName,
                                         java.lang.String algorithm,
                                         int keysize)
                                  throws TokenKeyStoreException

generate a KeyPair on the token, using default parameters for the specified algorithm. This action will create a new KeyEntry on the token, with a KeyPair and a temporary certificate chain consisting of a single self signed certificate with a fixed Distinguished Name

Parameters:

alias - the alias to assign to the new KeyEntry. may be null, in which case subjectName will be used as the alias

subjectName - RFC2253 encoded subject DN of temporary certificate. not null

the - algorithm to generate the KeyPair for. not null

keysize - key size of the keys to be generated

Returns:

a KeyEntry whos Keys reference objects resident on the token. not null

See Also:

KeyEntry

importPKCS12KeyEntry

public abstract KeyEntry importPKCS12KeyEntry(java.lang.String alias,
                                              byte[] encodedEntry,
                                              PasswordCallback callback)
                                       throws AliasConflictException,
                                              IncompleteChainException,
                                              TokenKeyStoreException

import a PKCS#12 PrivateKey and associated certificate chain. this action will create a new KeyEntry

Parameters:

alias - the alias to associate with the new KeyEntry. may be null, in which case the RFC 2253 encoded name of the subject cert will be used as the alias

encodedEntry - a BER encoded PKCS#12 archive. not null

callback - a PasswordCallback to decrypt the archive and to authenticate the user to the token. may be null

exportPKCS12KeyEntry

public abstract byte[] exportPKCS12KeyEntry(java.lang.String alias,
                                            PasswordCallback callback)
                                     throws NoSuchEntryException,
                                            TokenKeyStoreException

export a KeyEntry to a PKCS#12 archive

Parameters:

alias - the KeyEntry to export. not null

callback - a PasswordCallback to encrypt the archive and to authenticate the user to the token. may be null

Returns:

a byte array containing a BER encoded PKCS#12 archive

getTrustedCertificateEntry

public abstract TrustedCertificateEntry getTrustedCertificateEntry(java.lang.String alias)
                                                            throws NoSuchEntryException,
                                                                   TokenKeyStoreException

get a TrustedCertificateEntry

Parameters:

alias - the alias of the entry. not null

Returns:

a TruistedCertificateEntry. not null

getTrustedCertificateEntry

public abstract TrustedCertificateEntry getTrustedCertificateEntry(java.lang.String issuer,
                                                                   java.math.BigInteger serialNo)
                                                            throws NoSuchEntryException,
                                                                   TokenKeyStoreException

get a TrustedCertificateEntry whose issuer and serial number match those specified

Parameters:

issuer - the RFC2253 encoded issuer name of the certificate. not null

serialNo - the serial number of the certificate. not null

Returns:

a TruistedCertificateEntry. not null

getAllTrustedCertificateEntries

public abstract java.util.Set getAllTrustedCertificateEntries()

list all TrustedCertificateEntries on the token

Returns:

an Enumeration of TrustedCertificateEntrys. not null

addTrustedCertificateEntry

public abstract TrustedCertificateEntry addTrustedCertificateEntry(java.lang.String alias,
                                                                   java.security.cert.X509Certificate cert)
                                                            throws AliasConflictException,
                                                                   TokenKeyStoreException

import a trusted certificate. This action creates a new TrustedCertificateEntry

Parameters:

the - alias to give the TrustedCertificateEntry. may be null, in which case the rfc 2253 encoded subject name of the certificate will be used as the alias

cert - the certificate to be trusted. not null

callback - a PasswordCallback to authenticate the user to the token. may be null

validate

public void validate(java.security.cert.X509Certificate[] chain,
                     java.util.Date date)
              throws com.iplanet.trustbase.security.cert.ValidateException,
                     TrustException,
                     TokenKeyStoreException

validate

public abstract void validate(java.security.cert.X509Certificate[] chain,
                              KeyUsages purpose,
                              java.util.Date date)
                       throws com.iplanet.trustbase.security.cert.ValidateException,
                              TrustException,
                              TokenKeyStoreException

validate a certificate chain for a given purpose, on a given data

Parameters:

chain - the certificate chain. not null

purpose - the purpose to validate for. may be null, if TokenKeyStore policy permits it

date - the date on which to validate the certificate. may be null, in which case the current date is assumed

Throws:

com.iplanet.trustbase.security.cert.ValidateException - thrown if the certificate chain is invalid

TrustException - thrown if the certificate chain is valid but not trusted

completeCertificateChain

public abstract java.security.cert.X509Certificate[] completeCertificateChain(java.security.cert.X509Certificate[] partialChain)
                                                                       throws IncompleteChainException,
                                                                              TokenKeyStoreException

complete a certificate chain, given a partial chain

Parameters:

partialChain - the partial certificate chain. must contain at least one certificate

Returns:

the completed certificate chain

Throws:

IncompleteChainException - if the chain cannot be completed using certificates in the store

TokenKeyStoreException -

doCommand

public abstract void doCommand(java.lang.String commandVerb,
                               java.lang.String[] arguments)
                        throws TokenKeyStoreException

perform an implementation specific command

Parameters:

commandVerb - a String identifying the action to take. not empty

arguments - any arguments required by the commandVerb. may be null