July 2020 - tor-commits - lists.torproject.org

[tor/master] Update channel_matches_target_addr_for_extend test to current API
by nickm＠torproject.org 13 Jul '20

13 Jul '20

commit 59133051f9040717f2f87aa5c2b051eadce2ebdf Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Jul 13 10:10:25 2020 -0400 Update channel_matches_target_addr_for_extend test to current API --- src/core/or/channel.c | 9 +-------- src/core/or/channel.h | 5 ++++- src/test/test_channel.c | 12 ++++++------ 3 files changed, 11 insertions(+), 15 deletions(-) diff --git a/src/core/or/channel.c b/src/core/or/channel.c index e21f5a12c..20ccf4130 100644 --- a/src/core/or/channel.c +++ b/src/core/or/channel.c @@ -83,13 +83,6 @@ #include "core/or/cell_queue_st.h" -/* Static function prototypes */ - -static bool channel_matches_target_addr_for_extend( - channel_t *chan, - const tor_addr_t *target_ipv4_addr, - const tor_addr_t *target_ipv6_addr); - /* Global lists of channels */ /* All channel_t instances */ @@ -3317,7 +3310,7 @@ channel_matches_extend_info(channel_t *chan, extend_info_t *extend_info) * This function calls into the lower layer and asks if this channel thinks * it matches the target addresses for circuit extension purposes. */ -static bool +STATIC bool channel_matches_target_addr_for_extend(channel_t *chan, const tor_addr_t *target_ipv4_addr, const tor_addr_t *target_ipv6_addr) diff --git a/src/core/or/channel.h b/src/core/or/channel.h index 79e5fea9c..5fe1fb9cc 100644 --- a/src/core/or/channel.h +++ b/src/core/or/channel.h @@ -562,7 +562,10 @@ void channel_listener_dumpstats(int severity); #ifdef CHANNEL_FILE_PRIVATE STATIC void channel_add_to_digest_map(channel_t *chan); - +STATIC bool channel_matches_target_addr_for_extend( + channel_t *chan, + const tor_addr_t *target_ipv4_addr, + const tor_addr_t *target_ipv6_addr); #endif /* defined(CHANNEL_FILE_PRIVATE) */ /* Channel operations for subclasses and internal use only */ diff --git a/src/test/test_channel.c b/src/test/test_channel.c index 53ca8d9bb..2b723b4a8 100644 --- a/src/test/test_channel.c +++ b/src/test/test_channel.c @@ -1549,8 +1549,8 @@ test_channel_listener(void *arg) orcon->real_addr = addr; \ STMT_END; -#define TEST_MATCHES_ADDR(chan, addr, rv, exp) STMT_BEGIN \ - rv = channel_matches_target_addr_for_extend(chan, &addr); \ +#define TEST_MATCHES_ADDR(chan, addr4, addr6, rv, exp) STMT_BEGIN \ + rv = channel_matches_target_addr_for_extend(chan, addr4, addr6); \ tt_int_op(rv, OP_EQ, exp); \ STMT_END; @@ -1571,18 +1571,18 @@ test_channel_matches_target_addr_for_extend(void *arg) /* Test for IPv4 addresses. */ addr.family = AF_INET; TEST_SETUP_MATCHES_ADDR(orcon, addr, "1.2.3.4", rv); - TEST_MATCHES_ADDR(chan, addr, rv, 1); + TEST_MATCHES_ADDR(chan, &addr, NULL, rv, 1); tor_inet_pton(addr.family, "2.5.3.4", &addr.addr); - TEST_MATCHES_ADDR(chan, addr, rv, 0); + TEST_MATCHES_ADDR(chan, &addr, NULL, rv, 0); /* Test for IPv6 addresses. */ addr.family = AF_INET6; TEST_SETUP_MATCHES_ADDR(orcon, addr, "3:4:7:1:9:8:09:10", rv); - TEST_MATCHES_ADDR(chan, addr, rv, 1); + TEST_MATCHES_ADDR(chan, NULL, &addr, rv, 1); tor_inet_pton(addr.family, "::", &addr.addr); - TEST_MATCHES_ADDR(chan, addr, rv, 0); + TEST_MATCHES_ADDR(chan, NULL, &addr, rv, 0); done: circuitmux_clear_policy(chan->cmux);

1 0

[tor/master] Added tests
by nickm＠torproject.org 13 Jul '20

13 Jul '20

commit c84ce716dce09eb26f26e3303efa2c0a04a870b7 Author: MrSquanchee <usuraj35(a)gmail.com> Date: Tue Apr 21 18:23:42 2020 +0530 Added tests Added tests for channel_matches_target_addr_for_extend(). Ticket #33919. --- changes/ticket33919 | 3 +++ src/test/test_channel.c | 56 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+) diff --git a/changes/ticket33919 b/changes/ticket33919 new file mode 100644 index 000000000..a9991b741 --- /dev/null +++ b/changes/ticket33919 @@ -0,0 +1,3 @@ + o Minor features (testing): + - Added unit tests for channel_matches_target_addr_for_extend(). + Closes Ticket 33919. Patch by MrSquanchee. diff --git a/src/test/test_channel.c b/src/test/test_channel.c index 849cc497f..53ca8d9bb 100644 --- a/src/test/test_channel.c +++ b/src/test/test_channel.c @@ -16,6 +16,10 @@ /* For packed_cell stuff */ #define RELAY_PRIVATE #include "core/or/relay.h" +/* For channel_tls_t object and private functions. */ +#define CHANNEL_OBJECT_PRIVATE +#define CHANNELTLS_PRIVATE +#include "core/or/channeltls.h" /* For init/free stuff */ #include "core/or/scheduler.h" #include "feature/nodelist/networkstatus.h" @@ -25,6 +29,8 @@ #include "core/or/origin_circuit_st.h" #include "feature/nodelist/routerstatus_st.h" #include "core/or/var_cell_st.h" +#include "core/or/or_connection_st.h" +#include "lib/net/inaddr.h" /* Test suite stuff */ #include "test/log_test_helpers.h" @@ -1537,6 +1543,54 @@ test_channel_listener(void *arg) channel_free_all(); } +#define TEST_SETUP_MATCHES_ADDR(orcon, addr, src, rv) STMT_BEGIN \ + rv = tor_inet_pton(addr.family, src, &addr.addr); \ + tt_int_op(rv, OP_EQ, 1); \ + orcon->real_addr = addr; \ + STMT_END; + +#define TEST_MATCHES_ADDR(chan, addr, rv, exp) STMT_BEGIN \ + rv = channel_matches_target_addr_for_extend(chan, &addr); \ + tt_int_op(rv, OP_EQ, exp); \ + STMT_END; + +static void +test_channel_matches_target_addr_for_extend(void *arg) +{ + (void) arg; + + channel_tls_t *tlschan = tor_malloc_zero(sizeof(*tlschan)); + or_connection_t *orcon = tor_malloc_zero(sizeof(*orcon)); + channel_t *chan = &(tlschan->base_); + tor_addr_t addr; + int rv; + + tlschan->conn = orcon; + channel_tls_common_init(tlschan); + + /* Test for IPv4 addresses. */ + addr.family = AF_INET; + TEST_SETUP_MATCHES_ADDR(orcon, addr, "1.2.3.4", rv); + TEST_MATCHES_ADDR(chan, addr, rv, 1); + + tor_inet_pton(addr.family, "2.5.3.4", &addr.addr); + TEST_MATCHES_ADDR(chan, addr, rv, 0); + + /* Test for IPv6 addresses. */ + addr.family = AF_INET6; + TEST_SETUP_MATCHES_ADDR(orcon, addr, "3:4:7:1:9:8:09:10", rv); + TEST_MATCHES_ADDR(chan, addr, rv, 1); + + tor_inet_pton(addr.family, "::", &addr.addr); + TEST_MATCHES_ADDR(chan, addr, rv, 0); + + done: + circuitmux_clear_policy(chan->cmux); + circuitmux_free(chan->cmux); + tor_free(orcon); + tor_free(tlschan); +} + struct testcase_t channel_tests[] = { { "inbound_cell", test_channel_inbound_cell, TT_FORK, NULL, NULL }, @@ -1558,5 +1612,7 @@ struct testcase_t channel_tests[] = { NULL, NULL }, { "listener", test_channel_listener, TT_FORK, NULL, NULL }, + { "matches_target", test_channel_matches_target_addr_for_extend, TT_FORK, + NULL, NULL }, END_OF_TESTCASES };

