[tor-commits] [obfsproxy/master] Updated function documentation.

commit 46762842d8eb314b13a158e725c472da0e0d3601 Author: George Kadianakis desnacked@gmail.com Date: Sat Jun 11 00:03:33 2011 +0200

Updated function documentation. --- src/main.c | 2 +- src/network.c | 46 ++++++++++++++++++++++--- src/protocol.c | 5 +-- src/protocols/dummy.c | 29 +++++++++++++-- src/protocols/obfs2.c | 3 ++ src/protocols/obfs2_crypt.c | 42 +++++++++++++++++++++++ src/socks.c | 79 +++++++++++++++++++++++++++++++----------- src/util.c | 16 +++++++++ 8 files changed, 188 insertions(+), 34 deletions(-)

diff --git a/src/main.c b/src/main.c index ace9e8c..9399783 100644 --- a/src/main.c +++ b/src/main.c @@ -80,7 +80,7 @@ populate_options(char **options_string, }

/** - Returns 1 if 'name' is the nmae of a supported protocol, otherwise + Returns 1 if 'name' is the name of a supported protocol, otherwise it returns 0. */ static int diff --git a/src/network.c b/src/network.c index e3c2fa0..a0ab6e9 100644 --- a/src/network.c +++ b/src/network.c @@ -36,10 +36,9 @@ static void input_event_cb(struct bufferevent *bev, short what, void *arg); static void output_event_cb(struct bufferevent *bev, short what, void *arg);

/** - This function sets up the protocol defined by 'options' and - attempts to bind a new listener for it. + This function spawns a listener according to the 'proto_params'.

- Returns the listener on success, NULL on fail. + Returns the listener on success and NULL on fail. */ listener_t * listener_new(struct event_base *base, @@ -72,6 +71,9 @@ listener_new(struct event_base *base, return lsn; }

+/** + Deallocates listener_t 'lsn'. +*/ void listener_free(listener_t *lsn) { @@ -83,9 +85,16 @@ listener_free(listener_t *lsn) free(lsn); }

+/** + This function is called when a new connection is received. + + It initializes the protocol we are using, sets up the necessary + callbacks for input/output and does the protocol handshake. +*/ static void simple_listener_cb(struct evconnlistener *evcl, - evutil_socket_t fd, struct sockaddr *sourceaddr, int socklen, void *arg) + evutil_socket_t fd, struct sockaddr *sourceaddr, + int socklen, void *arg) { listener_t *lsn = arg; struct event_base *base; @@ -174,6 +183,9 @@ simple_listener_cb(struct evconnlistener *evcl, evutil_closesocket(fd); }

+/** + Deallocates conn_t 'conn'. +*/ static void conn_free(conn_t *conn) { @@ -189,6 +201,10 @@ conn_free(conn_t *conn) free(conn); }

+/** + Closes associated connection if the output evbuffer of 'bev' is + empty. +*/ static void close_conn_on_flush(struct bufferevent *bev, void *arg) { @@ -198,7 +214,9 @@ close_conn_on_flush(struct bufferevent *bev, void *arg) conn_free(conn); }

-/** This is only used in the input bufferevent of clients. */ +/** + This callback is responsible for handling SOCKS traffic. +*/ static void socks_read_cb(struct bufferevent *bev, void *arg) { @@ -253,6 +271,9 @@ socks_read_cb(struct bufferevent *bev, void *arg) } }

+/** + This callback is responsible for handling plaintext traffic. +*/ static void plaintext_read_cb(struct bufferevent *bev, void *arg) { @@ -267,6 +288,11 @@ plaintext_read_cb(struct bufferevent *bev, void *arg) conn_free(conn); }

+/** + This callback is responsible for handling obfusacted + traffic -- traffic that has already been obfuscated + by our protocol. +*/ static void obfuscated_read_cb(struct bufferevent *bev, void *arg) { @@ -288,6 +314,10 @@ obfuscated_read_cb(struct bufferevent *bev, void *arg) bufferevent_get_output(conn->output)); }

+/** + Something broke in our connection or we reached EOF. + We prepare the connection to be closed ASAP. +*/ static void error_or_eof(conn_t *conn, struct bufferevent *bev_err, struct bufferevent *bev_flush) @@ -311,6 +341,9 @@ error_or_eof(conn_t *conn, bufferevent_enable(bev_flush, EV_WRITE); }

