path: root/chrome/common/extensions/api/easy_unlock_private.idl

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

// <code>chrome.easyUnlockPrivate</code> API that provides hooks to Chrome to
// be used by Easy Unlock component app.
namespace easyUnlockPrivate {
  // Signature algorithms supported by the crypto library methods used by
  // Easy Unlock.
  enum SignatureType {
    HMAC_SHA256,
    ECDSA_P256_SHA256
  };

  // Encryption algorithms supported by the crypto library methods used by
  // Easy Unlock.
  enum EncryptionType {
    AES_256_CBC
  };

  // Available states for the Easy Unlock app.
  enum State {
    // Screen is either not locked, or the Easy Unlock is not enabled.
    INACTIVE,
    // The Bluetooth is not enabled.
    NO_BLUETOOTH,
    // Bluetooth is being activated.
    BLUETOOTH_CONNECTING,
    // There are no phones eligible to unlock the device.
    NO_PHONE,
    // A phone eligible to unlock the device is detected, but can't be
    // authenticated.
    PHONE_NOT_AUTHENTICATED,
    // A phone eligible to unlock the device is detected, but it's locked and
    // thus unable to unlock the device.
    PHONE_LOCKED,
    // A phone eligible to unlock the device is detected, but it is not allowed
    // to unlock the device because it doesn't have lock screen enabled.
    PHONE_UNLOCKABLE,
    // A phone eligible to unlock the device is detected, but it is not allowed
    // to unlock the device because it does not report its lock screen state.
    PHONE_UNSUPPORTED,
    // A phone eligible to unlock the device is detected, but its received
    // signal strength is too low, i.e. the phone is roughly more than 30 feet
    // away, and therefore is not allowed to unlock the device.
    RSSI_TOO_LOW,
    // A phone eligible to unlock the device is found, but the local device's
    // transmission power is too high, indicating that the phone is (probably)
    // more than 1 foot away, and therefore is not allowed to unlock the device.
    TX_POWER_TOO_HIGH,
    // A phone eligible to unlock the device is found; but (a) the phone is
    // locked, and (b) the local device's transmission power is too high,
    // indicating that the phone is (probably) more than 1 foot away, and
    // therefore is not allowed to unlock the device.
    PHONE_LOCKED_AND_TX_POWER_TOO_HIGH,
    // The device can be unlocked using Easy Unlock.
    AUTHENTICATED
  };

  // Type of a permit. All lower case to match permit.PermitRecord.Type.
  enum PermitType {access, license};

  enum ConnectionStatus {DISCONNECTED, IN_PROGRESS, CONNECTED};

  // Options that can be passed to |unwrapSecureMessage| method.
  dictionary UnwrapSecureMessageOptions {
    // The data associated with the message. For the message to be succesfully
    // verified, the message should have been created with the same associated
    // data.
    ArrayBuffer? associatedData;

    // The encryption algorithm that should be used to decrypt the message.
    // Should not be set for a cleartext message.
    EncryptionType? encryptType;

    // The algorithm to be used to verify signature contained in the message.
    // Defaults to |HMAC_SHA256|. |ECDSA_P256_SHA256| can currently be used
    // only with cleartext messages.
    SignatureType? signType;
  };

  dictionary CreateSecureMessageOptions {
    // Data associated with the message. The data will not be sent with the
    // message, but the message recepient will use the same data on its side
    // to verify the message.
    ArrayBuffer? associatedData;

    // Metadata to be added to the message header.
    ArrayBuffer? publicMetadata;

    // Verification key id added to the message header. Should be set if the
    // message is signed using |ECDSA_P256_SHA256|. Used by the message
    // recepient to determine which key should be used to verify the message
    // signature.
    ArrayBuffer? verificationKeyId;

    // Decryption key id added to the message header. Used by the message
    // recepient to determine which key should be used to decrypt the message.
    ArrayBuffer? decryptionKeyId;

    // The encryption algorithm that should be used to encrypt the message.
    // Should not be set for a cleartext message.
    EncryptionType? encryptType;

    // The algorithm to be used to sign the message.
    // Defaults to |HMAC_SHA256|. |ECDSA_P256_SHA256| can currently be used
    // only with cleartext messages.
    SignatureType? signType;
  };

