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

  • Method Details

    • login

      public void login(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
      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:
      IllegalArgumentException - If the certificate is not a valid signing certificate.
      IllegalArgumentException - If the certificate has expired.
      IllegalArgumentException - if certificate is null

    • createSignatureFromName

      public SignatureConfiguration createSignatureFromName(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()
      IllegalArgumentException - If the certificate is not a valid signing certificate
      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
      IllegalArgumentException - If the certificate is not a valid signing certificate
      IllegalArgumentException - If the key specification matches more than one key
      IllegalArgumentException - if id is null
      IllegalArgumentException - if certificate is null

    • createSignatureFromKeyLabel

      public SignatureConfiguration createSignatureFromKeyLabel(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
      IllegalArgumentException - If the certificate is not a valid signing certificate
      IllegalArgumentException - If the key specification matches more than one key
      IllegalArgumentException - if label is null
      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 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(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).