it.trento.comune.j4sign.pkcs11

Class PKCS11Signer

java.lang.Object

it.trento.comune.j4sign.pkcs11.PKCS11Signer

public class PKCS11Signer
extends java.lang.Object

This class uses the PKCS#11 Java api provieded by IAIK pkcs11 wrapper to perform PKCS#11 digital signature operations.
The IAIK wrapper is released in open source under an Apache-style license.
Here we use only a low-level subset of the wrapper's api (distributed in the j4sign installer package), so to minimize the weight of the relative jar files in an applet signing environment.

Several methods are designed to ease object retrieval during an italian style digital signature process. See findCertificateWithNonRepudiationCritical()for details.

Author:

Roberto Resoli

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	cryptokiLibrary The cryptokiLibrary is the native library implementing the PKCS#11 specification.
private boolean	libFinalized The finalization state of cryptokiLibrary?
private java.io.PrintStream	log The PrintStream where logging messages are written.
private PKCS11	pkcs11Module The java object wrapping criptoki library functionalities.
private long	sessionHandle The PKCS#11 session identifier returned when a session is opened.
private CK_MECHANISM	signatureMechanism PKCS#11 identifier for the signature algorithm.
private long	tokenHandle The PKCS#11 token identifier.

Constructor Summary

Constructors

Constructor and Description
PKCS11Signer(java.lang.String cryptokiLib, long mechanism, java.io.PrintStream out)
PKCS11Signer(java.lang.String cryptokiLib, long mechanism, java.lang.String reader, java.io.PrintStream out)
PKCS11Signer(java.lang.String cryptokiLib, java.io.PrintStream out)

Method Summary

Methods

Modifier and Type	Method and Description
void	closeSession() Closes the default PKCS#11 session.
void	closeSession(long sessionHandle) Closes a specific PKCS#11 session.
static java.lang.String	decodeError(int errorCode) Error decoding function.
byte[]	encryptDigest(java.lang.String label, byte[] digest)
long	findCertificateFromID(byte[] id) Finds a certificate matching the given byte[] id.
long	findCertificateFromLabel(char[] label) Finds a certificate matching the given textual label.
long	findCertificateFromSignatureKeyHandle(long signatureKeyHandle) Searches the certificate corresponding to the private key identified by the given handle; this method assumes that corresponding certificates and private keys are sharing the same byte[] IDs.
long[]	findCertificates() Trova un'array di certHandle di tutti i certificati presenti sulla carta senza che la sessione sia aperta (no password).
long	findCertificateWithNonRepudiationCritical() Queries the current token for a certificate suitable for a legal value subscription.
long	findCertificateWithNonRepudiationCritical(long token) Queries the a specific token for a certificate suitable for a legal value subscription.
long	findSignatureKey() Returns the first private key handle found on current token.
long	findSignatureKeyFromCertificateHandle(long certHandle) Searches the private key corresponding to the certificate identified by the given handle; this method assumes that corresponding certificates and private keys are sharing the same byte[] IDs.
long	findSignatureKeyFromID(byte[] id) Returns the private key handle, on current token, corresponding to the given byte[].
long	findSignatureKeyFromLabel(java.lang.String label) Returns the private key handle, on current token, corresponding to the given textual label.
long	findSuitableToken(long mechanismCode)
java.util.ArrayList	findTokensSupportingMechanism(long mechanismCode)
java.lang.String	getCryptokiLibrary() Gets the cryptoki library name.
byte[]	getDEREncodedCertificate(long certHandle) Returns the DER encoded certificate identified by the given handle, as read from the token.
byte[]	getDEREncodedCertificate(long certHandle, long sessionHandle)
byte[]	getDEREncodedCertificateAndID(long certHandle, java.io.ByteArrayOutputStream id) Returns the DER encoded certificate identified by the given handle, and its ID attribute.
byte[]	getDEREncodedCertificateFromLabel(java.lang.String label) Returns the DER encoded certificate corresponding to the given label, as read from the token.
void	getMechanismInfo() Gets informations on cryptographic operations supported by the tokens.
private void	getModuleInfo() Gets currently loaded cryptoky description.
private PKCS11	getPkcs11() Gets the java wrapper for the cryptoki.
private long	getSession() Gets the current session handle.
java.lang.String	getSlotDescription(long slotID)
private long[]	getSlotList() Gets current reader infos.
java.lang.String	getTokenDescription()
long	getTokenHandle() Gets the current token.
long[]	getTokenList() Lists currently inserted tokens and relative infos.
long[]	getTokens() Lists currently inserted tokens.
long	getTokenSupportingMechanism(long mechanismCode) Queries if there is a token that supporting a given cryptographic operation.
private void	initializeLibrary() Initializes cryptoki library operations.
private void	initializeTokenAndMechanism(long mechanism)
private void	initializeTokenInReader(java.lang.String reader)
(package private) boolean	isKeyUsageNonRepudiationCritical(java.security.cert.X509Certificate javaCert) checks Key Usage constraints of a java certificate.
boolean	isLibFinalized() Is cryptokiLibrary finalized (unlinked) ?
boolean	isMechanismSupportedByToken(long mechanismCode, long tokenID) Tells if a given token supports a given cryptographic operation.
void	libFinalize() Finalizes PKCS#11 operations; note this NOT actually unloads the native library.
void	login(char[] pwd) Logs in to the current session; login is usually necessary to see and use private key objects on the token.
void	login(java.lang.String pwd) Logs in to the current session; login is usually necessary to see and use private key objects on the token.
void	logout() Logs out the current user.
void	openSession() Opens a session on the default token.
void	openSession(char[] password) Opens a session on the token, logging in the user.
long	openSession(long aTokenHandle) Opens a session on a specific token.
void	setCryptokiLibrary(java.lang.String newCryptokiLibrary) Sets the cryptoky library
void	setMechanism(long mechanism)
void	setMechanism(long mechanism, java.lang.Object pParameter)
private void	setSession(long newSession) Sets the session handle.
void	setTokenHandle(long token) Sets the current token handle.
byte[]	signDataMultiplePart(long signatureKeyHandle, java.io.InputStream dataStream) Sign (here means digesting and encrypting with private key) the provided data with a multiple-pass operation.
byte[]	signDataSinglePart(long signatureKeyHandle, byte[] data) Sign (here means encrypting with private key) the provided data with a single operation.

