merge central traits into standard

Author: hg-anssi

src/en/SUMMARY.md

@@ -15,7 +15,6 @@
 - [Integer operations](integer.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)

src/en/central_traits.md

@@ -1,3 +1,11 @@
+---
+references:
+  - type: web
+    title: Specialization
+    url: https://github.com/rust-lang/rfcs/blob/master/text/1210-impl-specialization.md
+    id: RFC-1210
+---
+
 # Standard library
 
 ## `Send` and `Sync` traits
@@ -242,3 +250,80 @@ and lexicographical comparison is needed. Any manual implementation of
 standard comparison traits SHOULD be documented and justified.
 
 </div>
+
+## `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.
+
+<div class="note">
+
+Implementing this trait changes the execution semantics of the language.
+Indeed, unlike the classical behavior of traits [^1], the execution of the same 
+code will differ depending on whether this trait is implemented or not.
+
+[^1]: Except for the use of negative trait bounds, which is allowed for example
+by [@RFC-1210], but is not yet implemented for the current version of Rust (1.91.0).
+
+</div>
+
+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.
+
+<div class="reco" id="LANG-DROP" type="Rule" title="Justify `Drop` implementation">
+
+In a Rust secure development, the implementation of the `std::ops::Drop` trait
+MUST be justified and documented.
+
+</div>
+
+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](unsafe/memory.md#forget-and-memory-leaks)),
+- a panic during 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 availability issues.
+
+<div class="reco" id="LANG-DROP-NO-PANIC" type="Rule" title="Do not panic in `Drop` implementation">
+
+In a Rust secure development, the implementation of the `std::ops::Drop` trait
+MUST not panic.
+
+</div>
+
+Beside panics, secure-critical drop should be protected.
+
+<div class="reco" id="LANG-DROP-NO-CYCLE" type="Rule" title="Do not allow cycles of reference-counted `Drop`">
+
+A value whose type implements `Drop` MUST NOT be embedded directly or indirectly
+in a cycle of reference-counted references.
+
+</div>
+
+<div class="reco" id="LANG-DROP-SEC" type="Rule" title="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) MUST NOT rely only on the `Drop`
+trait implementation.
+
+</div>

src/en/standard.md

@@ -15,7 +15,6 @@
 - [Gestion des entiers](integer.md)
 - [Gestion des erreurs](errors.md)
 <!-- - [Système de types](typesystem.md) -->
-- [Traits centraux](central_traits.md)
 - [Unsafe Rust](unsafe.md)
   - [Généralités](unsafe/generalities.md)
   - [Gestion de la mémoire](unsafe/memory.md)

src/fr/SUMMARY.md

@@ -1,3 +1,11 @@
+---
+references:
+  - type: web
+    title: Specialization
+    url: https://github.com/rust-lang/rfcs/blob/master/text/1210-impl-specialization.md
+    id: RFC-1210
+---
+
 # Bibliothèque standard
 
 ## Les traits `Send` et `Sync`
@@ -260,3 +268,85 @@ sont nécessaires. Toute implémentation manuelle d'un trait de comparaison
 standard DEVRAIT être justifiée et documentée.
 
 </div>
+
+## Trait `Drop` : le destructeur
+
+Les types implémentent le trait `std::ops::Drop` dans le but d'effectuer
+certaines opérations lorsque la mémoire associée à une valeur est réclamée.
+`Drop` est l'équivalent Rust d'un destructeur en C++ ou un finaliseur en Java.
+
+<div class="note">
+
+Implémenter ce traits modifie la sémantique d'exécution du langage. En effet,
+contrairement au fonctionnement classique des traits [^1], l'exécution d'un même code
+se verra différente avec et sans cette implémentation.
+
+[^1]: excepté l'usage de contraintes négatives de type, permis par exemple par la [@RFC-1210],
+pas encore implémentée pour la version actuelle de Rust (1.91.0)
+
+</div>
+
+`Drop` agit récursivement, depuis la valeur externe vers les valeurs imbriquées.
+Lorsqu'une valeur sort du scope (ou est explicitement relâchée avec
+`std::mem::drop`), elle est relâchée en deux étapes. La première étape a lieu
+uniquement si le type de la valeur en question implémente le trait `Drop` et
+consiste en l'appel de la méthode `drop`. La seconde étape consiste en la
+répétition de processus de *drop* récursivement sur tous les champs que contient
+la valeur. Il est à noter que l'implémentation de `Drop` est
+*responsable uniquement de la valeur extérieure*.
+
+Tout d'abord, l'implémentation de `Drop` ne doit pas être systématique. Elle est
+nécessaire uniquement lorsque le type requiert un traitement logique à la
+destruction. `Drop` est typiquement utilisé dans le cas du relâchement des
+ressources externes (connexions réseau, fichier, etc.) ou de ressources mémoire
+complexes (*smart pointers* comme les `Box` ou les `Rc` par exemple). Au
+final, il est probable que l'implémentation du trait `Drop` contienne des blocs
+`unsafe` ainsi que d'autres opérations critiques du point de vue de la sécurité.
+
+<div class="reco" id="LANG-DROP" type="Règle" title="Justification de l'implémentation du trait `Drop`">
+
+Dans un développement sécurisé en Rust, l'implémentation du trait
+`std::ops::Drop` DOIT être justifiée et documentée.
+
+</div>
+
+Ensuite, le système de types de Rust assure seulement la sûreté mémoire et,
+du point de vue du typage, des `drop`s peuvent tout à fait être manqués.
+Plusieurs situations peuvent mener à manquer des `drop`s, comme :
+
+- un cycle dans la référence (par exemple avec `Rc` ou `Arc`) ;
+- un appel explicite à `std::mem::forget` (ou `core::mem::forget`) (voir
+  paragraphe à propos de [`forget` et des fuites de mémoire](unsafe/memory.md#forget-and-memory-leaks)) ;
+- un `panic` dans un `drop` ;
+- un arrêt du programme (et un `panic` lorsque `abort-on-panic` est activé).
+
+Les `drop`s manqués peuvent mener à l'exposition de données sensibles ou bien
+encore à l'épuisement de ressources limitées et par là même à des problèmes
+d'indisponibilité.
+
+<div class="reco" id="LANG-DROP-NO-PANIC" type="Règle" title="Absence de `panic` dans l'implémentation de `Drop`">
+
+Dans un développement sécurisé en Rust, l'implémentation du trait
+`std::ops::Drop` NE DOIT PAS causer de `panic`.
+
+</div>
+
+En plus des `panic`s, les `drop`s contenant du code critique doivent être
+protégés.
+
+<div class="reco" id="LANG-DROP-NO-CYCLE" type="Règle" title="Absence de cycles de références avec valeurs `Drop`ables">
+
+Les valeurs dont le type implémente `Drop` NE DOIVENT PAS être incluses,
+directement ou indirectement, dans un cycle de références à compteurs.
+
+</div>
+
+<!-- -->
+
+<div class="reco" id="LANG-DROP-SEC" type="Règle" title="Sécurité assurée par d'autres mécanismes en plus du trait `Drop`">
+
+Certaines opérations liées à la sécurité d'une application à la fin d'un
+traitement (comme l'effacement de secrets cryptographiques par exemple) NE DOIVENT PAS
+reposer uniquement sur l'implémentation du trait `Drop`.
+
+</div>