1 // Copyright 2015 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef NET_SSL_SSL_PRIVATE_KEY_H_ 6 #define NET_SSL_SSL_PRIVATE_KEY_H_ 7 8 #include <stdint.h> 9 10 #include <vector> 11 12 #include "base/containers/span.h" 13 #include "base/functional/callback_forward.h" 14 #include "base/memory/ref_counted.h" 15 #include "net/base/net_errors.h" 16 #include "net/base/net_export.h" 17 18 namespace net { 19 20 // An interface for a private key for use with SSL client authentication. A 21 // private key may be used with multiple signature algorithms, so methods use 22 // `SSL_SIGN_*` constants from BoringSSL, which correspond to TLS 1.3 23 // SignatureScheme values. 24 // 25 // Note that although ECDSA constants are named like 26 // `SSL_SIGN_ECDSA_SECP256R1_SHA256`, they may be used with any curve for 27 // purposes of this API. This discrepancy is due to differences between TLS 1.2 28 // and TLS 1.3. 29 // 30 // Implementations of this class do not need to handle the 31 // `SSL_SIGN_RSA_PKCS1_SHA256_LEGACY` codepoint, which re-enables 32 // RSASSA-PKCS1-v1_5 for TLS 1.3. SSLClientSocket will automatically convert to 33 // `SSL_SIGN_RSA_PKCS1_SHA256` as needed. 34 class NET_EXPORT SSLPrivateKey 35 : public base::RefCountedThreadSafe<SSLPrivateKey> { 36 public: 37 using SignCallback = 38 base::OnceCallback<void(Error, const std::vector<uint8_t>&)>; 39 40 SSLPrivateKey() = default; 41 42 SSLPrivateKey(const SSLPrivateKey&) = delete; 43 SSLPrivateKey& operator=(const SSLPrivateKey&) = delete; 44 45 // Returns a human-readable name of the provider that backs this 46 // SSLPrivateKey, for debugging. If not applicable or available, return the 47 // empty string. 48 virtual std::string GetProviderName() = 0; 49 50 // Returns the algorithms that are supported by the key in decreasing 51 // preference for TLS 1.2 and later. 52 virtual std::vector<uint16_t> GetAlgorithmPreferences() = 0; 53 54 // Asynchronously signs an `input` with the specified TLS signing algorithm. 55 // `input` is an unhashed message to be signed. On completion, it calls 56 // `callback` with the signature or an error code if the operation failed. 57 virtual void Sign(uint16_t algorithm, 58 base::span<const uint8_t> input, 59 SignCallback callback) = 0; 60 61 // Returns the default signature algorithm preferences for the specified key 62 // type, which should be a BoringSSL `EVP_PKEY_*` constant. RSA keys which use 63 // this must support PKCS #1 v1.5 signatures with SHA-1, SHA-256, SHA-384, and 64 // SHA-512. If `supports_pss` is true, they must additionally support PSS 65 // signatures with SHA-256, SHA-384, and SHA-512. ECDSA keys must support 66 // SHA-256, SHA-384, SHA-512. 67 // 68 // Keys with more specific capabilities or preferences should return a custom 69 // list. 70 static std::vector<uint16_t> DefaultAlgorithmPreferences(int type, 71 bool supports_pss); 72 73 protected: 74 virtual ~SSLPrivateKey() = default; 75 76 private: 77 friend class base::RefCountedThreadSafe<SSLPrivateKey>; 78 }; 79 80 } // namespace net 81 82 #endif // NET_SSL_SSL_PRIVATE_KEY_H_ 83