iaik.security.rsa

Class RSASignature

java.lang.Object

java.security.SignatureSpi

iaik.security.rsa.RSASignature

Direct Known Subclasses:

Md2RSASignature, Md5RSASignature, RawRSAPkcs1v15Signature, RipeMd128RSASignature, RipeMd160RSASignature, RipeMd256RSASignature, Sha224RSASignature, Sha256RSASignature, Sha3_224RSASignature, Sha3_256RSASignature, Sha3_384RSASignature, Sha3_512RSASignature, Sha384RSASignature, Sha512_224RSASignature, Sha512_256RSASignature, Sha512RSASignature, ShaRSASignature, WhirlpoolRSASignature

public abstract class RSASignature
extends java.security.SignatureSpi

This class implements the sign and verify methods of the PKCS#1v1.5 signature scheme (RSASSA-PKCS1-v1_5).

Digital signatures are used for ensuring data authentication and data integrity. RSA PKCS1v1.5 based signature algorithms use a proper hash function for creating a message digest of the message to be signed. Subsequently this message digest is wrapped in a DigestInfo and then encrypted with the RSA private key of the entity going to sign the message. Message and encrypted message digest together are sent to the intended recipient that verifies the signature by decrypting the received encrypted message digest with the corresponding RSA public key, and comparing it with the hash value derived from the received original message after hashing it with the same hash function as used by the entity that has sent the message.

This class follows the guidelines presented in PKCS#1 (v.2.1)) for implementing a PKCS#1v1.5 (RSASSA-PKCS1-v1_5) signature algorithm based on the RSA encryption method.

An application wishing to sign some message or to verify some signature, generally has to perform three steps (in the following example, HASH has to be replaced by the name of the desired hash algorithm):

• First an instance of the desired signature algorithm has to be created using a proper getInstance method, e.g.:

   Signature hash_rsa = Signature.getInstance("HASHwithRSA");
   

• Second, the Signature object just created has to be properly initialized for signing a message respectively verifying a signature using a RSA private respectively RSA public key, e.g.:
  • Initialize for Signing: hash_rsa.initSign(rsaPrivateKey);
  • Initialize for Verifying: hash_rsa.initVerify(rsaPublicKey);

• Finally, if the Signature object has been initialized for signing, the data to be signed is supplied to it and subsequently the signature is created by calling the sign method returning the signature as byte array. Otherwise, if the Signature object has been initialized for verifying, first the data to be verified is supplied to the Signature object, and subsequently the signature is verified by calling the verify method, supplied with the byte array holding the corresponding signature value:
  • Supply the data to be signed, and subsequently sign it:

     hash_rsa.update(data);
     byte[] signature = hash_rsa.sign();
     

  • Supply the data to be verified, and verify the signature:

     hash_rsa.update(data);
     System.out.println("Signature " + (hash_rsa.verify(signature) ? "correct!" : "not correct!"));
     

Version:

File Revision 18

See Also:

Md2RSASignature, Md5RSASignature, ShaRSASignature, Sha224RSASignature, Sha256RSASignature, Sha384RSASignature, Sha512RSASignature, RipeMd128RSASignature, RipeMd160RSASignature, RawRSAPkcs1v15Signature, RawRSASignature, Signature

Field Summary

Fields

Modifier and Type	Field and Description
protected java.security.MessageDigest	hash The MessageDigest engine used to hash the data; supplied with an instance of the desired MessageDigest algorithm by any extending subclass.

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RSASignature(AlgorithmID hashAlgorithm, java.security.MessageDigest hash) Creates a RSA PKCS#1v1.5 Signature object with a specified hash algorithm.
protected	RSASignature(java.lang.String name, java.security.MessageDigest hash) Creates a RSA PKCS#1v1.5 Signature object with the given name using the specified hash algorithm.

Method Summary

Methods

