|
IAIK PKCS#11 Wrapper version 1.2.16 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectiaik.pkcs.pkcs11.Session
Session objects are used to perform cryptographic operations on a token. The application gets a Session object by calling openSession on a certain Token object. Having the session object, the application may log-in the user, if required.
TokenInfo tokenInfo = token.getTokenInfo();
// check, if log-in of the user is required at all
if (tokenInfo.isLoginRequired()) {
// check, if the token has own means to authenticate the user; e.g. a PIN-pad on the reader
if (tokenInfo.isProtectedAuthenticationPath()) {
System.out.println("Please enter the user PIN at the PIN-pad of your reader.");
session.login(Session.UserType.USER, null); // the token prompts the PIN by other means; e.g. PIN-pad
} else {
System.out.print("Enter user-PIN and press [return key]: ");
System.out.flush();
BufferedReader input = new BufferedReader(new InputStreamReader(System.in));
String userPINString = input.readLine();
session.login(Session.UserType.USER, userPINString.toCharArray());
}
}
With this session object the application can search for token objects and
perform a cryptographic operation.
For example, to find private RSA keys that the application can use for
signing, you can write:
RSAPrivateKey privateSignatureKeyTemplate = new RSAPrivateKey();
privateSignatureKeyTemplate.getSign().setBooleanValue(Boolean.TRUE);
session.findObjectsInit(privateSignatureKeyTemplate);
Object[] privateSignatureKeys;
List signatureKeyList = new Vector(4);
while ((privateSignatureKeys = session.findObjects(1)).length > 0) {
signatureKeyList.add(privateSignatureKeys[0]);
}
session.findObjectsFinal();
Having chosen one of this keys, the application can create a signature value
using it.
// e.g. the encoded digest info object that contains an identifier of the
// hash algorithm and the hash value
byte[] toBeSigned;
// toBeSigned = ... assign value
RSAPrivateKey selectedSignatureKey;
// selectedSignatureKey = ... assign one of the available signature keys
// initialize for signing
session.signInit(Mechanism.RSA_PKCS, selectedSignatureKey);
// sign the data to be signed
byte[] signatureValue = session.sign(toBeSigned);
If the application does not need the session any longer, it should close the
session.
session.closeSession();
Object
,
Parameters
,
Session
,
SessionInfo
Nested Class Summary | |
static interface |
Session.UserType
This interface defines the different user tpyes of PKCS#11. |
Field Summary | |
protected Module |
module_
A reference to the underlying PKCS#11 module to perform the operations. |
protected PKCS11 |
pkcs11Module_
A reference to the underlying PKCS#11 module to perform the operations. |
protected long |
sessionHandle_
The session handle to perform the operations with. |
protected Token |
token_
The token to perform the operations on. |
Constructor Summary | |
protected |
Session(Token token,
long sessionHandle)
Constructor taking the token and the sesion handle. |
Method Summary | |
void |
cancelFunction()
Legacy function that will normally throw an PKCS11Exception with the error-code PKCS11Constants.CKR_FUNCTION_NOT_PARALLEL. |
void |
closeSession()
Closes this session. |
Object |
copyObject(Object sourceObject,
Object templateObject)
Copy an existing object. |
Object |
createObject(Object templateObject)
Create a new object on the token (or in the session). |
byte[] |
decrypt(byte[] data)
Decrypts the given data with the key and mechansim given to the decryptInit method. |
byte[] |
decryptDigestUpdate(byte[] part)
Dual-function. |
byte[] |
decryptFinal()
This method finalizes a decrpytion operation and returns the final result. |
void |
decryptInit(Mechanism mechanism,
Key key)
Initializes a new decryption operation. |
byte[] |
decryptUpdate(byte[] encryptedPart)
This method can be used to decrypt multiple pieces of data; e.g. |
byte[] |
decryptVerifyUpdate(byte[] encryptedPart)
Dual-function. |
Key |
deriveKey(Mechanism mechanism,
Key baseKey,
Key template)
Derives a new key from a specified base key unsing the given mechanism. |
void |
destroyObject(Object object)
Destroy a certain object on the token (or in the session). |
byte[] |
digest(byte[] data)
Digests the given data with the mechansim given to the digestInit method. |
byte[] |
digestEncryptedUpdate(byte[] part)
Dual-function. |
byte[] |
digestFinal()
This method finalizes a digesting operation and returns the final result. |
void |
digestInit(Mechanism mechanism)
Initializes a new digesting operation. |
void |
digestKey(SecretKey key)
This method is similar to digestUpdate and can be combined with it during one digesting operation. |
void |
digestUpdate(byte[] part)
This method can be used to digest multiple pieces of data; e.g. |
byte[] |
encrypt(byte[] data)
Encrypts the given data with the key and mechansim given to the encryptInit method. |
byte[] |
encryptFinal()
This method finalizes an encrpytion operation and returns the final result. |
void |
encryptInit(Mechanism mechanism,
Key key)
Initializes a new encryption operation. |
byte[] |
encryptUpdate(byte[] part)
This method can be used to encrypt multiple pieces of data; e.g. |
boolean |
equals(Object otherObject)
Compares the sessionHandle and token_ of this object with the other object. |
Object[] |
findObjects(int maxObjectCount)
Finds objects that match the template object passed to findObjectsInit. |
void |
findObjectsFinal()
Finalizes a find operation. |
void |
findObjectsInit(Object templateObject)
Initializes a find operations that provides means to find objects by passing a template object. |
Object |
generateKey(Mechanism mechanism,
Object template)
Generate a new secret key or a set of domain parameters. |
KeyPair |
generateKeyPair(Mechanism mechanism,
Object publicKeyTemplate,
Object privateKeyTemplate)
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. |
Object |
getAttributeValues(Object objectToRead)
Reads all the attributes of the given Object from the token and returns a new Object that contains all these attributes. |
void |
getFunctionStatus()
Legacy function that will normally throw an PKCS11Exception with the error-code PKCS11Constants.CKR_FUNCTION_NOT_PARALLEL. |
Module |
getModule()
Get the Module which this Session object operates with. |
long |
getObjectSize(Object object)
Get the size of the specified object in bytes. |
byte[] |
getOperationState()
Get the current operation state. |
long |
getSessionHandle()
Get the handle of this session. |
SessionInfo |
getSessionInfo()
Get information about this session. |
Token |
getToken()
Get the token that created this Session object. |
int |
hashCode()
The overriding of this method should ensure that the objects of this class work correctly in a hashtable. |
void |
initPIN(char[] pin)
Initializes the user-PIN. |
void |
login(boolean userType,
char[] pin)
Logs in the user or the security officer to the session. |
void |
logout()
Logs out this session. |
void |
seedRandom(byte[] seed)
Mixes additional seeding material into the random number generator. |
void |
setAttributeValues(Object objectToUpdate,
Object templateObject)
Gets all present attributes of the given template object an writes them to the object to update on the token (or in the session). |
void |
setOperationState(byte[] operationState,
Key encryptionKey,
Key authenticationKey)
Sets the operation state of this session to a previously saved one. |
void |
setPIN(char[] oldPin,
char[] newPin)
Set the user-PIN to a new value. |
byte[] |
sign(byte[] data)
Signs the given data with the key and mechansim given to the signInit method. |
byte[] |
signEncryptUpdate(byte[] part)
Dual-function. |
byte[] |
signFinal()
This method finalizes a signing operation and returns the final result. |
void |
signInit(Mechanism mechanism,
Key key)
Initializes a new signing operation. |
byte[] |
signRecover(byte[] data)
Signs the given data with the key and mechansim given to the signRecoverInit method. |
void |
signRecoverInit(Mechanism mechanism,
Key key)
Initializes a new signing operation for signing with recovery. |
void |
signUpdate(byte[] part)
This method can be used to sign multiple pieces of data; e.g. |
String |
toString()
Returns the string representation of this object. |
Key |
unwrapKey(Mechanism mechanism,
Key unwrappingKey,
byte[] wrappedKey,
Object keyTemplate)
Unwraps (decrypts) the given encrypted key with the unwrapping key using the given mechanism. |
void |
verify(byte[] data,
byte[] signature)
Verifies the given signature against the given data with the key and mechansim given to the verifyInit method. |
void |
verifyFinal(byte[] signature)
This method finalizes a verification operation. |
void |
verifyInit(Mechanism mechanism,
Key key)
Initializes a new verification operation. |
byte[] |
verifyRecover(byte[] signature)
Signs the given data with the key and mechansim given to the signRecoverInit method. |
void |
verifyRecoverInit(Mechanism mechanism,
Key key)
Initializes a new verification operation for verification with data recovery. |
void |
verifyUpdate(byte[] part)
This method can be used to verify a signature with multiple pieces of data; e.g. buffer-size pieces when reading the data from a stream. |
byte[] |
wrapKey(Mechanism mechanism,
Key wrappingKey,
Key key)
Wraps (encrypts) the given key with the wrapping key using the given mechanism. |
Methods inherited from class java.lang.Object |
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
protected Module module_
protected PKCS11 pkcs11Module_
protected long sessionHandle_
protected Token token_
Constructor Detail |
protected Session(Token token, long sessionHandle)
token
- The token this session operates with.sessionHandle
- The session handle to perform the operations with.Method Detail |
public void initPIN(char[] pin) throws TokenException
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.
TokenException
- If the session has not the right to set the PIN
of if the operation fails for some other reason.public void setPIN(char[] oldPin, char[] newPin) throws TokenException
oldPin
- The old (current) user-PIN.newPin
- The new value for the user-PIN.
TokenException
- If setting the new PIN fails.public void closeSession() throws TokenException
TokenException
- If closing the session failed.public boolean equals(Object otherObject)
otherObject
- The other Session object.
public int hashCode()
public long getSessionHandle()
public SessionInfo getSessionInfo() throws TokenException
TokenException
- If getting the information failed.public Module getModule()
public Token getToken()
public byte[] getOperationState() throws TokenException
TokenException
- If saving the state fails or is not possible.setOperationState(byte[],Key,Key)
public void setOperationState(byte[] operationState, Key encryptionKey, Key authenticationKey) throws TokenException
operationState
- The previously saved state as returned by
getOperationState().encryptionKey
- A encryption or decryption key, if a encryption or
decryption operation was saved which should be
continued, but the keys could not be saved.authenticationKey
- A signing, verification of MAC key, if a
signing, verification or MAC operation needs to
be restored that could not save the key.
TokenException
- If restoring the state fails.getOperationState()
public void login(boolean userType, char[] pin) throws TokenException
userType
- UserType.SO for the security officer or
UserType.USER to login the user.pin
- The PIN. The security officer-PIN or the user-PIN depending
on the userType parameter.
TokenException
- If login fails.public void logout() throws TokenException
TokenException
- If logging out the session fails.public Object createObject(Object templateObject) throws TokenException
DESSecretKey desKeyTemplate = new DESSecretKey();
// the key type is set by the DESSecretKey's constructor, so you need not do it
desKeyTemplate.setValue(myDesKeyValueAs8BytesLongByteArray);
desKeyTemplate.setToken(Boolean.TRUE);
desKeyTemplate.setPrivate(Boolean.TRUE);
desKeyTemplate.setEncrypt(Boolean.TRUE);
desKeyTemplate.setDecrypt(Boolean.TRUE);
...
DESSecretKey theCreatedDESKeyObject = (DESSecretKey) 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.
templateObject
- The template object that holds all values that the
new object on the token should contain.
(this is not a java.lang.Object!)
TokenException
- If the creation of the new object fails. If it
fails, the no new object was created on the
token.public Object copyObject(Object sourceObject, Object templateObject) throws TokenException
sourceObject
- The source object of the copy operation.templateObject
- A template object which's 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.
TokenException
- If copying the object fails for some reason.public void setAttributeValues(Object objectToUpdate, Object templateObject) throws TokenException
objectToUpdate
- The attributes of this object get updated.templateObject
- This methods gets all present attributes of this
template object and set this attributes at the
objectToUpdate.
TokenException
- If updateing the attributes fails. All or no
attributes are updated.public Object getAttributeValues(Object objectToRead) throws TokenException
objectToRead
- The object to newly read from the token.
TokenException
- If reading the attributes fails.public void destroyObject(Object object) throws TokenException
object
- The object that should be destroyed.
TokenException
- If the object could not be destroyed.public long getObjectSize(Object object) throws TokenException
object
- The object to get the size for.
TokenException
- If determining the size fails.public void findObjectsInit(Object templateObject) throws TokenException
templateObject
- 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.
TokenException
- If initializing the find operation fails.public Object[] findObjects(int maxObjectCount) throws TokenException
maxObjectCount
- Specifies how many objects to return with this call.
TokenException
- If finding objects failed.public void findObjectsFinal() throws TokenException
TokenException
- If finalizing the current find operation was not
possible.public void encryptInit(Mechanism mechanism, Key key) throws TokenException
mechanism
- The mechanism to use; e.g. Mechanism.DES_CBC.key
- The decryption key to use.
TokenException
- If initializing this operation failed.public byte[] encrypt(byte[] data) throws TokenException
data
- The data to encrpyt.
TokenException
- If encrypting failed.public byte[] encryptUpdate(byte[] part) throws TokenException
part
- The piece of data to encrpt.
TokenException
- If encrypting the data failed.public byte[] encryptFinal() throws TokenException
TokenException
- If calculating the final result failed.public void decryptInit(Mechanism mechanism, Key key) throws TokenException
mechanism
- The mechanism to use; e.g. Mechanism.DES_CBC.key
- The decryption key to use.
TokenException
- If initializing this operation failed.public byte[] decrypt(byte[] data) throws TokenException
data
- The data to decrpyt.
TokenException
- If decrypting failed.public byte[] decryptUpdate(byte[] encryptedPart) throws TokenException
encryptedPart
- The piece of data to decrpt.
TokenException
- If decrypting the data failed.public byte[] decryptFinal() throws TokenException
TokenException
- If calculating the final result failed.public void digestInit(Mechanism mechanism) throws TokenException
mechanism
- The mechanism to use; e.g. Mechanism.SHA_1.
TokenException
- If initializing this operation failed.public byte[] digest(byte[] data) throws TokenException
data
- The data to digest.
TokenException
- If digesting the data failed.public void digestUpdate(byte[] part) throws TokenException
part
- The piece of data to digest.
TokenException
- If digesting the data failed.public void digestKey(SecretKey key) throws TokenException
key
- The key to digest the value of.
TokenException
- If digesting the key failed.public byte[] digestFinal() throws TokenException
TokenException
- If calculating the final message digest failed.public void signInit(Mechanism mechanism, Key key) throws TokenException
mechanism
- The mechanism to use; e.g. Mechanism.RSA_PKCS.key
- The signing key to use.
TokenException
- If initializing this operation failed.public byte[] sign(byte[] data) throws TokenException
data
- The data to sign.
TokenException
- If signing the data failed.public void signUpdate(byte[] part) throws TokenException
part
- The piece of data to sign.
TokenException
- If signing the data failed.public byte[] signFinal() throws TokenException
TokenException
- If calculating the final signature value
failed.public void signRecoverInit(Mechanism mechanism, Key key) throws TokenException
mechanism
- The mechanism to use; e.g. Mechanism.RSA_9796.key
- The signing key to use.
TokenException
- If initializing this operation failed.public byte[] signRecover(byte[] data) throws TokenException
data
- The data to sign.
TokenException
- If signing the data failed.public void verifyInit(Mechanism mechanism, Key key) throws TokenException
mechanism
- The mechanism to use; e.g. Mechanism.RSA_PKCS.key
- The verification key to use.
TokenException
- If initializing this operation failed.public void verify(byte[] data, byte[] signature) throws TokenException
data
- The data that was signed.signature
- The signature or MAC to verify.
TokenException
- If verifying the signature fails. This is also
the case, if the signature is forged.public void verifyUpdate(byte[] part) throws TokenException
part
- The piece of data to verify against.
TokenException
- If verifying (e.g. digesting) the data failed.public void verifyFinal(byte[] signature) throws TokenException
signature
- The signature value.
TokenException
- If verifying the signature fails. This is also
the case, if the signature is forged.public void verifyRecoverInit(Mechanism mechanism, Key key) throws TokenException
mechanism
- The mechanism to use; e.g. Mechanism.RSA_9796.key
- The verification key to use.
TokenException
- If initializing this operation failed.public byte[] verifyRecover(byte[] signature) throws TokenException
signature
- The data to sign.
TokenException
- If signing the data failed.public byte[] digestEncryptedUpdate(byte[] part) throws TokenException
part
- The piece of data to digest and encrypt.
TokenException
- If digesting or encrypting the data failed.public byte[] decryptDigestUpdate(byte[] part) throws TokenException
part
- The piece of data to decrypt and digest.
TokenException
- If decrypting or digesting the data failed.public byte[] signEncryptUpdate(byte[] part) throws TokenException
part
- The piece of data to sign and encrypt.
TokenException
- If signing or encrypting the data failed.public byte[] decryptVerifyUpdate(byte[] encryptedPart) throws TokenException
encryptedPart
- The piece of data to decrypt and verify.
TokenException
- If decrypting or verifying the data failed.public Object generateKey(Mechanism mechanism, Object template) throws TokenException
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.
TokenException
- If generating a new secert key or domain
parameters failed.public KeyPair generateKeyPair(Mechanism mechanism, Object publicKeyTemplate, Object privateKeyTemplate) throws TokenException
mechanism
- The mechanism to generate a key for; e.g. Mechanism.RSA
to generate a new RSA key-pair.publicKeyTemplate
- The template for the new public key part; e.g. a
RSAPublicKey object which has set certain
attributes (e.g. public exponent and verify).privateKeyTemplate
- The template for the new private key part; e.g. a
RSAPrivateKey object which has set certain
attributes (e.g. sign and decrypt).
TokenException
- If generating a new key-pair failed.public byte[] wrapKey(Mechanism mechanism, Key wrappingKey, Key key) throws TokenException
mechanism
- The mechanism to use for wrapping the key.wrappingKey
- The key to use for wrapping (encrypting).key
- The key to wrap (encrypt).
TokenException
- If wrapping the key failed.public Key unwrapKey(Mechanism mechanism, Key unwrappingKey, byte[] wrappedKey, Object keyTemplate) throws TokenException
mechanism
- The mechanism to use for unwrapping the key.unwrappingKey
- The key to use for unwrapping (decrypting).wrappedKey
- The encrypted key to unwrap (decrypt).keyTemplate
- The template for creating the new key object.
TokenException
- If unwrapping the key or creating a new key
object failed.public Key deriveKey(Mechanism mechanism, Key baseKey, Key template) throws TokenException
mechanism
- The mechanism to use for deriving the new key from the
base key.baseKey
- The key to use as base for derivation.template
- The template for creating the new key object.
TokenException
- If deriving the key or creating a new key
object failed.public void seedRandom(byte[] seed) throws TokenException
seed
- The seed bytes to mix in.
TokenException
- If mixing in the seed failed.public byte[] generateRandom(int numberOfBytesToGenerate) throws TokenException
numberOfBytesToGenerate
- The number of random bytes to generate.
TokenException
- If generating random bytes failed.public void getFunctionStatus() throws TokenException
TokenException
- Throws always an PKCS11Excption.public void cancelFunction() throws TokenException
TokenException
- Throws always an PKCS11Excption.public String toString()
|
IAIK PKCS#11 Wrapper version 1.2.16 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |