org.hardtokenmgmt.core.token
Interface IToken

All Known Implementing Classes:

BaseToken, NetIdPrimeEIDLogonOnlyToken, NetIdSetCos431Token, NetIdSetCos441Token, SetCos431InstantEIDToken, SetCos441InstantEIDToken, SyncronizedToken

public interface IToken

Class acting as interface to different tokens supported The main implementing class is BaseToken that all other tokens should extend. For key types should the defined constants be used. It is possible to custom types, then will the type value be used as label. Not all implementation support all keytypes

Version:

$Id$

Author:

Philip Vendil 2006-aug-29

Field Summary

static java.lang.String	KEYALG_RSA Constant indicating that a RSA key should be generated
static java.lang.String	KEYTYPE_ALL Constants to all keys on a token, should only be used with the getCertificates method
static java.lang.String	KEYTYPE_AUTH Constant that refers the basic auth key on the token.
static java.lang.String	KEYTYPE_ENC Constant that refers the encryption key on the token.
static java.lang.String	KEYTYPE_SIGN Constant that refers the signing key on the token.
static java.lang.String	OBJECTTYPE_DATA Constant indicating that data objects should be processed
static java.lang.String	PINTYPE_BASIC Constant that refers to the basic PIN that usually protects the AUTH and ENC key All type of IToken implementations might not support all types.
static java.lang.String	PINTYPE_SIGN Constant that refers to the basic PIN that usually protects the AUTH and ENC key All type of IToken implementations might not support all types.

Method Summary

void	addObject(java.lang.String pintype, java.lang.String pin, IObject object) Adds a object (data, domainparameter) to the token
PINInfo	blockPIN(java.lang.String pintype) Method used to block a PIN, used for administrators to later change it
PINInfo	changePIN(java.lang.String pintype, java.lang.String oldpin, java.lang.String newpin) Method used to change the value of the
boolean	checkPIN(java.lang.String pintype, java.lang.String pIN) Method used to check if a PIN is valid and true if it is
void	clearCertificateCache() Method instructing the token to clear it's certificate cache if it have any.
void	clearToken(java.lang.String[] pintypes, java.lang.String[] puks) Method that should clear a token, either erase the card completely or remove all objects on the card for non-ereasable tokens.
void	downloadCert(java.lang.String label, java.lang.String pintype, java.lang.String pin, java.lang.String basicpin, java.security.cert.X509Certificate cert) Downloads a certificate to the token.
void	downloadKeyStore(java.lang.String keytype, java.lang.String pintype, java.lang.String pin, java.lang.String certLabel, java.security.KeyStore keyStore, java.lang.String keyStorePasswd) Method that downloads a keystores key and certificate on the token.
java.lang.String	generatePUK(java.lang.String pintype) Method that should generate the PUK code placed on the card for the specified PIN.
void	genKey(java.lang.String pintype, java.lang.String pin, java.lang.String basicpin, java.lang.String keytype, java.lang.String algorithm, int keysize, java.lang.String label) Method that should generate a key on the card with the specified algorithm.
org.bouncycastle.jce.PKCS10CertificationRequest	genPKCS10(java.lang.String keytype, java.lang.String pintype, java.lang.String pin, UserDataGenerator userDataGenerator) Method that generates a PKCS10 request using the specified key.
java.security.cert.X509Certificate	getCertificate(java.lang.String certficateLabel) Method that tries to find a certificate stored on the token wiht the specified label.
java.util.Collection	getCertificates(java.lang.String pintype) Method that retrieves all certificates stored on the token.
java.lang.String	getHardTokenSN() Method that should return the current hard token serial number of the card.
java.util.Collection	getKeyLabels(java.lang.String pintype) Method to get all labels of the keys (private) on the card.
java.util.Collection	getObjects(java.lang.String pintype, java.lang.String pin, java.lang.String objectType) Returns all objects of type (data or domain parameters) stored on the card
PINInfo	getPINInfo(java.lang.String pintype) Method that returns the current PIN related info about the given PIB
long	getSlotId(java.lang.String pintype) Method returning the slotId that is associated with this token.
java.lang.String[]	getSupportedPINTypes() Method that should return the tokens supported PIN types Either PINTYPE_ constants or customdefined labels
void	init(boolean useVirtualSlots, iaik.pkcs.pkcs11.Token token) Method that should be called by the TokenManager only when creating an instance.
void	initToken(java.lang.String tokenlabel, java.lang.String tokenserial, java.lang.String[] pintypes, java.lang.String[] pins, java.lang.String[] puks) Method that should initialize a token, cards that non-ereasable should clean the card as much as possible.
boolean	isTokenSupported(iaik.pkcs.pkcs11.Token token) Method used for knowing if an implementation supports the current token in process.
void	removeCertificate(java.lang.String pintype, java.lang.String pin, java.lang.String basicpin, java.security.cert.X509Certificate cert) Method removing the specified certificate from the token.
void	removeKey(java.lang.String pintype, java.lang.String pin, java.lang.String basicpin, java.lang.String label) Method removing a specified key from a card
void	removeObject(java.lang.String pintype, java.lang.String pin, java.lang.String basicPIN, IObject object) Method that removes a Data or Domain Parameters object from the card
boolean	requirePUKInDB() Method determining if the token requires the PUK to be uploaded to DB prior to initialization This is mainly for tokens that cannot be reformatted.
PINInfo	unblockPIN(java.lang.String pintype, java.lang.String puk, java.lang.String newpin) Method used to enter the PUK code to unblock a PIN code after to many erronious tries.
PINInfo	unlockPIN(java.lang.String pintype, java.lang.String pin) Method used to login to a PIN in order to be able to perform operations on the card, this is not the same as unblock PIN