Methods inherited from class java.lang.Object

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

Field Detail

cryptokiLibrary

private java.lang.String cryptokiLibrary

The cryptokiLibrary is the native library implementing the PKCS#11 specification.

libFinalized

private boolean libFinalized

The finalization state of cryptokiLibrary?

sessionHandle

private long sessionHandle

The PKCS#11 session identifier returned when a session is opened. Value is -1 if no session is open.

tokenHandle

private long tokenHandle

The PKCS#11 token identifier. Value is -1 if there is no current token.

pkcs11Module

private PKCS11 pkcs11Module

The java object wrapping criptoki library functionalities.

signatureMechanism

private CK_MECHANISM signatureMechanism

PKCS#11 identifier for the signature algorithm.

log

private java.io.PrintStream log

The PrintStream where logging messages are written.

Constructor Detail

PKCS11Signer

public PKCS11Signer(java.lang.String cryptokiLib,
            long mechanism,
            java.io.PrintStream out)
             throws java.io.IOException,
                    TokenException

Throws:

java.io.IOException

TokenException

PKCS11Signer

public PKCS11Signer(java.lang.String cryptokiLib,
            long mechanism,
            java.lang.String reader,
            java.io.PrintStream out)
             throws java.io.IOException,
                    TokenException

Throws:

java.io.IOException

TokenException

PKCS11Signer

public PKCS11Signer(java.lang.String cryptokiLib,
            java.io.PrintStream out)
             throws java.io.IOException,
                    TokenException

Throws:

java.io.IOException

TokenException

Method Detail

initializeLibrary

private void initializeLibrary()
                        throws PKCS11Exception

Initializes cryptoki library operations.

Throws:

PKCS11Exception

initializeTokenAndMechanism

private void initializeTokenAndMechanism(long mechanism)
                                  throws PKCS11Exception

Throws:

PKCS11Exception

initializeTokenInReader

private void initializeTokenInReader(java.lang.String reader)
                              throws PKCS11Exception

