mssql_auth/
lib.rs

1//! # mssql-auth
2//!
3//! Authentication strategies for SQL Server connections.
4//!
5//! This crate provides various authentication methods, isolated from
6//! connection logic for better modularity and testing.
7//!
8//! ## Supported Authentication Methods
9//!
10//! | Method | Feature Flag | Status | Description |
11//! |--------|--------------|--------|-------------|
12//! | SQL Authentication | default | ✅ Implemented | Username/password |
13//! | Azure AD Token | default | ✅ Implemented | Pre-obtained access token |
14//! | Azure Managed Identity | `azure-identity` | ✅ Implemented | VM/container identity |
15//! | Service Principal | `azure-identity` | ✅ Implemented | App credentials |
16//! | Integrated (Kerberos) | `integrated-auth` | ✅ Implemented | GSSAPI/Kerberos (Linux/macOS) |
17//! | Windows SSPI | `sspi-auth` | ✅ Implemented | Native Windows SSPI |
18//! | Certificate | `cert-auth` | ⚠️ Token acquisition only¹ | Client certificate (mTLS) |
19//!
20//! ¹ `CertificateAuth` acquires tokens, but `mssql-client` does not yet wire
21//! certificate credentials into the login sequence; `Client::connect` rejects
22//! them with a clear error. Tracked in
23//! [#155](https://github.com/praxiomlabs/rust-mssql-driver/issues/155).
24//!
25//! The Azure AD methods use the FEDAUTH SecurityToken workflow: the token is
26//! acquired client-side and sent in the LOGIN7 FEDAUTH feature extension
27//! (see [`azure_ad::build_security_token_feature_data`]). The ADAL/MSAL
28//! workflow (server-directed acquisition via FEDAUTHINFO) is #155 Phase 2.
29//!
30//! ## Authentication Tiers
31//!
32//! Per ARCHITECTURE.md, authentication is tiered:
33//!
34//! ### Tier 1 (Core - Pure Rust, Default)
35//!
36//! - [`SqlServerAuth`] - Username/password via Login7 ✅ Implemented
37//! - [`AzureAdAuth`] - Pre-acquired access token ✅ Implemented
38//!
39//! ### Tier 2 (Azure Native - `azure-identity` feature) ✅ Implemented
40//!
41//! - `ManagedIdentityAuth` - Azure VM/Container identity
42//! - `ServicePrincipalAuth` - Client ID + Secret
43//!
44//! ### Tier 3 (Enterprise - `integrated-auth` or `sspi-auth` feature) ✅ Implemented
45//!
46//! - `IntegratedAuth` - Kerberos (Linux/macOS via GSSAPI)
47//! - `SspiAuth` - Windows SSPI (native Windows, cross-platform via sspi-rs)
48//!
49//! ### Tier 4 (Certificate - `cert-auth` feature) ⚠️ login wiring pending (#155)
50//!
51//! - `CertificateAuth` - Client certificate authentication (mTLS)
52//!
53//! ## Secure Credential Handling
54//!
55//! Enable the `zeroize` feature for secure credential handling:
56//!
57//! ```toml
58//! mssql-auth = { version = "0.1", features = ["zeroize"] }
59//! ```
60//!
61//! This enables secure credential handling that automatically zeroes
62//! sensitive data from memory when dropped.
63//!
64//! ## Example
65//!
66//! ```rust
67//! use mssql_auth::{SqlServerAuth, AzureAdAuth, AuthProvider};
68//!
69//! // SQL Server authentication
70//! let sql_auth = SqlServerAuth::new("sa", "Password123!");
71//! let auth_data = sql_auth.authenticate().unwrap();
72//!
73//! // Azure AD authentication with pre-acquired token
74//! let azure_auth = AzureAdAuth::with_token("eyJ0eXAi...");
75//! ```
76
77#![warn(missing_docs)]
78// Unsafe code is denied globally but allowed in the Windows CNG FFI module.
79// See windows_certstore.rs for detailed SAFETY comments on each unsafe block.
80#![deny(unsafe_code)]
81
82pub mod azure_ad;
83#[cfg(feature = "azure-identity")]
84pub mod azure_identity_auth;
85#[cfg(feature = "cert-auth")]
86pub mod cert_auth;
87pub mod credentials;
88pub mod encryption;
89pub mod error;
90#[cfg(feature = "integrated-auth")]
91pub mod integrated_auth;
92#[cfg(all(windows, feature = "sspi-auth"))]
93#[allow(unsafe_code)] // Windows SSPI FFI; see SAFETY comments in each unsafe block
94pub mod native_sspi;
95#[cfg(any(feature = "integrated-auth", feature = "sspi-auth"))]
96pub mod negotiator;
97pub mod provider;
98pub mod sql_auth;
99#[cfg(feature = "sspi-auth")]
100pub mod sspi_auth;
101
102// Always Encrypted cryptography
103#[cfg(feature = "always-encrypted")]
104pub mod aead;
105#[cfg(feature = "always-encrypted")]
106pub mod cek_envelope;
107#[cfg(feature = "always-encrypted")]
108pub mod key_store;
109#[cfg(feature = "always-encrypted")]
110pub mod key_unwrap;
111
112// Always Encrypted key providers
113#[cfg(feature = "azure-keyvault")]
114pub mod azure_keyvault;
115#[cfg(all(windows, feature = "windows-certstore"))]
116#[allow(unsafe_code)] // Windows CNG FFI; see SAFETY comments in each unsafe block
117pub mod windows_certstore;
118
119// Core types
120pub use credentials::Credentials;
121pub use error::AuthError;
122pub use provider::{AsyncAuthProvider, AuthData, AuthMethod, AuthProvider};
123
124// Authentication providers
125pub use azure_ad::{AzureAdAuth, FedAuthLibrary};
126pub use sql_auth::SqlServerAuth;
127
128// Secure credential types (with zeroize feature)
129#[cfg(feature = "zeroize")]
130pub use credentials::{SecretString, SecureCredentials};
131
132// Azure Identity authentication (with azure-identity feature)
133#[cfg(feature = "azure-identity")]
134pub use azure_identity_auth::{ManagedIdentityAuth, ServicePrincipalAuth};
135
136// Integrated authentication (Kerberos/GSSAPI - with integrated-auth feature)
137#[cfg(feature = "integrated-auth")]
138pub use integrated_auth::IntegratedAuth;
139
140// Certificate authentication (Azure AD with X.509 certificate - with cert-auth feature)
141#[cfg(feature = "cert-auth")]
142pub use cert_auth::CertificateAuth;
143
144// Native Windows SSPI authentication (with sspi-auth feature, Windows only)
145#[cfg(all(windows, feature = "sspi-auth"))]
146pub use native_sspi::NativeSspiAuth;
147
148// Windows SSPI authentication via sspi-rs (with sspi-auth feature)
149#[cfg(feature = "sspi-auth")]
150pub use sspi_auth::SspiAuth;
151
152// SSPI/GSSAPI negotiator trait (with integrated-auth or sspi-auth feature)
153#[cfg(any(feature = "integrated-auth", feature = "sspi-auth"))]
154pub use negotiator::SspiNegotiator;
155
156// Always Encrypted infrastructure
157pub use encryption::{
158    CekMetadata, ColumnEncryptionConfig, ColumnEncryptionInfo, EncryptedValue, EncryptionError,
159    EncryptionType, KeyStoreProvider,
160};
161
162// Always Encrypted cryptography (with always-encrypted feature)
163#[cfg(feature = "always-encrypted")]
164pub use aead::AeadEncryptor;
165#[cfg(feature = "always-encrypted")]
166pub use key_store::{CekCache, CekCacheKey, InMemoryKeyStore};
167#[cfg(feature = "always-encrypted")]
168pub use key_unwrap::RsaKeyUnwrapper;
169
170// Always Encrypted key providers
171#[cfg(feature = "azure-keyvault")]
172pub use azure_keyvault::AzureKeyVaultProvider;
173#[cfg(all(windows, feature = "windows-certstore"))]
174pub use windows_certstore::WindowsCertStoreProvider;
mssql_auth/lib.rs

mssql_auth/
lib.rs