1 0

[tor/master] Syntax highlighting in the docs
by nickm＠torproject.org 13 Jul '20

13 Jul '20

commit b119c5577678b14f320a1a5cd58d8f591cb3084d Author: Guinness <guinness(a)crans.org> Date: Mon Jul 13 11:16:51 2020 +0200 Syntax highlighting in the docs This adds the syntax highlights in the MarkDown files. Fixes #33741 --- doc/HACKING/CircuitPaddingQuickStart.md | 22 +-- doc/HACKING/CodingStandards.md | 117 ++++++++------ doc/HACKING/CodingStandardsRust.md | 262 ++++++++++++++++++-------------- doc/HACKING/Fuzzing.md | 38 +++-- doc/HACKING/GettingStarted.md | 8 +- doc/HACKING/GettingStartedRust.md | 40 +++-- doc/HACKING/HelpfulTools.md | 130 ++++++++++------ doc/HACKING/Module.md | 6 +- doc/HACKING/README.1st.md | 4 +- doc/HACKING/ReleasingTor.md | 15 +- doc/HACKING/Tracing.md | 22 ++- doc/HACKING/WritingTests.md | 148 ++++++++++-------- doc/HACKING/android/Simpleperf.md | 8 + 13 files changed, 492 insertions(+), 328 deletions(-) diff --git a/doc/HACKING/CircuitPaddingQuickStart.md b/doc/HACKING/CircuitPaddingQuickStart.md index 2780b5c6e..2b01dae07 100644 --- a/doc/HACKING/CircuitPaddingQuickStart.md +++ b/doc/HACKING/CircuitPaddingQuickStart.md @@ -18,20 +18,20 @@ The quick and dirty plan is to: ## Clone and compile tor -```bash -git clone https://git.torproject.org/tor.git -cd tor -git checkout tor-0.4.1.5 +```console +$ git clone https://git.torproject.org/tor.git +$ cd tor +$ git checkout tor-0.4.1.5 ``` Above we use the tag for tor-0.4.1.5 where the circuit padding framework was released. Note that this version of the framework is missing many features and fixes that have since been merged to origin/master. If you need the newest framework features, you should use that master instead. -```bash -sh autogen.sh -./configure -make +```console +$ sh autogen.sh +$ ./configure +$ make ``` When you run `./configure` you'll be told of missing dependencies and packages to install on debian-based distributions. Important: if you plan to run `tor` on @@ -186,9 +186,9 @@ We also have to modify `circpad_machines_init()` in `circuitpadding.c` to register our machines: ```c - /* Register machines for the APE WF defense */ - circpad_machine_client_wf_ape(origin_padding_machines); - circpad_machine_relay_wf_ape(relay_padding_machines); +/* Register machines for the APE WF defense */ +circpad_machine_client_wf_ape(origin_padding_machines); +circpad_machine_relay_wf_ape(relay_padding_machines); ``` We run `make` to get a new `tor` binary and copy it to our local TB. diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 99bc3e502..4f4b836a6 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -118,27 +118,32 @@ instance of the feature (--reverse). For example, for #30224, we wanted to know when the bridge-distribution-request feature was introduced into Tor: - $ git log -S bridge-distribution-request --reverse - commit ebab521525 - Author: Roger Dingledine <arma(a)torproject.org> - Date: Sun Nov 13 02:39:16 2016 -0500 - Add new BridgeDistribution config option +```console +$ git log -S bridge-distribution-request --reverse commit ebab521525 +Author: Roger Dingledine <arma(a)torproject.org> +Date: Sun Nov 13 02:39:16 2016 -0500 - $ git describe --contains ebab521525 - tor-0.3.2.3-alpha~15^2~4 + Add new BridgeDistribution config option + +$ git describe --contains ebab521525 +tor-0.3.2.3-alpha~15^2~4 +``` If you need to know all the Tor versions that contain a commit, use: - $ git tag --contains 9f2efd02a1 | sort -V - tor-0.2.5.16 - tor-0.2.8.17 - tor-0.2.9.14 - tor-0.2.9.15 - ... - tor-0.3.0.13 - tor-0.3.1.9 - tor-0.3.1.10 - ... + +```console +$ git tag --contains 9f2efd02a1 | sort -V +tor-0.2.5.16 +tor-0.2.8.17 +tor-0.2.9.14 +tor-0.2.9.15 +... +tor-0.3.0.13 +tor-0.3.1.9 +tor-0.3.1.10 +... +``` If at all possible, try to create the changes file in the same commit where you are making the change. Please give it a distinctive name that no other @@ -438,8 +443,10 @@ use `tor_assert_nonfatal()` in place of `tor_assert()`. If you'd like to write a conditional that incorporates a nonfatal assertion, use the `BUG()` macro, as in: - if (BUG(ptr == NULL)) - return -1; +```c +if (BUG(ptr == NULL)) + return -1; +``` ## Allocator conventions @@ -451,33 +458,39 @@ Also, a type named `abc_t` should be freed by a function named `abc_free_()`. Don't call this `abc_free_()` function directly -- instead, wrap it in a macro called `abc_free()`, using the `FREE_AND_NULL` macro: - void abc_free_(abc_t *obj); - #define abc_free(obj) FREE_AND_NULL(abc_t, abc_free_, (obj)) +```c +void abc_free_(abc_t *obj); +#define abc_free(obj) FREE_AND_NULL(abc_t, abc_free_, (obj)) +``` This macro will free the underlying `abc_t` object, and will also set the object pointer to NULL. You should define all `abc_free_()` functions to accept NULL inputs: - void - abc_free_(abc_t *obj) - { - if (!obj) - return; - tor_free(obj->name); - thing_free(obj->thing); - tor_free(obj); - } +```c +void +abc_free_(abc_t *obj) +{ + if (!obj) + return; + tor_free(obj->name); + thing_free(obj->thing); + tor_free(obj); +} +``` If you need a free function that takes a `void *` argument (for example, to use it as a function callback), define it with a name like `abc_free_void()`: - static void - abc_free_void_(void *obj) - { - abc_free_(obj); - } +```c +static void +abc_free_void_(void *obj) +{ + abc_free_(obj); +} +``` When deallocating, don't say e.g. `if (x) tor_free(x)`. The convention is to have deallocators do nothing when NULL pointer is passed. @@ -488,24 +501,28 @@ Say what functions do as a series of one or more imperative sentences, as though you were telling somebody how to be the function. In other words, DO NOT say: - /** The strtol function parses a number. - * - * nptr -- the string to parse. It can include whitespace. - * endptr -- a string pointer to hold the first thing that is not part - * of the number, if present. - * base -- the numeric base. - * returns: the resulting number. - */ - long strtol(const char *nptr, char **nptr, int base); +```c +/** The strtol function parses a number. + * + * nptr -- the string to parse. It can include whitespace. + * endptr -- a string pointer to hold the first thing that is not part + * of the number, if present. + * base -- the numeric base. + * returns: the resulting number. + */ +long strtol(const char *nptr, char **nptr, int base); +``` Instead, please DO say: - /** Parse a number in radix base from the string nptr, - * and return the result. Skip all leading whitespace. If - * endptr is not NULL, set *endptr to the first character - * after the number parsed. - **/ - long strtol(const char *nptr, char **nptr, int base); +```c +/** Parse a number in radix base from the string nptr, + * and return the result. Skip all leading whitespace. If + * endptr is not NULL, set *endptr to the first character + * after the number parsed. + **/ +long strtol(const char *nptr, char **nptr, int base); +``` Doxygen comments are the contract in our abstraction-by-contract world: if the functions that call your function rely on it doing something, then your diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md index 97026c9b7..fb2c93bbe 100644 --- a/doc/HACKING/CodingStandardsRust.md +++ b/doc/HACKING/CodingStandardsRust.md @@ -22,20 +22,26 @@ For example, in a hypothetical `tor_addition` Rust module: In `src/rust/tor_addition/addition.rs`: - pub fn get_sum(a: i32, b: i32) -> i32 { - a + b - } +```rust +pub fn get_sum(a: i32, b: i32) -> i32 { + a + b +} +``` In `src/rust/tor_addition/lib.rs`: - pub use addition::*; +```rust +pub use addition::*; +``` In `src/rust/tor_addition/ffi.rs`: - #[no_mangle] - pub extern "C" fn tor_get_sum(a: c_int, b: c_int) -> c_int { - get_sum(a, b) - } +```rust +#[no_mangle] +pub extern "C" fn tor_get_sum(a: c_int, b: c_int) -> c_int { + get_sum(a, b) +} +``` If your Rust code must call out to parts of Tor's C code, you must declare the functions you are calling in the `external` crate, located @@ -129,16 +135,18 @@ crate. Unittests SHOULD go into their own module inside the module they are testing, e.g. in `src/rust/tor_addition/addition.rs` you should put: - #[cfg(test)] - mod test { - use super::*; +```rust +#[cfg(test)] +mod test { + use super::*; - #[test] - fn addition_with_zero() { - let sum: i32 = get_sum(5i32, 0i32); - assert_eq!(sum, 5); - } +#[test] + fn addition_with_zero() { + let sum: i32 = get_sum(5i32, 0i32); + assert_eq!(sum, 5); } +} +``` ## Benchmarking @@ -151,13 +159,17 @@ benchmarks in the following manner. If you wish to benchmark some of your Rust code, you MUST put the following in the `[features]` section of your crate's `Cargo.toml`: - [features] - bench = [] +```toml +[features] +bench = [] +``` Next, in your crate's `lib.rs` you MUST put: - #[cfg(all(test, feature = "bench"))] - extern crate test; +```rust +#[cfg(all(test, feature = "bench"))] +extern crate test; +``` This ensures that the external crate `test`, which contains utilities for basic benchmarks, is only used when running benchmarks via `cargo @@ -166,16 +178,18 @@ bench --features bench`. Finally, to write your benchmark code, in `src/rust/tor_addition/addition.rs` you SHOULD put: - #[cfg(all(test, features = "bench"))] - mod bench { - use test::Bencher; - use super::*; +```rust +#[cfg(all(test, features = "bench"))] +mod bench { + use test::Bencher; + use super::*; - #[bench] - fn addition_small_integers(b: &mut Bencher) { - b.iter(| | get_sum(5i32, 0i32)); - } +#[bench] + fn addition_small_integers(b: &mut Bencher) { + b.iter(| | get_sum(5i32, 0i32)); } +} +``` ## Fuzzing @@ -247,39 +261,47 @@ Here are some additional bits of advice and rules: potential error with the eel operator, `?` or another non panicking way. For example, consider a function which parses a string into an integer: - fn parse_port_number(config_string: &str) -> u16 { - u16::from_str_radix(config_string, 10).unwrap() - } + ```rust + fn parse_port_number(config_string: &str) -> u16 { + u16::from_str_radix(config_string, 10).unwrap() + } + ``` There are numerous ways this can fail, and the `unwrap()` will cause the whole program to byte the dust! Instead, either you SHOULD use `ok()` (or another equivalent function which will return an `Option` or a `Result`) and change the return type to be compatible: - fn parse_port_number(config_string: &str) -> Option<u16> { - u16::from_str_radix(config_string, 10).ok() - } + ```rust + fn parse_port_number(config_string: &str) -> Option<u16> { + u16::from_str_radix(config_string, 10).ok() + } + ``` or you SHOULD use `or()` (or another similar method): - fn parse_port_number(config_string: &str) -> Option<u16> { - u16::from_str_radix(config_string, 10).or(Err("Couldn't parse port into a u16") - } + ```rust + fn parse_port_number(config_string: &str) -> Option<u16> { + u16::from_str_radix(config_string, 10).or(Err("Couldn't parse port into a u16") + } + ``` Using methods like `or()` can be particularly handy when you must do something afterwards with the data, for example, if we wanted to guarantee that the port is high. Combining these methods with the eel operator (`?`) makes this even easier: - fn parse_port_number(config_string: &str) -> Result<u16, Err> { - let port = u16::from_str_radix(config_string, 10).or(Err("Couldn't parse port into a u16"))?; + ```rust + fn parse_port_number(config_string: &str) -> Result<u16, Err> { + let port = u16::from_str_radix(config_string, 10).or(Err("Couldn't parse port into a u16"))?; - if port > 1024 { - return Ok(port); - } else { - return Err("Low ports not allowed"); - } + if port > 1024 { + return Ok(port); + } else { + return Err("Low ports not allowed"); } + } + ``` 2. `unsafe` @@ -292,25 +314,29 @@ Here are some additional bits of advice and rules: When creating an FFI in Rust for C code to call, it is NOT REQUIRED to declare the entire function `unsafe`. For example, rather than doing: - #[no_mangle] - pub unsafe extern "C" fn increment_and_combine_numbers(mut numbers: [u8; 4]) -> u32 { - for number in &mut numbers { - *number += 1; - } - std::mem::transmute::<[u8; 4], u32>(numbers) + ```rust + #[no_mangle] + pub unsafe extern "C" fn increment_and_combine_numbers(mut numbers: [u8; 4]) -> u32 { + for number in &mut numbers { + *number += 1; } + std::mem::transmute::<[u8; 4], u32>(numbers) + } + ``` You SHOULD instead do: - #[no_mangle] - pub extern "C" fn increment_and_combine_numbers(mut numbers: [u8; 4]) -> u32 { - for index in 0..numbers.len() { - numbers[index] += 1; - } - unsafe { - std::mem::transmute::<[u8; 4], u32>(numbers) - } + ```rust + #[no_mangle] + pub extern "C" fn increment_and_combine_numbers(mut numbers: [u8; 4]) -> u32 { + for index in 0..numbers.len() { + numbers[index] += 1; } + unsafe { + std::mem::transmute::<[u8; 4], u32>(numbers) + } + } + ``` 3. Pass only C-compatible primitive types and bytes over the boundary @@ -385,45 +411,51 @@ Here are some additional bits of advice and rules: rather than using an untyped mapping between strings and integers like so: - use std::collections::HashMap; + ```rust + use std::collections::HashMap; - pub fn get_elements_with_over_9000_points(map: &HashMap<String, usize>) -> Vec<String> { - ... - } + pub fn get_elements_with_over_9000_points(map: &HashMap<String, usize>) -> Vec<String> { + ... + } + ``` It would be safer to define a new type, such that some other usage of `HashMap<String, usize>` cannot be confused for this type: - pub struct DragonBallZPowers(pub HashMap<String, usize>); + ```rust + pub struct DragonBallZPowers(pub HashMap<String, usize>); - impl DragonBallZPowers { - pub fn over_nine_thousand<'a>(&'a self) -> Vec<&'a String> { - let mut powerful_enough: Vec<&'a String> = Vec::with_capacity(5); + impl DragonBallZPowers { + pub fn over_nine_thousand<'a>(&'a self) -> Vec<&'a String> { + let mut powerful_enough: Vec<&'a String> = Vec::with_capacity(5); - for (character, power) in &self.0 { - if *power > 9000 { - powerful_enough.push(character); - } - } - powerful_enough - } - } + for (character, power) in &self.0 { + if *power > 9000 { + powerful_enough.push(character); + } + } + powerful_enough + } + } + ``` Note the following code, which uses Rust's type aliasing, is valid but it does NOT meet the desired type safety goals: - pub type Power = usize; + ```rust + pub type Power = usize; - pub fn over_nine_thousand(power: &Power) -> bool { - if *power > 9000 { - return true; - } - false + pub fn over_nine_thousand(power: &Power) -> bool { + if *power > 9000 { + return true; } + false + } - // We can still do the following: - let his_power: usize = 9001; - over_nine_thousand(&his_power); + // We can still do the following: + let his_power: usize = 9001; + over_nine_thousand(&his_power); + ``` 7. Unsafe mucking around with lifetimes @@ -431,15 +463,17 @@ Here are some additional bits of advice and rules: family of types, individual lifetimes can be treated as types. For example, one can arbitrarily extend and shorten lifetime using `std::mem::transmute`: - struct R<'a>(&'a i32); + ```rust + struct R<'a>(&'a i32); - unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> { - std::mem::transmute::<R<'b>, R<'static>>(r) - } + unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> { + std::mem::transmute::<R<'b>, R<'static>>(r) + } - unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>) -> &'b mut R<'c> { - std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r) - } + unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>) -> &'b mut R<'c> { + std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r) + } + ``` Calling `extend_lifetime()` would cause an `R` passed into it to live forever for the life of the program (the `'static` lifetime). Similarly, @@ -460,12 +494,14 @@ Here are some additional bits of advice and rules: For example, `std::mem::transmute` can be abused in ways where casting with `as` would be both simpler and safer: - // Don't do this - let ptr = &0; - let ptr_num_transmute = unsafe { std::mem::transmute::<&i32, usize>(ptr)}; + ```rust + // Don't do this + let ptr = &0; + let ptr_num_transmute = unsafe { std::mem::transmute::<&i32, usize>(ptr)}; - // Use an `as` cast instead - let ptr_num_cast = ptr as *const i32 as usize; + // Use an `as` cast instead + let ptr_num_cast = ptr as *const i32 as usize; + ``` In fact, using `std::mem::transmute` for *any* reason is a code smell and as such SHOULD be avoided. @@ -475,8 +511,10 @@ Here are some additional bits of advice and rules: This is generally fine to do, but it has some behaviours which you should be aware of. Casting down chops off the high bits, e.g.: - let x: u32 = 4294967295; - println!("{}", x as u16); // prints 65535 + ```rust + let x: u32 = 4294967295; + println!("{}", x as u16); // prints 65535 + ``` Some cases which you MUST NOT do include: @@ -487,24 +525,28 @@ Here are some additional bits of advice and rules: * Casting between integers and floats when the thing being cast cannot fit into the type it is being casted into, e.g.: - println!("{}", 42949.0f32 as u8); // prints 197 in debug mode and 0 in release - println!("{}", 1.04E+17 as u8); // prints 0 in both modes - println!("{}", (0.0/0.0) as i64); // prints whatever the heck LLVM wants + ```rust + println!("{}", 42949.0f32 as u8); // prints 197 in debug mode and 0 in release + println!("{}", 1.04E+17 as u8); // prints 0 in both modes + println!("{}", (0.0/0.0) as i64); // prints whatever the heck LLVM wants + ``` Because this behaviour is undefined, it can even produce segfaults in safe Rust code. For example, the following program built in release mode segfaults: - #[inline(never)] - pub fn trigger_ub(sl: &[u8; 666]) -> &[u8] { - // Note that the float is out of the range of `usize`, invoking UB when casting. - let idx = 1e99999f64 as usize; - &sl[idx..] // The bound check is elided due to `idx` being of an undefined value. - } - - fn main() { - println!("{}", trigger_ub(&[1; 666])[999999]); // ~ out of bound - } + ```rust + #[inline(never)] + pub fn trigger_ub(sl: &[u8; 666]) -> &[u8] { + // Note that the float is out of the range of `usize`, invoking UB when casting. + let idx = 1e99999f64 as usize; + &sl[idx..] // The bound check is elided due to `idx` being of an undefined value. + } + + fn main() { + println!("{}", trigger_ub(&[1; 666])[999999]); // ~ out of bound + } + ``` And in debug mode panics with: diff --git a/doc/HACKING/Fuzzing.md b/doc/HACKING/Fuzzing.md index 41853a8a2..d140844be 100644 --- a/doc/HACKING/Fuzzing.md +++ b/doc/HACKING/Fuzzing.md @@ -6,7 +6,10 @@ Check out fuzzing-corpora, and set TOR_FUZZ_CORPORA to point to the place where you checked it out. To run the fuzzing test cases in a deterministic fashion, use: - make test-fuzz-corpora + +```console +$ make test-fuzz-corpora +``` This won't actually fuzz Tor! It will just run all the fuzz binaries on our existing set of testcases for the fuzzer. @@ -58,11 +61,13 @@ machine you care about, anyway. To Build: Get AFL from http://lcamtuf.coredump.cx/afl/ and unpack it - cd afl - make - cd ../tor - PATH=$PATH:../afl/ CC="../afl/afl-gcc" ./configure --enable-expensive-hardening - AFL_HARDEN=1 make clean fuzzers + ```console + $ cd afl + $ make + $ cd ../tor + $ PATH=$PATH:../afl/ CC="../afl/afl-gcc" ./configure --enable-expensive-hardening + $ AFL_HARDEN=1 make clean fuzzers + ``` To Find The ASAN Memory Limit: (64-bit only) @@ -75,10 +80,12 @@ Read afl/docs/notes_for_asan.txt for more details. Download recidivm from http://jwilk.net/software/recidivm Download the signature Check the signature - tar xvzf recidivm*.tar.gz - cd recidivm* - make - /path/to/recidivm -v src/test/fuzz/fuzz-http + ```console + $ tar xvzf recidivm*.tar.gz + $ cd recidivm* + $ make + $ /path/to/recidivm -v src/test/fuzz/fuzz-http + ``` Use the final "ok" figure as the input to -m when calling afl-fuzz (Normally, recidivm would output a figure automatically, but in some cases, the fuzzing harness will hang when the memory limit is too small.) @@ -88,9 +95,11 @@ don't care about memory limits. To Run: - mkdir -p src/test/fuzz/fuzz_http_findings - ../afl/afl-fuzz -i ${TOR_FUZZ_CORPORA}/http -o src/test/fuzz/fuzz_http_findings -m <asan-memory-limit> -- src/test/fuzz/fuzz-http +```console +$ mkdir -p src/test/fuzz/fuzz_http_findings +$ ../afl/afl-fuzz -i ${TOR_FUZZ_CORPORA}/http -o src/test/fuzz/fuzz_http_findings -m <asan-memory-limit> -- src/test/fuzz/fuzz-http +``` AFL has a multi-core mode, check the documentation for details. You might find the included fuzz-multi.sh script useful for this. @@ -109,7 +118,10 @@ valid inputs may take a second or so, particularly with the fuzzer and sanitizers enabled. To see what fuzz-http is doing with a test case, call it like this: - src/test/fuzz/fuzz-http --debug < /path/to/test.case + +```console +$ src/test/fuzz/fuzz-http --debug < /path/to/test.case +``` (Logging is disabled while fuzzing to increase fuzzing speed.) diff --git a/doc/HACKING/GettingStarted.md b/doc/HACKING/GettingStarted.md index c2ca74d96..73fcf0baf 100644 --- a/doc/HACKING/GettingStarted.md +++ b/doc/HACKING/GettingStarted.md @@ -37,13 +37,17 @@ Once you've reached this point, here's what you need to know. We keep our source under version control in Git. To get the latest version, run: - git clone https://git.torproject.org/git/tor + ```console + $ git clone https://git.torproject.org/git/tor + ``` This will give you a checkout of the master branch. If you're going to fix a bug that appears in a stable version, check out the appropriate "maint" branch, as in: - git checkout maint-0.4.3 + ```console + $ git checkout maint-0.4.3 + ``` 2. Find your way around the source. diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md index 247ea5c69..440a2ce4f 100644 --- a/doc/HACKING/GettingStartedRust.md +++ b/doc/HACKING/GettingStartedRust.md @@ -54,7 +54,9 @@ fetching dependencies from Cargo or specifying a local directory. **Fetch dependencies from Cargo** - ./configure --enable-rust --enable-cargo-online-mode +```console +$ ./configure --enable-rust --enable-cargo-online-mode +``` **Using a local dependency cache** @@ -66,13 +68,17 @@ We vendor our Rust dependencies in a separate repo using [cargo-vendor](https://github.com/alexcrichton/cargo-vendor). To use them, do: - git submodule init - git submodule update +```console +$ git submodule init +$ git submodule update +``` To specify the local directory containing the dependencies, (assuming you are in the top level of the repository) configure tor with: - TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust +```console +$ TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust +``` (Note that `TOR_RUST_DEPENDENCIES` must be the full path to the directory; it cannot be relative.) @@ -80,7 +86,9 @@ cannot be relative.) Assuming you used the above `git submodule` commands and you're in the topmost directory of the repository, this would be: - TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust +```console +$ TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust +``` ## Identifying which modules to rewrite @@ -102,10 +110,12 @@ areas of responsibility. A good first step is to build a module-level callgraph to understand how interconnected your target module is. - git clone https://git.torproject.org/user/nickm/calltool.git - cd tor - CFLAGS=0 ./configure - ../calltool/src/main.py module_callgraph +```console +$ git clone https://git.torproject.org/user/nickm/calltool.git +$ cd tor +$ CFLAGS=0 ./configure +$ ../calltool/src/main.py module_callgraph +``` The output will tell you each module name, along with a set of every module that the module calls. Modules which call fewer other modules are better targets. @@ -156,15 +166,21 @@ run on your crate. Configure Tor's build system to build with Rust enabled: - ./configure --enable-fatal-warnings --enable-rust --enable-cargo-online-mode +```console +$ ./configure --enable-fatal-warnings --enable-rust --enable-cargo-online-mode +``` Tor's test should be run by doing: - make check +```console +$ make check +``` Tor's integration tests should also pass: - make test-stem +```console +$ make test-stem +``` ## Submitting a patch diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md index 15bd15331..0ce59576f 100644 --- a/doc/HACKING/HelpfulTools.md +++ b/doc/HACKING/HelpfulTools.md @@ -43,7 +43,9 @@ Builds should show up on the web at jenkins.torproject.org and on IRC at ## Valgrind - valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor +```console +$ valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor +``` (Note that if you get a zillion openssl warnings, you will also need to pass `--undef-value-errors=no` to valgrind, or rebuild your openssl @@ -77,10 +79,12 @@ we wish to permit are also documented in the blacklist file. Lcov is a utility that generates pretty HTML reports of test code coverage. To generate such a report: - ./configure --enable-coverage - make - make coverage-html - $BROWSER ./coverage_html/index.html +```console +$ ./configure --enable-coverage +$ make +$ make coverage-html +$ $BROWSER ./coverage_html/index.html +``` This will run the tor unit test suite `./src/test/test` and generate the HTML coverage code report under the directory `./coverage_html/`. To change the @@ -93,36 +97,48 @@ investigated (as of July 2014). To quickly run all the tests distributed with Tor: - make check +```console +$ make check +``` To run the fast unit tests only: - make test +```console +$ make test +``` To selectively run just some tests (the following can be combined arbitrarily): - ./src/test/test <name_of_test> [<name of test 2>] ... - ./src/test/test <prefix_of_name_of_test>.. [<prefix_of_name_of_test2>..] ... - ./src/test/test :<name_of_excluded_test> [:<name_of_excluded_test2]... +```console +$ ./src/test/test <name_of_test> [<name of test 2>] ... +$ ./src/test/test <prefix_of_name_of_test>.. [<prefix_of_name_of_test2>..] ... +$ ./src/test/test :<name_of_excluded_test> [:<name_of_excluded_test2]... +``` To run all tests, including those based on Stem or Chutney: - make test-full +```console +$ make test-full +``` To run all tests, including those based on Stem or Chutney that require a working connection to the internet: - make test-full-online +```console +$ make test-full-online +``` ## Running gcov for unit test coverage - ./configure --enable-coverage - make - make check - # or--- make test-full ? make test-full-online? - mkdir coverage-output - ./scripts/test/coverage coverage-output +```console +$ ./configure --enable-coverage +$ make +$ make check +$ # or--- make test-full ? make test-full-online? +$ mkdir coverage-output +$ ./scripts/test/coverage coverage-output +``` (On OSX, you'll need to start with `--enable-coverage CC=clang`.) @@ -145,7 +161,9 @@ you can run `make reset-gcov` to clear the intermediary gcov output. If you have two different `coverage-output` directories, and you want to see a meaningful diff between them, you can run: - ./scripts/test/cov-diff coverage-output1 coverage-output2 | less +```console +$ ./scripts/test/cov-diff coverage-output1 coverage-output2 | less +``` In this diff, any lines that were visited at least once will have coverage "1", and line numbers are deleted. This lets you inspect what you (probably) really @@ -313,12 +331,16 @@ that you're using the emacs-specific version of `etags` (bundled under the If you're using vim or emacs, you can also use Universal Ctags to build a tag file using the syntax: - ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' . +```console +$ ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' . +``` If you're using an older version of Universal Ctags, you can use the following instead: - ctags -R --mline-regex-c='/MOCK_IMPL\([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' . +```console +ctags -R --mline-regex-c='/MOCK_IMPL\([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' . +``` A vim-compatible tag file will be generated by default. If you use emacs, add the `-e` flag to generate an emacs-compatible tag file. @@ -330,50 +352,58 @@ source code. Here's how to use it: 1. Begin every file that should be documented with - /** - * \file filename.c - * \brief Short description of the file. - */ +``` + /** + * \file filename.c + * \brief Short description of the file. + */ +``` - (Doxygen will recognize any comment beginning with /** as special.) + (Doxygen will recognize any comment beginning with /** as special.) 2. Before any function, structure, #define, or variable you want to document, add a comment of the form: - /** Describe the function's actions in imperative sentences. - * - * Use blank lines for paragraph breaks - * - and - * - hyphens - * - for - * - lists. - * - * Write argument_names in boldface. - * - * \code - * place_example_code(); - * between_code_and_endcode_commands(); - * \endcode - */ +``` +/** Describe the function's actions in imperative sentences. + * + * Use blank lines for paragraph breaks + * - and + * - hyphens + * - for + * - lists. + * + * Write argument_names in boldface. + * + * \code + * place_example_code(); + * between_code_and_endcode_commands(); + * \endcode + */ +``` 3. Make sure to escape the characters `<`, `>`, `\`, `%` and `#` as `\<`, `\>`, `\\`, `\%` and `\#`. 4. To document structure members, you can use two forms: - struct foo { - /** You can put the comment before an element; */ - int a; - int b; /**< Or use the less-than symbol to put the comment - * after the element. */ - }; +```c +struct foo { + /** You can put the comment before an element; */ + int a; + int b; /**< Or use the less-than symbol to put the comment + * after the element. */ +}; +``` 5. To generate documentation from the Tor source code, type: - $ doxygen -g +```console +$ doxygen -g +``` - to generate a file called `Doxyfile`. Edit that file and run - `doxygen` to generate the API documentation. + to generate a file called `Doxyfile`. Edit that file and run + `doxygen` to generate the API documentation. 6. See the Doxygen manual for more information; this summary just scratches the surface. diff --git a/doc/HACKING/Module.md b/doc/HACKING/Module.md index f8a9773d4..b9d3a654e 100644 --- a/doc/HACKING/Module.md +++ b/doc/HACKING/Module.md @@ -70,7 +70,7 @@ There are couples of "rules" you want to follow: base. Every entry point should have a second definition if the module is disabled. For instance: - ``` + ```c #ifdef HAVE_MODULE_DIRAUTH int sr_init(int save_to_disk); @@ -109,7 +109,9 @@ There are couples of "rules" you want to follow: * When you include headers from the module, **always** use the full module path in your statement. Example: - `#include "feature/dirauth/dirvote.h"` +```c +#include "feature/dirauth/dirvote.h"` +``` The main reason is that we do **not** add the module include path by default so it needs to be specified. But also, it helps our human brain understand diff --git a/doc/HACKING/README.1st.md b/doc/HACKING/README.1st.md index 2278a61d6..4bc3298c6 100644 --- a/doc/HACKING/README.1st.md +++ b/doc/HACKING/README.1st.md @@ -32,7 +32,9 @@ For an explanation of how to change Tor's design to work differently, look at For the latest version of the code, get a copy of git, and - git clone https://git.torproject.org/git/tor +```console +$ git clone https://git.torproject.org/git/tor +``` ## Stay in touch diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index 2464d8afb..d9b8d9d82 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -38,9 +38,9 @@ new Tor release: 3. Run checks that aren't covered above, including: - * clang scan-build. (See the script in ./scripts/test/scan_build.sh) + * `clang scan-build`. (See the script in ./scripts/test/scan_build.sh) - * make test-network and make test-network-all (with + * `make test-network` and make `test-network-all` (with --enable-fragile-hardening) * Running Tor yourself and making sure that it actually works for you. @@ -57,8 +57,7 @@ new Tor release: of them and reordering to focus on what users and funders would find interesting and understandable. - To do this, run - `./scripts/maint/sortChanges.py changes/* > changelog.in` + To do this, run `./scripts/maint/sortChanges.py changes/* > changelog.inx` to combine headings and sort the entries. Copy the changelog.in file into the ChangeLog. Run 'format_changelog.py' (see below) to clean up the line breaks. @@ -164,9 +163,11 @@ new Tor release: 1. Sign the tarball, then sign and push the git tag: - gpg -ba <the_tarball> - git tag -s tor-0.4.x.y-<status> - git push origin tag tor-0.4.x.y-<status> +```console +$ gpg -ba <the_tarball> +$ git tag -s tor-0.4.x.y-<status> +$ git push origin tag tor-0.4.x.y-<status> +``` (You must do this before you update the website: the website scripts rely on finding the version by tag.) diff --git a/doc/HACKING/Tracing.md b/doc/HACKING/Tracing.md index d898bee17..0f2196c3f 100644 --- a/doc/HACKING/Tracing.md +++ b/doc/HACKING/Tracing.md @@ -28,7 +28,7 @@ Tracing is separated in two different concepts. The tracing API and the tracing probes. The API is in `src/lib/trace/` which defines how to call tracepoints in the -tor code. Every C files should include `src/lib/trace/events.h" if they want +tor code. Every C files should include `src/lib/trace/events.h` if they want to call a tracepoint. The probes are what actually record the tracepoint data. Because they often @@ -43,7 +43,9 @@ subsystem and an event name. A trace event in tor has the following standard format: - tor_trace(subsystem, event\_name, args...) +```c +tor_trace(subsystem, event\_name, args...); +``` The `subsystem` parameter is the name of the subsytem the trace event is in. For example that could be "scheduler" or "vote" or "hs". The idea is to add @@ -57,7 +59,9 @@ The `args` can be any number of arguments we want to collect. Here is an example of a possible tracepoint in main(): - tor_trace(main, init_phase, argc) +```c +tor_trace(main, init_phase, argc); +``` The above is a tracepoint in the `main` subsystem with `init\_phase` as the event name and the `int argc` is passed to the event as one argument. @@ -80,7 +84,9 @@ Currently, we have 3 types of possible instrumentation: arguments will be passed on because we don't know their type nor the string format of the debug log. The output is standardized like this: - [debug] __FUNC__: Tracepoint <event_name> from subsystem <subsystem> hit. +``` +[debug] __FUNC__: Tracepoint <event_name> from subsystem <subsystem> hit. +``` 2. USDT @@ -125,12 +131,16 @@ They can all be used together or independently. If one of them is set, This is pretty easy. Let's say you want to add a trace event in `src/feature/rend/rendcache.c`, you first need to include this file: - #include "lib/trace/events.h" +```c +#include "trace/events.h" +``` Then, the `tor\_trace()` macro can be used with the specific format detailled before in a previous section. As an example: - tor_trace(hs, store_desc_as_client, desc, desc_id); +```c +tor_trace(hs, store_desc_as_client, desc, desc_id); +``` For `Debug` instrumentation, you have nothing else to do. diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index d21202052..01e80f3f6 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -107,7 +107,9 @@ covered or uncovered. To count new or modified uncovered lines in D2, you can run: - ./scripts/test/cov-diff ${D1} ${D2}" | grep '^+ *\#' | wc -l +```console +$ ./scripts/test/cov-diff ${D1} ${D2}" | grep '^+ *\#' | wc -l +``` ## Marking lines as unreachable by tests @@ -163,28 +165,30 @@ I use the term "unit test" and "regression tests" very sloppily here. Here's an example of a test function for a simple function in util.c: - static void - test_util_writepid(void *arg) - { - (void) arg; +```c +static void +test_util_writepid(void *arg) +{ + (void) arg; - char *contents = NULL; - const char *fname = get_fname("tmp_pid"); - unsigned long pid; - char c; + char *contents = NULL; + const char *fname = get_fname("tmp_pid"); + unsigned long pid; + char c; - write_pidfile(fname); + write_pidfile(fname); - contents = read_file_to_str(fname, 0, NULL); - tt_assert(contents); + contents = read_file_to_str(fname, 0, NULL); + tt_assert(contents); - int n = sscanf(contents, "%lu\n%c", &pid, &c); - tt_int_op(n, OP_EQ, 1); - tt_int_op(pid, OP_EQ, getpid()); + int n = sscanf(contents, "%lu\n%c", &pid, &c); + tt_int_op(n, OP_EQ, 1); + tt_int_op(pid, OP_EQ, getpid()); - done: - tor_free(contents); - } +done: + tor_free(contents); +} +``` This should look pretty familiar to you if you've read the tinytest manual. One thing to note here is that we use the testing-specific @@ -214,10 +218,12 @@ macro-protected declaration of the function in the module's header. For example, `crypto_curve25519.h` contains: - #ifdef CRYPTO_CURVE25519_PRIVATE - STATIC int curve25519_impl(uint8_t *output, const uint8_t *secret, - const uint8_t *basepoint); - #endif +```c +#ifdef CRYPTO_CURVE25519_PRIVATE +STATIC int curve25519_impl(uint8_t *output, const uint8_t *secret, + const uint8_t *basepoint); +#endif +``` The `crypto_curve25519.c` file and the `test_crypto.c` file both define `CRYPTO_CURVE25519_PRIVATE`, so they can see this declaration. @@ -231,28 +237,29 @@ the test _really tests_ the code. For example, here is a _bad_ test for the unlink() function (which is supposed to remove a file). - static void - test_unlink_badly(void *arg) - { - (void) arg; - int r; +```c +static void +test_unlink_badly(void *arg) +{ + (void) arg; + int r; - const char *fname = get_fname("tmpfile"); + const char *fname = get_fname("tmpfile"); - /* If the file isn't there, unlink returns -1 and sets ENOENT */ - r = unlink(fname); - tt_int_op(n, OP_EQ, -1); - tt_int_op(errno, OP_EQ, ENOENT); + /* If the file isn't there, unlink returns -1 and sets ENOENT */ + r = unlink(fname); + tt_int_op(n, OP_EQ, -1); + tt_int_op(errno, OP_EQ, ENOENT); - /* If the file DOES exist, unlink returns 0. */ - write_str_to_file(fname, "hello world", 0); - r = unlink(fnme); - tt_int_op(r, OP_EQ, 0); - - done: - tor_free(contents); - } + /* If the file DOES exist, unlink returns 0. */ + write_str_to_file(fname, "hello world", 0); + r = unlink(fnme); + tt_int_op(r, OP_EQ, 0); +done: + tor_free(contents); +} +``` This test might get very high coverage on unlink(). So why is it a bad test? Because it doesn't check that unlink() *actually removes the @@ -273,20 +280,25 @@ To write tests for this case, you can replace the underlying functions with testing stubs while your unit test is running. You need to declare the underlying function as 'mockable', as follows: - MOCK_DECL(returntype, functionname, (argument list)); +```c +MOCK_DECL(returntype, functionname, (argument list)); +``` and then later implement it as: - MOCK_IMPL(returntype, functionname, (argument list)) - { - /* implementation here */ - } +```c +MOCK_IMPL(returntype, functionname, (argument list)) +{ + /* implementation here */ +} +``` For example, if you had a 'connect to remote server' function, you could declare it as: - - MOCK_DECL(int, connect_to_remote, (const char *name, status_t *status)); +```c +MOCK_DECL(int, connect_to_remote, (const char *name, status_t *status)); +``` When you declare a function this way, it will be declared as normal in regular builds, but when the module is built for testing, it is declared @@ -295,11 +307,15 @@ as a function pointer initialized to the actual implementation. In your tests, if you want to override the function with a temporary replacement, you say: - MOCK(functionname, replacement_function_name); +```c +MOCK(functionname, replacement_function_name); +``` And later, you can restore the original function with: - UNMOCK(functionname); +```c +UNMOCK(functionname); +``` For more information, see the definitions of this mocking logic in `testsupport.h`. @@ -324,11 +340,13 @@ cases and failure csaes. For example, consider testing this function: - /** Remove all elements E from sl such that E==element. Preserve - * the order of any elements before E, but elements after E can be - * rearranged. - */ - void smartlist_remove(smartlist_t *sl, const void *element); +```c +/** Remove all elements E from sl such that E==element. Preserve + * the order of any elements before E, but elements after E can be + * rearranged. + */ +void smartlist_remove(smartlist_t *sl, const void *element); +``` In order to test it well, you should write tests for at least all of the following cases. (These would be black-box tests, since we're only looking @@ -355,19 +373,21 @@ When you consider edge cases, you might try: Now let's look at the implementation: - void - smartlist_remove(smartlist_t *sl, const void *element) - { - int i; - if (element == NULL) +```c +void +smartlist_remove(smartlist_t *sl, const void *element) +{ + int i; + if (element == NULL) return; - for (i=0; i < sl->num_used; i++) + for (i=0; i < sl->num_used; i++) if (sl->list[i] == element) { - sl->list[i] = sl->list[--sl->num_used]; /* swap with the end */ - i--; /* so we process the new i'th element */ - sl->list[sl->num_used] = NULL; + sl->list[i] = sl->list[--sl->num_used]; /* swap with the end */ + i--; /* so we process the new i'th element */ + sl->list[sl->num_used] = NULL; } - } +} +``` Based on the implementation, we now see three more edge cases to test: diff --git a/doc/HACKING/android/Simpleperf.md b/doc/HACKING/android/Simpleperf.md index c7e63a7c8..ed640f912 100644 --- a/doc/HACKING/android/Simpleperf.md +++ b/doc/HACKING/android/Simpleperf.md @@ -29,7 +29,9 @@ the Android Software Development Kit (SDK) and Native Development Kit 3. Install the Android Package you generated in step 1: +```bash $ adb install /path/to/your/app-fullperm-debug.apk +``` 4. Check on your device that the newly installed Orbot actually works and behaves in the way you expect it to. @@ -76,10 +78,12 @@ was spend on the call. To access binaries, `torrc` files, and other useful information on the device do the following: +```console $ adb shell (device):/ $ run-as org.torproject.android (device):/data/data/org.torproject.android $ ls app_bin app_data cache databases files lib shared_prefs +``` Descriptors, control authentication cookie, state, and other files can be found in the `app_data` directory. The `torrc` can be found in the `app_bin/` @@ -88,10 +92,14 @@ was spend on the call. - You can enable logging in Tor via the syslog (or android) log mechanism with: +```console $ adb shell (device):/ $ run-as org.torproject.android (device):/data/data/org.torproject.android $ echo -e "\nLog info syslog" >> app_bin/torrc +``` Start Tor the normal way via Orbot and collect the logs from your computer using +```console $ adb logcat +```