Throws:

PKCS11Exception

setMechanism

public void setMechanism(long mechanism,
                java.lang.Object pParameter)

setMechanism

public void setMechanism(long mechanism)

closeSession

public void closeSession()
                  throws PKCS11Exception

Closes the default PKCS#11 session.

Throws:

PKCS11Exception

closeSession

public void closeSession(long sessionHandle)
                  throws PKCS11Exception

Closes a specific PKCS#11 session.

Parameters:

sessionHandle - handle of the session to close.

Throws:

PKCS11Exception

decodeError

public static java.lang.String decodeError(int errorCode)

Error decoding function. Currently not implemented (returns 'Unknown error' everytime).

Parameters:

errorCode - id of the error.

Returns:

the decription corresponding to error code.

findSignatureKeyFromLabel

public long findSignatureKeyFromLabel(java.lang.String label)
                               throws PKCS11Exception

Returns the private key handle, on current token, corresponding to the given textual label.

Parameters:

label - the string label to search.

Returns:

the integer identifier of the private key, or -1 if no key was found.

Throws:

PKCS11Exception

findSignatureKeyFromID

public long findSignatureKeyFromID(byte[] id)
                            throws PKCS11Exception

Returns the private key handle, on current token, corresponding to the given byte[]. ID is often the byte[] version of the label.

Parameters:

id - the byte[] id to search.

Returns:

the integer identifier of the private key, or -1 if no key was found.

Throws:

PKCS11Exception

See Also:

findSignatureKeyFromLabel(String)

findSignatureKey

public long findSignatureKey()
                      throws PKCS11Exception

Returns the first private key handle found on current token.

Returns:

a private key handle, or -1 if no key is found.

Throws:

PKCS11Exception

signDataSinglePart

public byte[] signDataSinglePart(long signatureKeyHandle,
                        byte[] data)
                          throws java.io.IOException,
                                 PKCS11Exception

Sign (here means encrypting with private key) the provided data with a single operation. This is the only modality supported by the (currently fixed) RSA_PKCS mechanism.

Parameters:

signatureKeyHandle - handle of the private key to use for signing.

data - the data to sign.

Returns:

a byte[] containing signed data.

Throws:

java.io.IOException

PKCS11Exception

signDataMultiplePart

public byte[] signDataMultiplePart(long signatureKeyHandle,
                          java.io.InputStream dataStream)
                            throws java.io.IOException,
                                   PKCS11Exception

Sign (here means digesting and encrypting with private key) the provided data with a multiple-pass operation. This is the a modality supported by CKM_SHA1_RSA_PKCS, for example, that digests and ecrypts data. Note that some Infocamere card-cryptoki combinations does not supports this type of mechanisms.

Parameters:

signatureKeyHandle - handle of the private key to use for signing.

dataStream - an InputStram providing data to sign.

Returns:

a byte[] containing signed data.

Throws:

java.io.IOException

PKCS11Exception

encryptDigest

public byte[] encryptDigest(java.lang.String label,
                   byte[] digest)
                     throws PKCS11Exception,
                            java.io.IOException

Throws:

PKCS11Exception

java.io.IOException

findCertificateWithNonRepudiationCritical

public long findCertificateWithNonRepudiationCritical(long token)
                                               throws TokenException,
                                                      java.security.cert.CertificateException

Queries the a specific token for a certificate suitable for a legal value subscription. See findCertificateWithNonRepudiationCritical().

Parameters:

token - ID of the token to query for the certificate.

Returns:

the handle of the required certificate, if found; -1 otherwise.

Throws:

TokenException

java.security.cert.CertificateException

See Also:

findCertificateWithNonRepudiationCritical()

findCertificateWithNonRepudiationCritical

public long findCertificateWithNonRepudiationCritical()
                                               throws TokenException,
                                                      java.security.cert.CertificateException

Queries the current token for a certificate suitable for a legal value subscription.

According to the italian law, if you want give to the digital signature the maximum legal value (equivalent to a signature on paper), and also for the sake of interoperability, the signer certificate has to satisfy some costraints. See the official document in PDF format or this html page (only in italian, sorry) for details.

In particular, the certificate has to carry a KeyUsage extension of 'non repudiation' (OID: 2.5.29.15) marked as critical.

