henrike@webrtc.org | f048872 | 2014-05-13 18:00:26 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2004 The WebRTC Project Authors. All rights reserved. |
| 3 | * |
| 4 | * Use of this source code is governed by a BSD-style license |
| 5 | * that can be found in the LICENSE file in the root of the source |
| 6 | * tree. An additional intellectual property rights grant can be found |
| 7 | * in the file PATENTS. All contributing project authors may |
| 8 | * be found in the AUTHORS file in the root of the source tree. |
| 9 | */ |
| 10 | |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 11 | #ifndef RTC_BASE_SSLSTREAMADAPTER_H_ |
| 12 | #define RTC_BASE_SSLSTREAMADAPTER_H_ |
henrike@webrtc.org | f048872 | 2014-05-13 18:00:26 +0000 | [diff] [blame] | 13 | |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 14 | #include <memory> |
| 15 | #include <string> |
| 16 | #include <vector> |
henrike@webrtc.org | f048872 | 2014-05-13 18:00:26 +0000 | [diff] [blame] | 17 | |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 18 | #include "rtc_base/sslidentity.h" |
| 19 | #include "rtc_base/stream.h" |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 20 | |
| 21 | namespace rtc { |
| 22 | |
| 23 | // Constants for SSL profile. |
| 24 | const int TLS_NULL_WITH_NULL_NULL = 0; |
| 25 | |
| 26 | // Constants for SRTP profiles. |
| 27 | const int SRTP_INVALID_CRYPTO_SUITE = 0; |
| 28 | #ifndef SRTP_AES128_CM_SHA1_80 |
| 29 | const int SRTP_AES128_CM_SHA1_80 = 0x0001; |
| 30 | #endif |
| 31 | #ifndef SRTP_AES128_CM_SHA1_32 |
| 32 | const int SRTP_AES128_CM_SHA1_32 = 0x0002; |
| 33 | #endif |
| 34 | #ifndef SRTP_AEAD_AES_128_GCM |
| 35 | const int SRTP_AEAD_AES_128_GCM = 0x0007; |
| 36 | #endif |
| 37 | #ifndef SRTP_AEAD_AES_256_GCM |
| 38 | const int SRTP_AEAD_AES_256_GCM = 0x0008; |
| 39 | #endif |
| 40 | |
| 41 | // Names of SRTP profiles listed above. |
| 42 | // 128-bit AES with 80-bit SHA-1 HMAC. |
| 43 | extern const char CS_AES_CM_128_HMAC_SHA1_80[]; |
| 44 | // 128-bit AES with 32-bit SHA-1 HMAC. |
| 45 | extern const char CS_AES_CM_128_HMAC_SHA1_32[]; |
| 46 | // 128-bit AES GCM with 16 byte AEAD auth tag. |
| 47 | extern const char CS_AEAD_AES_128_GCM[]; |
| 48 | // 256-bit AES GCM with 16 byte AEAD auth tag. |
| 49 | extern const char CS_AEAD_AES_256_GCM[]; |
| 50 | |
| 51 | // Given the DTLS-SRTP protection profile ID, as defined in |
| 52 | // https://tools.ietf.org/html/rfc4568#section-6.2 , return the SRTP profile |
| 53 | // name, as defined in https://tools.ietf.org/html/rfc5764#section-4.1.2. |
| 54 | std::string SrtpCryptoSuiteToName(int crypto_suite); |
| 55 | |
| 56 | // The reverse of above conversion. |
| 57 | int SrtpCryptoSuiteFromName(const std::string& crypto_suite); |
| 58 | |
| 59 | // Get key length and salt length for given crypto suite. Returns true for |
| 60 | // valid suites, otherwise false. |
| 61 | bool GetSrtpKeyAndSaltLengths(int crypto_suite, int *key_length, |
| 62 | int *salt_length); |
| 63 | |
| 64 | // Returns true if the given crypto suite id uses a GCM cipher. |
| 65 | bool IsGcmCryptoSuite(int crypto_suite); |
| 66 | |
| 67 | // Returns true if the given crypto suite name uses a GCM cipher. |
| 68 | bool IsGcmCryptoSuiteName(const std::string& crypto_suite); |
| 69 | |
| 70 | struct CryptoOptions { |
| 71 | CryptoOptions() {} |
| 72 | |
| 73 | // Helper method to return an instance of the CryptoOptions with GCM crypto |
| 74 | // suites disabled. This method should be used instead of depending on current |
| 75 | // default values set by the constructor. |
| 76 | static CryptoOptions NoGcm(); |
| 77 | |
| 78 | // Enable GCM crypto suites from RFC 7714 for SRTP. GCM will only be used |
| 79 | // if both sides enable it. |
| 80 | bool enable_gcm_crypto_suites = false; |
jbauch | 5869f50 | 2017-06-29 12:31:36 -0700 | [diff] [blame] | 81 | |
| 82 | // If set to true, encrypted RTP header extensions as defined in RFC 6904 |
| 83 | // will be negotiated. They will only be used if both peers support them. |
| 84 | bool enable_encrypted_rtp_header_extensions = false; |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 85 | }; |
| 86 | |
| 87 | // Returns supported crypto suites, given |crypto_options|. |
| 88 | // CS_AES_CM_128_HMAC_SHA1_32 will be preferred by default. |
| 89 | std::vector<int> GetSupportedDtlsSrtpCryptoSuites( |
| 90 | const rtc::CryptoOptions& crypto_options); |
| 91 | |
| 92 | // SSLStreamAdapter : A StreamInterfaceAdapter that does SSL/TLS. |
| 93 | // After SSL has been started, the stream will only open on successful |
| 94 | // SSL verification of certificates, and the communication is |
| 95 | // encrypted of course. |
| 96 | // |
| 97 | // This class was written with SSLAdapter as a starting point. It |
| 98 | // offers a similar interface, with two differences: there is no |
| 99 | // support for a restartable SSL connection, and this class has a |
| 100 | // peer-to-peer mode. |
| 101 | // |
| 102 | // The SSL library requires initialization and cleanup. Static method |
| 103 | // for doing this are in SSLAdapter. They should possibly be moved out |
| 104 | // to a neutral class. |
| 105 | |
| 106 | |
| 107 | enum SSLRole { SSL_CLIENT, SSL_SERVER }; |
| 108 | enum SSLMode { SSL_MODE_TLS, SSL_MODE_DTLS }; |
| 109 | enum SSLProtocolVersion { |
| 110 | SSL_PROTOCOL_TLS_10, |
| 111 | SSL_PROTOCOL_TLS_11, |
| 112 | SSL_PROTOCOL_TLS_12, |
| 113 | SSL_PROTOCOL_DTLS_10 = SSL_PROTOCOL_TLS_11, |
| 114 | SSL_PROTOCOL_DTLS_12 = SSL_PROTOCOL_TLS_12, |
| 115 | }; |
| 116 | enum class SSLPeerCertificateDigestError { |
| 117 | NONE, |
| 118 | UNKNOWN_ALGORITHM, |
| 119 | INVALID_LENGTH, |
| 120 | VERIFICATION_FAILED, |
| 121 | }; |
| 122 | |
| 123 | // Errors for Read -- in the high range so no conflict with OpenSSL. |
| 124 | enum { SSE_MSG_TRUNC = 0xff0001 }; |
| 125 | |
| 126 | // Used to send back UMA histogram value. Logged when Dtls handshake fails. |
| 127 | enum class SSLHandshakeError { UNKNOWN, INCOMPATIBLE_CIPHERSUITE, MAX_VALUE }; |
| 128 | |
| 129 | class SSLStreamAdapter : public StreamAdapterInterface { |
| 130 | public: |
| 131 | // Instantiate an SSLStreamAdapter wrapping the given stream, |
| 132 | // (using the selected implementation for the platform). |
| 133 | // Caller is responsible for freeing the returned object. |
| 134 | static SSLStreamAdapter* Create(StreamInterface* stream); |
| 135 | |
| 136 | explicit SSLStreamAdapter(StreamInterface* stream); |
| 137 | ~SSLStreamAdapter() override; |
| 138 | |
| 139 | void set_ignore_bad_cert(bool ignore) { ignore_bad_cert_ = ignore; } |
| 140 | bool ignore_bad_cert() const { return ignore_bad_cert_; } |
| 141 | |
| 142 | void set_client_auth_enabled(bool enabled) { client_auth_enabled_ = enabled; } |
| 143 | bool client_auth_enabled() const { return client_auth_enabled_; } |
| 144 | |
| 145 | // Specify our SSL identity: key and certificate. SSLStream takes ownership |
| 146 | // of the SSLIdentity object and will free it when appropriate. Should be |
| 147 | // called no more than once on a given SSLStream instance. |
| 148 | virtual void SetIdentity(SSLIdentity* identity) = 0; |
| 149 | |
| 150 | // Call this to indicate that we are to play the server role (or client role, |
| 151 | // if the default argument is replaced by SSL_CLIENT). |
| 152 | // The default argument is for backward compatibility. |
| 153 | // TODO(ekr@rtfm.com): rename this SetRole to reflect its new function |
| 154 | virtual void SetServerRole(SSLRole role = SSL_SERVER) = 0; |
| 155 | |
| 156 | // Do DTLS or TLS. |
| 157 | virtual void SetMode(SSLMode mode) = 0; |
| 158 | |
| 159 | // Set maximum supported protocol version. The highest version supported by |
| 160 | // both ends will be used for the connection, i.e. if one party supports |
| 161 | // DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used. |
| 162 | // If requested version is not supported by underlying crypto library, the |
| 163 | // next lower will be used. |
| 164 | virtual void SetMaxProtocolVersion(SSLProtocolVersion version) = 0; |
| 165 | |
| 166 | // Set the initial retransmission timeout for DTLS messages. When the timeout |
| 167 | // expires, the message gets retransmitted and the timeout is exponentially |
| 168 | // increased. |
| 169 | // This should only be called before StartSSL(). |
| 170 | virtual void SetInitialRetransmissionTimeout(int timeout_ms) = 0; |
| 171 | |
| 172 | // StartSSL starts negotiation with a peer, whose certificate is verified |
| 173 | // using the certificate digest. Generally, SetIdentity() and possibly |
| 174 | // SetServerRole() should have been called before this. |
| 175 | // SetPeerCertificateDigest() must also be called. It may be called after |
| 176 | // StartSSLWithPeer() but must be called before the underlying stream opens. |
| 177 | // |
| 178 | // Use of the stream prior to calling StartSSL will pass data in clear text. |
| 179 | // Calling StartSSL causes SSL negotiation to begin as soon as possible: right |
| 180 | // away if the underlying wrapped stream is already opened, or else as soon as |
| 181 | // it opens. |
| 182 | // |
| 183 | // StartSSL returns a negative error code on failure. Returning 0 means |
| 184 | // success so far, but negotiation is probably not complete and will continue |
| 185 | // asynchronously. In that case, the exposed stream will open after |
| 186 | // successful negotiation and verification, or an SE_CLOSE event will be |
| 187 | // raised if negotiation fails. |
| 188 | virtual int StartSSL() = 0; |
| 189 | |
| 190 | // Specify the digest of the certificate that our peer is expected to use. |
| 191 | // Only this certificate will be accepted during SSL verification. The |
| 192 | // certificate is assumed to have been obtained through some other secure |
| 193 | // channel (such as the signaling channel). This must specify the terminal |
| 194 | // certificate, not just a CA. SSLStream makes a copy of the digest value. |
| 195 | // |
| 196 | // Returns true if successful. |
| 197 | // |error| is optional and provides more information about the failure. |
| 198 | virtual bool SetPeerCertificateDigest( |
| 199 | const std::string& digest_alg, |
| 200 | const unsigned char* digest_val, |
| 201 | size_t digest_len, |
| 202 | SSLPeerCertificateDigestError* error = nullptr) = 0; |
| 203 | |
| 204 | // Retrieves the peer's X.509 certificate, if a connection has been |
| 205 | // established. It returns the transmitted over SSL, including the entire |
| 206 | // chain. |
| 207 | virtual std::unique_ptr<SSLCertificate> GetPeerCertificate() const = 0; |
| 208 | |
| 209 | // Retrieves the IANA registration id of the cipher suite used for the |
| 210 | // connection (e.g. 0x2F for "TLS_RSA_WITH_AES_128_CBC_SHA"). |
| 211 | virtual bool GetSslCipherSuite(int* cipher_suite); |
| 212 | |
| 213 | virtual int GetSslVersion() const = 0; |
| 214 | |
| 215 | // Key Exporter interface from RFC 5705 |
| 216 | // Arguments are: |
| 217 | // label -- the exporter label. |
| 218 | // part of the RFC defining each exporter |
| 219 | // usage (IN) |
| 220 | // context/context_len -- a context to bind to for this connection; |
| 221 | // optional, can be null, 0 (IN) |
| 222 | // use_context -- whether to use the context value |
| 223 | // (needed to distinguish no context from |
| 224 | // zero-length ones). |
| 225 | // result -- where to put the computed value |
| 226 | // result_len -- the length of the computed value |
| 227 | virtual bool ExportKeyingMaterial(const std::string& label, |
| 228 | const uint8_t* context, |
| 229 | size_t context_len, |
| 230 | bool use_context, |
| 231 | uint8_t* result, |
| 232 | size_t result_len); |
| 233 | |
| 234 | // DTLS-SRTP interface |
| 235 | virtual bool SetDtlsSrtpCryptoSuites(const std::vector<int>& crypto_suites); |
| 236 | virtual bool GetDtlsSrtpCryptoSuite(int* crypto_suite); |
| 237 | |
| 238 | // Returns true if a TLS connection has been established. |
| 239 | // The only difference between this and "GetState() == SE_OPEN" is that if |
| 240 | // the peer certificate digest hasn't been verified, the state will still be |
| 241 | // SS_OPENING but IsTlsConnected should return true. |
| 242 | virtual bool IsTlsConnected() = 0; |
| 243 | |
| 244 | // Capabilities testing. |
| 245 | // Used to have "DTLS supported", "DTLS-SRTP supported" etc. methods, but now |
| 246 | // that's assumed. |
| 247 | static bool IsBoringSsl(); |
| 248 | |
| 249 | // Returns true iff the supplied cipher is deemed to be strong. |
| 250 | // TODO(torbjorng): Consider removing the KeyType argument. |
| 251 | static bool IsAcceptableCipher(int cipher, KeyType key_type); |
| 252 | static bool IsAcceptableCipher(const std::string& cipher, KeyType key_type); |
| 253 | |
| 254 | // TODO(guoweis): Move this away from a static class method. Currently this is |
| 255 | // introduced such that any caller could depend on sslstreamadapter.h without |
| 256 | // depending on specific SSL implementation. |
| 257 | static std::string SslCipherSuiteToName(int cipher_suite); |
| 258 | |
| 259 | // Use our timeutils.h source of timing in BoringSSL, allowing us to test |
| 260 | // using a fake clock. |
| 261 | static void enable_time_callback_for_testing(); |
| 262 | |
| 263 | sigslot::signal1<SSLHandshakeError> SignalSSLHandshakeError; |
| 264 | |
| 265 | private: |
| 266 | // If true, the server certificate need not match the configured |
| 267 | // server_name, and in fact missing certificate authority and other |
| 268 | // verification errors are ignored. |
| 269 | bool ignore_bad_cert_; |
| 270 | |
| 271 | // If true (default), the client is required to provide a certificate during |
| 272 | // handshake. If no certificate is given, handshake fails. This applies to |
| 273 | // server mode only. |
| 274 | bool client_auth_enabled_; |
| 275 | }; |
| 276 | |
| 277 | } // namespace rtc |
henrike@webrtc.org | f048872 | 2014-05-13 18:00:26 +0000 | [diff] [blame] | 278 | |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 279 | #endif // RTC_BASE_SSLSTREAMADAPTER_H_ |