1 0

[community/master] Add keys folder location Fedora
by gus＠torproject.org 13 Jul '20

13 Jul '20

commit 1e6a6db50ae322c9e69240d9d48c025c0c8afd66 Author: Devices <devices(a)autistici.org> Date: Thu Jul 2 18:35:43 2020 +0000 Add keys folder location Fedora Added another operating system and its keys location. --- content/relay-operations/technical-setup/post-install/contents.lr | 1 + 1 file changed, 1 insertion(+) diff --git a/content/relay-operations/technical-setup/post-install/contents.lr b/content/relay-operations/technical-setup/post-install/contents.lr index 5105e69..f7ee53c 100644 --- a/content/relay-operations/technical-setup/post-install/contents.lr +++ b/content/relay-operations/technical-setup/post-install/contents.lr @@ -119,6 +119,7 @@ Default locations of the keys folder: * Debian/Ubuntu: `/var/lib/tor/keys` * FreeBSD: `/var/db/tor/keys` +* Fedora: `/var/lib/tor/keys` ## Subscribe to the tor-announce mailing list

1 0

[community/master] Merge branch 'patch-1'
by gus＠torproject.org 13 Jul '20

13 Jul '20

commit 131b697da073e21645a50a28685fb645093a7fcc Merge: 46365e2 1e6a6db Author: gus <gus(a)torproject.org> Date: Mon Jul 13 08:15:31 2020 -0400 Merge branch 'patch-1' content/relay-operations/technical-setup/post-install/contents.lr | 1 + 1 file changed, 1 insertion(+)

