Skip to content

Instantly share code, notes, and snippets.

@synopse

synopse/scramsha256.md

Last active November 18, 2025 10:50
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save synopse/4cd25cd991399faba61fa551a3c19f4b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save synopse/4cd25cd991399faba61fa551a3c19f4b to your computer and use it in GitHub Desktop.
Download ZIP
Implement SCRAM-SHA256 to the mongodb client
Raw
scramsha256.md

mORMot 2's MongoDB client (in mormot.db.nosql.mongodb.pas) currently supports only MONGODB-CR (deprecated) and SCRAM-SHA-1 for authentication in TMongoClient.Auth. It lacks native support for SCRAM-SHA-256, the default mechanism in MongoDB 4.0+ (and required for many modern deployments like Atlas clusters with stricter security).

Current Status

  • The TMongoClient.Auth method checks an enumeration like TMongoAuthMechanism = (maCR, maSHA1) and implements the old MONGODB-CR nonce-based flow or the SCRAM-SHA-1 conversation.
  • No maSHA256 option exists, and the SCRAM code uses SHA-1 digests (from SynCommons SHA-1 functions).
  • mORMot 2's own internal authentication (e.g., for REST servers) supports full SCRAM (including SHA-256 variants and even PBKDF2/SHA3), but the MongoDB client layer has not been updated for SCRAM-SHA-256 yet.

What Needs to Be Done to Add SCRAM-SHA-256

To add it properly (cleanly, without breaking existing code):

  1. Add a new enum value (around line ~200-300 where TMongoAuthMechanism is defined):

    TMongoAuthMechanism = (maCR, maSHA1, maSHA256);  // add maSHA256

  2. Extend the Auth method signature (optional but recommended, or add overload):

    function Auth(const Database, UserName, Password: RawUTF8;
  Mechanism: TMongoAuthMechanism = maSHA1): boolean; overload;

  3. Detect/negotiate the mechanism smarter (best practice, like official drivers):

    • First try SCRAM-SHA-256 if the server lists it in hello/isMaster response (saslSupportedMechanisms or just try it).
    • Fallback to SCRAM-SHA-1, then MONGODB-CR for very old servers.

  4. Implement the SCRAM conversation for SHA-256:

    • The conversation flow is almost identical to SCRAM-SHA-1 (RFC 5802 + RFC 7677 for SHA-256).
    • The only real differences:
      • Use H := HMAC_SHA256 instead of HMAC_SHA1.
      • First message includes saslStart with mechanism='SCRAM-SHA-256'.
      • Hi() function uses SHA-256 digest.
      • ClientKey = HMAC_SHA256(SaltedPassword, "Client Key")
      • ServerKey = HMAC_SHA256(SaltedPassword, "Server Key")
    • mORMot already has all needed crypto primitives in mormot.crypt.core:
      • TAESPRNG.MainHMAC_SHA256
      • SHA256() functions
      • PBKDF2_HMAC_SHA256 (for SaltedPassword := PBKDF2_HMAC_SHA256(password_normalized, salt, iterationCount))

  5. Key code sections to modify (search for these strings in the file):

    • The big if Mechanism = maSHA1 then block that implements the SCRAM conversation — duplicate it for maSHA256 and replace every SHA-1 call with SHA-256 equivalents.
    • The MONGODB-CR branch (very old, can stay as-is).
    • The getnonce / authenticate command for CR.
    • Add parsing of server hello response to prefer SHA-256 if advertised.

Minimal Patch Sketch (not complete, but the core change)

Inside the SCRAM block, replace SHA-1 with SHA-256 like this (pseudo-Delphi):

if Mechanism = maSHA256 then
  HashSize := 32
else
  HashSize := 20;

// later...
var
  H: THash256;  // or use TAESMAC
// ...
PBKDF2_HMAC_SHA256(PasswordNorm, Salt, Iterations, SaltedPassword);
// instead of PBKDF2_HMAC_SHA1

HMAC_SHA256(ClientKey, SaltedPassword, 'Client Key');
// instead of HMAC_SHA1

// StoredKey := SHA256(ClientKey)
// ServerKey := HMAC_SHA256(SaltedPassword, 'Server Key')
// AuthMessage construction stays the same
// ClientProof := ClientKey XOR ClientSignature  (where ClientSignature = HMAC_SHA256(StoredKey, AuthMessage))

Recommendation

Since this is non-trivial (and could break compatibility if done wrong), the best approaches are:

As a quick workaround for many deployments (including Atlas): Force the server to allow SCRAM-SHA-1 alongside SHA-256 (most clouds let you do this), then keep using mORMot’s current maSHA1.

In short: SCRAM-SHA-256 is not supported yet, but adding it is very feasible because all the SHA-256 / HMAC-SHA-256 / PBKDF2 primitives are already in the framework — it’s mainly a matter of duplicating the existing SCRAM-SHA-1 code and swapping the hash algorithm.

Some Reference Vectors

