openpgp: Mark experimental features.

  - Fixes #446.

10 files changed, 41 insertions, 1 deletions

diff --git a/openpgp/src/lib.rs b/openpgp/src/lib.rs
index e61f3742..47518a11 100644
--- a/openpgp/src/lib.rs
+++ b/openpgp/src/lib.rs
@@ -30,9 +30,19 @@
 //!
 //! [RFC 4880]: https://tools.ietf.org/html/rfc4880
 //! [RFC 6637]: https://tools.ietf.org/html/rfc6637
-//! [RFC 4880bis]: https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-05
 //! [unhashed signature subpackets]: https://tools.ietf.org/html/rfc4880#section-5.2.3.2
 //! [sequoia-core]: ../sequoia_core
+//!
+//! # Experimental Features
+//!
+//! This crate implements functionality from [RFC 4880bis], notable
+//! AEAD encryption containers.  As of this writing, this RFC is still
+//! a draft and the syntax or semantic defined in it may change or go
+//! away.  Therefore, all related functionality may change and
+//! artifacts created using this functionality may not be usable in
+//! the future.  Do not use it for things other than experiments.
+//!
+//! [RFC 4880bis]: https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-08
 
 #![warn(missing_docs)]
 
diff --git a/openpgp/src/packet/aed.rs b/openpgp/src/packet/aed.rs
index 40e3124d..8af94f00 100644
--- a/openpgp/src/packet/aed.rs
+++ b/openpgp/src/packet/aed.rs
@@ -15,6 +15,8 @@ use crate::Result;
 /// of RFC 4880bis] for details.
 ///
 /// [Section 5.16 of RFC 4880bis]: https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-05#section-5.16
