// Copyright (c) 2002 Graz University of Technology. All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without modification,
// are permitted provided that the following conditions are met:
// 
// 1. Redistributions of source code must retain the above copyright notice, this
//    list of conditions and the following disclaimer.
// 
// 2. Redistributions in binary form must reproduce the above copyright notice,
//    this list of conditions and the following disclaimer in the documentation
//    and/or other materials provided with the distribution.
// 
// 3. The end-user documentation included with the redistribution, if any, must
//    include the following acknowledgment:
// 
//    "This product includes software developed by IAIK of Graz University of
//     Technology."
// 
//    Alternately, this acknowledgment may appear in the software itself, if and
//    wherever such third-party acknowledgments normally appear.
// 
// 4. The names "Graz University of Technology" and "IAIK of Graz University of
//    Technology" must not be used to endorse or promote products derived from this
//    software without prior written permission.
// 
// 5. Products derived from this software may not be called "IAIK PKCS Wrapper",
//    nor may "IAIK" appear in their name, without prior written permission of
//    Graz University of Technology.
// 
// THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE LICENSOR BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
// OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
// ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
// OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
package iaik.pkcs.pkcs11;

import iaik.pkcs.pkcs11.objects.Key;
import iaik.pkcs.pkcs11.objects.KeyPair;
import iaik.pkcs.pkcs11.objects.Object;
import iaik.pkcs.pkcs11.objects.PrivateKey;
import iaik.pkcs.pkcs11.objects.PublicKey;
import iaik.pkcs.pkcs11.objects.SecretKey;
import iaik.pkcs.pkcs11.parameters.Parameters;
import iaik.pkcs.pkcs11.parameters.SSL3KeyMaterialParameters;
import iaik.pkcs.pkcs11.parameters.SSL3MasterKeyDeriveParameters;
import iaik.pkcs.pkcs11.wrapper.CK_ATTRIBUTE;
import iaik.pkcs.pkcs11.wrapper.CK_MECHANISM;
import iaik.pkcs.pkcs11.wrapper.CK_SESSION_INFO;
import iaik.pkcs.pkcs11.wrapper.CK_SSL3_KEY_MAT_PARAMS;
import iaik.pkcs.pkcs11.wrapper.CK_SSL3_MASTER_KEY_DERIVE_PARAMS;
import iaik.pkcs.pkcs11.wrapper.Constants;
import iaik.pkcs.pkcs11.wrapper.Functions;
import iaik.pkcs.pkcs11.wrapper.PKCS11;
import iaik.pkcs.pkcs11.wrapper.PKCS11Constants;

import java.util.Vector;
import java.util.concurrent.atomic.AtomicInteger;

/**
 * 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.
 *
 * <pre>
 * <code>
 *   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());
 *     }
 *   }
 * </code>
 * </pre>
 *
 * 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:
 *
 * <pre>
 * <code>
 *   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();
 * </code>
 * </pre>
 *
 * Having chosen one of this keys, the application can create a signature value
 * using it.
 *
 * <pre>
 * <code>
 *   // 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);
 * </code>
 * </pre>
 *
 * If the application does not need the session any longer, it should close the
 * session.
 *
 * <pre>
 * <code>
 *   session.closeSession();
 * </code>
 * </pre>
 *
 * @see iaik.pkcs.pkcs11.objects.Object
 * @see iaik.pkcs.pkcs11.parameters.Parameters
 * @see iaik.pkcs.pkcs11.Session
 * @see iaik.pkcs.pkcs11.SessionInfo
 * @author Karl Scheibelhofer
 * @version 1.0
 * @invariants (pkcs11Module_ <> null)
 */
public class Session {

    /**
     * This interface defines the different user types of PKCS#11.
     *
     * @author Karl Scheibelhofer
     * @version 1.0
     * @invariants
     */
    public interface UserType {

        /**
         * This constant stands for the security officer.
         */
        public static boolean SO = false;

        /**
         * Thsi constant stands for the user (token owner).
         */
        public static boolean USER = true;

    }

    /**
     * A reference to the underlying PKCS#11 module to perform the operations.
     */
    protected Module module_;

    /**
     * A reference to the underlying PKCS#11 module to perform the operations.
     */
    protected PKCS11 pkcs11Module_;

    /**
     * The session handle to perform the operations with.
     */
    protected long sessionHandle_;

    /**
     * The token to perform the operations on.
     */
    protected Token token_;

    /**
     * True, if UTF8 encoding is used as character encoding for character array
     * attributes and PINs.
     */
    private boolean useUtf8Encoding_;

    // time after which to close idle sessions, in milliseconds (3 minutes)
    private final static long MAX_IDLE_TIME = 3 * 60 * 1000;

    // number of objects created within this session
    private final AtomicInteger createdObjects;

    // time this session was last used
    // not synchronized/volatile for performance, so may be unreliable
    // this could lead to idle sessions being closed early, but that is harmless
    private long lastAccess;

    /**
     * Constructor taking the token and the session handle.
     *
     * @param token The token this session operates with.
     * @param sessionHandle The session handle to perform the operations with.
     * @preconditions (token <> null)
     * @postconditions
     */
    protected Session(Token token, long sessionHandle) {
        if (token == null) {
            throw new NullPointerException("Argument \"token\" must not be null.");
        }
        token_ = token;
        module_ = token_.getSlot().getModule();
        pkcs11Module_ = module_.getPKCS11Module();
        sessionHandle_ = sessionHandle;
        useUtf8Encoding_ = token.useUtf8Encoding_;

        createdObjects = new AtomicInteger();
    }

    boolean isLive(long currentTime) {
        return currentTime - lastAccess < MAX_IDLE_TIME;
    }

    long id() throws TokenException {
        if (token_.getSlot().getSlotInfo().isTokenPresent() == false) {
            throw new TokenException("Token has been removed");
        }

        return sessionHandle_;
    }

    int addObject() {
        int n = createdObjects.incrementAndGet();
        // XXX update statistics in session manager if n == 1
        return n;
    }

    int removeObject() {
        int n = createdObjects.decrementAndGet();
        return n;
    }

    public boolean hasObjects() {
        return createdObjects.get() != 0;
    }

