Integration via PKCS#11

Introduction

PKCS#11(Public Key Cryptography Standards number 11) defines an API also called Cryptoki(Cryptographic Token Interface Standard) which is used to manage key lifecycles and perform cryptographic operations within a device.

These standardized APIs allow applications to use encryption services independently of device vendors.

PKCS#11 Dinamo allows integration between an application using the standard and the HSM. This Cryptoki is built on the native HSM API and provides the algorithms present in the HSM.

As of version 3.1.0 of the HSM client suite and version 3.9.0.0 of the firmware, the implementation's architecture has been updated.

Attention

The version of the PKCS#11 library and the HSM firmware must be compatible in order to migrate to this new version.

If you have client versions older than 3.1.0, 2.0.0.0 of the PKCS#11 library Dinamo and/or HSM firmware version Dinamo older than 3.9.0.0 and want to migrate to the new version, please contact your supplier's support.

Overview

Initially, with the increase in the use of portable encryption devices (SmartCards, Tokens, PCMCIA...) the need was identified for a standard encryption API(Application Programming Interface) that would allow interoperability between applications and the various devices and manufacturers.

PKCS#11 has come to solve this problem in a simplified, portable way and with high-level APIs, defining basic token interfaces and behaviors.

Over time PKCS#11 has been widely used and has become the market standard for devices that store and perform cryptographic operations, and has even been used with HSMs.

The objectives of PKCS#11 are:

A simple view of cryptographic objects.
Technology independence. Being able to use any device.
Resource sharing. Multiple applications can use multiple devices. Allows the use of different cryptographic tokens without changing the application code.
Common logical view of the device, called "Cryptographic Token".
Portability. Works on several operating systems.
Define object types and their attributes.
Define cryptographic operations.

PKCS#11 Cryptoki API information:

Language: ANSI C
API name: Cryptoki, PKCS#11
Maintainer: OASIS
Format: Library (can be dynamic or static)
Headers: pkcs11.h includes the files pkcs11t.h e pkcs11f.h

General Model

Steps for an application to perform a cryptographic operation in the PKCS#11 model:

Load a Cryptoki library (a dll on windows or a so on linux);
Make a call to one of its APIs;
This call goes through a Slot;
And finally you reach the token.

---
title: Modelo Geral Cryptoki
---

%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%