  // A permit record contains the credentials used to request or grant
  // authorization of a permit.
  dictionary PermitRecord {
    // ID of the permit, which identifies the service/application that these
    // permit records are used in.
    DOMString permitId;

    // An identifier for this record that should be unique among all other
    // records of the same permit.
    DOMString id;

    // Type of the record.
    PermitType type;

    // Websafe base64 encoded payload data of the record.
    DOMString data;
  };

  // Device information that can be authenticated for Easy unlock.
  dictionary Device {
    // The Bluetooth address of the device.
    DOMString bluetoothAddress;

    // The name of the device.
    DOMString? name;

    // The permit record of the device.
    PermitRecord? permitRecord;

    // Websafe base64 encoded persistent symmetric key.
    DOMString? psk;
  };

  // The information about a user associated with Easy unlock service.
  dictionary UserInfo {
    // The user id.
    DOMString userId;

    // A stable identifier for the user and device. If a user is removed and
    // added to the same device, this id will remain the same. However, this id
    // will be different if another user is added to the same device or if the
    // same user is added on another device.
    DOMString deviceUserId;

    // Whether the user is logged in. If not logged in, the app is running on
    // the signin screen.
    boolean loggedIn;

    // Whether to require the remote device to be in very close proximity before
    // allowing unlock (~1 feet).
    boolean requireCloseProximity;

    // Whether all data needed to use Easy unlock service has been loaded for
    // the user.
    boolean dataReady;

    // Whether the |kEnableBluetoothLowEnergyDiscovery| switch is enabled.
    boolean bleDiscoveryEnabled;
  };

  // A range.
  dictionary Range {
    long start;
    long end;
  };

  // A rectangle, in screen coordinates, measured in device-independent pixels.
  dictionary Rect {
    long left;
    long top;
    long width;
    long height;
  };

  // Auto pairing reuslt.
  dictionary AutoPairingResult {
    // Whether the auto pairing is completed successfully.
    boolean success;

    // Optional error message to indicate the failure.
    DOMString? errorMessage;
  };

  // Callback for crypto methods that return a single array buffer.
  callback DataCallback = void(optional ArrayBuffer data);

  // An empty callback used purely for signalling success vs. failure.
  callback EmptyCallback = void();

  // Callback for the getStrings() method.
  callback GetStringsCallback = void(object strings);

  // Callback for method that generates an encryption key pair.
  callback KeyPairCallback = void(optional ArrayBuffer public_key,
                                  optional ArrayBuffer private_key);

  // Callback for the getPermitAccess() method.
  callback GetPermitAccessCallback = void(optional PermitRecord permitAccess);

  // Callback for the getRemoteDevices() method.
  callback GetRemoteDevicesCallback = void(Device[] devices);

  // Callback for the |getUserInfo()| method. Note that the callback argument is
  // a list for future use (on signin screen there may be more than one user
  // associated with the easy unlock service). Currently the method returns at
  // most one user.
  callback GetUserInfoCallback = void(UserInfo[] users);

  // Callback for |getSignInChallenge()| method.
  // In case challenge could not be created both |challenge| and |signedNonce|
  // will be empty.
  // If the requested nonce could not be signed, |signedNonce| will be empty.
  // |challenge|: The sign in challenge to be used when signing in the user
  //     currently associated with the Easy Unlock service.
  // |signedNonce|: Nonce signed by Chrome OS TPM, provided as an argument to
  //     the |getSignInChallenge()| function and signed by the TPM key
  //     associated with the user.
  callback SignInChallengeCallback = void(optional ArrayBuffer challenge,
                                          optional ArrayBuffer signedNonce);

  // Callback for the |getConnectionInfo()| method.
  // |rssi|: The received signal strength from the remote device in dB.
  // |transmit_power| The local transmission power to the remote device in dB.
  // |max_transmit_power| The maximum transmission power that can be achieved.
  callback ConnectionInfoCallback = void(
      long rssi, long transmit_power, long max_transmit_power);

  // Callback for the |FindSetupConnectionCallback| method.
  // |connectionId|: The identifier of the connection found. To be used in
  // future calls refering to this connection.
  // |deviceAddress|: The Bluetooth address of the remote device.
  callback FindSetupConnectionCallback = void(long connectionId,
                                              DOMString deviceAddress);

  // Callback for the |setupConnectionStatus()| method.
  // |status|: The status of the connection with |connection_id|.
  callback SetupConnectionStatusCallback = void(ConnectionStatus status);

