Add DTLS 1.2 PSK authentication (RFC 4279)

Adds pre-shared key support with TLS_PSK_WITH_AES_128_CCM_8 (0xC0A8),
the cipher mandated by RFC 7925 / LwM2M for constrained IoT devices.

Public API:
- Psk enum (Client { identity, resolver } / Server { hint, resolver })
- PskResolver trait for callback-based key lookup
- ConfigBuilder::with_psk_client / with_psk_server
- Dtls::new_12_psk constructor for PSK-only sessions
- Error::PskError variant

Internals:
- AuthMode enum unifies Certificate and PSK paths in CryptoContext
- ccm_cipher module implements AES-128-CCM-8 AEAD
- ClientKeyExchange / ServerKeyExchange gain PSK variants
- PSK cipher suite wired into both aws-lc-rs and rust-crypto backends
- Client handles servers that omit ServerKeyExchange when no identity
  hint is present (RFC 4279 §2)

Config validation:
- Reject PSK configs where DTLS 1.2 has no PSK suite after filtering,
  regardless of DTLS 1.3 state (DTLS 1.3 is not a fallback for
  Dtls::new_12_psk, and DTLS 1.3 PSK is a separate mechanism)
- Require kx groups whenever a cert-based DTLS 1.2 suite survives the
  filter, even when PSK is also configured
- require_client_certificate documented as cert-only

Security:
- Certificate-mode contexts reject PSK suites, preventing downgrade
  past Certificate/CertificateVerify
- PSK suites filtered from advertised list when no resolver configured
- Invalid-identity handling uses a dummy-PSK fallback plus an explicit
  psk_valid flag to avoid a timing oracle that would otherwise leak
  identity validity
- CCM_8 ordered after AEAD suites in the default list

Tests:
- tests/dtls12/psk.rs covers the PSK handshake and edge cases
- Config-builder validation tests for PSK + DTLS 1.3, PSK + cert
  suites, and PSK-only empty-kx-groups cases
- OpenSSL interop tests included but #[ignore]d (OpenSSL excludes
  CCM-8 from DTLS)

Docs: README, CHANGELOG, and module docs updated.

Signed-off-by: Jared Wolff <hello@jaredwolff.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jaredwolff

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Unreleased
 
+  * Add PSK (Pre-Shared Key) cipher suite for DTLS 1.2 (RFC 4279, RFC 7925)
+    * `PSK_AES128_CCM_8` (0xC0A8)
+  * Add `Dtls::new_12_psk()` constructor for PSK-only sessions
+  * Add `PskResolver` trait and PSK config builder methods
+  * Fix client to handle optional ServerKeyExchange in PSK handshakes (RFC 4279 §2)
   * Fix DTLS 1.2 signature hash mismatch for P-384 keys #97
 
 # 0.5.0

Cargo.lock

@@ -7,7 +7,7 @@ edition = "2024"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/algesten/dimpl"
 readme = "README.md"
-keywords = ["dtls", "tls", "webrtc"]
+keywords = ["dtls", "tls", "webrtc", "psk"]
 categories = ["network-programming", "cryptography", "security"]
 
 # MSRV
@@ -17,13 +17,14 @@ rust-version = "1.85.0"
 default = ["aws-lc-rs", "rcgen"]
 
 # Default crypto provider
-aws-lc-rs = ["dep:aws-lc-rs", "_crypto-common"]
+aws-lc-rs = ["dep:aws-lc-rs", "dep:ccm", "dep:aes", "_crypto-common"]
 
 # Pure Rust crypto provider
 rust-crypto = [
             "dep:aes-gcm", "dep:chacha20poly1305", "dep:chacha20", "dep:p256",
             "dep:p384", "dep:x25519-dalek", "dep:sha2", "dep:hmac", "dep:hkdf",
             "dep:ecdsa", "dep:generic-array", "dep:rand_core",
+            "dep:ccm", "dep:aes",
             "_crypto-common"
 ]
 
