Package com.pdftools.crypto.providers.pkcs11

Class Session

java.lang.Object

com.pdftools.internal.NativeBase

com.pdftools.internal.NativeObject

com.pdftools.crypto.providers.Provider

com.pdftools.crypto.providers.pkcs11.Session

All Implemented Interfaces:

java.lang.AutoCloseable

public class Session
extends Provider

A session to a cryptographic device (HSM, USB token, etc.) to perform cryptographic operations

The session can be used to create signature configuration to sign documents.

To acquire a session, the following steps must be performed:

• Load the PKCS#11 driver module using Module.load(java.lang.String).
• Get the appropriate cryptographic device from the module's Module.getDevices(). If it can be assumed that there is only a single device available, the DeviceList.getSingle() can be used.
• Create a session to the device using Device.createSession(java.lang.String).

Method Summary

Modifier and Type	Method	Description
SignatureConfiguration	createSignature(Certificate certificate)	Create a signature configuration based on signing certificate
SignatureConfiguration	createSignatureFromKeyId(byte[] id, Stream certificate)	Create a signature configuration based on the private key's ID and an external certificate
SignatureConfiguration	createSignatureFromKeyLabel(java.lang.String label, Stream certificate)	Create a signature configuration based on the private key's label (name) and an external certificate
SignatureConfiguration	createSignatureFromName(java.lang.String name)	Create a signature configuration based on certificate name
TimestampConfiguration	createTimestamp()	Create a time-stamp configuration
CertificateList	getCertificates()	The cerfificates of the device (Getter)
java.net.URI	getTimestampUrl()	The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Getter)
void	login(java.lang.String password)	Log in user into the cryptographic device
void	setTimestampUrl(java.net.URI value)	The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Setter)

Methods inherited from class com.pdftools.crypto.providers.Provider

close

Methods inherited from class com.pdftools.internal.NativeObject

equals, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

login

public void login(java.lang.String password)
           throws PasswordException,
                  PermissionException

Log in user into the cryptographic device

Login is typically required to enable cryptographic operations. Furthermore, some of the device's objects such as certificates or private keys might only be visible when logged in.

Note that many devices are locked after a number of failed login attempts. Therefore, it is crucial to not retry this method using the same password after a failed attempt.

Parameters:

password - The user's password

Throws:

PasswordException - If the password is not correct

PermissionException - If the password has been locked or is expired

java.lang.UnsupportedOperationException - If the user has already logged in

createSignature

public SignatureConfiguration createSignature(Certificate certificate)

Create a signature configuration based on signing certificate

Parameters:

certificate - The signing certificate from getCertificates()

Returns:

Throws:

java.lang.IllegalArgumentException - If the certificate is not a valid signing certificate.

java.lang.IllegalArgumentException - If the certificate has expired.

java.lang.IllegalArgumentException - if certificate is null

createSignatureFromName

public SignatureConfiguration createSignatureFromName(java.lang.String name)
                                               throws NotFoundException

Create a signature configuration based on certificate name

Parameters:

name - The name of the signing certificate (pdftools.crypto.providers.Certificate.getName)

Returns:

Throws:

NotFoundException - If the certificate cannot be found in getCertificates()

java.lang.IllegalArgumentException - If the certificate is not a valid signing certificate

java.lang.IllegalArgumentException - if name is null

createSignatureFromKeyId

public SignatureConfiguration createSignatureFromKeyId(byte[] id,
                                                       Stream certificate)
                                                throws NotFoundException

Create a signature configuration based on the private key's ID and an external certificate

Create a signature configuration where only the private key is contained in the PKCS#11 device and the signing certificate is provided externally. This is intended for PKCS#11 devices that can only store private keys, e.g. the Google Cloud Key Management (KMS).

The private key object is identified using its ID, i.e. the CKA_ID object attribute in the PKCS#11 store.

The certificates of the trust chain should be added using SignatureConfiguration.addCertificate(com.pdftools.sys.Stream).

Parameters:

id - The ID of the private key object in the PKCS#11 store

certificate - The signing certificate in either PEM (.pem, ASCII text) or DER (.cer, binary) form

Returns:

Throws:

NotFoundException - If the private key cannot be found in the PKCS#11 store

java.lang.IllegalArgumentException - If the certificate is not a valid signing certificate

java.lang.IllegalArgumentException - If the key specification matches more than one key

java.lang.IllegalArgumentException - if id is null

java.lang.IllegalArgumentException - if certificate is null

createSignatureFromKeyLabel

public SignatureConfiguration createSignatureFromKeyLabel(java.lang.String label,
                                                          Stream certificate)
                                                   throws NotFoundException

Create a signature configuration based on the private key's label (name) and an external certificate

Create a signature configuration where only the private key is contained in the PKCS#11 device and the signing certificate is provided externally. This is intended for PKCS#11 devices that can only store private keys, e.g. the Google Cloud Key Management (KMS).

The private key object is identified using its label, i.e. the CKA_LABEL object attribute in the PKCS#11 store.

The certificates of the trust chain should be added using SignatureConfiguration.addCertificate(com.pdftools.sys.Stream).

Parameters:

label - The label of the private key object in the PKCS#11 store

certificate - The signing certificate in either PEM (.pem, ASCII text) or DER (.cer, binary) form

Returns:

Throws:

NotFoundException - If the private key cannot be found in the PKCS#11 store

java.lang.IllegalArgumentException - If the certificate is not a valid signing certificate

java.lang.IllegalArgumentException - If the key specification matches more than one key

java.lang.IllegalArgumentException - if label is null

java.lang.IllegalArgumentException - if certificate is null

createTimestamp

public TimestampConfiguration createTimestamp()

Create a time-stamp configuration

Note that to create time-stamps, the getTimestampUrl() must be set.

Returns:

getTimestampUrl

public java.net.URI getTimestampUrl()

The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Getter)

The TSA must support the time-stamp protocol as defined in RFC 3161.

The property’s value must be a URL with the following elements:

http[s]://[‹user›[:‹password›]@]‹host›[:‹port›][/‹resource›]

Where:

• http/https: Protocol for connection to TSA.
• ‹user›:‹password› (optional): Credentials for connection to TSA (basic authorization).
• ‹host›: Hostname of TSA.
• ‹port›: Port for connection to TSA.
• ‹resource›: The resource.

Applying a time-stamp requires an online connection to a time server; the firewall must be configured accordingly. If a web proxy is used (see pdftools.Sdk.getProxy), make sure the following MIME types are supported:

• application/timestamp-query
• application/timestamp-reply

setTimestampUrl

public void setTimestampUrl(java.net.URI value)

The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Setter)

The TSA must support the time-stamp protocol as defined in RFC 3161.

The property’s value must be a URL with the following elements:

http[s]://[‹user›[:‹password›]@]‹host›[:‹port›][/‹resource›]

Where:

• http/https: Protocol for connection to TSA.
• ‹user›:‹password› (optional): Credentials for connection to TSA (basic authorization).
• ‹host›: Hostname of TSA.
• ‹port›: Port for connection to TSA.
• ‹resource›: The resource.

Applying a time-stamp requires an online connection to a time server; the firewall must be configured accordingly. If a web proxy is used (see pdftools.Sdk.getProxy), make sure the following MIME types are supported:

• application/timestamp-query
• application/timestamp-reply

getCertificates

public CertificateList getCertificates()

The cerfificates of the device (Getter)

The certificates available in this device. Note that some certificates or their private keys (see pdftools.crypto.providers.Certificate.getHasPrivateKey) might only be visible after login(java.lang.String).