henrike@webrtc.org | f7795df | 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 | |
| 11 | #ifndef WEBRTC_BASE_SSLSTREAMADAPTER_H_ |
| 12 | #define WEBRTC_BASE_SSLSTREAMADAPTER_H_ |
| 13 | |
| 14 | #include <string> |
| 15 | #include <vector> |
| 16 | |
| 17 | #include "webrtc/base/stream.h" |
| 18 | #include "webrtc/base/sslidentity.h" |
| 19 | |
| 20 | namespace rtc { |
| 21 | |
| 22 | // SSLStreamAdapter : A StreamInterfaceAdapter that does SSL/TLS. |
| 23 | // After SSL has been started, the stream will only open on successful |
| 24 | // SSL verification of certificates, and the communication is |
| 25 | // encrypted of course. |
| 26 | // |
| 27 | // This class was written with SSLAdapter as a starting point. It |
| 28 | // offers a similar interface, with two differences: there is no |
| 29 | // support for a restartable SSL connection, and this class has a |
| 30 | // peer-to-peer mode. |
| 31 | // |
| 32 | // The SSL library requires initialization and cleanup. Static method |
| 33 | // for doing this are in SSLAdapter. They should possibly be moved out |
| 34 | // to a neutral class. |
| 35 | |
| 36 | |
| 37 | enum SSLRole { SSL_CLIENT, SSL_SERVER }; |
| 38 | enum SSLMode { SSL_MODE_TLS, SSL_MODE_DTLS }; |
| 39 | |
| 40 | // Errors for Read -- in the high range so no conflict with OpenSSL. |
| 41 | enum { SSE_MSG_TRUNC = 0xff0001 }; |
| 42 | |
| 43 | class SSLStreamAdapter : public StreamAdapterInterface { |
| 44 | public: |
| 45 | // Instantiate an SSLStreamAdapter wrapping the given stream, |
| 46 | // (using the selected implementation for the platform). |
| 47 | // Caller is responsible for freeing the returned object. |
| 48 | static SSLStreamAdapter* Create(StreamInterface* stream); |
| 49 | |
| 50 | explicit SSLStreamAdapter(StreamInterface* stream) |
| 51 | : StreamAdapterInterface(stream), ignore_bad_cert_(false) { } |
| 52 | |
| 53 | void set_ignore_bad_cert(bool ignore) { ignore_bad_cert_ = ignore; } |
| 54 | bool ignore_bad_cert() const { return ignore_bad_cert_; } |
| 55 | |
| 56 | // Specify our SSL identity: key and certificate. Mostly this is |
| 57 | // only used in the peer-to-peer mode (unless we actually want to |
| 58 | // provide a client certificate to a server). |
| 59 | // SSLStream takes ownership of the SSLIdentity object and will |
| 60 | // free it when appropriate. Should be called no more than once on a |
| 61 | // given SSLStream instance. |
| 62 | virtual void SetIdentity(SSLIdentity* identity) = 0; |
| 63 | |
| 64 | // Call this to indicate that we are to play the server's role in |
| 65 | // the peer-to-peer mode. |
| 66 | // The default argument is for backward compatibility |
| 67 | // TODO(ekr@rtfm.com): rename this SetRole to reflect its new function |
| 68 | virtual void SetServerRole(SSLRole role = SSL_SERVER) = 0; |
| 69 | |
| 70 | // Do DTLS or TLS |
| 71 | virtual void SetMode(SSLMode mode) = 0; |
| 72 | |
| 73 | // The mode of operation is selected by calling either |
| 74 | // StartSSLWithServer or StartSSLWithPeer. |
| 75 | // Use of the stream prior to calling either of these functions will |
| 76 | // pass data in clear text. |
| 77 | // Calling one of these functions causes SSL negotiation to begin as |
| 78 | // soon as possible: right away if the underlying wrapped stream is |
| 79 | // already opened, or else as soon as it opens. |
| 80 | // |
| 81 | // These functions return a negative error code on failure. |
| 82 | // Returning 0 means success so far, but negotiation is probably not |
| 83 | // complete and will continue asynchronously. In that case, the |
| 84 | // exposed stream will open after successful negotiation and |
| 85 | // verification, or an SE_CLOSE event will be raised if negotiation |
| 86 | // fails. |
| 87 | |
| 88 | // StartSSLWithServer starts SSL negotiation with a server in |
| 89 | // traditional mode. server_name specifies the expected server name |
| 90 | // which the server's certificate needs to specify. |
| 91 | virtual int StartSSLWithServer(const char* server_name) = 0; |
| 92 | |
| 93 | // StartSSLWithPeer starts negotiation in the special peer-to-peer |
| 94 | // mode. |
| 95 | // Generally, SetIdentity() and possibly SetServerRole() should have |
| 96 | // been called before this. |
| 97 | // SetPeerCertificate() or SetPeerCertificateDigest() must also be called. |
| 98 | // It may be called after StartSSLWithPeer() but must be called before the |
| 99 | // underlying stream opens. |
| 100 | virtual int StartSSLWithPeer() = 0; |
| 101 | |
| 102 | // Specify the digest of the certificate that our peer is expected to use in |
| 103 | // peer-to-peer mode. Only this certificate will be accepted during |
| 104 | // SSL verification. The certificate is assumed to have been |
| 105 | // obtained through some other secure channel (such as the XMPP |
| 106 | // channel). Unlike SetPeerCertificate(), this must specify the |
| 107 | // terminal certificate, not just a CA. |
| 108 | // SSLStream makes a copy of the digest value. |
| 109 | virtual bool SetPeerCertificateDigest(const std::string& digest_alg, |
| 110 | const unsigned char* digest_val, |
| 111 | size_t digest_len) = 0; |
| 112 | |
| 113 | // Retrieves the peer's X.509 certificate, if a connection has been |
| 114 | // established. It returns the transmitted over SSL, including the entire |
| 115 | // chain. The returned certificate is owned by the caller. |
| 116 | virtual bool GetPeerCertificate(SSLCertificate** cert) const = 0; |
| 117 | |
| 118 | // Key Exporter interface from RFC 5705 |
| 119 | // Arguments are: |
| 120 | // label -- the exporter label. |
| 121 | // part of the RFC defining each exporter |
| 122 | // usage (IN) |
| 123 | // context/context_len -- a context to bind to for this connection; |
| 124 | // optional, can be NULL, 0 (IN) |
| 125 | // use_context -- whether to use the context value |
| 126 | // (needed to distinguish no context from |
| 127 | // zero-length ones). |
| 128 | // result -- where to put the computed value |
| 129 | // result_len -- the length of the computed value |
| 130 | virtual bool ExportKeyingMaterial(const std::string& label, |
| 131 | const uint8* context, |
| 132 | size_t context_len, |
| 133 | bool use_context, |
| 134 | uint8* result, |
| 135 | size_t result_len) { |
| 136 | return false; // Default is unsupported |
| 137 | } |
| 138 | |
| 139 | |
| 140 | // DTLS-SRTP interface |
| 141 | virtual bool SetDtlsSrtpCiphers(const std::vector<std::string>& ciphers) { |
| 142 | return false; |
| 143 | } |
| 144 | |
| 145 | virtual bool GetDtlsSrtpCipher(std::string* cipher) { |
| 146 | return false; |
| 147 | } |
| 148 | |
| 149 | // Capabilities testing |
| 150 | static bool HaveDtls(); |
| 151 | static bool HaveDtlsSrtp(); |
| 152 | static bool HaveExporter(); |
| 153 | |
| 154 | // If true, the server certificate need not match the configured |
| 155 | // server_name, and in fact missing certificate authority and other |
| 156 | // verification errors are ignored. |
| 157 | bool ignore_bad_cert_; |
| 158 | }; |
| 159 | |
| 160 | } // namespace rtc |
| 161 | |
| 162 | #endif // WEBRTC_BASE_SSLSTREAMADAPTER_H_ |