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.
[nodoc] 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,
    // The devie can be unlocked using Easy Unlock.
    AUTHENTICATED
  };

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

  // 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;

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

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

  // 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);

  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.
    static void getSignInChallenge(DataCallback 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 user's profile image as a bitmap.
    static void getUserImage(DataCallback 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);
  };
};