Cryptographic Objects

Objects stored in a smart card can be obtained using the Token.getObjects() method. Objects stored in a certificate store can be obtained using the CertStore.getObjects() method.

Note that, as per the PKCS#11 specifications, certificates and keys are linked together through their Object.ckId attribute. Also note that private objects can be seen only after a succesfull call to Pin.login() using the PIN they are associated with. Applications will therefore typically have the following workflow for performing a cryptographic operation:

  • Use Token.getObjects() to retrieve all objects, and filter the result using the Object.type attribute. If type is "certificate", it can be used as a candidate.

  • Additional filtering may be applied on the candidate certificates, depending on their key usage or issuer. If multiple certificates remain in the candidate list, a choice can be presented to the user.

  • The chosen certificate’s identifier is obtained through the Object.ckId property.

  • The associated PIN is obtained from the Token.pins array, at the index given by the chosen certificate’s Object.pinNumber property.

  • The PIN must be verified, by calling the Pin.login() method on the associated PIN object.

  • A new call to Token.getObjects() must be issued, which will return all objects, including the private keys.

  • The new object list must be filtered again, this time by both checking that Object.type is "privateKey" and that Object.ckId is the same value as the chosen certificate’s identifier.

  • If the card contents is consistent, a single private key object is obtained from this procedure. The cryptographic operation can be carried out on this object, typically using either the Key.sign(), Key.hashAndSign() or Key.decrypt() method.

Common properties

These properties are available for all kind of objects (SCWS.Certificate(), SCWS.Key() and SCWS.DataContainer() objects).

class SCWS.Object()

Describes a cryptographic object located in a smart card (or in a certificate store).

Note that the constructor is not intended to be called by user code. Such objects are constructed internally by the API.

Object.handle

Handle used to identify the object internally. Can be used to check if two objects correspond to the same item.

Object.parent

Container (SCWS.Token() or SCWS.CertStore() object) from which the object has been retrieved.

Object.type

String identifying the type of object. Possible values are: "certificate", "publicKey", "privateKey" and "dataContainer".

Object.ckId

Identifier string, corresponding to the hexadecimal representation of the CKA_ID attribute of the object, as seen by the PKCS#11 interface.

This value can be used to match keys and certificates that are linked together (belong in the same container).

Unavailable for data container objects.

Object.ckLabel

Label string, corresponding to the CKA_LABEL attribute of the object, as seen by the PKCS#11 interface.

Object.private

Boolean indicating whether the object is public or private (protected by PIN).

Mostly useful for data container objects.

Object.modifiable

Boolean indicating whether the object is modifiable.

Mostly useful for data container objects.

Object.pinNumber

Index of the PIN which grants access to the object. This corresponds to the index within the Token.pins array.

For public objects (certificates and public keys), it is the PIN which grants access to the corresponding private key (association is determined by the Object.ckId attribute).

Object.getDetails()

Retrieves detailed information about the object.

The information is returned (through a Promise) as a JavaScript object, whose fields depend on the type of the object. Public and private keys return an object containing key components (see Key.getDetails()). Certificates return an object containing details about the x.509 fields (see Certificate.getDetails()).

Returns:

A Promise resolving to the object containing the detail information.

Returns the URL from which the object data can be retrieved.

Only supported for certificate objects, returns the URL from which the DER-encoded X.509 data of the certificate can be obtained.

Returns:

A string containing the URL. Note that, unlike the other methods of the API, it is returned directly (not through a Promise).

Certificate Objects

class SCWS.Certificate()

Describes a certificate object. Inherits from SCWS.Object().

Note that the constructor is not intended to be called by user code. Such objects are constructed internally by the API.

Certificate.root

Boolean indicating if the certificate is a root certificate (issuer and subject are similar).

Certificate.subject

Simple string representation of the subject name.

The string is extracted from the last (most specific) occurrence of common name field. If no such field is defined, the implementation falls back on the first organizational unit name field, or the first organization name field, or the first email address field (in this order).

