PKCS11 Objects

Introduction

The PKCS #11 standard defines a platform-independent API to cryptographic tokens, such as hardware security modules (HSM), smart cards, and names the API itself "Cryptoki" (from "cryptographic token interface" and pronounced as "crypto-key" - but "PKCS #11" is often used to refer to the API as well as the standard that defines it). The API defines most commonly used cryptographic object types (RSAX.509 keys, DES/Triple DES Certificates/keys, etc.) and all the functions needed to use, create/generate, modify and delete those objects. This container relies on a PKCS#11 a library which handles the communication with the token/card. This can be a vendor specific library or an opensource one, please select the correct one depending on the type of token/card you are using.

Interface Summary

The Abstract PKCS #11 smartcard interface is summarised in the following snippet:

export interface AbstractPkcs11 {
    certificates(slotId: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: Pkcs11ObjectCertificatesResponse) => void): Promise<Pkcs11ObjectCertificatesResponse>;
    signData(data: Pkcs11SignData, callback?: (error: T1CLibException, data: Pkcs11ObjectSignResponse) => void): Promise<Pkcs11ObjectSignResponse>;
    slots(callback?: (error: T1CLibException, data: Pkcs11ObjectSlotsResponse) => void): Promise<Pkcs11ObjectSlotsResponse>;
    slotsWithTokenPresent(callback?: (error: T1CLibException, data: Pkcs11ObjectSlotsResponse) => void): Promise<Pkcs11ObjectSlotsResponse>;
    token(slotId: string, callback?: (error: T1CLibException, data: Pkcs11ObjectTokenResponse) => void): Promise<Pkcs11ObjectTokenResponse>;
}

Pkcs11 object models

export class Pkcs11ObjectInfoResponse extends DataObjectResponse {
    constructor(public data: Pkcs11Info, public success: boolean) {
        super(data, success);
    }
}

export class Pkcs11ObjectSign {
    constructor(public data: string) {
    }
}

export class Pkcs11ObjectSignResponse {
    constructor(public data: Pkcs11ObjectSign, public success: boolean) {
    }
}

export class Pkcs11ObjectSlots {
    constructor(public slots: Pkcs11Slot[]) {
    }
}

export class Pkcs11ObjectSlotsResponse {
    constructor(public data: Pkcs11ObjectSlots, public success: boolean) {
    }
}


export class Pkcs11ObjectCertificates {
    constructor(public certificates: Pkcs11ObjectCertificate[]) {}
}


export class Pkcs11ObjectCertificate {
    constructor(public id: string, public certificate: string, public parsed?: Certificate) {}
}

export class Pkcs11ObjectCertificatesResponse {
    constructor(public data: Pkcs11ObjectCertificates, public success: boolean) {
    }
}

export class Pkcs11SignData {
    constructor(public slotId: string,
                public certificateId: string,
                public algorithm: string,
                public data: string,
                public pin?: string,
                public osDialog?: boolean) {}
}

export class Pkcs11ObjectTokenResponse {
    constructor(public data: Pkcs11TokenInfo, public success: boolean) {
    }
}

export class Pkcs11SetConfigResponse {
    constructor(public data: string, public success: boolean) {
    }
}

export class Pkcs11Slots {
    constructor(public slots: Pkcs11Slot[]) {
    }
}

export class Pkcs11Slot {
    constructor(public slot: number,
                public description: string) {
    }
}

export class Pkcs11TokenInfo {
    constructor(public slot: string,
                public label: string,
                public manufacturerId: string,
                public model: string,
                public serialNumber: string,
                public flags: string,
                public ulMaxSessionCount: number,
                public ulSessionCount: number,
                public ulMaxRwSessionCount: number,
                public ulMaxPinLen: number,
                public ulMinPinLen: number,
                public ulTotalPublicMemory: number,
                public ulFreePublicMemory: number,
                public ulTotalPrivateMemory: number,
                public ulFreePrivateMemory: number,
                public hardwareVersion: string,
                public firmwareVersion: string) {
    }
}

Get the PKCS #11 container object

For more information on how to configure the JS client library see Configuration.

Depending on the OS you need to provide a valid location to the desired PKCS11 library to be used.

Call a function for the PKCS #11 container:

Reading data

Slots

This methods returns the available slots on the system.

An example response:

Slots with tokens present

This method is similar the the slots endpoint but only returns a list of slots where a token is present.

An example response:

Token

This methods returns the token information for a slot.

An example response:

Certificates

This methods allows you to retrieve the certificates from the PKCS #11 token.

Response:

Signing data

To successfully sign data, we need the following parameters:

  • Slot ID of the token to use

  • Certificate ID of the signing certificate

  • PIN code

  • Hashed data to sign

  • Hashing algorithm used

The slot id can be found using either a call to slots, slotsWithTokenPresent. Once the slot id is found, the certificates can be retrieved with a call to certificates. This then returns the certificate id. Now we can combine this with the PIN code and hashed data + hashing algorithm (SHA1, SHA256, SHA384, SHA512) to create the final signData call:

signData call

Returns signed data for provided input data.

An example response:

Error Handling

Error Object

The functions specified are asynchronous and always need a callback function. The callback function will reply with a data object in case of success, or with an error object in case of an error. An example callback:

The error object returned:

PreviousPKCS11

Last updated

Was this helpful?