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