From: rl1987 Date: Wed, 23 May 2018 11:08:47 +0000 (+0200) Subject: Document new code X-Git-Tag: tor-0.3.5.1-alpha~213^2~2^2~4 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a6af21c1b7f1751b96352a5080e0b3fb7e6201a9;p=thirdparty%2Ftor.git Document new code --- diff --git a/src/or/proto_socks.c b/src/or/proto_socks.c index 9f6073d2a6..dab349bbea 100644 --- a/src/or/proto_socks.c +++ b/src/or/proto_socks.c @@ -18,10 +18,10 @@ #include "or/socks_request_st.h" typedef enum { - SOCKS_RESULT_INVALID = -1, - SOCKS_RESULT_TRUNCATED = 0, - SOCKS_RESULT_DONE = 1, - SOCKS_RESULT_MORE_EXPECTED = 2, + SOCKS_RESULT_INVALID = -1, /* Message invalid. */ + SOCKS_RESULT_TRUNCATED = 0, /* Message incomplete/truncated. */ + SOCKS_RESULT_DONE = 1, /* OK, we're done. */ + SOCKS_RESULT_MORE_EXPECTED = 2, /* OK, more messages expected. */ } socks_result_t; static void socks_request_set_socks5_error(socks_request_t *req, @@ -96,6 +96,16 @@ socks_request_free_(socks_request_t *req) tor_free(req); } +/** + * Parse a single SOCKS4 request from buffer raw_data of length + * datalen and update relevant fields of req. If SOCKS4a + * request is detected, set *is_socks4a to true. Set *drain_out + * to number of bytes we parsed so far. + * + * Return SOCKS_RESULT_DONE if parsing succeeded, SOCKS_RESULT_INVALID if + * parsing failed because of invalid input or SOCKS_RESULT_TRUNCATED if it + * failed due to incomplete (truncated) input. + */ static socks_result_t parse_socks4_request(const uint8_t *raw_data, socks_request_t *req, size_t datalen, int *is_socks4a, size_t *drain_out) @@ -246,6 +256,17 @@ process_socks4_request(const socks_request_t *req, int is_socks4a, return SOCKS_RESULT_DONE; } +/** Parse a single SOCKS5 version identifier/method selection message + * from buffer raw_data (of length datalen). Update + * relevant fields of req (if any). Set *have_user_pass to + * true if username/password method is found. Set *have_no_auth + * if no-auth method is found. Set *drain_out to number of bytes + * we parsed so far. + * + * Return SOCKS_RESULT_DONE if parsing succeeded, SOCKS_RESULT_INVALID if + * parsing failed because of invalid input or SOCKS_RESULT_TRUNCATED if it + * failed due to incomplete (truncated) input. + */ static socks_result_t parse_socks5_methods_request(const uint8_t *raw_data, socks_request_t *req, size_t datalen, int *have_user_pass, @@ -309,6 +330,16 @@ parse_socks5_methods_request(const uint8_t *raw_data, socks_request_t *req, return res; } +/** + * Validate and respond to version identifier/method selection message + * we parsed in parse_socks5_methods_request (corresponding to req + * and having user/pass method if have_user_pass is true, no-auth + * method if have_no_auth is true). Set req->reply to + * an appropriate response (in SOCKS5 wire format). + * + * On success, return SOCKS_RESULT_DONE. On failure, return + * SOCKS_RESULT_INVALID. + */ static socks_result_t process_socks5_methods_request(socks_request_t *req, int have_user_pass, int have_no_auth) @@ -363,6 +394,16 @@ process_socks5_methods_request(socks_request_t *req, int have_user_pass, return res; } +/** + * Parse SOCKS5/RFC1929 username/password request from buffer + * raw_data of length datalen and update relevant + * fields of req. Set *drain_out to number of bytes + * we parsed so far. + * + * Return SOCKS_RESULT_DONE if parsing succeeded, SOCKS_RESULT_INVALID if + * parsing failed because of invalid input or SOCKS_RESULT_TRUNCATED if it + * failed due to incomplete (truncated) input. + */ static socks_result_t parse_socks5_userpass_auth(const uint8_t *raw_data, socks_request_t *req, size_t datalen, size_t *drain_out) @@ -415,6 +456,12 @@ parse_socks5_userpass_auth(const uint8_t *raw_data, socks_request_t *req, return res; } +/** + * Validate and respond to SOCKS5 username/password request we + * parsed in parse_socks5_userpass_auth (corresponding to req. + * Set req->reply to appropriate responsed. Return + * SOCKS_RESULT_DONE on success or SOCKS_RESULT_INVALID on failure. + */ static socks_result_t process_socks5_userpass_auth(socks_request_t *req) { @@ -461,6 +508,15 @@ process_socks5_userpass_auth(socks_request_t *req) return res; } +/** + * Parse a single SOCKS5 client request (RFC 1928 section 4) from buffer + * raw_data of length datalen and update relevant field of + * req. Set *drain_out to number of bytes we parsed so far. + * + * Return SOCKS_RESULT_DONE if parsing succeeded, SOCKS_RESULT_INVALID if + * parsing failed because of invalid input or SOCKS_RESULT_TRUNCATED if it + * failed due to incomplete (truncated) input. + */ static socks_result_t parse_socks5_client_request(const uint8_t *raw_data, socks_request_t *req, size_t datalen, size_t *drain_out) @@ -527,6 +583,16 @@ parse_socks5_client_request(const uint8_t *raw_data, socks_request_t *req, return res; } +/** + * Validate and respond to SOCKS5 request we parsed in + * parse_socks5_client_request (corresponding to req. + * Write appropriate response to req->reply (in + * SOCKS5 wire format). If log_sockstype is true, log a + * notice about possible DNS leaks on local system. If + * safe_socks is true, disallow insecure usage of SOCKS + * protocol. Return SOCKS_RESULT_DONE on success or + * SOCKS_RESULT_INVALID on failure. + */ static socks_result_t process_socks5_client_request(socks_request_t *req, int log_sockstype, @@ -587,6 +653,28 @@ process_socks5_client_request(socks_request_t *req, return res; } +/** + * Handle (parse, validate, process, respond) a single SOCKS + * message in buffer raw_data of length datalen. + * Update relevant fields of req. If log_sockstype + * is true, log a warning about possible DNS leaks on local + * system. If safe_socks is true, disallow insecure + * usage of SOCKS protocol. Set *drain_out to number + * of bytes in raw_data that we processed so far and + * that can be safely drained from buffer. + * + * Return: + * - SOCKS_RESULT_DONE if succeeded and not expecting further + * messages from client. + * - SOCKS_RESULT_INVALID if any of the steps failed due to + * request being invalid or unexpected given current state. + * - SOCKS_RESULT_TRUNCATED if we do not found an expected + * SOCKS message in its entirety (more stuff has to arrive + * from client). + * - SOCKS_RESULT_MORE_EXPECTED if we handled current message + * successfully, but we expect more messages from the + * client. + */ static socks_result_t handle_socks_message(const uint8_t *raw_data, size_t datalen, socks_request_t *req, int log_sockstype,