TLA  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 UBC           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                 : }