  // Callback for the |setupConnectionGetDeviceAddress()| method.
  // |deviceAddress|: The bluetooth address of the connection with 
  // |connectionId|.
  callback SetupConnectionGetDeviceAddressCallback = void(
      DOMString deviceAddress);

  interface Functions {
    // Gets localized strings required to render the API.
    //
    // |callback| : Called with a dictionary mapping names to resource strings.
    // TODO(isherman): This is essentially copied from identity_private.idl.
    //                 Perhaps this should be extracted to a common API instead?
    static void getStrings(GetStringsCallback callback);

    // Generates a ECDSA key pair for P256 curve.
    // Public key will be in format recognized by secure wire transport protocol
    // used by Easy Unlock app. Otherwise, the exact format for both key should
    // should be considered obfuscated to the app. The app should not use them
    // directly, but through this API.
    // |callback|: Callback with the generated keys. On failure, none of the
    //     keys will be set.
    static void generateEcP256KeyPair(KeyPairCallback callback);

    // Given a private key and a public ECDSA key from different asymetric key
    // pairs, it generates a symetric encryption key using EC Diffie-Hellman
    // scheme.
    // |privateKey|: A private key generated by the app using
    //     |generateEcP256KeyPair|.
    // |publicKey|: A public key that should be in the same format as the
    //     public key generated by |generateEcP256KeyPair|. Generally not the
    //     one paired with |private_key|.
    // |callback|: Function returning the generated secret symetric key.
    //     On failure, the returned value will not be set.
    static void performECDHKeyAgreement(ArrayBuffer privateKey,
                                        ArrayBuffer publicKey,
                                        DataCallback callback);

    // Creates a secure, signed message in format used by Easy Unlock app to
    // establish secure communication channel over unsecure connection.
    // |payload|: The payload the create message should carry.
    // |key|: The key used to sign the message content. If encryption algorithm
    //     is set in |options| the same key will be used to encrypt the message.
    // |options|: Additional (optional) parameters used to create the message.
    // |callback|: Function returning the created message bytes. On failure,
    //     the returned value will not be set.
    static void createSecureMessage(
        ArrayBuffer payload,
        ArrayBuffer key,
        CreateSecureMessageOptions options,
        DataCallback callback);

    // Authenticates and, if needed, decrypts a secure message. The message is
    // in the same format as the one created by |createSecureMessage|.
    // |secureMessage|: The message to be unwrapped.
    // |key|: Key to be used to authenticate the message sender. If encryption
    //     algorithm is set in |options|, the same key will be used to decrypt
    //     the message.
    // |options|: Additional (optional) parameters used to unwrap the message.
    // |callback|: Function returning an array buffer containing cleartext
    //     message header and body. They are returned in a single buffer in
    //     format used inside the message. If the massage authentication or
    //     decryption fails, the returned value will not be set.
    static void unwrapSecureMessage(
        ArrayBuffer secureMessage,
        ArrayBuffer key,
        UnwrapSecureMessageOptions options,
        DataCallback callback);

    // Connects to the SDP service on a device, given just the device's
    // Bluetooth address. This function is useful as a faster alternative to
    // Bluetooth discovery, when you already know the remote device's Bluetooth
    // address. A successful call to this function has the side-effect of
    // registering the device with the Bluetooth daemon, making it available for
    // future outgoing connections.
    // |deviceAddress|: The Bluetooth address of the device to connect to.
    // |callback|: Called to indicate success or failure.
    static void seekBluetoothDeviceByAddress(DOMString deviceAddress,
                                             optional EmptyCallback callback);

    // Connects the socket to a remote Bluetooth device over an insecure
    // connection, i.e. a connection that requests no bonding and no
    // man-in-the-middle protection. Other than the reduced security setting,
    // behaves identically to the chrome.bluetoothSocket.connect() function.
    // |socketId|: The socket identifier, as issued by the
    //     chrome.bluetoothSocket API.
    // |deviceAddress|: The Bluetooth address of the device to connect to.
    // |uuid|: The UUID of the service to connect to.
    // |callback|: Called when the connect attempt is complete.
    static void connectToBluetoothServiceInsecurely(long socketId,
                                                    DOMString deviceAddress,
                                                    DOMString uuid,
                                                    EmptyCallback callback);

    // Updates the screenlock state to reflect the Easy Unlock app state.
    static void updateScreenlockState(State state,
                                      optional EmptyCallback callback);

