Idemia Cosmo One v8.2

Sample code uses ES6 language features such as arrow functions and promises. For compatibility with IE11, code written with these features must be either transpiled using tools like Babel or refactored accordingly using callbacks.

Introduction

The ID-One Cosmo V8-n is part of the Idemia IAS ECC family of cryptographic modules called ID-One Cosmo V8. Modules within this family share the same functionalities and the description of the ID-One Cosmo V8 applies to all versions including the “-n” subject to this validation. This document describes the functionality provided by the Idemia IAS ECC ID-One smartcard - which is a PKI container - on the T1C-GCL (Generic Connector Library) implemented version:

• ID-One Cosmo V8-n; FIPS 140-2 Security Policy

Interface

export interface AbstractIdemia {
    allCerts(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsResponse) => void): Promise<TokenAllCertsResponse>;
    tokenData(callback?: (error: T1CLibException, data: TokenInfoResponse) => void): Promise<TokenInfoResponse>;
    rootCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    authenticationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    nonRepudiationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    encryptionCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    issuerCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>

    allCertsExtended(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
    rootCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
    authenticationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
    nonRepudiationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
    encryptionCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
    issuerCertificateExtended(parseCerts?: boolean,  callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;

    validateSignature(body: TokenValidateSignatureRequest, callback?: (error: T1CLibException, data: TokenValidateSignatureResponse) => void): Promise<TokenValidateSignatureResponse>;

    verifyPin(body: TokenVerifyPinData, callback?: (error: T1CLibException, data: TokenVerifyPinResponse) => void): Promise<TokenVerifyPinResponse>;
    authenticate(body: TokenAuthenticateOrSignData, callback?: (error: T1CLibException, data: TokenAuthenticateResponse) => void): Promise<TokenAuthenticateResponse>;
    sign(body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
    signRaw(body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
    allAlgoRefs(callback?: (error: T1CLibException, data: TokenAlgorithmReferencesResponse) => void): Promise<TokenAlgorithmReferencesResponse>
    resetBulkPin(callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
}

Models

All model information can be found in the Token typings model page

Examples

Create the Idemia module

T1cSdk.initialize(config).then(res => {
    const idemia = res.client.idemia(readerId);
}, err => {
    console.error(error)
});

When initialisation is finished you can continue using the aventra object to execute the functions below.

Token info

You can fetch the token information via the function. this will give all the information of the token you need according to the PKCS11 specifications

module.tokenData().then(res => {
    // see response below
})

{
    "success": true,
    "data": {
        "info": {
            "slot": "string",
            "label": "string",
            "manufacturerId": "string",
            "model": "string",
            "serialNumber": "string",
            "flags": {
                "isRandomNumberGenerator": "boolean",
                "isWriteProtected": "boolean",
                "isLoginRequired": "boolean",
                "isUserPinInitialized": "boolean",
                "isRestoreKeyNotNeeded": "boolean",
                "isClockOnToken": "boolean",
                "isProtectedAuthenticationPath": "boolean",
                "isDualCryptoOperations": "boolean",
                "isTokenInitialized": "boolean",
                "isSecondaryAuthentication": "boolean",
                "isUserPinCountLow": "boolean",
                "isUserPinFinalTry": "boolean",
                "isUserPinLocked": "boolean",
                "isUserPinToBeChanged": "boolean",
                "isSoPinCountLow": "boolean",
                "isSoPinFinalTry": "boolean",
                "isSoPinLocked": "boolean",
                "isSoPinToBeChanged": "boolean"
            },
            "mechanisms": [
                {
                    "mechanism": "string",
                    "flags": {
                        "isHardware": "boolean",
                        "isEncrypt": "boolean",
                        "isDecrypt": "boolean",
                        "isDigest": "boolean",
                        "isSign": "boolean",
                        "isSignRecover": "boolean",
                        "isVerify": "boolean",
                        "isVerifyRecover": "boolean",
                        "isGenerate": "boolean",
                        "isGenerateKeyPair": "boolean",
                        "isWrap": "boolean",
                        "isUnwrap": "boolean",
                        "isExtension": "boolean",
                        "isEcFP": "boolean",
                        "isEcNamedcurve": "boolean",
                        "isEcUncompress": "boolean",
                        "isEcCompress": "boolean"
                    },
                    "ulMinKeySize": "number",
                    "ulMaxKeySize": "number"
                }
            ],
            "ulMaxSessionCount": "number",
            "ulSessionCount": "number",
            "ulMaxRwSessionCount": "number",
            "ulMaxPinLen": "number",
            "ulMinPinLen": "number",
            "ulTotalPubLicMemory": "number",
            "ulFreePubMemory": "number",
            "ulTotalPrivateMemory": "number",
            "ulFreePrivateMemory": "number",
            "hardwareVersion": "string",
            "firmwareVersion": "string"
        },
        "infoType": "TokenInfoType"
    }
}



//ENUM
TokenInfoType {
    Token,
    PKCS11,
    File,
    Payment,
    HSM,
    Vault,
    Wallet,
}

All certificate filters

Extended certificates

You can also fetch the extended versions of the certificates via the functions

allCertsExtended(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
rootCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
authenticationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
nonRepudiationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
encryptionCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
issuerCertificateExtended(parseCerts?: boolean,  callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;

this has the capabilities to return multiple certificates if the token has multiple of this type.

for a single certificate the response looks like:

{
    "success" : true
    "data" : {
        "certificates": [{
            "certificate"?: string,
            "certificateType"?: string,
            "id"?: string,
            "subject"?: string,
            "issuer"?: string,
            "serialNumber"?: string,
            "url"?: string,
            "hashSubPubKey"?: string,
            "hashIssPubKey"?: string,
            "exponent"?: string,
            "remainder"?: string,
            "parsedCertificate"?: Certificate
        }]
    }
}

the allCertsExtended returns the following, with the contents of the certificates as the one you can see above;

{
    "success" : true
    "data" : {
        "rootCertificate": {
            "certificates": [...]
        },
        "authenticationCertificate": {
            "certificates": [...]
        },
        "nonRepudiationCertificate": {
            "certificates": [...]
        },
        "encryptionCertificates": {
            "certificates": [...]
        },
        "issuerCertificates": {
            "certificates": [...]
        }
   }
}

idemia.allCertFilters().then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: ['rootCertificate', 'authenticationCertificate', 'encryptionCertificate', 'nonRepudiationCertificate', 'issuerCertificate']
}

all Key references

idemia.allKeyRefs().then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: ['authenticate', 'sign', 'encrypt']
}

all Certificates

When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

const filter = ['rootCertificate', 'authenticationCertificate', 'encryptionCertificate'];
idemia.allCerts(filter).then(res => {
    res.data
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
 "rootCertificate": {
  ...
 },
 "authenticationCertificate": {
  ...
 },
 "nonRepudiationCertificate": {
  ...
 },
 "intermediateCertificates": {
  ...
 },
 "encryptionCertificate": {
  ...
 }
}

Token data

This will return information of the Aventra card.

idemia.tokenData().then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
       version?: string,
       serialNumber?: string,
       label?: string,
       changeCounter?: number,
    }
}

Certificate

When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

Root certificate

Contains the 'root certificate' stored on the smart card. The service can be called:

idemia.rootCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

Authentication certificate

Contains the 'authentication certificate' stored on the smart card. The 'authentication certificate' contains the public key corresponding to the private RSA authentication key. The 'authentication certificate' is needed for pin validation, authentication and singing. The service can be called:

idemia.authenticationCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

Non repudiation certificate

Contains the 'non-repudiation certificate' stored on the smart card. The 'non-repudiation certificate' contains the public key corresponding the private RSA non-repudiation key. The service can be called:

idemia.nonRepudiationCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

Issuer certificate

idemia.issuerCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

Encryption certificate

aventra.encryptionCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

The expected response for these calls should be in the following format;

{
    success: true,
    data: {
        certificate?: string,
        certificates?: Array<string>,
        certificateType?: string,
        id?: string,
        parsedCertificate?: Certificate,
        parsedCertificates?: Array<Certificate>
    }    
}

Verify pin

const data = {
    pin: "1234", // optional
    osDialog: true // optional
}
idemia.verifyPin(data).then(res => {
}, err => {
    console.error(err)
})

The expected response for these calls should be in the following format;

{
    success: true,
    data: {
        "verfied": true
    }
}

Sign

Data can be signed using the smartcard. To do so, the SDK facilitates in:

• Retrieving the certificate chain (root, intermediate and non-repudiation certificate)

• Perform a sign operation (private key stays on the smart card)

• Return the signed hash

To sign data, an algorithm must be specified in the algorithm property (see Supported Algorithms), and a Base64-encoded string representation of the digest bytes of the same algorithm in the data property.

Additionally, it is possible to bulk sign data without having to re-enter the PIN by adding an optional bulk parameter set to true to the request. Subsequent sign requests will not require the PIN to be re-entered until a request with bulk being set to false is sent, or the Bulk PIN Reset method is called.

When using bulk signing, great care must be taken to validate that the first signature request was successful prior to sending subsequent requests. Failing to do this will likely result in the card being blocked.

const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    id: "123"
}
const bulk = false;
idemia.sign(data, bulk).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
        data: string
    }
}

