chrome/common/extensions/api/smart_card_provider_private.idl

// 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"),
 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);
  };
};