Add PSK cipher suites for DTLS 1.2 by jaredwolff · Pull Request #92 · algesten/dimpl

jaredwolff · 2026-03-10T17:41:17Z

Summary

Implement RFC 4279 PSK key exchange for DTLS 1.2 with TLS_PSK_WITH_AES_128_CCM_8 (0xC0A8)
- Only mandatory PSK cipher suite per RFC 7925 (IoT TLS/DTLS profile)
Add PskResolver trait for callback-based key lookup and Dtls::new_12_psk() constructor
Model PSK config as Psk enum with Client and Server variants
Unify certificate/PSK auth via AuthMode enum in CryptoContext and Engine
Add PskError variant for PSK-specific error conditions
AES-128-CCM-8 cipher via ccm crate, shared across both aws-lc-rs and RustCrypto backends
Handle servers that omit ServerKeyExchange when no PSK identity hint is provided (RFC 4279 §2)

Motivation

PSK support is needed for IoT devices (e.g., nRF9151 modem) that use pre-shared keys
instead of certificates for DTLS 1.2 authentication.

Test plan

Self-handshake and bidirectional data transfer tests for PSK_AES128_CCM_8
PSK identity validation tests (invalid identity rejected at Finished)
~~OpenSSL interop tests~~ Ignored (OpenSSL does not support CCM-8 over DTLS)
All existing tests continue to pass (48 tests + doctests)
cargo clippy clean

motters · 2026-03-10T23:11:30Z

I’ve been watching this repo for like 7 months, waiting for PSK support. PSK + CIDs + session resumption would finally unlock Rust for a lot of IoT use-cases where DTLS is everywhere.

jaredwolff · 2026-03-11T00:15:55Z

Its definitely been a long time coming for the rust eco system. Excited to get this out there.

I'll get working on the rebase. Looks like some conflicts.

Implement pure PSK key exchange (RFC 4279) with AES-128-CCM-8 AEAD (RFC 6655) for DTLS 1.2, targeting nRF9151 modem compatibility. - AES-128-CCM-8 cipher via RustCrypto `ccm` crate (both backends) - PSK handshake flow: skip Certificate/CertificateVerify states - PskResolver trait for callback-based key lookup - Dtls::new_12_psk() constructor (no certificate required) - Self-handshake + application data round-trip tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Reuses existing AES-128-GCM cipher and PSK handshake path from CCM-8, with standard 16-byte GCM authentication tag instead of 8-byte CCM tag. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…nal SKE - Add PSK_AES256_GCM_SHA384 (0x00A9) and PSK_CHACHA20_POLY1305_SHA256 (0xCCAB) to both crypto backends - Add bidirectional OpenSSL PSK interop tests (dimpl client/server) - Fix client to handle servers that omit ServerKeyExchange when no PSK identity hint is provided (RFC 4279 §2) - Fix ArrayVec capacity in detect.rs for expanded cipher suite list - Update lib.rs docs to list all supported PSK suites Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove "Not supported: PSK cipher suites" from README and lib.rs - Add all 4 PSK suites to cryptography surface in README and lib.rs - Add Dtls::new_12_psk to version selection section - Add PSK client example with PskResolver to lib.rs and README - Add "psk" keyword to Cargo.toml - Add PSK entries to CHANGELOG.md under Unreleased Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

HMBSbige · 2026-03-11T05:03:54Z

I took a quick look at the changes and noticed a potential issue: when a Config has both a certificate and a psk_resolver, new_12 (certificate mode) can still negotiate PSK suites, since is_cipher_suite_compatible() returns true for PSK (no signature_algorithm). This could let a peer downgrade the connection to PSK, skipping Certificate/CertificateRequest and bypassing require_client_certificate. Might be worth filtering out PSK suites in the certificate path, or catching this in build().

jaredwolff · 2026-03-11T05:11:25Z

Good catch. Let me get a fix in there for that.

Certificate-mode contexts (with a private key) could negotiate PSK suites, skipping Certificate/CertificateVerify and bypassing certificate authentication. Fix is_cipher_suite_compatible() to reject PSK suites when a private key is present, and filter PSK suites from dtls12_cipher_suites() when no PskResolver is configured. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

HMBSbige

I also noticed a couple of minor issues:

src/crypto/aws_lc_rs/cipher_suite.rs

src/crypto/rust_crypto/cipher_suite.rs

src/dtls12/server.rs

Reordered cipher list putting CCM_8 after AEAD. Added dummy-PSK fallback to avoid potential attacks to determinne valid identities. Test coverage for both scenarios. Signed-off-by: Jared Wolff <hello@jaredwolff.com>

jaredwolff · 2026-03-12T21:20:57Z

Addressing the CI issues shortly.

- Run cargo fmt to fix long lines in PSK tests and other files - Shorten 114-char comment lines in validation/mod.rs to fit 110-char limit - Add #[cfg(feature = "rcgen")] to context tests using generate_self_signed_certificate - Remove duplicate DrainedOutputs/drain_outputs/deliver_packets from edge.rs (use common module) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

algesten

Hi there! I have read through the code. Overall looks good, I think there are a couple of improvements to do.

The ambition of dimpl was never to be a generic DTLS implementation (beyond my own needs in WebRTC), however I'm not opposed to it going that direction. Although I'm not a crypto person, I'll remain the code steward for it, for now.

