signature: remove long-winded intro section in rustdoc (#2392)

Much of this is out-of-date (signature types are no longer bag-of-bytes,
for example), and probably not generally helpful for understanding the
litany of traits available in this crate.

It might make sense to add back a similar section but it should probably
be written from scratch given the current state of the crate.

Author: tarcieri

signature/src/lib.rs

@@ -10,115 +10,28 @@
 
 //! # Design
 //!
-//! This crate provides a common set of traits for signing and verifying
-//! digital signatures intended to be implemented by libraries which produce
-//! or contain implementations of digital signature algorithms, and used by
-//! libraries which want to produce or verify digital signatures while
-//! generically supporting any compatible backend.
-//!
-//! ## Goals
-//!
-//! The traits provided by this crate were designed with the following goals
-//! in mind:
-//!
-//! - Provide an easy-to-use, misuse resistant API optimized for consumers
-//!   (as opposed to implementers) of its traits.
-//! - Support common type-safe wrappers around "bag-of-bytes" representations
-//!   which can be directly parsed from or written to the "wire".
-//! - Expose a trait/object-safe API where signers/verifiers spanning multiple
-//!   homogeneous provider implementations can be seamlessly leveraged together
-//!   in the same logical "keyring" so long as they operate on the same
-//!   underlying signature type.
-//! - Allow one provider type to potentially implement support (including
-//!   being generic over) several signature types.
-//! - Keep signature algorithm customizations / "knobs" out-of-band from the
-//!   signing/verification APIs, ideally pushing such concerns into the type
-//!   system so that algorithm mismatches are caught as type errors.
-//! - Opaque error type which minimizes information leaked from cryptographic
-//!   failures, as "rich" error types in these scenarios are often a source
-//!   of sidechannel information for attackers (e.g. [BB'06])
-//!
-//! [BB'06]: https://en.wikipedia.org/wiki/Daniel_Bleichenbacher
-//!
-//! ## Implementation
-//!
-//! To accomplish the above goals, the [`Signer`] and [`Verifier`] traits
-//! provided by this are generic over a signature value, and use generic
-//! parameters rather than associated types. Notably, they use such a parameter
-//! for the return value, allowing it to be inferred by the type checker based
-//! on the desired signature type.
-//!
-//! ## Alternatives considered
-//!
-//! This crate is based on many years of exploration of how to encapsulate
-//! digital signature systems in the most flexible, developer-friendly way.
-//! During that time many design alternatives were explored, tradeoffs
-//! compared, and ultimately the provided API was selected.
-//!
-//! The tradeoffs made in this API have all been to improve simplicity,
-//! ergonomics, type safety, and flexibility for *consumers* of the traits.
-//! At times, this has come at a cost to implementers. Below are some concerns
-//! we are cognizant of which were considered in the design of the API:
-//!
-//! - "Bag-of-bytes" serialization precludes signature providers from using
-//!   their own internal representation of a signature, which can be helpful
-//!   for many reasons (e.g. advanced signature system features like batch
-//!   verification).
-//! - Associated types, rather than generic parameters of traits, could allow
-//!   more customization of the types used by a particular signature system,
-//!   e.g. using custom error types.
-//!
-//! It may still make sense to continue to explore the above tradeoffs, but
-//! with a *new* set of traits which are intended to be implementor-friendly,
-//! rather than consumer friendly. The existing [`Signer`] and [`Verifier`]
-//! traits could have blanket impls for the "provider-friendly" traits.
-//! However, as noted above this is a design space easily explored after
-//! stabilizing the consumer-oriented traits, and thus we consider these
-//! more important.
-//!
-//! That said, below are some caveats of trying to design such traits, and
-//! why we haven't actively pursued them:
-//!
-//! - Generics in the return position are already used to select which trait
-//!   impl to use, i.e. for a particular signature algorithm/system. Avoiding
-//!   a unified, concrete signature type adds another dimension to complexity
-//!   and compiler errors, and in our experience makes them unsuitable for this
-//!   sort of API. We believe such an API is the natural one for signature
-//!   systems, reflecting the natural way they are written absent a trait.
-//! - Associated types preclude multiple implementations of the same trait.
-//!   These parameters are common in signature systems, notably ones which
-//!   support different serializations of a signature (e.g. raw vs ASN.1).
-//! - Digital signatures are almost always larger than the present 32-entry
-//!   trait impl limitation on array types, which complicates bounds
-//!   for these types (particularly things like `From` or `Borrow` bounds).
+//! This crate provides a common set of traits for signing and verifying digital signatures intended
+//! to be implemented by libraries which produce or contain implementations of digital signature
+//! algorithms, and used by libraries which want to produce or verify digital signatures
+//! generically.
 //!
 //! ## Unstable features
 //!
-//! Despite being post-1.0, this crate includes off-by-default unstable
-//! optional features, each of which depends on a pre-1.0
-//! crate.
+//! Despite being post-1.0, this crate includes off-by-default unstable optional features, each of
+//! which depends on a pre-1.0 crate.
 //!
-//! These features are considered exempt from SemVer. See the
-//! [SemVer policy](#semver-policy) above for more information.
+//! These features are considered exempt from SemVer. See "SemVer Policy Exemptions" for more
+//! information.
 //!
 //! The following unstable features are presently supported:
 //!
-//! - `digest`: enables the [`DigestSigner`] and [`DigestVerifier`]
-//!   traits which are based on the [`Digest`] trait from the [`digest`] crate.
-//!   These traits are used for representing signature systems based on the
-//!   [Fiat-Shamir heuristic] which compute a random challenge value to sign
-//!   by computing a cryptographically secure digest of the input message.
-//! - `rand_core`: enables the [`RandomizedSigner`] trait for signature
-//!   systems which rely on a cryptographically secure random number generator
-//!   for security.
-//!
-//! NOTE: the [`async-signature`] crate contains experimental `async` support
-//! for [`Signer`] and [`DigestSigner`].
+//! - `digest`: enables the [`DigestSigner`] and [`DigestVerifier`] traits which are based on the
+//!   [`Digest`] trait from the [`digest`] crate.
+//! - `rand_core`: enables the [`RandomizedSigner`] trait for signature systems which rely on a
+//!   cryptographically secure random number generator for security.
 //!
-//! [`async-signature`]: https://docs.rs/async-signature
 //! [`digest`]: https://docs.rs/digest/
 //! [`Digest`]: https://docs.rs/digest/latest/digest/trait.Digest.html
-//! [Fiat-Shamir heuristic]: https://en.wikipedia.org/wiki/Fiat%E2%80%93Shamir_heuristic
 
 #[cfg(feature = "alloc")]
 extern crate alloc;