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 access client certificates
   6 // managed by the platform. If the user or policy grants the permission, an
   7 // extension can use such a certficate in its custom authentication protocol.
   8 // E.g. this allows usage of platform managed certificates in third party VPNs
   9 // (see $(ref:vpnProvider chrome.vpnProvider)).
  10 namespace platformKeys {
  11   [noinline_doc] dictionary Match {
  12      // The DER encoding of a X.509 certificate.
  13      ArrayBuffer certificate;
  14
  15      // The
  16      // <a href="http://www.w3.org/TR/WebCryptoAPI/#key-algorithm-dictionary">
  17      // KeyAlgorithm</a> of the certified key. This contains algorithm
  18      // parameters that are inherent to the key of the certificate (e.g. the key
  19      // length). Other parameters like the hash function used by the sign
  20      // function are not included.
  21      object keyAlgorithm;
  22   };
  23
  24   enum ClientCertificateType {
  25     rsaSign,
  26     ecdsaSign
  27   };
  28
  29   // Analogous to TLS1.1's CertificateRequest.
  30   // See http://tools.ietf.org/html/rfc4346#section-7.4.4 .
  31   dictionary ClientCertificateRequest {
  32     // This field is a list of the types of certificates requested, sorted in
  33     // order of the server's preference. Only certificates of a type contained
  34     // in this list will be retrieved. If <code>certificateTypes</code> is the
  35     // empty list, however, certificates of any type will be returned.
  36     ClientCertificateType[] certificateTypes;
  37
  38     // List of distinguished names of certificate authorities allowed by the
  39     // server. Each entry must be a DER-encoded X.509 DistinguishedName.
  40     ArrayBuffer[] certificateAuthorities;
  41   };
  42
  43   dictionary SelectDetails {
  44     // Only certificates that match this request will be returned.
  45     ClientCertificateRequest request;
  46
  47     // If given, the <code>selectClientCertificates</code> operates on this
  48     // list. Otherwise, obtains the list of all certificates from the platform's
  49     // certificate stores that are available to this extensions.
  50     // Entries that the extension doesn't have permission for or which doesn't
  51     // match the request, are removed.
  52     ArrayBuffer[]? clientCerts;
  53
  54     // If true, the filtered list is presented to the user to manually select a
  55     // certificate and thereby granting the extension access to the
  56     // certificate(s) and key(s). Only the selected certificate(s) will be
  57     // returned. If is false, the list is reduced to all certificates that the
  58     // extension has been granted access to (automatically or manually).
  59     boolean interactive;
  60   };
  61
  62   dictionary VerificationDetails {
  63     // Each chain entry must be the DER encoding of a X.509 certificate, the
  64     // first entry must be the server certificate and each entry must certify
  65     // the entry preceding it.
  66     ArrayBuffer[] serverCertificateChain;
  67
  68     // The hostname of the server to verify the certificate for, e.g. the server
  69     // that presented the <code>serverCertificateChain</code>.
  70     DOMString hostname;
  71   };
  72
  73   dictionary VerificationResult {
  74     // The result of the trust verification: true if trust for the given
  75     // verification details could be established and false if trust is rejected
  76     // for any reason.
  77     boolean trusted;
  78
  79     // If the trust verification failed, this array contains the errors reported
  80     // by the underlying network layer. Otherwise, this array is empty.
  81     //
  82     // <strong>Note:</strong> This list is meant for debugging only and may not
  83     // contain all relevant errors. The errors returned may change in future
  84     // revisions of this API, and are not guaranteed to be forwards or backwards
  85     // compatible.
  86     DOMString[] debug_errors;
  87   };
  88
  89   // |matches|: The list of certificates that match the request, that the
  90   // extension has permission for and, if <code>interactive</code> is true, that
  91   // were selected by the user.
  92   callback SelectCallback = void (Match[] matches);
  93
  94   // The public and private
  95   // <a href="http://www.w3.org/TR/WebCryptoAPI/#dfn-CryptoKey">CryptoKey</a>
  96   // of a certificate which can only be used with
  97   // $(ref:platformKeys.subtleCrypto).
  98   // |privateKey|: Might be <code>null</code> if this extension does not have
  99   //   access to it.
 100   callback GetKeyPairCallback = void (object publicKey,
 101                                       optional object privateKey);
 102
 103   callback VerificationCallback = void (VerificationResult result);
 104
 105   interface Functions {
 106     // This function filters from a list of client certificates the ones that
 107     // are known to the platform, match <code>request</code> and for which the
 108     // extension has permission to access the certificate and its private key.
 109     // If <code>interactive</code> is true, the user is presented a dialog where
 110     // he can select from matching certificates and grant the extension access
 111     // to the certificate.
 112     // The selected/filtered client certificates will be passed to
 113     // <code>callback</code>.
 114     [nocompile] static void selectClientCertificates(
 115         SelectDetails details,
 116         SelectCallback callback);
 117
 118     // Passes the key pair of <code>certificate</code> for usage with
 119     // $(ref:platformKeys.subtleCrypto) to <code>callback</code>.
 120     // |certificate|: The certificate of a $(ref:Match) returned by
 121     // $(ref:selectClientCertificates).
 122     // |parameters|: Determines signature/hash algorithm parameters additionally
 123     //   to the parameters fixed by the key itself. The same parameters are
 124     //   accepted as by WebCrypto's <code>importKey</code> function, e.g.
 125     //   <code>RsaHashedImportParams</code> for a RSASSA-PKCS1-v1_5 key.
 126     //   For RSASSA-PKCS1-v1_5 keys, additionally the parameters
 127     //   <code>{ 'hash': { 'name': 'none' } }</code> are supported. The sign
 128     //   function will then apply PKCS#1 v1.5 padding and but not hash the
 129     //   given data.
 130     [nocompile] static void getKeyPair(ArrayBuffer certificate,
 131                                        object parameters,
 132                                        GetKeyPairCallback callback);
 133
 134     // An implementation of WebCrypto's
 135     // <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">
 136     // SubtleCrypto</a>
 137     // that allows crypto operations on keys of client certificates that are
 138     // available to this extension.
 139     [nocompile] static object subtleCrypto();
 140
 141     // Checks whether <code>details.serverCertificateChain</code> can be trusted
 142     // for <code>details.hostname</code> according to the trust settings of the
 143     // platform.
 144     // Note: The actual behavior of the trust verification is not fully
 145     // specified and might change in the future.
 146     // The API implementation verifies certificate expiration, validates the
 147     // certification path and checks trust by a known CA.
 148     // The implementation is supposed to respect the EKU serverAuth and to
 149     // support subject alternative names.
 150     static void verifyTLSServerCertificate(VerificationDetails details,
 151                                            VerificationCallback callback);
 152   };
 153 };
 154