Web Smart Card API

When getting, the smartCard attribute always returns the same instance of the SmartCardResourceManager object.

When getting, the smartCard attribute always returns the same instance of the SmartCardResourceManager object.

Requests a PC/SC context from the platform's PC/SC stack.

1. If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "smart-card", throw a "SecurityError" DOMException.
2. Let promise be a new promise.
3. Run the following steps in parallel:
   1. Let resourceManager be a new instance of the platform's [PCSC5] RESOURCEMANAGER class.
   2. Invoke the EstablishContext method of resourceManager with a "system" Scope parameter.
   3. If the returned RESPONSECODE is not SCARD_S_SUCCESS, perform the following steps:
      1. Destroy resourceManager.
      2. Queue a global task on the relevant global object of this using the smart card task source to reject promise with a corresponding exception.
   4. Otherwise, perform the following steps:
      1. Let context be a new SmartCardContext whose [[resourceManager]] internal slot is set to resourceManager.
      2. Queue a global task on the relevant global object of this using the smart card task source to resolve promise with context.
4. Return promise.

The listReaders() method steps are:

1. Let promise be a new promise.
2. If this.[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. Set this.[[operationInProgress]] to true.
4. Run the following steps in parallel:
   1. Let resourceQuery be a new instance of the platform's [PCSC5] RESOURCEQUERY class, with this.[[resourceManager]] as its constructor input parameter.
   2. Let groups be the platform's [PCSC5] STR[] containing the list of group names that is equivalent to "all readers in the system" in that platform.
      Note
   3. Let pcscReaders be an empty STR[].
   4. Invoke the ListReaders method of resourceQuery with groups as input and pcscReaders as output parameters.
   5. Let responseCode be the returned RESPONSECODE.
   6. Destroy resourceQuery.
   7. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Clear the operationInProgress of this.
      2. If responseCode is not SCARD_S_SUCCESS:
         1. If responseCode is SCARD_E_NO_READERS_AVAILABLE, resolve promise with an empty sequence of DOMString.
            Note
         2. Otherwise, reject promise with an exception corresponding to responseCode.
      3. Otherwise, resolve promise with a sequence of DOMString equivalent to pcscReaders.
5. Return promise.

The getStatusChange(readerStates, options) method steps are:

1. Let promise be a new promise.
2. If this.[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If options["signal"] exists, run the following steps:
   1. Let signal be options["signal"].
   2. If signal is aborted, reject promise with signal's abort reason and return promise.
   3. Set this.[[signal]] to signal
   4. Add the Cancel the outstanding GetStatusChange algorithm to signal.
4. Let pcscTimeout be a [PCSC5] DWORD set to [PCSC5] INFINITE.
5. If options["timeout"] exists, set pcscTimeout to options["timeout"].
6. Let pcscReaderStates be a [PCSC5] SCARD_READERSTATE[] corresponding to readerStates.
7. Set this.[[operationInProgress]] to true.
8. Set this.[[tracker]] to a new instance of the platform's [PCSC5] SCARDTRACK class, with this.[[resourceManager]] as its constructor input parameter.
9. Run the following steps in parallel:
   1. Call this.[[tracker]].GetStatusChange() with pcscReaderStates and pcscTimeout as input parameters.
   2. Let responseCode be the returned [PCSC5] RESPONSECODE.
   3. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Set this.[[tracker]] to null.
      2. Clear the operationInProgress of this.
      3. Let abortReason be undefined.
      4. If this.[[signal]] is not null, run the following steps:
         1. If this.[[signal]] is aborted then set abortReason to this.[[signal]]'s abort reason.
         2. Remove the cancel the outstanding GetStatusChange algorithm from this.[[signal]].
         3. Set this.[[signal]] to null.
      5. If responseCode is not SCARD_S_SUCCESS, run the following steps:
         1. If responseCode is SCARD_E_CANCELLED and abortReason is not undefined then reject promise with abortReason.
         2. Otherwise, reject promise with an exception corresponding to responseCode.
         3. Return.
      6. Let readerStatesOut be a sequence of SmartCardReaderStateOut corresponding to pcscReaderStates.
      7. Resolve promise with readerStatesOut.
10. Return promise.

WebIDLdictionary SmartCardReaderStateIn {
  required DOMString readerName;
  required SmartCardReaderStateFlagsIn currentState;
  unsigned long currentCount;
};

WebIDLdictionary SmartCardReaderStateFlagsIn {
  boolean unaware = false;
  boolean ignore = false;
  boolean unavailable = false;
  boolean empty = false;
  boolean present = false;
  boolean exclusive = false;
  boolean inuse = false;
  boolean mute = false;
  boolean unpowered = false;
};

WebIDLdictionary SmartCardReaderStateOut {
  required DOMString readerName;
  required SmartCardReaderStateFlagsOut eventState;
  required unsigned long eventCount;
  ArrayBuffer answerToReset;
};

WebIDLdictionary SmartCardReaderStateFlagsOut {
  boolean ignore = false;
  boolean changed = false;
  boolean unavailable = false;
  boolean unknown = false;
  boolean empty = false;
  boolean present = false;
  boolean exclusive = false;
  boolean inuse = false;
  boolean mute = false;
  boolean unpowered = false;
};

WebIDLdictionary SmartCardGetStatusChangeOptions {
  DOMHighResTimeStamp timeout;
  AbortSignal signal;
};

The connect(readerName, accessMode, options) method steps are:

1. Let promise be a new promise.
2. If this.[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. Set this.[[operationInProgress]] to true.
4. Run the following steps in parallel:
   1. Let accessFlags be a [PCSC5] DWORD corresponding to accessMode.
   2. Let protocolFlags be a DWORD set to 0.
   3. If options["preferredProtocols"] exists, set protocolFlags to its corresponding flags.
   4. Let activeProtocol be a DWORD set to 0.
   5. Let comm be a new instance of the platform's [PCSC5] SCARDCOMM class, with this.[[resourceManager]] as its constructor parameter.
   6. Call comm.Connect() with readerName, accessFlags and protocolFlags as input and activeProtocol as output parameters.
   7. Let responseCode be the returned RESPONSECODE.
   8. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Clear the operationInProgress of this.
      2. If responseCode is not SCARD_S_SUCCESS:
         1. Destroy comm.
         2. Reject promise with an exception corresponding to responseCode and abort these steps.
      3. Let result be an empty SmartCardConnectResult dictionary.
      4. Let connection be a new SmartCardConnection.
      5. Append connection to this.[[connections]].
      6. Set connection.[[comm]] to comm.
      7. Set connection.[[context]] to this.
      8. Set connection.[[activeProtocol]] to activeProtocol.
      9. Set result["connection"] to connection.
      10. If activeProtocol is a valid protocol value, set result["activeProtocol"] to the corresponding SmartCardProtocol.
      11. Resolve promise with result.
5. Return promise.

WebIDLenum SmartCardProtocol {
  "raw",
  "t0",
  "t1"
};

WebIDLdictionary SmartCardConnectResult {
  required SmartCardConnection connection;
  SmartCardProtocol activeProtocol;
};

WebIDLenum SmartCardAccessMode {
  "shared",
  "exclusive",
  "direct"
};

WebIDLdictionary SmartCardConnectOptions {
  sequence<SmartCardProtocol> preferredProtocols;
};

To clear the operationInProgress of a SmartCardContext context, perform the following steps:

1. Assert: context.[[operationInProgress]] is true.
2. Set context.[[operationInProgress]] to false.
3. For each connection of context.[[connections]]:
   1. End any settled transaction of connection.
   2. If context.[[operationInProgress]] is true, abort there steps.

The cancel the outstanding GetStatusChange algorithm steps are:

1. Call this.[[tracker]].Cancel().

The high word of a [PCSC5] DWORD is the result of an unsigned right shift of 16 bits on that DWORD.

To set the high word of a [PCSC5] DWORD named dword to a given number n, perform the following steps.

1. Set dword to dword bitwise AND 0xFFFF.
2. Let shiftedN be the result of a left shift of 16 bits on n.
3. Set dword to dword bitwise OR shiftedN.

To add a flag f to a [PCSC5] DWORD flags, set flags to flags bitwise OR f.

A [PCSC5] DWORD flags has a flag f if flags bitwise AND f is f.

The disconnect(disposition) method steps are:

1. Let promise be a new promise.
2. If this.[[context]].[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If this.[[comm]] is null, reject promise with a "InvalidStateError" DOMException and return promise.
4. Set this.[[context]].[[operationInProgress]] to true.
5. Run the following steps in parallel:
   1. Call this.[[comm]].Disconnect() with a DWORD corresponding to disposition as input parameter.
   2. Let responseCode be the returned RESPONSECODE.
   3. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Clear the operationInProgress of this.[[context]].
      2. If responseCode is not SCARD_S_SUCCESS, reject promise with an exception corresponding to responseCode and abort these steps.
      3. Destroy this.[[comm]].
      4. Set this.[[comm]] to null.
      5. Resolve promise.
6. Return promise.

WebIDLenum SmartCardDisposition {
  "leave",
  "reset",
  "unpower",
  "eject"
};

The transmit(sendBuffer, options) method steps are:

1. Let promise be a new promise.
2. If this.[[context]].[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If this.[[comm]] is null, reject promise with a "InvalidStateError" DOMException and return promise.
4. Let protocol be a [PCSC5] DWORD set to this.[[activeProtocol]].
5. If options["protocol"] exists, set protocol to the DWORD corresponding to options["protocol"].
6. If protocol is not a valid protocol value, reject promise with a "InvalidStateError" DOMException and return promise.
7. Set this.[[context]].[[operationInProgress]] to true.
8. Let sendPci be the platform's [PCSC5] SCARD_IO_HEADER corresponding to this.[[activeProtocol]].
9. Let pcscSendBuffer be a [PCSC5] BYTE[] containing sendBuffer.
10. Let recvPci be the platform's SCARD_IO_HEADER equivalent of empty or null.
11. Let recvBuffer be a BYTE[] big enough to hold the largest [ISO7186-3] extended response APDU (65538 bytes).
12. Let recvLength be a DWORD set to 0.
13. Run the following steps in parallel:
    1. Call this.[[comm]].Transmit() with sendPci, pcscSendBuffer, recvPci, recvBuffer and recvLength as arguments.
    2. Let responseCode be the returned RESPONSECODE.
    3. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
       1. Clear the operationInProgress of this.[[context]].
       2. If responseCode is not SCARD_S_SUCCESS, reject promise with an exception corresponding to responseCode and abort these steps.
       3. Resolve promise with an ArrayBuffer containing the first recvLength bytes of recvBuffer.
14. Return promise.

WebIDLdictionary SmartCardTransmitOptions {
  SmartCardProtocol protocol;
};

The startTransaction(transaction, options) method steps are:

1. Let promise be a new promise.
2. If this.[[context]].[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If this.[[comm]] is null, reject promise with a "InvalidStateError" DOMException and return promise.
4. If this.[[transactionState]] is not null, reject promise with a "InvalidStateError" DOMException and return promise.
5. Let signal be an AbortSignal set to null.
6. If options["signal"] exists, run the following steps:
   1. If options["signal"] is aborted, reject promise with options["signal"]'s abort reason and return promise.
   2. Set signal to options["signal"].
   3. Add the cancel algorithm to signal.
7. Set this.[[context]].[[operationInProgress]] to true.
8. Run the following steps in parallel:
   1. Call this.[[comm]].BeginTransaction().
   2. Let responseCode be the returned [PCSC5] RESPONSECODE.
   3. Queue a global task on the relevant global object of this using the smart card task source to process the result of a BeginTransaction with this, responseCode, signal, transaction and promise.
9. Return promise.

WebIDLdictionary SmartCardTransactionOptions {
  AbortSignal signal;
};

The status() method steps are:

1. Let promise be a new promise.
2. If this.[[context]].[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If this.[[comm]] is null, reject promise with a "InvalidStateError" DOMException and return promise.
4. Set this.[[context]].[[operationInProgress]] to true.
5. Run the following steps in parallel:
   1. Let pcscReader be an empty STR[].
   2. Let pcscState be a [PCSC5] DWORD set to 0.
   3. Let activeProtocol be a [PCSC5] DWORD set to 0.
   4. Let pcscAtr be a BYTE[] big enough to hold any [ISO7186-3] Answer To Reset (ATR).
   5. Call this.[[comm]].Status() with pcscReader, pcscState, activeProtocol and pcscAtr as output parameters.
   6. Let responseCode be the returned RESPONSECODE.
   7. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Clear the operationInProgress of this.[[context]].
      2. If responseCode is not SCARD_S_SUCCESS, reject promise with an exception corresponding to responseCode and abort these steps.
      3. Let state be a SmartCardConnectionState corresponding to pcscState and activeProtocol.
      4. If state is undefined, reject promise with an "UnknownError" DOMException and abort these steps.
      5. Let status be a new SmartCardConnectionStatus.
      6. Set status["readerName"] to pcscReader.
      7. Set status["state"] to state.
      8. Set status["answerToReset"] to an ArrayBuffer with the bytes that were written to pcscAtr.
      9. Resolve promise with status.
6. Return promise.

WebIDLdictionary SmartCardConnectionStatus {
  required DOMString readerName;
  required SmartCardConnectionState state;
  ArrayBuffer answerToReset;
};

WebIDLenum SmartCardConnectionState {
  "absent",
  "present",
  "swallowed",
  "powered",
  "negotiable",
  "t0",
  "t1",
  "raw"
};

The control(controlCode, data) method steps are:

1. Let promise be a new promise.
2. If this.[[context]].[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If this.[[comm]] is null, reject promise with a "InvalidStateError" DOMException and return promise.
4. Set this.[[context]].[[operationInProgress]] to true.
5. Let pcscControlCode be a [PCSC5] DWORD containing controlCode.
6. Get a copy of the buffer source data and save the result in a [PCSC5] BYTE[] inBuffer.
7. Let outBuffer be a [PCSC5] BYTE[] large enough to hold any control command response.
8. Let outBufferLength be a DWORD set to 0.
9. Run the following steps in parallel:
   1. Call this.[[comm]].Control() with pcscControlCode, inBuffer, outBuffer and outBufferLength as arguments.
   2. Let responseCode be the returned RESPONSECODE.
   3. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Clear the operationInProgress of this.[[context]].
      2. If responseCode is not SCARD_S_SUCCESS, reject promise with an exception corresponding to responseCode and abort these steps.
      3. Let resultBytes be the first outBufferLength bytes of outBuffer.
      4. Resolve promise with the result of creating an ArrayBuffer from resultBytes in this's relevant Realm.
10. Return promise.

The getAttribute(tag) method steps are:

1. Let promise be a new promise.
2. If this.[[context]].[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If this.[[comm]] is null, reject promise with a "InvalidStateError" DOMException and return promise.
4. Set this.[[context]].[[operationInProgress]] to true.
5. Run the following steps in parallel:
   1. Let pcscTag be a [PCSC5] DWORD containing tag.
   2. Let buffer be a [PCSC5] BYTE[] large enough to hold this reader attribute, as determined by the platform's [PCSC5] implementation.
   3. Call this.[[comm]].GetReaderCapabilities() with pcscTag and buffer as arguments.
   4. Let responseCode be the returned RESPONSECODE.
   5. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Clear the operationInProgress of this.[[context]].
      2. If responseCode is not SCARD_S_SUCCESS, reject promise with an exception corresponding to responseCode and abort these steps.
      3. Let resultBytes be the bytes of buffer containing the attribute read.
      4. Resolve promise with the result of creating an ArrayBuffer from resultBytes in this's relevant Realm.
6. Return promise.

The setAttribute(tag, value) method steps are:

1. Let promise be a new promise.
2. If this.[[context]].[[operationInProgress]] is true, reject promise with a "InvalidStateError" DOMException and return promise.
3. If this.[[comm]] is null, reject promise with a "InvalidStateError" DOMException and return promise.
4. Set this.[[context]].[[operationInProgress]] to true.
5. Let pcscTag be a [PCSC5] DWORD containing tag.
6. Get a copy of the buffer source value and save the result in a [PCSC5] BYTE[] buffer.
7. Run the following steps in parallel:
   1. Call this.[[comm]].SetReaderCapabilities() with pcscTag and buffer as arguments.
   2. Let responseCode be the returned RESPONSECODE.
   3. Queue a global task on the relevant global object of this using the smart card task source which performs the following steps:
      1. Clear the operationInProgress of this.[[context]].
      2. If responseCode is not SCARD_S_SUCCESS, reject promise with an exception corresponding to responseCode and abort these steps.
      3. Resolve promise.
8. Return promise.

WebIDLdictionary SmartCardErrorOptions {
  required SmartCardResponseCode responseCode;
};

The responseCode member is the value for SmartCardError's responseCode attribute.

WebIDLenum SmartCardResponseCode {
  "no-service",
  "no-smartcard",
  "not-ready",
  "not-transacted",
  "proto-mismatch",
  "reader-unavailable",
  "removed-card",
  "reset-card",
  "server-too-busy",
  "sharing-violation",
  "system-cancelled",
  "unknown-reader",
  "unpowered-card",
  "unresponsive-card",
  "unsupported-card",
  "unsupported-feature"
};

no-service

SCARD_E_NO_SERVICE in the [PCSC5] spec.

no-smartcard

SCARD_E_NO_SMARTCARD in the [PCSC5] spec.

not-ready

SCARD_E_NOT_READY in the [PCSC5] spec.

not-transacted

SCARD_E_NOT_TRANSACTED in the [PCSC5] spec.

proto-mismatch

SCARD_E_PROTO_MISMATCH in the [PCSC5] spec.

reader-unavailable

SCARD_E_READER_UNAVAILABLE in the [PCSC5] spec.

removed-card

SCARD_W_REMOVED_CARD in the [PCSC5] spec.

reset-card

SCARD_W_RESET_CARD in the [PCSC5] spec.

server-too-busy

The smart card resource manager is too busy to complete this operation.

sharing-violation

SCARD_E_SHARING_VIOLATION in the [PCSC5] spec.

system-cancelled

SCARD_E_SYSTEM_CANCELLED in the [PCSC5] spec.

unknown-reader

SCARD_E_UNKNOWN_READER in the [PCSC5] spec.

unpowered-card

SCARD_W_UNPOWERED_CARD in the [PCSC5] spec.

unresponsive-card

SCARD_W_UNRESPONSIVE_CARD in the [PCSC5] spec.

unsupported-card

SCARD_W_UNSUPPORTED_CARD in the [PCSC5] spec.

unsupported-feature

SCARD_E_UNSUPPORTED_FEATURE in the [PCSC5] spec.

Access to a smart card reader and any card present within it is a powerful feature. A user agent MUST NOT allow a web application to gain access to a SmartCardConnection object without express permission.

User consent MUST be obtained for a specific origin. The request for consent MUST be triggered by a call to the connect() method. The user agent MUST display a permission prompt that clearly indicates which origin is requesting access and provides the user with enough information to make an informed decision (for example, by displaying the name of the smart card reader).

User agents SHOULD provide options for both transient (e.g., "for this session only") and persistent permission. To mitigate the risk of users forgetting they have granted persistent access, transient permission SHOULD be the default and more prominent option.

Users MUST be provided with a mechanism to view and revoke any previously granted permissions for this API.

The listReaders() method and the answerToReset member of the SmartCardReaderStateOut dictionary expose information that can be used for passive fingerprinting. The presence and model of smart card readers can reveal information about the user, such as whether they are in a corporate environment. The Answer to Reset (ATR) can further identify the type and issuer of a smart card.

While this specification does not require a permission prompt before calling listReaders(), access to the entire API is controlled by the "smart-card" policy-controlled feature. This allows administrators or users to disable the API for specific origins, mitigating the fingerprinting risk.

The control() and setAttribute() methods provide direct, low-level access to the smart card reader hardware. A malicious site could potentially use these methods to upload malicious firmware, render the device inoperable, or otherwise interfere with its normal operation.

Similarly, a malicious site with a connection to a smart card could repeatedly attempt PIN verification to permanently block the card, or access or overwrite sensitive, unprotected data.

The primary mitigation for these threats is the requirement for express permission before a SmartCardConnection object is created, as this gates access to all subsequent powerful methods.

For authentication use cases, developers SHOULD prefer using the Web Authentication API wherever possible.

A smart card with writable memory could be used as a side-channel for different origins to exchange data, bypassing other same-origin policies. The mitigation for this is that express permission is granted to a specific origin. An attack would require the user to grant smart card access to multiple, potentially malicious, origins.

This API MUST only be exposed in an isolated context.

To prevent documents from holding connections to sensitive hardware while not in the user's direct control, a user agent MUST dispose of all active SmartCardContext objects and their associated SmartCardConnections when a document is no longer fully active. This includes automatically disconnecting any active connections as if disconnect() were called.

This specification defines a feature that controls whether the methods exposed by the smartCard attribute on the Navigator object may be used.

The feature name for this feature is "smart-card".

The default allowlist for this feature is 'none'. User agents MAY override this to 'self' for particular origins (for example based on user decision).