    /**
     * 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.
     *
     * @param 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.
     * @exception TokenException If the session has not the right to set the PIN
     * of if the operation fails for some other reason.
     * @preconditions
     * @postconditions
     */
    public void initPIN(char[] pin)
            throws TokenException {
        pkcs11Module_.C_InitPIN(sessionHandle_, pin, useUtf8Encoding_);
    }

    /**
     * Set the user-PIN to a new value. Can only be called from a read-write
     * sessions.
     *
     * @param oldPin The old (current) user-PIN.
     * @param newPin The new value for the user-PIN.
     * @exception TokenException If setting the new PIN fails.
     * @preconditions
     * @postconditions
     */
    public void setPIN(char[] oldPin, char[] newPin)
            throws TokenException {
        pkcs11Module_.C_SetPIN(sessionHandle_, oldPin, newPin, useUtf8Encoding_);
    }

    /**
     * Closes this session.
     *
     * @exception TokenException If closing the session failed.
     * @preconditions
     * @postconditions
     */
    public void closeSession()
            throws TokenException {
        pkcs11Module_.C_CloseSession(sessionHandle_);
    }

    /**
     * Compares the sessionHandle and token_ of this object with the other
     * object. Returns only true, if those are equal in both objects.
     *
     * @param otherObject The other Session object.
     * @return True, if other is an instance of Token and the session handles
     * and tokens of both objects are equal. False, otherwise.
     * @preconditions
     * @postconditions
     */
    public boolean equals(java.lang.Object otherObject) {
        boolean equal = false;

        if (otherObject instanceof Session) {
            Session other = (Session) otherObject;
            equal = (this == other)
                    || ((this.sessionHandle_ == other.sessionHandle_) && this.token_
                            .equals(other.token_));
        }

        return equal;
    }

    /**
     * The overriding of this method should ensure that the objects of this
     * class work correctly in a hashtable.
     *
     * @return The hash code of this object. Gained from the sessionHandle.
     * @preconditions
     * @postconditions
     */
    public int hashCode() {
        return (int) sessionHandle_;
    }

    /**
     * Get the handle of this session.
     *
     * @return The handle of this session.
     * @preconditions
     * @postconditions
     */
    public long getSessionHandle() {
        return sessionHandle_;
    }

    /**
     * Get information about this session.
     *
     * @return An object providing information about this session.
     * @exception TokenException If getting the information failed.
     * @preconditions
     * @postconditions (result <> null)
     */
    public SessionInfo getSessionInfo()
            throws TokenException {
        CK_SESSION_INFO ckSessionInfo = pkcs11Module_.C_GetSessionInfo(sessionHandle_);

        return new SessionInfo(ckSessionInfo);
    }

    /**
     * Get the Module which this Session object operates with.
     *
     * @return The module of this session.
     * @preconditions
     * @postconditions
     */
    public Module getModule() {
        return module_;
    }

    /**
     * Get the token that created this Session object.
     *
     * @return The token of this session.
     * @preconditions
     * @postconditions
     */
    public Token getToken() {
        return token_;
    }

    /**
     * Get the current operation state. This state can be used later to restore
     * the operation to exactly this state.
     *
     * @return The current operation state as a byte array.
     * @exception TokenException If saving the state fails or is not possible.
     * @see #setOperationState(byte[],Key,Key)
     * @preconditions
     * @postconditions (result <> null)
     */
    public byte[] getOperationState()
            throws TokenException {
        return pkcs11Module_.C_GetOperationState(sessionHandle_);
    }

    /**
     * Sets the operation state of this session to a previously saved one. This
     * method may need the key used during the saved operation to continue,
     * because it may not be possible to save a key into the state's byte array.
     * Refer to the PKCS#11 standard for details on this function.
     *
     * @param operationState The previously saved state as returned by
     * getOperationState().
     * @param 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.
     * @param authenticationKey A signing, verification of MAC key, if a
     * signing, verification or MAC operation needs to be restored that could
     * not save the key.
     * @exception TokenException If restoring the state fails.
     * @see #getOperationState()
     * @preconditions
     * @postconditions
     */
    public void setOperationState(byte[] operationState,
            Key encryptionKey,
            Key authenticationKey)
            throws TokenException {
        pkcs11Module_.C_SetOperationState(sessionHandle_, operationState,
                encryptionKey.getObjectHandle(), authenticationKey.getObjectHandle());
    }

    /**
     * Returns whether UTF8 encoding is set.
     *
     * @return true, if UTF8 is used as character encoding for character array
     * attributes and PINs.
     */
    public boolean isSetUtf8Encoding() {
        return useUtf8Encoding_;
    }

    /**
     * Logs in the user or the security officer to the session. Notice that all
     * sessions of a token have the same login state; i.e. if you login the user
     * to one session all other open sessions of this token get user rights.
     *
     * @param userType UserType.SO for the security officer or UserType.USER to
     * login the user.
     * @param pin The PIN. The security officer-PIN or the user-PIN depending on
     * the userType parameter.
     * @exception TokenException If login fails.
     * @preconditions
     * @postconditions
     */
    public void login(boolean userType, char[] pin)
            throws TokenException {
        long lUserType = (userType == UserType.SO) ? PKCS11Constants.CKU_SO
                : PKCS11Constants.CKU_USER;
        pkcs11Module_.C_Login(sessionHandle_, lUserType, pin, useUtf8Encoding_);
    }

    /**
     * Logs out this session.
     *
     * @exception TokenException If logging out the session fails.
     * @preconditions
     * @postconditions
     */
    public void logout()
            throws TokenException {
        pkcs11Module_.C_Logout(sessionHandle_);
    }

    /**
     * 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 DESSecretKey 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: <code>
     *   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);
     * </code> 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.
     *
     * @param templateObject The template object that holds all values that the
     * new object on the token should contain. (this is not a java.lang.Object!)
     * @return A new PKCS#11 Object (this is not a java.lang.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.
     * @exception TokenException If the creation of the new object fails. If it
     * fails, the no new object was created on the token.
     * @preconditions (templateObject <> null)
     * @postconditions (result <> null)
     */
    public Object createObject(Object templateObject)
            throws TokenException {
        CK_ATTRIBUTE[] ckAttributes = Object.getSetAttributes(templateObject);
        long objectHandle = pkcs11Module_.C_CreateObject(sessionHandle_, ckAttributes, useUtf8Encoding_);

        return Object.getInstance(this, objectHandle);
    }

