services/device/public/mojom/smart_card.mojom

// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// The purpose of these mojo interfaces is to expose the platform's PC/SC
// implementation (according to "Interoperability Specification for ICCs and
// Personal Computer Systems; Part 5 ICC Resource Manager Definition") as close
// as possible, exposing the same concepts and functionality.
//
// See https://pcscworkgroup.com/specifications/download/
// And its authoritative implementation, winscard.h:
// https://learn.microsoft.com/en-us/windows/win32/api/winscard/

module device.mojom;

import "mojo/public/mojom/base/time.mojom";

// The result of a SmartCard request.
// Either a success or an error.
union SmartCardResult {
  SmartCardSuccess success;
  SmartCardError error;
};

// Indicates that a SmartCard request succeeded.
enum SmartCardSuccess {
  kOk
};

// Possible error results for a SmartCard* request.
enum SmartCardError {
  // PC/SC error codes we can expect to hit (thus a non-exhaustive list):
  kRemovedCard,
  kResetCard,
  kUnpoweredCard,
  kUnresponsiveCard,
  kUnsupportedCard,
  kReaderUnavailable,
  kSharingViolation,
  kNotTransacted,
  kNoSmartcard,
  kProtoMismatch,
  kSystemCancelled,
  kNotReady,
  kCancelled,
  kInsufficientBuffer,
  kInvalidHandle,
  kInvalidParameter,
  kInvalidValue,
  kNoMemory,
  kTimeout,
  kUnknownReader,
  kUnsupportedFeature,
  kNoReadersAvailable,
  kServiceStopped,
  kNoService,
  kCommError,
  kInternalError,
  kUnknownError,
  kServerTooBusy,
  kUnexpected,
  kShutdown,

  // UNKNOWN means an SCARD_* (PC/SC) error code that is not mapped in this enum
  // (and thus should probably be added above):
  kUnknown,

  // This request is covered by a permission check and the user has denied it.
  kPermissionDenied
};

// Share mode of a connection.
enum SmartCardShareMode {
  // SCARD_SHARE_SHARED
  kShared,
  // SCARD_SHARE_EXCLUSIVE
  kExclusive,
  // SCARD_SHARE_DIRECT
  kDirect
};

// Communication protocol for a connection to a smart card.
enum SmartCardProtocol {
  // SCARD_PROTOCOL_UNDEFINED
  kUndefined,
  // SCARD_PROTOCOL_T0
  // T=0 protocol
  kT0,
  // SCARD_PROTOCOL_T1
  // T=1 protocol
  kT1,
  // SCARD_PROTOCOL_RAW
  kRaw
};

// Action to take after disconnecting.
enum SmartCardDisposition {
  // SCARD_LEAVE_CARD - Do nothing.
  kLeave,
  // SCARD_RESET_CARD - Reset the card (warm reset).
  kReset,
  // SCARD_UNPOWER_CARD - Power down the card (cold reset).
  kUnpower,
  // SCARD_EJECT_CARD - Eject the card.
  kEject
};

// State of a SmartCardConnection.
// Note that there's quite some overlap with SmartCardReaderStateFlags.
// But that's what PC/SC does.
enum SmartCardConnectionState {
  // SCARD_ABSENT
  kAbsent,
  // SCARD_PRESENT
  kPresent,
  // SCARD_SWALLOWED
  kSwallowed,
  // SCARD_POWERED
  kPowered,
  // SCARD_NEGOTIABLE
  kNegotiable,
  // SCARD_SPECIFIC
  kSpecific
};

// Flags for describing the state of a smart card reader.
// Maps to the corresponding SCARD_STATE_* flags in winscard.h
struct SmartCardReaderStateFlags {
  bool unaware;
  bool ignore;
  bool changed;
  bool unknown;
  bool unavailable;
  bool empty;
  bool present;
  bool exclusive;
  bool inuse;
  bool mute;
  bool unpowered;
};

// Describes the last known state of a smart card reader.
// SmartCardContext uses that information to decide whether the reader state
// has changed (ie, whether it's different from what the API user knows).
struct SmartCardReaderStateIn {
  string reader;
  SmartCardReaderStateFlags current_state;
  // Number of card insertion and removal events that happened in this reader,
  // as known by the application.
  uint16 current_count;
};

// Describes the actual state of a smart card reader.
struct SmartCardReaderStateOut {
  string reader;
  SmartCardReaderStateFlags event_state;
  // Number of card insertion and removal events that happened in this reader.
  // Will always be zero if not supported by the platform.
  uint16 event_count;
  array<uint8> answer_to_reset;
};