Modifier and Type	Method and Description
protected java.lang.Object	engineGetParameter(java.lang.String param) This method is not used and only throws an InvalidParameterException.
protected void	engineInitSign(java.security.PrivateKey pk) SPI: Initializes this Signature object with the given RSA private key for going to sign some data.
protected void	engineInitSign(java.security.PrivateKey pk, java.security.SecureRandom random) SPI: Initializes this Signature object with the given RSA private key for going to sign some data.
protected void	engineInitVerify(java.security.PublicKey pk) SPI: Initializes this Signature object with the given RSA public key for performing a signature verification.
protected void	engineSetParameter(java.security.spec.AlgorithmParameterSpec params) Allows to supply a SecureRandom object if required by the underlying signature scheme (e.g.
protected void	engineSetParameter(java.lang.String param, java.lang.Object value) Allows to supply a SecureRandom object if required by the underlying signature scheme (e.g.
protected byte[]	engineSign() SPI: Calculates the signature.
protected void	engineUpdate(byte b) SPI: Updates the data to be signed or verified with the specified byte.
protected void	engineUpdate(byte[] b, int off, int len) SPI: Updates the data to be signed or verified with the specified number of bytes, beginning at the specified offset within the given byte array.
protected boolean	engineVerify(byte[] sigBytes) Verifies the given signature of a message according to PKCS#1v1.5.

Methods inherited from class java.security.SignatureSpi

clone, engineGetParameters, engineSign, engineUpdate, engineVerify

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

hash

protected java.security.MessageDigest hash

The MessageDigest engine used to hash the data; supplied with an instance of the desired MessageDigest algorithm by any extending subclass.

Constructor Detail

RSASignature

protected RSASignature(AlgorithmID hashAlgorithm,
            java.security.MessageDigest hash)

Creates a RSA PKCS#1v1.5 Signature object with a specified hash algorithm.

This constructor is called from subclasses to represent a RSA PKCS#1v1.5 signature with a defined hash algorithm.

Applications use

 Signature.getInstance("HASHwithRSA");
 

for creating a Signature object, where HASH has to be replaced by the name of the desired hash algorithm.

Parameters:

hashAlgorithm - the algorithm id of the hash algorithm to use

hash - the MessageDigest engine to be used for hashing the data

See Also:

Signature.getInstance(java.lang.String)

RSASignature

protected RSASignature(java.lang.String name,
            java.security.MessageDigest hash)

Creates a RSA PKCS#1v1.5 Signature object with the given name using the specified hash algorithm.

This constructor is called from subclasses to represent a raw RSA PKCS#1v1.5 signature engine.

Parameters:

name - the name of the signature algorithm

hash - the MessageDigest engine to be used for hashing the data

See Also:

Signature.getInstance(java.lang.String)

Method Detail

engineSign

protected byte[] engineSign()
                     throws java.security.SignatureException

SPI: Calculates the signature.

Specified by:

engineSign in class java.security.SignatureSpi

Returns:

a byte array holding the signature value calculated on the data that has been supplied when updating this engine

Throws:

java.security.SignatureException - if an error occurs when creating the signature

engineVerify

protected boolean engineVerify(byte[] sigBytes)
                        throws java.security.SignatureException

Verifies the given signature of a message according to PKCS#1v1.5.

PKCS#1v1.5 defines a signature as bit string, which has to be converted into an octet string, RSA decrypted with the signer's RSA public key, and DER decoded for giving an ASN.1 DigestInfo. From this DigestInfo the message digest has to be taken to compare it with the message digest derived from hashing the original message with the same message digest algorithm.

Please notice that the first step of bit-string-to-octet-string conversion already has to be done when calling this verify method. In this way the supplied sigBytes value has to be the octet string signature value.

Specified by:

engineVerify in class java.security.SignatureSpi

Parameters:

sigBytes - the signature bytes to be verified

Returns:

true if signature is OK, false otherwise

Throws:

java.security.SignatureException - if an error occurs when verifying the signature

engineInitVerify

protected void engineInitVerify(java.security.PublicKey pk)
                         throws java.security.InvalidKeyException

SPI: Initializes this Signature object with the given RSA public key for performing a signature verification.

Specified by:

engineInitVerify in class java.security.SignatureSpi

Parameters:

pk - the RSA public key belonging to the RSA private key that has been used for signing.

Throws:

java.security.InvalidKeyException - if a key encoding error occurs

engineInitSign

protected void engineInitSign(java.security.PrivateKey pk)
                       throws java.security.InvalidKeyException

SPI: Initializes this Signature object with the given RSA private key for going to sign some data.

Specified by:

engineInitSign in class java.security.SignatureSpi

Parameters:

pk - the RSA private key to be used for signing.

Throws:

java.security.InvalidKeyException - if a key encoding error occurs

engineInitSign

protected void engineInitSign(java.security.PrivateKey pk,
                  java.security.SecureRandom random)
                       throws java.security.InvalidKeyException

SPI: Initializes this Signature object with the given RSA private key for going to sign some data. The supplied SecureRandom may be used by the signature engine if random numbers are required (e.g. PSS).

If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom, if required.

Overrides:

engineInitSign in class java.security.SignatureSpi

Parameters:

pk - the RSA private key to be used for signing.

random - the SecureRandom if random numbers are required by the signature engine (e.g. PSS)

Throws:

java.security.InvalidKeyException - if a key encoding error occurs

engineUpdate

protected void engineUpdate(byte b)

SPI: Updates the data to be signed or verified with the specified byte.

Specified by:

engineUpdate in class java.security.SignatureSpi

Parameters:

b - the byte to be used for updating.

engineUpdate

protected void engineUpdate(byte[] b,
                int off,
                int len)

SPI: Updates the data to be signed or verified with the specified number of bytes, beginning at the specified offset within the given byte array.

Specified by:

engineUpdate in class java.security.SignatureSpi

Parameters:

b - the byte array holding the data to be used for this update operation.

off - the offset, indicating the start position within the given byte array.

len - the number of bytes to be obtained from the given byte array, starting at the given position.

engineSetParameter

protected void engineSetParameter(java.lang.String param,
                      java.lang.Object value)
                           throws java.security.InvalidParameterException

Allows to supply a SecureRandom object if required by the underlying signature scheme (e.g. PSS). When using JDK versions prior JDK 1.2 method initSign(PrivateKey, SecureRandom) is not available. If required by the underlying signature scheme (e.g. PSS) an application may supply a SecureRandom object as parameter. If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom, if required.

Specified by:

engineSetParameter in class java.security.SignatureSpi

Parameters:

param - ignored

value - the SecureRandom supplied as PKCS1AlgorithmParameterSpec

Throws:

java.security.InvalidParameterException - if the SecureRandom is not supplied as PKCS1AlgorithmParameterSpec

engineSetParameter

protected void engineSetParameter(java.security.spec.AlgorithmParameterSpec params)
                           throws java.security.InvalidAlgorithmParameterException

Allows to supply a SecureRandom object if required by the underlying signature scheme (e.g. PSS). JDK 1.2 (or later) based applications may prefer to use method initSign(PrivateKey, SecureRandom) to supply a SecureRandom object if required. If a SecureRandom never has been supplied by the application, the signature engine will use a default SecureRandom, if required.

Overrides:

engineSetParameter in class java.security.SignatureSpi

Parameters:

params - the SecureRandom supplied as PKCS1AlgorithmParameterSpec

Throws:

java.security.InvalidParameterException - if the SecureRandom is not supplied as PKCS1AlgorithmParameterSpec

java.security.InvalidAlgorithmParameterException

engineGetParameter

protected java.lang.Object engineGetParameter(java.lang.String param)
                                       throws java.security.InvalidParameterException

This method is not used and only throws an InvalidParameterException.

Specified by:

engineGetParameter in class java.security.SignatureSpi

Throws:

java.security.InvalidParameterException - This Method is not supported