Work/secure erase

src/en/SUMMARY.md

@@ -1,15 +1,31 @@
 # Summary
 
-- [Introduction](01_introduction.md)
-- [Development environment](02_devenv.md)
-- [Libraries](03_libraries.md)
-- [Language generalities](04_language.md)
-- [Type system](05_typesystem.md)
-- [Unsafe Rust](06_unsafe.md)
-  - [Generalities](06_1_unsafe_generalities.md)
-  - [Memory management](06_2_unsafe_memory.md)
-  - [Foreign Function Interface](06_3_unsafe_ffi.md)
+[Introduction](introduction.md)
+
+# Lifecycle
+
+- [Development environment](devenv.md)
+- [Libraries](libraries.md)
+
+# Language
+
+- [Language guarantees](guarantees.md)
+- [Naming](naming.md)
+<!-- - [Macros](macros.md) -->
+- [Integer operations](integer.md)
+- [Secure erasure](erasure.md)
+- [Error handling](errors.md)
+<!-- - [Type system](typesystem.md) -->
+- [Central traits](central_traits.md)
+- [Unsafe Rust](unsafe.md)
+  - [Generalities](unsafe/generalities.md)
+  - [Memory management](unsafe/memory.md)
+  - [Foreign Function Interface](unsafe/ffi.md)
+
+# Ecosystem
+
+- [Standard library](standard.md)
 
 [Licence](LICENCE.md)
 
-<!-- TODO - [Test and fuzzing](08_testfuzz.md) -->
+<!-- TODO - [Test and fuzzing](testfuzz.md) -->

src/en/central_traits.md

@@ -0,0 +1,59 @@
+# Central traits
+
+## `Drop` trait, the destructor
+
+Types implement the trait `std::ops::Drop` to perform some operations when the
+memory associated with a value of this type is to be reclaimed. `Drop` is the
+Rust equivalent of a destructor in C++ or a finalizer in Java.
+
+Dropping is done recursively from the outer value to the inner values.
+When a value goes out of scope (or is explicitly dropped with `std::mem::drop`),
+the value is dropped in two steps. The first step happens only if the type of
+this value implements `Drop`. It consists in calling the `drop` method on it.
+The second step consists in repeating the dropping process recursively on any
+field the value contains. Note that a `Drop` implementation is
+**only responsible for the outer value**.
+
+First and foremost, implementing `Drop` should not be systematic.
+It is only needed if the type requires some destructor logic. In fact, `Drop` is
+typically used to release external resources (network connections, files, etc.)
+or to release memory (e.g. in smart pointers such as `Box` or `Rc`).
+As a result, `Drop` trait implementations are likely to contain `unsafe` code
+blocks as well as other security-critical operations.
+
+> **Recommendation {{#check LANG-DROP | Justify `Drop` implementation}}**
+>
+> In a Rust secure development, the implementation of the `std::ops::Drop` trait
+> should be justified, documented and peer-reviewed.
+
+Second, Rust type system only ensures memory safety and, from the type system's
+standpoint, missing drops is allowed. In fact, several things may lead to
+missing drops, such as:
+
+- a reference cycle (for instance, with `Rc` or `Arc`),
+- an explicit call to `std::mem::forget` (or `core::mem::forget`) (see paragraph
+  on [Forget and memory leaks](05_memory.html#forget-and-memory-leaks),
+- a panic in drop,
+- program aborts (and panics when abort-on-panic is on).
+
+
+And missing drops may lead to exposing sensitive data or to lock limited
+resources leading to unavailability issues.
+
+> **Rule {{#check LANG-DROP-NO-PANIC | Do not panic in `Drop` implementation}}**
+>
+> In a Rust secure development, the implementation of the `std::ops::Drop` trait
+> must not panic.
+
+Beside panics, secure-critical drop should be protected.
+
+> **Rule {{#check LANG-DROP-NO-CYCLE | Do not allow cycles of reference-counted `Drop`}}**
+>
+> Value whose type implements `Drop` must not be embedded directly or indirectly
+> in a cycle of reference-counted references.
+
+> **Recommendation {{#check LANG-DROP-SEC | Do not rely only on `Drop` to ensure security}}**
+>
+> Ensuring security operations at the end of some treatment (such as key erasure
+> at the end of a cryptographic encryption) should not rely only on the `Drop`
+> trait implementation.

src/en/erasure.md

@@ -0,0 +1,32 @@
+# Secure erasure
+
+Zeroing memory is useful for sensitive variables, especially if the
+Rust code is used through FFI.
+
+> **Rule {{#check MEM-ZERO | Zero out memory of sensitive data after use}}**
+>
+> Variables containing sensitive data must be zeroed out after use, using
+> functions that will not be removed by the compiler optimizations, like
+> `std::ptr::write_volatile` or the `zeroize` crate.
+
+The following code shows how to define an integer type that will be set to
+0 when freed, using the `Drop` trait:
+
+```rust
+/// Example: u32 newtype, set to 0 when freed
+pub struct ZU32(pub u32);
+
+impl Drop for ZU32 {
+    fn drop(&mut self) {
+        println!("zeroing memory");
+        unsafe{ ::std::ptr::write_volatile(&mut self.0, 0) };
+    }
+}
+
+# fn main() {
+{
+    let i = ZU32(42);
+    // ...
+} // i is freed here
+# }
+```