initial commit

Author: ad-anssi

.gitignore

@@ -0,0 +1 @@
+book/

LICENCE.md

@@ -0,0 +1,76 @@
+# OPEN LICENCE 2.0/LICENCE OUVERTE 2.0
+
+## “Reuse” of the “Information” covered by this licence
+
+The “Grantor” grants the “Reuser” the free, non-exclusive right to “Reuse” the “Information” subject of this licence, for commercial or non-commercial purposes, worldwide and for an unlimited period, in accordance with the conditions stated below.
+
+**The “Reuser” is free to reuse the “Information”:**
+
+-   To reproduce it, copy it.
+-   To adapt, modify, retrieve and transform it in order to create “derived information”, products and services.
+-   To share, disseminate, redistribute, publish and transmit it.
+-   To exploit it for commercial purposes, e.g., by combining it with other information, or by including it in his/her own product or application.
+
+**Subject to:**
+
+-   An acknowledgement of the authorship of the “Information”: its source (at least, the name of the “Grantor”) and the date of the most recent update of the reused “Information”. Specifically, the “Reuser” may satisfy this condition by pointing, via a hypertext link, to the source of “the Information” and so supplying an actual acknowledgement of its authorship.
+
+**For example:**
+
+> “Ministry of xxx—Original data downloaded from `http://www.data.gouv.fr/fr/datasets/xxx/`, updated on 14 February 2017”.
+
+This acknowledgement of authorship does not confer any official status on the “Reuse” of the “Information”, and must not suggest any sort of recognition or endorsement on the part of the “Grantor”, or any other public entity, of the “Reuser” or of their “Reuse”.
+
+## Personal data
+
+The “Information” made available may contain “Personal data” that may be subject to “Reuse”. If this is the case, the “Grantor” informs the “Reuser” about its existence. The “Information” may be freely reused, within the rights granted by this licence, subject to compliance with the legal framework relating to personal data protection.
+
+## Intellectual property rights
+
+It is guaranteed to The “Reuser” that potential “Intellectual property rights” held by third parties or by the “Grantor” on “Information” do not interfere with the rights granted by this licence.
+
+When the “Grantor” holds transferable “Intellectual property rights” on the “Information”, he/she assigns these to the “Reuser” on a non-exclusive basis, free of charge, worldwide, for the entire duration of the “Intellectual property rights”, and the “Reuser” is free to use the “Information” for any purpose that complies with the rights and conditions defined in this licence.
+
+## Liability
+
+The “Information” is made available as it is produced or received by the “Grantor”, without any other express or tacit guarantee than those set out in this licence. The “Grantor” does not guarantee the absence of errors or inaccuracies in the “Information”, nor a continuous supply of the “Information”. He/she cannot be held responsible for any loss, prejudice or damage of any kind caused to third parties as a result of the “Reuse”.
+
+The “Reuser” is solely responsible for the “Reuse” of the “Information”. This “Reuse” must not mislead third parties as to the contents of the “Information”, its source or its date of update.
+
+## Applicable legislation
+
+This licence is governed by French law.
+
+### Compatibility of this licence
+
+This licence has been designed to be compatible with any free licence that at least requires an acknowledgement of authorship, and specifically with the previous version of this licence as well as with the following licences: United Kingdom’s “Open Government Licence” (OGL), Creative Commons’ “Creative Commons Attribution” (CC-BY) and Open Knowledge Foundation’s “Open Data Commons Attribution” (ODC-BY).
+
+## Definitions
+
+Within the meaning of this licence, are to be considered as :
+
+-   The “Grantor”: any person granting the right to “Reuse” “Information” under the rights and conditions set out in this licence.
+-   The “Information”:
+    -   any public information contained in documents disclosed or published by any administration referred to in the first paragraph of Article L. 300-2 of the code des relations entre le public et l’administration (CRPA),
+    -   any information made available by any person under the terms and conditions of this licence.
+-   The “Reuse”: the use of the “Information” for other purposes than those for which it was produced or received.
+-   The“Reuser”: any person reusing the “Information” in accordance with the conditions of this licence.
+-   “Personal data”: any information relating to an identified or identifiable natural person who may be identified directly or indirectly. Its “Reuse” is conditional on the respect of the existing legal framework.
+-   “Derived information”: any new data or information created directly from the “Information” or from a combination of the “Information” and other data or information not subject to this licence.
+-   “Intellectual property rights”: all rights identified as such under the code de la propriété intellectuelle (including copyright, rights related to copyright, sui generis rights of database producers, etc.).
+
+## About this licence
+
+This licence is intended to be used by administrations for the reuse of their public information. It can also be used by any individual wishing to supply “Information” under the conditions defined in this licence.
+
+France has a comprehensive legal framework aiming at the spontaneous dissemination by the administrations of their public information in order to ensure the widest possible reuse of this information.
+
+The right to “Reuse” the administrations’ “Information” is governed by the code des relations entre le public et l’administration  (CRPA).
+
+This licence facilitates the unrestricted and free of charge reuse of public information and is one of the licences which can be used by the administration pursuant to the decree issued under article L. 323-2 of the CRPA.
+
+Under the Prime Minister’s authority, the Etalab mission is mandated to open up the maximum amount of data held by State administrations and public institutions. Etalab has drawn up the Open Licence to facilitate the unrestricted and free of charge reuse of public information, as defined by article L. 321-1 of the CRPA.
+
+This licence is version 2.0 of the Open Licence.
+
+Etalab reserves the right to propose new versions of the Open Licence. Nevertheless, “Reusers” may continue to reuse information obtained under this licence should they so wish.

