openpgp: Do not recommend padding by default.

  - We discovered compatibility problems with the padding mechanism,
    so we should caution against its use when compatibility with
    certain implementations is required.  Also, don't use padding in
    the module's example.

2 files changed, 6 insertions, 8 deletions

diff --git a/openpgp/src/serialize/stream.rs b/openpgp/src/serialize/stream.rs
index 249b8101..6c9906f2 100644
--- a/openpgp/src/serialize/stream.rs
+++ b/openpgp/src/serialize/stream.rs
@@ -75,9 +75,7 @@
 //!
 //! This example demonstrates how to create the most common OpenPGP
 //! message structure (see [Section 11.3 of RFC 4880]).  The plaintext
-//! is first signed, then compressed, encrypted, and finally ASCII
-//! armored.  Our example pads the plaintext instead of compressing
-//! it, but the resulting message structure is the same.
+//! is first signed, then encrypted, and finally ASCII armored.
 //!
 //! ```
 //! # fn main() -> sequoia_openpgp::Result<()> {
@@ -87,7 +85,6 @@
 //! use openpgp::cert::prelude::*;
 //! use openpgp::serialize::stream::{
 //!     Message, Armorer, Encryptor, Signer, LiteralWriter,
-//!     padding::Padder,
 //! };
 //! # use openpgp::parse::Parse;
 //!
@@ -114,7 +111,6 @@
 //! let message = Armorer::new(message).build()?;
 //! let message = Encryptor::for_recipients(message, recipients).build()?;
 //! // Reduce metadata leakage by concealing the message size.
-//! let message = Padder::new(message).build()?;
 //! let message = Signer::new(message, signing_keypair)
 //!     // Prevent Surreptitious Forwarding.
 //!     .add_intended_recipient(&recipient)
diff --git a/openpgp/src/serialize/stream/padding.rs b/openpgp/src/serialize/stream/padding.rs
index da96c6e7..247ac5cc 100644
--- a/openpgp/src/serialize/stream/padding.rs
+++ b/openpgp/src/serialize/stream/padding.rs
@@ -41,10 +41,12 @@
 //! transparent for the recipient (for example, no weird packets are
 //! inserted).
 //!
-//! Cursory [testing] (RNP, DKGPG, PGPy, OpenKeychain, GnuPG classic
-//! and modern) revealed no problems.
+//! Unfortunately, [testing] discovered problems when the resulting
+//! messages are consumed by (at the time of this writing) OpenPGP.js,
+//! RNP, and GnuPG.  If compatibility with these implementations is a
+//! concern, using this padding method is not advisable.
 //!
-//!   [testing]: https://tests.sequoia-pgp.org/#Encrypt-Decrypt_roundtrip_with_key__Bob___AES256
+//!   [testing]: https://tests.sequoia-pgp.org/#Packet_excess_consumption
 //!
 //! To be effective, the padding layer must be placed inside the
 //! encryption container.  To increase compatibility, the padding