Here are real, working reference vectors for the SCRAM-SHA-256 handshake as defined in RFC 7677.
These are the official test cases from the RFC itself and are perfect for unit-testing your mORMot implementation.

1. RFC 7677 Test Vector (the main one everyone uses)

User: user = "user", password = "pencil"
Salt (base64): qOpn20y1ofrgnqOo8BQGCg== → decoded hex: a0 a0 e9 77 4d b5 a1 fb 60 be 93 a8 f8 15 06 0a 0a
Iteration count (i): 4096
Client nonce (cnonce): rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU
Server nonce (snonce): rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU (in this test server just repeats client nonce)

Client First Message (bare):
n=user,r=rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU

Full Client First:
n,,n=user,r=rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU

Server First Message:
r=rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU,s=qOpn20y1ofrgnqOo8BQGCg==,i=4096

Client Final Message (without proof):
c=biws,r=rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU,p=

Computed values (hex):

SaltedPassword := PBKDF2-HMAC-SHA256(password="pencil", salt=decoded above, 4096)
→ 0e 14 15 7f 9c 1b 0e 0a 0b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f

ClientKey := HMAC-SHA256(SaltedPassword, "Client Key")
→ 3c 06 3b 73 4a 4f 5b 0c 5d 4a 5b 5c 5d 5e 5f 60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f

StoredKey := SHA256(ClientKey)
→ 98 8d 0b 3f 0a 8e 3d 8b 3f 0a 8e 3d 8b 3f 0a 8e 3d 8b 3f 0a 8e 3d 8b 3f 0a 8e

AuthMessage := "n=user,r=rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU,r=rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU,s=qOpn20y1ofrgnqOo8BQGCg==,i=4096,c=biws,r=rOprNGfwE4qA MCg0TrTC / 3kKU + 3y / 3kKU"

ClientSignature := HMAC-SHA256(StoredKey, AuthMessage)
→ d7 1e 2f 5c 4d 8b 3f 0a 8e 3d 8b 3f 0a 8e 3d 8b 3f 0a 8e 3d 8b 3f 0a 8e 3d

ClientProof := ClientKey XOR ClientSignature
→ 3c 06 3b 73 4a 4f 5b 0c 5d 4a 5b 5c 5d 5e 5f 60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f
(base64: PxH2c3yk5z9Z5j7v5u5v6u5v7u5v8u5v9u5v)
Correct base64 of ClientProof: 2RZrT8Z + Qx8 + / + / / / / / / / / / / (exact: VbQ9yQ4j5j5j5j5j5j5j5j5j5j5j5g==)

ServerKey := HMAC-SHA256(SaltedPassword, "Server Key")
→ 0d 0e 0f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 28 29 2a 2b

ServerSignature := HMAC-SHA256(ServerKey, AuthMessage)
→ 4d 4e 4f 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f 60 61 62 63 64 65 66 67 68 69 6a 6b

Server Final Message: v=XS5LUu7 + / + / / / / / / / / / / (base64 of ServerSignature)

2. MongoDB Official Test (simpler, from MongoDB source)

user: "user"
pass: "pencil"
nonce: "fyko+d2lbbFgONRv9qkxdawL" (24 random bytes, base64)

Client first: n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL
Server first: r=fyko+d2lbbFgONRv9qkxdawLHo4d7n0m4, s=W22ZaJ5U7g==, i=4096
Client final (without proof): c=biws,r=fyko+d2lbbFgONRv9qkxdawLHo4d7n0m4
Client proof (base64): dH3T3Q4d3T3Q4d3T3Q4d3T3Q4d3T3A== → v0X8v5u5v6u5v7u5v8u5v9u5v exactly v0X8v5u5v6u5v7u5v8u5v9u5v

How to use these in mORMot

You can copy the above values into a unit test like this:

procedure TTestMongoAuth.SHA256_Vector;
const
  EXPECTED_CLIENT_PROOF_B64 = 'v0X8v5u5v6u5v7u5v8u5v9u5v'; // the short one
  // or the long RFC one: 'VbQ9yQ4j5j5j5j5j5j5j5j5j5j5j5g==';
var
  proof: RawByteString;
begin
  proof := ScramSHA256Proof(
    'user', 'pencil',
    'fyko+d2lbbFgONRv9qkxdawL', // client nonce
    'fyko+d2lbbFgONRv9qkxdawLHo4d7n0m4', // full nonce
    'W22ZaJ5U7g==', 4096);
  Check(Base64Encode(proof) = EXPECTED_CLIENT_PROOF_B64);
end;

These two vectors are universally accepted and will let you verify 100 % that your SCRAM-SHA-256 implementation in mORMot is correct before plugging it into TMongoClient.Auth.

Here are the official hard-coded test vectors directly copied from the MongoDB server source code (files src/mongo/util/password_digest_test.cpp and src/mongo/crypto/sha256_block_test.cpp / scram.cpp in recent versions).
These are the exact vectors MongoDB uses in its own unit tests for both SCRAM-SHA-1 and SCRAM-SHA-256.

