Documenting how to use OpenSSL::SSL::SSLContext in PQC use cases

Open
#1,118 6 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@junaruga is already working on this.

Since Oct 26, 2026.

  • #1131 by @junaruga — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
55/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
ruby

Research direction

Start by reviewing the examples in ruby-pqc-test/openssl and ruby-pqc-test/openssl/script, along with the referenced OpenSSL workflow. Then inspect html/OpenSSL.html, html/OpenSSL/SSL/SSLContext.html, and html/OpenSSL/SSL/SSLSocket.html to determine the best placement for the PQC guidance. Done means the generated RDoc pages explain the relevant SSLContext and socket APIs with ML-DSA and ML-KEM examples.

Written by the indexing model from the issue text.

Description

The ruby/drb started to support PQC by the PR https://github.com/ruby/drb/pull/62. The approach is that drb accepts OpenSSL::SSL::SSLContext object from users. However, drb users need to understand how to create OpenSSL::SSL::SSLContext instance for PQC use cases. The usages are such as using #groups= to specify the key exchange algorithm with ML-KEM, and using #sigalgs= to specify signature algorithms with ML-DSA only for ML-DSA cert server, or ML-DSA/RSA for ML-DSA/RSA multiple cert server.

I created the following Ruby scripts to show the examples of OpenSSL::SSL::SSLContext in some PQC server/client cases with ML-DSA single certificate server and ML-DSA/RSA multiple certificate server.

I want to document the usages of OpenSSL::SSL::SSLContext in PQC use cases in ruby/openssl, to fill the knowledge gap, and guide users of other ruby/* libraries accepting or exposing OpenSSL::SSL::SSLContext instance.

I want to update the following generated rdoc documents, adding the PQC related contents with code examples.

  • html/OpenSSL.html - This document shows topic-based code examples on the top of the page. So, adding new section "Post-Quantum Cryptography" or/and "ML-DSA Encryption".
  • html/OpenSSL/SSL/SSLContext.html - #groups=, #sigalgs=
  • html/OpenSSL/SSL/SSLSocket.html - #group, #sigalg, #peer_sigalg

I am still considering what is the best to document this topic. What do you think? Is there a good idea about where and how to document this topic?

Dominant language
C
Stars
276
Forks
205
Avg merge
21h 17m
Merged PRs (30d)
17

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ruby/openssl

All issues in ruby/openssl

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.