README.md

@@ -0,0 +1,49 @@
+# Guide to develop secure applications with Rust
+
+## Objectives
+
+The object of this document is to provide hints and recommendations for secure
+applications development using the Rust programming language.
+
+It is not intended to be a course on how to write Rust programs, there are
+already plenty of good learning resources for this purpose (see the *External
+references* section below). The purpose is rather to guide the programmer and to
+inform him about certain pitfalls, especially in case he is involved in the
+development of applications with strong security requirements.  These
+recommendations form a complement to the good level of trust the Rust language
+already provides. That said, recalls are sometimes necessary for clarity, and
+the experienced Rust programmer may rely solely on *Recommendation* or *Warning*
+inserts.
+
+It is currently an ongoing version and all contributions are welcome.
+
+## Reading the guide online
+
+[Summary](./src/SUMMARY.md)
+
+## Building the guide
+
+```
+$ cargo install mdbook
+$ mdbook serve -o
+```
+
+## Contributions
+
+Feel free to create pull requests to suggest recommendations or modifications,
+or to submit an issue to start discussions.
+
+## Licence
+
+This document is published under the [Open Licence 2.0](LICENCE.md).
+
+## External references
+
+- [The Rust programming language](https://www.rust-lang.org)
+- [The Rust book](https://doc.rust-lang.org/stable/book)
+- [About Rust editions](https://rust-lang-nursery.github.io/edition-guide)
+- [Rust API guidelines](https://rust-lang-nursery.github.io/api-guidelines)
+
+One can also find an up-to-date list of various book resources about Rust and
+associated tools in the [Rust documentation main
+page](https://doc.rust-lang.org).

src/01_introduction.md

@@ -0,0 +1,63 @@
+# Introduction
+
+[Rust](https://www.rust-lang.org) is a multi-paradigm language with a focus on
+memory safety.
+
+It aims to be systems programming oriented, allowing fine-grained memory
+management without garbage collection but also without tedious and error-prone
+manual memory allocations and deallocations. It achieves this goal by means of
+its ownership system (mostly related to variable aliasing). At any point of a
+Rust program, the compiler tracks how many variables refer to a given data, and
+enforces a set of rules which enable automatic memory management, memory safety
+and data-race free programs.
+
+The language also focuses on performance, with powerful compilation
+optimizations and language constructs that allows writing zero-cost abstraction
+code.
+
+Moreover, the Rust language provides some high-level programming features.
+Thanks to higher-order functions, closures, iterators, etc., it allows writing
+program parts in the same vein as in functional programming languages.
+Besides, static typing discipline, type inference, and ad hoc polymorphism (in
+the form of traits) are other ways Rust provides to build libraries and programs
+in a safe manner.
+
+Nevertheless, due to its versatility, the language possibly offers some
+constructions that, if not used properly, can introduce security problems,
+either by or by making code misinterpreted by the programmer or a reviewer. In
+addition, as for every tool in the compilation or software verification field,
+the tools used to develop, compile and execute programs can expose certain
+features or configurations that, if misused, may lead to vulnerabilities.
+
+Thus, the object of this document is to compile hints and recommendations to
+stay in a safe zone for secure applications development while taking advantage
+of the range of possibilities Rust language can offer.
+
+## Target Audience
+
+The guide intents to group recommendations that should be applied for
+application development with strong security level requirements. Anyway, it can
+be followed by everyone who wants to ensure that guarantees offered by the Rust
+platform are not invalidated due to unsafe, misleading or unclear feature usage.
+
+It is not intended to be a course on how to write Rust programs, there are
+already plenty of good learning resources for this purpose
+(see for instance the
+[Rust documentation main page](https://doc.rust-lang.org)).
+The purpose is rather to guide the programmer and to inform him about certain
+pitfalls. These recommendations form a complement to the good level of trust
+the Rust language already provides. That said, recalls are sometimes necessary
+for clarity, and the experienced Rust programmer may rely solely on
+*Recommendation* or *Warning* inserts.
+
+## Structure of the Document
+
+The aim with the structure of this document is to consider separately different
+phases of a typical (and simplified) development process. Firstly, we provide
+some advices for using tools of the Rust ecosystem to how to take advantage
+of them for secure development. A second chapter focuses on precautions to
+take when choosing and using external libraries. Then, recommendations about
+the Rust language constructs are exposed. Finally, we introduce advices for
+writing tests for a project in Rust, and for using Rust fuzzing tools.
+A summary of recommendations presented throughout the document is listed at the
+end of this guide.

src/02_devenv.md

@@ -0,0 +1,121 @@
+# Development Environment
+
+## `rustup`
+
+`rustup` is the Rust toolchain installer. Among other things, it enables
+switching between different flavors of the toolchain (stable, beta, nightly),
+managing additional components installation and keeping them up to date.
+
+> ### Warning:
+> From a security perspective, `rustup` does perform all downloads over HTTPS,
+> but doesn’t validate signatures of downloads. Protection against downgrade
+> attacks, certificate pinning, validation of signatures are works that are
+> currently in progress. In some cases, it may be preferable to opt for
+> an alternative installation method listed in the *Install* section of the
+> official rust website.
+
+### Rust Editions
+
+Several flavors, called *editions*, of the Rust language coexist.
+The concept of editions has been introduced to clarify new features
+implementation and to make them incremental. But as stated in the
+[Edition Guide](https://rust-lang-nursery.github.io/edition-guide/editions/index.html),
+this doesn’t mean that new features and improvements will be shipped on
+the last edition only.
+
+However, some editions could bring new keywords and language constructs.
+Recommendations for secure applications development then remain closely
+linked to features that are used in such applications rather than the actual
+edition that is declared in it.
+In the rest of this guide, best effort will be made to highlight constructions
+and language features that are specific to a particular Rust edition.
+
+> ### Note:
+> No specific edition is recommended, as long as users follow recommendations
+> that are expressed in relation to features offered by edition that has been
+> chosen.
+
+### Stable, nightly and beta toolchains
+
+Orthogonally to editions that allows one to select a flavor (a set of features)
+of the Rust language, the Rust toolchain is provided in three different
+versions, called *release channels*:
+
+- *nightly* releases are created once a day,
+- *nightly* releases are promoted every six weeks to *beta* releases,
+- *beta* releases are promoted every six weeks to *stable* releases.
+
+When playing with different toolchains, it is important to check not only what
+the default toolchain is, but also if overrides are currently set for some
+directories.
+
+```shell
+$ pwd
+/tmp/foo
+$ rustup toolchain list
+stable-x86_64-unknown-linux-gnu (default)
+beta-x86_64-unknown-linux-gnu
+nightly-x86_64-unknown-linux-gnu
+$ rustup override list
+/tmp/foo                                	nightly-x86_64-unknown-linux-gnu
+$
+```
+
+> ### Recommendation:
+> In general, development of a secure application should be done using a
+> fully stable toolchain, for limiting potential compiler, runtime or tool
+> bugs.
+
+When using a specific cargo subcommand that requires a nightly component,
+it is preferable to run it by switching the toolchain only locally, instead
+of explicitly switching the complete toolchain. For example, to run the
+(nightly) latest `rustfmt`:
+
+```shell
+$ rustup toolchain list
+stable-x86_64-unknown-linux-gnu (default)
+beta-x86_64-unknown-linux-gnu
+nightly-x86_64-unknown-linux-gnu
+$ rustup run nightly cargo fmt
+$ # or
+$ cargo +nightly fmt
+$
+```
+
+## `cargo`
+
+Once `rustup` has been used to set up the appropriate Rust toolchain, the
+tool `cargo` has been made available. It’s the Rust package manager, that
+provides ways to structure and build projects, managing on its own dependencies
+download among other tasks. It’s also a front-end to run complementary tools such
+as those that are described below, in the form of sub-commands.
+
+<mark>TODO</mark>: identify unsafe features and risky environment variables.
+
+### clippy
+
+Clippy is a tool that provides and checks many lints (bugs, styling, performance
+issues, etc.). Since the stable toolchain has reached version 1.29, `clippy` can
+be used within the stable rustup environment. It is also recommended
+to install `clippy` as a component (`rustup component add clippy`) in the
+stable toolchain instead of installing it as a project dependency.
+
+The tool comes with some lint categories regarding the kind of issue it aims to
+detect. The warnings should be re-checked by the programmer before committing
+the fix that is suggested by `clippy`, especially in the case of lints of the
+category `clippy::nursery` since those hints are still under development.
+
+> ### Recommendation:
+> The tool `clippy` must be used at various times during a secure application
+> development process.
+
+### rustfmt
+
+<mark>TODO</mark>: introduce the rustfmt tool and recommend its use.
+
+### Others
+
+There exist other useful tools or cargo subcommands for enforcing program
+security whether by searching for specific code patterns or by providing
+convenient commands for testing or fuzzing. They are discussed in the following
+chapters, according to their goals.

src/03_libraries.md

@@ -0,0 +1,34 @@
+# Libraries
+
+In addition to a standard library, Rust provides an easy way to import libraries
+in a project, thanks to `cargo`. The libraries, known as *crates* in the Rust
+ecosystem, are imported from the open-source components central repository
+[crates.io](https://crates.io).
+
+It should be noticed that the quality (in terms of security, performances,
+readability, etc.) of the published crates is very variable. Moreover, their
+maintenance can be irregular or interrupted. The usage of each component from
+this repository should be justified, and the developer should validate the
+correct application of rules from the current guide in its code. Several tools
+can aid in that task.
+
+## cargo-outdated
+
+Cargo-outdated tool allows one to easily manage dependencies versions.
+
+For a given crate, it lists current dependencies versions (using its
+`Cargo.toml`), and checks latest compatible version and also latest general
+version.
+
+> ### Recommendation:
+> <mark>TODO</mark>: run cargo-outdated to check dependencies status
+
+## Unsafe code in libraries
+
+<mark>TODO</mark>: `unsafe` blocks are discussed in the following chapter.
+One needs to ensure that this kind of block is not misused in project
+dependencies.
+
+> ### Recommendation:
+> <mark>TODO</mark>: check that no `unsafe` blocks appear in the imported
+> dependencies (with a tool?).