Field Detail

KEYTYPE_ALL

static final java.lang.String KEYTYPE_ALL

Constants to all keys on a token, should only be used with the getCertificates method

See Also:

Constant Field Values

KEYTYPE_AUTH

static final java.lang.String KEYTYPE_AUTH

Constant that refers the basic auth key on the token. All type of IToken implementations might not support all types.

See Also:

Constant Field Values

KEYTYPE_SIGN

static final java.lang.String KEYTYPE_SIGN

Constant that refers the signing key on the token. All type of IToken implementations might not support all types.

See Also:

Constant Field Values

KEYTYPE_ENC

static final java.lang.String KEYTYPE_ENC

Constant that refers the encryption key on the token. All type of IToken implementations might not support all types.

See Also:

Constant Field Values

PINTYPE_BASIC

static final java.lang.String PINTYPE_BASIC

Constant that refers to the basic PIN that usually protects the AUTH and ENC key All type of IToken implementations might not support all types.

See Also:

Constant Field Values

PINTYPE_SIGN

static final java.lang.String PINTYPE_SIGN

Constant that refers to the basic PIN that usually protects the AUTH and ENC key All type of IToken implementations might not support all types.

See Also:

Constant Field Values

KEYALG_RSA

static final java.lang.String KEYALG_RSA

Constant indicating that a RSA key should be generated

See Also:

Constant Field Values

OBJECTTYPE_DATA

static final java.lang.String OBJECTTYPE_DATA

Constant indicating that data objects should be processed

See Also:

Constant Field Values

Method Detail

getHardTokenSN

java.lang.String getHardTokenSN()
                                throws iaik.pkcs.pkcs11.TokenException

Method that should return the current hard token serial number of the card. If the token doesn't have any serialnumber yet should null be returned.

Throws:

iaik.pkcs.pkcs11.TokenException

init

void init(boolean useVirtualSlots,
          iaik.pkcs.pkcs11.Token token)
          throws iaik.pkcs.pkcs11.TokenException

Method that should be called by the TokenManager only when creating an instance.

Throws:

iaik.pkcs.pkcs11.TokenException

isTokenSupported

boolean isTokenSupported(iaik.pkcs.pkcs11.Token token)
                         throws iaik.pkcs.pkcs11.TokenException

Method used for knowing if an implementation supports the current token in process.

Parameters:

token - the current token inserted into the slot.

Returns:

true if the current IToken implementation supports this token.

Throws:

