rsasl 2.3.0

The Rust SASL framework, aimed at both middleware-style protocol implementation and application code. Designed to make SASL authentication simple and safe while handing as much control to the user as possible.
Documentation 
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

use crate::alloc::{boxed::Box, string::String};

#[cfg(feature = "std")]
use thiserror::Error;

use crate::callback::CallbackError;
use crate::validate::ValidationError;
use core::fmt;

/// Different high-level kinds of errors that can happen in mechanisms
#[non_exhaustive]
pub enum MechanismErrorKind {
    /// Parsing failed for the given reason (syntactical error)
    Parse,

    /// The messages where syntactically valid but a semantical error occurred during handling
    Protocol,

    /// While the exchange did complete correctly, the authentication itself failed for some
    /// reason or another.
    Outcome,
}

#[cfg(feature = "std")]
/// Errors specific to a certain mechanism
pub trait MechanismError: fmt::Debug + fmt::Display + Send + Sync + std::error::Error {
    fn kind(&self) -> MechanismErrorKind;
}
#[cfg(not(feature = "std"))]
/// Errors specific to a certain mechanism
pub trait MechanismError: fmt::Debug + fmt::Display + Send + Sync {
    fn kind(&self) -> MechanismErrorKind;
}

#[derive(Debug, Error)]
/// Error type returned when stepping an established `Session`
///
///
#[non_exhaustive]
pub enum SessionError {
    #[error("IO error occurred")]
    Io {
        #[from]
        source: crate::io::Error,
    },

    #[cfg(feature = "provider_base64")]
    #[error("base64 wrapping failed")]
    Base64 {
        #[from]
        source: base64::DecodeError,
    },

    #[error("no security layer is installed")]
    /// No security layer is currently installed.
    NoSecurityLayer,

    #[error("input data was required but not provided")]
    // Common Mechanism Errors:
    /// Mechanism was called without input data when requiring some, or with too little input data.
    InputDataRequired,

    #[error("step was called after mechanism finished")]
    MechanismDone,

    #[error("internal mechanism error: {0}")]
    MechanismError(Box<dyn MechanismError>),

    #[error("callback error")]
    CallbackError(
        #[from]
        #[source]
        CallbackError,
    ),

    #[error("validation error")]
    ValidationError(
        #[from]
        #[source]
        ValidationError,
    ),

    #[error(transparent)]
    #[cfg(feature = "std")]
    Boxed(#[from] Box<dyn std::error::Error + Send + Sync>),

    #[error("callback did not validate the authentication exchange")]
    NoValidate,

    #[error("the server failed mutual authentication")]
    /// This error indicates that the server failed to authenticate itself to a client
    ///
    /// This is most of the time **a very bad thing**. It means that the server failed to show that
    /// it has access to the clients password *and let them in anyway*. While this may be okay in
    /// a few select circumstances this error should not be ignored lightly.
    ///
    /// Only mechanisms that perform mutual authentication can return this error, and it will
    /// only ever be returned on the client side of an authentication.
    MutualAuthenticationFailed,

    #[error("channel binding data for '{0}' is required")]
    MissingChannelBindingData(String),
}

impl SessionError {
    #[must_use]
    pub const fn input_required() -> Self {
        Self::InputDataRequired
    }

    #[must_use]
    pub const fn is_mechanism_error(&self) -> bool {
        matches!(self, Self::MechanismError(_))
    }

    #[must_use]
    pub const fn is_missing_prop(&self) -> bool {
        matches!(self, Self::CallbackError(CallbackError::NoCallback(_)))
    }
}

impl<T: MechanismError + 'static> From<T> for SessionError {
    fn from(e: T) -> Self {
        Self::MechanismError(Box::new(e))
    }
}

#[derive(Debug, Error)]
/// The error type for rsasl errors originating from [`SASLClient`](crate::sasl::SASLClient) or
/// [`SASLServer`](crate::sasl::SASLServer).
///
/// This is one of two error types a protocol implementation needs to be aware of, the other
/// being [`SessionError`].
///
/// `SASLError` is returned when trying to establish a new `Session` from e.g. a list of offered
/// mechanisms.
#[non_exhaustive]
pub enum SASLError {
    #[error("no shared mechanism found")]
    /// No mechanism from the offered list is available.
    ///
    /// This error may occur even if the mechanism is implemented by rsasl, as an user may have
    /// filtered the otherwise shared mechanisms.
    NoSharedMechanism,
}

#[cfg(test)]
mod tests {
    use super::*;

    static_assertions::assert_impl_all!(SessionError: Send, Sync);
    static_assertions::assert_obj_safe!(MechanismError);
}