Tokens

Manipulating tokens

The Token class is described below:

class SCWS.ICAO.Token()

Represents connection to an ICAO compliant smart card. ICAO token objects are obtained by calling the SCWS.Reader.connectICAO() method.

Token.reader

The SCWS.Reader() object from which this token is issued.

Token.disconnect()

Disconnects from the ICAO token. Must be called when the application terminates (e.g. from the onbeforeunload/onunload events), or before.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token operations

Reading data

Token.readFile(fileId)

Reads an Elementary File (EF) from the ICAO token. To identify file to read, a file identifier is used in parameter with several possible formats:

  • a value defined in ICAO.FILE_ID or, more generally, an object with following attributes:

    • efid as an integer, corresponding to the File Identifier (FID).

    • underMF as a boolean. If false, file to read is under eMRTD application passed in SCWS.Reader.connectICAO() method. If true, file to read is under Master File.

  • a value that can be passed in SCWS.ICAO.getFileIdentifier() function.

Returned data is an object with 2 attributes:

  • raw: raw data as a hexadecimal string, containing whole file.

  • content: an object representing parsed data content if applicable.

Arguments

  • fileId – The file identifier.

Throws

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisified for reading this file.

  • ICAO_ERR_FILE_NOT_FOUND() – file is not found.

Returns

A Promise resolving to an object containing the file content.

Examples:

// Example 1: read DG 2 with different input formats. Following operations are equivalent:

// by DG number
myToken.readFile(2).then(function(fileContent) {
  // do something
});

// by file identifier object
myToken.readFile(ICAO.FILE_ID.DG_2).then(function(fileContent) {
  // do something
});

// by DG DER tag
myToken.readFile(0x75).then(function(fileContent) {
  // do something
});

// Example 2: read EF_COM file and log its DGs tag list
myToken.readFile(ICAO.FILE_ID.EF_COM).then(function(efComContent){
  console.log(efComContent.content.dataGroupTagList);
});
// output is something like that:
>> Array(7) [ 97, 117, 99, 107, 108, 109, 110 ]

Note

see ASN.1 data reading formatting part for format of returned content value of Token.readFile() method.

Security mechanisms

Token.doBAC(mrzInformation)

Does Basic Access Control (BAC) protocol on the ICAO token.

Arguments

  • mrzInformation – The user MRZ information value, as a string.

Throws

ICAO_ERR_AUTHENTICATION_FAILED() – authentication failed, probably due to a wrong given mrzInformation value.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.doPACE(credentialType, credential[, securityInfoFileId[, securityInfoIndex]][, additionalParameters])

Does Password Authenticated Connection Establishment (PACE) protocol on the ICAO token. To identify which PACEInfo SecurityInfo token will use, securityInfoFileId and securityInfoIndex parameters are used:

  • securityInfoFileId defines a file identifier containing a PACEInfo SecurityInfo entry. Supported files are EF_CARD_ACCESS and DG_14 of ICAO.FILE_ID.

  • securityInfoIndex defines the index of PACEInfo SecurityInfo to use in previous file.

Additional parameters in additionalParameters parameter can be set if PACE will be followed by Terminal Authentication v2 for instance. It must be an object with the following optional fields:

  • CHAT: Certificate Holder Authorization Template as a DER hexadecimal string with 0x7F4C tag. Resolution value of returned promise will contain Certification Authority Reference and Previous Certification Authority Reference values returned by eMRTD.

Arguments

  • credentialType – The user crendential type, as an int. Possible values are values of ICAO.CREDENTIAL_TYPE.

  • credential – The user crendential value, as a string.

  • securityInfoFileId – The file identifier containing a PACEInfo SecurityInfo entry. If value is absent, or null is given, EF.CardAccess file will be used.

  • securityInfoIndex – The index of SecurityInfo to use in file defined by securityInfoFileId as an integer. If value is absent, or null is given, first PACEInfo SecurityInfo entry will be used in previous given file.

  • additionalParameters – Additional parameters for PACE as an object, defined as above.

