iaik.security.rsa

Class SHA512_256withRSAandMGF1Signature

java.lang.Object

java.security.SignatureSpi

iaik.security.rsa.RSAPssSignature

iaik.security.rsa.SHA512_256withRSAandMGF1Signature

public class SHA512_256withRSAandMGF1Signature
extends RSAPssSignature

This class implements PKCS#1v2.1 RSASSA-PSS signature scheme using SHA512/256 as hash algorithm, MGF1 (with SHA512/256) as mask generation function, 64 as salt length, and 1 as trailer field (which corresponds to the only trailer field byte -- 0xBC -- supported by PSS).

Although PKCS#1 (v.2.1) requires hash algorithm, mask generation algorithm, salt length and trailer field as parameters for the RSA PSS signature scheme:

 RSASSA-PSS-params :: = SEQUENCE {
      hashAlgorithm            [0] HashAlgorithm     DEFAULT sha1,
      maskGenerationAlgorithm  [1] MaskGenAlgorithm  DEFAULT mgf1SHA1,
      saltLength               [2] INTEGER           DEFAULT 20,
      trailerField             [3] TrailerField      DEFAULT trailerFieldBC
 }

 HashAlgorithm ::= Algorithmidentifier { {OAEP-PSSDigestAlgorithms} }

 MaskGenAlgorithm ::= AlgorithmIdentifier { {PKCS1MGFAlgorithms} }

 TrailerField ::= INTEGER { trailerFieldBC(1) }
 

the Java Cryptography Architecture only allows to set the salt length as parameter and specifiesall the other parameters by the algorithm standard name to be implemented by a corresponding PSS signature engine: A signature engine that implements the "SHA512/256withRSAandMGF1" (in general: <digest>with<encryption>and<mgf>) PSS signature algorithm has to use SHA512/256 as hash- and MGF1 as mask generation algorithm. The trailer field (0xBC) is fixed by the PKCS#1v2.1 standard and the salt length may be supplied as parameter; if not, a default salt length (28 for the SHA512/256 hash algorithm) will be used.

Because of compatibility of IAIK-JCE to JDK versions prior to 1.4 there is no proper way to use the java.security.spec.PSSParameterSpec class for modelling the saltLength parameter. The same functionality is provided by class RSAPssSaltParameterSpec which may be used to supply the saltLength to this PSS based signature engine; if no salt length is explicitly supplied, the defined default salt length for the underlying signature engine will be used.
An application also may use a RSAPssSaltParameterSpec or PKCS1AlgorithmParameterSpec to provide a SecureRandom object for supplying any random numbers as required by the PSS signature algorithm. 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 for generating random numbers.

Generally the following steps have to be performed for calculating/verifying a SHA512/256withRSAandMGF1 signature:

• First an instance of the SHA512/256withRSAandMGF1 signature engine has to be created using a proper getInstance method:

   Signature pss = Signature.getInstance("SHA512/256withRSAandMGF1");
   

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

• Third, optionally the saltLength maybe supplied as RSAPssSaltParameterSpec:

   int saltLength = ...;
   RSAPssSaltParameterSpec saltParamSpec = new RSAPssSaltParameterSpec(hashID, mgfID, saltLength);
   // set the parameters
   pss.setParameter(saltParamSpec); 
   

• 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:

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

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

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

Version:

File Revision 13

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
SHA512_256withRSAandMGF1Signature() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
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	engineSetParameter(java.security.spec.AlgorithmParameterSpec params) Sets the saltLength parameter for this RSA PSS signature engine.
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 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.RSAPssSignature

engineGetParameter, engineGetParameters, engineInitSign, engineInitVerify, engineSign, engineVerify, setValidateAgainstPssKeyParameters

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

SHA512_256withRSAandMGF1Signature

public SHA512_256withRSAandMGF1Signature()

Default constructor. Shall not be used by an application.

Applications use

 Signature signature = Signature.getInstance("SHA512/256withRSAandMGF1");
 

to get an instance of this PSS signature engine using SHA512/256 as hash- and MGF1 (with SHA512/256) as mask generation algorithm.

Method Detail

engineSetParameter

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

Sets the saltLength parameter for this RSA PSS signature engine.

Although PKCS#1 (v.2.1) requires hash algorithm, mask generation algorithm, salt length and trailer field as parameters for the RSA PSS signature scheme:

 RSASSA-PSS-params :: = SEQUENCE {
      hashAlgorithm            [0] HashAlgorithm     DEFAULT sha1,
      maskGenerationAlgorithm  [1] MaskGenAlgorithm  DEFAULT mgf1SHA1,
      saltLength               [2] INTEGER           DEFAULT 20,
      trailerField             [3] TrailerField      DEFAULT trailerFieldBC
 }

 HashAlgorithm ::= Algorithmidentifier { {OAEP-PSSDigestAlgorithms} }

 MaskGenAlgorithm ::= AlgorithmIdentifier { {PKCS1MGFAlgorithms} }

 TrailerField ::= INTEGER { trailerFieldBC(1) }
 

the Java Cryptography Architecture only allows to set the salt length as parameter and specifies all the other parameters by the algorithm standard name to be implemented by a corresponding PSS signature engine: A signature engine that implements the, for instance, "SHA1withRSAandMGF1" (in general: <digest>with<encryption>and<mgf>) PSS signature algorithm has to use SHA-1 as hash- and MGF1 as mask generation algorithm. The trailer field (0xBC) is fixed by the PKCS#1v2.1 standard and the salt length may be supplied as parameter; if not, a default salt length (20 for the SHA-1 hash algorithm) will be used.

Because of the JDK1.1.x compatibility of IAIK-JCE there is no proper way to use the java.security.spec.PSSParameterSpec class for modelling the saltLength parameter. The same functionality is provided by class RSAPssSaltParameterSpec which may be used to supply the saltLength to this PSS based signature engine; if no salt length is explicitly supplied, the defined default salt length for the underlying signature engine will be used.
An application also may use a RSAPssSaltParameterSpec or PKCS1AlgorithmParameterSpec to provide a SecureRandom object for supplying any random numbers as required by the PSS signature algorithm. 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 for generating random numbers.

However, if the application specifies the salt (length) by means of a RSAPssParameterSpec it is also checked if the other parameters (hash algorithm, mask generation function, trailer field) are valid for this Signature engine.

Overrides:

engineSetParameter in class RSAPssSignature

Parameters:

params - the saltLength parameter supplied as RSAPssSaltParameterSpec

Throws:

java.security.InvalidAlgorithmParameterException - if the parameters are not supplied as RSAPssSaltParameterSpec, RSAPssParameterSpec or PKCS1AlgorithmParameterSpec, or if invalid parameters are specified

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