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     // The devie can be unlocked using Easy Unlock.
  44     AUTHENTICATED
  45   };
  46
  47   // Type of a permit. All lower case to match permit.PermitRecord.Type.
  48   enum PermitType {access, license};
  49
  50   // Options that can be passed to |unwrapSecureMessage| method.
  51   dictionary UnwrapSecureMessageOptions {
  52     // The data associated with the message. For the message to be succesfully
  53     // verified, the message should have been created with the same associated
  54     // data.
  55     ArrayBuffer? associatedData;
  56
  57     // The encryption algorithm that should be used to decrypt the message.
  58     // Should not be set for a cleartext message.
  59     EncryptionType? encryptType;
  60
  61     // The algorithm to be used to verify signature contained in the message.
  62     // Defaults to |HMAC_SHA256|. |ECDSA_P256_SHA256| can currently be used
  63     // only with cleartext messages.
  64     SignatureType? signType;
  65   };
  66
  67   dictionary CreateSecureMessageOptions {
  68     // Data associated with the message. The data will not be sent with the
  69     // message, but the message recepient will use the same data on its side
  70     // to verify the message.
  71     ArrayBuffer? associatedData;
  72
  73     // Metadata to be added to the message header.
  74     ArrayBuffer? publicMetadata;
  75
  76     // Verification key id added to the message header. Should be set if the
  77     // message is signed using |ECDSA_P256_SHA256|. It's used by the message
  78     // recepient to determine which key should be used to verify the message
  79     // signature.
  80     ArrayBuffer? verificationKeyId;
  81
  82     // The encryption algorithm that should be used to encrypt the message.
  83     // Should not be set for a cleartext message.
  84     EncryptionType? encryptType;
  85
  86     // The algorithm to be used to sign the message.
  87     // Defaults to |HMAC_SHA256|. |ECDSA_P256_SHA256| can currently be used
  88     // only with cleartext messages.
  89     SignatureType? signType;
  90   };
  91
  92   // A permit record contains the credentials used to request or grant
  93   // authorization of a permit.
  94   dictionary PermitRecord {
  95     // ID of the permit, which identifies the service/application that these
  96     // permit records are used in.
  97     DOMString permitId;
  98
  99     // An identifier for this record that should be unique among all other
 100     // records of the same permit.
 101     DOMString id;
 102
 103     // Type of the record.
 104     PermitType type;
 105
 106     // Websafe base64 encoded payload data of the record.
 107     DOMString data;
 108   };
 109
 110   // Device information that can be authenticated for Easy unlock.
 111   dictionary Device {
 112     // The Bluetooth address of the device.
 113     DOMString bluetoothAddress;
 114
 115     // The name of the device.
 116     DOMString? name;
 117
 118     // The permit record of the device.
 119     PermitRecord? permitRecord;
 120
 121     // Websafe base64 encoded persistent symmetric key.
 122     DOMString? psk;
 123   };
 124
 125   // Callback for crypto methods that return a single array buffer.
 126   callback DataCallback = void(optional ArrayBuffer data);
 127
 128   // An empty callback used purely for signalling success vs. failure.
 129   callback EmptyCallback = void();
 130
 131   // Callback for the getStrings() method.
 132   callback GetStringsCallback = void(object strings);
 133
 134   // Callback for method that generates an encryption key pair.
 135   callback KeyPairCallback = void(optional ArrayBuffer public_key,
 136                                   optional ArrayBuffer private_key);
 137
 138   // Callback for the getPermitAccess() method.
 139   callback GetPermitAccessCallback = void(optional PermitRecord permitAccess);
 140
 141   // Callback for the getRemoteDevices() method.
 142   callback GetRemoteDevicesCallback = void(Device[] devices);
 143
 144   interface Functions {
 145     // Gets localized strings required to render the API.
 146     //
 147     // |callback| : Called with a dictionary mapping names to resource strings.
 148     // TODO(isherman): This is essentially copied from identity_private.idl.
 149     //                 Perhaps this should be extracted to a common API instead?
 150     static void getStrings(GetStringsCallback callback);
 151
 152     // Generates a ECDSA key pair for P256 curve.
 153     // Public key will be in format recognized by secure wire transport protocol
 154     // used by Easy Unlock app. Otherwise, the exact format for both key should
 155     // should be considered obfuscated to the app. The app should not use them
 156     // directly, but through this API.
 157     // |callback|: Callback with the generated keys. On failure, none of the
 158     //     keys will be set.
 159     static void generateEcP256KeyPair(KeyPairCallback callback);
 160
 161     // Given a private key and a public ECDSA key from different asymetric key
 162     // pairs, it generates a symetric encryption key using EC Diffie-Hellman
 163     // scheme.
 164     // |privateKey|: A private key generated by the app using
 165     //     |generateEcP256KeyPair|.
 166     // |publicKey|: A public key that should be in the same format as the
 167     //     public key generated by |generateEcP256KeyPair|. Generally not the
 168     //     one paired with |private_key|.
 169     // |callback|: Function returning the generated secret symetric key.
 170     //     On failure, the returned value will not be set.
 171     static void performECDHKeyAgreement(ArrayBuffer privateKey,
 172                                         ArrayBuffer publicKey,
 173                                         DataCallback callback);
 174
 175     // Creates a secure, signed message in format used by Easy Unlock app to
 176     // establish secure communication channel over unsecure connection.
 177     // |payload|: The payload the create message should carry.
 178     // |key|: The key used to sign the message content. If encryption algorithm
 179     //     is set in |options| the same key will be used to encrypt the message.
 180     // |options|: Additional (optional) parameters used to create the message.
 181     // |callback|: Function returning the created message bytes. On failure,
 182     //     the returned value will not be set.
 183     static void createSecureMessage(
 184         ArrayBuffer payload,
 185         ArrayBuffer key,
 186         CreateSecureMessageOptions options,
 187         DataCallback callback);
 188
 189     // Authenticates and, if needed, decrypts a secure message. The message is
 190     // in the same format as the one created by |createSecureMessage|.
 191     // |secureMessage|: The message to be unwrapped.
 192     // |key|: Key to be used to authenticate the message sender. If encryption
 193     //     algorithm is set in |options|, the same key will be used to decrypt
 194     //     the message.
 195     // |options|: Additional (optional) parameters used to unwrap the message.
 196     // |callback|: Function returning an array buffer containing cleartext
 197     //     message header and body. They are returned in a single buffer in
 198     //     format used inside the message. If the massage authentication or
 199     //     decryption fails, the returned value will not be set.
 200     static void unwrapSecureMessage(
 201         ArrayBuffer secureMessage,
 202         ArrayBuffer key,
 203         UnwrapSecureMessageOptions options,
 204         DataCallback callback);
 205
 206     // Connects to the SDP service on a device, given just the device's
 207     // Bluetooth address. This function is useful as a faster alternative to
 208     // Bluetooth discovery, when you already know the remote device's Bluetooth
 209     // address. A successful call to this function has the side-effect of
 210     // registering the device with the Bluetooth daemon, making it available for
 211     // future outgoing connections.
 212     // |deviceAddress|: The Bluetooth address of the device to connect to.
 213     // |callback|: Called to indicate success or failure.
 214     static void seekBluetoothDeviceByAddress(DOMString deviceAddress,
 215                                              optional EmptyCallback callback);
 216
 217     // Updates the screenlock state to reflect the Easy Unlock app state.
 218     static void updateScreenlockState(State state,
 219                                       optional EmptyCallback callback);
 220
 221     // Saves the permit record for the local device.
 222     // |permitAccess|: The permit record to be saved.
 223     // |callback|: Called to indicate success or failure.
 224     static void setPermitAccess(PermitRecord permitAccess,
 225                                 optional EmptyCallback callback);
 226
 227     // Gets the permit record for the local device.
 228     static void getPermitAccess(GetPermitAccessCallback callback);
 229
 230     // Clears the permit record for the local device.
 231     static void clearPermitAccess(optional EmptyCallback callback);
 232
 233     // Saves the remote device list.
 234     // |devices|: The list of remote devices to be saved.
 235     // |callback|: Called to indicate success or failure.
 236     static void setRemoteDevices(Device[] devices,
 237                                  optional EmptyCallback callback);
 238
 239     // Gets the remote device list.
 240     static void getRemoteDevices(GetRemoteDevicesCallback callback);
 241   };
 242 };