Throws

  • ICAO_ERR_FUNCTION_NOT_SUPPORTED() – PACEInfo SecurityInfo to use is not supported by middleware.

  • ICAO_ERR_INVALID_PARAMS() – PACEInfo SecurityInfo to use is invalid (wrong file or index).

  • ICAO_ERR_CREDENTIAL_SUSPENDED() – credential to use (PIN or PUK) is suspended, use Token.resumePIN() or Token.resumePUK() method if applicable.

  • ICAO_ERR_CREDENTIAL_BLOCKED() – credential to use (PIN or PUK) is blocked, use Token.unblockPIN() method if applicable.

  • ICAO_ERR_CREDENTIAL_DEACTIVATED() – credential to use (PIN) is deactivated, use Token.activatePIN() method if applicable.

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisified (for reading DG_14 for instance) or credential to use (PIN or PUK) is blocked, deactivated or suspended (on certain eMRTD token this error is returned instead of ICAO_ERR_CREDENTIAL_SUSPENDED, ICAO_ERR_CREDENTIAL_BLOCKED or ICAO_ERR_CREDENTIAL_DEACTIVATED).

  • ICAO_ERR_AUTHENTICATION_FAILED() – authentication failed, probably due to a wrong given credential value. If ICAO.CREDENTIAL_TYPE.PIN or ICAO.CREDENTIAL_TYPE.PUK was used, returned SCWS.Error() object has an additional remainingTries attribute with remaining tries value as an integer.

Returns

A Promise resolved when the operation has been performed. If CHAT was given in additionalParameters, resolution value is an object with certificationAuthorityReference and previousCertificationAuthorityReference attributes as strings, otherwise, the resolution value is undefined.

Examples:

// Example 1: PACE with CAN value, using PACEInfo from EF_CARD_ACCESS file
myToken.doPACE(ICAO.CREDENTIAL_TYPE.CAN, "123456", ICAO.FILE_ID.EF_CARD_ACCESS).then(function() {
  console.log("success");
}).catch(function(err) {
  console.log("error:" + err);
  throw err;
});

// Example 2: PACE with a wrong PIN value (caution, sensitive operation!)
myToken.doPACE(ICAO.CREDENTIAL_TYPE.PIN, "9999").catch(function(err) {
  console.log("error: " + err.code);
  console.log("remaining tries: " + err.remainingTries);
  throw err;
});
>> error: ICAO_ERR_AUTHENTICATION_FAILED
   remaining tries: 3

// Example 3: PACE with Certificate Holder Authorization Template (CHAT) additional attribute
var chatVal = "7F 4C 12 06 09 04 00 7F 00 07 03 01 02 02 53 05 FF FF FF FF FF";
myToken.doPACE(ICAO.CREDENTIAL_TYPE.CAN, "123456", null, null, {"CHAT": chatVal}).then(function(ret) {
  console.log("success");
  console.log("certification authority reference: " + ret.certificationAuthorityReference);
});
>> success
   certification authority reference: USCVCATEST1
Token.doPassiveAuthentication(CSCACertificate[, DSCertificate])

Does Passive Authentication using PKCS#7 structure contained in token’s EF.SOD file and given certificates.

The following steps are done:

  • PKCS#7 signatures of EF.SOD and EF.CardSecurity, if applicable, are verified using DS public key stored in DS certificate.

  • PKCS#7 structure of EF.SOD is verified using given Country Signing CA (CSCA) certificate and, optionally, given Document Signer (DS) certificate.

  • Each relevent DGs are read from the token and hashed according to digest algorithm specified in PKCS#7 structure. Each hash value is then compared to reference hash value from EF.SOD content.

Returned object contains results of passive authentication:

  • verifiedDG: an array of DG numbers that have been correctly verified.

  • notVerifiedDG: an array of DG numbers that could not be verified; typically when current security status are not sufficient to read corresponding DGs.

