org.xipki.pkcs11.wrapper

Class PKCS11Token

java.lang.Object

org.xipki.pkcs11.wrapper.PKCS11Token

public class PKCS11Token
extends Object

This is a PKCS#11 token with session management.

Author:

xipki

Constructor Summary

Constructors

Constructor and Description
PKCS11Token(Token token, boolean readOnly, char[] pin) The simple constructor.
PKCS11Token(Token token, boolean readOnly, long userType, char[] userName, List<char[]> pins, Integer numSessions) The advanced constructor.

Method Summary

Modifier and Type	Method and Description
void	closeAllSessions() Closes all sessions.
long	copyObject(long sourceObjectHandle, AttributeVector template) Copy an existing object.
long	createECPrivateKeyObject(AttributeVector template, byte[] ecPoint) Create EC private key object in the PKCS#11 device.
long	createObject(AttributeVector template) Create a new object on the token (or in the session).
long	createPrivateKeyObject(AttributeVector template, PublicKey publicKey)
byte[]	decrypt(Mechanism mechanism, long keyHandle, byte[] ciphertext) Decrypts the given data with the key and mechanism.
int	decrypt(OutputStream out, Mechanism mechanism, long keyHandle, InputStream ciphertext) This method can be used to decrypt large data.
byte[][]	decryptMessages(Mechanism mechanism, long keyHandle, DecryptMessageBytesEntry[] entries) Decrypts the given ciphertexts using the given mechanism and keys.
int[]	decryptMessages(Mechanism mechanism, long keyHandle, DecryptMessageStreamEntry[] entries) Decrypts the given ciphertexts using the given mechanism and key.
long	deriveKey(Mechanism mechanism, long baseKeyHandle, AttributeVector template) Derives a new key from a specified base key using the given mechanism.
void	destroyObject(long objectHandle) Destroy a certain object on the token (or in the session).
List<Long>	destroyObjects(List<Long> objectHandles)
long[]	destroyObjects(long... objectHandles) Destroy a certain object on the token (or in the session).
byte[]	digest(Mechanism mechanism, byte[] data) Digests the given data with the mechanism.
byte[]	digest(Mechanism mechanism, InputStream data) Digests the large data with the mechanism.
byte[]	digestKey(Mechanism mechanism, long keyHandle) Digests the given key with the mechanism.
byte[]	encrypt(Mechanism mechanism, long keyHandle, byte[] plaintext) Encrypts the given data with the key and mechanism.
int	encrypt(OutputStream out, Mechanism mechanism, long keyHandle, InputStream plaintext) This method can be used to encrypt large data.
byte[][]	encryptMessages(Mechanism mechanism, long keyHandle, EncryptMessageBytesEntry[] entries) Encrypts the given messages using the given mechanism and key
int[]	encryptMessages(Mechanism mechanism, long keyHandle, EncryptMessageStreamEntry[] entries) Encrypts the given messages using the given mechanism and key.
long[]	findAllObjects(AttributeVector template) Finds all objects that match the template.
long[]	findObjects(AttributeVector template, int maxObjectCount) Finds objects that match the template.
long	generateKey(Mechanism mechanism, AttributeVector template) Generate a new secret key or a set of domain parameters.
PKCS11KeyPair	generateKeyPair(Mechanism mechanism, KeyPairTemplate template) Generate a new public key - private key key-pair and use the set attributes of the template objects for setting the attributes of the new public key and private key objects.
byte[]	generateRandom(int numberOfBytesToGenerate) Generates a certain number of random bytes.
byte[]	generateRandom(int numberOfBytesToGenerate, byte[] extraSeed) Generates a certain number of random bytes.
byte[]	generateUniqueId(AttributeVector template, int idLength, Random random) Generate a unique CKA_ID.
AttributeVector	getAttrValues(long objectHandle, List<Long> attributeTypes) Gets give attributes for the given object handle.
AttributeVector	getAttrValues(long objectHandle, long... attributeTypes) Gets give attributes for the given object handle.
AttributeVector	getDefaultAttrValues(long objectHandle) Gets all attributes for the given object handle.
PKCS11Key	getKey(AttributeVector criteria) Gets the PKCS11Key of a key satisfying the given criteria.
PKCS11Key	getKey(PKCS11KeyId keyId) Gets the PKCS11Key identified by the given PKCS11KeyId.
PKCS11KeyId	getKeyId(AttributeVector criteria) Gets the PKCS11KeyId of a key satisfying the given criteria.
MechanismInfo	getMechanismInfo(long mechanism) Gets the MechanismInfo for given mechanism code.
Set<Long>	getMechanisms()
PKCS11Module	getModule()
String	getModuleInfo()
long	getObjectSize(long objectHandle) Get the size of the specified object in bytes.
Token	getToken() Get the token that created this Session object.
long	getTokenId() Get the token (slot) identifier of this token.
void	initPIN(char[] pin) Initializes the user-PIN.
boolean	isReadOnly() Returns whether this token is read-only.
void	logInSecurityOfficer(char[] userName, char[] pin) Login this session as CKU_SO (Security Officer).
void	logout() Logs out this session.
void	setAttributeValues(long objectToUpdateHandle, AttributeVector template) Gets all present attributes of the given template object and writes them to the object to update on the token (or in the session).
void	setMaxMessageSize(int maxMessageSize) Sets the maximal message size sent to the PKCS#11 device in one command.
void	setPIN(char[] oldPin, char[] newPin) Set the user-PIN to a new value.
void	setTimeOutWaitNewSession(int timeOutWaitNewSessionMs)
byte[]	sign(Mechanism mechanism, long keyHandle, byte[] data) Signs the given data with the key and mechanism.
byte[]	sign(Mechanism mechanism, long keyHandle, InputStream data) This method can be used to sign large data.
byte[][]	signMessages(Mechanism mechanism, long keyHandle, SignMessageBytesEntry[] entries) Signs the given messages using the given mechanism and key.
byte[][]	signMessages(Mechanism mechanism, long keyHandle, SignMessageStreamEntry[] entries) Signs the given messages using the given mechanism and key.
byte[]	signRecover(Mechanism mechanism, long keyHandle, byte[] data) Sign-recovers the given data with the key and mechanism.
boolean	supportsMechanism(long mechanism, long flagBit) Returns whether the mechanism for given purpose is supported.
String	toString() Returns the string representation of this object.
long	unwrapKey(Mechanism mechanism, long unwrappingKeyHandle, byte[] wrappedKey, AttributeVector keyTemplate) Unwraps (decrypts) the given encrypted key with the unwrapping key using the given mechanism.
boolean	verify(Mechanism mechanism, long keyHandle, byte[] data, byte[] signature) Verifies the given signature against the given data with the key and mechanism.
boolean	verify(Mechanism mechanism, long keyHandle, InputStream data, byte[] signature) This method can be used to verify large data.
boolean[]	verifyMessages(Mechanism mechanism, long keyHandle, VerifyMessageBytesEntry[] entries)
boolean[]	verifyMessages(Mechanism mechanism, long keyHandle, VerifyMessageStreamEntry[] entries) Verify the signatures over given messages using the given mechanism and key.
byte[]	verifyRecover(Mechanism mechanism, long keyHandle, byte[] data) Verify-recovers the given data with the key and mechanism.
byte[]	wrapKey(Mechanism mechanism, long wrappingKeyHandle, long keyHandle) Wraps (encrypts) the given key with the wrapping key using the given mechanism.

