2 * Copyright 2014 Facebook, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 #include <arpa/inet.h>
21 #include <openssl/ssl.h>
23 #include <folly/Optional.h>
24 #include <folly/String.h>
25 #include <folly/io/async/AsyncSocket.h>
26 #include <folly/io/async/SSLContext.h>
27 #include <folly/io/async/AsyncTimeout.h>
28 #include <folly/io/async/TimeoutManager.h>
30 #include <folly/Bits.h>
31 #include <folly/io/IOBuf.h>
32 #include <folly/io/Cursor.h>
34 using folly::io::Cursor;
35 using std::unique_ptr;
39 class SSLException: public folly::AsyncSocketException {
41 SSLException(int sslError, int errno_copy);
43 int getSSLError() const { return error_; }
51 * A class for performing asynchronous I/O on an SSL connection.
53 * AsyncSSLSocket allows users to asynchronously wait for data on an
54 * SSL connection, and to asynchronously send data.
56 * The APIs for reading and writing are intentionally asymmetric.
57 * Waiting for data to read is a persistent API: a callback is
58 * installed, and is notified whenever new data is available. It
59 * continues to be notified of new events until it is uninstalled.
61 * AsyncSSLSocket does not provide read timeout functionality,
62 * because it typically cannot determine when the timeout should be
63 * active. Generally, a timeout should only be enabled when
64 * processing is blocked waiting on data from the remote endpoint.
65 * For server connections, the timeout should not be active if the
66 * server is currently processing one or more outstanding requests for
67 * this connection. For client connections, the timeout should not be
68 * active if there are no requests pending on the connection.
69 * Additionally, if a client has multiple pending requests, it will
70 * ususally want a separate timeout for each request, rather than a
71 * single read timeout.
73 * The write API is fairly intuitive: a user can request to send a
74 * block of data, and a callback will be informed once the entire
75 * block has been transferred to the kernel, or on error.
76 * AsyncSSLSocket does provide a send timeout, since most callers
77 * want to give up if the remote end stops responding and no further
78 * progress can be made sending the data.
80 class AsyncSSLSocket : public virtual AsyncSocket {
82 typedef std::unique_ptr<AsyncSSLSocket, Destructor> UniquePtr;
86 virtual ~HandshakeCB() {}
89 * handshakeVer() is invoked during handshaking to give the
90 * application chance to validate it's peer's certificate.
92 * Note that OpenSSL performs only rudimentary internal
93 * consistency verification checks by itself. Any other validation
94 * like whether or not the certificate was issued by a trusted CA.
95 * The default implementation of this callback mimics what what
96 * OpenSSL does internally if SSL_VERIFY_PEER is set with no
97 * verification callback.
99 * See the passages on verify_callback in SSL_CTX_set_verify(3)
102 virtual bool handshakeVer(AsyncSSLSocket* sock,
104 X509_STORE_CTX* ctx) noexcept {
109 * handshakeSuc() is called when a new SSL connection is
110 * established, i.e., after SSL_accept/connect() returns successfully.
112 * The HandshakeCB will be uninstalled before handshakeSuc()
115 * @param sock SSL socket on which the handshake was initiated
117 virtual void handshakeSuc(AsyncSSLSocket *sock) noexcept = 0;
120 * handshakeErr() is called if an error occurs while
121 * establishing the SSL connection.
123 * The HandshakeCB will be uninstalled before handshakeErr()
126 * @param sock SSL socket on which the handshake was initiated
127 * @param ex An exception representing the error.
129 virtual void handshakeErr(
130 AsyncSSLSocket *sock,
131 const AsyncSocketException& ex)
135 class HandshakeTimeout : public AsyncTimeout {
137 HandshakeTimeout(AsyncSSLSocket* sslSocket, EventBase* eventBase)
138 : AsyncTimeout(eventBase)
139 , sslSocket_(sslSocket) {}
141 virtual void timeoutExpired() noexcept {
142 sslSocket_->timeoutExpired();
146 AsyncSSLSocket* sslSocket_;
151 * These are passed to the application via errno, packed in an SSL err which
152 * are outside the valid errno range. The values are chosen to be unique
153 * against values in ssl.h
156 SSL_CLIENT_RENEGOTIATION_ATTEMPT = 900,
157 SSL_INVALID_RENEGOTIATION = 901,
158 SSL_EARLY_WRITE = 902
162 * Create a client AsyncSSLSocket
164 AsyncSSLSocket(const std::shared_ptr<folly::SSLContext> &ctx,
168 * Create a server/client AsyncSSLSocket from an already connected
169 * socket file descriptor.
171 * Note that while AsyncSSLSocket enables TCP_NODELAY for sockets it creates
172 * when connecting, it does not change the socket options when given an
173 * existing file descriptor. If callers want TCP_NODELAY enabled when using
174 * this version of the constructor, they need to explicitly call
175 * setNoDelay(true) after the constructor returns.
177 * @param ctx SSL context for this connection.
178 * @param evb EventBase that will manage this socket.
179 * @param fd File descriptor to take over (should be a connected socket).
180 * @param server Is socket in server mode?
182 AsyncSSLSocket(const std::shared_ptr<folly::SSLContext>& ctx,
183 EventBase* evb, int fd, bool server = true);
187 * Helper function to create a server/client shared_ptr<AsyncSSLSocket>.
189 static std::shared_ptr<AsyncSSLSocket> newSocket(
190 const std::shared_ptr<folly::SSLContext>& ctx,
191 EventBase* evb, int fd, bool server=true) {
192 return std::shared_ptr<AsyncSSLSocket>(
193 new AsyncSSLSocket(ctx, evb, fd, server),
198 * Helper function to create a client shared_ptr<AsyncSSLSocket>.
200 static std::shared_ptr<AsyncSSLSocket> newSocket(
201 const std::shared_ptr<folly::SSLContext>& ctx,
203 return std::shared_ptr<AsyncSSLSocket>(
204 new AsyncSSLSocket(ctx, evb),
209 #if OPENSSL_VERSION_NUMBER >= 0x1000105fL && !defined(OPENSSL_NO_TLSEXT)
211 * Create a client AsyncSSLSocket with tlsext_servername in
212 * the Client Hello message.
214 AsyncSSLSocket(const std::shared_ptr<folly::SSLContext> &ctx,
216 const std::string& serverName);
219 * Create a client AsyncSSLSocket from an already connected
220 * socket file descriptor.
222 * Note that while AsyncSSLSocket enables TCP_NODELAY for sockets it creates
223 * when connecting, it does not change the socket options when given an
224 * existing file descriptor. If callers want TCP_NODELAY enabled when using
225 * this version of the constructor, they need to explicitly call
226 * setNoDelay(true) after the constructor returns.
228 * @param ctx SSL context for this connection.
229 * @param evb EventBase that will manage this socket.
230 * @param fd File descriptor to take over (should be a connected socket).
231 * @param serverName tlsext_hostname that will be sent in ClientHello.
233 AsyncSSLSocket(const std::shared_ptr<folly::SSLContext>& ctx,
236 const std::string& serverName);
238 static std::shared_ptr<AsyncSSLSocket> newSocket(
239 const std::shared_ptr<folly::SSLContext>& ctx,
241 const std::string& serverName) {
242 return std::shared_ptr<AsyncSSLSocket>(
243 new AsyncSSLSocket(ctx, evb, serverName),
249 * TODO: implement support for SSL renegotiation.
251 * This involves proper handling of the SSL_ERROR_WANT_READ/WRITE
252 * code as a result of SSL_write/read(), instead of returning an
253 * error. In that case, the READ/WRITE event should be registered,
254 * and a flag (e.g., writeBlockedOnRead) should be set to indiciate
255 * the condition. In the next invocation of read/write callback, if
256 * the flag is on, performWrite()/performRead() should be called in
257 * addition to the normal call to performRead()/performWrite(), and
258 * the flag should be reset.
261 // Inherit TAsyncTransport methods from AsyncSocket except the
263 // See the documentation in TAsyncTransport.h
264 // TODO: implement graceful shutdown in close()
265 // TODO: implement detachSSL() that returns the SSL connection
266 virtual void closeNow() override;
267 virtual void shutdownWrite() override;
268 virtual void shutdownWriteNow() override;
269 virtual bool good() const override;
270 virtual bool connecting() const override;
272 bool isEorTrackingEnabled() const override;
273 virtual void setEorTracking(bool track) override;
274 virtual size_t getRawBytesWritten() const override;
275 virtual size_t getRawBytesReceived() const override;
276 void enableClientHelloParsing();
279 * Accept an SSL connection on the socket.
281 * The callback will be invoked and uninstalled when an SSL
282 * connection has been established on the underlying socket.
283 * The value of verifyPeer determines the client verification method.
284 * By default, its set to use the value in the underlying context
286 * @param callback callback object to invoke on success/failure
287 * @param timeout timeout for this function in milliseconds, or 0 for no
289 * @param verifyPeer SSLVerifyPeerEnum uses the options specified in the
290 * context by default, can be set explcitly to override the
291 * method in the context
293 virtual void sslAccept(HandshakeCB* callback, uint32_t timeout = 0,
294 const folly::SSLContext::SSLVerifyPeerEnum& verifyPeer =
295 folly::SSLContext::SSLVerifyPeerEnum::USE_CTX);
298 * Invoke SSL accept following an asynchronous session cache lookup
300 void restartSSLAccept();
303 * Connect to the given address, invoking callback when complete or on error
305 * Note timeout applies to TCP + SSL connection time
307 void connect(ConnectCallback* callback,
308 const folly::SocketAddress& address,
310 const OptionMap &options = emptyOptionMap,
311 const folly::SocketAddress& bindAddr = anyAddress)
314 using AsyncSocket::connect;
317 * Initiate an SSL connection on the socket
318 * THe callback will be invoked and uninstalled when an SSL connection
319 * has been establshed on the underlying socket.
320 * The verification option verifyPeer is applied if its passed explicitly.
321 * If its not, the options in SSLContext set on the underying SSLContext
324 * @param callback callback object to invoke on success/failure
325 * @param timeout timeout for this function in milliseconds, or 0 for no
327 * @param verifyPeer SSLVerifyPeerEnum uses the options specified in the
328 * context by default, can be set explcitly to override the
329 * method in the context. If verification is turned on sets
330 * SSL_VERIFY_PEER and invokes
331 * HandshakeCB::handshakeVer().
333 virtual void sslConn(HandshakeCB *callback, uint64_t timeout = 0,
334 const folly::SSLContext::SSLVerifyPeerEnum& verifyPeer =
335 folly::SSLContext::SSLVerifyPeerEnum::USE_CTX);
341 STATE_RSA_ASYNC_PENDING,
344 STATE_REMOTE_CLOSED, /// remote end closed; we can still write
345 STATE_CLOSING, ///< close() called, but waiting on writes to complete
346 /// close() called with pending writes, before connect() has completed
347 STATE_CONNECTING_CLOSING,
352 SSLStateEnum getSSLState() const { return sslState_;}
355 * Get a handle to the negotiated SSL session. This increments the session
356 * refcount and must be deallocated by the caller.
358 SSL_SESSION *getSSLSession();
361 * Set the SSL session to be used during sslConn. AsyncSSLSocket will
362 * hold a reference to the session until it is destroyed or released by the
363 * underlying SSL structure.
365 * @param takeOwnership if true, AsyncSSLSocket will assume the caller's
366 * reference count to session.
368 void setSSLSession(SSL_SESSION *session, bool takeOwnership = false);
371 * Get the name of the protocol selected by the client during
372 * Next Protocol Negotiation (NPN)
374 * Throw an exception if openssl does not support NPN
376 * @param protoName Name of the protocol (not guaranteed to be
377 * null terminated); will be set to nullptr if
378 * the client did not negotiate a protocol.
379 * Note: the AsyncSSLSocket retains ownership
381 * @param protoNameLen Length of the name.
383 virtual void getSelectedNextProtocol(const unsigned char** protoName,
384 unsigned* protoLen) const;
387 * Get the name of the protocol selected by the client during
388 * Next Protocol Negotiation (NPN)
390 * @param protoName Name of the protocol (not guaranteed to be
391 * null terminated); will be set to nullptr if
392 * the client did not negotiate a protocol.
393 * Note: the AsyncSSLSocket retains ownership
395 * @param protoNameLen Length of the name.
396 * @return false if openssl does not support NPN
398 virtual bool getSelectedNextProtocolNoThrow(const unsigned char** protoName,
399 unsigned* protoLen) const;
402 * Determine if the session specified during setSSLSession was reused
403 * or if the server rejected it and issued a new session.
405 bool getSSLSessionReused() const;
408 * true if the session was resumed using session ID
410 bool sessionIDResumed() const { return sessionIDResumed_; }
412 void setSessionIDResumed(bool resumed) {
413 sessionIDResumed_ = resumed;
417 * Get the negociated cipher name for this SSL connection.
418 * Returns the cipher used or the constant value "NONE" when no SSL session
419 * has been established.
421 const char *getNegotiatedCipherName() const;
424 * Get the server name for this SSL connection.
425 * Returns the server name used or the constant value "NONE" when no SSL
426 * session has been established.
427 * If openssl has no SNI support, throw TTransportException.
429 const char *getSSLServerName() const;
432 * Get the server name for this SSL connection.
433 * Returns the server name used or the constant value "NONE" when no SSL
434 * session has been established.
435 * If openssl has no SNI support, return "NONE"
437 const char *getSSLServerNameNoThrow() const;
440 * Get the SSL version for this connection.
441 * Possible return values are SSL2_VERSION, SSL3_VERSION, TLS1_VERSION,
442 * with hexa representations 0x200, 0x300, 0x301,
443 * or 0 if no SSL session has been established.
445 int getSSLVersion() const;
448 * Get the certificate size used for this SSL connection.
450 int getSSLCertSize() const;
452 /* Get the number of bytes read from the wire (including protocol
453 * overhead). Returns 0 once the connection has been closed.
455 unsigned long getBytesRead() const {
456 if (ssl_ != nullptr) {
457 return BIO_number_read(SSL_get_rbio(ssl_));
462 /* Get the number of bytes written to the wire (including protocol
463 * overhead). Returns 0 once the connection has been closed.
465 unsigned long getBytesWritten() const {
466 if (ssl_ != nullptr) {
467 return BIO_number_written(SSL_get_wbio(ssl_));
472 virtual void attachEventBase(EventBase* eventBase) override {
473 AsyncSocket::attachEventBase(eventBase);
474 handshakeTimeout_.attachEventBase(eventBase);
477 virtual void detachEventBase() override {
478 AsyncSocket::detachEventBase();
479 handshakeTimeout_.detachEventBase();
482 virtual void attachTimeoutManager(TimeoutManager* manager) {
483 handshakeTimeout_.attachTimeoutManager(manager);
486 virtual void detachTimeoutManager() {
487 handshakeTimeout_.detachTimeoutManager();
490 #if OPENSSL_VERSION_NUMBER >= 0x009080bfL
492 * This function will set the SSL context for this socket to the
493 * argument. This should only be used on client SSL Sockets that have
494 * already called detachSSLContext();
496 void attachSSLContext(const std::shared_ptr<folly::SSLContext>& ctx);
499 * Detaches the SSL context for this socket.
501 void detachSSLContext();
504 #if OPENSSL_VERSION_NUMBER >= 0x1000105fL && !defined(OPENSSL_NO_TLSEXT)
506 * Switch the SSLContext to continue the SSL handshake.
507 * It can only be used in server mode.
509 void switchServerSSLContext(
510 const std::shared_ptr<folly::SSLContext>& handshakeCtx);
513 * Did server recognize/support the tlsext_hostname in Client Hello?
514 * It can only be used in client mode.
516 * @return true - tlsext_hostname is matched by the server
517 * false - tlsext_hostname is not matched or
518 * is not supported by server
520 bool isServerNameMatch() const;
523 * Set the SNI hostname that we'll advertise to the server in the
524 * ClientHello message.
526 void setServerName(std::string serverName) noexcept;
529 void timeoutExpired() noexcept;
532 * Get the list of supported ciphers sent by the client in the client's
535 void getSSLClientCiphers(std::string& clientCiphers) {
536 std::stringstream ciphersStream;
537 std::string cipherName;
539 if (parseClientHello_ == false
540 || clientHelloInfo_->clientHelloCipherSuites_.empty()) {
545 for (auto originalCipherCode : clientHelloInfo_->clientHelloCipherSuites_)
547 // OpenSSL expects code as a big endian char array
548 auto cipherCode = htons(originalCipherCode);
550 #if defined(SSL_OP_NO_TLSv1_2)
551 const SSL_CIPHER* cipher =
552 TLSv1_2_method()->get_cipher_by_char((unsigned char*)&cipherCode);
553 #elif defined(SSL_OP_NO_TLSv1_1)
554 const SSL_CIPHER* cipher =
555 TLSv1_1_method()->get_cipher_by_char((unsigned char*)&cipherCode);
556 #elif defined(SSL_OP_NO_TLSv1)
557 const SSL_CIPHER* cipher =
558 TLSv1_method()->get_cipher_by_char((unsigned char*)&cipherCode);
560 const SSL_CIPHER* cipher =
561 SSLv3_method()->get_cipher_by_char((unsigned char*)&cipherCode);
564 if (cipher == nullptr) {
565 ciphersStream << std::setfill('0') << std::setw(4) << std::hex
566 << originalCipherCode << ":";
568 ciphersStream << SSL_CIPHER_get_name(cipher) << ":";
572 clientCiphers = ciphersStream.str();
573 clientCiphers.erase(clientCiphers.end() - 1);
577 * Get the list of compression methods sent by the client in TLS Hello.
579 std::string getSSLClientComprMethods() {
580 if (!parseClientHello_) {
583 return folly::join(":", clientHelloInfo_->clientHelloCompressionMethods_);
587 * Get the list of TLS extensions sent by the client in the TLS Hello.
589 std::string getSSLClientExts() {
590 if (!parseClientHello_) {
593 return folly::join(":", clientHelloInfo_->clientHelloExtensions_);
597 * Get the list of shared ciphers between the server and the client.
598 * Works well for only SSLv2, not so good for SSLv3 or TLSv1.
600 void getSSLSharedCiphers(std::string& sharedCiphers) {
601 char ciphersBuffer[1024];
602 ciphersBuffer[0] = '\0';
603 SSL_get_shared_ciphers(ssl_, ciphersBuffer, sizeof(ciphersBuffer) - 1);
604 sharedCiphers = ciphersBuffer;
608 * Get the list of ciphers supported by the server in the server's
611 void getSSLServerCiphers(std::string& serverCiphers) {
612 serverCiphers = SSL_get_cipher_list(ssl_, 0);
615 while ((cipher = SSL_get_cipher_list(ssl_, i)) != nullptr) {
616 serverCiphers.append(":");
617 serverCiphers.append(cipher);
622 static int getSSLExDataIndex();
623 static AsyncSSLSocket* getFromSSL(const SSL *ssl);
624 static int eorAwareBioWrite(BIO *b, const char *in, int inl);
625 void resetClientHelloParsing(SSL *ssl);
626 static void clientHelloParsingCallback(int write_p, int version,
627 int content_type, const void *buf, size_t len, SSL *ssl, void *arg);
629 struct ClientHelloInfo {
630 folly::IOBufQueue clientHelloBuf_;
631 uint8_t clientHelloMajorVersion_;
632 uint8_t clientHelloMinorVersion_;
633 std::vector<uint16_t> clientHelloCipherSuites_;
634 std::vector<uint8_t> clientHelloCompressionMethods_;
635 std::vector<uint16_t> clientHelloExtensions_;
639 ClientHelloInfo* getClientHelloInfo() {
640 return clientHelloInfo_.get();
646 * Protected destructor.
648 * Users of AsyncSSLSocket must never delete it directly. Instead, invoke
649 * destroy() instead. (See the documentation in TDelayedDestruction.h for
654 // Inherit event notification methods from AsyncSocket except
657 void handleRead() noexcept override;
658 void handleWrite() noexcept override;
659 void handleAccept() noexcept;
660 void handleConnect() noexcept override;
662 void invalidState(HandshakeCB* callback);
663 bool willBlock(int ret, int *errorOut) noexcept;
665 virtual void checkForImmediateRead() noexcept override;
666 // AsyncSocket calls this at the wrong time for SSL
667 void handleInitialReadWrite() noexcept override {}
669 ssize_t performRead(void* buf, size_t buflen) override;
670 ssize_t performWrite(const iovec* vec, uint32_t count, WriteFlags flags,
671 uint32_t* countWritten, uint32_t* partialWritten)
674 // This virtual wrapper around SSL_write exists solely for testing/mockability
675 virtual int sslWriteImpl(SSL *ssl, const void *buf, int n) {
676 return SSL_write(ssl, buf, n);
680 * Apply verification options passed to sslConn/sslAccept or those set
681 * in the underlying SSLContext object.
683 * @param ssl pointer to the SSL object on which verification options will be
684 * applied. If verifyPeer_ was explicitly set either via sslConn/sslAccept,
685 * those options override the settings in the underlying SSLContext.
687 void applyVerificationOptions(SSL * ssl);
690 * A SSL_write wrapper that understand EOR
692 * @param ssl: SSL* object
693 * @param buf: Buffer to be written
694 * @param n: Number of bytes to be written
695 * @param eor: Does the last byte (buf[n-1]) have the app-last-byte?
696 * @return: The number of app bytes successfully written to the socket
698 int eorAwareSSLWrite(SSL *ssl, const void *buf, int n, bool eor);
700 // Inherit error handling methods from AsyncSocket, plus the following.
701 void failHandshake(const char* fn, const AsyncSocketException& ex);
703 void invokeHandshakeCB();
705 static void sslInfoCallback(const SSL *ssl, int type, int val);
707 static std::mutex mutex_;
708 static int sslExDataIndex_;
709 // Whether we've applied the TCP_CORK option to the socket
711 // SSL related members.
713 // Used to prevent client-initiated renegotiation. Note that AsyncSSLSocket
714 // doesn't fully support renegotiation, so we could just fail all attempts
715 // to enforce this. Once it is supported, we should make it an option
716 // to disable client-initiated renegotiation.
717 bool handshakeComplete_{false};
718 bool renegotiateAttempted_{false};
719 SSLStateEnum sslState_{STATE_UNINIT};
720 std::shared_ptr<folly::SSLContext> ctx_;
721 // Callback for SSL_accept() or SSL_connect()
722 HandshakeCB* handshakeCallback_{nullptr};
724 SSL_SESSION *sslSession_{nullptr};
725 HandshakeTimeout handshakeTimeout_;
726 // whether the SSL session was resumed using session ID or not
727 bool sessionIDResumed_{false};
729 // The app byte num that we are tracking for the MSG_EOR
730 // Only one app EOR byte can be tracked.
731 size_t appEorByteNo_{0};
733 // When openssl is about to sendmsg() across the minEorRawBytesNo_,
734 // it will pass MSG_EOR to sendmsg().
735 size_t minEorRawByteNo_{0};
736 #if OPENSSL_VERSION_NUMBER >= 0x1000105fL && !defined(OPENSSL_NO_TLSEXT)
737 std::shared_ptr<folly::SSLContext> handshakeCtx_;
738 std::string tlsextHostname_;
740 folly::SSLContext::SSLVerifyPeerEnum
741 verifyPeer_{folly::SSLContext::SSLVerifyPeerEnum::USE_CTX};
743 // Callback for SSL_CTX_set_verify()
744 static int sslVerifyCallback(int preverifyOk, X509_STORE_CTX* ctx);
746 bool parseClientHello_{false};
747 unique_ptr<ClientHelloInfo> clientHelloInfo_;