iaik.pkcs.pkcs11.TokenException - if a pkcs11 related problem occurs

getSupportedPINTypes

java.lang.String[] getSupportedPINTypes()

Method that should return the tokens supported PIN types Either PINTYPE_ constants or customdefined labels

initToken

void initToken(java.lang.String tokenlabel,
               java.lang.String tokenserial,
               java.lang.String[] pintypes,
               java.lang.String[] pins,
               java.lang.String[] puks)
               throws OperationNotSupportedException,
                      iaik.pkcs.pkcs11.TokenException

Method that should initialize a token, cards that non-ereasable should clean the card as much as possible. Keys protected by each PIN may be generated but isn't required

Parameters:

tokenlabel - the label of the token, can be null if no token label should be set.

tokenserial - the serial number that should be written to the card, only used if the card supports the serial number to be set during initialization otherwise could null be used.

pintypes - an array of PINTYPE_contants or custom label strings. Indicates which key that should have which PIN and PUK

pins - an array of pin codes used in the initialization, should be used with the keytype array get hold of key to use. be defined in the getKeyIndex type.

puks - an array of puk codes for each PIN

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

clearToken

void clearToken(java.lang.String[] pintypes,
                java.lang.String[] puks)
                throws OperationNotSupportedException,
                       iaik.pkcs.pkcs11.TokenException

Method that should clear a token, either erase the card completely or remove all objects on the card for non-ereasable tokens.

Parameters:

pintypes - optional parameter used by some cards with non-erasable filesystem and needs the PUK code to erease some areas. Should contain an array of PINTYPE_contants or custom label strings

puks - optional parameter used by some cards with non-erasable filesystem and needs the PUK code to erease some areas.

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

genKey

void genKey(java.lang.String pintype,
            java.lang.String pin,
            java.lang.String basicpin,
            java.lang.String keytype,
            java.lang.String algorithm,
            int keysize,
            java.lang.String label)
            throws ObjectAlreadyExistsException,
                   OperationNotSupportedException,
                   iaik.pkcs.pkcs11.TokenException

Method that should generate a key on the card with the specified algorithm.

Parameters:

pintype - one of the PINTYPE_ indicating the PIN that should protect the key

pin - the pin to unlock (May not be required, then can null be used)

basicpin - pin to unlock the basic area, might be used for signature keys

keytype - one of the KEYTYPE_ constants or the label of the object for custom keys

algorithm - one of the KEYALG_ constants

keysize - the size of the key

label - a reference to the key to use.

Throws:

ObjectAlreadyExistsException - if the keytype already exists.

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

genPKCS10

org.bouncycastle.jce.PKCS10CertificationRequest genPKCS10(java.lang.String keytype,
                                                          java.lang.String pintype,
                                                          java.lang.String pin,
                                                          UserDataGenerator userDataGenerator)
                                                          throws OperationNotSupportedException,
                                                                 iaik.pkcs.pkcs11.TokenException

Method that generates a PKCS10 request using the specified key.

Parameters:

keytype - which key that should be used for the request.

pintype - of the PIN needed to unlock the token

pin - the pin to unlock (May not be required, then can null be used)

userDataGenerator - user data generator to use when fetching token labels.

Returns:

a PKCS10CertificateRequest for the specified key.

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

downloadCert

void downloadCert(java.lang.String label,
                  java.lang.String pintype,
                  java.lang.String pin,
                  java.lang.String basicpin,
                  java.security.cert.X509Certificate cert)
                  throws ObjectAlreadyExistsException,
                         OperationNotSupportedException,
                         iaik.pkcs.pkcs11.TokenException

Downloads a certificate to the token. Should mainly be used for root certificates.

Parameters:

label - the label used to mark the object on the token.

pintype - of the PIN needed to unlock the token

pin - the pin to unlock (May not be required, then can null be used)

basicpin - to unlock the certificate store.

Throws:

ObjectAlreadyExistsException - if a certificate with the label already exists.

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

downloadKeyStore

