---
title: "SCRAM-SHA-256 Quick Reference"
---

# SCRAM-SHA-256 Quick Reference

Fast reference for SCRAM-SHA-256 authentication in HeliosDB Nano.

## Quick Setup

```rust
use heliosdb_nano::protocol::postgres::{
    PgServerBuilder, AuthMethod, AuthManager,
    InMemoryPasswordStore, SharedPasswordStore
};
use std::sync::Arc;

// 1. Create password store and add users
let mut store = InMemoryPasswordStore::new();
store.add_user("postgres", "password")?;

// 2. Wrap in shared store
let shared = SharedPasswordStore::new(store);

// 3. Create auth manager
let auth = Arc::new(
    AuthManager::with_password_store(AuthMethod::ScramSha256, shared)
);

// 4. Build server
let server = PgServerBuilder::new()
    .address("127.0.0.1:5432".parse()?)
    .auth_manager(auth)
    .build(db)?;
```

## Connect with psql

```bash
# Direct password
psql "host=127.0.0.1 port=5432 user=postgres password=password"

# Interactive prompt
psql "host=127.0.0.1 port=5432 user=postgres"

# With SSL
psql "sslmode=require host=127.0.0.1 port=5432 user=postgres password=password"
```

## User Management

```rust
let mut store = InMemoryPasswordStore::new();

// Add user
store.add_user("alice", "secret")?;

// Update password
store.update_password("alice", "new_secret")?;

// Remove user
store.remove_user("alice")?;

// Check existence
if store.user_exists("alice") { ... }

// List users
let users = store.list_users();
```

## Custom Iterations

```rust
// Higher security (slower)
let store = InMemoryPasswordStore::with_iterations(8192);

// Development (faster)
let store = InMemoryPasswordStore::with_iterations(4096);
```

## Authentication Methods

```rust
// SCRAM-SHA-256 (recommended)
AuthMethod::ScramSha256

// Trust (development only)
AuthMethod::Trust

// Cleartext (not recommended)
AuthMethod::CleartextPassword

// MD5 (legacy)
AuthMethod::Md5
```

## File Locations

| Component | File Path |
|-----------|-----------|
| Core Implementation | `src/protocol/postgres/auth.rs` |
| Password Store | `src/protocol/postgres/password_store.rs` |
| Protocol Handler | `src/protocol/postgres/handler.rs` |
| Tests | `tests/postgres_scram_auth_tests.rs` |
| Example | `examples/postgres_server_ssl.rs` |
| Documentation | `docs/SCRAM_SHA256_AUTHENTICATION.md` |

## Key Functions

```rust
// Credential preparation
let (stored_key, server_key) = prepare_scram_credentials(password, salt, iterations);

// Password verification
let creds = ScramCredentials::from_password("user".to_string(), "password", 4096);
assert!(creds.verify_password("password"));

// SCRAM auth state
let mut state = ScramAuthState::new("username".to_string());
state.set_client_nonce(nonce);
let server_first = state.build_server_first_message()?;
```

## Testing

```bash
# Run SCRAM tests
cargo test postgres_scram_auth_tests

# Run all protocol tests
cargo test --test '*protocol*'

# Run example
cargo run --example postgres_server_ssl
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "User not found" | Add user with `store.add_user(username, password)` |
| "Invalid password" | Update with `store.update_password(username, new_password)` |
| Slow auth | Reduce iterations (4096 is good for development) |
| Client errors | Ensure client supports SCRAM-SHA-256 (psql 10+) |

## Security Checklist

- Use SCRAM-SHA-256 in production
- Combine with SSL/TLS
- Use strong passwords (12+ chars)
- High iterations (8192+) for production
- Implement password rotation
- Log authentication events
- Use persistent password store

## Performance

| Configuration | Auth Time | Recommended For |
|---------------|-----------|-----------------|
| 4096 iterations | ~10ms | Development |
| 8192 iterations | ~20ms | Production |
| 16384 iterations | ~40ms | High Security |

## Common Patterns

### Development Setup
```rust
let auth = AuthManager::with_scram_store(AuthMethod::ScramSha256)
    .with_default_users();
```

### Production Setup with SSL
```rust
let server = PgServerBuilder::new()
    .address("0.0.0.0:5432".parse()?)
    .auth_manager(scram_auth_manager)
    .ssl_config(ssl_config)
    .build(db)?;
```

### Custom Password Store
```rust
struct MyPasswordStore { /* ... */ }

impl PasswordStore for MyPasswordStore {
    fn get_credentials(&self, username: &str) -> Option<ScramCredentials> { ... }
    fn add_user(&mut self, username: &str, password: &str) -> Result<()> { ... }
    fn remove_user(&mut self, username: &str) -> Result<bool> { ... }
    fn update_password(&mut self, username: &str, new_password: &str) -> Result<()> { ... }
    fn user_exists(&self, username: &str) -> bool { ... }
    fn list_users(&self) -> Vec<String> { ... }
}
```

## RFC References

- [RFC 5802 - SCRAM](https://tools.ietf.org/html/rfc5802)
- [RFC 7677 - SCRAM-SHA-256](https://tools.ietf.org/html/rfc7677)
- [PostgreSQL SCRAM](https://www.postgresql.org/docs/current/sasl-authentication.html)

## See Also

- [Complete Documentation](https://www.heliosdb.com/docs/nano/guides/quickstart/docs/scram_sha256_authentication/)