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