YubiKey
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.
The Abstract PKCS #11 smartcard interface is summarized in the following snippet:
interface AbstractPkcs11{
certificates(slotId: number,
options?: Options,
callback?: (error: RestException, data: SafeNetCertificatesResponse) => void): Promise<SafeNetCertificatesResponse>;
info(callback?: (error: RestException, data: InfoResponse) => void): Promise<InfoResponse>;
signData(data: SafeNetSignData, callback?: (error: RestException, data: DataResponse) => void): Promise<DataResponse>;
slots(callback?: (error: RestException, data: SlotsResponse) => void): Promise<SlotsResponse>;
slotsWithTokenPresent(callback?: (error: RestException, data: SlotsResponse) => void): Promise<SlotsResponse>;
token(callback?: (error: RestException, data: TokensResponse) => void): Promise<TokensResponse>;
verifySignedData(data: Pkcs11VerifySignedData,
callback?: (error: RestException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
}
Each interface will be covered on this wiki, accompanied with example code and response objects.
For more information on how to configure the T1C-JS client library see Client Configuration.
To set the locations of the PCKS#11 library, pass a
ModuleConfig object when initializing the client:var moduleConfig = {
"linux": "/usr/local/lib/libeTPkcs11.so",
"mac": "/usr/local/lib/libeTPkcs11.dylib",
"win": "C:\\Windows\\System32\\eTPKCS11.dll"
}
var config = new GCLConfig("ds uri", "apikey", moduleConfig);
GCLLib.GCLClient.initialize(config, function(err, gclClient) {
// gclClient ready to use
});
Then grab a reference to the pkcs11 container:
var pkcs11 = gclClient.pkcs11();
Call a function for the PKCS #11 container:
function callback(err,data) {
if(err){console.log("Error:",JSON.stringify(err, null, ' '));}
else {console.log(JSON.stringify(data, null, ' '));}
}
gclClient.pkcs11(moduleConfig).certificates(callback);
This methods returns more information about the PKCS #11 library you are using.
gclClient.pkcs11(moduleConfig).info(callback);
An example response:
{
"data":
{
"cryptoki_version": "2.20",
"manufacturer_id": "SafeNet, Inc.",
"flags": 7,
"library_description": "eToken PKCS#11",
"library_version": "9.1"
}
"success": true
}
This methods returns the available slots on the system.
gclClient.pkcs11(moduleConfig).slots(callback);
An example response:
{
"data":
[
{
"slot_id": 0,
"description": "eToken 5100",
"flags": 7,
"hardware_version": "2.0",
"firmware_version": "0.0"
},
{
"slot_id": 1,
"description": "",
"flags": 2,
"hardware_version": "2.0",
"firmware_version": "0.0"
}
]
"success": true
}
The flags value gives more information about the slot, possible values are
Value | Description |
0 | Empty |
1 | Token present |
2 | Removable device |
3 | Token present + removable device |
4 | Hardware slot |
5 | Token present + hardware slot |
6 | Removable device + hardware slot |
7 | Token present + removable device + hardware slot |
32 | Unknown |
This method is similar the the slots endpoint but only returns a list of slots where a token is present.
gclClient.pkcs11(moduleConfig).slotsWithTokenPresent(callback);
An example response:
{
"data":
[
{
"slot_id": 0,
"description": "eToken 5100",
"flags": 7,
"hardware_version": "2.0",
"firmware_version": "0.0"
}
]
"success": true
}
This methods returns the token information for a slot.
gclClient.pkcs11(moduleConfig).token(slot_id, callback);
An example response:
{
"data":
{
"slot_id": 1,
"label": "Token Label",
"manufacturer_id": "Gemalto",
"model": "Safenet Token e5100",
"serial_number": "1234567890",
"flags": 7,
"max_session_count": 10,
"session_count": 1,
"max_rw_session_count": 5,
"rw_session_count": 1,
"max_pin_length": 20,
"min_pin_length": 8,
"total_public_memory": 10000,
"free_public_memory": 5000,
"total_private_memory": 1000,
"free_private_memory": 50,
"hardware_version": "1",
"firmware_version": "1"
},
"success": true
}
This methods allows you to retrieve the certificates from the PKCS #11 token.
// retrieve certificates for token in slot_id 0
gclClient.pkcs11(moduleConfig).certificates(0, { parseCerts: false }, callback);
An example callback:
function callback(err,data) {
if(err) {
console.log("Error:",JSON.stringify(err, null, ' '));
}
else {
console.log(JSON.stringify(data, null, ' '));
}
}
Response:
{
"data": [
{
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"id": "E8CE05618E79A79825722AE067EC0029851D860D"
},
{
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"id": "9F8F1CD68867526B1DF919832219B217282D2B0B"
}
],
"success": true
}
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:Returns signed data for provided input data.
var signDataPayload = {
slot_id: 1,
cert_id: "9F8F1CD68867526B1DF919832219B217282D2B0B",
pin: "thepincodeforthetoken",
data: "hashed data"
algorithm_reference: "sha256"
}
gclClient.pkcs11(moduleConfig).signData(signDataPayload, callback);
An example response:
{
"data": "L3BWs7lvoajPg5tC9GEmlSMdXMcDkNDUVVvt+KFqbJbXkJdI3DGoM3IOeXLaeTCxKmJ33/QQApL1nEAMuHY38V41czyswfSdpnqeex3EisXKkiYHeNzt9AXeoxDtsWbGkejKqru6X4xzAy/1SnccjZ2BQB/uUwyfyyweFjbZAGCLfTzWraCxG0ud2c8itsjmsBgXSuGjLqxKIJXbtuX22gd0nc4LeZLA91sxaoNFBCEVlOgJ/oJncFylf6T/Tz9R4VOA9kSf6NB1tAMsFEsihgjZafu/rzlrOfzZw4YY/T32LKY4Y2zNnDhJAucqflZjopGadDvkkSmTvxxEJuE+Bw==",
"success": true
}
This call can be used to verify if the signed data is correct. The request is similar to
signData, but we also pass in the signed hash:var verifyDataPayload = {
slot_id: 1,
cert_id: "9F8F1CD68867526B1DF919832219B217282D2B0B",
pin: "thepincodeforthetoken",
data: "hashed data"
algorithm_reference: "sha256",
signature: "signed hash"
}
gclClient.pkcs11(moduleConfig).verifySignedData(verifyDataPayload, callback);
An example response:
{
"data": true,
"success": true
}
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:
function callback(err,data) {
if(err){
console.log("Error:",JSON.stringify(err, null, ' '));
}
else {
console.log(JSON.stringify(data, null, ' '));
}
}
The error object returned:
{
success: false,
description: "some error description",
code: "some error code"
}
Last modified 4yr ago