Certificate.issuer

Simple string representation of the issuer name.

The string is obtained by using the same rules as for the subject string.

Certificate.notBefore

Start of validity date, given as a ISO-8601 string (directly useable by the Date constructor).

Certificate.notAfter

End of validity date, given as a ISO-8601 string (directly useable by the Date constructor).

Certificate.getDetails()

Retrieves detailed information about the certificate.

The information is returned (through a Promise) as a JavaScript object containing the following fields:

  • subject: String containing the fully decoded X.509 subject name, one attribute per line (separated by newline characters), and using short names (e.g. CN).

  • issuer: String containing the fully decoded X.509 issuer name.

  • notBefore: Start of validity date, given as a ISO-8601 string, directly useable by the Date constructor.

  • notAfter: End of validity date.

  • serial: Hexadecimal string representation of the serial number.

  • version: Number indicating the X.509 version this certificate adheres to.

  • publicKeyAlg: String indicating the public key algorithm used (typically "RSA").

  • publicKeySize: Number indicating the key length in bits.

  • publicKeyValue: Hexadecimal reprentation of the ASN.1 DER-encoding of the public key.

  • signatureAlg: String indicating the algorithm used to sign this certicicate (e.g. "sha256WithRSAEncryption").

  • signatureValue: Hexadecimal representation of the signature value.

  • extensions (optional): Array providing information about the X.509 V3 extensions. For each extension, an object with the following fields is provided:

    • object: Describes the type of extension. This is itself given as an object with the following fields:

      • oid: String representation of the object identifier in numerical form (e.g. "2.5.29.15").

      • shortName (optional): Short name of the extension (if known). Short names may include (but are not limited to) the following strings:

        • "subjectKeyIdentifier": Subject key identifier

        • "keyUsage": Key usages

        • "privateKeyUsagePeriod": Private key usage period

        • "subjectAltName": Subject alternative name

        • "issuerAltName": Issuer alternative name

        • "basicConstraints": Basic constraints

        • "crlNumber": CRL number

        • "CRLReason": CRL reason code

        • "invalidityDate": Invalidity date

        • "deltaCRL": Delta CRL identifier

        • "nameConstraints": Name constraints

        • "crlDistributionPoints": CRL distribution points

        • "certificatePolicies": Certificate policies

        • "policyMappings": Policy mappings

        • "authorityKeyIdentifier": Authority key identifier

        • "policyConstraints": Policy constraints

        • "extendedKeyUsage": Extended key usages

        • "inhibitAnyPolicy": Inhibit any-policy

        • "targetInformation": Target information

        • "noRevAvail": No revocation available

        • "authorityInfoAccess": Authority information access

      • longName (optional): Long, human-readable name of the extension.

    • critical: Boolean indicating if the extension is critical.

    • value: String representation of the extension value. The purpose is to display the information to the user, not parsing it, so it is given in a human-readable form.

Returns:

A Promise resolving to the object containing the detail information.

Certificate.getTrust()

Checks the validity of the certificate and retrieves detailed trust information.