Returns:

the handle of the required certificate, if found; -1 otherwise.

Throws:

TokenException

java.security.cert.CertificateException

findCertificates

public long[] findCertificates()
                        throws TokenException,
                               java.security.cert.CertificateException

Trova un'array di certHandle di tutti i certificati presenti sulla carta senza che la sessione sia aperta (no password). La length dell'array corrisponde al numero dei certificati

Returns:

the handle of the required certificate, if found; -1 otherwise.

Throws:

TokenException

java.security.cert.CertificateException

isKeyUsageNonRepudiationCritical

boolean isKeyUsageNonRepudiationCritical(java.security.cert.X509Certificate javaCert)

checks Key Usage constraints of a java certificate.

Parameters:

javaCert - the certificate to check as java object.

Returns:

true if the given certificate has a KeyUsage extension of 'non repudiation' (OID: 2.5.29.15) marked as critical.

See Also:

findCertificateWithNonRepudiationCritical()

findCertificateFromID

public long findCertificateFromID(byte[] id)
                           throws PKCS11Exception

Finds a certificate matching the given byte[] id.

Parameters:

id -

Returns:

the handle of the certificate, or -1 if not found.

Throws:

PKCS11Exception

findCertificateFromLabel

public long findCertificateFromLabel(char[] label)
                              throws PKCS11Exception

Finds a certificate matching the given textual label.

Parameters:

label -

Returns:

the handle of the certificate, or -1 if not found.

Throws:

PKCS11Exception

findCertificateFromSignatureKeyHandle

public long findCertificateFromSignatureKeyHandle(long signatureKeyHandle)
                                           throws PKCS11Exception

Searches the certificate corresponding to the private key identified by the given handle; this method assumes that corresponding certificates and private keys are sharing the same byte[] IDs.

Parameters:

signatureKeyHandle - the handle of a private key.

Returns:

the handle of the certificate corrisponding to the given key.

Throws:

PKCS11Exception

findSignatureKeyFromCertificateHandle

public long findSignatureKeyFromCertificateHandle(long certHandle)
                                           throws PKCS11Exception

Searches the private key corresponding to the certificate identified by the given handle; this method assumes that corresponding certificates and private keys are sharing the same byte[] IDs.

Parameters:

certHandle - the handle of a certificate.

Returns:

the handle of the private key corrisponding to the given certificate.

Throws:

PKCS11Exception

getDEREncodedCertificateFromLabel

public byte[] getDEREncodedCertificateFromLabel(java.lang.String label)
                                         throws TokenException

Returns the DER encoded certificate corresponding to the given label, as read from the token.

Parameters:

label - the object label on the token.

Returns:

the DER encoded certificate, as byte[]

Throws:

java.io.UnsupportedEncodingException

TokenException

getDEREncodedCertificate

public byte[] getDEREncodedCertificate(long certHandle)
                                throws PKCS11Exception

Returns the DER encoded certificate identified by the given handle, as read from the token.

Parameters:

certHandle - the handleof the certificate on the token.

Returns:

the DER encoded certificate, as a byte array.

Throws:

java.io.UnsupportedEncodingException

TokenException

PKCS11Exception

getDEREncodedCertificateAndID

public byte[] getDEREncodedCertificateAndID(long certHandle,
                                   java.io.ByteArrayOutputStream id)
                                     throws PKCS11Exception,
                                            java.io.IOException

Returns the DER encoded certificate identified by the given handle, and its ID attribute.

Parameters:

certHandle - the handle of the certificate on the token, as a byte array.

id - the ID of the Certificate as a ByteArrayOutputStream.

Returns:

the DER encoded certificate, as a byte array (has to to be not Null) .

Throws:

java.io.IOException

java.io.UnsupportedEncodingException

TokenException

PKCS11Exception

getDEREncodedCertificate

public byte[] getDEREncodedCertificate(long certHandle,
                              long sessionHandle)
                                throws PKCS11Exception

Throws:

PKCS11Exception

getSlotDescription

public java.lang.String getSlotDescription(long slotID)

getCryptokiLibrary

public java.lang.String getCryptokiLibrary()