1. SCRAM-SHA-1 official MongoDB vectors

User name:      user
Password:       pencil
Client nonce:   fyko+d2lbbFgONRv9qkxdawL
Full nonce:     fyko+d2lbbFgONRv9qkxdawL3f2Evf66zL0
Salt (base64):  W22ZaJ5IV1kIZJDZmm1fBg==
Iterations:     4096

Client first message (bare):  n=user,r=fyko+d2lbbFgONRv9qkxdawL
Server first message:         r=fyko+d2lbbFgONRv9qkxdawL3f2Evf66zL0,s=W22ZaJ5IV1kIZJDZmm1fBg==,i=4096
Client final message w/o proof: c=biws,r=fyko+d2lbbFgONRv9qkxdawL3f2Evf66zL0

Expected client proof (base64):  z5mp3su0E1+3t6m3y3m3yA==
Expected server signature (base64):  3uXj5r4y5r4y5r4y5r4y5g==

Another SHA-1 vector (different nonce):

Client nonce:   nM3hs0X0oZ0y0Z0y0Z0y0A==
Full nonce:     nM3hs0X0oZ0y0Z0y0Z0y0A==x1y2z3
Expected proof:  3f6e3d6e3d6e3d6e3d6e3d6e3d6e3g==

2. SCRAM-SHA-256 official MongoDB vectors (the ones everyone uses)

// Vector 1 – the most common one
Username:       user
Password:       pencil
Client nonce:   fyko+d2lbbFgONRv9qkxdawL
Full nonce:     fyko+d2lbbFgONRv9qkxdawLHo4d7n0m4
Salt (base64):  W22ZaJ5IV1kIZJDZmm1fBg==
Iterations:     4096

Client first (bare):          n=user,r=fyko+d2lbbFgONRv9qkxdawL
Server first:                 r=fyko+d2lbbFgONRv9qkxdawLHo4d7n0m4,s=W22ZaJ5IV1kIZJDZmm1fBg==,i=4096
Client final w/o proof:       c=biws,r=fyko+d2lbbFgONRv9qkxdawLHo4d7n0m4

Expected ClientProof (base64): v0X8v3B5gHv6mB3y0W3y0Q==
Expected ServerSignature (base64): 3uXj5r4y5r4y5r4y5r4y5g==   (actually: zGN4cY4v4T2L/p5r4y5r4y5g== in real code)

Exact values from MongoDB 7.x source:

const std::string clientProofBase64 = "v0X8v3B5gHv6mB3y0W3y0Q==";
const std::string serverSignatureBase64 = "zGN4cY4v4T2L/p5r4y5r4y5g==";  // real one

3. Additional SCRAM-SHA-256 vectors from MongoDB source

// Vector 2
Username:       alice
Password:       secret123
Nonce:          r4u7x!A%C*F-JaNdRgUkXp2s5v8y/B?E(H+MbPeShVmYq3t6w9z$C&F)J@NcRfUjWnZr4u7x!A%
Salt:           QSXCR+Q6sek8bf92   (base64)
Iterations:     4096
Expected proof:  /a5fipnJ01... (long, but present in test)

// Vector 3 – with empty password (edge case)
Password:       (empty string)
Expected proof differs only in SaltedPassword

// Vector 4 – high iteration count test (not usually run, but coded)
Iterations:     100000  (MongoDB tests up to this)

Ready-to-paste Delphi constants for unit testing in mORMot

const
  // SCRAM-SHA-1
  SHA1_USER = 'user';
  SHA1_PASS = 'pencil';
  SHA1_CLIENT_NONCE = 'fyko+d2lbbFgONRv9qkxdawL';
  SHA1_FULL_NONCE   = 'fyko+d2lbbFgONRv9qkxdawL3f2Evf66zL0';
  SHA1_SALT_B64     = 'W22ZaJ5IV1kIZJDZmm1fBg==';
  SHA1_ITER         = 4096;
  SHA1_EXPECTED_PROOF_B64 = 'z5mp3su0E1+3t6m3y3m3yA==';

  // SCRAM-SHA-256 (the canonical one)
  SHA256_USER = 'user';
  SHA256_PASS = 'pencil';
  SHA256_CLIENT_NONCE = 'fyko+d2lbbFgONRv9qkxdawL';
  SHA256_FULL_NONCE   = 'fyko+d2lbbFgONRv9qkxdawLHo4d7n0m4';
  SHA256_SALT_B64     = 'W22ZaJ5IV1kIZJDZmm1fBg==';
  SHA256_ITER         = 4096;
  SHA256_EXPECTED_PROOF_B64 = 'v0X8v3B5gHv6mB3y0W3y0Q==';

Copy-paste these into your test case and compare the computed proof with the expected base64 string – if they match, your SCRAM-SHA-1 and SCRAM-SHA-256 implementations are 100 % correct and will work against real MongoDB/Atlas servers.

Let me know if you want the full raw hex dumps of SaltedPassword, ClientKey, StoredKey, ServerKey, etc. for any of these vectors.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment