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_HOST_MEMORY": Not enough memory on the host computer.

  • "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_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_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.

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

  • "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_FUNCTION_NOT_PERMITTED": The key does not support this operation.

  • "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": The PIN has been blocked

  • "CKR_SIGNATURE_INVALID": The digital signature in invalid.

  • "CKR_SIGNATURE_LEN_RANGE": The length od the digital signature is incorrect.

  • "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_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_INFORMATION_SENSITIVE": The information is private and cannot be revealed.

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

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

  • "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.

Error.httpStatus

HTTP status resulting from the request.