src/chrome/common/extensions/api/easy_unlock_private.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // <code>chrome.easyUnlockPrivate</code> API that provides hooks to Chrome to
   6 // be used by Easy Unlock component app.
   7 [nodoc] namespace easyUnlockPrivate {
   8   // Signature algorithms supported by the crypto library methods used by
   9   // Easy Unlock.
  10   enum SignatureType {
  11     HMAC_SHA256,
  12     ECDSA_P256_SHA256
  13   };
  14
  15   // Encryption algorithms supported by the crypto library methods used by
  16   // Easy Unlock.
  17   enum EncryptionType {
  18     AES_256_CBC
  19   };
  20
  21   // Available states for the Easy Unlock app.
  22   enum State {
  23     // Screen is either not locked, or the Easy Unlock is not enabled.
  24     INACTIVE,
  25     // The Bluetooth is not enabled.
  26     NO_BLUETOOTH,
  27     // Bluetooth is being activated.
  28     BLUETOOTH_CONNECTING,
  29     // There are no phones eligible to unlock the device.
  30     NO_PHONE,
  31     // A phone eligible to unlock the device is detected, but can't be
  32     // authenticated.
  33     PHONE_NOT_AUTHENTICATED,
  34     // A phone eligible to unlock the device is detected, but it's locked and
  35     // thus unable to unlock the device.
  36     PHONE_LOCKED,
  37     // A phone eligible to unlock the device is detected, but it is not allowed
  38     // to unlock the device because it doesn't have lock screen enabled.
  39     PHONE_UNLOCKABLE,
  40     // A phone eligible to unlock the device is detected, but it's not close
  41     // enough to be allowed to unlock the device.
  42     PHONE_NOT_NEARBY,
  43     // A phone eligible to unlock the device is detected, but it is not allowed
  44     // to unlock the device because it does not report its lock screen state.
  45     PHONE_UNSUPPORTED,
  46     // The devie can be unlocked using Easy Unlock.
  47     AUTHENTICATED
  48   };
  49
  50   // Type of a permit. All lower case to match permit.PermitRecord.Type.
  51   enum PermitType {access, license};
  52
  53   // Options that can be passed to |unwrapSecureMessage| method.
  54   dictionary UnwrapSecureMessageOptions {
  55     // The data associated with the message. For the message to be succesfully
  56     // verified, the message should have been created with the same associated
  57     // data.
  58     ArrayBuffer? associatedData;
  59
  60     // The encryption algorithm that should be used to decrypt the message.
  61     // Should not be set for a cleartext message.
  62     EncryptionType? encryptType;
  63
  64     // The algorithm to be used to verify signature contained in the message.
  65     // Defaults to |HMAC_SHA256|. |ECDSA_P256_SHA256| can currently be used
  66     // only with cleartext messages.
  67     SignatureType? signType;
  68   };
  69
  70   dictionary CreateSecureMessageOptions {
  71     // Data associated with the message. The data will not be sent with the
  72     // message, but the message recepient will use the same data on its side
  73     // to verify the message.
  74     ArrayBuffer? associatedData;
  75
  76     // Metadata to be added to the message header.
  77     ArrayBuffer? publicMetadata;
  78
  79     // Verification key id added to the message header. Should be set if the
  80     // message is signed using |ECDSA_P256_SHA256|. It's used by the message
  81     // recepient to determine which key should be used to verify the message
  82     // signature.
  83     ArrayBuffer? verificationKeyId;
  84
  85     // The encryption algorithm that should be used to encrypt the message.
  86     // Should not be set for a cleartext message.
  87     EncryptionType? encryptType;
  88
  89     // The algorithm to be used to sign the message.
  90     // Defaults to |HMAC_SHA256|. |ECDSA_P256_SHA256| can currently be used
  91     // only with cleartext messages.
  92     SignatureType? signType;
  93   };
  94
  95   // A permit record contains the credentials used to request or grant
  96   // authorization of a permit.
  97   dictionary PermitRecord {
  98     // ID of the permit, which identifies the service/application that these
  99     // permit records are used in.
 100     DOMString permitId;
 101
 102     // An identifier for this record that should be unique among all other
 103     // records of the same permit.
 104     DOMString id;
 105
 106     // Type of the record.
 107     PermitType type;
 108
 109     // Websafe base64 encoded payload data of the record.
 110     DOMString data;
 111   };
 112
 113   // Device information that can be authenticated for Easy unlock.
 114   dictionary Device {
 115     // The Bluetooth address of the device.
 116     DOMString bluetoothAddress;
 117
 118     // The name of the device.
 119     DOMString? name;
 120
 121     // The permit record of the device.
 122     PermitRecord? permitRecord;
 123
 124     // Websafe base64 encoded persistent symmetric key.
 125     DOMString? psk;
 126   };
 127
 128   // Callback for crypto methods that return a single array buffer.
 129   callback DataCallback = void(optional ArrayBuffer data);
 130
 131   // An empty callback used purely for signalling success vs. failure.
 132   callback EmptyCallback = void();
 133
 134   // Callback for the getStrings() method.
 135   callback GetStringsCallback = void(object strings);
 136
 137   // Callback for method that generates an encryption key pair.
 138   callback KeyPairCallback = void(optional ArrayBuffer public_key,
 139                                   optional ArrayBuffer private_key);
 140
 141   // Callback for the getPermitAccess() method.
 142   callback GetPermitAccessCallback = void(optional PermitRecord permitAccess);
 143
 144   // Callback for the getRemoteDevices() method.
 145   callback GetRemoteDevicesCallback = void(Device[] devices);
 146
 147   interface Functions {
 148     // Gets localized strings required to render the API.
 149     //
 150     // |callback| : Called with a dictionary mapping names to resource strings.
 151     // TODO(isherman): This is essentially copied from identity_private.idl.
 152     //                 Perhaps this should be extracted to a common API instead?
 153     static void getStrings(GetStringsCallback callback);
 154
 155     // Generates a ECDSA key pair for P256 curve.
 156     // Public key will be in format recognized by secure wire transport protocol
 157     // used by Easy Unlock app. Otherwise, the exact format for both key should
 158     // should be considered obfuscated to the app. The app should not use them
 159     // directly, but through this API.
 160     // |callback|: Callback with the generated keys. On failure, none of the
 161     //     keys will be set.
 162     static void generateEcP256KeyPair(KeyPairCallback callback);
 163
 164     // Given a private key and a public ECDSA key from different asymetric key
 165     // pairs, it generates a symetric encryption key using EC Diffie-Hellman
 166     // scheme.
 167     // |privateKey|: A private key generated by the app using
 168     //     |generateEcP256KeyPair|.
 169     // |publicKey|: A public key that should be in the same format as the
 170     //     public key generated by |generateEcP256KeyPair|. Generally not the
 171     //     one paired with |private_key|.
 172     // |callback|: Function returning the generated secret symetric key.
 173     //     On failure, the returned value will not be set.
 174     static void performECDHKeyAgreement(ArrayBuffer privateKey,
 175                                         ArrayBuffer publicKey,
 176                                         DataCallback callback);
 177
 178     // Creates a secure, signed message in format used by Easy Unlock app to
 179     // establish secure communication channel over unsecure connection.
 180     // |payload|: The payload the create message should carry.
 181     // |key|: The key used to sign the message content. If encryption algorithm
 182     //     is set in |options| the same key will be used to encrypt the message.
 183     // |options|: Additional (optional) parameters used to create the message.
 184     // |callback|: Function returning the created message bytes. On failure,
 185     //     the returned value will not be set.
 186     static void createSecureMessage(
 187         ArrayBuffer payload,
 188         ArrayBuffer key,
 189         CreateSecureMessageOptions options,
 190         DataCallback callback);
 191
 192     // Authenticates and, if needed, decrypts a secure message. The message is
 193     // in the same format as the one created by |createSecureMessage|.
 194     // |secureMessage|: The message to be unwrapped.
 195     // |key|: Key to be used to authenticate the message sender. If encryption
 196     //     algorithm is set in |options|, the same key will be used to decrypt
 197     //     the message.
 198     // |options|: Additional (optional) parameters used to unwrap the message.
 199     // |callback|: Function returning an array buffer containing cleartext
 200     //     message header and body. They are returned in a single buffer in
 201     //     format used inside the message. If the massage authentication or
 202     //     decryption fails, the returned value will not be set.
 203     static void unwrapSecureMessage(
 204         ArrayBuffer secureMessage,
 205         ArrayBuffer key,
 206         UnwrapSecureMessageOptions options,
 207         DataCallback callback);
 208
 209     // Connects to the SDP service on a device, given just the device's
 210     // Bluetooth address. This function is useful as a faster alternative to
 211     // Bluetooth discovery, when you already know the remote device's Bluetooth
 212     // address. A successful call to this function has the side-effect of
 213     // registering the device with the Bluetooth daemon, making it available for
 214     // future outgoing connections.
 215     // |deviceAddress|: The Bluetooth address of the device to connect to.
 216     // |callback|: Called to indicate success or failure.
 217     static void seekBluetoothDeviceByAddress(DOMString deviceAddress,
 218                                              optional EmptyCallback callback);
 219
 220     // Connects the socket to a remote Bluetooth device over an insecure
 221     // connection, i.e. a connection that requests no bonding and no
 222     // man-in-the-middle protection. Other than the reduced security setting,
 223     // behaves identically to the chrome.bluetoothSocket.connect() function.
 224     // |socketId|: The socket identifier, as issued by the
 225     //     chrome.bluetoothSocket API.
 226     // |deviceAddress|: The Bluetooth address of the device to connect to.
 227     // |uuid|: The UUID of the service to connect to.
 228     // |callback|: Called when the connect attempt is complete.
 229     static void connectToBluetoothServiceInsecurely(long socketId,
 230                                                     DOMString deviceAddress,
 231                                                     DOMString uuid,
 232                                                     EmptyCallback callback);
 233
 234     // Updates the screenlock state to reflect the Easy Unlock app state.
 235     static void updateScreenlockState(State state,
 236                                       optional EmptyCallback callback);
 237
 238     // Saves the permit record for the local device.
 239     // |permitAccess|: The permit record to be saved.
 240     // |callback|: Called to indicate success or failure.
 241     static void setPermitAccess(PermitRecord permitAccess,
 242                                 optional EmptyCallback callback);
 243
 244     // Gets the permit record for the local device.
 245     static void getPermitAccess(GetPermitAccessCallback callback);
 246
 247     // Clears the permit record for the local device.
 248     static void clearPermitAccess(optional EmptyCallback callback);
 249
 250     // Saves the remote device list.
 251     // |devices|: The list of remote devices to be saved.
 252     // |callback|: Called to indicate success or failure.
 253     static void setRemoteDevices(Device[] devices,
 254                                  optional EmptyCallback callback);
 255
 256     // Gets the remote device list.
 257     static void getRemoteDevices(GetRemoteDevicesCallback callback);
 258   };
 259 };