ACE/ace/SSL/SSL_SOCK_Stream.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    SSL_SOCK_Stream.h
   6  *
   7  *  @author Ossama Othman <ossama@uci.edu>
   8  *  @author Carlos O'Ryan <coryan@uci.edu>
   9  *  @author John Heitmann
  10  */
  11 //=============================================================================
  12
  13
  14 #ifndef ACE_SSL_SOCK_STREAM_H
  15 #define ACE_SSL_SOCK_STREAM_H
  16
  17 #include /**/ "ace/pre.h"
  18
  19 #include "SSL_Export.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 // This must be included before any <openssl> include on LynxOS
  26 #include "ace/os_include/os_stdio.h"
  27
  28 #include <openssl/err.h>
  29
  30 #include "SSL_SOCK.h"
  31 #include "SSL_Context.h"
  32
  33 #include "ace/SOCK_Stream.h"
  34
  35 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  36
  37 /**
  38  * @class ACE_SSL_SOCK_Stream
  39  *
  40  * @brief Defines methods in the ACE_SSL_SOCK_Stream abstraction.
  41  *
  42  * This class encapsulates the methods and functionality necessary to
  43  * send and receive data over TLS/SSL.
  44  * @par
  45  * Since SSL is record-oriented, some additional steps must be taken
  46  * to make the ACE_SSL_SOCK_Stream interact properly with the
  47  * Reactor (if one is used) when performing non-blocking IO.  In
  48  * particular, if ::SSL_pending (ssl), where "ssl" is a pointer to the
  49  * SSL data structure returned from ACE_SSL_SOCK_Stream::ssl(),
  50  * returns a non-zero value then the event handler that calls the IO
  51  * methods in this class should return a value greater than zero to
  52  * force the Reactor to invoke the event handler before polling for
  53  * additional events (e.g. blocking on select()).
  54  *
  55  * @note The user must currently ensure that only one thread services
  56  *       a given SSL session at any given time since underlying SSL
  57  *       implementations, such as OpenSSL, are not entirely
  58  *       thread-safe or reentrant.
  59  */
  60 class ACE_SSL_Export ACE_SSL_SOCK_Stream : public ACE_SSL_SOCK
  61 {
  62 public:
  63   /// Constructor
  64   /**
  65    * @param context Pointer to @c ACE_SSL_Context instance containing
  66    *                the OpenSSL @c SSL data structure to be associated
  67    *                with this @c ACE_SSL_SOCK_Stream.  The @c SSL data
  68    *                structure will be copied to make it at least
  69    *                logically independent of the supplied @a context.
  70    */
  71   ACE_SSL_SOCK_Stream (ACE_SSL_Context *context =
  72                        ACE_SSL_Context::instance ());
  73
  74   /// Destructor
  75   ~ACE_SSL_SOCK_Stream ();
  76
  77   /// Send an @a n byte buffer to the ssl socket using the semantics of
  78   /// send(3n).
  79   /**
  80    * ACE_SSL supports no flags for sending at this time.
  81    */
  82   ssize_t send (const void *buf,
  83                 size_t n,
  84                 int flags) const;
  85
  86   /// Recv an @a n byte buffer from the ssl socket using the semantics of
  87   /// recv(3n).
  88   /**
  89    * ACE_SSL supports MSG_PEEK, but no other flags at this time.
  90    */
  91   ssize_t recv (void *buf,
  92                 size_t n,
  93                 int flags) const;
  94
  95   /// Send an @a n byte buffer to the ssl socket using the semantics of
  96   /// write(2).
  97   ssize_t send (const void *buf,
  98                 size_t n) const;
  99
 100   /// Recv an @a n byte buffer from the ssl socket using the semantics of
 101   /// read(2).
 102   ssize_t recv (void *buf,
 103                 size_t n) const;
 104
 105   /// Send an iovec of size @a n to the ssl socket.
 106   /**
 107    * Note that it is not possible to perform a "scattered" write with
 108    * the underlying OpenSSL implementation.  As such, the expected
 109    * semantics are not fully reproduced with this implementation.
 110    */
 111   ssize_t sendv (const iovec iov[],
 112                  size_t n,
 113                  const ACE_Time_Value *timeout = 0) const;
 114
 115   /**
 116    * Allows a client to read from a socket without having to provide a
 117    * buffer to read.  This method determines how much data is in the
 118    * socket, allocates a buffer of this size, reads in the data, and
 119    * returns the number of bytes read.  The caller is responsible for
 120    * deleting the member in the iov_base field of io_vec using
 121    * delete [] io_vec->iov_base.
 122    */
 123   ssize_t recvv (iovec *io_vec,
 124                  const ACE_Time_Value *timeout = 0) const;
 125
 126   /**
 127    * Wait to timeout amount of time to send up to n bytes into buf
 128    * (uses the send() call).  If send() times out -1 is returned with
 129    * errno == ETIME.  If it succeeds the number of bytes sent is
 130    * returned. No flags are supported.
 131    */
 132   ssize_t send (const void *buf,
 133                 size_t n,
 134                 int flags,
 135                 const ACE_Time_Value *timeout) const;
 136
 137   /**
 138    * Wait up to timeout amount of time to receive up to @a n bytes into
 139    * @a buf (uses the recv() call).  If recv() times out -1 is returned
 140    * with errno == ETIME.  If it succeeds the number of bytes received
 141    * is returned.  MSG_PEEK is the only supported flag.
 142    */
 143   ssize_t recv (void *buf,
 144                 size_t n,
 145                 int flags,
 146                 const ACE_Time_Value *timeout) const;
 147
 148   /**
 149    * Wait to to timeout amount of time to send up to @a n bytes into
 150    * @a buf (uses the send() call).  If send() times out
 151    * a -1 is returned with errno == ETIME.  If it succeeds the
 152    * number of bytes sent is returned.
 153    */
 154   ssize_t send (const void *buf,
 155                 size_t n,
 156                 const ACE_Time_Value *timeout) const;
 157
 158   /**
 159    * Wait up to timeout amount of time to receive up to @a n bytes
 160    * into @a buf (uses the recv() call).  If recv() times
 161    * out a -1 is returned with @c errno == ETIME.  If it succeeds the
 162    * number of bytes received is returned.
 163    */
 164   ssize_t recv (void *buf,
 165                 size_t n,
 166                 const ACE_Time_Value *timeout) const;
 167
 168   /// Send @a n varargs messages to the connected ssl socket.
 169   ssize_t send (size_t n,
 170                 ...) const;
 171
 172   /// Recv @a n varargs messages to the connected ssl socket.
 173   ssize_t recv (size_t n,
 174                 ...) const;
 175
 176   /// Send @a n bytes, keep trying until n are sent.
 177   ssize_t send_n (const void *buf, int n) const;
 178
 179   /// Recv @a n bytes, keep trying until @a n are received.
 180   ssize_t recv_n (void *buf, int n) const;
 181
 182   /**
 183    * @note In the following four methods, only MSG_PEEK is supported
 184    * for recv_n(), and no flags are supported for send_n().
 185    */
 186   //@{
 187   /// Send @a n bytes, keep trying until @a n are sent.
 188   ssize_t send_n (const void *buf, int n, int flags) const;
 189
 190   /// Recv @a n bytes, keep trying until @a n are sent.
 191   ssize_t recv_n (void *buf, int n, int flags) const;
 192
 193   /**
 194    * Try to send exactly @a len bytes into @a buf (uses the send() call).
 195    * If send() blocks for longer than timeout the number of bytes
 196    * actually sent is returned with errno == ETIME.  If a timeout does
 197    * not occur, send_n() return len (i.e., the number of bytes
 198    * requested to be sent).
 199    */
 200   ssize_t send_n (const void *buf,
 201                   size_t len,
 202                   int flags,
 203                   const ACE_Time_Value *timeout,
 204                   size_t *bytes_transferred = 0) const;
 205
 206   /**
 207    * Try to send exactly @a len bytes into @a buf (uses the send() call).
 208    * If send() blocks for longer than timeout the number of bytes
 209    * actually sent is returned with errno == ETIME.  If a timeout does
 210    * not occur, send_n() return len (i.e., the number of bytes
 211    * requested to be sent).
 212    */
 213   ssize_t send_n (const void *buf,
 214                   size_t len,
 215                   const ACE_Time_Value *timeout,
 216                   size_t *bytes_transferred = 0) const;
 217
 218   /**
 219    * Try to receive exactly @a len bytes into @a buf (uses the recv() call).
 220    * The ACE_Time_Value indicates how long to blocking trying to
 221    * receive.  If timeout == 0, the caller will block until action is
 222    * possible, else will wait until the relative time specified in
 223    * timeout elapses).  If recv() blocks for longer than timeout the
 224    * number of bytes actually read is returned with errno == ETIME.
 225    * If a timeout does not occur, recv_n return len (i.e., the number
 226    * of bytes requested to be read).
 227    */
 228   ssize_t recv_n (void *buf,
 229                   size_t len,
 230                   int flags,
 231                   const ACE_Time_Value *timeout,
 232                   size_t *bytes_transferred = 0) const;
 233
 234   /**
 235    * Try to receive exactly len bytes into buf (uses the recv() call).
 236    * The ACE_Time_Value indicates how long to blocking trying to
 237    * receive.  If timeout == 0, the caller will block until action is
 238    * possible, else will wait until the relative time specified in
 239    * timeout elapses).  If recv() blocks for longer than timeout the
 240    * number of bytes actually read is returned with errno == ETIME.
 241    * If a timeout does not occur, recv_n return len (i.e., the number
 242    * of bytes requested to be read).
 243    */
 244   ssize_t recv_n (void *buf,
 245                   size_t len,
 246                   const ACE_Time_Value *timeout,
 247                   size_t *bytes_transferred = 0) const;
 248   //@}
 249
 250   /**
 251    * Send an iovec of size n to the connected socket.  Will block
 252    * until all bytes are sent or an error occurs.
 253    */
 254   ssize_t sendv_n (const iovec iov[],
 255                    size_t n) const;
 256
 257   /// Receive an iovec of size n to the connected socket.
 258   ssize_t recvv_n (iovec iov[],
 259                    size_t n) const;
 260
 261   /**
 262    * Selectively close endpoints.
 263    */
 264   //@{
 265   /// Close down the reader.
 266   int close_reader ();
 267
 268   /// Close down the writer.
 269   int close_writer ();
 270   //@}
 271
 272   ///Close down the socket.
 273   int close ();
 274
 275   /// Meta-type info
 276   typedef ACE_INET_Addr PEER_ADDR;
 277
 278   /// Declare the dynamic allocation hooks.
 279   ACE_ALLOC_HOOK_DECLARE;
 280
 281   /// Overridden set_handle() method.
 282   /**
 283    * Only an ACE_SSL_SOCK_Acceptor or ACE_SSL_SOCK_Connector should
 284    * access this method since some state in the underlying "ssl_" data
 285    * structure is set during SSL connection establishment.
 286    */
 287   void set_handle (ACE_HANDLE fd);
 288
 289   /// Return a pointer to the underlying SSL structure.
 290   SSL *ssl () const;
 291
 292   /**
 293    * Return the address of the remotely connected peer (if there is
 294    * one), in the referenced ACE_Addr. Returns 0 if successful, else
 295    * -1.
 296    *
 297    * @note If the TCP connection has been completed but the SSL
 298    *       connection has not been completed yet, -1 will be
 299    *       returned.
 300    */
 301   int get_remote_addr (ACE_Addr &) const;
 302
 303   /// Return the underlying ACE_SOCK_Stream which ACE_SSL runs atop of.
 304   ACE_SOCK_Stream & peer ();
 305
 306 protected:
 307   /// Underlying send() helper method common to all public send()
 308   /// methods.
 309   ssize_t send_i (const void *buf,
 310                   size_t n,
 311                   int flags) const;
 312
 313   /// Underlying send() helper method common to all public send()
 314   /// methods.
 315   ssize_t recv_i (void *buf,
 316                   size_t n,
 317                   int flags,
 318                   const ACE_Time_Value *timeout) const;
 319
 320 private:
 321   void operator= (const ACE_SSL_SOCK_Stream &) = delete;
 322   ACE_SSL_SOCK_Stream (const ACE_SSL_SOCK_Stream &) = delete;
 323
 324 protected:
 325   /// The SSL session.
 326   SSL *ssl_;
 327
 328   /// The stream which works under the ssl connection.
 329   ACE_SOCK_Stream stream_;
 330 };
 331
 332 ACE_END_VERSIONED_NAMESPACE_DECL
 333
 334 #if defined (__ACE_INLINE__)
 335 #include "SSL_SOCK_Stream.inl"
 336 #endif /* __ACE_INLINE__ */
 337
 338 #include /**/ "ace/post.h"
 339
 340 #endif /* ACE_SSL_SOCK_STREAM_H */