Arguments

  • CSCACertificate – The CSCA certificate to use for chain verification as a hexadecimal string. Only DER encoding is supported.

  • DSCertificate – The DS certificate to use for chain verification as a hexadecimal string. Only DER encoding is supported. This parameter is optional if DS certificate is already present in EF.SOD PKCS#7 structure.

Throws

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied to read EF_SOD file.

  • ICAO_ERR_AUTHENTICATION_FAILED() – PKCS#7 signatures were not correctly verified or some processed DGs hash are not equal to their reference value in EF.SOD content file. In the last case, returned SCWS.Error() object has an additional failedVerificationDGs attribute containing an array of corresponding DGs number.

  • ICAO_ERR_VERIFY_CERTIFICATE_FAILED() – CSCA or DS certificates verification (certificate chain, certificates date…) failed.

  • ICAO_ERR_FUNCTION_NOT_SUPPORTED() – hash algorithm defined in PKCS#7 structure is not supported by middleware.

Returns

A Promise resolving to an object containing results of DGs verification.

Examples:

// passive authentication with corrupted DGs 1 and 15 in eMRTD
// we assume CSCACertificate is correctly filled
myToken.doPassiveAuthentication(CSCACertificate).then(function() {
  console.log("success");
}).catch(function(err) {
  if (err.code === "ICAO_ERR_AUTHENTICATION_FAILED" && err.failedVerificationDGs)
    console.log(err.failedVerificationDGs);
  throw err;
});
>> Array(2) [ 1, 15 ]
Token.doActiveAuthentication()

Does Active Authentication on the ICAO, using public key of Data Group 15.

Throws

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

  • ICAO_ERR_AUTHENTICATION_FAILED() – authentication failed.

  • ICAO_ERR_FUNCTION_NOT_SUPPORTED() – an algorithm defined in Public Key used for verification or hash function (ECDSA) is not supported by the middleware.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.doChipAuthenticationV1([securityInfoFileId[, securityInfoIndex]])

Does Chip Authentication v.1 (CAv1) protocol on the ICAO token. It must be preceded by Token.doBAC() or Token.doPACE() security mechanisms. To identify which ChipAuthenticationInfo SecurityInfo token will use, securityInfoFileId and securityInfoIndex parameters are used:

  • securityInfoFileId defines a file identifier containing a ChipAuthenticationInfo SecurityInfo entry. Supported files are EF_CARD_ACCESS and DG_14 of ICAO.FILE_ID.

  • securityInfoIndex defines the index of ChipAuthenticationInfo SecurityInfo to use in previous file.

Arguments

  • securityInfoFileId – The file identifier containing a ChipAuthenticationInfo SecurityInfo entry. If value is absent, or null is given, DG 14 file will be used.

  • securityInfoIndex – The index of ChipAuthenticationInfo SecurityInfo to use in file defined by securityInfoFileId as an integer. If value is absent, or null is given, first ChipAuthenticationInfo SecurityInfo entry will be used in previous given file.

Throws

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

  • ICAO_ERR_INVALID_PARAMS() – ChipAuthenticationInfo SecurityInfo to use is invalid (wrong file or index).

  • ICAO_ERR_AUTHENTICATION_FAILED() – authentication failed.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.doChipAuthenticationV2()

Does Chip Authentication v.2 (CAv2) protocol on the ICAO token. It must be preceded by Token.doTerminalAuthenticationV2() security mechanism.

Throws

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

  • ICAO_ERR_AUTHENTICATION_FAILED() – authentication failed; authentication token returned by token and authentication token processed by middleware does not match.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.doTerminalAuthenticationV1(caReferenceName, CVCs, callback)

Does Terminal Authentication v.1 (TAv1) protocol on the ICAO token. It must be preceded by Token.doChipAuthenticationV1() security mechanism.