+/** + We land in here when an event happens on conn->input. +*/ static void input_event_cb(struct bufferevent *bev, short what, void *arg) { @@ -325,6 +358,9 @@ input_event_cb(struct bufferevent *bev, short what, void *arg) /* XXX we don't expect any other events */ }

+/** + We land in here when an event happens on conn->output. +*/ static void output_event_cb(struct bufferevent *bev, short what, void *arg) { diff --git a/src/protocol.c b/src/protocol.c index 544dcef..0845c11 100644 --- a/src/protocol.c +++ b/src/protocol.c @@ -40,9 +40,8 @@ set_up_protocol(int n_options, char **options, }

/** - This function creates a protocol object. - It's called once per connection. - It creates a new protocol_t structure and fills it's vtable etc. + This function is called once per connection and creates a protocol + object to be used during the session. Return a 'protocol_t' if successful, NULL otherwise. */ struct protocol_t * diff --git a/src/protocols/dummy.c b/src/protocols/dummy.c index bdf97fc..be4c287 100644 --- a/src/protocols/dummy.c +++ b/src/protocols/dummy.c @@ -26,9 +26,10 @@ static int parse_and_set_options(int n_options, char **options, struct protocol_params_t *params);

static protocol_vtable *vtable=NULL; + /** - This function sets up the protocol and populates 'listner' - according to 'options'. + This function populates 'params' according to 'options' and sets up + the protocol vtable.

'options' is an array like this: {"dummy","socks","127.0.0.1:6666"} @@ -56,6 +57,9 @@ dummy_init(int n_options, char **options, return 1; }

+/** + Helper: Parses 'options' and fills 'params'. +*/ static int parse_and_set_options(int n_options, char **options, struct protocol_params_t *params) @@ -96,6 +100,9 @@ parse_and_set_options(int n_options, char **options, return 1; }

+/** + Prints dummy protocol usage information. +*/ static void usage(void) { @@ -109,8 +116,12 @@ usage(void) "\tobfsproxy dummy socks 127.0.0.1:5000\n"); }

- - +/* + This is called everytime we get a connection for the dummy + protocol. + + It sets up the protocol vtable in 'proto_struct'. +*/ void * dummy_new(struct protocol_t *proto_struct, struct protocol_params_t *params) @@ -122,6 +133,11 @@ dummy_new(struct protocol_t *proto_struct, return (void *)666U; }

