feature: ssl.get_shared_ssl_ciphers()

[chensunny]

SSL Shared Ciphers Implementation Summary

Overview

This implementation adds the get_shared_ssl_ciphers() function to lua-resty-core's SSL module, corresponding to the ngx_http_lua_ffi_req_shared_ssl_ciphers function from PR #2424 in lua-nginx-module.

🔗 Related Issues

Closed openresty/lua-nginx-module#1962
Closed openresty/lua-nginx-module#2424

Files Modified

1. /lib/ngx/ssl.lua

• Added FFI declarations for both HTTP and stream subsystems:
  • ngx_http_lua_ffi_req_shared_ssl_ciphers
  • ngx_stream_lua_ffi_req_shared_ssl_ciphers
• Added custom FFI struct ngx_lua_ssl_ciphers with flexible array
• Added function variable declaration and assignments
• Added required imports: ffi_copy, ffi_sizeof, ffi_typeof, ffi_new, format, concat
• Added TLS GREASE cipher constants for filtering
• Implemented comprehensive TLS cipher suite information table with:
  • TLS 1.3 ciphers (AES-GCM, ChaCha20-Poly1305, AES-CCM variants)
  • Common TLS 1.2 ciphers (ECDHE-RSA/ECDSA with various algorithms)
  • Rich metadata: IANA names, TLS versions, key exchange, authentication, encryption, hash algorithms
• Implemented elegant get_shared_ssl_ciphers() function in do...end block with:
  • Automatic GREASE filtering
  • Structured FFI object with metatype support
  • ipairs() iteration with detailed cipher information
  • tostring() for formatted cipher lists
  • Unknown cipher handling via metatable __index

2. /lib/ngx/ssl.md

• Added function to table of contents
• Added comprehensive documentation including:
  • Function syntax and context
  • Detailed description of returned object structure
  • Usage examples with ipairs() and rich cipher information
  • GREASE filtering explanation
  • Version information

3. /t/ssl.t

• Updated TEST 33 to work with new rich interface
• Tests structured object with ciphers.nciphers property
• Tests ipairs() iteration with cipher_info.iana_name
• Follows existing test patterns in the file

4. /examples/ssl_shared_ciphers.lua

• Updated example to demonstrate new rich interface
• Shows usage of ciphers.nciphers, ipairs(), and tostring()
• Demonstrates accessing detailed cipher information
• Includes TLS 1.3 cipher detection example

Function Details

Signature: ciphers = ssl.get_shared_ssl_ciphers()

Behavior:

• Returns intersection of server-supported and client-offered ciphers
• Automatically filters GREASE cipher values (RFC 8701)
• Returns structured FFI object with rich cipher information
• Works in any SSL context (not restricted to client_hello phase)

Returned Object:

• ciphers.nciphers: Number of shared ciphers
• Supports ipairs() iteration with detailed cipher info
• Supports tostring() for formatted cipher list
• Each cipher entry includes IANA name, TLS version, algorithms, etc.

Error Handling:

• Returns nil, error_string on failure
• Returns empty structure when no shared ciphers found

Implementation Notes

1. Advanced Data Structure: Uses custom FFI struct ngx_lua_ssl_ciphers with flexible array
2. Rich Cipher Information: Provides IANA names, TLS versions, and algorithm details
3. Elegant Interface: Supports ipairs() and tostring() through metatype
4. Memory Efficiency: Uses variable-length arrays instead of fixed buffers
5. GREASE Filtering: Filters out all 16 GREASE cipher values per RFC 8701
6. Cross-Platform: Supports both HTTP and stream subsystems
7. Consistent API: Follows same patterns as existing SSL functions
8. Encapsulated Design: All related code organized in do...end block

Testing

• Syntax validated with luac -p
• Test case updated to work with new rich interface
• Example usage provided demonstrating all features

Key Improvements Over Initial Design

The implementation has been significantly enhanced based on user feedback:

1. Structured Data: Moved from simple numeric array to rich FFI structure
2. Comprehensive Cipher Info: Added complete TLS cipher suite metadata
3. Elegant Iteration: Implemented ipairs() and tostring() support
4. Better Organization: Encapsulated all functionality in do...end block
5. Rich Documentation: Updated with detailed usage examples
6. Enhanced Testing: Updated test cases to verify new functionality

This implementation provides the lua-resty-core API for the SSL cipher enumeration functionality added in lua-nginx-module PR #2424, with significant enhancements for usability and functionality.