1 0

[community/master] Fix typo
by gus＠torproject.org 13 Jul '20

13 Jul '20

commit 46365e296007fabaeffbde22d2ed1211e82609db Author: Amin Shah Gilani <amin(a)gilani.me> Date: Mon Jul 13 15:21:10 2020 +0500 Fix typo --- content/onion-services/advanced/onion-location/contents.lr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/onion-services/advanced/onion-location/contents.lr b/content/onion-services/advanced/onion-location/contents.lr index 74664ab..efd5e0c 100644 --- a/content/onion-services/advanced/onion-location/contents.lr +++ b/content/onion-services/advanced/onion-location/contents.lr @@ -17,7 +17,7 @@ html: two-columns-page.html body: Onion-Location is an easy way to advertise an onion site to the users. -You can either configure a web server to show an Onion-Location Header or add an HTML meta attibute in the website. +You can either configure a web server to show an Onion-Location Header or add an HTML meta attribute in the website. For the header to be valid the following conditions need to be fulfilled:

1 0

[translation/support-portal] https://gitweb.torproject.org/translation.git/commit/?h=support-portal
by translation＠torproject.org 13 Jul '20

13 Jul '20

commit d43c820c045e3dae6b6396e6274f20bc7c0e7ff7 Author: Translation commit bot <translation(a)torproject.org> Date: Mon Jul 13 09:18:01 2020 +0000 https://gitweb.torproject.org/translation.git/commit/?h=support-portal --- contents+ka.po | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/contents+ka.po b/contents+ka.po index 13c7c567b3..a3d6c9aaa0 100644 --- a/contents+ka.po +++ b/contents+ka.po @@ -3236,7 +3236,7 @@ msgstr "რა არის Tor?" #: https//support.torproject.org/about/what-is-tor/ #: (content/about/what-is-tor/contents+en.lrquestion.description) msgid "The name \"Tor\" can refer to several different components." -msgstr "დასახელება „Tor“ შეიძლება აღნიშნავდეს რამდენიმე სხვადახვა ნაწილს." +msgstr "დასახელება „Tor“ შეიძლება აღნიშნავდეს სხვადახვა შემადგენელ ნაწილს." #: https//support.torproject.org/about/what-is-tor/ #: (content/about/what-is-tor/contents+en.lrquestion.description) @@ -11712,6 +11712,8 @@ msgid "" "On the other hand, from the viewpoint of IRC server operators, security is " "not an all-or-nothing thing." msgstr "" +"მეორე მხრივ, IRC-სერვერის მფლობელების თვალით თუ შევხედავთ, უსაფრთხოება არაა " +"გადამწყვეტი რამ." #: https//support.torproject.org/abuse/tor-ban-irc/ #: (content/abuse/irc-ban/contents+en.lrquestion.description) @@ -12033,7 +12035,7 @@ msgid "" "anonymity (identity theft, compromising computers and using them as bounce " "points, etc)." msgstr "" -"გარდა ამისა, [ცუდი ხალხის ასე გამოჭერა, მანც ვერ მოხერხდება](/abuse/what-" +"გარდა ამისა, [ცუდი ხალხის ასე გამოჭერა, მაინც ვერ მოხერხდება](/abuse/what-" "about-criminals/), ვინაიდან ისინი სხვა გზებსაც იყენებენ ვინაობის უკეთ " "დასამალად (სხვისი ვინაობის უკან ამოფარება, სხვისი კომპიუტერის გატეხა, მისი " "სატყუარად გამოყენება და სხვა)."