void downloadKeyStore(java.lang.String keytype,
                      java.lang.String pintype,
                      java.lang.String pin,
                      java.lang.String certLabel,
                      java.security.KeyStore keyStore,
                      java.lang.String keyStorePasswd)
                      throws ObjectAlreadyExistsException,
                             OperationNotSupportedException,
                             iaik.pkcs.pkcs11.TokenException

Method that downloads a keystores key and certificate on the token.

Parameters:

keytype - one of the KEYTYPE_ constants or the label of the object for custom keys

pintype - of the PIN needed to unlock the token

pin - the pin to unlock (May not be required, then can null be used)

certLabel - label the label used to mark the object on the token.

keyStore - the java keystore to extract the keystore from

keyStorePasswd - the passwordused to lock the keystore

Throws:

ObjectAlreadyExistsException - if a certificate or key with the label already exists.

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

getCertificates

java.util.Collection getCertificates(java.lang.String pintype)
                                     throws OperationNotSupportedException,
                                            iaik.pkcs.pkcs11.TokenException

Method that retrieves all certificates stored on the token.

Parameters:

pintype - of the PIN that are connected to the certificates

Returns:

a Collection of X509Certificate

Throws:

OperationNotSupportedException - if this operation isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

getCertificate

java.security.cert.X509Certificate getCertificate(java.lang.String certficateLabel)
                                                  throws OperationNotSupportedException,
                                                         iaik.pkcs.pkcs11.TokenException

Method that tries to find a certificate stored on the token wiht the specified label. The method will traverse through all supported pin types.

Parameters:

certficateLabel - of the certficate to look for

Returns:

the X509Certificate on null of it couldn't be found.

Throws:

OperationNotSupportedException - if this operation isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

removeCertificate

void removeCertificate(java.lang.String pintype,
                       java.lang.String pin,
                       java.lang.String basicpin,
                       java.security.cert.X509Certificate cert)
                       throws OperationNotSupportedException,
                              iaik.pkcs.pkcs11.TokenException

Method removing the specified certificate from the token.

Parameters:

pintype - of the PIN needed to unlock the token

pin - the pin to unlock (May not be required, then can null be used)

basicpin - pin to unlock the basic area, might be used for signature certificates

cert -

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

getKeyLabels

java.util.Collection getKeyLabels(java.lang.String pintype)
                                  throws OperationNotSupportedException,
                                         iaik.pkcs.pkcs11.TokenException

Method to get all labels of the keys (private) on the card.

Parameters:

pintype - of the PIN needed to unlock the key

Returns:

a collection of String

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

removeKey

void removeKey(java.lang.String pintype,
               java.lang.String pin,
               java.lang.String basicpin,
               java.lang.String label)
               throws OperationNotSupportedException,
                      iaik.pkcs.pkcs11.TokenException

Method removing a specified key from a card

Parameters:

pintype - of the PIN needed to unlock the token

pin - the pin to unlock (May not be required, then can null be used)

basicpin - pin to unlock the basic area, might be used for signature certificates

label - of the key

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

addObject

void addObject(java.lang.String pintype,
               java.lang.String pin,
               IObject object)
               throws OperationNotSupportedException,
                      iaik.pkcs.pkcs11.TokenException

Adds a object (data, domainparameter) to the token

Parameters:

pintype - of the PIN that should protect the key, null for no protection

pin - the pin to unlock the private area (May not be required, then can null be used)

object - a object to add to the token

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

getObjects

java.util.Collection getObjects(java.lang.String pintype,
                                java.lang.String pin,
                                java.lang.String objectType)
                                throws OperationNotSupportedException,
                                       iaik.pkcs.pkcs11.TokenException

Returns all objects of type (data or domain parameters) stored on the card

Parameters:

pintype - of the PIN needed to unlock the token, if neccessary

pin - the pin to unlock (May not be required, then can null be used)

objectType - of object to return, one of the OBJECTTYPE_ constants

Returns:

a Collection of IObject

Throws:

OperationNotSupportedException - if this operation isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

removeObject

void removeObject(java.lang.String pintype,
                  java.lang.String pin,
                  java.lang.String basicPIN,
                  IObject object)
                  throws OperationNotSupportedException,
                         iaik.pkcs.pkcs11.TokenException

