General conventions

Asynchronous operations

The API makes extensive use of the Promise API (as defined by the JavaScript ES6 specification), because all requests are made asynchronously. All functions and methods therefore return a Promise object, rather than directly the result of the operation. Object properties, however, typically return cached data, and return the requested value directly.

Error handling

All errors resulting from operations with the API are represented by a SCWS.Error() object:

class SCWS.Error(message, code, status, customData)

Describes an error resulting from a request to the SCWS service.

Error.message

Human-readable error message.

Error.code

Error code string, suitable for checking when specific actions need to be taken depending on the cause.

Possible values are:

  • "CKR_CANCEL": The operation was canceled.

  • "CKR_HOST_MEMORY": Not enough memory on the host computer.

  • "CKR_SLOT_ID_INVALID": The selected slot Pin ID is invalid.

  • "CKR_GENERAL_ERROR": An unrecoverable error occurred. This may be due to an inconsistency in the smart card data.

  • "CKR_FUNCTION_FAILED": The operation failed for an unknown reason.

  • "CKR_ARGUMENTS_BAD": Bad argument were passed to the function.

  • "CKR_ATTRIBUTE_READ_ONLY": The token object cannot be modified because it is read-only.

  • "CKR_ATTRIBUTE_SENSITIVE": The token object cannot be read because it is sensitive.

  • "CKR_ATTRIBUTE_TYPE_INVALID": The object attribute is invalid.

  • "CKR_ATTRIBUTE_VALUE_INVALID": The value of the object attribute is invalid.

  • "CKR_ACTION_PROHIBITED": The action cannot be done because it is prohibited by the token.

  • "CKR_DATA_INVALID": The data is invalid.

  • "CKR_DATA_LEN_RANGE": The length of the data is inconsistent.

  • "CKR_DEVICE_ERROR": An error occurred during the communication with the card.

  • "CKR_DEVICE_MEMORY": There is not enough memory space available in the card.

  • "CKR_DEVICE_REMOVED": The card has been removed during the operation.

  • "CKR_ENCRYPTED_DATA_INVALID": The encrypted data is invalid.

  • "CKR_ENCRYPTED_DATA_LEN_RANGE": The length of the encrypted data is invalid.

  • "CKR_FUNCTION_CANCELED": The operation has been cancelled. (Legacy support)There is currently no function executing in parallel in the specified session. * - "CKR_FUNCTION_NOT_PARALLEL":

  • "CKR_FUNCTION_NOT_SUPPORTED": The operation is not supported by the card.

  • "CKR_KEY_HANDLE_INVALID": The specified key handle is not valid.

  • "CKR_KEY_SIZE_RANGE": The key size is outside of the range supported for this operation.

  • "CKR_KEY_TYPE_INCONSISTENT": The key types are inconsistent for this operation.

  • "CKR_KEY_NOT_NEEDED": An extraneous key was supplied.

  • "CKR_KEY_CHANGED": One of the keys specified is not the same key that was being used in the original saved session.

  • "CKR_KEY_INDIGESTIBLE": The key cannot be digested.

  • "CKR_KEY_FUNCTION_NOT_PERMITTED": The key does not support this operation.

  • "CKR_KEY_NOT_WRAPPABLE": The key cannot be wrapped.

  • "CKR_KEY_UNEXTRACTABLE": The key cannot be extracted.

  • "CKR_MECHANISM_INVALID": The cryptographic algorithm is not supported.

  • "CKR_MECHANISM_PARAM_INVALID": The parameters for the cryptographic operation are incorrect.

  • "CKR_PIN_INCORRECT": The PIN value is incorrect.

  • "CKR_PIN_INVALID": The PIN does not have the proper format.

  • "CKR_PIN_LEN_RANGE": The length of the PIN is outside of the range.

  • "CKR_PIN_EXPIRED": The PIN has expired and needs to be changed.

  • "CKR_PIN_LOCKED": Due to too many incorrect PINs entered, the card has been locked.

  • "CKR_SIGNATURE_INVALID": The digital signature in invalid.

  • "CKR_SIGNATURE_LEN_RANGE": The length of the digital signature is inconsistent.

  • "CKR_TEMPLATE_INCOMPLETE": The template specified for creating an object is incomplete, and lacks some necessary attributes.

  • "CKR_TEMPLATE_INCONSISTENT": The template specified for creating an object has conflicting attribute.

  • "CKR_TOKEN_NOT_PRESENT": The token has been removed.

  • "CKR_TOKEN_NOT_RECOGNIZED": The token is not supported.

  • "CKR_TOKEN_WRITE_PROTECTED": The token is write-protected.

  • "CKR_UNWRAPPING_KEY_HANDLE_INVALID": The key handle specified to be used to unwrap another key is not valid.

  • "CKR_UNWRAPPING_KEY_SIZE_RANGE": The size of the unwrapping key is outside of the range supported for this operation.

  • "CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT": The type of the unwrapping key is not supported for this operation.

  • "CKR_USER_ALREADY_LOGGED_IN": The user is already logged in.

  • "CKR_USER_NOT_LOGGED_IN": The appropriate user is not logged in.

  • "CKR_USER_PIN_NOT_INITIALIZED": The user PIN on this token has never been initially set.

  • "CKR_USER_TYPE_INVALID": The required user type is not defined for this card.

  • "CKR_USER_ANOTHER_ALREADY_LOGGED_IN": Another user is currently logged in.

  • "CKR_USER_TOO_MANY_TYPES": Too many users are logged in the token.

  • "CKR_WRAPPED_KEY_INVALID": The size of the wrapped key is outside of the range supported for this operation.

  • "CKR_WRAPPED_KEY_LEN_RANGE": The type of the wrapped key is not supported for this operation.

  • "CKR_WRAPPING_KEY_HANDLE_INVALID": The key handle specified to be used to wrap another key is not valid.

  • "CKR_WRAPPING_KEY_SIZE_RANGE": The size of the wrapping key is outside of the range supported for this operation.

  • "CKR_WRAPPING_KEY_TYPE_INCONSISTENT": The type of the wrapping key is not supported for this operation.

  • "CKR_CURVE_NOT_SUPPORTED": This curve is not supported by this token.

  • "CKR_INFORMATION_SENSITIVE": The information is sensitive and cannot be revealed.

  • "CKR_LIBRARY_LOAD_FAILED": The Cryptoki library could not load a dependent shared library.

  • "CKR_PIN_TOO_WEAK": The new PIN must be different from the current one and recent previous PINs.

  • "CKR_PUBLIC_KEY_INVALID": The public key fails a public key validation.

  • "CXR_NO_LICENSE_KEY": The software license key is invalid.

  • "CXR_CONTAINER_INVALID": The selected container is invalid.

  • "CXR_CONTAINER_EXISTS": Security status not satisfied: the user may not be authenticated, the secure channel might not be established, or chip authentication may be missing.

  • "CXR_PUK_ALREADY_USED": The Puk is already used.

  • "CXR_PIN_UNBLOCK_BLOCKED": The PIN cannot be unblocked anymore. The maximum number of unlock attempts has been reached.

  • "CXR_NOT_PERMITTED": The Puk is already used.

  • "CXR_MISSING_FINGERPRINT_SCANNER": a fingerprint scanner is needed for this operation.

  • "CXR_SIGNATURE_TIMESTAMP": Timestamping step of the signature failed.

  • "CXR_PACE_NEEDED": The card needs a Pace before using it.

  • "CXR_CERT_NOT_TRUSTED": The certificate has not been approved by an authority from the trusted zone.

  • "CXR_BROKEN_AUTHENTICATION": Secure chanel is broken.

  • "MWR_IMPORT_FILE_INVALID": The format of the file is unsupported or the file has been damaged.

  • "MWR_IMPORT_PASSWORD_INVALID": The file password is invalid.

  • "MWR_IMPORT_KEY_TYPE_UNSUPPORTED": The card does not support the required key type.

  • "MWR_IMPORT_KEY_LENGTH_UNSUPPORTED": The card does not support the required key length.

  • "MWR_PUK_ALREADY_USED": This PIN unblocking code has already been used.

  • "MWR_SCWS_UNREACHABLE": The SCWS service could not be reached.

  • "MWR_SCWS_COMM_ERROR": The communication with the SCWS service failed.

  • "MWR_SCWS_COMM_TIMEOUT": The communication with the SCWS service has timed out.

  • "MWR_SCWS_BAD_PARAMS": Invalid input parameters.

  • "MWR_SCWS_UNKNOWN_ERROR": The SCWS service returned an invalid error code.

On mobile devices, additional values are possible:

  • "CXR_BT_PERMISSIONS_NOT_GRANTED": Bluetooth permissions are not granted.

  • "CXR_BT_INITIALIZATION_FAILED": The initialization of bluetooth service failed. Maybe it is not enabled on your device.

  • "CXR_BT_NOT_SCANNING": Bluetooth scan has not been started or has been stopped.

  • "CXR_BT_DEVICE_NOT_SUPPORTED": The bluetooth peripheral is not supported.

  • "CXR_BT_DEVICE_NOT_DETECTED": The bluetooth peripheral is not detected.

  • "CXR_BT_ALREADY_PAIRED": The current operation is not permitted because a bluetooth peripheral is already paired.

  • "CXR_FUNCTION_TIMED_OUT": The operation timed out. (typical on iOS NFC)

  • "CXR_AID_NOT_IN_PLIST_FILE": The AID of the card is not recognized, please be sure to add the correct card AID in the info.plis file.

Error.httpStatus

HTTP status resulting from the request.