The information is returned (through a Promise) as a JavaScript object, with the following fields:

  • trustStatus: Either the "ok" string if the certificate is valid according to the operating system criterias, or an array of strings indicating the (possibly multiple) reasons why the certificate validity checks failed. Reasons may be:

    • "notTimeValid": This certificate or one of the certificates in the chain is not time-valid.

    • "notTimeNested": The certificates in the chain are not properly time-nested.

    • "revoked": The trust for this certificate or one of the certificates in the chain has been revoked.

    • "revocationStatusUnknown": The revocation status of this certificate or one of the certificate of the chain is unknown.

    • "revocationOffline": The revocation status cannot be checked because the revocation server is offline.

    • "signatureInvalid": The certificate or one of the certificates in the chain does not have a valid signature.

    • "invalidUsage": The certificate does not allow the required usage.

    • "untrustedRoot": The certificate or certificate chain is based on an untrusted root.

    • "cyclicChain": One of the certificates in the chain was issued by a certification authority that the original certificate had certified.

    • "partialChain": The certificate chain is not complete.

    • "ctlNotTimeValid": A CTL used to create this chain was not time-valid.

    • "ctlSignatureInvalid": A CTL used to create this chain did not have a valid signature.

    • "ctlInvalidUsage": A CTL used to create this chain is not valid for this usage.

    • "invalidExtension": One of the certificates has an extension that is not valid.

    • "invalidPolicyConstraints": The certificate or one of the certificates in the certificate chain has a policy constraints extension, and one of the issued certificates has a disallowed policy mapping extension or does not have a required issuance policies extension.

    • "invalidBasicConstraints": The certificate or one of the certificates in the certificate chain has a basic constraints extension, and either the certificate cannot be used to issue other certificates, or the chain path length has been exceeded.

    • "invalidNameConstraints": The certificate or one of the certificates in the certificate chain has a name constraints extension that is not valid.

    • "unsupportedNameConstraint": The certificate or one of the certificates in the certificate chain has a name constraints extension that contains unsupported fields.

    • "undefinedNameConstraint": The certificate or one of the certificates in the certificate chain has a name constraints extension, and a name constraint is missing for one of the name choices in the end certificate.

    • "forbiddenNameConstraint": The certificate or one of the certificates in the certificate chain has a name constraints extension, and there is not a permitted name constraint for one of the name choices in the end certificate.

    • "excludedNameConstraint": The certificate or one of the certificates in the certificate chain has a name constraints extension, and one of the name choices in the end certificate is explicitly excluded.

    • "noIssuanceChainPolicy": The end certificate does not have any resultant issuance policies, and one of the issuing CA certificates has a policy constraints extension requiring it.

    • "notSupportedCriticalExtension": The certificate contains an unsupported critical extension.

    • "unknown": An unkown reason reported by the system.

  • usages: As defined in Certificate.usages property. This field is available even with a middleware version prior to 6.22.0.0.

  • certPath: Certification path (up to the final root entity if it could be determined, or incomplete if some entities are missing in the appropriate stores), as an array of SCWS.Certificate() objects. The entity certificate (the certificate on which the check is being made made) is at index 0, and the final root authority is at the last index.

These combinations have been defined to mimimc the behavior of the Windows “View Certificate” dialog box.

Returns:

A Promise resolving to the object containing the trust information.

Certificate.getValue(format)

Retrieves the DER-encoded value of the certificate.

Returns:

A Promise resolving to a string containing the full PEM data of the certificate (base-64 encoding, enclosed with RFC7468 header and footer).

Key Objects

class SCWS.Key()

Describes a key object. Inherits from SCWS.Object().

Note that the constructor is not intended to be called by user code. Such objects are constructed internally by the API.

Key.keyType

String identifying the type of the key. The possible values are:

  • "publicKey"

  • "privateKey"

Key.algorithmName

String identifying the algorithm of the key. Possible values are currently "RSA" and "ECDSA".

Key.keyLength

Number indicating the key length, in bits.

Key.partialHash

Boolean indicating if the key must use partial hashing (qualified signature key). Available only for private keys.

Key.getDetails()

Retrieves detailed information about the key.

The information is returned (through a Promise) as a JavaScript object containing the following fields:

  • for RSA private and public keys:

    • modulus: modulus as a hexadecimal string.

    • pubExp: public exponent as a hexadecimal string.

  • for ECDSA keys:

    • ecParameters: ECDSA curve paramaters (curve name or parameters) as a DER encoded hexadecimal string, as described in PKCS#11.

    • ecPoint: ECDSA public point in uncompressed format as a hexadecimal string (only for public keys).

Returns:

A Promise resolving to the object containing the detail information.

Data Container Objects

class SCWS.DataContainer()

Describes a data container object. Inherits from SCWS.Object().

