Cryptographic Objects

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

Common properties

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

class SCWS.Object()

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() 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 the value of the public components. 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.

Certificate Objects

class SCWS.Certificate()

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 RFC1123 string (directly useable by the Date constructor).

Certificate.notAfter

End of validity date, given as a RFC1123 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 RFC1123 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 representation of the ASN.1 DER-encoding of the public key.

  • signatureAlg: String indicating the algorithm used to sign this certificate (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.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()

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. The only possible value is currently "RSA".

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.

Data Container Objects

class SCWS.DataContainer()

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 object 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, Buffer or Uint8Array containing the new data value.

Returns

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