@@ -68,6 +69,8 @@ generic-array = { version = "0.14", optional = true }
 rand_core = { version = "0.6", optional = true }
 chacha20poly1305 = { version = "0.10", optional = true }
 chacha20 = { version = "0.9", optional = true }
+ccm = { version = "0.5", default-features = false, optional = true }
+aes = { version = "0.8", optional = true }
 x25519-dalek = { version = "2", optional = true, features = ["static_secrets"] }
 
 # certificate generation

Cargo.toml

@@ -22,8 +22,9 @@ verification and SRTP key export yourself.
 
 ### Version selection
 
-Three constructors control which DTLS version is used:
-- [`Dtls::new_12`][new_12] — explicit DTLS 1.2
+Four constructors control which DTLS version is used:
+- [`Dtls::new_12`][new_12] — explicit DTLS 1.2 (certificate‑based)
+- [`Dtls::new_12_psk`][new_12_psk] — explicit DTLS 1.2 (PSK, no certificates)
 - [`Dtls::new_13`][new_13] — explicit DTLS 1.3
 - [`Dtls::new_auto`][new_auto] — auto‑sense: the first
   incoming ClientHello determines the version (based on the
@@ -34,6 +35,8 @@ Three constructors control which DTLS version is used:
   - `ECDHE_ECDSA_AES256_GCM_SHA384`
   - `ECDHE_ECDSA_AES128_GCM_SHA256`
   - `ECDHE_ECDSA_CHACHA20_POLY1305_SHA256`
+- **PSK cipher suites (TLS 1.2 over DTLS)**
+  - `PSK_AES128_CCM_8`
 - **Cipher suites (TLS 1.3 over DTLS)**
   - `TLS_AES_128_GCM_SHA256`
   - `TLS_AES_256_GCM_SHA384`
@@ -44,7 +47,6 @@ Three constructors control which DTLS version is used:
 - **DTLS‑SRTP**: Exports keying material for `SRTP_AEAD_AES_256_GCM`,
   `SRTP_AEAD_AES_128_GCM`, and `SRTP_AES128_CM_SHA1_80` ([RFC 5764], [RFC 7714]).
 - **Extended Master Secret** ([RFC 7627]) is negotiated and enforced (DTLS 1.2).
-- Not supported: PSK cipher suites.
 
 ### Certificate model
 During the handshake the engine emits
@@ -131,6 +133,37 @@ let dtls = mk_dtls_client();
 let _ = example_event_loop(dtls);
 ```
 
+## Example (PSK client)
+
+```rust
+use std::sync::Arc;
+use std::time::Instant;
+
+use dimpl::{Config, Dtls, PskResolver};
+
+struct MyPsk;
+
+impl PskResolver for MyPsk {
+    fn resolve(&self, identity: &[u8]) -> Option<Vec<u8>> {
+        if identity == b"device-01" {
+            Some(b"shared-secret-key".to_vec())
+        } else {
+            None
+        }
+    }
+}
+
+let config = Arc::new(
+    Config::builder()
+        .with_psk_client(b"device-01".to_vec(), Arc::new(MyPsk))
+        .build()
+        .unwrap(),
+);
+
+let mut dtls = Dtls::new_12_psk(config, Instant::now());
+dtls.set_active(true); // client role
+```
+
 #### MSRV
 Rust 1.85.0
 
@@ -139,6 +172,7 @@ Rust 1.85.0
 - Renegotiation is not implemented (WebRTC does full restart).
 
 [new_12]: https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_12
+[new_12_psk]: https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_12_psk
 [new_13]: https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_13
 [new_auto]: https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_auto
 [peer_cert]: https://docs.rs/dimpl/latest/dimpl/enum.Output.html#variant.PeerCert

README.md

@@ -105,7 +105,7 @@ impl HybridClientHello {
         ch_body.push(0);
 
         // cipher_suites: 1.3 suites first, then 1.2 suites (filtered by config)
-        let mut suites: ArrayVec<u16, 8> = ArrayVec::new();
+        let mut suites: ArrayVec<u16, 16> = ArrayVec::new();
         for cs in config.dtls13_cipher_suites() {
             suites.push(cs.suite().as_u16());
         }