Method that removes a Data or Domain Parameters object from the card

Parameters:

pintype - of the PIN needed to unlock the token

pin - the pin to unlock (May not be required, then can null be used)

basicPIN - to unlock (May not be required, then can null be used)

object - the iaik.pkcs.pkcs11.objects.Object object to remove

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

getPINInfo

PINInfo getPINInfo(java.lang.String pintype)
                   throws OperationNotSupportedException,
                          iaik.pkcs.pkcs11.TokenException

Method that returns the current PIN related info about the given PIB

Parameters:

pintype - one of the PINTYPE_ constants

Returns:

a PINInfo object

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

changePIN

PINInfo changePIN(java.lang.String pintype,
                  java.lang.String oldpin,
                  java.lang.String newpin)
                  throws OperationNotSupportedException,
                         iaik.pkcs.pkcs11.TokenException

Method used to change the value of the

Parameters:

pintype - one of the PINTYPE_ constants

oldpin - the old pinvalue

newpin - the new pinvalue

Returns:

a PIN info object containing the current status of the PIN

Throws:

OperationNotSupportedException

iaik.pkcs.pkcs11.TokenException

unlockPIN

PINInfo unlockPIN(java.lang.String pintype,
                  java.lang.String pin)
                  throws OperationNotSupportedException,
                         iaik.pkcs.pkcs11.TokenException

Method used to login to a PIN in order to be able to perform operations on the card, this is not the same as unblock PIN

Parameters:

pintype - one of the PINTYPE_ constants

pin - the pin that should be used for login

Returns:

a PIN info object containing the current status of the PIN

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

unblockPIN

PINInfo unblockPIN(java.lang.String pintype,
                   java.lang.String puk,
                   java.lang.String newpin)
                   throws OperationNotSupportedException,
                          iaik.pkcs.pkcs11.TokenException

Method used to enter the PUK code to unblock a PIN code after to many erronious tries.

Parameters:

pintype - one of the PINTYPE_ constants

puk - the PUK that should be used to unblock

newpin - the new PIN.

Returns:

a PINInfo object indicating the new status of the PIN

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

blockPIN

PINInfo blockPIN(java.lang.String pintype)
                 throws OperationNotSupportedException,
                        iaik.pkcs.pkcs11.TokenException

Method used to block a PIN, used for administrators to later change it

Parameters:

pintype - one of the PINTYPE_ constants

Returns:

a PINInfo object indicating the new status of the PIN

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

clearCertificateCache

void clearCertificateCache()

Method instructing the token to clear it's certificate cache if it have any. It's up to the implementation if there should be any caching of certificates or not.

checkPIN

boolean checkPIN(java.lang.String pintype,
                 java.lang.String pIN)
                 throws OperationNotSupportedException,
                        iaik.pkcs.pkcs11.TokenException

Method used to check if a PIN is valid and true if it is

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.

requirePUKInDB

boolean requirePUKInDB()
                       throws iaik.pkcs.pkcs11.TokenException

Method determining if the token requires the PUK to be uploaded to DB prior to initialization This is mainly for tokens that cannot be reformatted.

Returns:

'true' if PUK data must exist in database before card is managed. 'false' othervise.

Throws:

iaik.pkcs.pkcs11.TokenException - for other token related failures.

generatePUK

java.lang.String generatePUK(java.lang.String pintype)
                             throws OperationNotSupportedException

Method that should generate the PUK code placed on the card for the specified PIN. Should only be used in the case requirePUKInDB is false and PUK codes should be generated during token initialization. This is mainly for tokens that cannot be reformatted.

Returns:

a valid PUK supported by the token

Throws:

OperationNotSupportedException - if this method isn't supported by this token.

getSlotId

long getSlotId(java.lang.String pintype)
               throws OperationNotSupportedException,
                      iaik.pkcs.pkcs11.TokenException

Method returning the slotId that is associated with this token.

Returns:

the tokens slotId

Throws:

OperationNotSupportedException - if this operation or some of it's parameters isn't supported

iaik.pkcs.pkcs11.TokenException - for other token related failures.