iaik.pkcs.pkcs11.provider.signatures.rsa

Class ExternalRsaPssSignature

java.lang.Object

java.security.SignatureSpi

iaik.pkcs.pkcs11.provider.signatures.PKCS11Signature

iaik.pkcs.pkcs11.provider.signatures.ExternalHashSignature

iaik.pkcs.pkcs11.provider.signatures.rsa.ExternalRsaPssSignature

All Implemented Interfaces:

PKCS11EngineClass

public class ExternalRsaPssSignature
extends ExternalHashSignature

This is an implementation of a Signature class that uses the IAIK PKCS#11 wrapper to access the token. It only works with IAIKPKCS11PrivateKey and IAIKPKCS11PublicKey. This version uses the RSA_PKCS_PSS mechanism to create a RSASSA-PSS signature. Refer to the PKCS#11 v2.11 standard for details.

The hash over the data is calculated by using the configured software delegation provider (IAIK by the default). MGF1 is used as mask generation function, by default with SHA-1 as hash function (which by default is also used for data hash calculation). An alternative hash function can be provided by calling method Signature.setParameter() where the parameters have to be supplied as iaik.pkcs.pkcs11.provider.signatures.PKCS11SignatureParameterSpec (or maybe java.security.spec.PSSParameterSpec or iaik.pkcs.pkcs1.RSAPssParameterSpec) on the signing side, or java.security.spec.PSSParameterSpec or iaik.pkcs.pkcs1.RSAPssParameterSpec on the verification side where a software delegate is used.
On the signing side Signature.setParameter() must be called before initializing the Signature engine (calling Signature.initSign(); a typical workflow may look like (for using SHA-256 as hash function):

 // the PKCS#11 provider instance
 IAIKPkcs11 pkcs11Provider = new IAIKPkcs11();
 // the private (PKCS#11) signing key
 PrivateKey privatekey = ...;
 // create Signature engine
 Signature signature = Signature.getInstance("RSASSA-PSS", pcks11Provider);
 // create and set PSS parameters for SHA-256
 Mechanism hashAlgorithm = Mechanism.get(PKCS11Constants.CKM_SHA256);
 long messageGenerationFunctionType = RSAPkcsParameters.MessageGenerationFunctionType.SHA256;
 int saltLength == 32;
 RSAPkcsPssParameters parameters = new RSAPkcsPssParameters(hashAlgorithm, messageGenerationFunctionType, saltLength);
 PKCS11SignatureParameterSpec paramSpec = new PKCS11SignatureParameterSpec(parameters); 
 signature.setParameter(paramSpec);
 // init Signature engine for signing
 signatureEngine.initSign(signatureKey);
 // supply data to be signed by one or more update calls
 byte[] data ...;
 signature.update(data);
 // finish signature calculation
 byte[] signatureValue = signature.sign();
 

On the verification side typically a software provider (like IAIK) will be used for verifying the signature, e.g.:

 // the public (software) verification key
 PublicKey publickey = ...;
 // create and init Signature engine
 Signature signature = Signature.getInstance("RSASSA-PSS","IAIK");
 signature.initVerify(publicKey);
 // create and set PSS parameters for SHA-256
 AlgorithmID hashID = (AlgorithmID)AlgorithmID.sha256.clone();
 AlgorithmID mgfID = (AlgorithmID)AlgorithmID.mgf1.clone();
 mgfID.setParameter(hashID.toASN1Object());
 int saltLength = 32;
 RSAPssParameterSpec pssParamSpec = new RSAPssParameterSpec(hashID, mgfID, saltLength);
 signature.setParameter(pssParamSpec); 
 // supply data that has been signed by one or more update calls
 byte[] data ...;
 signature.update(data);
 // verify signature value
 boolean valid = signature.verify(signatureValue);
 

Field Summary

Fields

Modifier and Type	Field and Description
protected iaik.pkcs.pkcs11.Mechanism	mechanism_ The mechanism of this signature object which contains parameters also.
protected static java.lang.String	SIGNATURE_ALGORITHM_NAME The JCA standard name of this signature algorithm.

Fields inherited from class iaik.pkcs.pkcs11.provider.signatures.ExternalHashSignature

messageDigest_

Fields inherited from class iaik.pkcs.pkcs11.provider.signatures.PKCS11Signature

currentKeyIsSoftwareKey_, initialized_, operationState_, pkcs11OperationInitialized_, privateKey_, publicKey_, session_, SIGN, softwareDelegate_, tokenManager_, usedMechanismInfos_, usedMechanisms_, VERIFY

Fields inherited from class java.security.SignatureSpi

appRandom

Constructor Summary

Constructors

Constructor and Description
ExternalRsaPssSignature() Public default constructor to enable instantiation via Class.forName(String).

Method Summary

Modifier and Type	Method and Description
protected void	engineSetParameter(java.security.spec.AlgorithmParameterSpec parametersSpec) SPI: Set the parameters for this signature object.
protected java.lang.String	getAlgorithmName() Get the JCA standard name of this signature algorithm.
protected iaik.pkcs.pkcs11.Mechanism	getMechanism() Get the mechanism of this signature object.
protected java.lang.String	getMessageDigestName() Returns the message digest's name that this object uses to hash the data.
protected void	pkcs11SetParameter(java.security.spec.AlgorithmParameterSpec parametersSpec) SPI: Set the parameters for this signature object.

Methods inherited from class iaik.pkcs.pkcs11.provider.signatures.ExternalHashSignature

getMessageDigest, pkcs11InitSign, pkcs11InitVerify, pkcs11Sign, pkcs11Update, pkcs11Update, pkcs11Verify, prepareHash

Methods inherited from class iaik.pkcs.pkcs11.provider.signatures.PKCS11Signature

engineGetParameter, engineInitSign, engineInitVerify, engineSetParameter, engineSign, engineUpdate, engineUpdate, engineVerify, finalize, finalizePkcs11Operation, getUsedMechanismFeatures, getUsedMechanisms, initializePkcs11Operation, initializeSession, initializeSoftwareDelegate, isSupportedBy, pkcs11GetParameter, pkcs11SetParameter

Methods inherited from class java.security.SignatureSpi

clone, engineGetParameters, engineInitSign, engineSign, engineUpdate, engineVerify

Methods inherited from class java.lang.Object

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

Field Detail

SIGNATURE_ALGORITHM_NAME

protected static java.lang.String SIGNATURE_ALGORITHM_NAME

The JCA standard name of this signature algorithm.

mechanism_

protected iaik.pkcs.pkcs11.Mechanism mechanism_

The mechanism of this signature object which contains parameters also.

Constructor Detail

ExternalRsaPssSignature

public ExternalRsaPssSignature()

Public default constructor to enable instantiation via Class.forName(String). Shall NOT be used by applications. Applications shall instantiate a RSA-PSS Signature engine by calling Signature.getInstance("RSASSA-PSS", pkcs11Provider);.

Method Detail

getMessageDigestName

protected java.lang.String getMessageDigestName()

Returns the message digest's name that this object uses to hash the data. This is the JCA name.

Specified by:

getMessageDigestName in class ExternalHashSignature

Returns:

A message digest's JCA name.

Postconditions:

(result <> null)

getAlgorithmName

protected java.lang.String getAlgorithmName()

Get the JCA standard name of this signature algorithm.

Specified by:

getAlgorithmName in class PKCS11Signature

Returns:

The JCA standard name of this signature algorithm.

Postconditions:

(result <> null)

engineSetParameter

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

SPI: Set the parameters for this signature object. For this implementation, the parametersSpec shall be an iaik.pkcs.pkcs11.provider.signatures.PKCS11SignatureParameterSpec (or a java.security.spec.PSSParameterSpec or an iaik.pkcs.pkcs1.RSAPssParameterSpec). On the verification side when using a software delegate provider the parameters have to be a java.security.spec.PSSParameterSpec or an iaik.pkcs.pkcs1.RSAPssParameterSpec..

Overrides:

engineSetParameter in class PKCS11Signature

Parameters:

parametersSpec - The AlgorithmParameterSpec containing the PSS parameters.

Throws:

java.security.InvalidAlgorithmParameterException - if the given parameters are not supported.

pkcs11SetParameter

protected void pkcs11SetParameter(java.security.spec.AlgorithmParameterSpec parametersSpec)
                           throws java.security.InvalidAlgorithmParameterException

SPI: Set the parameters for this signature object. For this implementation, the parametersSpec shall be an iaik.pkcs.pkcs11.provider.signatures.PKCS11SignatureParameterSpec (or a java.security.spec.PSSParameterSpec or an iaik.pkcs.pkcs1.RSAPssParameterSpec). On the verification side when using a software delegate provider the parameters have to be a java.security.spec.PSSParameterSpec or an iaik.pkcs.pkcs1.RSAPssParameterSpec..

Overrides:

pkcs11SetParameter in class PKCS11Signature

Parameters:

parametersSpec - The AlgorithmParameterSpec containing the PSS parameters.

Throws:

java.security.InvalidAlgorithmParameterException - if the given parameters are not supported.

getMechanism

protected iaik.pkcs.pkcs11.Mechanism getMechanism()

Get the mechanism of this signature object. This implementation returns a mechanism with CKM_RSA_PKCS_PSS as ID.

Specified by:

getMechanism in class ExternalHashSignature

Returns:

The mechanism this object uses for signing and verification.

Postconditions:

(result <> null)