remove example about safe/unsafe trust relation

Author: hg-anssi

examples/src/generalities.rs

@@ -30,53 +30,3 @@ impl<T> Vec<T> {
     }
 }
 // ANCHOR_END: make_room
-
-// ANCHOR: Locatable
-trait Locatable {
-    /// Find object of type `Self` in the buffer `buf`.
-    /// Returns the index of the first byte representing
-    /// an object of type `Self`
-    fn locate_instance_into(buf: &[u8]) -> Option<usize>;
-
-    fn find(buf: &[u8]) -> Option<Self>
-    where
-        Self: Sized,
-    {
-        let start = Self::locate_instance_into(buf)?;
-        unsafe {
-            let ptr: *const Self = buf.as_ptr().add(start).cast();
-            Some(ptr.read_unaligned())
-        }
-    }
-}
-// ANCHOR_END: Locatable
-#[cfg(feature = "OK")]
-mod ok {
-    use super::*;
-    // ANCHOR: Locatable_bool_OK
-    impl Locatable for bool {
-        fn locate_instance_into(buf: &[u8]) -> Option<usize> {
-            buf.iter().position(|u| *u == 0 || *u == 1)
-        }
-    }
-    // ANCHOR_END: Locatable_bool_OK
-}
-#[cfg(feature = "KO")]
-mod bad {
-    use super::*;
-    // ANCHOR: Locatable_bool_KO
-    impl Locatable for bool {
-        fn locate_instance_into(buf: &[u8]) -> Option<usize> {
-            buf.iter().position(|u| *u == 0 || *u == 1).map(|n| n + 100)
-        }
-    }
-    // ANCHOR_END: Locatable_bool_KO
-
-    // ANCHOR: Locatable_UB
-    fn use_locatable() {
-        let buf = [4, 1, 99];
-        let located_bool: Option<bool> = bool::find(&buf); // UB here!
-        println!("{:?}", located_bool)
-    }
-    // ANCHOR_END: Locatable_UB
-}

src/en/unsafe/generalities.md

@@ -119,7 +119,7 @@ without an `unsafe` block must be marked as `unsafe` if it breaks these
 invariants. The choice and knowledge of these invariants are therefore crucial
 for secure development.
 
