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() must also be called. It may be called after
115
// StartSSLWithPeer() but must be called before the underlying
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
// Key Exporter interface from RFC 5705
143
// label -- the exporter label.
144
// part of the RFC defining each exporter
146
// context/context_len -- a context to bind to for this connection;
147
// optional, can be NULL, 0 (IN)
148
// use_context -- whether to use the context value
149
// (needed to distinguish no context from
150
// zero-length ones).
151
// result -- where to put the computed value
152
// result_len -- the length of the computed value
153
virtual bool ExportKeyingMaterial(const std::string& label,
154
const uint8* context,
159
return false; // Default is unsupported
163
// DTLS-SRTP interface
164
virtual bool SetDtlsSrtpCiphers(const std::vector<std::string>& ciphers) {
168
virtual bool GetDtlsSrtpCipher(std::string* cipher) {
172
// Capabilities testing
173
static bool HaveDtls();
174
static bool HaveDtlsSrtp();
175
static bool HaveExporter();
177
// If true, the server certificate need not match the configured
178
// server_name, and in fact missing certificate authority and other
179
// verification errors are ignored.
180
bool ignore_bad_cert_;
183
} // namespace talk_base
185
#endif // TALK_BASE_SSLSTREAMADAPTER_H__