chrome/common/extensions/api/platform_keys.idl

   1 // Copyright 2015 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.platformKeys</code> API to use client certificates
   6 // managed by the platform.
   7 namespace platformKeys {
   8   dictionary Match {
   9      // The DER encoding of a X.509 certificate.
  10      ArrayBuffer certificate;
  11
  12      // The
  13      // <a href="http://www.w3.org/TR/WebCryptoAPI/#key-algorithm-dictionary">
  14      // KeyAlgorithm</a> of the certified key. This contains algorithm
  15      // parameters that are inherent to the key of the certificate (e.g. the key
  16      // length). Other parameters like the hash function used by the sign
  17      // function are not included.
  18      object keyAlgorithm;
  19   };
  20
  21   enum ClientCertificateType {
  22     rsaSign,
  23     dssSign,
  24     ecdsaSign
  25   };
  26
  27   // Analogous to TLS1.1's CertificateRequest.
  28   // See http://tools.ietf.org/html/rfc4346#section-7.4.4 .
  29   dictionary ClientCertificateRequest {
  30     // This field is a list of the types of certificates requested, sorted in
  31     // order of the server's preference.
  32     ClientCertificateType[] certificateTypes;
  33
  34     // List of distinguished names of certificate authorities allowed by the
  35     // server. Each entry must be a DER-encoded X.509 DistinguishedName.
  36     ArrayBuffer[] certificateAuthorities;
  37   };
  38
  39   dictionary SelectDetails {
  40     // Only certificates that match this request will be returned.
  41     ClientCertificateRequest request;
  42
  43     // If given, the <code>selectClientCertificates</code> operates on this
  44     // list. Otherwise, obtains the list of all certificates from the platform's
  45     // certificate stores that are available to this extensions.
  46     // Entries that the extension doesn't have permission for or which doesn't
  47     // match the request, are removed.
  48     ArrayBuffer[]? clientCerts;
  49
  50     // If true, the filtered list is presented to the user to manually select a
  51     // certificate and thereby granting the extension access to the
  52     // certificate(s) and key(s). Only the selected certificate(s) will be
  53     // returned. If is false, the list is reduced to all certificates that the
  54     // extension has been granted access to (automatically or manually).
  55     boolean interactive;
  56   };
  57
  58   callback SelectCallback = void (Match[] certs);
  59
  60   // The public and private
  61   // <a href="http://www.w3.org/TR/WebCryptoAPI/#dfn-CryptoKey">CryptoKey</a>
  62   // of a certificate which can only be used with
  63   // <code>chrome.certs.subtleCrypto</code>. <code>privateKey</code> Might be
  64   // null if this extension does not have access to it.
  65   callback GetKeyPairCallback = void (object publicKey,
  66                                       optional object privateKey);
  67
  68   interface Functions {
  69     // This function filters from a list of client certificates the ones that
  70     // are known to the platform, match <code>request</code> and for which the
  71     // extension has permission to access the certificate and its private key.
  72     // If <code>interactive</code> is true, the user is presented a dialog where
  73     // he can select from matching certificates and grant the extension access
  74     // to the certificate.
  75     // The selected/filtered client certificates will be passed to
  76     // <code>callback</code>.
  77     // |callback|: Will be called with the matching and, if
  78     //   <code>interactive</code> is true, selected certificates that this
  79     //   extension has access to.
  80     [nocompile] static void selectClientCertificates(
  81         SelectDetails details,
  82         SelectCallback callback);
  83
  84     // Passes the key pair of <code>certificate</code> for usage with
  85     // $(ref:platformKeys.subtleCrypto) to <code>callback</code>.
  86     // |certificate|: The certificate of a $(ref:Match) returned by
  87     //     $ref(selectClientCertificates).
  88     // |params|: Determines signature/hash algorithm parameters additionally to
  89     //     the parameters fixed by the key itself. The same parameters are
  90     //     accepted as by WebCrypto's <code>importKey</code> function, e.g.
  91     //     <code>RsaHashedImportParams</code> for a RSASSA-PKCS1-v1_5 key.
  92     //     For RSASSA-PKCS1-v1_5 keys, additionally the parameters
  93     //     <code>{ 'hash': { 'name': 'none' } }</code> are supported. The sign
  94     //     function will then apply PKCS#1 v1.5 padding and but not hash the
  95     //     given data.
  96     [nocompile] static void getKeyPair(ArrayBuffer certificate,
  97                                        object parameters,
  98                                        GetKeyPairCallback callback);
  99
 100     // An implementation of WebCrypto's
 101     // <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">
 102     // SubtleCrypto</a>
 103     // that allows crypto operations on keys of client certificates that are
 104     // available to this extension.
 105     [nocompile] static object subtleCrypto();
 106   };
 107 };
 108