|
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 | ||||||||||