1 /* 2 * libjingle 3 * Copyright 2004--2008, Google Inc. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, 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. 13 * 3. The name of the author may not be used to endorse or promote products 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 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 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, 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 25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #ifndef TALK_BASE_SSLSTREAMADAPTER_H__ 29 #define TALK_BASE_SSLSTREAMADAPTER_H__ 30 31 #include "talk/base/stream.h" 32 #include "talk/base/sslidentity.h" 33 34 namespace talk_base { 35 36 // SSLStreamAdapter : A StreamInterfaceAdapter that does SSL/TLS. 37 // After SSL has been started, the stream will only open on successful 38 // SSL verification of certificates, and the communication is 39 // encrypted of course. 40 // 41 // This class was written with SSLAdapter as a starting point. It 42 // offers a similar interface, with two differences: there is no 43 // support for a restartable SSL connection, and this class has a 44 // peer-to-peer mode. 45 // 46 // The SSL library requires initialization and cleanup. Static method 47 // for doing this are in SSLAdapter. They should possibly be moved out 48 // to a neutral class. 49 50 class SSLStreamAdapter : public StreamAdapterInterface { 51 public: 52 // Instantiate an SSLStreamAdapter wrapping the given stream, 53 // (using the selected implementation for the platform). 54 // Caller is responsible for freeing the returned object. 55 static SSLStreamAdapter* Create(StreamInterface* stream); 56 57 explicit SSLStreamAdapter(StreamInterface* stream) 58 : StreamAdapterInterface(stream), ignore_bad_cert_(false) { } 59 60 void set_ignore_bad_cert(bool ignore) { ignore_bad_cert_ = ignore; } 61 bool ignore_bad_cert() const { return ignore_bad_cert_; } 62 63 // Specify our SSL identity: key and certificate. Mostly this is 64 // only used in the peer-to-peer mode (unless we actually want to 65 // provide a client certificate to a server). 66 // SSLStream takes ownership of the SSLIdentity object and will 67 // free it when appropriate. Should be called no more than once on a 68 // given SSLStream instance. 69 virtual void SetIdentity(SSLIdentity* identity) = 0; 70 71 // Call this to indicate that we are to play the server's role in 72 // the peer-to-peer mode. 73 virtual void SetServerRole() = 0; 74 75 // The mode of operation is selected by calling either 76 // StartSSLWithServer or StartSSLWithPeer. 77 // Use of the stream prior to calling either of these functions will 78 // pass data in clear text. 79 // Calling one of these functions causes SSL negotiation to begin as 80 // soon as possible: right away if the underlying wrapped stream is 81 // already opened, or else as soon as it opens. 82 // 83 // These functions return a negative error code on failure. 84 // Returning 0 means success so far, but negotiation is probably not 85 // complete and will continue asynchronously. In that case, the 86 // exposed stream will open after successful negotiation and 87 // verification, or an SE_CLOSE event will be raised if negotiation 88 // fails. 89 90 // StartSSLWithServer starts SSL negotiation with a server in 91 // traditional mode. server_name specifies the expected server name 92 // which the server's certificate needs to specify. 93 virtual int StartSSLWithServer(const char* server_name) = 0; 94 95 // StartSSLWithPeer starts negotiation in the special peer-to-peer 96 // mode. 97 // Generally, SetIdentity() and possibly SetServerRole() should have 98 // been called before this. 99 // SetPeerCertificate() must also be called. It may be called after 100 // StartSSLWithPeer() but must be called before the underlying 101 // stream opens. 102 virtual int StartSSLWithPeer() = 0; 103 104 // Specify the certificate that our peer is expected to use in 105 // peer-to-peer mode. Only this certificate will be accepted during 106 // SSL verification. The certificate is assumed to have been 107 // obtained through some other secure channel (such as the XMPP 108 // channel). (This could also specify the certificate authority that 109 // will sign the peer's certificate.) 110 // SSLStream takes ownership of the SSLCertificate object and will 111 // free it when appropriate. Should be called no more than once on a 112 // given SSLStream instance. 113 virtual void SetPeerCertificate(SSLCertificate* cert) = 0; 114 115 // If true, the server certificate need not match the configured 116 // server_name, and in fact missing certificate authority and other 117 // verification errors are ignored. 118 bool ignore_bad_cert_; 119 }; 120 121 } // namespace talk_base 122 123 #endif // TALK_BASE_SSLSTREAMADAPTER_H__ 124
