henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 1 | /* |
| 2 | * libjingle |
| 3 | * Copyright 2004--2008, Google Inc. |
| 4 | * |
wu@webrtc.org | 2a81a38 | 2014-01-03 22:08:47 +0000 | [diff] [blame] | 5 | * Redistribution and use in source and binary forms, with or without |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 6 | * modification, are permitted provided that the following conditions are met: |
| 7 | * |
wu@webrtc.org | 2a81a38 | 2014-01-03 22:08:47 +0000 | [diff] [blame] | 8 | * 1. Redistributions of source code must retain the above copyright notice, |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 9 | * this list of conditions and the following disclaimer. |
| 10 | * 2. Redistributions in binary form must reproduce the above copyright notice, |
| 11 | * this list of conditions and the following disclaimer in the documentation |
| 12 | * and/or other materials provided with the distribution. |
wu@webrtc.org | 2a81a38 | 2014-01-03 22:08:47 +0000 | [diff] [blame] | 13 | * 3. The name of the author may not be used to endorse or promote products |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 14 | * derived from this software without specific prior written permission. |
| 15 | * |
| 16 | * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED |
wu@webrtc.org | 2a81a38 | 2014-01-03 22:08:47 +0000 | [diff] [blame] | 17 | * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 18 | * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO |
wu@webrtc.org | 2a81a38 | 2014-01-03 22:08:47 +0000 | [diff] [blame] | 19 | * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 20 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 21 | * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; |
| 22 | * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, |
wu@webrtc.org | 2a81a38 | 2014-01-03 22:08:47 +0000 | [diff] [blame] | 23 | * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR |
| 24 | * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 25 | * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 26 | */ |
| 27 | |
wu@webrtc.org | 62fe97f | 2013-10-09 15:37:36 +0000 | [diff] [blame] | 28 | #ifndef TALK_BASE_SSLSTREAMADAPTER_H_ |
| 29 | #define TALK_BASE_SSLSTREAMADAPTER_H_ |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 30 | |
| 31 | #include <string> |
| 32 | #include <vector> |
| 33 | |
| 34 | #include "talk/base/stream.h" |
| 35 | #include "talk/base/sslidentity.h" |
| 36 | |
| 37 | namespace talk_base { |
| 38 | |
| 39 | // SSLStreamAdapter : A StreamInterfaceAdapter that does SSL/TLS. |
| 40 | // After SSL has been started, the stream will only open on successful |
| 41 | // SSL verification of certificates, and the communication is |
| 42 | // encrypted of course. |
| 43 | // |
| 44 | // This class was written with SSLAdapter as a starting point. It |
| 45 | // offers a similar interface, with two differences: there is no |
| 46 | // support for a restartable SSL connection, and this class has a |
| 47 | // peer-to-peer mode. |
| 48 | // |
| 49 | // The SSL library requires initialization and cleanup. Static method |
| 50 | // for doing this are in SSLAdapter. They should possibly be moved out |
| 51 | // to a neutral class. |
| 52 | |
| 53 | |
| 54 | enum SSLRole { SSL_CLIENT, SSL_SERVER }; |
| 55 | enum SSLMode { SSL_MODE_TLS, SSL_MODE_DTLS }; |
| 56 | |
| 57 | // Errors for Read -- in the high range so no conflict with OpenSSL. |
| 58 | enum { SSE_MSG_TRUNC = 0xff0001 }; |
| 59 | |
| 60 | class SSLStreamAdapter : public StreamAdapterInterface { |
| 61 | public: |
| 62 | // Instantiate an SSLStreamAdapter wrapping the given stream, |
| 63 | // (using the selected implementation for the platform). |
| 64 | // Caller is responsible for freeing the returned object. |
| 65 | static SSLStreamAdapter* Create(StreamInterface* stream); |
| 66 | |
| 67 | explicit SSLStreamAdapter(StreamInterface* stream) |
| 68 | : StreamAdapterInterface(stream), ignore_bad_cert_(false) { } |
| 69 | |
| 70 | void set_ignore_bad_cert(bool ignore) { ignore_bad_cert_ = ignore; } |
| 71 | bool ignore_bad_cert() const { return ignore_bad_cert_; } |
| 72 | |
| 73 | // Specify our SSL identity: key and certificate. Mostly this is |
| 74 | // only used in the peer-to-peer mode (unless we actually want to |
| 75 | // provide a client certificate to a server). |
| 76 | // SSLStream takes ownership of the SSLIdentity object and will |
| 77 | // free it when appropriate. Should be called no more than once on a |
| 78 | // given SSLStream instance. |
| 79 | virtual void SetIdentity(SSLIdentity* identity) = 0; |
| 80 | |
| 81 | // Call this to indicate that we are to play the server's role in |
| 82 | // the peer-to-peer mode. |
| 83 | // The default argument is for backward compatibility |
| 84 | // TODO(ekr@rtfm.com): rename this SetRole to reflect its new function |
| 85 | virtual void SetServerRole(SSLRole role = SSL_SERVER) = 0; |
| 86 | |
| 87 | // Do DTLS or TLS |
| 88 | virtual void SetMode(SSLMode mode) = 0; |
| 89 | |
| 90 | // The mode of operation is selected by calling either |
| 91 | // StartSSLWithServer or StartSSLWithPeer. |
| 92 | // Use of the stream prior to calling either of these functions will |
| 93 | // pass data in clear text. |
| 94 | // Calling one of these functions causes SSL negotiation to begin as |
| 95 | // soon as possible: right away if the underlying wrapped stream is |
| 96 | // already opened, or else as soon as it opens. |
| 97 | // |
| 98 | // These functions return a negative error code on failure. |
| 99 | // Returning 0 means success so far, but negotiation is probably not |
| 100 | // complete and will continue asynchronously. In that case, the |
| 101 | // exposed stream will open after successful negotiation and |
| 102 | // verification, or an SE_CLOSE event will be raised if negotiation |
| 103 | // fails. |
| 104 | |
| 105 | // StartSSLWithServer starts SSL negotiation with a server in |
| 106 | // traditional mode. server_name specifies the expected server name |
| 107 | // which the server's certificate needs to specify. |
| 108 | virtual int StartSSLWithServer(const char* server_name) = 0; |
| 109 | |
| 110 | // StartSSLWithPeer starts negotiation in the special peer-to-peer |
| 111 | // mode. |
| 112 | // Generally, SetIdentity() and possibly SetServerRole() should have |
| 113 | // been called before this. |
wu@webrtc.org | 62fe97f | 2013-10-09 15:37:36 +0000 | [diff] [blame] | 114 | // SetPeerCertificate() or SetPeerCertificateDigest() must also be called. |
| 115 | // It may be called after StartSSLWithPeer() but must be called before the |
| 116 | // underlying stream opens. |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 117 | virtual int StartSSLWithPeer() = 0; |
| 118 | |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 119 | // Specify the digest of the certificate that our peer is expected to use in |
| 120 | // peer-to-peer mode. Only this certificate will be accepted during |
| 121 | // SSL verification. The certificate is assumed to have been |
| 122 | // obtained through some other secure channel (such as the XMPP |
| 123 | // channel). Unlike SetPeerCertificate(), this must specify the |
| 124 | // terminal certificate, not just a CA. |
| 125 | // SSLStream makes a copy of the digest value. |
| 126 | virtual bool SetPeerCertificateDigest(const std::string& digest_alg, |
| 127 | const unsigned char* digest_val, |
| 128 | size_t digest_len) = 0; |
| 129 | |
wu@webrtc.org | 2a81a38 | 2014-01-03 22:08:47 +0000 | [diff] [blame] | 130 | // Retrieves the peer's X.509 certificate, if a connection has been |
| 131 | // established. It returns the transmitted over SSL, including the entire |
| 132 | // chain. The returned certificate is owned by the caller. |
wu@webrtc.org | 62fe97f | 2013-10-09 15:37:36 +0000 | [diff] [blame] | 133 | virtual bool GetPeerCertificate(SSLCertificate** cert) const = 0; |
| 134 | |
henrike@webrtc.org | 0e118e7 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 135 | // Key Exporter interface from RFC 5705 |
| 136 | // Arguments are: |
| 137 | // label -- the exporter label. |
| 138 | // part of the RFC defining each exporter |
| 139 | // usage (IN) |
| 140 | // context/context_len -- a context to bind to for this connection; |
| 141 | // optional, can be NULL, 0 (IN) |
| 142 | // use_context -- whether to use the context value |
| 143 | // (needed to distinguish no context from |
| 144 | // zero-length ones). |
| 145 | // result -- where to put the computed value |
| 146 | // result_len -- the length of the computed value |
| 147 | virtual bool ExportKeyingMaterial(const std::string& label, |
| 148 | const uint8* context, |
| 149 | size_t context_len, |
| 150 | bool use_context, |
| 151 | uint8* result, |
| 152 | size_t result_len) { |
| 153 | return false; // Default is unsupported |
| 154 | } |
| 155 | |
| 156 | |
| 157 | // DTLS-SRTP interface |
| 158 | virtual bool SetDtlsSrtpCiphers(const std::vector<std::string>& ciphers) { |
| 159 | return false; |
| 160 | } |
| 161 | |
| 162 | virtual bool GetDtlsSrtpCipher(std::string* cipher) { |
| 163 | return false; |
| 164 | } |
| 165 | |
| 166 | // Capabilities testing |
| 167 | static bool HaveDtls(); |
| 168 | static bool HaveDtlsSrtp(); |
| 169 | static bool HaveExporter(); |
| 170 | |
| 171 | // If true, the server certificate need not match the configured |
| 172 | // server_name, and in fact missing certificate authority and other |
| 173 | // verification errors are ignored. |
| 174 | bool ignore_bad_cert_; |
| 175 | }; |
| 176 | |
| 177 | } // namespace talk_base |
| 178 | |
wu@webrtc.org | 62fe97f | 2013-10-09 15:37:36 +0000 | [diff] [blame] | 179 | #endif // TALK_BASE_SSLSTREAMADAPTER_H_ |