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 <string>
32#include <vector>
33
34#include "talk/base/stream.h"
35#include "talk/base/sslidentity.h"
36
37namespace 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
54enum SSLRole { SSL_CLIENT, SSL_SERVER };
55enum SSLMode { SSL_MODE_TLS, SSL_MODE_DTLS };
56
57// Errors for Read -- in the high range so no conflict with OpenSSL.
58enum { SSE_MSG_TRUNC = 0xff0001 };
59
60class 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.
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;
118
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;
129
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;
140
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;
147
148  // Key Exporter interface from RFC 5705
149  // Arguments are:
150  // label               -- the exporter label.
151  //                        part of the RFC defining each exporter
152  //                        usage (IN)
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,
162                                    size_t context_len,
163                                    bool use_context,
164                                    uint8* result,
165                                    size_t result_len) {
166    return false;  // Default is unsupported
167  }
168
169
170  // DTLS-SRTP interface
171  virtual bool SetDtlsSrtpCiphers(const std::vector<std::string>& ciphers) {
172    return false;
173  }
174
175  virtual bool GetDtlsSrtpCipher(std::string* cipher) {
176    return false;
177  }
178
179  // Capabilities testing
180  static bool HaveDtls();
181  static bool HaveDtlsSrtp();
182  static bool HaveExporter();
183
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_;
188};
189
190}  // namespace talk_base
191
192#endif  // TALK_BASE_SSLSTREAMADAPTER_H_
193