This function starts with a Card Verifiable Certificates (CVCs) verification. Then, a signature verification is made by the token with public key contained in the given terminal certificate (last CVC in CVCs parameter).

The signature (with hashing) with the corresponding private key, must be done by provided callback function. It is given the following parameter:

  • dataToSign: the data to hash and sign, as an ArrayBuffer.

The function must return an ArrayBuffer containing the signature (DER or raw) to be provided for signature verification by token.

Arguments

  • caReferenceName – the issuer reference name of 1st certificate to verify, as a string. If null or an empty string is given, the issuer reference name will not be checked during CVCs verification.

  • CVCs – The Card Verifiable Certificates (CVCs) to be verified by token, as a list of hexadecimal strings. First certificate must be a CVCA certificate and last one must be a terminal certificate (IS role).

  • callback – the callback function that will hash and sign data.

Throws

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

  • ICAO_ERR_OPERATION_NOT_PERMITTED() – operation is not permitted; only one execution of Terminal Authentication is allowed per session.

  • ICAO_ERR_INVALID_PARAMS() – certificates to verify are missing.

  • ICAO_ERR_VERIFY_CERTIFICATE_FAILED() – certificates verification failed (by token or by middleware).

  • ICAO_ERR_AUTHENTICATION_FAILED() – authentication failed, probably due to a wrong signature returned by callback.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.doTerminalAuthenticationV2(CVCs, callback[, securityInfoFileId[, securityInfoIndex]])

Does Terminal Authentication v.2 (TAv2) protocol on the ICAO token. It must be preceded by Token.doPACE() security mechanism with CHAT additional attribute.

This function starts with a Card Verifiable Certificates (CVCs) verification. Then, middleware generates and sends to the token an ephemeral Diffie-Hellman key pair based on a ChipAuthenticationPublicKeyInfo SecurityInfo entry stored in token. To identify which ChipAuthenticationInfo SecurityInfo (and so, corresponding ChipAuthenticationPublicKeyInfo) entry will be use, securityInfoFileId and securityInfoIndex parameters are used:

  • securityInfoFileId defines a file identifier containing a ChipAuthenticationInfo SecurityInfo entry. Supported files are DG_14 and EF_CARD_SECURITY of ICAO.FILE_ID.

  • securityInfoIndex defines the index of ChipAuthenticationInfo SecurityInfo to use in previous file. For EF_CARD_SECURITY, SecurityInfos structure is content.signedData.encapContentInfo.eContent attribute of read file.

Finally, a signature verification is made by the token with public key contained in the given terminal certificate (last CVC in CVCs parameter).

The signature (with hashing) with the corresponding private key, must be done by provided callback function. It is given the following parameter:

  • dataToSign: the data to hash and sign, as an ArrayBuffer.

The function must return an ArrayBuffer containing the signature (DER or raw) to be provided for signature verification by token.

Arguments

  • CVCs – The Card Verifiable Certificates (CVC) to be verified by token, as a list of hexadecimal strings. First certificate must be a CVCA certificate and last one must be a terminal certificate (IS role).

  • callback – the callback function that will hash and sign data.

  • securityInfoFileId – The file identifier containing a ChipAuthenticationInfo SecurityInfo entry. If value is absent, or null is passed, EF.CardSecurity file will be used.

  • securityInfoIndex – The index of ChipAuthenticationInfo SecurityInfo to use in file defined by securityInfoFileId as an integer. If value is absent, or null is given, first ChipAuthenticationInfo SecurityInfo entry will be used in previous given file.

Throws

  • ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

  • ICAO_ERR_OPERATION_NOT_PERMITTED() – operation is not permitted; only one execution of Terminal Authentication is allowed per session.

  • ICAO_ERR_INVALID_PARAMS() – certificates to verify are missing or specified ChipAuthenticationInfo could not be found.

  • ICAO_ERR_VERIFY_CERTIFICATE_FAILED() – certificates verification failed by token.

  • ICAO_ERR_AUTHENTICATION_FAILED() – authentication failed, probably due to a wrong signature returned by callback.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

