1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
   12:  long SSL_set_mode(SSL *ssl, long mode);
   13: 
   14:  long SSL_CTX_get_mode(SSL_CTX *ctx);
   15:  long SSL_get_mode(SSL *ssl);
   16: 
   17: =head1 DESCRIPTION
   18: 
   19: SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
   20: Options already set before are not cleared.
   21: 
   22: SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
   23: Options already set before are not cleared.
   24: 
   25: SSL_CTX_get_mode() returns the mode set for B<ctx>.
   26: 
   27: SSL_get_mode() returns the mode set for B<ssl>.
   28: 
   29: =head1 NOTES
   30: 
   31: The following mode changes are available:
   32: 
   33: =over 4
   34: 
   35: =item SSL_MODE_ENABLE_PARTIAL_WRITE
   36: 
   37: Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
   38: when just a single record has been written). When not set (the default),
   39: SSL_write() will only report success once the complete chunk was written.
   40: Once SSL_write() returns with r, r bytes have been successfully written
   41: and the next call to SSL_write() must only send the n-r bytes left,
   42: imitating the behaviour of write().
   43: 
   44: =item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
   45: 
   46: Make it possible to retry SSL_write() with changed buffer location
   47: (the buffer contents must stay the same). This is not the default to avoid
   48: the misconception that non-blocking SSL_write() behaves like
   49: non-blocking write().
   50: 
   51: =item SSL_MODE_AUTO_RETRY
   52: 
   53: Never bother the application with retries if the transport is blocking.
   54: If a renegotiation take place during normal operation, a
   55: L<SSL_read(3)|SSL_read(3)> or L<SSL_write(3)|SSL_write(3)> would return
   56: with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.
   57: In a non-blocking environment applications must be prepared to handle
   58: incomplete read/write operations.
   59: In a blocking environment, applications are not always prepared to
   60: deal with read/write operations returning without success report. The
   61: flag SSL_MODE_AUTO_RETRY will cause read/write operations to only
   62: return after the handshake and successful completion.
   63: 
   64: =back
   65: 
   66: =head1 RETURN VALUES
   67: 
   68: SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
   69: after adding B<mode>.
   70: 
   71: SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
   72: 
   73: =head1 SEE ALSO
   74: 
   75: L<ssl(3)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)>
   76: 
   77: =head1 HISTORY
   78: 
   79: SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6.
   80: 
   81: =cut