// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use this API to give the browser access to a winscard.h[1] compatible
// PC/SC[2] implementation, which will be the backend of the browser's
// Web Smart Card API[3].
//
// [1] https://pcsclite.apdu.fr/api/winscard_8h.html
// [2] https://en.wikipedia.org/wiki/PC/SC
// [3] https://github.com/WICG/web-smart-card/blob/main/README.md#web-idl
//
// TODO(crbug.com/40247152): Add API for the remaining SCard* functions.
[platforms=("chromeos", "lacros"),
implemented_in="chrome/browser/chromeos/extensions/smart_card_provider_private/smart_card_provider_private_api.h"]
namespace smartCardProviderPrivate {
// PC/SC error codes we can expect to hit (thus a non-exhaustive list).
// UNKNOWN means an SCARD error code that is not mapped in this enum (and
// thus should probably be added here).
enum ResultCode {
SUCCESS,
REMOVED_CARD,
RESET_CARD,
UNPOWERED_CARD,
UNRESPONSIVE_CARD,
UNSUPPORTED_CARD,
READER_UNAVAILABLE,
SHARING_VIOLATION,
NOT_TRANSACTED,
NO_SMARTCARD,
PROTO_MISMATCH,
SYSTEM_CANCELLED,
NOT_READY,
CANCELLED,
INSUFFICIENT_BUFFER,
INVALID_HANDLE,
INVALID_PARAMETER,
INVALID_VALUE,
NO_MEMORY,
TIMEOUT,
UNKNOWN_READER,
UNSUPPORTED_FEATURE,
NO_READERS_AVAILABLE,
SERVICE_STOPPED,
NO_SERVICE,
COMM_ERROR,
INTERNAL_ERROR,
UNKNOWN_ERROR,
SERVER_TOO_BUSY,
UNEXPECTED,
SHUTDOWN,
UNKNOWN
};
// Maps to the SCARD_SHARE_* values defined in the winscard.h API.
enum ShareMode {
SHARED,
EXCLUSIVE,
DIRECT
};
// What the reader should do with the card inserted in it.
enum Disposition {
// SCARD_LEAVE_CARD - Do nothing.
LEAVE_CARD,
// SCARD_RESET_CARD - Reset the card (warm reset).
RESET_CARD,
// SCARD_UNPOWER_CARD - Power down the card (cold reset).
UNPOWER_CARD,
// SCARD_EJECT_CARD - Eject the card.
EJECT_CARD
};
enum ConnectionState {
// SCARD_ABSENT
ABSENT,
// SCARD_PRESENT
PRESENT,
// SCARD_SWALLOWED
SWALLOWED,
// SCARD_POWERED
POWERED,
// SCARD_NEGOTIABLE
NEGOTIABLE,
// SCARD_SPECIFIC
SPECIFIC
};
// Maps to the SCARD_STATE_* flags defined in the winscard.h API.
dictionary ReaderStateFlags {
boolean? unaware;
boolean? ignore;
boolean? changed;
boolean? unknown;
boolean? unavailable;
boolean? empty;
boolean? present;
boolean? exclusive;
boolean? inuse;
boolean? mute;
boolean? unpowered;
};
// Maps to the SCARD_PROTOCOL_* flags defined in the winscard.h API.
dictionary Protocols {
boolean? t0;
boolean? t1;
boolean? raw;
};
// Maps to the SCARD_PROTOCOL_* values defined in the winscard.h API.
enum Protocol {
UNDEFINED,
T0,
T1,
RAW
};
dictionary ReaderStateIn {
DOMString reader;
ReaderStateFlags currentState;
// Number of card insertion and removal events that happened in this reader,
// as known by the application.
long currentCount;
};
dictionary ReaderStateOut {
DOMString reader;
ReaderStateFlags eventState;
// The actual number of card insertion and removal events that happened in
// this reader.
// Set to zero if not supported.
long eventCount;
ArrayBuffer atr;
};
dictionary Timeout {
// If absent, it means "infinite" or "never timeout"
long? milliseconds;
};
interface Events {
// Browser requested a SCardEstablishContext call.
// Extension must report the result to the browser by calling
// reportEstablishContextResult.
[maxListeners=1] static void onEstablishContextRequested(long requestId);
// Browser requested a SCardReleaseContext call.
// Extension must report the result to the browser by calling
// reportReleaseContextResult.
[maxListeners=1] static void onReleaseContextRequested(long requestId,
long scardContext);
// Browser requested a SCardListReaders call.
// Extension must report the result to the browser by calling
// reportListReadersResult.
[maxListeners=1] static void onListReadersRequested(long requestId,
long scardContext);
// Browser requested a SCardGetStatusChange call.
// Extension must report the result to the browser by calling
// reportGetStatusChangeResult.
[maxListeners=1] static void onGetStatusChangeRequested(long requestId,
long scardContext,
Timeout timeout,
ReaderStateIn[] readerStates);
// Browser requested a SCardCancel call.
// Extension must report the result to the browser by calling
// reportPlainResult.
[maxListeners=1] static void onCancelRequested(long requestId,
long scardContext);
// Browser requested a SCardConnect call.
// Extension must report the result to the browser by calling
// reportConnectResult.
[maxListeners=1] static void onConnectRequested(long requestId,
long scardContext,
DOMString reader,
ShareMode shareMode,
Protocols preferredProtocols);
// Browser requested a SCardDisconnect call.
// Extension must report the result to the browser by calling
// reportPlainResult.
[maxListeners=1] static void onDisconnectRequested(long requestId,
long scardHandle, Disposition disposition);
// Browser requested a SCardTransmit call.
// Extension must report the result to the browser by calling
// reportDataResult.
[maxListeners=1] static void onTransmitRequested(long requestId,
long scardHandle, Protocol protocol, ArrayBuffer data);
// Browser requested a SCardControl call.
// Extension must report the result to the browser by calling
// reportDataResult.
[maxListeners=1] static void onControlRequested(long requestId,
long scardHandle, long controlCode, ArrayBuffer data);
// Browser requested a SCardGetAttrib call.
// Extension must report the result to the browser by calling
// reportDataResult.
[maxListeners=1] static void onGetAttribRequested(long requestId,
long scardHandle, long attribId);
// Browser requested a SCardSetAttrib call.
// Extension must report the result to the browser by calling
// reportPlainResult.
[maxListeners=1] static void onSetAttribRequested(long requestId,
long scardHandle, long attribId, ArrayBuffer data);
// Browser requested a SCardStatus call.
// Extension must report the result to the browser by calling
// reportStatusResult.
[maxListeners=1] static void onStatusRequested(long requestId,
long scardHandle);
// Browser requested a SCardBeginTransaction call.
// Extension must report the result to the browser by calling
// reportPlainResult.
[maxListeners=1] static void onBeginTransactionRequested(long requestId,
long scardHandle);
// Browser requested a SCardEndTransaction call.
// Extension must report the result to the browser by calling
// reportPlainResult.
[maxListeners=1] static void onEndTransactionRequested(long requestId,
long scardHandle, Disposition disposition);
};
interface Functions {
// Reports the result of a SCardEstablishContext call.
static void reportEstablishContextResult(long requestId,
long scardContext, ResultCode resultCode);
// Reports the result of a SCardReleaseContext call.
static void reportReleaseContextResult(long requestId,
ResultCode resultCode);
// Reports the result of a SCardListReaders call.
static void reportListReadersResult(long requestId,
DOMString[] readers, ResultCode resultCode);
// Reports the result of a SCardGetStatusChange call.
static void reportGetStatusChangeResult(long requestId,
ReaderStateOut[] readerStates, ResultCode resultCode);
// Reports the result of a call which doesn't send back any other
// information.
static void reportPlainResult(long requestId,
ResultCode resultCode);
// Reports the result of a SCardConnect call.
static void reportConnectResult(long requestId, long scardHandle,
Protocol activeProtocol, ResultCode resultCode);
// Reports the result of a call that sends back data on success.
static void reportDataResult(long requestId, ArrayBuffer data,
ResultCode resultCode);
// Reports the result of a SCardStatus call.
static void reportStatusResult(long requestId, DOMString readerName,
ConnectionState state, Protocol protocol, ArrayBuffer atr,
ResultCode resultCode);
};
};
Codebase Browser
chromium