Gets the cryptoki library name.

Returns:

the current cryptoki library name.

getPkcs11

private PKCS11 getPkcs11()

Gets the java wrapper for the cryptoki.

Returns:

the java wrapper for the cryptoki.

getSession

private long getSession()

Gets the current session handle.

Returns:

the long identifying the current session.

libFinalize

public void libFinalize()
                 throws java.lang.Throwable

Finalizes PKCS#11 operations; note this NOT actually unloads the native library.

Throws:

java.lang.Throwable

login

public void login(java.lang.String pwd)
           throws PKCS11Exception

Logs in to the current session; login is usually necessary to see and use private key objects on the token. This method converts the given String as a char[] and calls login(char[]).

Parameters:

pwd - password as a String.

Throws:

PKCS11Exception

login

public void login(char[] pwd)
           throws PKCS11Exception

Logs in to the current session; login is usually necessary to see and use private key objects on the token.

Parameters:

pwd - password as a char[].

Throws:

PKCS11Exception

logout

public void logout()
            throws PKCS11Exception

Logs out the current user.

Throws:

PKCS11Exception

getModuleInfo

private void getModuleInfo()
                    throws PKCS11Exception

Gets currently loaded cryptoky description.

Throws:

PKCS11Exception

getSlotList

private long[] getSlotList()
                    throws PKCS11Exception

Gets current reader infos.

Throws:

PKCS11Exception

getTokenList

public long[] getTokenList()

Lists currently inserted tokens and relative infos.

Throws:

PKCS11Exception

getTokens

public long[] getTokens()
                 throws PKCS11Exception

Lists currently inserted tokens. Questo metodo è public e utilizzato in ReadCertsTask

Throws:

PKCS11Exception

getTokenDescription

public java.lang.String getTokenDescription()
                                     throws PKCS11Exception

Throws:

PKCS11Exception

getMechanismInfo

public void getMechanismInfo()
                      throws PKCS11Exception

Gets informations on cryptographic operations supported by the tokens.

Throws:

PKCS11Exception

findSuitableToken

public long findSuitableToken(long mechanismCode)
                       throws PKCS11Exception

Throws:

PKCS11Exception

findTokensSupportingMechanism

public java.util.ArrayList findTokensSupportingMechanism(long mechanismCode)
                                                  throws PKCS11Exception

Throws:

PKCS11Exception

getTokenSupportingMechanism

public long getTokenSupportingMechanism(long mechanismCode)
                                 throws PKCS11Exception

Queries if there is a token that supporting a given cryptographic operation.

Parameters:

mechanismCode - the ID of the required mechanism.

Returns:

the handle if the token supporting the given mechanism, -1 otherwise.

Throws:

PKCS11Exception

isMechanismSupportedByToken

public boolean isMechanismSupportedByToken(long mechanismCode,
                                  long tokenID)
                                    throws PKCS11Exception

Tells if a given token supports a given cryptographic operation. Also lists all supported mechanisms.

Parameters:

mechanismCode - the mechanism ID.

tokenID - the token handla.

Returns:

true if the token supports the mechanism.

Throws:

PKCS11Exception

openSession

public long openSession(long aTokenHandle)
                 throws TokenException

Opens a session on a specific token.

Parameters:

aTokenHandle - the token ID.

Throws:

TokenException

openSession

public void openSession()
                 throws TokenException

Opens a session on the default token.

Throws:

TokenException

openSession

public void openSession(char[] password)
                 throws TokenException,
                        PKCS11Exception

Opens a session on the token, logging in the user.

Throws:

TokenException

PKCS11Exception

setCryptokiLibrary

public void setCryptokiLibrary(java.lang.String newCryptokiLibrary)

Sets the cryptoky library

Parameters:

newCryptokiLibrary - the cryptoki name.

setSession

private void setSession(long newSession)

Sets the session handle.

Parameters:

newSession -

getTokenHandle

public long getTokenHandle()

Gets the current token.

Returns:

Returns the token handle

setTokenHandle

public void setTokenHandle(long token)

Sets the current token handle.

Parameters:

token - the token handle to set.

isLibFinalized

public boolean isLibFinalized()

Is cryptokiLibrary finalized (unlinked) ?