Package javacard.security

Class Signature.OneShot

  • Enclosing class:
    Signature
    public static final class Signature.OneShot
extends Signature
    The OneShot class is a specialization of the Signature class intended to support efficient one-shot signing and verification operations that may avoid persistent memory writes entirely. The OneShot class uses a delegation model where calls are delegated to an instance of a Signature-implementing class configured for one-shot use.

    Note:

    • Instances of OneShot are JCRE owned temporary Entry Point Object instances and references to these temporary objects cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
    • The platform must support at least one instance of OneShot. Support for several OneShot instances is platform dependent. To guarantee application code portability, acquiring/opening and then releasing/closing OneShot instances should be performed within tight try-catch-finally blocks (as illustrated in the code sample below) in order to avoid unnecessarily keeping hold of instances and to prevent interleaving invocations - hence enforcing the One-Shot usage pattern. Additionally, any local variable holding a reference to a OneShot instance should be set to null once the instance is closed in order to prevent further use attempts.
    • Upon return from any Applet entry point method, back to the JCRE, and on tear or card reset events any OneShot instances in use are released back to the JCRE.
    • The internal state associated with an instance of OneShot must be bound to the initial calling context (owner context) as to preclude use/calls on that instance from other contexts.
    • Unless otherwise specified, after an instance of OneShot is released back to the JCRE, calls to any of the instance methods of the OneShot class results in an CryptoException being thrown with reason code CryptoException.ILLEGAL_USE.
    • OneShot cannot be used to get instances of type SignatureMessageRecovery.

    The following code shows a typical usage pattern for the OneShot class. 

     ...
 Signature.OneShot sig = null;
 try {
     sig = Signature.OneShot.open(MessageDigest.ALG_SHA, Signature.SIG_CIPHER_RSA, Cipher.PAD_PKCS1);
     sig.init(someRSAKey, Signature.MODE_SIGN);
     sig.sign(someInData, (short) 0, (short) someInData.length, sigData, (short) 0);
 } catch (CryptoException ce) {
     // Handle exception
 } finally {
     if (sig != null) {
        sig.close();
        sig = null;
     }
 }
 ...

    Since:
    3.0.5

    • Method Detail

      • open

        public static final Signature.OneShot open​(byte messageDigestAlgorithm,
                                           byte cipherAlgorithm,
                                           byte paddingAlgorithm)
                                    throws CryptoException
        Opens/acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected message digest algorithm, cipher algorithm and padding algorithm.

        Note:

        • Note that the cipher algorithms listed in the Signature class include some choices not available directly as a Cipher - e.g DSA.
        • When there is no discrete message digest algorithm, use the MessageDigest.ALG_NULL choice for the message digest algorithm.
        • When the padding algorithm is built into the cipher algorithm use the PAD_NULL choice for the padding algorithm.

        Parameters:
        messageDigestAlgorithm - the desired message digest algorithm. Valid codes listed in ALG_* constants in the MessageDigest class e.g. ALG_NULL.
        cipherAlgorithm - the desired cipher algorithm. Valid codes listed in SIG_CIPHER_* constants in the Signature class e.g. Signature.SIG_CIPHER_DES_MAC4.
        paddingAlgorithm - the desired padding algorithm. Valid codes listed in PAD_* constants in the Cipher class e.g. PAD_NULL.
        Returns:
        the OneShot object instance of the requested algorithm.
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if the requested message digest algorithm or cipher algorithm or padding algorithm or their combination is not supported.
        SystemException - with the following reason codes:
        • SystemException.NO_RESOURCE if sufficient resources are not available.

      • close

        public void close()
        Closes and releases this JCRE owned temporary instance of the OneShot object for reuse. If this method is called again this method does nothing.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • init

        public void init​(Key theKey,
                 byte theMode)
          throws CryptoException
        Initializes the Signature object with the appropriate Key. This method should be used for algorithms which do not need initialization parameters or use default parameter values.

        init() must be used to update the Signature object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update(), sign(), and verify() methods is unspecified.

        The Key is checked for consistency with the Signature algorithm. For example, the key type must be matched. For elliptic curve algorithms, the key must represent a valid point on the curve's domain parameters. Additional key component/domain parameter strength checks are implementation specific.

        Note:

        • AES, DES, triple DES, and Korean SEED algorithms in CBC mode will use 0 for initial vector(IV) if this method is used.
        • RSA algorithms using the padding scheme PKCS1_PSS will use a default salt length equal to the length of the message digest.
        • For optimal performance, when the theKey parameter is a transient key, the implementation should, whenever possible, use transient space for internal storage.

        Specified by:
        init in class Signature
        Parameters:
        theKey - the key object to use for signing or verifying
        theMode - one of MODE_SIGN or MODE_VERIFY
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if the Key is inconsistent with theMode or with the Signature implementation.
        • CryptoException.UNINITIALIZED_KEY if theKey instance is uninitialized.
        • CryptoException.ILLEGAL_USE if theMode is not allowed by this Signature algorithm.

      • init

        public void init​(Key theKey,
                 byte theMode,
                 byte[] bArray,
                 short bOff,
                 short bLen)
          throws CryptoException
        Initializes the Signature object with the appropriate Key and algorithm specific parameters.

        init() must be used to update the Signature object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update(), sign(), and verify() methods is unspecified.

        The Key is checked for consistency with the Signature algorithm. For example, the key type must be matched. For elliptic curve algorithms, the key must represent a valid point on the curve's domain parameters. Additional key component/domain parameter strength checks are implementation specific.

        Note:

        • DES and triple DES algorithms in CBC mode expect an 8-byte parameter value for the initial vector(IV) in bArray.
        • AES algorithms, except for ALG_AES_CMAC_128, in CBC mode expect a 16-byte parameter value for the initial vector(IV) in bArray.
        • Korean SEED algorithms in CBC mode expect a 16-byte parameter value for the initial vector(IV) in bArray.
        • ECDSA, DSA and HMAC algorithms throw CryptoException.ILLEGAL_VALUE. For RSA algorithms using the padding scheme PKCS1_PSS expect a two-byte parameter value (b1 b2) for the salt length in bArray. This two-byte parameter represents a short value where b1 is the first byte (high order byte) and b2 is the second byte (low order byte). For all other RSA algorithms CryptoException.ILLEGAL_VALUE is thrown.
        • For optimal performance, when the theKey parameter is a transient key, the implementation should, whenever possible, use transient space for internal storage.

        Specified by:
        init in class Signature
        Parameters:
        theKey - the key object to use for signing
        theMode - one of MODE_SIGN or MODE_VERIFY
        bArray - byte array containing algorithm specific initialization information
        bOff - offset within bArray where the algorithm specific data begins
        bLen - byte length of algorithm specific parameter data
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if a byte array parameter option is not supported by the algorithm or if the bLen is an incorrect byte length for the algorithm specific data or if the Key is inconsistent with theMode or with the Signature implementation.
        • CryptoException.UNINITIALIZED_KEY if theKey instance is uninitialized.
        • CryptoException.ILLEGAL_USE if theMode is not allowed by this Signature algorithm.

      • setInitialDigest

        public void setInitialDigest​(byte[] initialDigestBuf,
                             short initialDigestOffset,
                             short initialDigestLength,
                             byte[] digestedMsgLenBuf,
                             short digestedMsgLenOffset,
                             short digestedMsgLenLength)
                      throws CryptoException
        This method initializes the starting hash value in place of the default value used by the Signature class. The starting hash value represents the previously computed hash (using the same algorithm) of the first part of the message. The remaining bytes of the message must be presented to this Signature object via the update and sign or verify methods to generate or verify the signature.

        Note:

        • The maximum allowed value of the byte length of the first part of the message is algorithm specific
        • This method throws an exception if the underlying signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives. These algorithms throw exception - DES, triple DES, AES, HMAC and KOREAN SEED.

        Specified by:
        setInitialDigest in class Signature
        Parameters:
        initialDigestBuf - input buffer containing the starting hash value representing the previously computed hash (using the same algorithm) of first part of the message
        initialDigestOffset - offset into initialDigestBuf array where the starting digest value data begins
        initialDigestLength - the length of data in initialDigestBuf array.
        digestedMsgLenBuf - the byte array containing the number of bytes in the first part of the message that has previously been hashed to obtain the specified starting digest value
        digestedMsgLenOffset - the offset within digestedMsgLenBuf where the digested length begins(the bytes starting at this offset for digestedMsgLenLength bytes are concatenated to form the actual digested message length value)
        digestedMsgLenLength - byte length of the digested length
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_VALUE if the parameter initialDigestLength is not equal to the intermediate hash value size of the algorithm or if the number of bytes in the first part of the message that has previously been hashed is 0 or not a multiple of the algorithm's block size or greater than the maximum length supported by the algorithm (see ALG_* algorithm descriptions MessageDigest.ALG_SHA).
        • CryptoException.ILLEGAL_USE if the Signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives or if this Signature algorithm includes message recovery functionality.

      • getAlgorithm

        public byte getAlgorithm()
        Gets the Signature algorithm. Pre-defined codes listed in ALG_* constants above, for example, Signature.ALG_DES_MAC4_NOPAD.
        Specified by:
        getAlgorithm in class Signature
        Returns:
        the algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • getMessageDigestAlgorithm

        public byte getMessageDigestAlgorithm()
        Gets the message digest algorithm. Pre-defined codes listed in ALG_* constants in the MessageDigest class e.g. ALG_NULL.
        Specified by:
        getMessageDigestAlgorithm in class Signature
        Returns:
        the message digest algorithm code defined in the MessageDigest class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • getCipherAlgorithm

        public byte getCipherAlgorithm()
        Gets the cipher algorithm. Pre-defined codes listed in SIG_CIPHER_* constants in this class e.g. SIG_CIPHER_DES_MAC4.
        Specified by:
        getCipherAlgorithm in class Signature
        Returns:
        the cipher algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • getPaddingAlgorithm

        public byte getPaddingAlgorithm()
        Gets the padding algorithm. Pre-defined codes listed in PAD_* constants in the Cipher class e.g. PAD_NULL.
        Specified by:
        getPaddingAlgorithm in class Signature
        Returns:
        the padding algorithm code defined in the Cipher class; if the algorithm is not one of the pre-defined algorithms, 0 is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • getLength

        public short getLength()
                throws CryptoException
        Returns the byte length of the signature data.
        Specified by:
        getLength in class Signature
        Returns:
        the byte length of the signature data
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.INVALID_INIT if this Signature object is not initialized.
        • CryptoException.UNINITIALIZED_KEY if key not initialized.

      • sign

        public short sign​(byte[] inBuff,
                  short inOffset,
                  short inLength,
                  byte[] sigBuff,
                  short sigOffset)
           throws CryptoException
        Generates the signature of all/last input data.

        A call to this method also resets this Signature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to sign another message. In addition, note that the initial vector(IV) used in AES, DES and Korean SEED algorithms in CBC mode will be reset to 0.

        Note:

        • AES, DES, triple DES, and Korean SEED algorithms in CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init(Key, byte, byte[], short, short) method.

        The input and output buffer data may overlap.

        In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Specified by:
        sign in class Signature
        Parameters:
        inBuff - the input buffer of data to be signed
        inOffset - the offset into the input buffer at which to begin signature generation
        inLength - the byte length to sign
        sigBuff - the output buffer to store signature data
        sigOffset - the offset into sigBuff at which to begin signature data
        Returns:
        number of bytes of signature output in sigBuff
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.UNINITIALIZED_KEY if key not initialized.
        • CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature verify mode.
        • CryptoException.ILLEGAL_USE if one of the following conditions is met:
          • if this Signature algorithm does not pad the message and the message is not block aligned.
          • if this Signature algorithm does not pad the message and no input data has been provided in inBuff or via the update() method.
          • if the message value is not supported by the Signature algorithm or if a message value consistency check failed.
          • if this Signature algorithm includes message recovery functionality.

      • signPreComputedHash

        public short signPreComputedHash​(byte[] hashBuff,
                                 short hashOff,
                                 short hashLength,
                                 byte[] sigBuff,
                                 short sigOffset)
                          throws CryptoException
        Generates the signature of the precomputed hash data.

        A call to this method also resets this Signature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to sign another precomputed hash.

        Note:

        • This method throws an exception if the underlying signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives. These algorithms throw exception - DES, triple DES, AES, HMAC and KOREAN SEED.
        • Any data previously accumulated from previous calls to the update method are discarded.

        The hash and output buffer data may overlap.

        In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Specified by:
        signPreComputedHash in class Signature
        Parameters:
        hashBuff - the input buffer of precomputed hash to be signed
        hashOff - the offset into the buffer where the hash begins
        hashLength - the byte length of the hash
        sigBuff - the output buffer to store signature data
        sigOffset - the offset into sigBuff at which to begin signature data
        Returns:
        number of bytes of signature output in sigBuff
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.UNINITIALIZED_KEY if key not initialized.
        • CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature verify mode.
        • CryptoException.ILLEGAL_USE if one of the following conditions is met:
          • if the hashLength value is not equal to the length of the algorithm's message digest length.
          • if this Signature algorithm includes message recovery functionality.
          • if the Signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives

      • verify

        public boolean verify​(byte[] inBuff,
                      short inOffset,
                      short inLength,
                      byte[] sigBuff,
                      short sigOffset,
                      short sigLength)
               throws CryptoException
        Verifies the signature of all/last input data against the passed in signature. A call to this method also resets this Signature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to verify another message. In addition, note that the initial vector(IV) used in AES, DES and Korean SEED algorithms in CBC mode will be reset to 0.

        Note:

        • AES, DES, triple DES, and Korean SEED algorithms in CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init(Key, byte, byte[], short, short) method.

        In addition to returning a boolean result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Specified by:
        verify in class Signature
        Parameters:
        inBuff - the input buffer of data to be verified
        inOffset - the offset into the input buffer at which to begin signature generation
        inLength - the byte length to sign
        sigBuff - the input buffer containing signature data
        sigOffset - the offset into sigBuff where signature data begins
        sigLength - the byte length of the signature data
        Returns:
        true if the signature verifies, false otherwise. Note, if sigLength is inconsistent with this Signature algorithm, false is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.UNINITIALIZED_KEY if key not initialized.
        • CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature sign mode.
        • CryptoException.ILLEGAL_USE if one of the following conditions is met:
          • if this Signature algorithm does not pad the message and the message is not block aligned.
          • if this Signature algorithm does not pad the message and no input data has been provided in inBuff or via the update() method.
          • if the message value is not supported by the Signature algorithm or if a message value consistency check failed.
          • if this Signature algorithm includes message recovery functionality.

      • verifyPreComputedHash

        public boolean verifyPreComputedHash​(byte[] hashBuff,
                                     short hashOff,
                                     short hashLength,
                                     byte[] sigBuff,
                                     short sigOffset,
                                     short sigLength)
                              throws CryptoException
        Verifies the signature of precomputed hash data.

        A call to this method also resets this Signature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to verify another precomputed hash. In addition, note that the initial vector(IV) used in AES, DES and Korean SEED algorithms in CBC mode will be reset to 0.

        Note:

        • This method throws an exception if the underlying signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives. These algorithms throw exception - DES, triple DES, AES, and KOREAN SEED.
        • Any data previously accumulated from previous calls to the update method are discarded.

        The hash and output buffer data may overlap.

        In addition to returning a boolean result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Specified by:
        verifyPreComputedHash in class Signature
        Parameters:
        hashBuff - the input buffer of precomputed hash to be verified
        hashOff - the offset into the buffer where the hash begins
        hashLength - the byte length of the hash
        sigBuff - the input buffer containing signature data
        sigOffset - the offset into sigBuff where signature data begins
        sigLength - the byte length of the signature data
        Returns:
        true if the signature verifies, false otherwise. Note, if sigLength is inconsistent with this Signature algorithm, false is returned.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.UNINITIALIZED_KEY if key not initialized.
        • CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature sign mode.
        • CryptoException.ILLEGAL_USE if one of the following conditions is met:
          • if the hashLength value is not equal to the length of the algorithm's message digest length.
          • if this Signature algorithm includes message recovery functionality.
          • if the Signature algorithm does not compute a distinct message digest value prior to applying cryptographic primitives