| // 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. |
| |
| // Use the <code>chrome.enterprise.platformKeys</code> API to generate |
| // hardware-backed keys and to 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")] |
| 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 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; |
| }; |
| |
| // 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); |
| |
| 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); |
| |
| // 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. |
| 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. |
| static void challengeUserKey(ArrayBuffer challenge, |
| boolean registerKey, |
| ChallengeCallback callback); |
| }; |
| }; |
