Line data Source code
1 : //! Simple Authentication and Security Layer.
2 : //!
3 : //! RFC: <https://datatracker.ietf.org/doc/html/rfc4422>.
4 : //!
5 : //! Reference implementation:
6 : //! * <https://github.com/postgres/postgres/blob/94226d4506e66d6e7cbf4b391f1e7393c1962841/src/backend/libpq/auth-sasl.c>
7 : //! * <https://github.com/postgres/postgres/blob/94226d4506e66d6e7cbf4b391f1e7393c1962841/src/interfaces/libpq/fe-auth.c>
8 :
9 : mod channel_binding;
10 : mod messages;
11 : mod stream;
12 :
13 : use crate::error::{ReportableError, UserFacingError};
14 : use std::io;
15 : use thiserror::Error;
16 :
17 : pub use channel_binding::ChannelBinding;
18 : pub use messages::FirstMessage;
19 : pub use stream::{Outcome, SaslStream};
20 :
21 : /// Fine-grained auth errors help in writing tests.
22 0 : #[derive(Error, Debug)]
23 : pub enum Error {
24 : #[error("Channel binding failed: {0}")]
25 : ChannelBindingFailed(&'static str),
26 :
27 : #[error("Unsupported channel binding method: {0}")]
28 : ChannelBindingBadMethod(Box<str>),
29 :
30 : #[error("Bad client message: {0}")]
31 : BadClientMessage(&'static str),
32 :
33 : #[error("Internal error: missing digest")]
34 : MissingBinding,
35 :
36 : #[error("could not decode salt: {0}")]
37 : Base64(#[from] base64::DecodeError),
38 :
39 : #[error(transparent)]
40 : Io(#[from] io::Error),
41 : }
42 :
43 : impl UserFacingError for Error {
44 0 : fn to_string_client(&self) -> String {
45 0 : use Error::*;
46 0 : match self {
47 0 : ChannelBindingFailed(m) => m.to_string(),
48 0 : ChannelBindingBadMethod(m) => format!("unsupported channel binding method {m}"),
49 0 : _ => "authentication protocol violation".to_string(),
50 : }
51 0 : }
52 : }
53 :
54 : impl ReportableError for Error {
55 0 : fn get_error_kind(&self) -> crate::error::ErrorKind {
56 0 : match self {
57 0 : Error::ChannelBindingFailed(_) => crate::error::ErrorKind::User,
58 0 : Error::ChannelBindingBadMethod(_) => crate::error::ErrorKind::User,
59 0 : Error::BadClientMessage(_) => crate::error::ErrorKind::User,
60 0 : Error::MissingBinding => crate::error::ErrorKind::Service,
61 0 : Error::Base64(_) => crate::error::ErrorKind::ControlPlane,
62 0 : Error::Io(_) => crate::error::ErrorKind::ClientDisconnect,
63 : }
64 0 : }
65 : }
66 :
67 : /// A convenient result type for SASL exchange.
68 : pub type Result<T> = std::result::Result<T, Error>;
69 :
70 : /// A result of one SASL exchange.
71 : #[must_use]
72 : pub enum Step<T, R> {
73 : /// We should continue exchanging messages.
74 : Continue(T, String),
75 : /// The client has been authenticated successfully.
76 : Success(R, String),
77 : /// Authentication failed (reason attached).
78 : Failure(&'static str),
79 : }
80 :
81 : /// Every SASL mechanism (e.g. [SCRAM](crate::scram)) is expected to implement this trait.
82 : pub trait Mechanism: Sized {
83 : /// What's produced as a result of successful authentication.
84 : type Output;
85 :
86 : /// Produce a server challenge to be sent to the client.
87 : /// This is how this method is called in PostgreSQL (`libpq/sasl.h`).
88 : fn exchange(self, input: &str) -> Result<Step<Self, Self::Output>>;
89 : }
|