feat: use scram hash in users.toml (#908)

Allow to specify SCRAM-SHA-256 hashes in `users.toml` instead of
plaintext passwords. Users can authenticate to pgdog without us having
to store the password anywhere.

Server auth has to be passwordless, however, e.g. RDS IAM or trust.

Author: levkk

.schema/users.schema.json

@@ -141,6 +141,13 @@
             "null"
           ]
         },
+        "password_hash": {
+          "description": "Passwords hash. Can be used to validate user logins without storing passwords in users.toml.\nServer authentication must use RDS IAM or some other passwordless authentication, e.g. trust.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "passwords": {
           "description": "Multiple passwords for this user, all of which will be attempted during auth to server and client.",
           "type": "array",

Cargo.lock

@@ -301,3 +301,22 @@ async fn test_passthrough_password_change() {
 
     admin.execute("RELOAD").await.unwrap();
 }
+
+#[tokio::test]
+async fn test_scram_hashed_passthrough() {
+    let mut conn =
+        sqlx::PgConnection::connect("postgres://pgdog_hashed:pgdog@127.0.0.1:6432/pgdog")
+            .await
+            .unwrap();
+    conn.execute("SELECT 1").await.unwrap();
+
+    let conn =
+        sqlx::PgConnection::connect("postgres://pgdog_hashed:badpw@127.0.0.1:6432/pgdog").await;
+    assert!(conn.is_err());
+    assert!(
+        conn.err()
+            .unwrap()
+            .to_string()
+            .contains("password for user")
+    );
+}

integration/rust/tests/integration/auth.rs

@@ -3,6 +3,14 @@ name = "pgdog"
 database = "pgdog"
 password = "pgdog"
 
+[[users]]
+name = "pgdog_hashed"
+database = "pgdog"
+password_hash = "SCRAM-SHA-256$4096:b6lksqhYfkXiN2hDMl3zfA==$9Rh0FdfjsbECkf289/WO2yHGiUBnNOOb1uNHVtOCCDE=:V7jC7GHvIr4guRsI66S3u4aXNhHWj1Pz71ymRM7bLFU="
+server_password = "pgdog" # Pointless obviously, but we can test scram hash is working as expected. pgdog -> server auth is expected to be passwordless, e.g. rds iam, trust, azure working directory, etc.
+server_user = "pgdog"
+min_pool_size = 0
+
 [[users]]
 name = "pgdog_session"
 database = "pgdog"

integration/users.toml

@@ -62,15 +62,14 @@ impl ConfigAndUsers {
         }
 
         let mut users: Users = if let Ok(users) = read_to_string(users_path) {
-            let mut users: Users = match toml::from_str(&users) {
+            let users: Users = match toml::from_str(&users) {
                 Ok(config) => config,
                 Err(err) => {
                     let error = Error::config(&users, err);
                     error!("failed to load {}: {}", users_path.display(), error);
                     return Err(error);
                 }
             };
-            users.check(&config);
             info!("loaded \"{}\"", users_path.display());
             users
         } else {

pgdog-config/src/core.rs

@@ -1,5 +1,6 @@
 use serde::{Deserialize, Serialize};
 use std::env;
+use std::fmt::Display;
 use std::path::PathBuf;
 use tracing::warn;
 
@@ -47,11 +48,11 @@ impl Users {
     /// Run configuration checks.
     pub fn check(&mut self, config: &Config) {
         for user in &mut self.users {
-            if user.password().is_empty() {
+            if user.passwords().is_empty() {
                 if !config.general.passthrough_auth() {
                     warn!(
-                        "user \"{}\" doesn't have a password and passthrough auth is disabled",
-                        user.name
+                        r#"user "{}" (database "{}") doesn't have a password and passthrough auth is disabled"#,
+                        user.name, user.database,
                     );
                 }
 
@@ -64,24 +65,36 @@ impl Users {
 
                     for database in databases {
                         if min_pool_size > 0 {
-                            warn!("user \"{}\" (database \"{}\") doesn't have a password configured, \
-                            so we can't connect to the server to maintain min_pool_size of {}; setting it to 0", user.name, database, min_pool_size);
+                            warn!(
+                                r#"user "{}" (database "{}") does not have a password configured, PgDog cannot connect to the server to maintain "min_pool_size" of {}, setting it to 0"#,
+                                user.name, database, min_pool_size
+                            );
                             user.min_pool_size = Some(0);
                         }
                     }
                 }
             }
 
+            if user.server_password.is_none()
+                && user.server_auth == ServerAuth::Password
+                && user.password_hash.is_some()
+            {
+                warn!(
+                    r#"user "{}" (database "{}") is using hash authentication but does not specify a "server_password""#,
+                    user.name, user.database
+                );
+            }
+
             if !user.database.is_empty() && !user.databases.is_empty() {
                 warn!(
-                    r#"user "{}" is configured for both "database" and "databases", defaulting to "database""#,
-                    user.name
+                    r#"user "{}" is configured for both "{}" and "{:?}", defaulting to "{}""#,
+                    user.name, user.database, user.databases, user.database,
                 );
             }
 
             if user.all_databases && (!user.databases.is_empty() || !user.database.is_empty()) {
                 warn!(
-                    r#"user "{}" is configured for "all_databases" and specific databases, defaulting to "all_databases""#,
+                    r#"user "{}" is configured for all databases and a specific database, defaulting to all databases""#,
                     user.name
                 );
             }
@@ -143,6 +156,31 @@ impl ServerAuth {
     }
 }
 
+/// The kind of password configured on the user.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PasswordKind {
+    Plain(String),
+    Hashed(String),
+}
+
+impl PasswordKind {
+    pub fn as_str(&self) -> &str {
+        match self {
+            Self::Plain(plain) => plain.as_str(),
+            Self::Hashed(hash) => hash.as_str(),
+        }
+    }
+}
+
+impl Display for PasswordKind {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Plain(plain) => write!(f, "{}", plain),
+            Self::Hashed(hashed) => write!(f, "{}", hashed),
+        }
+    }
+}
+
 /// User allowed to connect to pgDog.
 /// A user entry in `users.toml`, controlling which users are allowed to connect to PgDog.
 ///
@@ -174,6 +212,9 @@ pub struct User {
     /// Multiple passwords for this user, all of which will be attempted during auth to server and client.
     #[serde(default)]
     pub passwords: Vec<String>,
+    /// Passwords hash. Can be used to validate user logins without storing passwords in users.toml.
+    /// Server authentication must use RDS IAM or some other passwordless authentication, e.g. trust.
+    pub password_hash: Option<String>,
     /// Overrides [`default_pool_size`](https://docs.pgdog.dev/configuration/pgdog.toml/general/) for this user. No more than this many server connections will be open at any given time to serve requests for this connection pool.
     ///
     /// https://docs.pgdog.dev/configuration/users.toml/users/#pool_size
@@ -252,10 +293,19 @@ impl User {
         }
     }
 
-    pub fn passwords(&self) -> Vec<String> {
-        let mut passwords = self.passwords.clone();
+    pub fn passwords(&self) -> Vec<PasswordKind> {
+        let mut passwords: Vec<_> = self
+            .passwords
+            .clone()
+            .into_iter()
+            .map(|p| PasswordKind::Plain(p))
+            .collect();
         if !self.password().is_empty() {
-            passwords.push(self.password().to_string());
+            passwords.push(PasswordKind::Plain(self.password().to_string()));
+        }
+
+        if let Some(hash) = self.password_hash.clone() {
+            passwords.push(PasswordKind::Hashed(hash));
         }
 
         passwords

pgdog-config/src/users.rs

@@ -39,7 +39,8 @@ toml = "0.8"
 pgdog-plugin.workspace = true
 tokio-util = { version = "0.7", features = ["rt"] }
 fnv = "1"
-scram = { git = "https://github.com/pgdogdev/scram.git", rev = "90c511f703d2856dddd029ea062239c3132f902d" }
+scram = { git = "https://github.com/pgdogdev/scram.git", rev = "2c259426941a61f30e4252b9186e5f93e42fc924" }
+ring = "0.16"
 base64 = "0.22"
 md5 = "0.7"
 futures = "0.3"

pgdog/Cargo.toml

@@ -4,6 +4,7 @@
 //!
 use bytes::Bytes;
 use md5::Context;
+
 use rand::Rng;
 
 use super::Error;

pgdog/src/auth/md5.rs

@@ -7,3 +7,25 @@ pub mod state;
 pub use client::Client;
 pub use error::Error;
 pub use server::Server;
+
+/// Generate a `SCRAM-SHA-256$iterations:salt$StoredKey:ServerKey` hash string
+/// from a plaintext password, suitable for storage in `users.toml` or `pg_shadow`.
+pub fn generate_hash(password: &str, iterations: std::num::NonZeroU32, salt: &[u8]) -> String {
+    use base64::prelude::*;
+    use ring::digest;
+    use ring::hmac::{self, HMAC_SHA256};
+
+    let salted_password = scram::hash_password(password, iterations, salt);
+    let key = hmac::Key::new(HMAC_SHA256, &salted_password);
+    let client_key = hmac::sign(&key, b"Client Key");
+    let server_key = hmac::sign(&key, b"Server Key");
+    let stored_key = digest::digest(&digest::SHA256, client_key.as_ref());
+
+    format!(
+        "SCRAM-SHA-256${}:{}${}:{}",
+        iterations,
+        BASE64_STANDARD.encode(salt),
+        BASE64_STANDARD.encode(stored_key.as_ref()),
+        BASE64_STANDARD.encode(server_key.as_ref()),
+    )
+}