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
|
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef CryptoHistograms_h
#define CryptoHistograms_h
#include "public/platform/WebCrypto.h"
// -------------------------------------------------------------
// Overview
// -------------------------------------------------------------
//
// The high level goal is to measure the popularity of WebCrypto methods and
// algorithms. This data will inform future optimizations and deprecation.
//
// This is accomplished by decomposing each call to crypto.* into a set of
// "features".
//
// These features include the name of the method, and the algorithm name. For
// the complete list refer to UseCounter.h (features are prefixed by Crypto* or
// SubtleCrypto*).
//
// This approach allows answering questions like:
// * "How often was SHA1 used?"
// * "How often was crypto.subtle.wrapKey() called?"
//
// Note that for practical matters, features are counted independently. So we
// cannot answer questions that span multiple features like:
// "How often was SHA1 used when doing ECDSA signing?"
// But we could separately answer each of:
// * "How often was SHA1 used?"
// * "How often was ECDSA used?"
// * "How often was crypto.subtle.sign() used?"
//
// Lastly, to explore the results of this instrumentation use the public
// dashboard (www.chromestatus.com), or the (internal) UMA histogram
// dashboard.
//
// -------------------------------------------------------------
// Features
// -------------------------------------------------------------
//
// WebCrypto operations are complex and have many parameters. The important
// parameters are distilled to a set of features, the most important being:
//
// * The name of the operation (i.e. "crypto.subtle.encrypt",
// "crypto.subtle.exportKey")
// * The name of the algorithm (i.e. "AES-GCM", "RSA-PSS", "SHA-1")
//
// In the case where the algorithm makes use of an inner hash function (for
// instance HMAC), that hash algorithm is also considered as having been used.
// This means that when reading usage counters for hash functions, they are NOT
// exclusive to crypto.subtle.digest().
//
// Here are some examples to illustrate how it works:
//
// * Consumer calls crypto.subtle.encrypt() using a 128-bit AES-GCM key:
// ==> Increment SubtleCryptoEncrypt
// ==> Increment CryptAlgorithmAesGcm
//
// * Consumer calls crypto.subtle.sign() using an HMAC key bound to SHA1:
// ==> Increment SubtleCryptoSign
// ==> Increment CryptoAlgorithmHmac
// ==> Increment CryptoAlgorithmSha1
//
// * Consumer calls crypto.subtle.wrapKey() using a 1024 bit RSA-OAEP key with
// SHA-256 as the wrapping key, and wrapping a ECDSA P-521 SHA-512 key:
// ==> Increment SubtleCryptoWrapKey
// ==> Increment CryptoAlgorithmRsaOaep
// ==> Increment CryptoAlgorithmSha256
// ==> Increment CryptoAlgorithmEcdsa
// ==> Increment CryptoAlgorithmSha512
//
// (Note that the algorithm parameters of the key being exported/wrapped are
// also recorded for consistency)
//
// * Consumer calls crypto.subtle.exportKey() on a 2048 bit RSA-PSS key
// using SHA-512:
// ==> Increment SubtleCryptoExportKey
// ==> Increment CryptoAlgorithmRsaPss
// ==> Increment CryptoAlgorithmSha512
//
// (Note that even though the key is just being exported, all of its
// algorithm parameters are also recorded)
//
// -----------------------
// Caveats
// -----------------------
//
// * Usage counters are incomplete for shared workers and service workers
// (http://crbug.com/376039)
//
// * Measurements when there are errors (the Promise is rejected) are
// inconsistent.
//
// In some cases the underlying UseCounter is incremented, in
// others it isn't. It depends how early the error occured. For instance if
// an error was thrown by the binding layer, then no usage will be recorded
// for the algorithm/key in question.
//
// Most of these early errors correspond with caller errors of WebCrypto so
// they shouldn't skew the stats.
//
// But it is important to realize that UNSUPPORTED ALGORITHMS WILL similarly
// error early on and not count the usage.
namespace blink {
class ExecutionContext;
class WebCryptoAlgorithm;
class WebCryptoKey;
// Log the usage of a particular WebCryptoAlgorithm (i.e. operation).
void histogramAlgorithm(ExecutionContext*, const WebCryptoAlgorithm&);
// Log the usage of a particular WebCryptoKey.
void histogramKey(ExecutionContext*, const WebCryptoKey&);
// This is a convenience function for calling histogramAlgorithm() and
// histogramKey().
void histogramAlgorithmAndKey(ExecutionContext*,
const WebCryptoAlgorithm&,
const WebCryptoKey&);
} // namespace blink
#endif
|