Raw data signing

With the function signRaw you can sign unhashed document data. This means that the Trust1Connector will hash the value itself depending on the provided sign algorithm.

Trust1Connector only supports SHA2 hashing at this point.

When using SHA3, the Trust1Connector will convert to SHA2 implicitly

Below you can find an example

var data = {
      "algorithm":"sha256",
      "data":"vl5He0ulthjX+VWNM46QX7vJ8VvXMq2k/Tq8Xq1bwEw=",
      "osDialog": false,
      "id" : "fewf5+65"
}
idemia.signRaw(data, callback);

The function looks the same as a regular sign operation but expects a base64 data object that is unhashed.

Supported hash functions (SHA2) are;

• SHA256

• SHA384

• SHA512

Bulk PIN Reset

The PIN set for bulk signing can be reset by calling this method.

idemia.resetBulkPin().then(res => {
}, err => {
    console.error(err)
})

Response will look like:

{
    "success": true,
    "data": true
}

Authenticate

The SDK is able to authenticate a card holder based on a challenge. The challenge can be:

• provided by an external service

• provided by the smart card An authentication can be interpreted as a signature use case, the challenge is signed data, that can be validated in a back-end process

const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    id: "123"
}
idemia.authenticate(data).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
        data: string
    }
}

Retrieve supported algorithms

idemia.allAlgoRefs(data).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
        ref: ['sha256', 'md5']
    }
}

Validate signature

The module allows you to call a function on the token that can validate a signature. For this we need to use the validateSignature function. You can call this one via;

const body = {
    "algorithm": 'sha256',
    "hash": '...',
    "signedHash": '...',
    "osDialog": false,
    "id": 'cert_id',
    "pin": 'pin_code',
    "timeout": 120 //timeout in seconds
}
safenet.validateSignature(body).then(response => {
    response.valid
).catch(error => {
    errorHandler(error)}
)

The response of this function will return a valid property that is either true or false.

{
    "success": true,
    "data": {
        "valid": true
    }
}