    // Saves the permit record for the local device.
    // |permitAccess|: The permit record to be saved.
    // |callback|: Called to indicate success or failure.
    static void setPermitAccess(PermitRecord permitAccess,
                                optional EmptyCallback callback);

    // Gets the permit record for the local device.
    static void getPermitAccess(GetPermitAccessCallback callback);

    // Clears the permit record for the local device.
    static void clearPermitAccess(optional EmptyCallback callback);

    // Saves the remote device list.
    // |devices|: The list of remote devices to be saved.
    // |callback|: Called to indicate success or failure.
    static void setRemoteDevices(Device[] devices,
                                 optional EmptyCallback callback);

    // Gets the remote device list.
    static void getRemoteDevices(GetRemoteDevicesCallback callback);

    // Gets the sign-in challenge for the current user.
    // |nonce|: Nonce that should be signed by the Chrome OS TPM. The signed
    //     nonce is returned with the sign-in challenge.
    static void getSignInChallenge(ArrayBuffer nonce,
                                   SignInChallengeCallback callback);

    // Tries to sign-in the current user with a secret obtained by decrypting
    // the sign-in challenge. Check chrome.runtime.lastError for failures. Upon
    // success, the user session will be started.
    static void trySignInSecret(ArrayBuffer signInSecret,
                                EmptyCallback callback);

    // Retrieves information about the user associated with the Easy unlock
    // service.
    static void getUserInfo(GetUserInfoCallback callback);

    // Gets the connection info for the Bluetooth device identified by
    // deviceAddress.
    static void getConnectionInfo(DOMString deviceAddress,
                                  ConnectionInfoCallback callback);

    // Shows an error bubble with the given |message|, anchored to an edge of
    // the given |anchorRect| -- typically the right edge, but possibly a
    // different edge if there is not space for the bubble to the right of the
    // anchor rectangle. If the |link_range| is non-empty, renders the text
    // within the |message| that is contained in the |link_range| as a link with
    // the given |link_target| URL.
    static void showErrorBubble(DOMString message,
                                Range link_range,
                                DOMString link_target,
                                Rect anchorRect);

    // Hides the currently visible error bubble, if there is one.
    static void hideErrorBubble();

    // Sets the result of auto pairing triggered from onStartAutoPairing
    // event. If auto pairing is completed successfully, |result.success|
    // should be true so that Easy bootstrap flow would finish and starts
    // the user session. Otherwise, |result.success| is set to false with
    // an optional error message to be displayed to the user.
    static void setAutoPairingResult(AutoPairingResult result,
                                     optional EmptyCallback callback);

    // Finds and connects the remote BLE device that is advertising:
    // |setupServiceUUID|. Returns when a connection is found or |timeOut|
    // seconds have elapsed.
    static void findSetupConnection(DOMString setupServiceUuid,
                                    long timeOut,
                                    FindSetupConnectionCallback callback);

    // Returns the status of the connection with |connectionId|.
    static void setupConnectionStatus(long connectionId,
                                      SetupConnectionStatusCallback callback);

    // Disconnects the connection with |connectionId|. 
    static void setupConnectionDisconnect(long connectionId, 
                                          optional EmptyCallback callback);

    // Sends |data| through the connection with |connnectionId|.
    static void setupConnectionSend(long connectionId,
                                    ArrayBuffer data,
                                    optional EmptyCallback callback);

    // Gets the Bluetooth address of the connection with |connectionId|
    static void setupConnectionGetDeviceAddress(long connectionId,
        SetupConnectionGetDeviceAddressCallback callback);
  };

  interface Events {
    // Event fired when the data for the user currently associated with
    // Easy unlock service is updated.
    // |userInfo| The updated user information.
    static void onUserInfoUpdated(UserInfo userInfo);

    // Event fired at the end of Easy bootstrap to start auto pairing so
    // that a proper cryptohome key could be generated for the user.
    static void onStartAutoPairing();

    // Event fired when |connectionId| change status.
    static void onConnectionStatusChanged(long connectionId,
                                          ConnectionStatus oldStatus,
                                          ConnectionStatus newStatus);

    // Event fired when |connectionId| receives |data|.
    static void onDataReceived(long connectionId,
                               ArrayBuffer data);

    // Event fired when |connectionId| sends |data|. |success| is true
    // if the send operation was successful.
    static void onSendCompleted(long connectionId,
                                ArrayBuffer data,
                                boolean success);
  };
};