Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

SSL_SOCK_Stream.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    SSL_SOCK_Stream.h
00006  *
00007  *  $Id: SSL_SOCK_Stream.h,v 1.1.1.2 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Ossama Othman <ossama@uci.edu>
00010  *  @author Carlos O'Ryan <coryan@uci.edu>
00011  *  @author John Heitmann
00012  */
00013 //=============================================================================
00014 
00015 
00016 #ifndef ACE_SSL_SOCK_STREAM_H
00017 #define ACE_SSL_SOCK_STREAM_H
00018 
00019 #include "ace/pre.h"
00020 
00021 #include "SSL_Export.h"
00022 
00023 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00024 # pragma once
00025 #endif /* ACE_LACKS_PRAGMA_ONCE */
00026 
00027 #include <openssl/err.h>
00028 
00029 #include "SSL_SOCK.h"
00030 #include "SSL_Context.h"
00031 
00032 #include "ace/SOCK_Stream.h"
00033 
00034 
00035 /**
00036  * @class ACE_SSL_SOCK_Stream
00037  *
00038  * @brief Defines methods in the ACE_SSL_SOCK_Stream abstraction.
00039  *
00040  * This class encapsulates the methods and functionality necessary to
00041  * send and receive data over TLS/SSL.
00042  * @par
00043  * Since SSL is record-oriented, some additional steps must be taken
00044  * to make the ACE_SSL_SOCK_Stream interact properly with the
00045  * Reactor (if one is used) when performing non-blocking IO.  In
00046  * particular, if ::SSL_pending (ssl), where "ssl" is a pointer to the
00047  * SSL data structure returned from ACE_SSL_SOCK_Stream::ssl(),
00048  * returns a non-zero value then the event handler that calls the IO
00049  * methods in this class should return a value greater than zero to
00050  * force the Reactor to invoke the event handler before polling for
00051  * additional events (e.g. blocking on select()).
00052  *
00053  * @note The user must currently ensure that only one thread services
00054  *       a given SSL session at any given time since underlying SSL
00055  *       implementations, such as OpenSSL, are not entirely
00056  *       thread-safe or reentrant.
00057  */
00058 class ACE_SSL_Export ACE_SSL_SOCK_Stream : public ACE_SSL_SOCK
00059 {
00060   friend class ACE_SSL_SOCK_Connector;
00061   friend class ACE_SSL_SOCK_Acceptor;
00062 
00063 public:
00064 
00065   /// Constructor
00066   ACE_SSL_SOCK_Stream (ACE_SSL_Context *context =
00067                          ACE_SSL_Context::instance ());
00068 
00069   /// Destructor
00070   ~ACE_SSL_SOCK_Stream (void);
00071 
00072   /// Send an n byte buffer to the ssl socket using the semantics of
00073   /// send(3n).
00074   /**
00075    * ACE_SSL supports no flags for sending at this time.
00076    */
00077   ssize_t send (const void *buf,
00078                 size_t n,
00079                 int flags) const;
00080 
00081   /// Recv an n byte buffer from the ssl socket using the semantics of
00082   /// recv(3n).
00083   /**
00084    * ACE_SSL supports MSG_PEEK, but no other flags at this time.
00085    */
00086   ssize_t recv (void *buf,
00087                 size_t n,
00088                 int flags) const;
00089 
00090   /// Send an n byte buffer to the ssl socket using the semantics of
00091   /// write(2).
00092   ssize_t send (const void *buf,
00093                 size_t n) const;
00094 
00095   /// Recv an n byte buffer from the ssl socket using the semantics of
00096   /// read(2).
00097   ssize_t recv (void *buf,
00098                 size_t n) const;
00099 
00100   /// Send an iovec of size n to the ssl socket.
00101   /**
00102    * Note that it is not possible to perform a "scattered" write with
00103    * the underlying OpenSSL implementation.  As such, the expected
00104    * semantics are not fully reproduced with this implementation.
00105    */
00106   ssize_t sendv (const iovec iov[],
00107                  size_t n,
00108                  const ACE_Time_Value *timeout = 0) const;
00109 
00110   /**
00111    * Allows a client to read from a socket without having to provide a
00112    * buffer to read.  This method determines how much data is in the
00113    * socket, allocates a buffer of this size, reads in the data, and
00114    * returns the number of bytes read.  The caller is responsible for
00115    * deleting the member in the iov_base field of io_vec using
00116    * delete [] io_vec->iov_base.
00117    */
00118   ssize_t recvv (iovec *io_vec,
00119                  const ACE_Time_Value *timeout = 0) const;
00120 
00121   /**
00122    * Wait to timeout amount of time to send up to n bytes into buf
00123    * (uses the send() call).  If send() times out -1 is returned with
00124    * errno == ETIME.  If it succeeds the number of bytes sent is
00125    * returned. No flags are supported.
00126    */
00127   ssize_t send (const void *buf,
00128                 size_t n,
00129                 int flags,
00130                 const ACE_Time_Value *timeout) const;
00131 
00132   /**
00133    * Wait up to timeout amount of time to receive up to n bytes into
00134    * buf (uses the recv() call).  If recv() times out -1 is returned
00135    * with errno == ETIME.  If it succeeds the number of bytes received
00136    * is returned.  MSG_PEEK is the only supported flag.
00137    */
00138   ssize_t recv (void *buf,
00139                 size_t n,
00140                 int flags,
00141                 const ACE_Time_Value *timeout) const;
00142 
00143   /**
00144    * Wait to to timeout amount of time to send up to n bytes into
00145    * buf (uses the send() call).  If send() times out
00146    * a -1 is returned with errno == ETIME.  If it succeeds the
00147    * number of bytes sent is returned.
00148    */
00149   ssize_t send (const void *buf,
00150                 size_t n,
00151                 const ACE_Time_Value *timeout) const;
00152 
00153   /**
00154    * Wait up to timeout amount of time to receive up to n bytes
00155    * into buf (uses the recv() call).  If recv() times
00156    * out a -1 is returned with errno == ETIME.  If it succeeds the
00157    * number of bytes received is returned.
00158    */
00159   ssize_t recv (void *buf,
00160                 size_t n,
00161                 const ACE_Time_Value *timeout) const;
00162 
00163   /// Send n varargs messages to the connected ssl socket.
00164   ssize_t send (size_t n,
00165                 ...) const;
00166 
00167   /// Recv n varargs messages to the connected ssl socket.
00168   ssize_t recv (size_t n,
00169                 ...) const;
00170 
00171   /// Send n bytes, keep trying until n are sent.
00172   ssize_t send_n (const void *buf, int n) const;
00173 
00174   /// Recv n bytes, keep trying until n are received.
00175   ssize_t recv_n (void *buf, int n) const;
00176 
00177   /**
00178    * @note In the following four methods, only MSG_PEEK is supported
00179    * for recv_n(), and no flags are supported for send_n().
00180    */
00181   //@{
00182   /// Send n bytes, keep trying until n are sent.
00183   ssize_t send_n (const void *buf, int n, int flags) const;
00184 
00185   /// Recv n bytes, keep trying until n are sent.
00186   ssize_t recv_n (void *buf, int n, int flags) const;
00187 
00188   /**
00189    * Try to send exactly len bytes into buf (uses the send() call).
00190    * If send() blocks for longer than timeout the number of bytes
00191    * actually sent is returned with errno == ETIME.  If a timeout does
00192    * not occur, send_n() return len (i.e., the number of bytes
00193    * requested to be sent).
00194    */
00195   ssize_t send_n (const void *buf,
00196                   size_t len,
00197                   int flags,
00198                   const ACE_Time_Value *timeout,
00199                   size_t *bytes_transferred = 0) const;
00200 
00201   /**
00202    * Try to receive exactly len bytes into buf (uses the recv() call).
00203    * The ACE_Time_Value indicates how long to blocking trying to
00204    * receive.  If timeout == 0, the caller will block until action is
00205    * possible, else will wait until the relative time specified in
00206    * timeout elapses).  If recv() blocks for longer than timeout the
00207    * number of bytes actually read is returned with errno == ETIME.
00208    * If a timeout does not occur, recv_n return len (i.e., the number
00209    * of bytes requested to be read).
00210    */
00211   ssize_t recv_n (void *buf,
00212                   size_t len,
00213                   int flags,
00214                   const ACE_Time_Value *timeout,
00215                   size_t *bytes_transferred = 0) const;
00216   //@}
00217 
00218   /**
00219    * Send an iovec of size n to the connected socket.  Will block
00220    * until all bytes are sent or an error occurs.
00221    */
00222   ssize_t sendv_n (const iovec iov[],
00223                    size_t n) const;
00224 
00225   /// Receive an iovec of size n to the connected socket.
00226   ssize_t recvv_n (iovec iov[],
00227                    size_t n) const;
00228 
00229 
00230   /**
00231    * Selectively close endpoints.
00232    */
00233   //@{
00234   /// Close down the reader.
00235   int close_reader (void);
00236 
00237   /// Close down the writer.
00238   int close_writer (void);
00239   //@}
00240 
00241   ///Close down the socket.
00242   int close (void);
00243 
00244   /// Meta-type info
00245   typedef ACE_INET_Addr PEER_ADDR;
00246 
00247   /// Declare the dynamic allocation hooks.
00248   ACE_ALLOC_HOOK_DECLARE;
00249 
00250   /// Overridden set_handle() method.
00251   /**
00252    * Only an ACE_SSL_SOCK_Acceptor or ACE_SSL_SOCK_Connector should
00253    * access this method since some state in the underlying "ssl_" data
00254    * structure is set during SSL connection establishment.
00255    */
00256   void set_handle (ACE_HANDLE fd);
00257 
00258   /// Return a pointer to the underlying SSL structure.
00259   SSL *ssl (void) const;
00260 
00261   /**
00262    * Return the address of the remotely connected peer (if there is
00263    * one), in the referenced <ACE_Addr>. Returns 0 if successful, else
00264    * -1.
00265    *
00266    * @note If the TCP connection has been completed but the SSL
00267    *       connection has not been completed yet, -1 will be
00268    *       returned.
00269    */
00270   int get_remote_addr (ACE_Addr &) const;
00271 
00272   /// Return the underlying ACE_SOCK_Stream which ACE_SSL runs atop of.
00273   ACE_SOCK_Stream & peer (void);
00274 
00275 protected:
00276 
00277   /// Underlying send() helper method common to all public send()
00278   /// methods.
00279   ssize_t send_i (const void *buf,
00280                   size_t n,
00281                   int flags) const;
00282 
00283   /// Underlying send() helper method common to all public send()
00284   /// methods.
00285   ssize_t recv_i (void *buf,
00286                   size_t n,
00287                   int flags,
00288                   const ACE_Time_Value *timeout) const;
00289 
00290 private:
00291 
00292   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_SSL_SOCK_Stream &))
00293   ACE_UNIMPLEMENTED_FUNC (ACE_SSL_SOCK_Stream (const ACE_SSL_SOCK_Stream &))
00294 
00295 protected:
00296 
00297   /// The SSL session.
00298   SSL *ssl_;
00299 
00300   /// The stream which works under the ssl connection.
00301   ACE_SOCK_Stream stream_;
00302 
00303 };
00304 
00305 #if !defined (ACE_LACKS_INLINE_FUNCTIONS)
00306 #include "SSL_SOCK_Stream.i"
00307 #endif /* ACE_LACKS_INLINE_FUNCTIONS */
00308 
00309 #include "ace/post.h"
00310 
00311 #endif /* ACE_SSL_SOCK_STREAM_H */

Generated on Mon Jun 16 13:15:56 2003 for ACE_SSL by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002