chrome/common/extensions/api/enterprise_platform_keys.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 // Use the <code>chrome.enterprise.platformKeys</code> API to generate
   6 // hardware-backed keys and to install certificates for these keys. The
   7 // certificates will be managed by the platform and can be used for TLS
   8 // authentication, network access or by other extension through
   9 // $(ref:platformKeys chrome.platformKeys).
  10 [platforms = ("chromeos")]
  11 namespace enterprise.platformKeys {
  12   [nocompile, noinline_doc] dictionary Token {
  13     // Uniquely identifies this <code>Token</code>.
  14     // <p>Static IDs are <code>"user"</code> and <code>"system"</code>,
  15     // referring to the platform's user-specific and the system-wide hardware
  16     // token, respectively. Any other tokens (with other identifiers) might be
  17     // returned by $(ref:enterprise.platformKeys.getTokens).</p>
  18     DOMString id;
  19
  20     // Implements the WebCrypto's
  21     // <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">SubtleCrypto</a>
  22     // interface. The cryptographic operations, including key generation, are
  23     // hardware-backed.
  24     // <p>Only non-extractable RSASSA-PKCS1-V1_5 keys with
  25     // <code>modulusLength</code> up to 2048 can be generated. Each key can be
  26     // used for signing data at most once.</p>
  27     // <p>Keys generated on a specific <code>Token</code> cannot be used with
  28     // any other Tokens, nor can they be used with
  29     // <code>window.crypto.subtle</code>. Equally, <code>Key</code> objects
  30     // created with <code>window.crypto.subtle</code> cannot be used with this
  31     // interface.</p>
  32     [instanceOf = SubtleCrypto] object subtleCrypto;
  33   };
  34
  35   // Invoked by <code>getTokens</code> with the list of available Tokens.
  36   // |tokens|: The list of available tokens.
  37   callback GetTokensCallback = void(Token[] tokens);
  38
  39   // Callback to which the certificates are passed.
  40   // |certificates|: The list of certificates, each in DER encoding of a X.509
  41   //     certificate.
  42   callback GetCertificatesCallback = void(ArrayBuffer[] certificates);
  43
  44   // Invoked by importCertificate or removeCertificate when the respective
  45   // operation is finished.
  46   callback DoneCallback = void();
  47
  48   interface Functions {
  49     // Returns the available Tokens. In a regular user's session the list will
  50     // always contain the user's token with <code>id</code> <code>"user"</code>.
  51     // If a system-wide TPM token is available, the returned list will also
  52     // contain the system-wide token with <code>id</code> <code>"system"</code>.
  53     // The system-wide token will be the same for all sessions on this device
  54     // (device in the sense of e.g. a Chromebook).
  55     [nocompile] static void getTokens(GetTokensCallback callback);
  56
  57     // Returns the list of all client certificates available from the given
  58     // token. Can be used to check for the existence and expiration of client
  59     // certificates that are usable for a certain authentication.
  60     // |tokenId|: The id of a Token returned by <code>getTokens</code>.
  61     // |callback|: Called back with the list of the available certificates.
  62     static void getCertificates(DOMString tokenId,
  63                                 GetCertificatesCallback callback);
  64
  65     // Imports <code>certificate</code> to the given token if the certified key
  66     // is already stored in this token.
  67     // After a successful certification request, this function should be used to
  68     // store the obtained certificate and to make it available to the operating
  69     // system and browser for authentication.
  70     // |tokenId|: The id of a Token returned by <code>getTokens</code>.
  71     // |certificate|: The DER encoding of a X.509 certificate.
  72     // |callback|: Called back when this operation is finished.
  73     static void importCertificate(DOMString tokenId,
  74                                   ArrayBuffer certificate,
  75                                   optional DoneCallback callback);
  76
  77     // Removes <code>certificate</code> from the given token if present.
  78     // Should be used to remove obsolete certificates so that they are not
  79     // considered during authentication and do not clutter the certificate
  80     // choice. Should be used to free storage in the certificate store.
  81     // |tokenId|: The id of a Token returned by <code>getTokens</code>.
  82     // |certificate|: The DER encoding of a X.509 certificate.
  83     // |callback|: Called back when this operation is finished.
  84     static void removeCertificate(DOMString tokenId,
  85                                   ArrayBuffer certificate,
  86                                   optional DoneCallback callback);
  87   };
  88 };