-### Example 1: Preserving a type invariant
+## Example: Preserving a type invariant
 
 The following code comes from the [Rustonomicon](https://doc.rust-lang.org/nomicon/working-with-unsafe.html).
 It could be used to implement a custom `Vec` type.
@@ -137,91 +137,3 @@ This invariant can be broken with *safe* code. For instance
 ```
 
 This function may be necessary for internal use, but it should not be exposed in the API, or it should be marked with the `unsafe` keyword, because its use can lead to UB.
-
-### Example 2: Trust relationship between *safe* and *unsafe*
-
-In the Rust paradigm:
-
-> `unsafe`-free code cannot go wrong
-
-which means it cannot result in UB.
-This property is lost when developers use *unsafe* code, so they are responsible for not producing UB in any scenario.
-Consequently, even *safe* functions must be handled carefully in *unsafe* contexts.
-
-Suppose one wants to propose an API to find an object of a given type in memory.
-This API could require implementing the following trait:
-
-```rust bad
-{{#include ../../../examples/src/generalities.rs:Locatable}}
-```
-
-This trait can be implemented **without** using `unsafe`.
-
-For instance, the `bool` type can implement this trait as follows:
-
-```rust,ignore align
-{{#include ../../../examples/src/generalities.rs:Locatable_bool_OK}}
-```
-
-<div class="warning">
-
-The `Locatable`'s API is harmful for two reasons:
-
-* If the `Locatable` implementation does not give the index of an object of type `T`, the `read_unaligned` may produce UB.
-* If the `Locatable` implementation gives an out-of-bounds index or an index for which part of the object is out of bounds, the subsequent buffer overflow is UB.
-
-</div>
-
-For instance, the following `Locatable` implementation is incorrect, **but** it is the responsibility of the API author to take it into account.
-
-```rust align bad
-{{#include ../../../examples/src/generalities.rs:Locatable_bool_KO}}
-```
-
-The following program produces UB.
-
-```rust,ignore align ub
-{{#include ../../../examples/src/generalities.rs:Locatable_UB}}
-```
-
-The UB-detecting tool `miri` reports the following:
-
-```default
-$ cargo +nightly miri r --bin overflow
-    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
-     Running `/home/user/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/bin/cargo-miri runner target/miri/x86_64-unknown-linux-gnu/debug/overflow`
-error: Undefined Behavior: in-bounds pointer arithmetic failed: attempting to offset pointer by 101 bytes, but got alloc249 which is only 3 bytes from the end of the allocation
-  --> src/overflow.rs:16:29
-   |
-16 |         let ptr: *const T = buf.as_ptr().add(start).cast();
-   |                             ^^^^^^^^^^^^^^^^^^^^^^^ Undefined Behavior occurred here
-   |
-   = help: this indicates a bug in the program: it performed an invalid operation, and caused Undefined Behavior
-   = help: see https://doc.rust-lang.org/nightly/reference/behavior-considered-undefined.html for further information
-help: alloc249 was allocated here:
-  --> src/overflow.rs:22:9
-   |
-22 |     let buf = [4, 1, 99];
-   |         ^^^
-   = note: BACKTRACE (of the first span):
-   = note: inside `find::<bool>` at src/overflow.rs:16:29: 16:52
-note: inside `main`
-  --> src/overflow.rs:23:38
-   |
-23 |     let located_bool: Option<bool> = find(&buf); // UB here!
-   |                                      ^^^^^^^^^^
-
-note: some details are omitted, run with `MIRIFLAGS=-Zmiri-backtrace=full` for a verbose backtrace
-
-error: aborting due to 1 previous error
-```
-
-This example shows that developers using `unsafe` blocks
-cannot assume that *safe* functions or traits they use are well implemented, and thus must prevent UB in case these *safe* functions have bad behavior.
-
-If they cannot protect their function against poorly implemented *safe* functions or traits, they have two options:
-
-* Mark the function they *write* as `unsafe`: thus, it is the user's responsibility to provide correct arguments (by checking the `unsafe` function's documentation).
-* Mark the traits they *use* as `unsafe`: thus, it is the user's responsibility to implement the trait properly (again, by reading the trait documentation).
-
-More examples can be found in [@rust-book] (in the [Unsafe Rust](https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html) chapter) or the [nomicon](https://doc.rust-lang.org/nomicon/safe-unsafe-meaning.html).

src/fr/unsafe/generalities.md

@@ -133,7 +133,7 @@ tout code `unsafe` DOIT être encapsulé de manière :
 
 Ainsi, une fonction utilisant des opérations `unsafe` peut-être sûre (et donc sans marque `unsafe`) si les opérations `unsafe` ne présentent pas d'*UB* étant donnés les invariants du composant (typiquement l'invariant de type pour une méthode). Inversement, une fonction sans bloc `unsafe` doit être marquée `unsafe` si elle casse ces invariants. Le choix et la connaissance de ces invariants sont donc cruciaux pour le développement sécurisé.
 
-### Exemple 1 : préservation d'un invariant de type
+## Exemple : préservation d'un invariant de type
 
 La protection des invariants d'une bibliothèque est primordiale pour se prémunir de
 bugs en général, d'*UB* en particulier.
@@ -158,98 +158,3 @@ Or, il est possible de casser cet invariant avec du code *safe*. Par exemple, co
 Si elle peut être tout à fait légitime pour du code *interne* à l'API,
 cette méthode ne doit pas être exposée par l'API ou alors doit être annotée
 par `unsafe` car elle peut conduire à des *UB* (même si elle ne comporte pas de blocs *unsafe*s).
-
-### Exemple 2 : relation de confiance *safe*/*unsafe*
-
-La relation de confiance entre le code *safe* et le code `unsafe` est délicate.
-Dans un composant logiciel, le code `unsafe` doit être écrit de manière à ce qu'aucun usage *safe* du composant ne puisse conduire à des *UB*.
-
-Le cas suivant illustre ce principe.
-On souhaite ici proposer une API générique permettant de localiser un objet dans une zone mémoire.
-On demande donc à l'utilisateur de l'API de fournir une implémentation à ce trait :
-
-```rust,ignore bad
-{{#include ../../../examples/src/generalities.rs:Locatable}}
-```
-
-L'implémentation d'un tel trait peut être réalisée en utilisant du code **sans** `unsafe`.
-
-Par exemple, on peut implémenter ce trait pour le type `bool` comme suit :
-
-```rust,ignore align
-{{#include ../../../examples/src/generalities.rs:Locatable_bool_OK}}
-```
-
-<div class="warning">
-
-L'API du trait `Locatable` est mauvaise pour deux raisons :
-
-* si l'implémentation de `Locatable` ne donne pas l'index d'un objet de type `T`, alors la fonction `read_unaligned` peut produire un *UB*.
-* si l'implémentation de `Locatable` renvoie un index en dehors du tableau ou un index tel que l'objet de type `T` ne soit pas entièrement contenu dans le tableau, alors un dépassement de tableau se produit.
-
-</div>
-
-Par exemple, cette implémentation de `Locatable` est fautive alors qu'elle n'est pas `unsafe` :
-
-```rust,ignore align bad
-{{#include ../../../examples/src/generalities.rs:Locatable_bool_KO}}
-```
-
-L'exécution du programme suivant produit un *UB* :
-
-```rust,ignore align ub
-{{#include ../../../examples/src/generalities.rs:Locatable_UB}}
-```
-
-Voici le retour obtenu avec l'outil de détection de comportement indéfini `miri` :
-
-```default
-$ cargo +nightly miri r --bin overflow
-    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
-     Running `/home/user/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/bin/cargo-miri runner target/miri/x86_64-unknown-linux-gnu/debug/overflow`
-error: Undefined Behavior: in-bounds pointer arithmetic failed: attempting to offset pointer by 101 bytes, but got alloc249 which is only 3 bytes from the end of the allocation
-  --> src/overflow.rs:16:29
-   |
-16 |         let ptr: *const T = buf.as_ptr().add(start).cast();
-   |                             ^^^^^^^^^^^^^^^^^^^^^^^ Undefined Behavior occurred here
-   |
-   = help: this indicates a bug in the program: it performed an invalid operation, and caused Undefined Behavior
-   = help: see https://doc.rust-lang.org/nightly/reference/behavior-considered-undefined.html for further information
-help: alloc249 was allocated here:
-  --> src/overflow.rs:22:9
-   |
-22 |     let buf = [4, 1, 99];
-   |         ^^^
-   = note: BACKTRACE (of the first span):
-   = note: inside `find::<bool>` at src/overflow.rs:16:29: 16:52
-note: inside `main`
-  --> src/overflow.rs:23:38
-   |
-23 |     let located_bool: Option<bool> = find(&buf); // UB here!
-   |                                      ^^^^^^^^^^
-
-note: some details are omitted, run with `MIRIFLAGS=-Zmiri-backtrace=full` for a verbose backtrace
-
-error: aborting due to 1 previous error
-```
-
-Dans cet exemple, il est rappelé que la responsabilité de l'exécution *safe*
-(sans *UB*) d'un code Rust incombe à la personne utilisant des blocs *unsafe*.
-
-S'il n'est pas possible de se protéger contre les fonctions/traits *safe*s lors de l'écriture d'une fonction contenant un bloc *unsafe*, deux solutions sont possibles :
-
-* marquer la fonction comme *unsafe* : ainsi la responsabilité de sa bonne exécution revient à la personne utilisant cette fonction, notamment en l'obligeant à vérifier dans la documentation de la fonction que les arguments fournis répondent bien à la   spécification de la fonction
-* marquer le trait dont dépend la fonction comme *unsafe* : ainsi, de même, la responsabilité de la bonne exécution du programme revient à l'implémenteur du trait en s'assurant que l'implémentation répond bien aux spécifications du trait (présente dans sa documentation).
-
-On pourra se référer à [@rust-book] (au chapitre [Unsafe Rust](https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html)) où au [nomicon](https://doc.rust-lang.org/nomicon/safe-unsafe-meaning.html) pour d'autres exemples.
-
-<!--
-Dans ce cas particulier, la solution la plus adaptée est sans doute de marquer le trait `Locatable` comme `unsafe` :
-
-```rust
-{{#include ../../../examples/unsafe2/src/fix.rs::14}}
-```
-
-Le supertrait `Copy` permet de s'assurer que le type peut être copié par une simple lecture mémoire.
-Une alternative serait de l'ajouter aux conditions de sûreté du trait.
--->