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