1 0

[translation/support-portal] https://gitweb.torproject.org/translation.git/commit/?h=support-portal
by translation＠torproject.org 13 Jul '20

13 Jul '20

commit 3e1d040fdd1f3d291807e58bed7c64b8b91b177e Author: Translation commit bot <translation(a)torproject.org> Date: Mon Jul 13 08:48:13 2020 +0000 https://gitweb.torproject.org/translation.git/commit/?h=support-portal --- contents+ka.po | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/contents+ka.po b/contents+ka.po index e0e3b83d54..13c7c567b3 100644 --- a/contents+ka.po +++ b/contents+ka.po @@ -11696,6 +11696,10 @@ msgid "" "sprung up based on this flawed security model (not unlike the antivirus " "industry)." msgstr "" +"IRC-ქსელები წაგებულ ომში არიან ჩართული, ყველა კვანძის შეზღუდვის მცდელობით და" +" სახელსახელოდ შექმნილი ტროლების საწინააღმდეგო აკრძალვების სიებით, " +"ნაკლოვანების მქონე უსაფრთხოების მოდელის გამო (მსგავსად ანტივირუსების " +"სფეროსი)." #: https//support.torproject.org/abuse/tor-ban-irc/ #: (content/abuse/irc-ban/contents+en.lrquestion.description)