Methods inherited from class java.lang.Object

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

Constructor Detail

PKCS11Token

public PKCS11Token(Token token,
                   boolean readOnly,
                   char[] pin)
            throws TokenException

The simple constructor.

Parameters:

token - The token

readOnly - True if this token is read only, false if read-write.

pin - The PIN of user type CKU_USER. May be null.

Throws:

TokenException - If accessing the PKCS#11 device failed.

PKCS11Token

public PKCS11Token(Token token,
                   boolean readOnly,
                   long userType,
                   char[] userName,
                   List<char[]> pins,
                   Integer numSessions)
            throws TokenException

The advanced constructor.

Parameters:

token - The token

readOnly - True if this token is read only, false if read-write.

userType - The user type. In general, it is CKU_USER.

userName - The user name. In general, it is null.

pins - The PINs. May be null and empty list.

numSessions - Number of sessions. May be null.

Throws:

TokenException - If accessing the PKCS#11 device failed.

Method Detail

getModule

public PKCS11Module getModule()

setTimeOutWaitNewSession

public void setTimeOutWaitNewSession(int timeOutWaitNewSessionMs)

setMaxMessageSize

public void setMaxMessageSize(int maxMessageSize)

Sets the maximal message size sent to the PKCS#11 device in one command.

Parameters:

