3 * Copyright 2004--2008, Google Inc.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
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.
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.
28 #ifndef TALK_BASE_SSLSTREAMADAPTER_H_
29 #define TALK_BASE_SSLSTREAMADAPTER_H_
34 #include "talk/base/stream.h"
35 #include "talk/base/sslidentity.h"
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.
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
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.
54 enum SSLRole { SSL_CLIENT, SSL_SERVER };
55 enum SSLMode { SSL_MODE_TLS, SSL_MODE_DTLS };
57 // Errors for Read -- in the high range so no conflict with OpenSSL.
58 enum { SSE_MSG_TRUNC = 0xff0001 };
60 class SSLStreamAdapter : public StreamAdapterInterface {
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);
67 explicit SSLStreamAdapter(StreamInterface* stream)
68 : StreamAdapterInterface(stream), ignore_bad_cert_(false) { }
70 void set_ignore_bad_cert(bool ignore) { ignore_bad_cert_ = ignore; }
71 bool ignore_bad_cert() const { return ignore_bad_cert_; }
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;
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;
88 virtual void SetMode(SSLMode mode) = 0;
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.
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
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;
110 // StartSSLWithPeer starts negotiation in the special peer-to-peer
112 // Generally, SetIdentity() and possibly SetServerRole() should have
113 // been called before this.
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.
117 virtual int StartSSLWithPeer() = 0;
119 // Specify 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). (This could also specify the certificate authority that
124 // will sign the peer's certificate.)
125 // SSLStream takes ownership of the SSLCertificate object and will
126 // free it when appropriate. Should be called no more than once on a
127 // given SSLStream instance.
128 virtual void SetPeerCertificate(SSLCertificate* cert) = 0;
130 // Specify the digest of the certificate that our peer is expected to use in
131 // peer-to-peer mode. Only this certificate will be accepted during
132 // SSL verification. The certificate is assumed to have been
133 // obtained through some other secure channel (such as the XMPP
134 // channel). Unlike SetPeerCertificate(), this must specify the
135 // terminal certificate, not just a CA.
136 // SSLStream makes a copy of the digest value.
137 virtual bool SetPeerCertificateDigest(const std::string& digest_alg,
138 const unsigned char* digest_val,
139 size_t digest_len) = 0;
141 // Retrieves the peer's X.509 certificate, if a certificate has been
142 // provided by SetPeerCertificate or a connection has been established. If
143 // a connection has been established, this returns the
144 // certificate transmitted over SSL, including the entire chain.
145 // The returned certificate is owned by the caller.
146 virtual bool GetPeerCertificate(SSLCertificate** cert) const = 0;
148 // Key Exporter interface from RFC 5705
150 // label -- the exporter label.
151 // part of the RFC defining each exporter
153 // context/context_len -- a context to bind to for this connection;
154 // optional, can be NULL, 0 (IN)
155 // use_context -- whether to use the context value
156 // (needed to distinguish no context from
157 // zero-length ones).
158 // result -- where to put the computed value
159 // result_len -- the length of the computed value
160 virtual bool ExportKeyingMaterial(const std::string& label,
161 const uint8* context,
166 return false; // Default is unsupported
170 // DTLS-SRTP interface
171 virtual bool SetDtlsSrtpCiphers(const std::vector<std::string>& ciphers) {
175 virtual bool GetDtlsSrtpCipher(std::string* cipher) {
179 // Capabilities testing
180 static bool HaveDtls();
181 static bool HaveDtlsSrtp();
182 static bool HaveExporter();
184 // If true, the server certificate need not match the configured
185 // server_name, and in fact missing certificate authority and other
186 // verification errors are ignored.
187 bool ignore_bad_cert_;
190 } // namespace talk_base
192 #endif // TALK_BASE_SSLSTREAMADAPTER_H_