README.md
1This crate aims to provide a complete implementation of OpenPGP as
2defined by [RFC 4880] as well as some extensions (e.g., [RFC
36637], which describes ECC cryptography for OpenPGP. This
4includes support for unbuffered message processing.
5
6A few features that the OpenPGP community considers to be
7deprecated (e.g., version 3 compatibility) have been left out. We
8have also updated some OpenPGP defaults to avoid foot guns (e.g.,
9we selected modern algorithm defaults). If some functionality is
10missing, please file a bug report.
11
12A non-goal of this crate is support for any sort of high-level,
13bolted-on functionality. For instance, [RFC 4880] does not define
14trust models, such as the web of trust, direct trust, or TOFU.
15Neither does this crate. [RFC 4880] does provide some mechanisms
16for creating trust models (specifically, UserID certifications),
17and this crate does expose those mechanisms.
18
19We also try hard to avoid dictating how OpenPGP should be used.
20This doesn't mean that we don't have opinions about how OpenPGP
21should be used in a number of common scenarios (for instance,
22message validation). But, in this crate, we refrain from
23expressing those opinions; we will expose an opinionated, high-level
24interface in the future.
25
26[RFC 4880]: https://tools.ietf.org/html/rfc4880
27[RFC 6637]: https://tools.ietf.org/html/rfc6637
28
29# Experimental Features
30
31This crate implements functionality from [RFC 4880bis], notably
32AEAD encryption containers. As of this writing, this RFC is still
33a draft and the syntax or semantic defined in it may change or go
34away. Therefore, all related functionality may change and
35artifacts created using this functionality may not be usable in
36the future. Do not use it for things other than experiments.
37
38[RFC 4880bis]: https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-08
39
40This crate aims to provide a complete implementation of OpenPGP as
41defined by RFC 4880 as well as several extensions (e.g., RFC 6637,
42which describes ECC cryptography for OpenPGP, and RFC 4880bis, the
43draft of the next OpenPGP standard). This includes support for
44unbuffered message processing.
45
46# Feature flags
47
48This crate uses *features* to enable or disable optional
49functionality. You can tweak the features in your `Cargo.toml` file,
50like so:
51
52```toml
53sequoia-openpgp = { version = "*", default-features = false, features = ["crypto-nettle", ...] }
54```
55
56By default, Sequoia is built using Nettle as cryptographic backend
57with all compression algorithms enabled.
58
59Note that if you use `default-features = false`, you need to
60explicitly enable a crypto backend.
61
62## Crypto backends
63
64Sequoia supports multiple cryptographic libraries that can be selected
65at compile time. Currently, these libraries are available:
66
67 - The Nettle cryptographic library. This is the default backend,
68 and is selected by the default feature set. If you use
69 `default-features = false`, you need to explicitly include
70 the `crypto-nettle` feature to enable it.
71
72 - The Windows Cryptography API: Next Generation (CNG). To select
73 this backend, use `default-features = false`, and explicitly
74 include the `crypto-cng` feature to enable it. Currently, the CNG
75 backend requires at least Windows 10.
76
77## Compression algorithms
78
79Use the `compression` flag to enable support for all compression
80algorithms, `compression-deflate` to enable *DEFLATE* and *zlib*
81compression support, and `compression-bzip2` to enable *bzip2*
82support.
83
84## Testing, debugging, and fuzzing
85
86Sequoia uses [`quickcheck`] in tests. To use it as a downstream user,
87enable the `x-quickcheck` feature (this feature will be called just
88`quickcheck` once [this feature] is implemented).
89
90[`quickcheck`]: https://docs.rs/quickcheck
91[this feature]: https://github.com/rust-lang/cargo/issues/5565
92
93# Minimum Supported Rust Version (MSRV)
94
95`sequoia-openpgp` requires Rust 1.34.
96