    /**
     * 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 ist
     * created. See the PKCS#11 standard for details.
     *
     * @param sourceObject The source object of the copy operation.
     * @param 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.
     * @return The new object that is created by copying the source object and
     * setting attributes to the values given by the templateObject.
     * @exception TokenException If copying the object fails for some reason.
     * @preconditions (sourceObject <> null)
     * @postconditions
     */
    public Object copyObject(Object sourceObject, Object templateObject)
            throws TokenException {
        long sourceObjectHandle = sourceObject.getObjectHandle();
        CK_ATTRIBUTE[] ckAttributes = Object.getSetAttributes(templateObject);
        long newObjectHandle = pkcs11Module_.C_CopyObject(sessionHandle_, sourceObjectHandle,
                ckAttributes, useUtf8Encoding_);

        return Object.getInstance(this, newObjectHandle);
    }

    /**
     * Gets all present attributes of the given template object an 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.
     *
     * @param objectToUpdate The attributes of this object get updated.
     * @param templateObject This methods gets all present attributes of this
     * template object and set this attributes at the objectToUpdate.
     * @exception TokenException If updateing the attributes fails. All or no
     * attributes are updated.
     * @preconditions (objectToUpdate <> null) and (template <> null)
     * @postconditions
     */
    public void setAttributeValues(Object objectToUpdate, Object templateObject)
            throws TokenException {
        long objectToUpdateHandle = objectToUpdate.getObjectHandle();
        CK_ATTRIBUTE[] ckAttributesTemplates = Object.getSetAttributes(templateObject);
        pkcs11Module_.C_SetAttributeValue(sessionHandle_, objectToUpdateHandle,
                ckAttributesTemplates, useUtf8Encoding_);
    }

    /**
     * Reads all the attributes of the given Object from the token and returns a
     * new Object that contains all these attributes. The given objectToRead and
     * the returned Object are different Java objects. This method just uses the
     * object handle of the given object, it does not modify anything in this
     * object.
     *
     * @param objectToRead The object to newly read from the token.
     * @return A new Object holding all attributes that this method just read
     * from the token.
     * @exception TokenException If reading the attributes fails.
     * @preconditions (objectToRead <> null)
     * @postconditions (result <> null)
     */
    public Object getAttributeValues(Object objectToRead)
            throws TokenException {
        long objectHandle = objectToRead.getObjectHandle();

        return Object.getInstance(this, objectHandle);
    }

    /**
     * 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.
     *
     * @param object The object that should be destroyed.
     * @exception TokenException If the object could not be destroyed.
     * @preconditions (object <> null)
     * @postconditions
     */
    public void destroyObject(Object object)
            throws TokenException {
        long objectHandle = object.getObjectHandle();
        pkcs11Module_.C_DestroyObject(sessionHandle_, objectHandle);
    }

    /**
     * Get the size of the specified object in bytes. This size specifies how
     * much memory the object takes up on the token.
     *
     * @param object The object to get the size for.
     * @return The object's size bytes.
     * @exception TokenException If determining the size fails.
     * @preconditions (object <> null)
     * @postconditions
     */
    public long getObjectSize(Object object)
            throws TokenException {
        long objectHandle = object.getObjectHandle();
        return pkcs11Module_.C_GetObjectSize(sessionHandle_, objectHandle);
    }

    /**
     * Initializes a find operations that provides means to find objects by
     * passing a template object. This method get all set attributes of the
     * template object ans searches for all objects on the token that match with
     * these attributes.
     *
     * @param 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.
     * @exception TokenException If initializing the find operation fails.
     * @preconditions
     * @postconditions
     */
    public void findObjectsInit(Object templateObject)
            throws TokenException {
        CK_ATTRIBUTE[] ckAttributes = Object.getSetAttributes(templateObject);
        pkcs11Module_.C_FindObjectsInit(sessionHandle_, ckAttributes, useUtf8Encoding_);
    }

    /**
     * Finds objects that match the template object passed to findObjectsInit.
     * The application must call findObjectsInit before calling this method.
     * With maxObjectCount the application can specifay how many objects to
     * return at once; i.e. the application can get all found objects by
     * susequent calls to this method like maxObjectCount(1) until it receives
     * an empty array (this method never returns null!).
     *
     * @param maxObjectCount Specifies how many objects to return with this
     * call.
     * @return An array of found objects. The maximum size of this array is
     * maxObjectCount, the minimum length is 0. Never returns null.
     * @exception TokenException A plain TokenException if something during
     * PKCS11 FindObject went wrong, a TokenException with a nested
     * TokenException if the Exception is raised during object parsing.
     * @preconditions
     * @postconditions (result <> null)
     */
    public Object[] findObjects(int maxObjectCount)
            throws TokenException {
        Vector foundObjects = new Vector();
        long[] objectHandles = pkcs11Module_.C_FindObjects(sessionHandle_, maxObjectCount);

        try {
            for (int i = 0; i < objectHandles.length; i++) {
                Object object = Object.getInstance(this, objectHandles[i]);
                foundObjects.addElement(object);
            }
            Object[] objectArray = new Object[foundObjects.size()];
            foundObjects.copyInto(objectArray);

            return objectArray;
        } catch (TokenException e) {
            // encapsulate exception to signal a cause other than C_FindObjects
            throw new TokenException(e);
        }
    }

    /**
     * Finalizes a find operation. The application must call this method to
     * finalize a find operation before attempting to start any other operation.
     *
     * @exception TokenException If finalizing the current find operation was
     * not possible.
     * @preconditions
     * @postconditions
     */
    public void findObjectsFinal()
            throws TokenException {
        pkcs11Module_.C_FindObjectsFinal(sessionHandle_);
    }

