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 verificaiton: 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
  80   // |matches|: The list of certificates that match the request, that the
  81   // extension has permission for and, if <code>interactive</code> is true, that
  82   // were selected by the user.
  83   callback SelectCallback = void (Match[] matches);
  84
  85   // The public and private
  86   // <a href="http://www.w3.org/TR/WebCryptoAPI/#dfn-CryptoKey">CryptoKey</a>
  87   // of a certificate which can only be used with
  88   // $(ref:platformKeys.subtleCrypto).
  89   // |privateKey|: Might be <code>null</code> if this extension does not have
  90   //   access to it.
  91   callback GetKeyPairCallback = void (object publicKey,
  92                                       optional object privateKey);
  93
  94   callback VerificationCallback = void (VerificationResult result);
  95
  96   interface Functions {
  97     // This function filters from a list of client certificates the ones that
  98     // are known to the platform, match <code>request</code> and for which the
  99     // extension has permission to access the certificate and its private key.
 100     // If <code>interactive</code> is true, the user is presented a dialog where
 101     // he can select from matching certificates and grant the extension access
 102     // to the certificate.
 103     // The selected/filtered client certificates will be passed to
 104     // <code>callback</code>.
 105     [nocompile] static void selectClientCertificates(
 106         SelectDetails details,
 107         SelectCallback callback);
 108
 109     // Passes the key pair of <code>certificate</code> for usage with
 110     // $(ref:platformKeys.subtleCrypto) to <code>callback</code>.
 111     // |certificate|: The certificate of a $(ref:Match) returned by
 112     // $(ref:selectClientCertificates).
 113     // |parameters|: Determines signature/hash algorithm parameters additionally
 114     //   to the parameters fixed by the key itself. The same parameters are
 115     //   accepted as by WebCrypto's <code>importKey</code> function, e.g.
 116     //   <code>RsaHashedImportParams</code> for a RSASSA-PKCS1-v1_5 key.
 117     //   For RSASSA-PKCS1-v1_5 keys, additionally the parameters
 118     //   <code>{ 'hash': { 'name': 'none' } }</code> are supported. The sign
 119     //   function will then apply PKCS#1 v1.5 padding and but not hash the
 120     //   given data.
 121     [nocompile] static void getKeyPair(ArrayBuffer certificate,
 122                                        object parameters,
 123                                        GetKeyPairCallback callback);
 124
 125     // An implementation of WebCrypto's
 126     // <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">
 127     // SubtleCrypto</a>
 128     // that allows crypto operations on keys of client certificates that are
 129     // available to this extension.
 130     [nocompile] static object subtleCrypto();
 131
 132     // Checks whether <code>details.serverCertificateChain</code> can be trusted
 133     // for <code>details.hostname</code> according to the trust settings of the
 134     // platform.
 135     // Note: The actual behavior of the trust verification is not fully
 136     // specified and might change in the future.
 137     // The API implementation verifies certificate expiration, validates the
 138     // certification path and checks trust by a known CA.
 139     // The implementation is supposed to respect the EKU serverAuth and to
 140     // support subject alternative names.
 141     static void verifyTLSServerCertificate(VerificationDetails details,
 142                                            VerificationCallback callback);
 143   };
 144 };
 145