Click or drag to resize
Pdftools logo

Session Class

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 Load(String).
  • Get the appropriate cryptographic device from the module's Devices. If it can be assumed that there is only a single device available, the GetSingle can be used.
  • Create a session to the device using CreateSession(String).

Inheritance Hierarchy
SystemObject
  PdfTools.InternalNativeBase
    PdfTools.InternalNativeObject
      PdfTools.Crypto.ProvidersProvider
        PdfTools.Crypto.Providers.Pkcs11Session

Namespace: PdfTools.Crypto.Providers.Pkcs11
Assembly: PdfTools (in PdfTools.dll) Version: 1.1.0.0
Syntax
C#
public class Session : Provider

The Session type exposes the following members.

Properties
 NameDescription
Public propertyCertificates

The cerfificates of the device

The certificates available in this device. Note that some certificates or their private keys (see HasPrivateKey) might only be visible after Login(String).
Public propertyTimestampUrl

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

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 Proxy), make sure the following MIME types are supported:

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

Top
Methods
 NameDescription
Public methodCreateSignature

Create a signature configuration based on signing certificate

Public methodCreateSignatureFromKeyId

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 AddCertificate(Stream).

Public methodCreateSignatureFromKeyLabel

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 AddCertificate(Stream).

Public methodCreateSignatureFromName

Create a signature configuration based on certificate name

Public methodCreateTimestamp

Create a time-stamp configuration

Note that to create time-stamps, the TimestampUrl must be set.
Public methodDispose

Close the object

Release all resources associated with the object.
(Inherited from Provider)
Public methodEquals
(Inherited from NativeObject)
Public methodGetHashCode
(Inherited from NativeObject)
Public methodLogin

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.

Top
See Also