/ 
Hypersonic-0.11
/ Hypersonic::TLS

NAME

Hypersonic::TLS - TLS/HTTPS support for Hypersonic

SYNOPSIS

use Hypersonic;

# Create an HTTPS server
my $server = Hypersonic->new(
    tls       => 1,
    cert_file => '/path/to/cert.pem',
    key_file  => '/path/to/key.pem',
);

$server->get('/api/secure' => sub { '{"secure":true}' });
$server->compile();
$server->run(port => 8443);

# Generate self-signed certificate for testing
# openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
#   -days 365 -nodes -subj "/CN=localhost"

DESCRIPTION

Hypersonic::TLS provides TLS/HTTPS support for the Hypersonic HTTP server using OpenSSL. The TLS handshake and encryption/decryption are JIT-compiled to native XS code for maximum performance.

This module is used internally by Hypersonic when TLS is enabled. You typically don't need to use it directly.

REQUIREMENTS

  • OpenSSL development libraries

  • Alien::OpenSSL (recommended for portability)

Installing OpenSSL

macOS (Homebrew):

brew install openssl@3

Debian/Ubuntu:

apt-get install libssl-dev

RHEL/CentOS/Fedora:

yum install openssl-devel

Using Alien::OpenSSL (recommended):

cpanm Alien::OpenSSL

USAGE

TLS is enabled via the main Hypersonic constructor:

use Hypersonic;

my $server = Hypersonic->new(
    tls       => 1,                    # Enable TLS
    cert_file => 'cert.pem',           # Certificate file (required)
    key_file  => 'key.pem',            # Private key file (required)
);

Certificate Files

The certificate and key files must be in PEM format:

cert_file

PEM-encoded X.509 certificate (or certificate chain)

key_file

PEM-encoded private key (RSA, ECDSA, or Ed25519)

Certificate Chain

For production, include the full certificate chain in cert_file:

cat server.crt intermediate.crt root.crt > fullchain.pem

CLASS METHODS

check_openssl

if (Hypersonic::TLS::check_openssl()) {
    # OpenSSL is available
}

Returns true if OpenSSL is available for compilation.

Checks:

1. Alien::OpenSSL availability (preferred)
2. System OpenSSL via test compilation

compile_tls_ops

Hypersonic::TLS->compile_tls_ops(
    cache_dir => '_tls_cache',
);

Compile the TLS operations to XS. Called automatically when TLS is enabled in the server constructor.

get_extra_cflags

my $cflags = Hypersonic::TLS::get_extra_cflags();
# e.g., "-I/opt/homebrew/opt/openssl@3/include"

Returns extra compiler flags for OpenSSL include paths.

get_extra_ldflags

my $ldflags = Hypersonic::TLS::get_extra_ldflags();
# e.g., "-L/opt/homebrew/opt/openssl@3/lib -lssl -lcrypto"

Returns extra linker flags for OpenSSL.

CODE GENERATION METHODS

These methods generate C code fragments included in the compiled server.

gen_includes

Returns C code for OpenSSL includes:

#include <openssl/ssl.h>
#include <openssl/err.h>

gen_ssl_ctx_init

Returns C code to initialize the SSL context with certificate/key.

gen_ssl_accept

Returns C code for TLS handshake on new connections.

gen_ssl_io

Returns C code for TLS-encrypted read/write operations.

gen_ssl_close

Returns C code for clean TLS connection shutdown.

SECURITY FEATURES

Protocol Version

  • TLS 1.2 minimum (TLS 1.0/1.1 disabled by default)

  • TLS 1.3 supported if available

Best Practices

  • Private key permissions should be 0600 (owner read only)

  • Use strong cipher suites in production

  • Enable HSTS header (Strict-Transport-Security)

  • Keep OpenSSL updated

Security Headers

When TLS is enabled, Hypersonic automatically adds HSTS header:

Strict-Transport-Security: max-age=31536000; includeSubDomains

PERFORMANCE

TLS operations are JIT-compiled with:

  • Session resumption for reduced handshake overhead

  • Optimized buffer handling

  • Direct OpenSSL API calls (no Perl layer)

TESTING TLS

Generate a self-signed certificate for testing:

# Generate certificate and key
openssl req -x509 -newkey rsa:2048 \
    -keyout key.pem -out cert.pem \
    -days 365 -nodes \
    -subj "/CN=localhost"

# Test with curl (skip verification for self-signed)
curl -k https://localhost:8443/api/test

TROUBLESHOOTING

"TLS support not available"

OpenSSL not found. Install it:

# macOS
brew install openssl@3

# Or use Alien::OpenSSL
cpanm Alien::OpenSSL

"cert_file not found"

Verify the certificate file path is correct and readable.

"Failed to initialize TLS context"

Check that:

  • Certificate and key match (same public key)

  • Key file is in PEM format

  • Key file has correct permissions

Verify with:

openssl x509 -noout -modulus -in cert.pem | md5
openssl rsa -noout -modulus -in key.pem | md5

Both commands should output the same MD5 hash.

EXAMPLE

Complete HTTPS server:

use Hypersonic;
use Hypersonic::Response 'res';

my $server = Hypersonic->new(
    tls       => 1,
    cert_file => 'fullchain.pem',
    key_file  => 'privkey.pem',
    
    # Security hardening
    max_request_size => 16384,
    enable_security_headers => 1,
);

$server->get('/api/status' => sub {
    res->json({ status => 'ok', tls => 'enabled' });
}, { dynamic => 1 });

$server->compile();
$server->run(port => 8443, workers => 4);

SEE ALSO

Hypersonic - Main HTTP server module

Alien::OpenSSL - Portable OpenSSL installation

https://www.openssl.org/ - OpenSSL documentation

AUTHOR

LNATION <email@lnation.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.