open_payments/http_signature/
error.rs

1//! # HTTP Signature Error Types
2//!
3//! This module defines the error types used throughout the HTTP signature functionality.
4//! All signature operations return a [`Result<T, HttpSignatureError>`] which provides
5//! detailed error information for different failure scenarios.
6//!
7//! ## Error Categories
8//!
9//! - **I/O Errors**: File system and network I/O problems
10//! - **Parsing Errors**: Key format and data parsing failures
11//! - **Cryptographic Errors**: Signature creation and validation issues
12//! - **JWK Errors**: JSON Web Key format and processing problems
13//!
14//! ## Example Usage
15//!
16//! ```rust
17//! use open_payments::http_signature::{HttpSignatureError, Result};
18//!
19//! fn handle_signature_error(result: Result<()>) {
20//!     match result {
21//!         Ok(()) => println!("Signature operation successful"),
22//!         Err(HttpSignatureError::Io(err)) => eprintln!("I/O error: {}", err),
23//!         Err(HttpSignatureError::Signature(msg)) => eprintln!("Signature error: {}", msg),
24//!         Err(HttpSignatureError::Validation(msg)) => eprintln!("Validation error: {}", msg),
25//!         Err(e) => eprintln!("Unexpected error: {:?}", e),
26//!     }
27//! }
28//! ```
29
30use base64::DecodeError;
31use std::io;
32use thiserror::Error;
33
34/// Error type for HTTP signature operations.
35///
36/// This enum provides detailed error information for different types of failures
37/// that can occur during HTTP signature creation, validation, and key management.
38/// Each variant includes context-specific error messages to help with debugging
39/// and error handling.
40///
41/// ## Error Variants
42///
43/// - `Io` - File system and I/O errors
44/// - `Base64` - Base64 encoding/decoding errors
45/// - `Pem` - PEM format parsing errors
46/// - `Pkcs8` - PKCS8 key format errors
47/// - `InvalidPrivateKeyLength` - Private key length validation errors
48/// - `Utf8` - UTF-8 encoding/decoding errors
49/// - `Jwk` - JSON Web Key format errors
50/// - `Signature` - Signature creation and verification errors
51/// - `Validation` - Signature validation and verification errors
52/// - `Other` - Miscellaneous errors
53#[derive(Debug, Error)]
54pub enum HttpSignatureError {
55    /// File system and I/O errors.
56    ///
57    /// This error is automatically converted from `std::io::Error` and occurs
58    /// when the signature module cannot read key files or perform other I/O operations.
59    #[error("IO error: {0}")]
60    Io(#[from] io::Error),
61
62    /// Base64 encoding or decoding errors.
63    ///
64    /// This error is automatically converted from `base64::DecodeError` and occurs
65    /// when the signature module cannot decode Base64-encoded data such as signatures,
66    /// keys, or other encoded content.
67    #[error("Base64 decode error: {0}")]
68    Base64(#[from] DecodeError),
69
70    /// PEM format parsing errors.
71    ///
72    /// Occurs when the signature module cannot parse PEM-encoded private keys or certificates.
73    /// This includes malformed PEM files, unsupported PEM types, or invalid PEM structure.
74    #[error("PEM parse error: {0}")]
75    Pem(String),
76
77    /// PKCS8 key format errors.
78    ///
79    /// Occurs when the signature module cannot parse PKCS8-encoded private keys.
80    /// This includes unsupported key algorithms, malformed key data, or invalid
81    /// PKCS8 structure.
82    #[error("PKCS8 parse error: {0}")]
83    Pkcs8(String),
84
85    /// Private key length validation errors.
86    ///
87    /// Occurs when a private key has an invalid length for the expected algorithm.
88    /// For Ed25519 keys, this typically means the key is not exactly 32 bytes long.
89    #[error("Invalid private key length")]
90    InvalidPrivateKeyLength,
91
92    /// UTF-8 encoding or decoding errors.
93    ///
94    /// This error is automatically converted from `std::string::FromUtf8Error` and occurs
95    /// when the signature module cannot convert byte data to UTF-8 strings, typically
96    /// when processing key files or signature data.
97    #[error("UTF-8 error: {0}")]
98    Utf8(#[from] std::string::FromUtf8Error),
99
100    /// JSON Web Key format errors.
101    ///
102    /// Occurs when there are issues with JWK format, parsing, or processing.
103    /// This includes malformed JWK JSON, unsupported key types, or invalid
104    /// JWK structure.
105    #[error("JWK error: {0}")]
106    Jwk(String),
107
108    /// Signature creation and verification errors.
109    ///
110    /// Occurs when there are issues with HTTP message signature creation or verification.
111    /// This includes key loading failures, signature generation errors, or algorithm
112    /// compatibility issues.
113    #[error("Signature error: {0}")]
114    Signature(String),
115
116    /// Signature validation and verification errors.
117    ///
118    /// Occurs when signature validation fails, including expired signatures,
119    /// invalid signature formats, or verification failures against public keys.
120    #[error("Validation error: {0}")]
121    Validation(String),
122
123    /// Miscellaneous errors that don't fit into other categories.
124    ///
125    /// This variant is used for errors that are specific to the HTTP signature
126    /// implementation or other unexpected issues that don't fall into the standard
127    /// error categories.
128    #[error("Other: {0}")]
129    Other(String),
130}
131
132/// Result type for HTTP signature operations.
133///
134/// This is a type alias for `Result<T, HttpSignatureError>` that provides a convenient
135/// way to handle signature operation results with detailed error information.
136pub type Result<T> = std::result::Result<T, HttpSignatureError>;
open_payments/http_signature/error.rs

open_payments/http_signature/
error.rs
