Add easyUnlockPrivate extension API

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
+  };
+
+  // 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;
+  };
+
+  // Callback for crypto methods that return a single array buffer.
+  callback DataCallback = void(optional ArrayBuffer data);
+
+  // Callback for method that generates an encryption key pair.
+  callback KeyPairCallback = void(optional ArrayBuffer public_key,
+                                  optional ArrayBuffer private_key);
+
+  interface Functions {
+    // 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);
+  };
+};