1 0

[translation/support-portal] https://gitweb.torproject.org/translation.git/commit/?h=support-portal
by translation＠torproject.org 13 Jul '20

13 Jul '20

commit 348f5b1a01f99c1b5faa779390653f26fa0dcfa6 Author: Translation commit bot <translation(a)torproject.org> Date: Mon Jul 13 08:17:57 2020 +0000 https://gitweb.torproject.org/translation.git/commit/?h=support-portal --- contents+ka.po | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/contents+ka.po b/contents+ka.po index e3dbed43d6..e0e3b83d54 100644 --- a/contents+ka.po +++ b/contents+ka.po @@ -11501,6 +11501,9 @@ msgid "" " see the [collection of templates](https://community.torproject.org/relay" "/community-resources/tor-abuse-templates/)." msgstr "" +"სრულ კრებულს პასუხების ნიმუშებისას, სხვადასხვა დარღვევის საჩივრებზე, იხილავთ" +" [ამ ნაკრებში](https://community.torproject.org/relay/community-resources" +"/tor-abuse-templates/)." #: https//support.torproject.org/abuse/exit-relay-expectations/ #: (content/abuse/exit-relay-expectations/contents+en.lrquestion.description) @@ -11511,6 +11514,11 @@ msgid "" "[running a reduced exit " "policy](https://trac.torproject.org/projects/tor/wiki/doc/ReducedExitPolicy)." msgstr "" +"თქვენ, ასევე შეგიძლიათ თავიდან აიცილოთ გარკვეული დარღვევები, თუ " +"გაითვალისწინებთ [ამ რჩევებს, გამსვლელი კვანძის გაშვებისას ზიანის " +"შემცირებითა](https://blog.torproject.org/blog/tips-running-exit-node) და " +"[შეზღუდული გამსვლელი დებულების " +"გამოყენებით](https://trac.torproject.org/projects/tor/wiki/doc/ReducedExitP…." #: https//support.torproject.org/abuse/exit-relay-expectations/ #: (content/abuse/exit-relay-expectations/contents+en.lrquestion.description)