Note that the constructor is not intended to be called by user code. Such objects are constructed internally by the API.

To create a new DataContainer objbect in a token, the Token.createDataContainer() method can be used.

DataContainer.application

String naming the application that manages the object. Optional.

DataContainer.getValue()

Retrieves the data container data value.

Returns:

a Promise resolving to an ArrayBuffer containing the data value.

DataContainer.setValue(value)

Modifies the data container data value.

Arguments:

  • value – an ArrayBuffer or Uint8Array containing the new data value.

Returns:

a Promise resolved when the operation completes. The resolution value is undefined.

High level object getters

These entry points have been designed to be easy to use on desktop and mobile to get Objects from cards.

static SCWS.requestCertificates(callback, options)

This asynchronous function enumerates all cards, and enumerates all certificates found from all the cards. If no card is found on the system, the function waits for a card to be inserted.

If none of the inserted cards is useable (the connection fails on all cards), an error is thrown.

If at least one card is found, but no certificates are present, an error is thrown.

On iOS, the function shows the “Ready to scan” system dialog box, which is closed when the operation is done (when the returned promise is resolved).

On Android, the function shows an equivalent dialog, simulated by the middleware application.

On other systems (desktop systems), there is no such dialog box builtin (as the middleware cannot interact directly on the GUI shown within the web browser), but it can be simulated by the web application itself, through the showScanDlg/closeScanDlg/setScanDlgMsg optional callbacks.

Warning: Callbacks SCWS.onreaderstatechanged and SCWS.onreaderadded must not be change during requestCertificates call!

The implementation of the callback can perform operations using the certificate. The certificate object, however, can only be used within the context of this callback.

Arguments:

  • callback – the function called when certificates have been enumerated. The unique parameter is filled with an array of SCWS.Certificate objects that have been found. The “Ready to scan” dialog is kept open during the execution of the callback.

  • options – an object with the following optional properties: - showScanDlg: a callback function that will be called when the app-simulated “Ready to scan” dialog box needs to be shown (desktop only). - closeScanDlg: a callback function that will be called when the app-simulated “Ready to scan” dialog box needs to be closed. The callback should accept a parameter, which is set to null if the operation was successfull, or which contains the error message as a string, in case the operation failed. The implementation is expected to show either a successful indication, or the given error message with a failure indication for a short period of time before closing. Note that the closeScanDlg implementation can be asynchronous (return a Promise), in which case the requestCertificates call will wait for its completion before being itself resolved. - setScanDlgMsg: a callback function that will be called when the message in the app-simulated “Ready to scan” dialog box needs to be updated. The callback should accept a string parameter for the message. - disableScanDlg: boolean, if true, disables the middleware-simulated “Ready to scan” dialog box on Android (note: this dialog cannot be disabled on iOS). - waitingMsg: the string to be displayed while waiting for the user to insert a card - connectingMsg: the string to be displayed when a card is being connected to - readingMsg: the string to be displayed while the card is being read

Returns:

A Promise whose value resolves to the return value of the callback.

static SCWS.requestPrivateKey(certificate, credential, callback, options)

This asynchronous function finds the private key associated to the given certificate. It retrieves the token containing the given certificate, logs in using the given credential, and searches for the private key object with the ckId attribute corresponding to the certificate.

It calls back a function, providing the private key found and its associated certificate. If no private key/certificate is found, an error is thrown.

During the entire operation, including the callback function, a “Ready to scan” dialog box is shown, in a similar fashion as SCWS.requestCertificates. The implementation of the callback can perform operations using the private key and its associated certificate (e.g. document signatures, …). Private key and certificate objects, however, can only be used within the context of this callback.

Arguments:

  • certificate – the certificate

  • credential – the credential that will be used to log in

  • callback – the callback function. The first parameter is filled with the private key found, the second with the associated valid certificate.

  • options – see SCWS.requestCertificates

Returns:

a Promise whose value resolves to the return value of the callback.