+/** + Responsible for sending data according to the dummy protocol. + + The dummy protocol just puts the data of 'source' in 'dest'. +*/ static int dummy_send(void *nothing, struct evbuffer *source, struct evbuffer *dest) { @@ -130,6 +146,11 @@ dummy_send(void *nothing, return evbuffer_add_buffer(dest,source); }

+/* + Responsible for receiving data according to the dummy protocol. + + The dummy protocol just puts the data of 'source' into 'dest'. +*/ static enum recv_ret dummy_recv(void *nothing, struct evbuffer *source, struct evbuffer *dest) { diff --git a/src/protocols/obfs2.c b/src/protocols/obfs2.c index 676ddd7..f4302a2 100644 --- a/src/protocols/obfs2.c +++ b/src/protocols/obfs2.c @@ -61,6 +61,9 @@ obfs2_init(int n_options, char **options, return 1; }

+/** + Helper: Parses 'options' and fills 'params'. +*/ int parse_and_set_options(int n_options, char **options, struct protocol_params_t *params) diff --git a/src/protocols/obfs2_crypt.c b/src/protocols/obfs2_crypt.c index 681fab6..4e814e7 100644 --- a/src/protocols/obfs2_crypt.c +++ b/src/protocols/obfs2_crypt.c @@ -48,6 +48,9 @@ get_uint32(const void *ptr) #include "../sha256.c" #endif

+/** + Initializes the obfs2 crypto subsystem. +*/ int initialize_crypto(void) { @@ -77,6 +80,9 @@ initialize_crypto(void) #endif }

+/** + Cleans up the obfs2 crypto subsystem. +*/ void cleanup_crypto(void) { @@ -91,18 +97,33 @@ cleanup_crypto(void) struct digest_t { SHA256_CTX ctx; }; + +/** + Returns a new SHA256 digest container, or NULL on failure. +*/ digest_t * digest_new(void) { digest_t *d = malloc(sizeof(digest_t)); + if (!d) + return NULL; SHA256_Init(&d->ctx); return d; } + +/** + Updates the contents of the SHA256 container 'd' with the first + 'len' bytes of 'buf'. +*/ void digest_update(digest_t *d, const uchar *buf, size_t len) { SHA256_Update(&d->ctx, buf, len); } + +/** + Returns the digest stored in 'd' into 'buf' of length 'len'. +*/ size_t digest_getdigest(digest_t *d, uchar *buf, size_t len) { @@ -123,6 +144,8 @@ digest_t * digest_new(void) { digest_t *d = malloc(sizeof(digest_t)); + if (!d) + return NULL; sha256_init(&d->ctx); return d; } @@ -156,6 +179,9 @@ digest_free(digest_t *d) Stream crypto ===== */

+/** + Initializes the AES cipher with 'key'. +*/ crypt_t * crypt_new(const uchar *key, size_t keylen) { @@ -171,12 +197,20 @@ crypt_new(const uchar *key, size_t keylen)

return k; } + +/** + Sets the IV of 'key' to 'iv'. +*/ void crypt_set_iv(crypt_t *key, const uchar *iv, size_t ivlen) { assert(ivlen == sizeof(key->ivec)); memcpy(key->ivec, iv, ivlen); } + +/* + In-place encrypts 'buf' with 'key'. +*/ void stream_crypt(crypt_t *key, uchar *buf, size_t len) { @@ -185,6 +219,10 @@ stream_crypt(crypt_t *key, uchar *buf, size_t len) &key->key, key->ivec, key->ecount_buf, &key->pos); } + +/** + Deallocates memory space of 'key'. +*/ void crypt_free(crypt_t *key) { @@ -196,6 +234,10 @@ crypt_free(crypt_t *key) PRNG ===== */

+/** + Fills 'buf' with 'buflen' random bytes and returns 0 on success. + Returns -1 on failure. +*/ int random_bytes(uchar *buf, size_t buflen) { diff --git a/src/socks.c b/src/socks.c index 7cf179b..d3c69f2 100644 --- a/src/socks.c +++ b/src/socks.c @@ -48,6 +48,11 @@ static enum socks_ret socks5_do_negotiation(struct evbuffer *dest,

typedef unsigned char uchar;

+/** + Creates a new SOCKS state. + + Returns a 'socks_state_t' on success, NULL on fail. +*/ socks_state_t * socks_state_new(void) { @@ -59,6 +64,9 @@ socks_state_new(void) return state; }

+/** + Deallocates memory of socks_state_t 's'. +*/ void socks_state_free(socks_state_t *s) { @@ -108,17 +116,15 @@ socks_errno_to_reply(socks_state_t *state, int error) #undef ERR

/** - Takes a command request from 'source', it evaluates it and if it's - legit it parses it into 'parsereq'. - - It returns '1' if everything went fine. - It returns '0' if we need more data from the client. - It returns '-1' if we didn't like something. - It returns '-2' if the client asked for something else than CONNECT. - If that's the case we should send a reply back to the client - telling him that we don't support it. + Takes a SOCKS5 command request from 'source', it evaluates it and + if it's legit it parses it into 'parsereq'.

- Disclaimer: This is just a temporary documentation. + It returns SOCKS_GOOD if everything went fine. + It returns SOCKS_INCOMPLETE if we need more data from the client. + It returns SOCKS_BROKEN if we didn't like something. + It returns SOCKS_CMD_NOT_CONNECT if the client asked for something + else other than CONNECT. If that's the case we should send a reply + back to the client telling him that we don't support it.

Client Request (Client -> Server) */ @@ -223,7 +229,8 @@ socks5_handle_request(struct evbuffer *source, struct parsereq *parsereq) }

/** - This sends the appropriate reply to the client on 'reply_dest'. + This sends the appropriate SOCKS5 reply to the client on + 'reply_dest', according to 'status'.

Server Reply (Server -> Client): | version | rep | rsv | atyp | destaddr | destport @@ -281,7 +288,7 @@ socks5_send_reply(struct evbuffer *reply_dest, socks_state_t *state,

/** This function handles the initial SOCKS5 packet in 'source' sent by - the client, which negotiates the version and method of SOCKS. If + the client which negotiates the version and method of SOCKS. If the packet is actually valid, we reply to 'dest'.

Method Negotiation Packet (Client -> Server): @@ -351,7 +358,14 @@ socks5_do_negotiation(struct evbuffer *dest, unsigned int neg_was_success) return SOCKS_GOOD; }

-/* rename to socks4_handle_request or something. */ +/** + Takes a SOCKS4/SOCKS4a command request from 'source', it evaluates + it and if it's legit it parses it into 'parsereq'. + + It returns SOCKS_GOOD if everything went fine. + It returns SOCKS_INCOMPLETE if we need more data from the client. + It returns SOCKS_BROKEN if we didn't like something. +*/ enum socks_ret socks4_read_request(struct evbuffer *source, socks_state_t *state) { @@ -418,13 +432,18 @@ socks4_read_request(struct evbuffer *source, socks_state_t *state) } else { struct in_addr in; in.s_addr = htonl(ipaddr); - if (evutil_inet_ntop(AF_INET, &in, state->parsereq.addr, sizeof(state->parsereq.addr)) == NULL) + if (evutil_inet_ntop(AF_INET, &in, state->parsereq.addr, + sizeof(state->parsereq.addr)) == NULL) return SOCKS_BROKEN; }

return SOCKS_GOOD; }

+/** + This sends the appropriate SOCKS4 reply to the client on + 'reply_dest', according to 'status'. +*/ int socks4_send_reply(struct evbuffer *dest, socks_state_t *state, int status) { @@ -448,12 +467,15 @@ socks4_send_reply(struct evbuffer *dest, socks_state_t *state, int status) }

/** - We are given data from the network. - If we haven't negotiated with the connection, we try to negotiate. - If we have already negotiated, we suppose it's a CONNECT request and - try to be helpful. - - Returns 1 on done, -1 on unrecoverable error, 0 on "need more bytes + We are given SOCKS data from the network. + We figure out what what SOCKS version it is and act accordingly. + + It returns SOCKS_GOOD if everything went fine. + It returns SOCKS_INCOMPLETE if we need more data from the client. + It returns SOCKS_BROKEN if we didn't like something. + It returns SOCKS_CMD_NOT_CONNECT if the client asked for something + else other than CONNECT. If that's the case we should send a reply + back to the client telling him that we don't support it. */ enum socks_ret handle_socks(struct evbuffer *source, struct evbuffer *dest, @@ -533,12 +555,22 @@ handle_socks(struct evbuffer *source, struct evbuffer *dest, return SOCKS_BROKEN; }

+/** + Returns the protocol status of the SOCKS state 'state'. +*/ enum socks_status_t socks_state_get_status(const socks_state_t *state) { return state->state; }

+/** + If we have previously parsed a SOCKS CONNECT request, this function + places the corresponding address/port to 'af_out', 'addr_out' and + 'port_out'. + + It returns 0 on success and -1 if it was called unnecessarily. +*/ int socks_state_get_address(const socks_state_t *state, int *af_out, @@ -553,6 +585,10 @@ socks_state_get_address(const socks_state_t *state, return 0; }

+/** + Places the address/port in 'sa' into the SOCKS state 'state' for + later retrieval. +*/ int socks_state_set_address(socks_state_t *state, const struct sockaddr *sa) { @@ -583,11 +619,12 @@ socks_state_set_address(socks_state_t *state, const struct sockaddr *sa)

/** This function sends a SOCKS{5,4} "Server Reply" to 'dest'. + 'error' is 0 if no errors were encountered during the SOCKS operation (normally a CONNECT with no errors means that the connect() was successful). If 'error' is not 0, it means that an error was encountered and - error carries the errno(3) of the error. + error carries the errno(3). */ int socks_send_reply(socks_state_t *state, struct evbuffer *dest, int error) diff --git a/src/util.c b/src/util.c index d4eddb6..1d44a52 100644 --- a/src/util.c +++ b/src/util.c @@ -27,6 +27,17 @@ static void logv(int severity, const char *format, va_list ap);

/************************ Obfsproxy Network Routines *************************/

+/** + Accepts a string 'address' of the form ADDRESS:PORT and attempts to + parse it into 'addr_out' and put it's length into 'addrlen_out'. + + If 'nodns' is set it means that 'address' was an IP address. + If 'passive' is set it means that the address is destined for + listening and not for connecting. + + If no port was given in 'address', we set 'default_port' as the + port. +*/ int resolve_address_port(const char *address, int nodns, int passive, @@ -369,6 +380,10 @@ logv(int severity, const char *format, va_list ap) }

#ifdef NEED_LOG_WRAPPERS +/** + If our platform doesn't support the log_* macros defined in + util.h, we use these functions. +*/ void log_info(const char *format, ...) { @@ -399,4 +414,5 @@ log_debug(const char *format, ...)

va_end(ap); } + #endif