Package org.xipki.pkcs11.wrapper

Class Session

  • public class Session
extends Object
    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 login 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(CKU_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(CKU_USER, userPINString.toCharArray());
     }
   }
    If the application does not need the session any longer, it should close the session. 
     
   session.closeSession();
    Author:
    Karl Scheibelhofer (SIC), Lijun Liao (xipki)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected Token token
      The token to perform the operations on.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Session​(Token token, long sessionHandle)
      Constructor taking the token and the session handle.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cancelFunction()
      Legacy function that will normally throw an PKCS11Exception with the error-code CKR_FUNCTION_NOT_PARALLEL.
      void closeSession()
      Closes this session.
      long copyObject​(long sourceObjectHandle, AttributeVector template)
      Copy an existing object.
      long createECPrivateKeyObject​(AttributeVector template, byte[] ecPoint)
      Create EC private key object in the PKCS#11 device.
      long createObject​(AttributeVector template)
      Create a new object on the token (or in the session).
      long createPrivateKeyObject​(AttributeVector template, PublicKey publicKey)  
      byte[] decrypt​(byte[] ciphertext)
      Decrypts the given data with the key and mechanism given to the decryptInit method.
      byte[] decryptDigestUpdate​(byte[] part)
      Dual-function.
      byte[] decryptFinal()
      This method finalizes a decryption operation and returns the final result.
      void decryptInit​(Mechanism mechanism, long keyHandle)
      Initializes a new decryption operation.
      byte[] decryptMessage​(CkParams params, byte[] associatedData, byte[] ciphertext)
      Decrypts the given message with the key and mechanism given to the MessageDecryptInit method.
      void decryptMessageBegin​(CkParams params, byte[] associatedData)
      Starts a multipart message-decryption operation.
      byte[] decryptMessageNext​(CkParams params, byte[] ciphertext, boolean isLastOperation)
      Decrypts one part of a multipart decryption operation.
      byte[] decryptSingle​(Mechanism mechanism, long keyHandle, byte[] ciphertext)  
      byte[] decryptUpdate​(byte[] ciphertextPart)
      This method can be used to decrypt multiple pieces of data; e.g.
      byte[] decryptVerifyUpdate​(byte[] encryptedPart)
      Dual-function.
      long deriveKey​(Mechanism mechanism, long baseKeyHandle, AttributeVector template)
      Derives a new key from a specified base key using the given mechanism.
      void destroyObject​(long objectHandle)
      Destroy a certain object on the token (or in the session).
      byte[] digest​(byte[] data)
      Digests the given data with the mechanism given to the digestInit method.
      byte[] digestEncryptedUpdate​(byte[] part)
      Dual-function.
      byte[] digestFinal()
      This method finalizes a digesting operation and returns the final result.
      int digestFinal​(byte[] out, int outOfs, int outLen)
      This method finalizes a digesting operation and returns the final result.
      void digestInit​(Mechanism mechanism)
      Initializes a new digesting operation.
      void digestKey​(long keyHandle)
      This method is similar to digestUpdate and can be combined with it during one digesting operation.
      byte[] digestSingle​(Mechanism mechanism, byte[] data)  
      void digestUpdate​(byte[] dataPart)
      This method can be used to digest multiple pieces of data; e.g.
      byte[] encrypt​(byte[] plaintext)
      Encrypts the given data with the key and mechanism given to the encryptInit method.
      byte[] encryptFinal()
      This method finalizes an encryption operation and returns the final result.
      void encryptInit​(Mechanism mechanism, long keyHandle)
      Initializes a new encryption operation.
      byte[] encryptMessage​(CkParams params, byte[] associatedData, byte[] plaintext)
      Encrypts the given message with the key and mechanism given to the MessageEncryptInit method.
      void encryptMessageBegin​(CkParams params, byte[] associatedData)
      Starts a multipart message-encryption operation.
      byte[] encryptMessageNext​(CkParams params, byte[] plaintext, boolean isLastOperation)
      Encrypts one part of a multipart encryption operation.
      byte[] encryptSingle​(Mechanism mechanism, long keyHandle, byte[] plaintext)  
      byte[] encryptUpdate​(byte[] plaintextPat)
      This method can be used to encrypt multiple pieces of data; e.g.
      long[] findAllObjectsSingle​(AttributeVector template)  
      long[] findObjects​(int maxObjectCount)
      Finds objects that match the template object passed to findObjectsInit.
      void findObjectsFinal()
      Finalizes a find operation.
      void findObjectsInit​(AttributeVector template)
      Initializes a find operations that provides means to find objects by passing a template object.
      long[] findObjectsSingle​(AttributeVector template, int maxObjectCount)  
      long generateKey​(Mechanism mechanism, AttributeVector template)
      Generate a new secret key or a set of domain parameters.
      PKCS11KeyPair generateKeyPair​(Mechanism mechanism, KeyPairTemplate template)
      Generate a new public key - private key key-pair and use the set attributes of the template objects for setting the attributes of the new public key and private key objects.
      byte[] generateRandom​(int numberOfBytesToGenerate)
      Generates a certain number of random bytes.
      AttributeVector getAttrValues​(long objectHandle, long... attributeTypes)  
      AttributeVector getAttrValues​(long objectHandle, List<Long> attributeTypes)  
      AttributeVector getDefaultAttrValues​(long objectHandle)
      Return the default attributes, but without attributes which contain the sensitive values.
      AttributeVector getDefaultAttrValues​(long objectHandle, boolean withSensitiveVAttributes)
      Return the default attributes
      void getFunctionStatus()
      Legacy function that will normally throw an PKCS11Exception with the error-code CKR_FUNCTION_NOT_PARALLEL.
      PKCS11Module getModule()
      Get the Module which this Session object operates with.
      long getObjectSize​(long objectHandle)
      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.
      String getStringAttrValue​(long objectHandle, long attributeType)  
      Token getToken()
      Get the token that created this Session object.
      void initPIN​(char[] pin)
      Initializes the user-PIN.
      boolean isRwSession()
      Determines if this session is an R/W session.
      boolean isSetUtf8Encoding()
      Returns whether UTF8 encoding is set.
      void login​(long userType, char[] pin)
      Logs in the user or the security officer to the session.
      void loginUser​(long userType, char[] pin, char[] username)
      Logs in the user or the security officer to the session.
      void logout()
      Logs out this session.
      void messageDecryptFinal()
      finishes multipart message decryption operation.
      void messageDecryptInit​(Mechanism mechanism, long keyHandle)
      Initializes a new message decryption operation.
      void messageEncryptFinal()
      Finishes a Message Encryption Operation which has previously been started with messageEncryptInit.
      void messageEncryptInit​(Mechanism mechanism, long keyHandle)
      Initializes a new message encryption operation.
      void messageSignFinal()
      finishes a message-based signing process.
      void messageSignInit​(Mechanism mechanism, long keyHandle)  
      void messageVerifyFinal()
      finishes a message-based verification process.
      void messageVerifyInit​(Mechanism mechanism, long keyHandle)
      Initiates a message verification operation, preparing a session for one or more verification operations (where the signature is an appendix to the data) that use the same verification mechanism and verification key.
      void seedRandom​(byte[] seed)
      Mixes additional seeding material into the random number generator.
      void sessionCancel()
      terminates active session based operations.
      void setAttributeValues​(long objectToUpdateHandle, AttributeVector template)
      Gets all present attributes of the given template object and writes them to the object to update on the token (or in the session).
      void setOperationState​(byte[] operationState, long encryptionKeyHandle, long authenticationKeyHandle)
      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.
      void setSessionHandle​(long sessionHandle)  
      byte[] sign​(byte[] data)
      Signs the given data with the key and mechanism 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, long keyHandle)
      Initializes a new signing operation.
      byte[] signMessage​(CkParams params, byte[] data)  
      void signMessageBegin​(CkParams params)
      SignMessageBegin begins a multiple-part message signature operation, where the signature is an appendix to the message.
      byte[] signMessageNext​(CkParams params, byte[] data, boolean isLastOperation)
      SignMessageNext continues a multiple-part message signature operation, processing another data part, or finishes a multiple-part message signature operation, returning the signature.
      byte[] signRecover​(byte[] data)
      Signs the given data with the key and mechanism given to the signRecoverInit method.
      void signRecoverInit​(Mechanism mechanism, long keyHandle)
      Initializes a new signing operation for signing with recovery.
      byte[] signRecoverSingle​(Mechanism mechanism, long keyHandle, byte[] data)  
      byte[] signSingle​(Mechanism mechanism, long keyHandle, byte[] data)  
      void signUpdate​(byte[] dataPart)
      This method can be used to sign multiple pieces of data; e.g.
      void signUpdate​(byte[] in, int inOfs, int inLen)
      This method can be used to sign multiple pieces of data; e.g.
      String toString()
      Returns the string representation of this object.
      long unwrapKey​(Mechanism mechanism, long unwrappingKeyHandle, byte[] wrappedKey, AttributeVector keyTemplate)
      Unwraps (decrypts) the given encrypted key with the unwrapping key using the given mechanism.
      void verify​(byte[] data, byte[] signature)
      Verifies the given signature against the given data with the key and mechanism given to the verifyInit method.
      void verifyFinal​(byte[] signature)
      This method finalizes a verification operation.
      void verifyInit​(Mechanism mechanism, long keyHandle)
      Initializes a new verification operation.
      void verifyMessage​(CkParams params, byte[] data, byte[] signature)
      Verifies a signature on a message in a single part operation.
      void verifyMessageBegin​(CkParams params)
      Begins a multipart message verification operation.
      void verifyMessageNext​(CkParams params, byte[] data, byte[] signature)
      continues a multiple-part message verification operation, processing another data part, or finishes a multiple-part message verification operation, checking the signature.
      byte[] verifyRecover​(byte[] data)
      Verifies the given data with the key and mechanism given to the verifyRecoverInit method.
      void verifyRecoverInit​(Mechanism mechanism, long keyHandle)
      Initializes a new verification operation for verification with data recovery.
      byte[] verifyRecoverSingle​(Mechanism mechanism, long keyHandle, byte[] data)  
      void verifySingle​(Mechanism mechanism, long keyHandle, byte[] data, byte[] signature)  
      void verifyUpdate​(byte[] dataPart)
      This method can be used to verify a signature with multiple pieces of data; e.g.
      byte[] wrapKey​(Mechanism mechanism, long wrappingKeyHandle, long keyHandle)
      Wraps (encrypts) the given key with the wrapping key using the given mechanism.

    • Field Detail

      • token

        protected final Token token
        The token to perform the operations on.

    • Constructor Detail

      • Session

        protected Session​(Token token,
                  long sessionHandle)
        Constructor taking the token and the session handle.
        Parameters:
        token - The token this session operates with.
        sessionHandle - The session handle to perform the operations with.

    • Method Detail

      • initPIN

        public void initPIN​(char[] pin)
             throws PKCS11Exception
        Initializes the user-PIN. Can only be called from a read-write security officer session. May be used to set a new user-PIN if the user-PIN is locked.
        Parameters:
        pin - The new user-PIN. This parameter may be null, if the token has a protected authentication path. Refer to the PKCS#11 standard for details.
        Throws:
        PKCS11Exception - If the session has not the right to set the PIN of if the operation fails for some other reason.

      • setPIN

        public void setPIN​(char[] oldPin,
                   char[] newPin)
            throws PKCS11Exception
        Set the user-PIN to a new value. Can only be called from a read-write sessions.
        Parameters:
        oldPin - The old (current) user-PIN.
        newPin - The new value for the user-PIN.
        Throws:
        PKCS11Exception - If setting the new PIN fails.

      • getSessionHandle

        public long getSessionHandle()
        Get the handle of this session.
        Returns:
        The handle of this session.

      • getSessionInfo

        public SessionInfo getSessionInfo()
                           throws PKCS11Exception
        Get information about this session.
        Returns:
        An object providing information about this session.
        Throws:
        PKCS11Exception - If getting the information failed.

      • sessionCancel

        public void sessionCancel()
                   throws PKCS11Exception
        terminates active session based operations.
        Throws:
        PKCS11Exception - If terminating operations failed

      • getModule

        public PKCS11Module getModule()
        Get the Module which this Session object operates with.
        Returns:
        The module of this session.

      • getToken

        public Token getToken()
        Get the token that created this Session object.
        Returns:
        The token of this session.

      • getOperationState

        public byte[] getOperationState()
                         throws PKCS11Exception
        Get the current operation state. This state can be used later to restore the operation to exactly this state.
        Returns:
        The current operation state as a byte array.
        Throws:
        PKCS11Exception - If saving the state fails or is not possible.

      • setOperationState

        public void setOperationState​(byte[] operationState,
                              long encryptionKeyHandle,
                              long authenticationKeyHandle)
                       throws PKCS11Exception
        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.
        Parameters:
        operationState - The previously saved state as returned by getOperationState().
        encryptionKeyHandle - An encryption or decryption key handle, if an encryption or decryption operation was saved which should be continued, but the keys could not be saved.
        authenticationKeyHandle - A signing, verification of MAC key handle, if a signing, verification or MAC operation needs to be restored that could not save the key.
        Throws:
        PKCS11Exception - If restoring the state fails.

      • setSessionHandle

        public void setSessionHandle​(long sessionHandle)

      • isSetUtf8Encoding

        public boolean isSetUtf8Encoding()
        Returns whether UTF8 encoding is set.
        Returns:
        true, if UTF8 is used as character encoding for character array attributes and PINs.

      • login

        public void login​(long userType,
                  char[] pin)
           throws PKCS11Exception
        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.
        Parameters:
        userType - CKU_SO for the security officer or CKU_USER to login the user.
        pin - The PIN. The security officer-PIN or the user-PIN depending on the userType parameter.
        Throws:
        PKCS11Exception - If login fails.

      • loginUser

        public void loginUser​(long userType,
                      char[] pin,
                      char[] username)
               throws PKCS11Exception
        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 log in the user to one session all other open sessions of this token get user rights.
        Parameters:
        userType - CKU_SO for the security officer or CKU_USER to log in the user.
        pin - The PIN. The security officer-PIN or the user-PIN depending on the userType parameter.
        username - The username of the user.
        Throws:
        PKCS11Exception - If login fails.

      • createObject

        public long createObject​(AttributeVector template)
                  throws PKCS11Exception
        Create a new object on the token (or in the session). The application must provide a template that holds enough information to create a certain object. For instance, if the application wants to create a new DES key object it creates a new instance of the AttributesTemplate class to serve as a template. The application must set all attributes of this new object which are required for the creation of such an object on the token. Then it passes this DESSecretKey object to this method to create the object on the token. Example: AttributesTemplate desKeyTemplate = AttributesTemplate.newSecretKey(CKK_DES3); // the key type is set by the DESSecretKey's constructor, so you need not do it desKeyTemplate.value(myDesKeyValueAs8BytesLongByteArray) .token(true) .private(true); .encrypt(true); .decrypt(true); ... long theCreatedDESKeyObjectHandle = userSession.createObject(desKeyTemplate); Refer to the PKCS#11 standard to find out what attributes must be set for certain types of objects to create them on the token.
        Parameters:
        template - The template object that holds all values that the new object on the token should contain.
        Returns:
        A new PKCS#11 Object that serves holds all the (readable) attributes of the object on the token. In contrast to the templateObject, this object might have certain attributes set to token-dependent default-values.
        Throws:
        PKCS11Exception - If the creation of the new object fails. If it fails, the no new object was created on the token.

      • createECPrivateKeyObject

        public long createECPrivateKeyObject​(AttributeVector template,
                                     byte[] ecPoint)
                              throws PKCS11Exception
        Create EC private key object in the PKCS#11 device.
        Parameters:
        template - Template of the EC private key.
        ecPoint - The encoded EC-Point. May be null.
        Returns:
        object handle of the new EC private key.
        Throws:
        PKCS11Exception - If creating the object fails for some reason.

      • copyObject

        public long copyObject​(long sourceObjectHandle,
                       AttributeVector template)
                throws PKCS11Exception
        Copy an existing object. The source object and a template object are given. Any value set in the template object will override the corresponding value from the source object, when the new object is created. See the PKCS#11 standard for details.
        Parameters:
        sourceObjectHandle - The source object of the copy operation.
        template - A template object whose attribute values are used for the new object; i.e. they have higher priority than the attribute values from the source object. May be null; in that case the new object is just a one-to-one copy of the sourceObject.
        Returns:
        The new object that is created by copying the source object and setting attributes to the values given by the template.
        Throws:
        PKCS11Exception - If copying the object fails for some reason.

      • setAttributeValues

        public void setAttributeValues​(long objectToUpdateHandle,
                               AttributeVector template)
                        throws PKCS11Exception
        Gets all present attributes of the given template object and writes them to the object to update on the token (or in the session). Both parameters may refer to the same Java object. This is possible, because this method only needs the object handle of the objectToUpdate, and gets the attributes to set from the template. This means, an application can get the object using createObject of findObject, then modify attributes of this Java object and then call this method passing this object as both parameters. This will update the object on the token to the values as modified in the Java object.
        Parameters:
        objectToUpdateHandle - The attributes of this object get updated.
        template - Gets all present attributes of this template object and sets this attributes at the objectToUpdate.
        Throws:
        PKCS11Exception - If updating the attributes fails. All or no attributes are updated.

      • destroyObject

        public void destroyObject​(long objectHandle)
                   throws PKCS11Exception
        Destroy a certain object on the token (or in the session). Give the object that you want to destroy. This method uses only the internal object handle of the given object to identify the object.
        Parameters:
        objectHandle - The object handle that should be destroyed.
        Throws:
        PKCS11Exception - If the object could not be destroyed.

      • getObjectSize

        public long getObjectSize​(long objectHandle)
                   throws PKCS11Exception
        Get the size of the specified object in bytes. This size specifies how much memory the object takes up on the token.
        Parameters:
        objectHandle - The object to get the size for.
        Returns:
        The object's size bytes.
        Throws:
        PKCS11Exception - If determining the size fails.

      • findObjectsInit

        public void findObjectsInit​(AttributeVector template)
                     throws PKCS11Exception
        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 and searches for all objects on the token that match with these attributes.
        Parameters:
        template - The object that serves as a template for searching. If this object is null, the find operation will find all objects that this session can see. Notice, that only a user session will see private objects.
        Throws:
        PKCS11Exception - If initializing the find operation fails.

      • findObjects

        public long[] findObjects​(int maxObjectCount)
                   throws PKCS11Exception
        Finds objects that match the template object passed to findObjectsInit. The application must call findObjectsInit before calling this method. With maxObjectCount the application can specify how many objects to return at once; i.e. the application can get all found objects by subsequent calls to this method like maxObjectCount(1) until it receives an empty array (this method never returns null!).
        Parameters:
        maxObjectCount - Specifies how many objects to return with this call.
        Returns:
        An array of found objects. The maximum size of this array is maxObjectCount, the minimum length is 0. Never returns null.
        Throws:
        PKCS11Exception - A plain PKCS11Exception if something during PKCS11 FindObject went wrong, a PKCS11Exception with a nested PKCS11Exception if the Exception is raised during object parsing.

      • findObjectsFinal

        public void findObjectsFinal()
                      throws PKCS11Exception
        Finalizes a find operation. The application must call this method to finalize a find operation before attempting to start any other operation.
        Throws:
        PKCS11Exception - If finalizing the current find operation was not possible.

      • encryptInit

        public void encryptInit​(Mechanism mechanism,
                        long keyHandle)
                 throws PKCS11Exception
        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 mechanism to use for encryption and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.DES_CBC.
        keyHandle - The decryption key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • encrypt

        public byte[] encrypt​(byte[] plaintext)
               throws PKCS11Exception
        Encrypts the given data with the key and mechanism 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 pieces of data use encryptUpdate and encryptFinal.
        Parameters:
        plaintext - the to-be-encrypted data
        Returns:
        the encrypted data. Never returns null.
        Throws:
        PKCS11Exception - If encrypting failed.

      • encryptUpdate

        public byte[] encryptUpdate​(byte[] plaintextPat)
                     throws PKCS11Exception
        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 mechanism 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.
        Parameters:
        plaintextPat - Piece of the to-be-encrypted data
        Returns:
        the encrypted data for this update. Never returns null.
        Throws:
        PKCS11Exception - If encrypting the data failed.

      • encryptFinal

        public byte[] encryptFinal()
                    throws PKCS11Exception
        This method finalizes an encryption 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.
        Returns:
        the last part of the encrypted data. Never returns null.
        Throws:
        PKCS11Exception - If calculating the final result failed.

      • messageEncryptInit

        public void messageEncryptInit​(Mechanism mechanism,
                               long keyHandle)
                        throws PKCS11Exception
        Initializes a new message encryption operation. The application must call this method before calling any other encryptMessage* 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 mechanism to use for encryption and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.DES_CBC.
        keyHandle - The decryption key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • encryptMessage

        public byte[] encryptMessage​(CkParams params,
                             byte[] associatedData,
                             byte[] plaintext)
                      throws PKCS11Exception
        Encrypts the given message with the key and mechanism given to the MessageEncryptInit method. Contrary to the encrypt-Function, the encryptMessage-Function can be called any number of times and does not finalize the encryption-operation
        Parameters:
        params - The parameter object
        associatedData - The associated Data for AEAD Mechanisms
        plaintext - The plaintext getting encrypted
        Returns:
        The ciphertext. Never returns null.
        Throws:
        PKCS11Exception - If encrypting failed.

      • encryptMessageBegin

        public void encryptMessageBegin​(CkParams params,
                                byte[] associatedData)
                         throws PKCS11Exception
        Starts a multipart message-encryption operation. Can only be called when an encryption operation has been initialized before.
        Parameters:
        params - The IV or nonce
        associatedData - The associated Data for AEAD Mechanisms
        Throws:
        PKCS11Exception - in case of error.

      • encryptMessageNext

        public byte[] encryptMessageNext​(CkParams params,
                                 byte[] plaintext,
                                 boolean isLastOperation)
                          throws PKCS11Exception
        Encrypts one part of a multipart encryption operation. The multipart operation must have been started with encryptMessageBegin before calling this function. If the isLastOperation is set, the multipart operation finishes and if present the TAG or MAC is returned in the parameters.
        Parameters:
        params - The parameter object
        plaintext - The associated Data for AEAD Mechanisms
        isLastOperation - If this is the last part of the multipart message encryption, this should be true
        Returns:
        The encrypted message part. Never returns null.
        Throws:
        PKCS11Exception - in case of error.

      • messageEncryptFinal

        public void messageEncryptFinal()
                         throws PKCS11Exception
        Finishes a Message Encryption Operation which has previously been started with messageEncryptInit.
        Throws:
        PKCS11Exception - in case of error.

      • decryptInit

        public void decryptInit​(Mechanism mechanism,
                        long keyHandle)
                 throws PKCS11Exception
        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 mechanism to use for decryption and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.DES_CBC.
        keyHandle - The decryption key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • decrypt

        public byte[] decrypt​(byte[] ciphertext)
               throws PKCS11Exception
        Decrypts the given data with the key and mechanism 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 pieces of data use decryptUpdate and decryptFinal.
        Parameters:
        ciphertext - the to-be-decrypted data
        Returns:
        the decrypted data. Never returns null.
        Throws:
        PKCS11Exception - If decrypting failed.

      • decryptUpdate

        public byte[] decryptUpdate​(byte[] ciphertextPart)
                     throws PKCS11Exception
        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 mechanism 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.
        Parameters:
        ciphertextPart - Piece of the to-be-decrypted data for this update
        Returns:
        the decrypted data for this update. Never returns null.
        Throws:
        PKCS11Exception - If decrypting the data failed.

      • decryptFinal

        public byte[] decryptFinal()
                    throws PKCS11Exception
        This method finalizes a decryption 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.
        Returns:
        the last part of decrypted data. Never returns null.
        Throws:
        PKCS11Exception - If calculating the final result failed.

      • messageDecryptInit

        public void messageDecryptInit​(Mechanism mechanism,
                               long keyHandle)
                        throws PKCS11Exception
        Initializes a new message decryption operation. The application must call this method before calling any other decryptMessage* 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 mechanism to use for encryption and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.DES_CBC.
        keyHandle - The decryption key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • decryptMessage

        public byte[] decryptMessage​(CkParams params,
                             byte[] associatedData,
                             byte[] ciphertext)
                      throws PKCS11Exception
        Decrypts the given message with the key and mechanism given to the MessageDecryptInit method. Contrary to the decrypt-Function, the decryptMessage-Function can be called any number of times and does not finalize the decryption-operation
        Parameters:
        params - The parameter object
        associatedData - The associated Data for AEAD Mechanisms
        ciphertext - The to-be-decrypted data
        Returns:
        The ciphertext. Never returns null.
        Throws:
        PKCS11Exception - If encrypting failed.

      • decryptMessageBegin

        public void decryptMessageBegin​(CkParams params,
                                byte[] associatedData)
                         throws PKCS11Exception
        Starts a multipart message-decryption operation.
        Parameters:
        params - The parameter object
        associatedData - The associated Data for AEAD Mechanisms
        Throws:
        PKCS11Exception - in case of error.

      • decryptMessageNext

        public byte[] decryptMessageNext​(CkParams params,
                                 byte[] ciphertext,
                                 boolean isLastOperation)
                          throws PKCS11Exception
        Decrypts one part of a multipart decryption operation. The multipart operation must have been started with decryptMessageBegin before calling this function. If the isLastOperation is set, the multipart operation finishes.
        Parameters:
        params - The parameter object
        ciphertext - The ciphertext getting decrypted
        isLastOperation - If this is the last part of the multipart message encryption, this should be true
        Returns:
        the decrypted message part. Never returns null.
        Throws:
        PKCS11Exception - in case of error.

      • messageDecryptFinal

        public void messageDecryptFinal()
                         throws PKCS11Exception
        finishes multipart message decryption operation.
        Throws:
        PKCS11Exception - in case of error.

      • digestInit

        public void digestInit​(Mechanism mechanism)
                throws PKCS11Exception
        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 mechanism to use for digesting for this operation. For the mechanism the application may use a constant defined in the Mechanism class.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.SHA_1.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • digest

        public byte[] digest​(byte[] data)
              throws PKCS11Exception
        Digests the given data with the mechanism 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 pieces of data use digestUpdate and digestFinal.
        Parameters:
        data - the to-be-digested data
        Returns:
        the message digest. Never returns null.
        Throws:
        PKCS11Exception - If digesting the data failed.

      • digestUpdate

        public void digestUpdate​(byte[] dataPart)
                  throws PKCS11Exception
        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 mechanism 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.
        Parameters:
        dataPart - Piece of the to-be-digested data
        Throws:
        PKCS11Exception - If digesting the data failed.

      • digestKey

        public void digestKey​(long keyHandle)
               throws PKCS11Exception
        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.
        Parameters:
        keyHandle - The key to digest the value of.
        Throws:
        PKCS11Exception - If digesting the key failed.

      • digestFinal

        public byte[] digestFinal()
                   throws PKCS11Exception
        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.
        Returns:
        the message digest. Never returns null.
        Throws:
        PKCS11Exception - If calculating the final message digest failed.

      • digestFinal

        public int digestFinal​(byte[] out,
                       int outOfs,
                       int outLen)
                throws PKCS11Exception
        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.
        Parameters:
        out - buffer for the message digest
        outOfs - buffer offset for the message digest
        outLen - buffer size for the message digest
        Returns:
        the length of message digest
        Throws:
        PKCS11Exception - If calculating the final message digest failed.

      • signInit

        public void signInit​(Mechanism mechanism,
                     long keyHandle)
              throws PKCS11Exception
        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 mechanism to use for signing and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.RSA_PKCS.
        keyHandle - The signing key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • sign

        public byte[] sign​(byte[] data)
            throws PKCS11Exception
        Signs the given data with the key and mechanism 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 pieces of data use signUpdate and signFinal.
        Parameters:
        data - The data to sign.
        Returns:
        The signed data. Never returns null.
        Throws:
        PKCS11Exception - If signing the data failed.

      • signUpdate

        public void signUpdate​(byte[] dataPart)
                throws PKCS11Exception
        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 mechanism 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.
        Parameters:
        dataPart - Piece of the to-be-signed data
        Throws:
        PKCS11Exception - If signing the data failed.

      • signUpdate

        public void signUpdate​(byte[] in,
                       int inOfs,
                       int inLen)
                throws PKCS11Exception
        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 mechanism 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.
        Parameters:
        in - buffer containing the to-be-signed data
        inOfs - buffer offset of the to-be-signed data
        inLen - length of the to-be-signed data
        Throws:
        PKCS11Exception - If signing the data failed.

      • signFinal

        public byte[] signFinal()
                 throws PKCS11Exception
        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.
        Returns:
        The final result of the signing operation; i.e. the signature value. Never returns null.
        Throws:
        PKCS11Exception - If calculating the final signature value failed.

      • signRecoverInit

        public void signRecoverInit​(Mechanism mechanism,
                            long keyHandle)
                     throws PKCS11Exception
        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 mechanism to use for signing and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.RSA_9796.
        keyHandle - The signing key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • signRecover

        public byte[] signRecover​(byte[] data)
                   throws PKCS11Exception
        Signs the given data with the key and mechanism given to the signRecoverInit method. This method finalizes the current sign-recover operation; there is no equivalent method to signUpdate for signing with recovery.
        Parameters:
        data - the to-be-signed data
        Returns:
        the signed data. Never returns null.
        Throws:
        PKCS11Exception - If signing the data failed.

      • messageSignInit

        public void messageSignInit​(Mechanism mechanism,
                            long keyHandle)
                     throws PKCS11Exception
        Parameters:
        mechanism - the mechanism parameter to use
        keyHandle - the key to sign the data with
        Throws:
        PKCS11Exception - in case of error.

      • signMessage

        public byte[] signMessage​(CkParams params,
                          byte[] data)
                   throws PKCS11Exception
        Parameters:
        params - the mechanism parameter to use
        data - the data to sign
        Returns:
        the signature. Never returns null.
        Throws:
        PKCS11Exception - if signing failed.

      • signMessageBegin

        public void signMessageBegin​(CkParams params)
                      throws PKCS11Exception
        SignMessageBegin begins a multiple-part message signature operation, where the signature is an appendix to the message.
        Parameters:
        params - the mechanism parameter to use
        Throws:
        PKCS11Exception - in case of error.

      • signMessageNext

        public byte[] signMessageNext​(CkParams params,
                              byte[] data,
                              boolean isLastOperation)
                       throws PKCS11Exception
        SignMessageNext continues a multiple-part message signature operation, processing another data part, or finishes a multiple-part message signature operation, returning the signature.
        Parameters:
        params - the mechanism parameter to use
        data - the message to sign
        isLastOperation - specifies if this is the last part of this message.
        Returns:
        the signature. Never returns null.
        Throws:
        PKCS11Exception - in case of error.

      • messageSignFinal

        public void messageSignFinal()
                      throws PKCS11Exception
        finishes a message-based signing process. The message-based signing process MUST have been initialized with messageSignInit.
        Throws:
        PKCS11Exception - in case of error.

      • verifyInit

        public void verifyInit​(Mechanism mechanism,
                       long keyHandle)
                throws PKCS11Exception
        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 mechanism to use for verification and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.RSA_PKCS.
        keyHandle - The verification key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • verify

        public void verify​(byte[] data,
                   byte[] signature)
            throws PKCS11Exception
        Verifies the given signature against the given data with the key and mechanism 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 pieces of data use verifyUpdate and verifyFinal. This method throws an exception, if the verification of the signature fails.
        Parameters:
        data - The data that was signed.
        signature - The signature or MAC to verify.
        Throws:
        PKCS11Exception - If verifying the signature fails. This is also the case, if the signature is forged.

      • verifyUpdate

        public void verifyUpdate​(byte[] dataPart)
                  throws PKCS11Exception
        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.
        Parameters:
        dataPart - Piece of the to-be-verified data.
        Throws:
        PKCS11Exception - If verifying (e.g. digesting) the data failed.

      • verifyFinal

        public void verifyFinal​(byte[] signature)
                 throws PKCS11Exception
        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.
        Parameters:
        signature - The signature value.
        Throws:
        PKCS11Exception - If verifying the signature fails. This is also the case, if the signature is forged.

      • verifyRecoverInit

        public void verifyRecoverInit​(Mechanism mechanism,
                              long keyHandle)
                       throws PKCS11Exception
        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 mechanism to use for verification and the key for this operation. 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.
        Parameters:
        mechanism - The mechanism to use; e.g. Mechanism.RSA_9796.
        keyHandle - The verification key to use.
        Throws:
        PKCS11Exception - If initializing this operation failed.

      • verifyRecover

        public byte[] verifyRecover​(byte[] data)
                     throws PKCS11Exception
        Verifies the given data with the key and mechanism given to the verifyRecoverInit method. This method finalizes the current verify-recover operation; there is no equivalent method to verifyUpdate for signing with recovery.
        Parameters:
        data - the to-be-verified data
        Returns:
        the verified data. Never returns null.
        Throws:
        PKCS11Exception - If signing the data failed.

      • messageVerifyInit

        public void messageVerifyInit​(Mechanism mechanism,
                              long keyHandle)
                       throws PKCS11Exception
        Initiates a message verification operation, preparing a session for one or more verification operations (where the signature is an appendix to the data) that use the same verification mechanism and verification key.
        Parameters:
        mechanism - the mechanism to use
        keyHandle - the verification key to use
        Throws:
        PKCS11Exception - in case of error.

      • verifyMessage

        public void verifyMessage​(CkParams params,
                          byte[] data,
                          byte[] signature)
                   throws PKCS11Exception
        Verifies a signature on a message in a single part operation. messageVerifyInit must previously been called on the session.
        Parameters:
        params - the mechanism parameter to use
        data - the message to verify with the signature
        signature - the signature of the message
        Throws:
        PKCS11Exception - if the message cant be verified

      • verifyMessageBegin

        public void verifyMessageBegin​(CkParams params)
                        throws PKCS11Exception
        Begins a multipart message verification operation. MessageVerifyInit must previously been called on the session
        Parameters:
        params - the mechanism parameter to use
        Throws:
        PKCS11Exception - in case of error.

      • verifyMessageNext

        public void verifyMessageNext​(CkParams params,
                              byte[] data,
                              byte[] signature)
                       throws PKCS11Exception
        continues a multiple-part message verification operation, processing another data part, or finishes a multiple-part message verification operation, checking the signature. The signature argument is set to NULL if there is more data part to follow, or set to a non-NULL value (pointing to the signature to verify) if this is the last data part.
        Parameters:
        params - the mechanism parameter to use
        data - the data to be verified
        signature - NUll if there is data follow, the signature if it is the last part of the signing operation
        Throws:
        PKCS11Exception - if The Signature is invalid

      • messageVerifyFinal

        public void messageVerifyFinal()
                        throws PKCS11Exception
        finishes a message-based verification process. The message-based verification process must have been initialized with messageVerifyInit.
        Throws:
        PKCS11Exception - in case of error.

      • digestEncryptedUpdate

        public byte[] digestEncryptedUpdate​(byte[] part)
                             throws PKCS11Exception
        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.
        Parameters:
        part - The piece of data to digest and encrypt.
        Returns:
        The intermediate result of the encryption. Never returns null.
        Throws:
        PKCS11Exception - If digesting or encrypting the data failed.

      • decryptDigestUpdate

        public byte[] decryptDigestUpdate​(byte[] part)
                           throws PKCS11Exception
        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.
        Parameters:
        part - The piece of data to decrypt and digest.
        Returns:
        The intermediate result of the decryption; the decrypted data. Never returns null.
        Throws:
        PKCS11Exception - If decrypting or digesting the data failed.

      • signEncryptUpdate

        public byte[] signEncryptUpdate​(byte[] part)
                         throws PKCS11Exception
        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.
        Parameters:
        part - The piece of data to sign and encrypt.
        Returns:
        The intermediate result of the encryption; the encrypted data. Never returns null.
        Throws:
        PKCS11Exception - If signing or encrypting the data failed.

      • decryptVerifyUpdate

        public byte[] decryptVerifyUpdate​(byte[] encryptedPart)
                           throws PKCS11Exception
        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.
        Parameters:
        encryptedPart - The piece of data to decrypt and verify.
        Returns:
        The intermediate result of the decryption; the decrypted data. Never returns null.
        Throws:
        PKCS11Exception - If decrypting or verifying the data failed.

      • generateKey

        public long generateKey​(Mechanism mechanism,
                        AttributeVector template)
                 throws PKCS11Exception
        Generate a new secret key or a set of domain parameters. It uses the set attributes of the template for setting the attributes of the new key object. As mechanism the application can use a constant of the Mechanism class.
        Parameters:
        mechanism - The mechanism to generate a key for; e.g. Mechanism.DES to generate a DES key.
        template - The template for the new key or domain parameters; e.g. a DESSecretKey object which has set certain attributes.
        Returns:
        The newly generated secret key or domain parameters.
        Throws:
        PKCS11Exception - If generating a new secret key or domain parameters failed.

      • generateKeyPair

        public PKCS11KeyPair generateKeyPair​(Mechanism mechanism,
                                     KeyPairTemplate template)
                              throws PKCS11Exception
        Generate a new public key - private key key-pair and use the set attributes of the template objects for setting the attributes of the new public key and private key objects. As mechanism the application can use a constant of the Mechanism class.
        Parameters:
        mechanism - The mechanism to generate a key for; e.g. Mechanism.RSA to generate a new RSA key-pair.
        template - The template for the new keypair.
        Returns:
        The newly generated key-pair.
        Throws:
        PKCS11Exception - If generating a new key-pair failed.

      • wrapKey

        public byte[] wrapKey​(Mechanism mechanism,
                      long wrappingKeyHandle,
                      long keyHandle)
               throws PKCS11Exception
        Wraps (encrypts) the given key with the wrapping key using the given mechanism.
        Parameters:
        mechanism - The mechanism to use for wrapping the key.
        wrappingKeyHandle - The key to use for wrapping (encrypting).
        keyHandle - The key to wrap (encrypt).
        Returns:
        The wrapped key as byte array. Never returns null.
        Throws:
        PKCS11Exception - If wrapping the key failed.

      • unwrapKey

        public long unwrapKey​(Mechanism mechanism,
                      long unwrappingKeyHandle,
                      byte[] wrappedKey,
                      AttributeVector keyTemplate)
               throws PKCS11Exception
        Unwraps (decrypts) the given encrypted key with the unwrapping key using the given mechanism. The application can also pass a template key to set certain attributes of the unwrapped key. This creates a key object after unwrapping the key and returns an object representing this key.
        Parameters:
        mechanism - The mechanism to use for unwrapping the key.
        unwrappingKeyHandle - The key to use for unwrapping (decrypting).
        wrappedKey - The encrypted key to unwrap (decrypt).
        keyTemplate - The template for creating the new key object.
        Returns:
        A key object representing the newly created key object.
        Throws:
        PKCS11Exception - If unwrapping the key or creating a new key object failed.

      • deriveKey

        public long deriveKey​(Mechanism mechanism,
                      long baseKeyHandle,
                      AttributeVector template)
               throws PKCS11Exception
        Derives a new key from a specified base key using the given mechanism. After deriving a new key from the base key, a new key object is created and a representation of it is returned. The application can provide a template key to set certain attributes of the new key object.
        Parameters:
        mechanism - The mechanism to use for deriving the new key from the base key.
        baseKeyHandle - The key to use as base for derivation.
        template - The template for creating the new key object.
        Returns:
        A key object representing the newly derived (created) key object or null, if the used mechanism uses other means to return its values; e.g. the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism.
        Throws:
        PKCS11Exception - If deriving the key or creating a new key object failed.

      • seedRandom

        public void seedRandom​(byte[] seed)
                throws PKCS11Exception
        Mixes additional seeding material into the random number generator.
        Parameters:
        seed - The seed bytes to mix in.
        Throws:
        PKCS11Exception - If mixing in the seed failed.

      • generateRandom

        public byte[] generateRandom​(int numberOfBytesToGenerate)
                      throws PKCS11Exception
        Generates a certain number of random bytes.
        Parameters:
        numberOfBytesToGenerate - The number of random bytes to generate.
        Returns:
        An array of random bytes with length numberOfBytesToGenerate.
        Throws:
        PKCS11Exception - If generating random bytes failed.

      • getFunctionStatus

        public void getFunctionStatus()
                       throws PKCS11Exception
        Legacy function that will normally throw an PKCS11Exception with the error-code CKR_FUNCTION_NOT_PARALLEL.
        Throws:
        PKCS11Exception - Throws always a PKCS11Exception.

      • cancelFunction

        public void cancelFunction()
                    throws PKCS11Exception
        Legacy function that will normally throw an PKCS11Exception with the error-code CKR_FUNCTION_NOT_PARALLEL.
        Throws:
        PKCS11Exception - Throws always a PKCS11Exception.

      • isRwSession

        public boolean isRwSession()
                    throws PKCS11Exception
        Determines if this session is an R/W session.
        Returns:
        true if this is an R/W session, false otherwise.
        Throws:
        PKCS11Exception - in case of error.

      • toString

        public String toString()
        Returns the string representation of this object.
        Overrides:
        toString in class Object
        Returns:
        the string representation of this object

      • getDefaultAttrValues

        public AttributeVector getDefaultAttrValues​(long objectHandle)
                                     throws PKCS11Exception
        Return the default attributes, but without attributes which contain the sensitive values.
        Parameters:
        objectHandle - the object handle.
        Returns:
        the attributes.
        Throws:
        PKCS11Exception - If getting attributes failed.

      • getDefaultAttrValues

        public AttributeVector getDefaultAttrValues​(long objectHandle,
                                            boolean withSensitiveVAttributes)
                                     throws PKCS11Exception
        Return the default attributes
        Parameters:
        objectHandle - the object handle.
        withSensitiveVAttributes - whether to get the attributes which contain sensitive values.
        Returns:
        the attributes.
        Throws:
        PKCS11Exception - If getting attributes failed.