Definition
An instance sb of class secure_socket_streambuf can be used as an adapter: It turns a leda_socket s into a C++-streambuf object. This object can be used in standard C++ ostreams and istreams, which makes the communication through the socket easier. Moreover, secure_socket_streambuf uses cryptography to secure the communication. Every piece of data is authenticated, (possibly) compressed and encrypted before it is sent.
If two parties want to use the class secure_socket_streambuf to exchange data they have to do the following. First they establish a connection through leda_sockets. Then each party contructs an instance of the class secure_socket_streambuf which is attached to its socket. (An example showing how to this can be found at the end of Section socket_streambuf; simply replace ``socket_streambuf'' by ``secure_socket_streambuf'' and add the passphrase(s).)
The communication between two instances of the class secure_socket_streambuf can be divided in two phases. In the first phase the two parties negotiate session parameters like packet sizes and they also agree on a so-called session-seed which will be explained later. In the second phase the actual user data is exchanged. Each phases is protected with cryptography. The authentication and encryption keys for the first phase are generated in a deterministic way from the user-supplied passphrase(s). They are called master keys because they remain the same as long as the passphrases are not changed. In order to protect the master keys we use them only during the first phase, which consists of two messages from each party. After that we use the random session seed (in addition to the passphrases) to compute session keys which are used during the second phase.
#include < LEDA/coding/secure_socket_streambuf.h >
Creation
| secure_socket_streambuf | sb(leda_socket& s, const CryptByteString& auth_passphrase, const CryptByteString& cipher_passphrase, uint32 out_buf_sz = DefaultBufferSize, uint32 in_buf_sz = DefaultBufferSize, bool enable_compression = false, bool send_acknowledge = false) | |
| creates a sb and attaches it to the socket s.
The two passphrases are used to generate the keys for authentication and
encryption.
The parameters out_buf_sz and in_buf_sz determine the maximum size of
the out-buffer and the in-buffer.
The paramter enable_compression determines whether compression is used.
send_acknowledge specifies whether an acknowledgement is sent for every
received packet.
Precondition The connection between the server and the client must have been established when sb is created. |
||
| secure_socket_streambuf | sb(leda_socket& s, const CryptByteString& passphrase, uint32 out_buf_sz = DefaultBufferSize, uint32 in_buf_sz = DefaultBufferSize, bool enable_compression = false, bool send_acknowledge = false) | |
| as above, but the same passphrase is used for generating both the authentication and the encryption key. However, it is still guaranteed that two different keys are used. | ||
Operations
The class secure_socket_streambuf inherits most of its operations from the class streambuf that belongs to the C++ standard library. Usually there is no need to call these operations explicitly. (You can find documentation for streambuf at http://www.cplusplus.com)
| bool | sb.failed() | returns whether a failure has occured. |
| string | sb.get_error() | returns an error message (if available). |
| void | sb.sputEOF() | signals the end of the transmission to the receiving socket, so that it does not wait for further data. (This function is called automatically in the destructor unless it has been called explicitly by the user. If sb is not immediately destroyed after the end of the transmission then you should call sputEOF explicitly, otherwise the receiving party might incur a timeout error.) |
| bool | sb.has_put_EOF() | returns whether EOF has already been sent. |
| bool | sb.has_got_EOF() | returns whether EOF has already been received. |
| leda_socket& | sb.get_socket() | returns the socket to which sb is attached. |
| uint32 | sb.get_outgoing_packet_size() | |
| returns the (actual) outgoing packet size. | ||
| uint32 | sb.get_incoming_packet_size() | |
| returns the (actual) incoming packet size. | ||
| bool | sb.uses_compression() | returns whether sb compresses outgoing packets before sending. |
| bool | sb.waits_for_acknowledge() | |
| returns whether sb expects an acknowledgement for outgoing packets. | ||
| bool | sb.sends_acknowledge() | returns whether sb sends an acknowledgement for incoming packets. |