blob: 5a33e5e26457c0396b4b87bca1bab50e21dd725d [file] [log] [blame]
// 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's not close
// enough to be allowed to unlock the device.
PHONE_NOT_NEARBY,
// 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,
// 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|. It's used by the message
// recepient to determine which key should be used to verify the message
// signature.
ArrayBuffer? verificationKeyId;
// 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;
};
// 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);
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);
};
};