1 0

[metrics-tasks/master] Add ipv6.py script for tpo/metrics/trac#40002.
by karsten＠torproject.org 13 Jul '20

13 Jul '20

commit 2cab2b49267cb5e0f7fb8f7f89926b244a2d3acb Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Mon Jul 13 09:47:54 2020 +0200 Add ipv6.py script for tpo/metrics/trac#40002. --- tpo-metrics-trac-40002/README.md | 4 + tpo-metrics-trac-40002/ipv6.py | 173 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 177 insertions(+) diff --git a/tpo-metrics-trac-40002/README.md b/tpo-metrics-trac-40002/README.md new file mode 100644 index 0000000..e141b02 --- /dev/null +++ b/tpo-metrics-trac-40002/README.md @@ -0,0 +1,4 @@ +# Script that Counts IPv6 Relays in the Consensus + +See `ipv6.py` for usage information and [tpo/metrics/trac#40002](https://gitlab.torproject.org/tpo/metrics/trac/-/is… for context. + diff --git a/tpo-metrics-trac-40002/ipv6.py b/tpo-metrics-trac-40002/ipv6.py new file mode 100644 index 0000000..497ea26 --- /dev/null +++ b/tpo-metrics-trac-40002/ipv6.py @@ -0,0 +1,173 @@ +#!/usr/bin/env python3 + +""" +---------------------------------------------------------------------------- + +This script implements Section 3 of Proposal 313: + +3. Monitoring IPv6 Relays in the Consensus + +We propose writing a script that calculates: + * the number of relays, and + * the consensus weight fraction of relays, +in the consensus that: + * have an IPv6 ORPort, + * support IPv6 reachability checks, + * support IPv6 clients, and + * support IPv6 reachability checks, and IPv6 clients. + +In order to provide easy access to these statistics, we propose +that the script should: + * download a consensus (or read an existing consensus), and + * calculate and report these statistics. + +The following consensus weight fractions should divide by the total +consensus weight: + * have an IPv6 ORPort (all relays have an IPv4 ORPort), and + * support IPv6 reachability checks (all relays support IPv4 reachability). + +The following consensus weight fractions should divide by the +"usable Guard" consensus weight: + * support IPv6 clients, and + * support IPv6 reachability checks and IPv6 clients. + +"Usable Guards" have the Guard flag, but do not have the Exit flag. If the +Guard also has the BadExit flag, the Exit flag should be ignored. + +Note that this definition of "Usable Guards" is only valid when the +consensus contains many more guards than exits. That is, Wgd must be 0 in +the consensus. (See the [Tor Directory Protocol] for more details.) + +Therefore, the script should check that Wgd is 0. If it is not, the script +should log a warning about the accuracy of the "Usable Guard" statistics. + +---------------------------------------------------------------------------- + +Copyright 2020 The Tor Project + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following disclaimer + in the documentation and/or other materials provided with the + distribution. + +* Neither the names of the copyright owners nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +---------------------------------------------------------------------------- +""" + +import sys, stem, stem.version, stem.descriptor + +partial_support_version = stem.version.Version('0.4.4') +full_support_version = stem.version.Version('0.4.5') + +def read(consensus_filename): + + parsed_consensus = stem.descriptor.parse_file(consensus_filename, + descriptor_type = 'network-status-consensus-3 1.0') + + valid_after = None + wgd = None + + relays = [] + relays_ipv6 = [] + relays_partial = [] + relays_full = [] + guards = [] + guards_ipv6 = [] + guards_partial = [] + guards_full = [] + + for relay in parsed_consensus: + + if not valid_after: + valid_after = relay.document.valid_after + wgd = relay.document.bandwidth_weights["Wgd"] + + if relay.bandwidth is None: + continue + + has_ipv6_address = False + if relay.or_addresses: + for or_address in relay.or_addresses: + if len(or_address) == 3 and or_address[2]: + has_ipv6_address = True + is_usable_guard = False + if relay.flags: + if "Guard" in relay.flags and ( + "Exit" not in relay.flags or "BadExit" in relay.flags): + is_usable_guard = True + has_partial_support = False + has_full_support = False + if relay.version: + if relay.version >= full_support_version: + has_full_support = True + if relay.version >= partial_support_version: + has_partial_support = True + + relays.append(relay.bandwidth) + if has_ipv6_address: + relays_ipv6.append(relay.bandwidth) + if has_partial_support: + relays_partial.append(relay.bandwidth) + if has_full_support: + relays_full.append(relay.bandwidth) + if is_usable_guard: + guards.append(relay.bandwidth) + if has_ipv6_address: + guards_ipv6.append(relay.bandwidth) + if has_partial_support: + guards_partial.append(relay.bandwidth) + if has_full_support: + guards_full.append(relay.bandwidth) + + print("\nParsed consensus with valid-after time {0}:".format(valid_after)) + print(" - Consensus contains {0} relays:".format(len(relays))) + print(" - {0} of these ({1:.2f}% TCW) have an IPv6 ORPort.". + format(len(relays_ipv6), 100 * sum(relays_ipv6) / sum(relays))) + print(" - {0} of these ({1:.2f}% TCW) support at least partial IPv6 reachability checks.". + format(len(relays_partial), 100 * sum(relays_partial) / sum(relays))) + print(" - {0} of these ({1:.2f}% TCW) support full IPv6 reachability checks.". + format(len(relays_full), 100 * sum(relays_full) / sum(relays))) + print(" - Consensus contains {0} \"usable guards\" and Wgd={1}.". + format(len(guards), wgd)) + print(" - {0} of these ({1:.2f}% UGCW) support IPv6 clients.". + format(len(guards_ipv6), 100 * sum(guards_ipv6) / sum(guards))) + print(" - {0} of these ({1:.2f}% UGCW) support at least partial IPv6 reachability checks.". + format(len(guards_partial), 100 * sum(guards_partial) / sum(guards))) + print(" - {0} of these ({1:.2f}% UGCW) support full IPv6 reachability checks.". + format(len(guards_full), 100 * sum(guards_full) / sum(guards))) + if wgd != 0: + print(" - WARNING: \"usable guards\" definition is only valid when Wgd=0!") + +def main(): + if len(sys.argv) < 2: + print("Please provide one or more downloaded consensus files as arguments.") + else: + for argv in sorted(sys.argv[1:]): + read(argv) + print() + +if __name__ == '__main__': + sys.exit(main()) +

1 0