Line data    Source code

       1              : //! Functions to encrypt a password in the client.
       2              : //!
       3              : //! This is intended to be used by client applications that wish to
       4              : //! send commands like `ALTER USER joe PASSWORD 'pwd'`. The password
       5              : //! need not be sent in cleartext if it is encrypted on the client
       6              : //! side. This is good because it ensures the cleartext password won't
       7              : //! end up in logs pg_stat displays, etc.
       8              : 
       9              : use base64::Engine as _;
      10              : use base64::prelude::BASE64_STANDARD;
      11              : use hmac::{Hmac, Mac};
      12              : use rand::RngCore;
      13              : use sha2::digest::FixedOutput;
      14              : use sha2::{Digest, Sha256};
      15              : 
      16              : use crate::authentication::sasl;
      17              : 
      18              : #[cfg(test)]
      19              : mod test;
      20              : 
      21              : const SCRAM_DEFAULT_ITERATIONS: u32 = 4096;
      22              : const SCRAM_DEFAULT_SALT_LEN: usize = 16;
      23              : 
      24              : /// Hash password using SCRAM-SHA-256 with a randomly-generated
      25              : /// salt.
      26              : ///
      27              : /// The client may assume the returned string doesn't contain any
      28              : /// special characters that would require escaping in an SQL command.
      29           16 : pub async fn scram_sha_256(password: &[u8]) -> String {
      30           16 :     let mut salt: [u8; SCRAM_DEFAULT_SALT_LEN] = [0; SCRAM_DEFAULT_SALT_LEN];
      31           16 :     let mut rng = rand::thread_rng();
      32           16 :     rng.fill_bytes(&mut salt);
      33           16 :     scram_sha_256_salt(password, salt).await
      34           16 : }
      35              : 
      36              : // Internal implementation of scram_sha_256 with a caller-provided
      37              : // salt. This is useful for testing.
      38           17 : pub(crate) async fn scram_sha_256_salt(
      39           17 :     password: &[u8],
      40           17 :     salt: [u8; SCRAM_DEFAULT_SALT_LEN],
      41           17 : ) -> String {
      42              :     // Prepare the password, per [RFC
      43              :     // 4013](https://tools.ietf.org/html/rfc4013), if possible.
      44              :     //
      45              :     // Postgres treats passwords as byte strings (without embedded NUL
      46              :     // bytes), but SASL expects passwords to be valid UTF-8.
      47              :     //
      48              :     // Follow the behavior of libpq's PQencryptPasswordConn(), and
      49              :     // also the backend. If the password is not valid UTF-8, or if it
      50              :     // contains prohibited characters (such as non-ASCII whitespace),
      51              :     // just skip the SASLprep step and use the original byte
      52              :     // sequence.
      53           17 :     let prepared: Vec<u8> = match std::str::from_utf8(password) {
      54           17 :         Ok(password_str) => {
      55           17 :             match stringprep::saslprep(password_str) {
      56           17 :                 Ok(p) => p.into_owned().into_bytes(),
      57              :                 // contains invalid characters; skip saslprep
      58            0 :                 Err(_) => Vec::from(password),
      59              :             }
      60              :         }
      61              :         // not valid UTF-8; skip saslprep
      62            0 :         Err(_) => Vec::from(password),
      63              :     };
      64              : 
      65              :     // salt password
      66           17 :     let salted_password = sasl::hi(&prepared, &salt, SCRAM_DEFAULT_ITERATIONS).await;
      67              : 
      68              :     // client key
      69           17 :     let mut hmac = Hmac::<Sha256>::new_from_slice(&salted_password)
      70           17 :         .expect("HMAC is able to accept all key sizes");
      71           17 :     hmac.update(b"Client Key");
      72           17 :     let client_key = hmac.finalize().into_bytes();
      73              : 
      74              :     // stored key
      75           17 :     let mut hash = Sha256::default();
      76           17 :     hash.update(client_key.as_slice());
      77           17 :     let stored_key = hash.finalize_fixed();
      78              : 
      79              :     // server key
      80           17 :     let mut hmac = Hmac::<Sha256>::new_from_slice(&salted_password)
      81           17 :         .expect("HMAC is able to accept all key sizes");
      82           17 :     hmac.update(b"Server Key");
      83           17 :     let server_key = hmac.finalize().into_bytes();
      84              : 
      85           17 :     format!(
      86           17 :         "SCRAM-SHA-256${}:{}${}:{}",
      87              :         SCRAM_DEFAULT_ITERATIONS,
      88           17 :         BASE64_STANDARD.encode(salt),
      89           17 :         BASE64_STANDARD.encode(stored_key),
      90           17 :         BASE64_STANDARD.encode(server_key)
      91              :     )
      92           17 : }