chrome/common/extensions/api/enterprise_platform_keys.idl - chromium/src - Git at Google

 // Copyright 2014 The Chromium Authors
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 // Use the <code>chrome.enterprise.platformKeys</code> API to generate keys and
 // install certificates for these keys. The certificates will be managed by the
 // platform and can be used for TLS authentication, network access or by other
 // extension through $(ref:platformKeys chrome.platformKeys).
 [platforms = ("chromeos", "lacros")]
 namespace enterprise.platformKeys {
   [nocompile, noinline_doc] dictionary Token {
     // Uniquely identifies this <code>Token</code>.
     // <p>Static IDs are <code>"user"</code> and <code>"system"</code>,
     // referring to the platform's user-specific and the system-wide hardware
     // token, respectively. Any other tokens (with other identifiers) might be
     // returned by $(ref:enterprise.platformKeys.getTokens).</p>
     DOMString id;

     // Implements the WebCrypto's
     // <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">SubtleCrypto</a>
     // interface. The cryptographic operations, including key generation, are
     // hardware-backed.
     // <p>Only non-extractable RSASSA-PKCS1-V1_5 keys with
     // <code>modulusLength</code> up to 2048 and ECDSA with
     // <code>namedCurve</code> P-256 can be generated. Each key can be
     // used for signing data at most once.</p>
     // <p>Keys generated on a specific <code>Token</code> cannot be used with
     // any other Tokens, nor can they be used with
     // <code>window.crypto.subtle</code>. Equally, <code>Key</code> objects
     // created with <code>window.crypto.subtle</code> cannot be used with this
     // interface.</p>
     [instanceOf = SubtleCrypto] object subtleCrypto;

     // Implements the WebCrypto's
     // <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">SubtleCrypto</a>
     // interface. The cryptographic operations, including key generation, are
     // software-backed. Protection of the keys, and thus implementation of the
     // non-extractable property, is done in software, so the keys are less
     // protected than hardware-backed keys.
     // <p>Only non-extractable RSASSA-PKCS1-V1_5 keys with
     // <code>modulusLength</code> up to 2048 can be generated. Each key can be
     // used for signing data at most once.</p>
     // <p>Keys generated on a specific <code>Token</code> cannot be used with
     // any other Tokens, nor can they be used with
     // <code>window.crypto.subtle</code>. Equally, <code>Key</code> objects
     // created with <code>window.crypto.subtle</code> cannot be used with this
     // interface.</p>
     [instanceOf = SubtleCrypto] object softwareBackedSubtleCrypto;
   };

   // Whether to use the Enterprise User Key or the Enterprise Machine Key.
   enum Scope { USER, MACHINE };

   // Type of key to generate.
   enum Algorithm { RSA, ECDSA };

   // Invoked by <code>getTokens</code> with the list of available Tokens.
   // |tokens|: The list of available tokens.
   callback GetTokensCallback = void(Token[] tokens);

   // Callback to which the certificates are passed.
   // |certificates|: The list of certificates, each in DER encoding of a X.509
   //     certificate.
   callback GetCertificatesCallback = void(ArrayBuffer[] certificates);

   // Invoked by importCertificate or removeCertificate when the respective
   // operation is finished.
   callback DoneCallback = void();

   // Invoked by <code>challengeMachineKey</code> or
   // <code>challengeUserKey</code> with the challenge response.
   // |response|: The challenge response.
   callback ChallengeCallback = void(ArrayBuffer response);

   dictionary RegisterKeyOptions {
     // Which algorithm the registered key should use.
     Algorithm algorithm;
   };

   dictionary ChallengeKeyOptions {
     // A challenge as emitted by the Verified Access Web API.
     ArrayBuffer challenge;
     // If present, registers the challenged key with the specified
     // <code>scope</code>'s token.  The key can then be associated with a
     // certificate and used like any other signing key.  Subsequent calls to
     // this function will then generate a new Enterprise Key in the specified
     // <code>scope</code>.
     RegisterKeyOptions? registerKey;
     // Which Enterprise Key to challenge.
     Scope scope;
   };


   interface Functions {
     // Returns the available Tokens. In a regular user's session the list will
     // always contain the user's token with <code>id</code> <code>"user"</code>.
     // If a system-wide TPM token is available, the returned list will also
     // contain the system-wide token with <code>id</code> <code>"system"</code>.
     // The system-wide token will be the same for all sessions on this device
     // (device in the sense of e.g. a Chromebook).
     [nocompile] static void getTokens(GetTokensCallback callback);

     // Returns the list of all client certificates available from the given
     // token. Can be used to check for the existence and expiration of client
     // certificates that are usable for a certain authentication.
     // |tokenId|: The id of a Token returned by <code>getTokens</code>.
     // |callback|: Called back with the list of the available certificates.
     static void getCertificates(DOMString tokenId,
                                 GetCertificatesCallback callback);

     // Imports <code>certificate</code> to the given token if the certified key
     // is already stored in this token.
     // After a successful certification request, this function should be used to
     // store the obtained certificate and to make it available to the operating
     // system and browser for authentication.
     // |tokenId|: The id of a Token returned by <code>getTokens</code>.
     // |certificate|: The DER encoding of a X.509 certificate.
     // |callback|: Called back when this operation is finished.
     static void importCertificate(DOMString tokenId,
                                   ArrayBuffer certificate,
                                   optional DoneCallback callback);

     // Removes <code>certificate</code> from the given token if present.
     // Should be used to remove obsolete certificates so that they are not
     // considered during authentication and do not clutter the certificate
     // choice. Should be used to free storage in the certificate store.
     // |tokenId|: The id of a Token returned by <code>getTokens</code>.
     // |certificate|: The DER encoding of a X.509 certificate.
     // |callback|: Called back when this operation is finished.
     static void removeCertificate(DOMString tokenId,
                                   ArrayBuffer certificate,
                                   optional DoneCallback callback);

     // Similar to <code>challengeMachineKey</code> and
     // <code>challengeUserKey</code>, but allows specifying the algorithm of a
     // registered key. Challenges a hardware-backed Enterprise Machine Key and
     // emits the response as part of a remote attestation protocol. Only useful
     // on Chrome OS and in conjunction with the Verified Access Web API which
     // both issues challenges and verifies responses.
     //
     // A successful verification by the Verified Access Web API is a strong
     // signal that the current device is a legitimate Chrome OS device, the
     // current device is managed by the domain specified during verification,
     // the current signed-in user is managed by the domain specified during
     // verification, and the current device state complies with enterprise
     // device policy. For example, a policy may specify that the device must not
     // be in developer mode.  Any device identity emitted by the verification is
     // tightly bound to the hardware of the current device. If
     // <code>"user"</code> Scope is specified, the identity is also tighly bound
     // to the current signed-in user.
     //
     // This function is highly restricted and will fail if the current device is
     // not managed, the current user is not managed, or if this operation has
     // not explicitly been enabled for the caller by enterprise device policy.
     // The challenged key does not reside in the <code>"system"</code> or
     // <code>"user"</code> token and is not accessible by any other API.
     // |options|: Object containing the fields defined in
     //            $(ref:ChallengeKeyOptions).
     // |callback|: Called back with the challenge response.
     static void challengeKey(ChallengeKeyOptions options,
                              ChallengeCallback callback);

     // Challenges a hardware-backed Enterprise Machine Key and emits the
     // response as part of a remote attestation protocol. Only useful on Chrome
     // OS and in conjunction with the Verified Access Web API which both issues
     // challenges and verifies responses. A successful verification by the
     // Verified Access Web API is a strong signal of all of the following:
     // * The current device is a legitimate Chrome OS device.
     // * The current device is managed by the domain specified during
     //   verification.
     // * The current signed-in user is managed by the domain specified during
     //   verification.
     // * The current device state complies with enterprise device policy. For
     //   example, a policy may specify that the device must not be in developer
     //   mode.
     // * Any device identity emitted by the verification is tightly bound to the
     //   hardware of the current device.
     // This function is highly restricted and will fail if the current device
     // is not managed, the current user is not managed, or if this operation
     // has not explicitly been enabled for the caller by enterprise device
     // policy. The Enterprise Machine Key does not reside in the
     // <code>"system"</code> token and is not accessible by any other API.
     // |challenge|: A challenge as emitted by the Verified Access Web API.
     // |registerKey|: If set, the current Enterprise Machine Key is registered
     //                with the <code>"system"</code> token and relinquishes the
     //                Enterprise Machine Key role. The key can then be
     //                associated with a certificate and used like any other
     //                signing key. This key is 2048-bit RSA. Subsequent calls
     //                to this function will then generate a new Enterprise
     //                Machine Key.
     // |callback|: Called back with the challenge response.
     [deprecated="Use $(ref:challengeKey) instead."]
     static void challengeMachineKey(ArrayBuffer challenge,
                                     optional boolean registerKey,
                                     ChallengeCallback callback);

     // Challenges a hardware-backed Enterprise User Key and emits the response
     // as part of a remote attestation protocol. Only useful on Chrome OS and in
     // conjunction with the Verified Access Web API which both issues challenges
     // and verifies responses. A successful verification by the Verified Access
     // Web API is a strong signal of all of the following:
     // * The current device is a legitimate Chrome OS device.
     // * The current device is managed by the domain specified during
     //   verification.
     // * The current signed-in user is managed by the domain specified during
     //   verification.
     // * The current device state complies with enterprise user policy. For
     //   example, a policy may specify that the device must not be in developer
     //   mode.
     // * The public key emitted by the verification is tightly bound to the
     //   hardware of the current device and to the current signed-in user.
     // This function is highly restricted and will fail if the current device is
     // not managed, the current user is not managed, or if this operation has
     // not explicitly been enabled for the caller by enterprise user policy.
     // The Enterprise User Key does not reside in the <code>"user"</code> token
     // and is not accessible by any other API.
     // |challenge|: A challenge as emitted by the Verified Access Web API.
     // |registerKey|: If set, the current Enterprise User Key is registered with
     //                the <code>"user"</code> token and relinquishes the
     //                Enterprise User Key role. The key can then be associated
     //                with a certificate and used like any other signing key.
     //                This key is 2048-bit RSA. Subsequent calls to this
     //                function will then generate a new Enterprise User Key.
     // |callback|: Called back with the challenge response.
     [deprecated="Use $(ref:challengeKey) instead."]
     static void challengeUserKey(ArrayBuffer challenge,
                                  boolean registerKey,
                                  ChallengeCallback callback);
   };
 };
	// Copyright 2014 The Chromium Authors
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	// Use the <code>chrome.enterprise.platformKeys</code> API to generate keys and
	// install certificates for these keys. The certificates will be managed by the
	// platform and can be used for TLS authentication, network access or by other
	// extension through $(ref:platformKeys chrome.platformKeys).
	[platforms = ("chromeos", "lacros")]
	namespace enterprise.platformKeys {
	[nocompile, noinline_doc] dictionary Token {
	// Uniquely identifies this <code>Token</code>.
	// <p>Static IDs are <code>"user"</code> and <code>"system"</code>,
	// referring to the platform's user-specific and the system-wide hardware
	// token, respectively. Any other tokens (with other identifiers) might be
	// returned by $(ref:enterprise.platformKeys.getTokens).</p>
	DOMString id;

	// Implements the WebCrypto's
	// <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">SubtleCrypto</a>
	// interface. The cryptographic operations, including key generation, are
	// hardware-backed.
	// <p>Only non-extractable RSASSA-PKCS1-V1_5 keys with
	// <code>modulusLength</code> up to 2048 and ECDSA with
	// <code>namedCurve</code> P-256 can be generated. Each key can be
	// used for signing data at most once.</p>
	// <p>Keys generated on a specific <code>Token</code> cannot be used with
	// any other Tokens, nor can they be used with
	// <code>window.crypto.subtle</code>. Equally, <code>Key</code> objects
	// created with <code>window.crypto.subtle</code> cannot be used with this
	// interface.</p>
	[instanceOf = SubtleCrypto] object subtleCrypto;

	// Implements the WebCrypto's
	// <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">SubtleCrypto</a>
	// interface. The cryptographic operations, including key generation, are
	// software-backed. Protection of the keys, and thus implementation of the
	// non-extractable property, is done in software, so the keys are less
	// protected than hardware-backed keys.
	// <p>Only non-extractable RSASSA-PKCS1-V1_5 keys with
	// <code>modulusLength</code> up to 2048 can be generated. Each key can be
	// used for signing data at most once.</p>
	// <p>Keys generated on a specific <code>Token</code> cannot be used with
	// any other Tokens, nor can they be used with
	// <code>window.crypto.subtle</code>. Equally, <code>Key</code> objects
	// created with <code>window.crypto.subtle</code> cannot be used with this
	// interface.</p>
	[instanceOf = SubtleCrypto] object softwareBackedSubtleCrypto;
	};

	// Whether to use the Enterprise User Key or the Enterprise Machine Key.
	enum Scope { USER, MACHINE };

	// Type of key to generate.
	enum Algorithm { RSA, ECDSA };

	// Invoked by <code>getTokens</code> with the list of available Tokens.
	// \|tokens\|: The list of available tokens.
	callback GetTokensCallback = void(Token[] tokens);

	// Callback to which the certificates are passed.
	// \|certificates\|: The list of certificates, each in DER encoding of a X.509
	// certificate.
	callback GetCertificatesCallback = void(ArrayBuffer[] certificates);

	// Invoked by importCertificate or removeCertificate when the respective
	// operation is finished.
	callback DoneCallback = void();

	// Invoked by <code>challengeMachineKey</code> or
	// <code>challengeUserKey</code> with the challenge response.
	// \|response\|: The challenge response.
	callback ChallengeCallback = void(ArrayBuffer response);

	dictionary RegisterKeyOptions {
	// Which algorithm the registered key should use.
	Algorithm algorithm;
	};

	dictionary ChallengeKeyOptions {
	// A challenge as emitted by the Verified Access Web API.
	ArrayBuffer challenge;
	// If present, registers the challenged key with the specified
	// <code>scope</code>'s token. The key can then be associated with a
	// certificate and used like any other signing key. Subsequent calls to
	// this function will then generate a new Enterprise Key in the specified
	// <code>scope</code>.
	RegisterKeyOptions? registerKey;
	// Which Enterprise Key to challenge.
	Scope scope;
	};


	interface Functions {
	// Returns the available Tokens. In a regular user's session the list will
	// always contain the user's token with <code>id</code> <code>"user"</code>.
	// If a system-wide TPM token is available, the returned list will also
	// contain the system-wide token with <code>id</code> <code>"system"</code>.
	// The system-wide token will be the same for all sessions on this device
	// (device in the sense of e.g. a Chromebook).
	[nocompile] static void getTokens(GetTokensCallback callback);

	// Returns the list of all client certificates available from the given
	// token. Can be used to check for the existence and expiration of client
	// certificates that are usable for a certain authentication.
	// \|tokenId\|: The id of a Token returned by <code>getTokens</code>.
	// \|callback\|: Called back with the list of the available certificates.
	static void getCertificates(DOMString tokenId,
	GetCertificatesCallback callback);

	// Imports <code>certificate</code> to the given token if the certified key
	// is already stored in this token.
	// After a successful certification request, this function should be used to
	// store the obtained certificate and to make it available to the operating
	// system and browser for authentication.
	// \|tokenId\|: The id of a Token returned by <code>getTokens</code>.
	// \|certificate\|: The DER encoding of a X.509 certificate.
	// \|callback\|: Called back when this operation is finished.
	static void importCertificate(DOMString tokenId,
	ArrayBuffer certificate,
	optional DoneCallback callback);

	// Removes <code>certificate</code> from the given token if present.
	// Should be used to remove obsolete certificates so that they are not
	// considered during authentication and do not clutter the certificate
	// choice. Should be used to free storage in the certificate store.
	// \|tokenId\|: The id of a Token returned by <code>getTokens</code>.
	// \|certificate\|: The DER encoding of a X.509 certificate.
	// \|callback\|: Called back when this operation is finished.
	static void removeCertificate(DOMString tokenId,
	ArrayBuffer certificate,
	optional DoneCallback callback);

	// Similar to <code>challengeMachineKey</code> and
	// <code>challengeUserKey</code>, but allows specifying the algorithm of a
	// registered key. Challenges a hardware-backed Enterprise Machine Key and
	// emits the response as part of a remote attestation protocol. Only useful
	// on Chrome OS and in conjunction with the Verified Access Web API which
	// both issues challenges and verifies responses.
	//
	// A successful verification by the Verified Access Web API is a strong
	// signal that the current device is a legitimate Chrome OS device, the
	// current device is managed by the domain specified during verification,
	// the current signed-in user is managed by the domain specified during
	// verification, and the current device state complies with enterprise
	// device policy. For example, a policy may specify that the device must not
	// be in developer mode. Any device identity emitted by the verification is
	// tightly bound to the hardware of the current device. If
	// <code>"user"</code> Scope is specified, the identity is also tighly bound
	// to the current signed-in user.
	//
	// This function is highly restricted and will fail if the current device is
	// not managed, the current user is not managed, or if this operation has
	// not explicitly been enabled for the caller by enterprise device policy.
	// The challenged key does not reside in the <code>"system"</code> or
	// <code>"user"</code> token and is not accessible by any other API.
	// \|options\|: Object containing the fields defined in
	// $(ref:ChallengeKeyOptions).
	// \|callback\|: Called back with the challenge response.
	static void challengeKey(ChallengeKeyOptions options,
	ChallengeCallback callback);

	// Challenges a hardware-backed Enterprise Machine Key and emits the
	// response as part of a remote attestation protocol. Only useful on Chrome
	// OS and in conjunction with the Verified Access Web API which both issues
	// challenges and verifies responses. A successful verification by the
	// Verified Access Web API is a strong signal of all of the following:
	// * The current device is a legitimate Chrome OS device.
	// * The current device is managed by the domain specified during
	// verification.
	// * The current signed-in user is managed by the domain specified during
	// verification.
	// * The current device state complies with enterprise device policy. For
	// example, a policy may specify that the device must not be in developer
	// mode.
	// * Any device identity emitted by the verification is tightly bound to the
	// hardware of the current device.
	// This function is highly restricted and will fail if the current device
	// is not managed, the current user is not managed, or if this operation
	// has not explicitly been enabled for the caller by enterprise device
	// policy. The Enterprise Machine Key does not reside in the
	// <code>"system"</code> token and is not accessible by any other API.
	// \|challenge\|: A challenge as emitted by the Verified Access Web API.
	// \|registerKey\|: If set, the current Enterprise Machine Key is registered
	// with the <code>"system"</code> token and relinquishes the
	// Enterprise Machine Key role. The key can then be
	// associated with a certificate and used like any other
	// signing key. This key is 2048-bit RSA. Subsequent calls
	// to this function will then generate a new Enterprise
	// Machine Key.
	// \|callback\|: Called back with the challenge response.
	[deprecated="Use $(ref:challengeKey) instead."]
	static void challengeMachineKey(ArrayBuffer challenge,
	optional boolean registerKey,
	ChallengeCallback callback);

	// Challenges a hardware-backed Enterprise User Key and emits the response
	// as part of a remote attestation protocol. Only useful on Chrome OS and in
	// conjunction with the Verified Access Web API which both issues challenges
	// and verifies responses. A successful verification by the Verified Access
	// Web API is a strong signal of all of the following:
	// * The current device is a legitimate Chrome OS device.
	// * The current device is managed by the domain specified during
	// verification.
	// * The current signed-in user is managed by the domain specified during
	// verification.
	// * The current device state complies with enterprise user policy. For
	// example, a policy may specify that the device must not be in developer
	// mode.
	// * The public key emitted by the verification is tightly bound to the
	// hardware of the current device and to the current signed-in user.
	// This function is highly restricted and will fail if the current device is
	// not managed, the current user is not managed, or if this operation has
	// not explicitly been enabled for the caller by enterprise user policy.
	// The Enterprise User Key does not reside in the <code>"user"</code> token
	// and is not accessible by any other API.
	// \|challenge\|: A challenge as emitted by the Verified Access Web API.
	// \|registerKey\|: If set, the current Enterprise User Key is registered with
	// the <code>"user"</code> token and relinquishes the
	// Enterprise User Key role. The key can then be associated
	// with a certificate and used like any other signing key.
	// This key is 2048-bit RSA. Subsequent calls to this
	// function will then generate a new Enterprise User Key.
	// \|callback\|: Called back with the challenge response.
	[deprecated="Use $(ref:challengeKey) instead."]
	static void challengeUserKey(ArrayBuffer challenge,
	boolean registerKey,
	ChallengeCallback callback);
	};
	};