iaik.security.rsa

Class RawRSAPkcs1v15Signature

java.lang.Object

java.security.SignatureSpi

iaik.security.rsa.RSASignature

iaik.security.rsa.RawRSAPkcs1v15Signature

public class RawRSAPkcs1v15Signature
extends RSASignature

This class represents a "raw" implementation of the RSA PKCS#1v1.5 digital signature algorithm (RSASSA-PKCS1-v1_5) where the hash on the data to be signed has to be calculated by the application.

In contrast to the RawRSASignature engine class where the application has to do both hash calculation and DigestInfo wrapping, this class only expects that the hash value is supplied to one of its update methods and does the DigestInfo wrapping/unwrapping itself. Since building the DigestInfo requires the knowledge of the hash algorithm in use, the calling application has to supply the corresponding algorithm id as RSASSAPkcs1v15ParameterSpec:

 AlgorithmID hashAlgorithm = AlgorithmID.sha1; 
 RSASSAPkcs1v15ParameterSpec params = new RSASSAPkcs1v15ParameterSpec(hashAlgorithm);
 

Generally an application wishing to sign some message or to verify some signature, generally has to perform four 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 rawRsaSignatureEngine = Signature.getInstance("RSAPkcs15", "IAIK");
   

• 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: rawRsaSignatureEngine.initSign(rsaPrivateKey);
  • Initialize for Verifying: rawRsaSignatureEngine.initVerify(rsaPublicKey);

• Third, the hash algorithm has to be supplied as parameters spec, e.g.:

   AlgorithmID hashAlgorithm = AlgorithmID.HASH; // e.g. AlgorithmID.sha1
   RSASSAPkcs1v15ParameterSpec params = new RSASSAPkcs1v15ParameterSpec(hashAlgorithm);
   rawRsaSignatureEngine.setParameter(null, params);
   

• Finally, if the Signature object has been initialized for signing, the prepared hash 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 prepared hash 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 prepared hash to be signed, and subsequently sign it:

     rawRsaSignatureEngine.update(preparedHash);
     byte[] signature = rawRsaSignatureEngine.sign();
     

  • Supply the prepared hash to be verified, and verify the signature:

     rawRsaSignatureEngine.update(preparedHash);
     System.out.println("Signature " + (rawRsaSignatureEngine.verify(signature) ? "correct!" : "incorrect!"));
     

Please note that it is the entire responsibility of the application to take care to provide a proper hash value when calling an update method; no check is performed if the supplied hash value corresponds to the hash algorithm in use (e.g. has the correct length).

Version:

File Revision 11

See Also:

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

Constructor and Description
RawRSAPkcs1v15Signature() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected java.lang.Object	engineGetParameter(java.lang.String param) Returns the hash algorithm parameter used by this PKCS#1.5 signature engine.
protected java.security.AlgorithmParameters	engineGetParameters() Returns the hash algorithm parameter used by this PKCS#1.5 signature engine.
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) Sets the hash algorithm parameter to be used by this PKCS#1.5 signature engine.
protected void	engineSetParameter(java.lang.String param, java.lang.Object value) Sets the hash algorithm parameter to be used by this PKCS#1.5 signature engine.
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.

Methods inherited from class iaik.security.rsa.RSASignature

engineSign, engineVerify

Methods inherited from class java.security.SignatureSpi

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

RawRSAPkcs1v15Signature

public RawRSAPkcs1v15Signature()

Default constructor.

Applications use

 Signature.getInstance("RSAPkcs15");
 

for creating a Signature object.

Method Detail

engineSetParameter

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

Sets the hash algorithm parameter to be used by this PKCS#1.5 signature engine. In contrast to the RawRSASignature engine class where the application has to do both hash calculation and DigestInfo wrapping, this class only expects that the hash value is supplied to one of its update methods and does the DigestInfo wrapping/unwrapping itself. Since building the DigestInfo requires the knowledge of the hash algorithm in use, the calling application has to supply the corresponding algorithm id as RSASSAPkcs1v15ParameterSpec:

 AlgorithmID hashAlgorithm = AlgorithmID.sha1; 
 RSASSAPkcs1v15ParameterSpec params = new RSASSAPkcs1v15ParameterSpec(hashAlgorithm);
 rawRsaSignatureEngine.setParameter(null, params);
 

Parameters:

param - ignored

value - the hash algorithm supplied as RSASSAPkcs1v15ParameterSpec

Throws:

java.security.InvalidParameterException - if the hash algorithm is not supplied as RSASSAPkcs1v15ParameterSpec

engineSetParameter

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

Sets the hash algorithm parameter to be used by this PKCS#1.5 signature engine. In contrast to the RawRSASignature engine class where the application has to do both hash calculation and DigestInfo wrapping, this class only expects that the hash value is supplied to one of its update methods and does the DigestInfo wrapping/unwrapping itself. Since building the DigestInfo requires the knowledge of the hash algorithm in use, the calling application has to supply the corresponding algorithm id as RSASSAPkcs1v15ParameterSpec:

 AlgorithmID hashAlgorithm = AlgorithmID.sha1; 
 RSASSAPkcs1v15ParameterSpec params = new RSASSAPkcs1v15ParameterSpec(hashAlgorithm);
 rawRsaSignatureEngine.setParameter(null, params);
 

Parameters:

params - the hash algorithm supplied as RSASSAPkcs1v15ParameterSpec

Throws:

java.security.InvalidParameterException - if the hash algorithm is not supplied as RSASSAPkcs1v15ParameterSpec

java.security.InvalidAlgorithmParameterException

engineGetParameter

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

Returns the hash algorithm parameter used by this PKCS#1.5 signature engine.

Parameters:

param - ignored

Returns:

the hash algorithm as RSASSAPkcs1v15Parameters

Throws:

java.security.InvalidParameterException - should not occur

engineGetParameters

protected java.security.AlgorithmParameters engineGetParameters()

Returns the hash algorithm parameter used by this PKCS#1.5 signature engine.

Overrides:

engineGetParameters in class java.security.SignatureSpi

Returns:

the hash algorithm as RSASSAPkcs1v15Parameters

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.