// Preferred protocols.
struct SmartCardProtocols {
  // SCARD_PROTOCOL_T0
  bool t0;
  // SCARD_PROTOCOL_T1
  bool t1;
  // SCARD_PROTOCOL_RAW
  bool raw;
};

// Status of a SmartCardConnection.
struct SmartCardStatus {
  string reader_name;
  SmartCardConnectionState state;
  SmartCardProtocol protocol;
  array<uint8> answer_to_reset;
};

// The result of a SmartCardContext.GetStatusChange request.
union SmartCardStatusChangeResult {
  array<SmartCardReaderStateOut> reader_states;
  SmartCardError error;
};

// The result of a SmartCardContext.ListReaders request.
union SmartCardListReadersResult {
  array<string> readers;
  SmartCardError error;
};

// The result of a SmartCardContextFactory.CreateContext request.
union SmartCardCreateContextResult {
  pending_remote<SmartCardContext> context;
  SmartCardError error;
};

// The result of a SmartCardContext.Connect request in
// case of success.
struct SmartCardConnectSuccess {
  pending_remote<SmartCardConnection> connection;
  SmartCardProtocol active_protocol;
};

// The result of a SmartCardContext.Connect request.
union SmartCardConnectResult {
  SmartCardConnectSuccess success;
  SmartCardError error;
};

// Result of a PC/SC request that sends back data on success.
// Otherwise, an error.
union SmartCardDataResult {
  array<uint8> data;
  SmartCardError error;
};

// The result of a SmartCardConnection.Status request.
union SmartCardStatusResult {
  SmartCardStatus status;
  SmartCardError error;
};

// The result of a SmartCardConnection.BeginTransaction request.
union SmartCardTransactionResult {
  pending_associated_remote<SmartCardTransaction> transaction;
  SmartCardError error;
};

// An interface to a transaction.
// All commands sent through the related SmartCardConnection will be part of
// this transaction.
interface SmartCardTransaction {
  // Ends a logical transaction, allowing other applications to resume
  // interactions with that card.
  // Upon termination, the action indicated by `disposition` is performed.
  EndTransaction(SmartCardDisposition disposition) => (SmartCardResult result);
};

// An interface to a valid connection (SCARDHANDLE) within a context
// in a PC/SC (winscard.h) provider.
interface SmartCardConnection {
  // Terminates the connection and leaves the card in the given `disposition`.
  Disconnect(SmartCardDisposition disposition)
      => (SmartCardResult result);

  // Sends an APDU to the smart card and receives a response back from it.
  Transmit(SmartCardProtocol protocol, array<uint8> data)
      => (SmartCardDataResult result);

  // Sends a command directly to the Interface Device (IFD) Handler (reader
  // driver) to be processed by the reader.
  Control(uint32 control_code, array<uint8> data)
      => (SmartCardDataResult result);

  // Gets an attribute from the Interface Device Handler (reader driver).
  GetAttrib(uint32 id) => (SmartCardDataResult result);

  // Sets an attribute of the Interface Device Handler.
  SetAttrib(uint32 id, array<uint8> data) => (SmartCardResult result);

  // Returns the status of the connected reader.
  Status() => (SmartCardStatusResult result);

  // Initiates a logical transaction against the card in the reader associated
  // with this connection. If successful, this blocks other applications from
  // accessing the card, allowing the calling application to perform a sequence
  // of operations against the card with assurance that any intermediate state
  // information will remain valid.
  //
  // On Windows, if a transaction is held on the card for more than five seconds
  // with no operations happening on that card, then the card is reset.
  BeginTransaction() => (SmartCardTransactionResult result);
};

// An interface to a valid context in a PC/SC (winscard.h) provider.
//
// Dropping a remote of this interface equates to calling SCardReleaseContext()
// on the corresponding PC/SC provider.
interface SmartCardContext {
  // Returns a list of currently available readers on the system.
  ListReaders() => (SmartCardListReadersResult result);

  // Waits until the current availability of the cards in a specific set of
  // readers changes.
  GetStatusChange(mojo_base.mojom.TimeDelta timeout,
                  array<SmartCardReaderStateIn> reader_states)
    => (SmartCardStatusChangeResult result);

  // Terminates an outstanding GetStatusChange() call with
  // SmartCardError::kCancelled.
  Cancel() => (SmartCardResult result);

  // Establishes a connection to the specified reader.
  Connect(string reader, SmartCardShareMode share_mode,
          SmartCardProtocols preferred_protocols) =>
    (SmartCardConnectResult result);
};

// An interface to establish contexts with a PC/SC (winscard.h) provider.
interface SmartCardContextFactory {
  // Creates an Application Context to the PC/SC Resource Manager.
  CreateContext() => (SmartCardCreateContextResult result);
};