+///
+/// This feature is [experimental](../../index.html#experimental-features).
 #[derive(Clone, Debug)]
 pub struct AED1 {
     /// CTB packet header fields.
diff --git a/openpgp/src/packet/mod.rs b/openpgp/src/packet/mod.rs
index 2bf6c102..9f24cf01 100644
--- a/openpgp/src/packet/mod.rs
+++ b/openpgp/src/packet/mod.rs
@@ -485,6 +485,8 @@ pub enum SKESK {
     /// SKESK packet version 4.
     V4(self::skesk::SKESK4),
     /// SKESK packet version 5.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     V5(self::skesk::SKESK5),
 
     /// This marks this enum as non-exhaustive.  Do not use this
@@ -779,6 +781,8 @@ impl DerefMut for SEIP {
 ///
 /// Note: This enum cannot be exhaustively matched to allow future
 /// extensions.
+///
+/// This feature is [experimental](../index.html#experimental-features).
 #[derive(PartialEq, Eq, Hash, Clone, Debug)]
 pub enum AED {
     /// AED packet version 1.
diff --git a/openpgp/src/packet/skesk.rs b/openpgp/src/packet/skesk.rs
index ae7b3554..dfe9844e 100644
--- a/openpgp/src/packet/skesk.rs
+++ b/openpgp/src/packet/skesk.rs
@@ -245,6 +245,8 @@ impl Arbitrary for SKESK4 {
 /// 4880bis] for details.
 ///
 /// [Section 5.3 of RFC 4880]: https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-05#section-5.3
+///
+/// This feature is [experimental](../../index.html#experimental-features).
 #[derive(PartialEq, Eq, Hash, Clone, Debug)]
 pub struct SKESK5 {
     /// Common fields.
diff --git a/openpgp/src/packet/tag.rs b/openpgp/src/packet/tag.rs
index 17ce2293..38d4e5b5 100644
--- a/openpgp/src/packet/tag.rs
+++ b/openpgp/src/packet/tag.rs
@@ -48,6 +48,8 @@ pub enum Tag {
     /// Modification Detection Code Packet.
     MDC,
     /// AEAD Encrypted Data Packet.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     AED,
     /// Unassigned packets (as of RFC4880).
     Unknown(u8),
diff --git a/openpgp/src/parse/stream.rs b/openpgp/src/parse/stream.rs
index f02bb241..4b057a22 100644
--- a/openpgp/src/parse/stream.rs
+++ b/openpgp/src/parse/stream.rs
@@ -266,6 +266,8 @@ pub enum MessageLayer<'a> {
         /// Symmetric algorithm used.
         sym_algo: SymmetricAlgorithm,
         /// AEAD algorithm used, if any.
+        ///
+        /// This feature is [experimental](../../index.html#experimental-features).
         aead_algo: Option<AEADAlgorithm>,
     },
     /// Represents a signature group.
diff --git a/openpgp/src/policy.rs b/openpgp/src/policy.rs
index 79e2da79..7e16273c 100644
--- a/openpgp/src/policy.rs
+++ b/openpgp/src/policy.rs
@@ -121,6 +121,8 @@ pub trait Policy : fmt::Debug {
     ///
     /// With this function, you can prevent the use of insecure AEAD
     /// constructions.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     fn aead_algorithm(&self, _algo: AEADAlgorithm) -> Result<()> {
         Ok(())
     }
@@ -632,11 +634,15 @@ impl<'a> StandardPolicy<'a> {
     }
 
     /// Always considers `s` to be secure.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     pub fn accept_aead_algo(&mut self, a: AEADAlgorithm) {
         self.aead_algos.set(a, ACCEPT);
     }
 
     /// Always considers `s` to be insecure.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     pub fn reject_aead_algo(&mut self, a: AEADAlgorithm) {
         self.aead_algos.set(a, REJECT);
     }
@@ -647,6 +653,8 @@ impl<'a> StandardPolicy<'a> {
     /// algorithm has no known vulnerabilities.
     ///
     /// By default, we accept all AEAD modes.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     pub fn reject_aead_algo_at<C>(&mut self, a: AEADAlgorithm,
                                        cutoff: C)
         where C: Into<Option<SystemTime>>,
@@ -657,6 +665,8 @@ impl<'a> StandardPolicy<'a> {
     }
 
     /// Returns the cutoff times for the specified hash algorithm.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     pub fn aead_algo_cutoff(&self, a: AEADAlgorithm)
                                  -> Option<SystemTime> {
         self.aead_algos.cutoff(a).map(|t| t.into())
diff --git a/openpgp/src/serialize/stream.rs b/openpgp/src/serialize/stream.rs
index c0f6828e..92bce274 100644
--- a/openpgp/src/serialize/stream.rs
+++ b/openpgp/src/serialize/stream.rs
@@ -1113,6 +1113,8 @@ impl<'a> Encryptor<'a> {
     }
 
     /// Enables AEAD and sets the AEAD algorithm to use.
+    ///
+    /// This feature is [experimental](../../index.html#experimental-features).
     pub fn aead_algo(mut self, algo: AEADAlgorithm) -> Self {
         self.aead_algo = Some(algo);
         self
diff --git a/openpgp/src/types/features.rs b/openpgp/src/types/features.rs
index c17c9676..a1baefcf 100644
--- a/openpgp/src/types/features.rs
+++ b/openpgp/src/types/features.rs
@@ -142,11 +142,15 @@ impl Features {
     }
 
     /// Whether or not AEAD is supported.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     pub fn supports_aead(&self) -> bool {
         self.aead
     }
 
     /// Sets whether or not AEAD is supported.
+    ///
+    /// This feature is [experimental](../index.html#experimental-features).
     pub fn set_aead(mut self, v: bool) -> Self {
         self.aead = v;
         self
diff --git a/openpgp/src/types/mod.rs b/openpgp/src/types/mod.rs
index 1e6b31c3..6f9422cc 100644
--- a/openpgp/src/types/mod.rs
+++ b/openpgp/src/types/mod.rs
@@ -521,6 +521,8 @@ impl Arbitrary for SymmetricAlgorithm {
 /// symbolic one.
 ///
 ///   [`AEADAlgorithm::from`]: https://doc.rust-lang.org/std/convert/trait.From.html
+///
+/// This feature is [experimental](../index.html#experimental-features).
 #[derive(Clone, Copy, Hash, PartialEq, Eq, Debug, PartialOrd, Ord)]
 pub enum AEADAlgorithm {
     /// EAX mode.