    /**
     * Initializes a new encryption operation. The application must call this
     * method before calling any other encrypt* operation. Before initializing a
     * new operation, any currently pending operation must be finalized using
     * the appropriate *Final method (e.g. digestFinal()). There are exceptions
     * for dual-function operations. This method requires the mechansim to use
     * for encrpytion and the key for this oepration. The key must have set its
     * encryption flag. For the mechanism the application may use a constant
     * defined in the Mechanism class. Notice that the key and the mechanism
     * must be compatible; i.e. you cannot use a DES key with the RSA mechanism.
     *
     * @param mechanism The mechanism to use; e.g. Mechanism.DES_CBC.
     * @param key The decryption key to use.
     * @exception TokenException If initializing this operation failed.
     * @preconditions (mechansim <> null) and (key <> null)
     * @postconditions
     */
    public void encryptInit(Mechanism mechanism, Key key)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        pkcs11Module_.C_EncryptInit(sessionHandle_, ckMechanism, key.getObjectHandle(), useUtf8Encoding_);
    }

    /**
     * Encrypts the given data with the key and mechansim given to the
     * encryptInit method. This method finalizes the current encryption
     * operation; i.e. the application need (and should) not call encryptFinal()
     * after this call. For encrypting multiple pices of data use encryptUpdate
     * and encryptFinal.
     *
     * @param data The data to encrpyt.
     * @return The encrpyted data.
     * @exception TokenException If encrypting failed.
     * @preconditions (data <> null)
     * @postconditions (result <> null)
     */
    public byte[] encrypt(byte[] data)
            throws TokenException {
        return pkcs11Module_.C_Encrypt(sessionHandle_, data);
    }

    /**
     * This method can be used to encrypt multiple pieces of data; e.g.
     * buffer-size pieces when reading the data from a stream. Encrypts the
     * given data with the key and mechansim given to the encryptInit method.
     * The application must call encryptFinal to get the final result of the
     * encryption after feeding in all data using this method.
     *
     * @param part The piece of data to encrpt.
     * @return The intermediate encryption result. May not be available. To get
     * the final result call encryptFinal.
     * @exception TokenException If encrypting the data failed.
     * @preconditions (part <> null)
     * @postconditions
     */
    public byte[] encryptUpdate(byte[] part)
            throws TokenException {
        return pkcs11Module_.C_EncryptUpdate(sessionHandle_, part);
    }

    /**
     * This method finalizes an encrpytion operation and returns the final
     * result. Use this method, if you fed in the data using encryptUpdate. If
     * you used the encrypt(byte[]) method, you need not (and shall not) call
     * this method, because encrypt(byte[]) finalizes the encryption itself.
     *
     * @return The final result of the encryption; i.e. the encrypted data.
     * @exception TokenException If calculating the final result failed.
     * @preconditions
     * @postconditions (result <> null)
     */
    public byte[] encryptFinal()
            throws TokenException {
        return pkcs11Module_.C_EncryptFinal(sessionHandle_);
    }

    /**
     * Initializes a new decryption operation. The application must call this
     * method before calling any other decrypt* operation. Before initializing a
     * new operation, any currently pending operation must be finalized using
     * the appropriate *Final method (e.g. digestFinal()). There are exceptions
     * for dual-function operations. This method requires the mechansim to use
     * for decrpytion and the key for this oepration. The key must have set its
     * decryption flag. For the mechanism the application may use a constant
     * defined in the Mechanism class. Notice that the key and the mechanism
     * must be compatible; i.e. you cannot use a DES key with the RSA mechanism.
     *
     * @param mechanism The mechanism to use; e.g. Mechanism.DES_CBC.
     * @param key The decryption key to use.
     * @exception TokenException If initializing this operation failed.
     * @preconditions (mechansim <> null) and (key <> null)
     * @postconditions
     */
    public void decryptInit(Mechanism mechanism, Key key)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        pkcs11Module_.C_DecryptInit(sessionHandle_, ckMechanism, key.getObjectHandle(), useUtf8Encoding_);
    }

    /**
     * Decrypts the given data with the key and mechansim given to the
     * decryptInit method. This method finalizes the current decryption
     * operation; i.e. the application need (and should) not call decryptFinal()
     * after this call. For decrypting multiple pices of data use decryptUpdate
     * and decryptFinal.
     *
     * @param data The data to decrpyt.
     * @return The decrpyted data.
     * @exception TokenException If decrypting failed.
     * @preconditions (data <> null)
     * @postconditions (result <> null)
     */
    public byte[] decrypt(byte[] data)
            throws TokenException {
        return pkcs11Module_.C_Decrypt(sessionHandle_, data);
    }

    /**
     * This method can be used to decrypt multiple pieces of data; e.g.
     * buffer-size pieces when reading the data from a stream. Decrypts the
     * given data with the key and mechansim given to the decryptInit method.
     * The application must call decryptFinal to get the final result of the
     * encryption after feeding in all data using this method.
     *
     * @param encryptedPart The piece of data to decrpt.
     * @return The intermediate decryption result. May not be available. To get
     * the final result call decryptFinal.
     * @exception TokenException If decrypting the data failed.
     * @preconditions (encryptedPart <> null)
     * @postconditions
     */
    public byte[] decryptUpdate(byte[] encryptedPart)
            throws TokenException {
        return pkcs11Module_.C_DecryptUpdate(sessionHandle_, encryptedPart);
    }

    /**
     * This method finalizes a decrpytion operation and returns the final
     * result. Use this method, if you fed in the data using decryptUpdate. If
     * you used the decrypt(byte[]) method, you need not (and shall not) call
     * this method, because decrypt(byte[]) finalizes the decryption itself.
     *
     * @return The final result of the decryption; i.e. the decrypted data.
     * @exception TokenException If calculating the final result failed.
     * @preconditions
     * @postconditions (result <> null)
     */
    public byte[] decryptFinal()
            throws TokenException {
        return pkcs11Module_.C_DecryptFinal(sessionHandle_);
    }

    /**
     * Initializes a new digesting operation. The application must call this
     * method before calling any other digest* operation. Before initializing a
     * new operation, any currently pending operation must be finalized using
     * the appropriate *Final method (e.g. digestFinal()). There are exceptions
     * for dual-function operations. This method requires the mechansim to use
     * for digesting for this oepration. For the mechanism the application may
     * use a constant defined in the Mechanism class.
     *
     * @param mechanism The mechanism to use; e.g. Mechanism.SHA_1.
     * @exception TokenException If initializing this operation failed.
     * @preconditions (mechansim <> null)
     * @postconditions
     */
    public void digestInit(Mechanism mechanism)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        pkcs11Module_.C_DigestInit(sessionHandle_, ckMechanism, useUtf8Encoding_);
    }

    /**
     * Digests the given data with the mechansim given to the digestInit method.
     * This method finalizes the current digesting operation; i.e. the
     * application need (and should) not call digestFinal() after this call. For
     * digesting multiple pices of data use digestUpdate and digestFinal.
     *
     * @param data The data to digest.
     * @return The digested data.
     * @exception TokenException If digesting the data failed.
     * @preconditions (data <> null)
     * @postconditions (result <> null)
     */
    public byte[] digest(byte[] data)
            throws TokenException {
        return pkcs11Module_.C_Digest(sessionHandle_, data);
    }

    /**
     * This method can be used to digest multiple pieces of data; e.g.
     * buffer-size pieces when reading the data from a stream. Digests the given
     * data with the mechansim given to the digestInit method. The application
     * must call digestFinal to get the final result of the digesting after
     * feeding in all data using this method.
     *
     * @param part The piece of data to digest.
     * @exception TokenException If digesting the data failed.
     * @preconditions (part <> null)
     * @postconditions
     */
    public void digestUpdate(byte[] part)
            throws TokenException {
        pkcs11Module_.C_DigestUpdate(sessionHandle_, part);
    }

    /**
     * This method is similar to digestUpdate and can be combined with it during
     * one digesting operation. This method digests the value of the given
     * secret key.
     *
     * @param key The key to digest the value of.
     * @exception TokenException If digesting the key failed.
     * @preconditions (key <> null)
     * @postconditions
     */
    public void digestKey(SecretKey key)
            throws TokenException {
        pkcs11Module_.C_DigestKey(sessionHandle_, key.getObjectHandle());
    }

    /**
     * This method finalizes a digesting operation and returns the final result.
     * Use this method, if you fed in the data using digestUpdate and/or
     * digestKey. If you used the digest(byte[]) method, you need not (and shall
     * not) call this method, because digest(byte[]) finalizes the digesting
     * itself.
     *
     * @return The final result of the digesting; i.e. the message digest.
     * @exception TokenException If calculating the final message digest failed.
     * @preconditions
     * @postconditions (result <> null)
     */
    public byte[] digestFinal()
            throws TokenException {
        return pkcs11Module_.C_DigestFinal(sessionHandle_);
    }

    /**
     * Initializes a new signing operation. Use it for signatures and MACs. The
     * application must call this method before calling any other sign*
     * operation. Before initializing a new operation, any currently pending
     * operation must be finalized using the appropriate *Final method (e.g.
     * digestFinal()). There are exceptions for dual-function operations. This
     * method requires the mechansim to use for signing and the key for this
     * oepration. The key must have set its sign flag. For the mechanism the
     * application may use a constant defined in the Mechanism class. Notice
     * that the key and the mechanism must be compatible; i.e. you cannot use a
     * DES key with the RSA mechanism.
     *
     * @param mechanism The mechanism to use; e.g. Mechanism.RSA_PKCS.
     * @param key The signing key to use.
     * @exception TokenException If initializing this operation failed.
     * @preconditions (mechansim <> null) and (key <> null)
     * @postconditions
     */
    public void signInit(Mechanism mechanism, Key key)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        pkcs11Module_.C_SignInit(sessionHandle_, ckMechanism, key.getObjectHandle(), useUtf8Encoding_);
    }

    /**
     * Signs the given data with the key and mechansim given to the signInit
     * method. This method finalizes the current signing operation; i.e. the
     * application need (and should) not call signFinal() after this call. For
     * signing multiple pices of data use signUpdate and signFinal.
     *
     * @param data The data to sign.
     * @return The signed data.
     * @exception TokenException If signing the data failed.
     * @preconditions (data <> null)
     * @postconditions (result <> null)
     */
    public byte[] sign(byte[] data)
            throws TokenException {
        return pkcs11Module_.C_Sign(sessionHandle_, data);
    }

    /**
     * This method can be used to sign multiple pieces of data; e.g. buffer-size
     * pieces when reading the data from a stream. Signs the given data with the
     * mechansim given to the signInit method. The application must call
     * signFinal to get the final result of the signing after feeding in all
     * data using this method.
     *
     * @param part The piece of data to sign.
     * @exception TokenException If signing the data failed.
     * @preconditions (part <> null)
     * @postconditions
     */
    public void signUpdate(byte[] part)
            throws TokenException {
        pkcs11Module_.C_SignUpdate(sessionHandle_, part);
    }

    /**
     * This method finalizes a signing operation and returns the final result.
     * Use this method, if you fed in the data using signUpdate. If you used the
     * sign(byte[]) method, you need not (and shall not) call this method,
     * because sign(byte[]) finalizes the signing operation itself.
     *
     * @return The final result of the signing operation; i.e. the signature
     * value.
     * @exception TokenException If calculating the final signature value
     * failed.
     * @preconditions
     * @postconditions (result <> null)
     */
    public byte[] signFinal()
            throws TokenException {
        return pkcs11Module_.C_SignFinal(sessionHandle_);
    }

    /**
     * Initializes a new signing operation for signing with recovery. The
     * application must call this method before calling signRecover. Before
     * initializing a new operation, any currently pending operation must be
     * finalized using the appropriate *Final method (e.g. digestFinal()). There
     * are exceptions for dual-function operations. This method requires the
     * mechansim to use for signing and the key for this oepration. The key must
     * have set its sign-recover flag. For the mechanism the application may use
     * a constant defined in the Mechanism class. Notice that the key and the
     * mechanism must be compatible; i.e. you cannot use a DES key with the RSA
     * mechanism.
     *
     * @param mechanism The mechanism to use; e.g. Mechanism.RSA_9796.
     * @param key The signing key to use.
     * @exception TokenException If initializing this operation failed.
     * @preconditions (mechansim <> null) and (key <> null)
     * @postconditions
     */
    public void signRecoverInit(Mechanism mechanism, Key key)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        pkcs11Module_.C_SignRecoverInit(sessionHandle_, ckMechanism, key.getObjectHandle(), useUtf8Encoding_);
    }

    /**
     * Signs the given data with the key and mechansim given to the
     * signRecoverInit method. This method finalizes the current sign-recover
     * operation; there is no equivalent method to signUpdate for signing with
     * recovery.
     *
     * @param data The data to sign.
     * @return The signed data.
     * @exception TokenException If signing the data failed.
     * @preconditions (data <> null)
     * @postconditions (result <> null)
     */
    public byte[] signRecover(byte[] data)
            throws TokenException {
        return pkcs11Module_.C_SignRecover(sessionHandle_, data);
    }

    /**
     * Initializes a new verification operation. You can use it for verifying
     * signatures and MACs. The application must call this method before calling
     * any other verify* operation. Before initializing a new operation, any
     * currently pending operation must be finalized using the appropriate
     * *Final method (e.g. digestFinal()). There are exceptions for
     * dual-function operations. This method requires the mechansim to use for
     * verification and the key for this oepration. The key must have set its
     * verify flag. For the mechanism the application may use a constant defined
     * in the Mechanism class. Notice that the key and the mechanism must be
     * compatible; i.e. you cannot use a DES key with the RSA mechanism.
     *
     * @param mechanism The mechanism to use; e.g. Mechanism.RSA_PKCS.
     * @param key The verification key to use.
     * @exception TokenException If initializing this operation failed.
     * @preconditions (mechansim <> null) and (key <> null)
     * @postconditions
     */
    public void verifyInit(Mechanism mechanism, Key key)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        pkcs11Module_.C_VerifyInit(sessionHandle_, ckMechanism, key.getObjectHandle(), useUtf8Encoding_);
    }

    /**
     * Verifies the given signature against the given data with the key and
     * mechansim given to the verifyInit method. This method finalizes the
     * current verification operation; i.e. the application need (and should)
     * not call verifyFinal() after this call. For verifying with multiple pices
     * of data use verifyUpdate and verifyFinal. This method throws an
     * exception, if the verification of the signature fails.
     *
     * @param data The data that was signed.
     * @param signature The signature or MAC to verify.
     * @exception TokenException If verifying the signature fails. This is also
     * the case, if the signature is forged.
     * @preconditions (data <> null) and (signature <> null)
     * @postconditions
     */
    public void verify(byte[] data, byte[] signature)
            throws TokenException {
        pkcs11Module_.C_Verify(sessionHandle_, data, signature);
    }

    /**
     * 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. To
     * verify the signature or MAC call verifyFinal after feeding in all data
     * using this method.
     *
     * @param part The piece of data to verify against.
     * @exception TokenException If verifying (e.g. digesting) the data failed.
     * @preconditions (part <> null)
     * @postconditions
     */
    public void verifyUpdate(byte[] part)
            throws TokenException {
        pkcs11Module_.C_VerifyUpdate(sessionHandle_, part);
    }

    /**
     * This method finalizes a verification operation. Use this method, if you
     * fed in the data using verifyUpdate. If you used the verify(byte[])
     * method, you need not (and shall not) call this method, because
     * verify(byte[]) finalizes the verification operation itself. If this
     * method verified the signature successfully, it returns normally. If the
     * verification of the signature fails, e.g. if the signature was forged or
     * the data was modified, this method throws an exception.
     *
     * @param signature The signature value.
     * @exception TokenException If verifying the signature fails. This is also
     * the case, if the signature is forged.
     * @preconditions
     * @postconditions (result <> null)
     */
    public void verifyFinal(byte[] signature)
            throws TokenException {
        pkcs11Module_.C_VerifyFinal(sessionHandle_, signature);
    }

    /**
     * Initializes a new verification operation for verification with data
     * recovery. The application must call this method before calling
     * verifyRecover. Before initializing a new operation, any currently pending
     * operation must be finalized using the appropriate *Final method (e.g.
     * digestFinal()). This method requires the mechansim to use for
     * verification and the key for this oepration. The key must have set its
     * verify-recover flag. For the mechanism the application may use a constant
     * defined in the Mechanism class. Notice that the key and the mechanism
     * must be compatible; i.e. you cannot use a DES key with the RSA mechanism.
     *
     * @param mechanism The mechanism to use; e.g. Mechanism.RSA_9796.
     * @param key The verification key to use.
     * @exception TokenException If initializing this operation failed.
     * @preconditions (mechansim <> null) and (key <> null)
     * @postconditions
     */
    public void verifyRecoverInit(Mechanism mechanism, Key key)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        pkcs11Module_.C_VerifyRecoverInit(sessionHandle_, ckMechanism, key.getObjectHandle(), useUtf8Encoding_);
    }

    /**
     * Signs the given data with the key and mechansim given to the
     * signRecoverInit method. This method finalizes the current sign-recover
     * operation; there is no equivalent method to signUpdate for signing with
     * recovery.
     *
     * @param signature The data to sign.
     * @return The signed data.
     * @exception TokenException If signing the data failed.
     * @preconditions (data <> null)
     * @postconditions (result <> null)
     */
    public byte[] verifyRecover(byte[] signature)
            throws TokenException {
        return pkcs11Module_.C_VerifyRecover(sessionHandle_, signature);
    }

    /**
     * Dual-function. Continues a multipart dual digest and encryption
     * operation. This method call can also be combined with calls to
     * digestUpdate, digestKey and encryptUpdate. Call digestFinal and
     * encryptFinal to get the final results.
     *
     * @param part The piece of data to digest and encrypt.
     * @return The intermediate result of the encryption.
     * @exception TokenException If digesting or encrypting the data failed.
     * @preconditions (part <> null)
     * @postconditions
     */
    public byte[] digestEncryptedUpdate(byte[] part)
            throws TokenException {
        return pkcs11Module_.C_DigestEncryptUpdate(sessionHandle_, part);
    }

    /**
     * Dual-function. Continues a multipart dual decrypt and digest operation.
     * This method call can also be combined with calls to digestUpdate,
     * digestKey and decryptUpdate. It is the recovered plaintext that gets
     * digested in this method call, not the given encryptedPart. Call
     * digestFinal and decryptFinal to get the final results.
     *
     * @param part The piece of data to decrypt and digest.
     * @return The intermediate result of the decryption; the decrypted data.
     * @exception TokenException If decrypting or digesting the data failed.
     * @preconditions (part <> null)
     * @postconditions
     */
    public byte[] decryptDigestUpdate(byte[] part)
            throws TokenException {
        return pkcs11Module_.C_DecryptDigestUpdate(sessionHandle_, part);
    }

    /**
     * Dual-function. Continues a multipart dual sign and encrypt operation.
     * Calls to this method can also be combined with calls to signUpdate and
     * encryptUpdate. Call signFinal and encryptFinal to get the final results.
     *
     * @param part The piece of data to sign and encrypt.
     * @return The intermediate result of the encryption; the encrypted data.
     * @exception TokenException If signing or encrypting the data failed.
     * @preconditions (part <> null)
     * @postconditions
     */
    public byte[] signEncryptUpdate(byte[] part)
            throws TokenException {
        return pkcs11Module_.C_SignEncryptUpdate(sessionHandle_, part);
    }

    /**
     * Dual-function. Continues a multipart dual decrypt and verify operation.
     * This method call can also be combined with calls to decryptUpdate and
     * verifyUpdate. It is the recovered plaintext that gets verified in this
     * method call, not the given encryptedPart. Call decryptFinal and
     * verifyFinal to get the final results.
     *
     * @param encryptedPart The piece of data to decrypt and verify.
     * @return The intermediate result of the decryption; the decrypted data.
     * @exception TokenException If decrypting or verifying the data failed.
     * @preconditions (encryptedPart <> null)
     * @postconditions
     */
    public byte[] decryptVerifyUpdate(byte[] encryptedPart)
            throws TokenException {
        return pkcs11Module_.C_DecryptVerifyUpdate(sessionHandle_, encryptedPart);
    }

    /**
     * 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.
     *
     * @param mechanism The mechanism to generate a key for; e.g. Mechanism.DES
     * to generate a DES key.
     * @param template The template for the new key or domain parameters; e.g. a
     * DESSecretKey object which has set certain attributes.
     * @return The newly generated secret key or domain parameters.
     * @exception TokenException If generating a new secert key or domain
     * parameters failed.
     * @preconditions
     * @postconditions (result instanceof SecretKey) or (result instanceof
     * DomainParameters)
     */
    public Object generateKey(Mechanism mechanism, Object template)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;
        CK_ATTRIBUTE[] ckAttributes = Object.getSetAttributes(template);

        long objectHandle = pkcs11Module_.C_GenerateKey(sessionHandle_, ckMechanism,
                ckAttributes, useUtf8Encoding_);

        return Object.getInstance(this, objectHandle);
    }

    /**
     * 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.
     *
     * @param mechanism The mechanism to generate a key for; e.g. Mechanism.RSA
     * to generate a new RSA key-pair.
     * @param 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).
     * @param privateKeyTemplate The template for the new private key part; e.g.
     * a RSAPrivateKey object which has set certain attributes (e.g. sign and
     * decrypt).
     * @return The newly generated key-pair.
     * @exception TokenException If generating a new key-pair failed.
     * @preconditions
     * @postconditions
     */
    public KeyPair generateKeyPair(Mechanism mechanism,
            Object publicKeyTemplate,
            Object privateKeyTemplate)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;
        CK_ATTRIBUTE[] ckPublicKeyAttributes = Object.getSetAttributes(publicKeyTemplate);
        CK_ATTRIBUTE[] ckPrivateKeyAttributes = Object.getSetAttributes(privateKeyTemplate);

        long[] objectHandles = pkcs11Module_.C_GenerateKeyPair(sessionHandle_, ckMechanism,
                ckPublicKeyAttributes, ckPrivateKeyAttributes, useUtf8Encoding_);

        PublicKey publicKey = (PublicKey) Object.getInstance(this, objectHandles[0]);
        PrivateKey privateKey = (PrivateKey) Object.getInstance(this, objectHandles[1]);

        return new KeyPair(publicKey, privateKey);
    }

    /**
     * Wraps (encrypts) the given key with the wrapping key using the given
     * mechanism.
     *
     * @param mechanism The mechanism to use for wrapping the key.
     * @param wrappingKey The key to use for wrapping (encrypting).
     * @param key The key to wrap (encrypt).
     * @return The wrapped key as byte array.
     * @exception TokenException If wrapping the key failed.
     * @preconditions (mechanism <> null) and (wrappingKey <> null) and (key <>
     * null)
     * @postconditions (result <> null)
     */
    public byte[] wrapKey(Mechanism mechanism, Key wrappingKey, Key key)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;

        return pkcs11Module_.C_WrapKey(sessionHandle_, ckMechanism,
                wrappingKey.getObjectHandle(), key.getObjectHandle(), useUtf8Encoding_);
    }

    /**
     * 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.
     *
     * @param mechanism The mechanism to use for unwrapping the key.
     * @param unwrappingKey The key to use for unwrapping (decrypting).
     * @param wrappedKey The encrypted key to unwrap (decrypt).
     * @param keyTemplate The template for creating the new key object.
     * @return A key object representing the newly created key object.
     * @exception TokenException If unwrapping the key or creating a new key
     * object failed.
     * @preconditions (mechanism <> null) and (unwrappingKey <> null) and
     * (wrappedKey <> null)
     * @postconditions (result <> null)
     */
    public Key unwrapKey(Mechanism mechanism,
            Key unwrappingKey,
            byte[] wrappedKey,
            Object keyTemplate)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;
        CK_ATTRIBUTE[] ckAttributes = Object.getSetAttributes(keyTemplate);

        long objectHandle = pkcs11Module_.C_UnwrapKey(sessionHandle_, ckMechanism,
                unwrappingKey.getObjectHandle(), wrappedKey, ckAttributes, useUtf8Encoding_);

        Key ret = new Key();
        ret.setObjectHandle(objectHandle);
        return ret;
        //return (Key) Object.getInstance(this, objectHandle);
    }

    public Key unwrapKey20210224(Mechanism mechanism,
            Key unwrappingKey,
            byte[] wrappedKey,
            Object keyTemplate)
            throws TokenException {
        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;
        CK_ATTRIBUTE[] ckAttributes = Object.getSetAttributes(keyTemplate);

        long objectHandle = pkcs11Module_.C_UnwrapKey(sessionHandle_, ckMechanism,
                unwrappingKey.getObjectHandle(), wrappedKey, ckAttributes, useUtf8Encoding_);

        return (Key) Object.getInstance(this, objectHandle);
    }

    /**
     * Derives a new key from a specified base key unsing 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.
     *
     * @param mechanism The mechanism to use for deriving the new key from the
     * base key.
     * @param baseKey The key to use as base for derivation.
     * @param template The template for creating the new key object.
     * @return 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.
     * @exception TokenException If deriving the key or creating a new key
     * object failed.
     * @preconditions (mechanism <> null) and (baseKey <> null)
     * @postconditions
     */
    public Key deriveKey(Mechanism mechanism, Key baseKey, Key template)
            throws TokenException {
        Key derivedKey = null;

        CK_MECHANISM ckMechanism = new CK_MECHANISM();
        ckMechanism.mechanism = mechanism.getMechanismCode();
        Parameters parameters = mechanism.getParameters();
        ckMechanism.pParameter = (parameters != null) ? parameters.getPKCS11ParamsObject()
                : null;
        CK_ATTRIBUTE[] ckAttributes = Object.getSetAttributes(template);

        long objectHandle = pkcs11Module_.C_DeriveKey(sessionHandle_, ckMechanism,
                baseKey.getObjectHandle(), ckAttributes, useUtf8Encoding_);

        /*
		 * for certain mechanisms we must copy back the returned values the the
		 * parameters object of the given mechanism
         */
        if ((ckMechanism.mechanism == PKCS11Constants.CKM_SSL3_MASTER_KEY_DERIVE || ckMechanism.mechanism == PKCS11Constants.CKM_TLS_MASTER_KEY_DERIVE)
                && (parameters instanceof SSL3MasterKeyDeriveParameters)) {
            /*
			 * The SSL3MasterKeyDeriveParameters object need special handling due to
			 * their deeper nesting of their data structure, which needs to be copied
			 * back to get all the results.
             */
            // set the returned client version
            ((SSL3MasterKeyDeriveParameters) parameters).getVersion().setPKCS11ParamsObject(
                    ((CK_SSL3_MASTER_KEY_DERIVE_PARAMS) (ckMechanism.pParameter)).pVersion);
            derivedKey = (Key) Object.getInstance(this, objectHandle);
        } else if ((ckMechanism.mechanism == PKCS11Constants.CKM_SSL3_KEY_AND_MAC_DERIVE || ckMechanism.mechanism == PKCS11Constants.CKM_TLS_KEY_AND_MAC_DERIVE)
                && (parameters instanceof SSL3KeyMaterialParameters)) {
            /*
			 * The SSL3KeyMaterialParameters object need special handling due to their
			 * deeper nesting of their data structure, which needs to be copied back
			 * to get all the results.
             */
            // set the returned secret keys and IVs
            ((SSL3KeyMaterialParameters) parameters).getReturnedKeyMaterial()
                    .setPKCS11ParamsObject(
                            ((CK_SSL3_KEY_MAT_PARAMS) (ckMechanism.pParameter)).pReturnedKeyMaterial,
                            this);
            /*
			 * this mechanism returns its keys and values through the parameters
			 * object of the mechanism, but it does not return a key
             */
            derivedKey = null;
        } else {
            derivedKey = (Key) Object.getInstance(this, objectHandle);
        }

        return derivedKey;
    }

    /**
     * Mixes additional seeding material into the random number generator.
     *
     * @param seed The seed bytes to mix in.
     * @exception TokenException If mixing in the seed failed.
     * @preconditions (seed <> null)
     * @postconditions
     */
    public void seedRandom(byte[] seed)
            throws TokenException {
        pkcs11Module_.C_SeedRandom(sessionHandle_, seed);
    }

    /**
     * Generates a certain number of random bytes.
     *
     * @param numberOfBytesToGenerate The number of random bytes to generate.
     * @return An array of random bytes with length numberOfBytesToGenerate.
     * @exception TokenException If generating random bytes failed.
     * @preconditions (numberOfBytesToGenerate >= 0)
     * @postconditions (result <> null) and (result.length ==
     * numberOfBytesToGenerate)
     */
    public byte[] generateRandom(int numberOfBytesToGenerate)
            throws TokenException {
        byte[] randomBytesBuffer = new byte[numberOfBytesToGenerate];
        pkcs11Module_.C_GenerateRandom(sessionHandle_, randomBytesBuffer); // fill
        // the
        // buffer
        // with
        // random
        // bytes

        return randomBytesBuffer;
    }

    /**
     * Legacy function that will normally throw an PKCS11Exception with the
     * error-code PKCS11Constants.CKR_FUNCTION_NOT_PARALLEL.
     *
     * @exception TokenException Throws always an PKCS11Excption.
     * @preconditions
     * @postconditions
     */
    public void getFunctionStatus()
            throws TokenException {
        pkcs11Module_.C_GetFunctionStatus(sessionHandle_);
    }

    /**
     * Legacy function that will normally throw an PKCS11Exception with the
     * error-code PKCS11Constants.CKR_FUNCTION_NOT_PARALLEL.
     *
     * @exception TokenException Throws always an PKCS11Excption.
     * @preconditions
     * @postconditions
     */
    public void cancelFunction()
            throws TokenException {
        pkcs11Module_.C_CancelFunction(sessionHandle_);
    }

    /**
     * Returns the string representation of this object.
     *
     * @return the string representation of this object
     */
    public String toString() {
        StringBuffer buffer = new StringBuffer();

        buffer.append("Session Handle: ");
        buffer.append("0x");
        buffer.append(Functions.toHexString(sessionHandle_));
        buffer.append(Constants.NEWLINE);

        buffer.append("Token: ");
        buffer.append(token_.toString());

        return buffer.toString();
    }

}