Add `OpenSSL::SSL::Context::Server#on_server_name` for SNI by carlhoerberg · Pull Request #16452 · crystal-lang/crystal

carlhoerberg · 2025-11-29T08:47:41Z

Summary

Adds on_server_name method to OpenSSL::SSL::Context::Server for Server Name Indication (SNI) support
Allows TLS servers to present different certificates based on the client's requested hostname
Enables virtual hosting over TLS with a single listening socket

Example

default_context = OpenSSL::SSL::Context::Server.new
default_context.certificate_chain = "default.crt"
default_context.private_key = "default.key"

example_context = OpenSSL::SSL::Context::Server.new
example_context.certificate_chain = "example.com.crt"
example_context.private_key = "example.com.key"

default_context.on_server_name do |hostname|
  case hostname
  when "example.com", "www.example.com"
    example_context
  else
    nil # use default context
  end
end

Test plan

Added spec for on_server_name method in context_spec.cr
Added end-to-end spec in socket_spec.cr that verifies the callback receives the client hostname

🤖 Generated with Claude Code

This adds Server Name Indication (SNI) callback support, allowing TLS servers to present different certificates based on the hostname the client is connecting to. The `set_sni_callback` method accepts a block that receives the client's requested hostname and returns either a configured `SSL::Context::Server` for that hostname, or `nil` to continue using the default context. Example: ```crystal default_context.set_sni_callback do |hostname| case hostname when "example.com" example_context else nil end end ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Also use null pointer instead of nilable type for callback box, matching the existing pattern for @alpn_protocol. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

src/openssl/ssl/context.cr

spec/std/openssl/ssl/context_spec.cr

spec/std/openssl/ssl/socket_spec.cr

src/openssl/ssl/context.cr

Co-authored-by: Johannes Müller <straightshoota@gmail.com>

Let exceptions propagate naturally instead of silently swallowing them. This is consistent with other OpenSSL callbacks in the same file (set_cert_verify_callback, alpn_protocol=) which don't have exception handling either. Exceptions will bubble up through the libssl stack and surface at the SSL_accept call, where they can be properly handled by Crystal code. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

C callbacks must always return an error code, never raise - letting exceptions unwind through the C stack is unsafe as libssl cannot do its cleanup. On any exception in the SNI callback, set the alert pointer to SSL_AD_INTERNAL_ERROR and return SSL_TLSEXT_ERR_ALERT_FATAL. This lets OpenSSL handle the error properly and terminate the handshake with an appropriate alert. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Verifies that when the SNI callback raises an exception, the server returns an SSL error (via ALERT_FATAL) rather than crashing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

src/openssl/ssl/context.cr

Co-authored-by: Julien Portalier <julien@portalier.com>

straight-shoota · 2025-12-03T15:11:56Z

Apparently this is broken in the interpreter. Perhaps we could just skip the spec in interpreted mode? With a note that this leads to invalid memory access.

And Crystal 1.0 doesn't seem to support the proc literal syntax. Might be best to use Proc.new instead: Proc(LibSSL::SSL, LibC::Int*, Void*, LibC::Int).new { |ssl, alert_ptr, arg|

src/openssl/ssl/context.cr

Co-authored-by: Sijawusz Pur Rahnama <sija@sija.pl>

src/openssl/ssl/context.cr

ysbaddaden

Just a polish change to make sure the c callback is properly validated by the compiler (no closure data) when sent to the OpenSSL function.

src/openssl/lib_ssl.cr

src/openssl/ssl/context.cr

This commit corrects the type signature for the SSL_CTX_callback_ctrl C binding to prevent memory safety issues related to garbage collection and closures. Co-authored-by: Julien Portalier <julien@portalier.com>

straight-shoota · 2025-12-10T13:44:32Z

I have some ideas for improving this feature: #16494

carlhoerberg · 2025-12-16T22:38:50Z

We've started to notice GC Warning: Finalization cycle involving (???) when running SNI specs. We suspect it's related to the storage of the callback, @sni_callback_box. One way we can avoid it is to use a class level hash for storing the callback box, and deleting it in the finalizer, but that seems less than optimal..

ysbaddaden · 2025-12-17T11:02:00Z

I assume the issue comes from the captured block closure: it can have direct references to other contexts and trying to finalize one context leads the GC to identify a circular finalization... which isn't an issue because the finalizer only accesses the object itself.

I wish there was a way to tell the GC to skip the check (unsafe finalizer).

carlhoerberg · 2025-12-17T19:14:32Z

I wish there was a way to tell the GC to skip the check (unsafe finalizer).

how about GC_register_finalizer_ignore_self? https://github.com/bdwgc/bdwgc/blob/master/docs/finalization.md#getting-around-topological-finalization-ordering

straight-shoota · 2025-12-19T13:42:35Z

We already use GC_register_finalizer_ignore_self for all finalizers:

crystal/src/gc/boehm.cr

Lines 338 to 343 in 37cdfa7

    
           private def self.add_finalizer_impl(object : T) forall T 
        
             LibGC.register_finalizer_ignore_self(object.as(Void*), 
        
               ->(obj, data) { obj.as(T).finalize }, 
        
               nil, nil, nil) 
        
             nil 
        
           end

Crystal 1.19.0 includes it, which cause a conflict: In src/stdlib/openssl_sni.cr:13:3 13 | SSL_CTRL_SET_TLSEXT_SERVERNAME_CB = 53 ^-------------------------------- Error: already initialized constant LibSSL::SSL_CTRL_SET_TLSEXT_SERVERNAME_CB Replace custom openssl_sni.cr monkey-patch with the new on_server_name callback added in crystal-lang/crystal#16452 by us This has only been tested by existing specs.