PIN management

Token.resumePIN(canValue, pinValue[, securityInfoFileId[, securityInfoIndex]])

Resumes suspended PIN used in Token.doPACE() method. Internally, middleware will use PACE with CAN followed by PACE with PIN.

If a wrong value of PIN is given, operation will fail and block PIN credential.

To identify which PACEInfo SecurityInfo token will use, securityInfoFileId and securityInfoIndex parameters are used:

  • securityInfoFileId defines a file identifier containing a PACEInfo SecurityInfo entry. Supported files are EF_CARD_ACCESS and DG_14 of ICAO.FILE_ID.

  • securityInfoIndex defines the index of PACEInfo SecurityInfo to use in previous file.

Arguments

  • canValue – The CAN user crendential value, as a string.

  • pinValue – The PIN user crendential value, as a string.

  • securityInfoFileId – The file identifier containing a PACEInfo SecurityInfo entry. If value is absent, or null is given, EF.CardAccess file will be used.

  • securityInfoIndex – The index of PACEInfo SecurityInfo to use in file defined by securityInfoFileId as an integer. If value is absent, or null is given, first PACEInfo SecurityInfo entry will be used in previous given file.

Throws

same errors as Token.doPACE() method.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.resumePUK(canValue, pukValue[, securityInfoFileId[, securityInfoIndex]])

Resumes suspended PUK used in Token.doPACE() method. Internally, middleware will use PACE with CAN followed by PACE with PUK.

If a wrong value of PUK is given, operation will fail and block PUK credential.

To identify which PACEInfo SecurityInfo token will use, securityInfoFileId and securityInfoIndex parameters are used:

  • securityInfoFileId defines a file identifier containing a PACEInfo SecurityInfo entry. Supported files are EF_CARD_ACCESS and DG_14 of ICAO.FILE_ID.

  • securityInfoIndex defines the index of PACEInfo SecurityInfo to use in previous file.

Arguments

  • canValue – The CAN user crendential value, as a string.

  • pukValue – The PUK user crendential value, as a string.

  • securityInfoFileId – The file identifier containing a PACEInfo SecurityInfo entry. If value is absent, or null is given, EF.CardAccess file will be used.

  • securityInfoIndex – The index of PACEInfo SecurityInfo to use in file defined by securityInfoFileId as an integer. If value is absent, or null is given, first PACEInfo SecurityInfo entry will be used in previous given file.

Throws

same errors as Token.doPACE() method.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.unblockPIN()

Unblocks PIN used in Token.doPACE() method.

Throws

ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.changePIN(newPIN)

Changes PIN used in Token.doPACE() method.

Arguments

  • newPIN – The new PIN value, as a string.

Throws

ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.activatePIN()

Activates PIN used in Token.doPACE() method.

Throws

ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Token.deactivatePIN()

Deactivates PIN used in Token.doPACE() method.

Throws

ICAO_ERR_SECURITY_STATUS_NOT_SATISFIED() – security status are not satisfied.

Returns

A Promise resolved when the operation has been performed (the resolution value is undefined).

Notes

Sessions

The following API entry points will start a new session:

Session is released after completion of:

See ICAO specifications (Doc 9303 part 11) for a definition of a session.

Additional error attributes

Some API entry points reject a SCWS.Error() object with additional attributes:

  • Token.doPACE() when ICAO.CREDENTIAL_TYPE.PIN or ICAO.CREDENTIAL_TYPE.PUK with a wrong value is used. In the case of an ICAO_ERR_AUTHENTICATION_FAILED code error, a remainingTries integer attribute is defined.

  • Token.doPassiveAuthentication() when rejects ICAO_ERR_AUTHENTICATION_FAILED code error and at least one DG hash verification failed. In this case, a failedVerificationDGs attribute is defined as an array of DGs number.