The PSK stuff goes beyond what I expect we'll use dimpl for ourselves, so accepting this into the tree also means we will be relying on yourself (and other volunteers) to stay on top of that part of the code. HMBSbige has already stepped up, so maybe that won't be much of a problem.

algesten · 2026-03-12T21:08:01Z

src/crypto/aws_lc_rs/cipher_suite.rs

+static PSK_AES_128_CCM_8: PskAes128Ccm8 = PskAes128Ccm8;
+static PSK_AES_128_GCM_SHA256: PskAes128GcmSha256 = PskAes128GcmSha256;
+static PSK_AES_256_GCM_SHA384: PskAes256GcmSha384 = PskAes256GcmSha384;
+static PSK_CHACHA20_POLY1305_SHA256: PskChaCha20Poly1305Sha256 = PskChaCha20Poly1305Sha256;


@jaredwolff @HMBSbige When I set out to make the dimpl crate, I deliberately selected a very narrow set of ciphers. Only the ones I know are often used in WebRTC (three of them).

With this PSK PR, we are adding 4 new, which means we have more PSK cipher suites than we have non-PSK, which is quite at odds with the narrow focus of where I started.

I'm not saying we can't do this, but is it strictly necessary? Are some of these suites rarely or almost never used?

We can definitely pair this back. It wasn't a big deal to add them. For embedded (my use case) the most secure that our device supports in an offloaded manor (handled by the hardware) is TLS-PSK-WITH-AES-128-CCM-8. Ideally ECDHE-PSK + AEAD as it's more secure. Maybe it's worth just having those two. Offloading to mbedTLS is expensive when it comes to code space. (which is what we would use to get the more secure cipher)

More research:

RFC 7925 (DTLS + IoT) - PSK_AES_128_CCM_8 is considered a MUST
LwM2M (which is just a beefier CoAP client) - again PSK_AES_128_CCM_8 is considered a MUST

So I went overboard a bit. 😇 Stay tuned for a refactor.

src/dtls12/client.rs

src/dtls12/engine.rs

src/config.rs

Remove PSK_AES128_GCM_SHA256, PSK_AES256_GCM_SHA384, and PSK_CHACHA20_POLY1305_SHA256 — only TLS_PSK_WITH_AES_128_CCM_8 is mandated by IoT standards (RFC 7925, LwM2M). This keeps the PSK surface minimal and aligned with dimpl's narrow-focus philosophy. Architectural changes per review feedback: - Model PSK config as Psk enum (Client/Server) replacing three loose fields; builder API becomes with_psk_client/with_psk_server - Unify CryptoContext constructors via AuthMode enum (Certificate/Psk) - Merge Engine::new and Engine::new_psk into single constructor - Add Error::PskError variant for PSK-specific errors - Move Debug impls to bottom of config.rs before tests - Fix code ordering: PSK branches before ECDHE in client.rs - Import ServerKeyExchangeParams properly instead of inline path - Remove dead code: get_key_exchange_group_info, _group_info, CurveType - Export Psk, ConfigBuilder from public API - Mark OpenSSL PSK interop tests #[ignore] (OpenSSL excludes CCM-8 from DTLS) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jaredwolff · 2026-03-13T04:53:09Z

Probably a good candidate for a squashed commit everything is hashed out. Thanks again all.

jaredwolff and others added 4 commits March 10, 2026 21:03

Add TLS_PSK_WITH_AES_128_GCM_SHA256 (0x00A8) cipher suite

ccf3692

Reuses existing AES-128-GCM cipher and PSK handshake path from CCM-8, with standard 16-byte GCM authentication tag instead of 8-byte CCM tag. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jaredwolff force-pushed the psk-support branch from bcf1ce5 to 8c1ad4b Compare March 11, 2026 01:04

jaredwolff force-pushed the psk-support branch from 1031234 to dc77600 Compare March 11, 2026 05:24

HMBSbige suggested changes Mar 11, 2026

View reviewed changes

src/crypto/aws_lc_rs/cipher_suite.rs Show resolved Hide resolved

src/crypto/rust_crypto/cipher_suite.rs Show resolved Hide resolved

src/dtls12/server.rs Outdated Show resolved Hide resolved

fix: harden invalid-identity handling

892326b

Reordered cipher list putting CCM_8 after AEAD. Added dummy-PSK fallback to avoid potential attacks to determinne valid identities. Test coverage for both scenarios. Signed-off-by: Jared Wolff <hello@jaredwolff.com>

jaredwolff force-pushed the psk-support branch from ed59485 to c754701 Compare March 12, 2026 21:52

algesten reviewed Mar 12, 2026

View reviewed changes

jaredwolff force-pushed the psk-support branch from 62fadcc to 8b3f4c3 Compare March 13, 2026 03:23

jaredwolff force-pushed the psk-support branch from 8b3f4c3 to fe24c71 Compare March 13, 2026 03:44

Conversation

jaredwolff commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Test plan

Uh oh!

motters commented Mar 10, 2026

Uh oh!

jaredwolff commented Mar 11, 2026

Uh oh!

HMBSbige commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jaredwolff commented Mar 11, 2026

Uh oh!

HMBSbige left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jaredwolff commented Mar 12, 2026

Uh oh!

algesten left a comment

Choose a reason for hiding this comment

Uh oh!

algesten Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

jaredwolff Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

jaredwolff Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jaredwolff commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jaredwolff commented Mar 10, 2026 •

edited

Loading

HMBSbige commented Mar 11, 2026 •

edited

Loading