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::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(transparent)]
      37              :     Io(#[from] io::Error),
      38              : }
      39              : 
      40              : impl UserFacingError for Error {
      41            0 :     fn to_string_client(&self) -> String {
      42            0 :         use Error::*;
      43            0 :         match self {
      44            0 :             ChannelBindingFailed(m) => m.to_string(),
      45            0 :             ChannelBindingBadMethod(m) => format!("unsupported channel binding method {m}"),
      46            0 :             _ => "authentication protocol violation".to_string(),
      47              :         }
      48            0 :     }
      49              : }
      50              : 
      51              : /// A convenient result type for SASL exchange.
      52              : pub type Result<T> = std::result::Result<T, Error>;
      53              : 
      54              : /// A result of one SASL exchange.
      55              : #[must_use]
      56              : pub enum Step<T, R> {
      57              :     /// We should continue exchanging messages.
      58              :     Continue(T, String),
      59              :     /// The client has been authenticated successfully.
      60              :     Success(R, String),
      61              :     /// Authentication failed (reason attached).
      62              :     Failure(&'static str),
      63              : }
      64              : 
      65              : /// Every SASL mechanism (e.g. [SCRAM](crate::scram)) is expected to implement this trait.
      66              : pub trait Mechanism: Sized {
      67              :     /// What's produced as a result of successful authentication.
      68              :     type Output;
      69              : 
      70              :     /// Produce a server challenge to be sent to the client.
      71              :     /// This is how this method is called in PostgreSQL (`libpq/sasl.h`).
      72              :     fn exchange(self, input: &str) -> Result<Step<Self, Self::Output>>;
      73              : }