maxMessageSize - the maximal message size in bytes.

getMechanisms

public Set<Long> getMechanisms()

getMechanismInfo

public MechanismInfo getMechanismInfo(long mechanism)

Gets the MechanismInfo for given mechanism code.

Parameters:

mechanism - The mechanism code.

Returns:

the MechanismInfo.

supportsMechanism

public boolean supportsMechanism(long mechanism,
                                 long flagBit)

Returns whether the mechanism for given purpose is supported.

Parameters:

mechanism - The mechanism.

flagBit - The purpose. Valid values are (could be extended in the future PKCS#11 version): PKCS11Constants.CKF_SIGN, PKCS11Constants.CKF_VERIFY, PKCS11Constants.CKF_SIGN_RECOVER, PKCS11Constants.CKF_VERIFY_RECOVER, PKCS11Constants.CKF_ENCRYPT, PKCS11Constants.CKF_DECRYPT, PKCS11Constants.CKF_DERIVE, PKCS11Constants.CKF_DIGEST, PKCS11Constants.CKF_UNWRAP, PKCS11Constants.CKF_WRAP.

Returns:

whether mechanism with given flag bit is supported.

setPIN

public void setPIN(char[] oldPin,
                   char[] newPin)
            throws TokenException

Set the user-PIN to a new value. Can only be called from a read-write sessions.

Parameters:

oldPin - The old (current) user-PIN.

newPin - The new value for the user-PIN.

Throws:

TokenException - If setting the new PIN fails.

initPIN

public void initPIN(char[] pin)
             throws TokenException

Initializes the user-PIN. Can only be called from a read-write security officer session. May be used to set a new user-PIN if the user-PIN is locked.

Parameters:

pin - The new user-PIN. This parameter may be null, if the token has a protected authentication path. Refer to the PKCS#11 standard for details.

Throws:

TokenException - If the session has not the right to set the PIN of if the operation fails for some other reason.

closeAllSessions

public void closeAllSessions()

Closes all sessions.

getTokenId

public long getTokenId()

Get the token (slot) identifier of this token.

Returns:

the slot identifier of this token.

getToken

public Token getToken()

Get the token that created this Session object.

Returns:

The token.

getModuleInfo

public String getModuleInfo()
                     throws TokenException

Throws:

TokenException

isReadOnly

public boolean isReadOnly()

Returns whether this token is read-only.

Returns:

true if read-only, false if read-write.

logInSecurityOfficer

public void logInSecurityOfficer(char[] userName,
                                 char[] pin)
                          throws TokenException

Login this session as CKU_SO (Security Officer).

Parameters:

userName - Username of user type CKU_SO.

pin - PIN.

Throws:

TokenException - If logging in the session fails.

logout

public void logout()
            throws TokenException

Logs out this session.

Throws:

TokenException - If logging out the session fails.

createObject

public long createObject(AttributeVector template)
                  throws TokenException

Create a new object on the token (or in the session). The application must provide a template that holds enough information to create a certain object. For instance, if the application wants to create a new DES key object it creates a new instance of the AttributesTemplate class to serve as a template. The application must set all attributes of this new object which are required for the creation of such an object on the token. Then it passes this DESSecretKey object to this method to create the object on the token. Example: AttributesTemplate desKeyTemplate = AttributesTemplate.newSecretKey(CKK_DES3); // the key type is set by the DESSecretKey's constructor, so you need not do it desKeyTemplate.value(myDesKeyValueAs8BytesLongByteArray) .token(true) .private(true); .encrypt(true); .decrypt(true); ... long theCreatedDESKeyObjectHandle = userSession.createObject(desKeyTemplate); Refer to the PKCS#11 standard to find out what attributes must be set for certain types of objects to create them on the token.

Parameters:

template - The template object that holds all values that the new object on the token should contain.

Returns:

A new PKCS#11 Object that serves holds all the (readable) attributes of the object on the token. In contrast to the templateObject, this object might have certain attributes set to token-dependent default-values.

Throws:

TokenException - If the creation of the new object fails. If it fails, the no new object was created on the token.

createPrivateKeyObject

public long createPrivateKeyObject(AttributeVector template,
                                   PublicKey publicKey)
                            throws TokenException

Throws:

TokenException

createECPrivateKeyObject

public long createECPrivateKeyObject(AttributeVector template,
                                     byte[] ecPoint)
                              throws TokenException

Create EC private key object in the PKCS#11 device.

Parameters:

template - Template of the EC private key.

ecPoint - The encoded EC-Point. May be null.

Returns:

object handle of the new EC private key.

Throws:

TokenException - if creating new object failed.

copyObject

public long copyObject(long sourceObjectHandle,
                       AttributeVector template)
                throws TokenException

Copy an existing object. The source object and a template object are given. Any value set in the template object will override the corresponding value from the source object, when the new object is created. See the PKCS#11 standard for details.

Parameters:

sourceObjectHandle - The source object of the copy operation.

template - A template object whose attribute values are used for the new object; i.e. they have higher priority than the attribute values from the source object. May be null; in that case the new object is just a one-to-one copy of the sourceObject.

Returns:

The new object that is created by copying the source object and setting attributes to the values given by the template.

Throws:

TokenException - If copying the object fails for some reason.

setAttributeValues

public void setAttributeValues(long objectToUpdateHandle,
                               AttributeVector template)
                        throws TokenException

Gets all present attributes of the given template object and writes them to the object to update on the token (or in the session). Both parameters may refer to the same Java object. This is possible, because this method only needs the object handle of the objectToUpdate, and gets the attributes to set from the template. This means, an application can get the object using createObject of findObject, then modify attributes of this Java object and then call this method passing this object as both parameters. This will update the object on the token to the values as modified in the Java object.

Parameters:

objectToUpdateHandle - The attributes of this object get updated.

template - This method gets all present attributes of this template object and set this attributes at the objectToUpdate.

Throws:

TokenException - If updating the attributes fails. All or no attributes are updated.

destroyObject

public void destroyObject(long objectHandle)
                   throws TokenException

Destroy a certain object on the token (or in the session). Give the object that you want to destroy. This method uses only the internal object handle of the given object to identify the object.

Parameters:

objectHandle - The object handle that should be destroyed.

Throws:

TokenException - If the object could not be destroyed.

destroyObjects

public long[] destroyObjects(long... objectHandles)
                      throws TokenException

Destroy a certain object on the token (or in the session). Give the object that you want to destroy. This method uses only the internal object handle of the given object to identify the object.

Parameters:

objectHandles - The object handles that should be destroyed.

Returns:

objects that have been destroyed.

Throws:

TokenException - If could not get a valid session.

destroyObjects

public List<Long> destroyObjects(List<Long> objectHandles)
                          throws TokenException

Throws:

TokenException

getObjectSize

public long getObjectSize(long objectHandle)
                   throws TokenException

Get the size of the specified object in bytes. This size specifies how much memory the object takes up on the token.

Parameters:

objectHandle - The object to get the size for.

Returns:

The object's size bytes.

Throws:

TokenException - If determining the size fails.

generateUniqueId

public byte[] generateUniqueId(AttributeVector template,
                               int idLength,
                               Random random)
                        throws TokenException

Generate a unique CKA_ID.

Parameters:

template - The search criteria for the uniqueness.

idLength - Length of the CKA_ID.

random - random to generate the random CKA_ID.

Returns:

the unique CKA_ID.

Throws:

TokenException - If executing operation fails.

getKey

public PKCS11Key getKey(PKCS11KeyId keyId)
                 throws TokenException

Gets the PKCS11Key identified by the given PKCS11KeyId.

Parameters:

keyId - The key identifier.

Returns:

PKCS11Key identified by the given PKCS11KeyId.

Throws:

TokenException - If executing operation fails.

getKey

public PKCS11Key getKey(AttributeVector criteria)
                 throws TokenException

Gets the PKCS11Key of a key satisfying the given criteria.

Parameters:

criteria - The criteria. At one of the CKA_ID and CKA_LABEL must be set.

Returns:

PKCS11Key of a key satisfying the given criteria

Throws:

TokenException - If executing operation fails.

getKeyId

public PKCS11KeyId getKeyId(AttributeVector criteria)
                     throws TokenException

Gets the PKCS11KeyId of a key satisfying the given criteria.

Parameters:

criteria - The criteria. At one of the CKA_ID and CKA_LABEL must be set.

Returns:

PKCS11KeyId of a key satisfying the given criteria

Throws:

TokenException - If executing operation fails.

findAllObjects

public long[] findAllObjects(AttributeVector template)
                      throws TokenException

Finds all objects that match the template.

Parameters:

template - The object that serves as a template for searching. If this object is null, the find operation will find all objects that this session can see. Notice, that only a user session will see private objects.

Returns:

An array of found objects. The maximum size of this array is maxObjectCount, the minimum length is 0. Never returns null.

Throws:

TokenException - if finding objects failed.

findObjects

public long[] findObjects(AttributeVector template,
                          int maxObjectCount)
                   throws TokenException

Finds objects that match the template.

Parameters:

template - The object that serves as a template for searching. If this object is null, the find operation will find all objects that this session can see. Notice, that only a user session will see private objects.

maxObjectCount - Specifies how many objects to return with this call.

Returns:

An array of found objects. The maximum size of this array is maxObjectCount, the minimum length is 0. Never returns null.

Throws:

TokenException - if finding objects failed.

encrypt

public byte[] encrypt(Mechanism mechanism,
                      long keyHandle,
                      byte[] plaintext)
               throws TokenException

Encrypts the given data with the key and mechanism.

Parameters:

mechanism - The mechanism to use; e.g. Mechanism.DES_CBC.

keyHandle - The decryption key to use.

plaintext - the to-be-encrypted data

Returns:

the encrypted data. Never returns null.

Throws:

TokenException - If encrypting failed.

encrypt

public int encrypt(OutputStream out,
                   Mechanism mechanism,
                   long keyHandle,
                   InputStream plaintext)
            throws TokenException,
                   IOException

This method can be used to encrypt large data.

Parameters:

out - Stream to which the cipher text is written.

mechanism - The mechanism to use.

keyHandle - The decryption key to use.

plaintext - Input-stream of the to-be-encrypted data

Returns:

length of the encrypted data.

Throws:

TokenException - If encrypting the data failed.

IOException - if reading data from the plaintext stream failed or writing to the ciphertext stream failed.

decrypt

public byte[] decrypt(Mechanism mechanism,
                      long keyHandle,
                      byte[] ciphertext)
               throws TokenException

Decrypts the given data with the key and mechanism.

Parameters:

mechanism - The mechanism to use.

keyHandle - The decryption key to use.

ciphertext - the to-be-decrypted data

Returns:

the decrypted data. Never returns null.

Throws:

TokenException - If encrypting failed.

decrypt

public int decrypt(OutputStream out,
                   Mechanism mechanism,
                   long keyHandle,
                   InputStream ciphertext)
            throws TokenException,
                   IOException

This method can be used to decrypt large data.

Parameters:

out - Stream to which the plain text is written.

mechanism - The mechanism to use.

keyHandle - The decryption key to use.

ciphertext - Input-stream of the to-be-encrypted data

Returns:

length of the decrypted data.

Throws:

TokenException - If decrypting the data failed.

IOException - if reading data from the ciphertext stream failed or writing to the plaintext stream failed.

digest

public byte[] digest(Mechanism mechanism,
                     byte[] data)
              throws TokenException

Digests the given data with the mechanism.

Parameters:

mechanism - The mechanism to use; e.g. Mechanism.SHA_1.

data - the to-be-digested data

Returns:

the message digest. Never returns null.

Throws:

TokenException - If digesting the data failed.

digestKey

public byte[] digestKey(Mechanism mechanism,
                        long keyHandle)
                 throws TokenException

Digests the given key with the mechanism.

Parameters:

mechanism - The mechanism to use; e.g. Mechanism.SHA_1.

keyHandle - handle of the to-be-digested key.

Returns:

the message digest. Never returns null.

Throws:

TokenException - If digesting the data failed.

digest

public byte[] digest(Mechanism mechanism,
                     InputStream data)
              throws TokenException,
                     IOException

Digests the large data with the mechanism.

Parameters:

mechanism - The mechanism to use; e.g. Mechanism.SHA_1.

data - the to-be-digested data

Returns:

the message digest. Never returns null.

Throws:

TokenException - If digesting the data failed.

IOException - if reading data from stream failed.

sign

public byte[] sign(Mechanism mechanism,
                   long keyHandle,
                   byte[] data)
            throws TokenException

Signs the given data with the key and mechanism.

Parameters:

mechanism - The mechanism to use.

keyHandle - The signing key to use.

data - The data to sign.

Returns:

The signed data. Never returns null.

Throws:

TokenException - If signing the data failed.

sign

public byte[] sign(Mechanism mechanism,
                   long keyHandle,
                   InputStream data)
            throws TokenException,
                   IOException

This method can be used to sign large data.

Parameters:

mechanism - The mechanism to use.

keyHandle - The signing key to use.

data - Input-stream of the to-be-signed data

Returns:

length of the signature.

Throws:

TokenException - If signing the data failed.

IOException - If reading data stream failed.

signRecover

public byte[] signRecover(Mechanism mechanism,
                          long keyHandle,
                          byte[] data)
                   throws TokenException

Sign-recovers the given data with the key and mechanism.

Parameters:

mechanism - The mechanism to use.

keyHandle - The signing key to use.

data - The data to sign-recovers.

Returns:

The signed data. Never returns null.

Throws:

TokenException - If signing the data failed.

verify

public boolean verify(Mechanism mechanism,
                      long keyHandle,
                      byte[] data,
                      byte[] signature)
               throws TokenException

Verifies the given signature against the given data with the key and mechanism. This method throws an exception, if the verification of the signature fails.

Parameters:

mechanism - The mechanism to use; e.g. Mechanism.RSA_PKCS.

keyHandle - The verification key to use.

data - The data that was signed.

signature - The signature or MAC to verify.

Returns:

true if signature is invalid, false otherwise.

Throws:

TokenException - If verifying the signature fails.

verify

public boolean verify(Mechanism mechanism,
                      long keyHandle,
                      InputStream data,
                      byte[] signature)
               throws TokenException,
                      IOException

This method can be used to verify large data.

Parameters:

mechanism - The mechanism to use.

keyHandle - The signing key to use.

data - Input-stream of the to-be-verified data

signature - the signature.

Returns:

true if signature is invalid, false otherwise.

Throws:

TokenException - If signing the data failed.

IOException - If reading data stream failed.

verifyRecover

public byte[] verifyRecover(Mechanism mechanism,
                            long keyHandle,
                            byte[] data)
                     throws TokenException

Verify-recovers the given data with the key and mechanism.

Parameters:

mechanism - The mechanism to use.

keyHandle - The signing key to use.

data - The data to be verify-recovered.

Returns:

The verify-recovered data. Never returns null.

Throws:

TokenException - If signing the data failed.

generateKey

public long generateKey(Mechanism mechanism,
                        AttributeVector template)
                 throws TokenException

Generate a new secret key or a set of domain parameters. It uses the set attributes of the template for setting the attributes of the new key object. As mechanism the application can use a constant of the Mechanism class.

Parameters:

mechanism - The mechanism to generate a key for; e.g. Mechanism.DES to generate a DES key.

template - The template for the new key or domain parameters; e.g. a DESSecretKey object which has set certain attributes.

Returns:

The newly generated secret key or domain parameters.

Throws:

TokenException - If generating a new secret key or domain parameters failed.

generateKeyPair

public PKCS11KeyPair generateKeyPair(Mechanism mechanism,
                                     KeyPairTemplate template)
                              throws TokenException

Generate a new public key - private key key-pair and use the set attributes of the template objects for setting the attributes of the new public key and private key objects. As mechanism the application can use a constant of the Mechanism class.

Parameters:

mechanism - The mechanism to generate a key for; e.g. Mechanism.RSA to generate a new RSA key-pair.

template - The template for the new keypair.

Returns:

The newly generated key-pair.

Throws:

TokenException - If generating a new key-pair failed.

wrapKey

public byte[] wrapKey(Mechanism mechanism,
                      long wrappingKeyHandle,
                      long keyHandle)
               throws TokenException

Wraps (encrypts) the given key with the wrapping key using the given mechanism.

Parameters:

mechanism - The mechanism to use for wrapping the key.

wrappingKeyHandle - The key to use for wrapping (encrypting).

keyHandle - The key to wrap (encrypt).

Returns:

The wrapped key as byte array. Never returns null.

Throws:

TokenException - If wrapping the key failed.

unwrapKey

public long unwrapKey(Mechanism mechanism,
                      long unwrappingKeyHandle,
                      byte[] wrappedKey,
                      AttributeVector keyTemplate)
               throws TokenException

Unwraps (decrypts) the given encrypted key with the unwrapping key using the given mechanism. The application can also pass a template key to set certain attributes of the unwrapped key. This creates a key object after unwrapping the key and returns an object representing this key.

Parameters:

mechanism - The mechanism to use for unwrapping the key.

unwrappingKeyHandle - The key to use for unwrapping (decrypting).

wrappedKey - The encrypted key to unwrap (decrypt).

keyTemplate - The template for creating the new key object.

Returns:

A key object representing the newly created key object.

Throws:

TokenException - If unwrapping the key or creating a new key object failed.

deriveKey

public long deriveKey(Mechanism mechanism,
                      long baseKeyHandle,
                      AttributeVector template)
               throws TokenException

Derives a new key from a specified base key using the given mechanism. After deriving a new key from the base key, a new key object is created and a representation of it is returned. The application can provide a template key to set certain attributes of the new key object.

Parameters:

mechanism - The mechanism to use for deriving the new key from the base key.

baseKeyHandle - The key to use as base for derivation.

template - The template for creating the new key object.

Returns:

A key object representing the newly derived (created) key object or null, if the used mechanism uses other means to return its values; e.g. the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism.

Throws:

TokenException - If deriving the key or creating a new key object failed.

generateRandom

public byte[] generateRandom(int numberOfBytesToGenerate)
                      throws TokenException

Generates a certain number of random bytes.

Parameters:

numberOfBytesToGenerate - The number of random bytes to generate.

Returns:

An array of random bytes with length numberOfBytesToGenerate.

Throws:

TokenException - If generating random bytes failed.

generateRandom

public byte[] generateRandom(int numberOfBytesToGenerate,
                             byte[] extraSeed)
                      throws TokenException

Generates a certain number of random bytes.

Parameters:

numberOfBytesToGenerate - The number of random bytes to generate.

extraSeed - The seed bytes to mix in.

Returns:

An array of random bytes with length numberOfBytesToGenerate.

Throws:

TokenException - If generating random bytes failed.

encryptMessages

public byte[][] encryptMessages(Mechanism mechanism,
                                long keyHandle,
                                EncryptMessageBytesEntry[] entries)
                         throws TokenException

Encrypts the given messages using the given mechanism and key

Parameters:

mechanism - The encryption mechanism

keyHandle - Handle of the encryption key.

entries - Arrays of plaintexts in byte[] with additional parameters to be encrypted.

Returns:

Array of ciphertexts. The result at index i is the ciphertext of entries[i].

Throws:

TokenException - If encrypting failed.

encryptMessages

public int[] encryptMessages(Mechanism mechanism,
                             long keyHandle,
                             EncryptMessageStreamEntry[] entries)
                      throws TokenException,
                             IOException

Encrypts the given messages using the given mechanism and key.

Parameters:

mechanism - The encryption mechanism

keyHandle - Handle of the encryption key.

entries - Arrays of plaintexts in stream with additional parameters to be encrypted.

Returns:

Array of lengths of ciphertext. The result at index i corresponds to entries[i].

Throws:

TokenException - If encrypting failed.

IOException - if reading or writing stream failed.

decryptMessages

public byte[][] decryptMessages(Mechanism mechanism,
                                long keyHandle,
                                DecryptMessageBytesEntry[] entries)
                         throws TokenException

Decrypts the given ciphertexts using the given mechanism and keys.

Parameters:

mechanism - The encryption mechanism

keyHandle - Handle of the encryption key.

entries - Arrays of ciphertexts in byte[] with additional parameters to be encrypted.

Returns:

Array of lengths of ciphertext. The result at index i corresponds to entries[i].

Throws:

TokenException - If encrypting failed.

decryptMessages

public int[] decryptMessages(Mechanism mechanism,
                             long keyHandle,
                             DecryptMessageStreamEntry[] entries)
                      throws TokenException,
                             IOException

Decrypts the given ciphertexts using the given mechanism and key.

Parameters:

mechanism - The encryption mechanism

keyHandle - Handle of the encryption key.

entries - Arrays of ciphertexts in stream with additional parameters to be encrypted.

Returns:

Array of lengths of ciphertext. The result at index i corresponds to entries[i].

Throws:

TokenException - If encrypting failed.

IOException - if reading or writing stream failed.

signMessages

public byte[][] signMessages(Mechanism mechanism,
                             long keyHandle,
                             SignMessageBytesEntry[] entries)
                      throws TokenException

Signs the given messages using the given mechanism and key.

Parameters:

mechanism - The encryption mechanism

keyHandle - Handle of the signing key.

entries - Arrays of messages in byte[] with additional parameters to be encrypted.

Returns:

Array of signatures. The result at index i corresponds to entries[i].

Throws:

TokenException - If signing failed.

signMessages

public byte[][] signMessages(Mechanism mechanism,
                             long keyHandle,
                             SignMessageStreamEntry[] entries)
                      throws TokenException,
                             IOException

Signs the given messages using the given mechanism and key.

Parameters:

mechanism - The encryption mechanism

keyHandle - Handle of the signing key.

entries - Arrays of messages in stream with additional parameters to be encrypted.

Returns:

Array of signatures. The result at index i corresponds to entries[i].

Throws:

TokenException - If signing failed.

IOException - if reading or writing stream failed.

verifyMessages

public boolean[] verifyMessages(Mechanism mechanism,
                                long keyHandle,
                                VerifyMessageBytesEntry[] entries)
                         throws TokenException

Throws:

TokenException

verifyMessages

public boolean[] verifyMessages(Mechanism mechanism,
                                long keyHandle,
                                VerifyMessageStreamEntry[] entries)
                         throws TokenException,
                                IOException

Verify the signatures over given messages using the given mechanism and key.

Parameters:

mechanism - The signature verification mechanism

keyHandle - Handle of the verification key.

entries - Arrays of messages in stream with additional parameters to be verified.

Returns:

Array of signature verification result. The result at index i corresponds to entries[i].

Throws:

TokenException - If verifying failed.

IOException - if reading or writing stream failed.

toString

public String toString()

Returns the string representation of this object.

Overrides:

toString in class Object

Returns:

the string representation of this object

getAttrValues

public AttributeVector getAttrValues(long objectHandle,
                                     long... attributeTypes)
                              throws TokenException

Gets give attributes for the given object handle.

Parameters:

objectHandle - the object handle.

attributeTypes - types of attributes to be read.

Returns:

attributes for the given object handle.

Throws:

TokenException - if getting attributes failed.

getAttrValues

public AttributeVector getAttrValues(long objectHandle,
                                     List<Long> attributeTypes)
                              throws TokenException

Gets give attributes for the given object handle.

Parameters:

objectHandle - the object handle.

attributeTypes - types of attributes to be read.

Returns:

attributes for the given object handle.

Throws:

TokenException - if getting attributes failed.

getDefaultAttrValues

public AttributeVector getDefaultAttrValues(long objectHandle)
                                     throws TokenException

Gets all attributes for the given object handle.

Parameters:

objectHandle - the object handle.

Returns:

all attributes for the given object handle.

Throws:

TokenException - if getting attributes failed.