flowchart TD

    classDef red_s stroke:#f00
    App1[Aplicação 1]
    Appk[Aplicação k]
    p11.1[Biblioteca PKCS#11<br>#40;CryptoKi#41;]
    p11.2[Biblioteca PKCS#11<br>#40;CryptoKi#41;]
    sync[Contenção/Sincronização]
    slot1[Slot 1]
    slotk[Slot k]
    token1[Token 1<br>#40;Device 1#41;]
    tokenk[Token k<br>#40;Device k#41;]

    App1 --> p11.1
    Appk --> p11.2
    p11.1 --> sync
    p11.2 --> sync
    sync --> slot1
    sync --> slotk
    slot1 --> token1
    slotk --> tokenk

Slot corresponds to a physical reader (e.g. a smart card reader). The token corresponds to a device (e.g. a smart card).

Slots and tokens are logical representations.

The PKCS#11 Cryptoki library is defined in C. To access Cryptoki from another language (Java, .Net, etc.) you need to create an interface between the languages. There are several PKCS#11 integrations on the market in different languages, they are easy to find and some of them are even native.

Note

O Dinamo There is only one Slot which is number 1.

Logical view of the token

Cryptoki divides objects into 3 classes:

Data
Certificates
Keys

The keys can be:

Public
Private
Secret

---
title: Hierarquia de Objetos
---

%%{ init: { 'flowchart': { 'curve': 'bumpY' } } }%%

flowchart TD

    classDef red_s stroke:#f00
    obj[Objeto]
    data[Dado]
    key[Chave]
    cert[Certificado]
    pubk[Chave Pública]
    privk[Chave Privada]
    seck[Chave Secreta]

    obj --> data
    obj --> key
    obj --> cert
    key --> pubk
    key --> privk
    key --> seck

    linkStyle 0,1,2,3,4,5 stroke-width:1px;

Objects can also be divided:

By lifetime
Token objects: are persistent. They remain in the token even if the session is closed;
Session objects: these are temporary. The object ceases to exist when the session that created it is closed.
By access level
- Private objects: can only be accessed if the user is authenticated;
- Public objects: can be accessed even with an unauthenticated session.

Dinamo does not allow access to an object unless the user is properly authenticated. All objects are architecturally private.

Objects also have specific attributes according to each type, such as the modulus or exponent of an RSA key.

Cryptoki implementations are not obliged to implement all objects and mechanisms. It is expected that there will be a logical adaptation of the Cryptoki implementation to suit the particularities of the definitions in PKCS#11.

Users

PKCS#11 defines 2 types of users:

Security Officer - performs administrative operations, such as initializing the token, setting a normal user's PIN and possibly manipulating public objects.
Ordinary user - has access to private objects (only when the user is authenticated).

At Dinamo , operators and ordinary users can create and use private objects. There is no distinction between types.

The user that will be used by Criptoki is defined via configuration or alternatively via a password parameter.

The token initialization operation is not supported via Criptoki and can therefore be disregarded. In HSM, initialization is done via the local console.

PIN setting is not supported via Cryptoki and can therefore be disregarded. The PIN is only created/changed when the user is created or when the user changes it.

Threads

Attention: Session-Thread Affinity

HSM sessions have session-thread affinity. This means that the same session cannot be used by several threads at the same time.

Sessions can only perform one operation at a time. This means that you cannot make multiple simultaneous calls to Criptoki using the same session. It is recommended to open one session per thread or to ensure that the session is used to perform only one operation at a time.

Cryptoki Dinamo uses its own locking mechanism.

Session

Sessions can be Read-Only (R/O) or Read-Write (R/W). Read-only refers to token objects.

Read-Only: you can only read token objects.
Read-Write: you can create, read, write and destroy session and token objects.

In Dinamo there is no distinction between Read-Only and Read-Write sessions. The user always has full permission over their objects.

Sessions can be authenticated or unauthenticated.

Authenticated: The user has permission over public and private objects.
Unauthenticated: The user only has permission on public objects.

On Dinamo you can only see the user's own objects, and they must be authenticated.

Additional Details

Private keys and secret keys can be marked as sensitive or unextractable:

sensitive: the key can be exported, but only in encrypted form.
unextractable: the key cannot be exported in any way.

Dinamo only has the option of the key being exportable or not, regardless of the form of export. The PKCS#11 extractable and sensitive options are related to the option of exportable keys in HSM. For example, a sensitive key cannot be exported even in encrypted form.

PKCS#11 HSM Dinamo

According to the PKCS#11 definitions, a Cryptoki implementation is not expected to support all options. Criptoki from Dinamo will provide the operations that the HSM offers and that are supported by the PKCS#11 specification.

The mechanisms supported by HSM can be seen here.

Some implementation details Dinamo are summarized below.

Compatible with version v2.40 of PKCS#11;
Allows the use of usr:password@ip instead of the password, if the option is enabled.
It only has one Slot(number 1).
Fixed token label as "Dinamo HSM".
Allows access to objects only by authenticated sessions.
Operators and ordinary users can create and use private objects. There is no distinction between types.
Cryptoki Dinamo uses its own locking .
Token initialization and PIN setting can be disregarded. These are done via settings on the device itself.
The user that will be used by Criptoki is defined via configuration or alternatively via a password parameter.
The user always has full permission over their objects. There is no distinction between Read-Only and Read-Write sessions.
There is no option for unauthenticated sessions.
See the list of possible Criptoki Dinamo configurations for more details.
Keys only have the option of being exportable or not, regardless of how they are exported. The extractable and sensitive options are related to the exportable keys option. For example, a sensitive key cannot be exported even in encrypted form.