carlhoerberg and others added 2 commits November 29, 2025 09:47

Rename set_sni_callback to on_server_name

9970c76

Also use null pointer instead of nilable type for callback box, matching the existing pattern for @alpn_protocol. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

carlhoerberg changed the title ~~Add SNI callback support to OpenSSL::SSL::Context::Server~~ Add SNI support via on_server_name callback to OpenSSL::SSL::Context::Server Nov 29, 2025

straight-shoota reviewed Nov 29, 2025

View reviewed changes

src/openssl/ssl/context.cr Show resolved Hide resolved

spec/std/openssl/ssl/context_spec.cr Show resolved Hide resolved

spec/std/openssl/ssl/socket_spec.cr Outdated Show resolved Hide resolved

src/openssl/ssl/context.cr Show resolved Hide resolved

carlhoerberg and others added 5 commits November 30, 2025 21:17

Only keep reference to the Box

38ee6e3

Co-authored-by: Johannes Müller <straightshoota@gmail.com>

Simplify spec

7cae09c

Co-authored-by: Johannes Müller <straightshoota@gmail.com>

carlhoerberg force-pushed the openssl-sni branch from d56814d to 88773e2 Compare December 1, 2025 12:02

ysbaddaden approved these changes Dec 1, 2025

View reviewed changes

src/openssl/ssl/context.cr Outdated Show resolved Hide resolved

Tidy up

92754a1

Co-authored-by: Julien Portalier <julien@portalier.com>

straight-shoota approved these changes Dec 3, 2025

View reviewed changes

straight-shoota added kind:feature topic:stdlib:crypto labels Dec 3, 2025

carlhoerberg added 2 commits December 3, 2025 18:57

Mark some socket specs as pending with interpreter

cc809b8

use a Proc instead of proc literal for crystal 1.0.0 compability

a725d19

straight-shoota approved these changes Dec 3, 2025

View reviewed changes

ysbaddaden approved these changes Dec 4, 2025

View reviewed changes

ysbaddaden added this to the 1.19.0 milestone Dec 4, 2025

Sija reviewed Dec 4, 2025

View reviewed changes

src/openssl/ssl/context.cr Outdated Show resolved Hide resolved

Update src/openssl/ssl/context.cr

ccd3bff

Co-authored-by: Sijawusz Pur Rahnama <sija@sija.pl>

Sija reviewed Dec 5, 2025

View reviewed changes

src/openssl/ssl/context.cr Outdated Show resolved Hide resolved

ysbaddaden reviewed Dec 5, 2025

View reviewed changes

src/openssl/lib_ssl.cr Outdated Show resolved Hide resolved

src/openssl/ssl/context.cr Outdated Show resolved Hide resolved

Correct OpenSSL C Binding for SNI Callback Safety

9f51a3f

This commit corrects the type signature for the SSL_CTX_callback_ctrl C binding to prevent memory safety issues related to garbage collection and closures. Co-authored-by: Julien Portalier <julien@portalier.com>

ysbaddaden approved these changes Dec 8, 2025

View reviewed changes

straight-shoota approved these changes Dec 8, 2025

View reviewed changes

straight-shoota changed the title ~~Add SNI support via on_server_name callback to OpenSSL::SSL::Context::Server~~ Add OpenSSL::SSL::Context::Server#on_server_name for SNI Dec 8, 2025

straight-shoota merged commit e80f29f into crystal-lang:master Dec 10, 2025
47 of 48 checks passed

straight-shoota mentioned this pull request Dec 10, 2025

Rethinking the SSL::Server#on_server_name API #16494

Open

straight-shoota mentioned this pull request Dec 17, 2025

OpenSSL::SSL::Server#accept raises when a connection attempt fails #16515

Open

straight-shoota mentioned this pull request Dec 19, 2025

Mark SSL::Context#on_server_name as experimental [fixup #16452] #16525

Merged

jage mentioned this pull request Jan 16, 2026

Crystal 1.19.0 compatibility cloudamqp/lavinmq#1616

Closed

jage mentioned this pull request Jan 16, 2026

Use Crystal stdlib SNI implementation cloudamqp/lavinmq#1618

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add `OpenSSL::SSL::Context::Server#on_server_name` for SNI#16452

Add `OpenSSL::SSL::Context::Server#on_server_name` for SNI#16452
straight-shoota merged 12 commits intocrystal-lang:masterfrom
carlhoerberg:openssl-sni

carlhoerberg commented Nov 29, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

straight-shoota commented Dec 3, 2025

Uh oh!

Uh oh!

Uh oh!

ysbaddaden left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

straight-shoota commented Dec 10, 2025

Uh oh!

carlhoerberg commented Dec 16, 2025

Uh oh!

ysbaddaden commented Dec 17, 2025

Uh oh!

carlhoerberg commented Dec 17, 2025

Uh oh!

straight-shoota commented Dec 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

carlhoerberg commented Nov 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Example

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

straight-shoota commented Dec 3, 2025

Uh oh!

Uh oh!

Uh oh!

ysbaddaden left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

straight-shoota commented Dec 10, 2025

Uh oh!

carlhoerberg commented Dec 16, 2025

Uh oh!

ysbaddaden commented Dec 17, 2025

Uh oh!

carlhoerberg commented Dec 17, 2025

Uh oh!

straight-shoota commented Dec 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

carlhoerberg commented Nov 29, 2025 •

edited

Loading