1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
//! Signatory: a multi-provider digital signature library //! //! This crate provides a thread-and-object-safe API for both creating and //! verifying elliptic curve digital signatures, using either software-based //! or hardware-based providers. //! //! The following algorithms are supported: //! //! - [ecdsa]: Elliptic Curve Digital Signature Algorithm ([FIPS 186-4]) //! - [ed25519]: Edwards Digital Signature Algorithm (EdDSA) instantiated using //! the twisted Edwards form of Curve25519 ([RFC 8032]). //! //! ## Providers //! //! There are several backend providers available, which are each available //! in their own crates: //! //! - [signatory-dalek]: Ed25519 signing/verification using the pure-Rust //! [ed25519-dalek] crate. //! - [signatory-ring]: ECDSA and Ed25519 signing/verification provider //! for the [*ring*] cryptography library. //! - [signatory-secp256k1]: ECDSA signing/verification for the secp256k1 //! elliptic curve (commonly used by Bitcoin and other cryptocurrrencies) //! which wraps the [libsecp256k1] library from Bitcoin Core. //! - [signatory-sodiumoxide]: Ed25519 signing/verification with the //! [sodiumoxide] crate, a Rust wrapper for libsodium (NOTE: requires //! libsodium to be installed on the system) //! - [yubihsm-rs]: ECDSA and Ed25519 signing provider support for //! private keys stored in a `YubiHSM2` hardware device, via the //! Signatory signers types in the [yubihsm-rs] crate //! ([yubihsm::ecdsa::Signer] and [yubihsm::ed25519::Signer]). //! //! ## Signing API //! //! Signatory provides the following convenience methods for signing. Each of //! them dispatches through a trait object for the given trait: //! //! - [signatory::sign] - sign a byte slice using a given signing provider. //! This method wraps the [Signer] trait and is most useful for computing //! [ed25519] signatures. //! - [signatory::sign_digest] - sign the given precomputed digest using the //! given signing provider, a.k.a. Initialize-Update-Finalize (IUF). This //! method wraps the [DigestSigner] trait and is most useful for signing //! large messages in conjunction with hardware-backed signers. //! - [signatory::sign_sha256], [signatory::sign_sha384], //! [signatory::sign_sha512] - sign the given message after first computing //! its SHA-2 digest. These methods wrap the [Sha256Signer], //! [Sha384Signer], and [Sha512Signer] traits respectively, and are most //! useful in conjunction with [ecdsa]. //! //! Each of these methods and traits is generic around the signature type. //! This makes it important to annotate the particular type of signature //! which you would like when using them, e.g. //! //! ``` //! use signatory::{self, ed25519}; //! //! let sig: ed25519::Signature = signatory::sign(signer, &msg).unwrap(); //! ``` //! //! Or use the [turbofish]: //! //! ``` //! use signatory::{self, ed25519}; //! //! let sig = signatory::sign::<ed25519::Signature>(signer, &msg).unwrap(); //! ``` //! //! Alternatively, for Ed25519 signatures, the [ed25519] module provides //! methods which operate on concrete Ed25519 types. //! //! ## Verifier API //! //! Signatory provides the following convenience methods for verifying //! signatures, which map 1:1 to the methods provided for signing: //! //! * [signatory::verify] - verify a byte slice using a given provider. //! This method wraps the [Verifier] trait and is most useful for verifying //! [ed25519] signatures. //! * [signatory::verify_digest] - verify the given precomputed message digest //! against the provided signature, i.e. IUF. This method wraps the //! [DigestVerifier] trait and is most useful for verifying large messages //! in conjunction with hardware-backed signers. //! * [signatory::verify_sha256], [signatory::verify_sha384], //! [signatory::verify_sha512] - verify the given message after first //! computing its SHA-2 digest. These methods wrap the [Sha256Verifier], //! [Sha384Verifier], and [Sha512Verifier] traits respectively, and are most //! useful in conjunction with [ecdsa]. //! //! [FIPS 186-4]: https://csrc.nist.gov/publications/detail/fips/186/4/final //! [RFC 8032]: https://tools.ietf.org/html/rfc8032 //! [ecdsa]: https://docs.rs/signatory/latest/signatory/ecdsa/index.html //! [ed25519]: https://docs.rs/signatory/latest/signatory/ed25519/index.html //! [signatory-dalek]: https://docs.rs/crate/signatory-dalek/ //! [ed25519-dalek]: https://docs.rs/crate/ed25519-dalek/ //! [signatory-ring]: https://docs.rs/crate/signatory-ring/ //! [*ring*]: https://github.com/briansmith/ring //! [signatory-secp256k1]: https://docs.rs/crate/signatory-secp256k1/ //! [libsecp256k1]: https://docs.rs/crate/secp256k1 //! [signatory-sodiumoxide]: https://docs.rs/crate/signatory-sodiumoxide/ //! [sodiumoxide]: https://docs.rs/crate/sodiumoxide/ //! [yubihsm-rs]: https://docs.rs/crate/yubihsm/ //! [yubihsm::ecdsa::Signer]: https://docs.rs/yubihsm/latest/yubihsm/ecdsa/struct.Signer.html //! [yubihsm::ed25519::Signer]: https://docs.rs/yubihsm/latest/yubihsm/ed25519/struct.Signer.html //! [signatory::sign]: https://docs.rs/signatory/latest/signatory/fn.sign.html //! [signatory::sign_digest]: https://docs.rs/signatory/latest/signatory/fn.sign_digest.html //! [signatory::sign_sha256]: https://docs.rs/signatory/latest/signatory/fn.sign_sha256.html //! [signatory::sign_sha384]: https://docs.rs/signatory/latest/signatory/fn.sign_sha384.html //! [signatory::sign_sha512]: https://docs.rs/signatory/latest/signatory/fn.sign_sha512.html //! [Signer]: https://docs.rs/signatory/latest/signatory/trait.Signer.html //! [DigestSigner]: https://docs.rs/signatory/latest/signatory/trait.DigestSigner.html //! [Sha256Signer]: https://docs.rs/signatory/latest/signatory/trait.Sha256Signer.html //! [Sha384Signer]: https://docs.rs/signatory/latest/signatory/trait.Sha384Signer.html //! [Sha512Signer]: https://docs.rs/signatory/latest/signatory/trait.Sha512Signer.html //! [signatory::verify]: https://docs.rs/signatory/latest/signatory/fn.verify.html //! [signatory::verify_digest]: https://docs.rs/signatory/latest/signatory/fn.verify_digest.html //! [signatory::verify_sha256]: https://docs.rs/signatory/latest/signatory/fn.verify_sha256.html //! [signatory::verify_sha384]: https://docs.rs/signatory/latest/signatory/fn.verify_sha384.html //! [signatory::verify_sha512]: https://docs.rs/signatory/latest/signatory/fn.verify_sha512.html //! [Verifier]: https://docs.rs/signatory/latest/signatory/trait.Verifier.html //! [DigestVerifier]: https://docs.rs/signatory/latest/signatory/trait.DigestVerifier.html //! [Sha256Verifier]: https://docs.rs/signatory/latest/signatory/trait.Sha256Verifier.html //! [Sha384Verifier]: https://docs.rs/signatory/latest/signatory/trait.Sha384Verifier.html //! [Sha512Verifier]: https://docs.rs/signatory/latest/signatory/trait.Sha512Verifier.html //! [turbofish]: https://turbo.fish/ #![no_std] #![deny( warnings, missing_docs, trivial_casts, trivial_numeric_casts, unsafe_code, unused_import_braces, unused_qualifications )] #![doc( html_logo_url = "https://raw.githubusercontent.com/tendermint/signatory/develop/img/signatory-rustacean.png", html_root_url = "https://docs.rs/signatory/0.11.5" )] #[cfg(all(feature = "alloc", not(feature = "std")))] #[allow(unused_imports)] // rustc bug? #[macro_use] extern crate alloc; #[cfg(any(feature = "std", test))] #[macro_use] extern crate std; #[cfg(feature = "digest")] pub use digest; #[cfg(feature = "generic-array")] pub use generic_array; #[macro_use] pub mod error; #[cfg(feature = "ecdsa")] pub mod ecdsa; #[cfg(feature = "ed25519")] #[macro_use] pub mod ed25519; #[cfg(feature = "encoding")] pub mod encoding; pub(crate) mod prelude; mod public_key; mod signature; mod signer; #[cfg(feature = "test-vectors")] pub mod test_vector; mod util; mod verifier; #[cfg(feature = "ecdsa")] pub use crate::ecdsa::{ PublicKey as EcdsaPublicKey, SecretKey as EcdsaSecretKey, Signature as EcdsaSignature, }; #[cfg(feature = "ed25519")] pub use crate::ed25519::{ PublicKey as Ed25519PublicKey, Seed as Ed25519Seed, Signature as Ed25519Signature, }; #[cfg(feature = "encoding")] pub use crate::encoding::*; pub use crate::{ error::{Error, ErrorKind}, public_key::{public_key, PublicKey, PublicKeyed}, signature::Signature, signer::{sha2::*, sign, Signer}, verifier::{sha2::*, verify, Verifier}, }; #[cfg(feature = "digest")] pub use crate::{ signer::digest::{sign_digest, DigestSigner}, verifier::digest::{verify_digest, DigestVerifier}, }; #[cfg(feature = "digest")] pub use digest::Digest;