Add diagrams for minimal examples in wiki and liboqs documentation

[anvega]

I've created Mermaid diagrams for the two minimal examples currently in the liboqs wiki and the examples on the docs site. These aim to enhance the understanding of the key encapsulation and digital signature processes.

• Initially discussed on Discord (conversation summary attached below)
• The wiki isn't directly in the project repository, making direct contributions challenging
• There's interest in incorporating these diagrams into the documentation

Proposal:

1. I'd like to have these reviewed for which I'll file a PR to the site repo
2. Once reviewed and approved, consider adding them to the wiki as well

I'll share the code for these diagrams. The way it's rendered in the wiki of my fork. GitHub can render this directly from markdown, but I can also provide PNG exports if preferred.

Questions:

1. What's the preferred format for submitting these diagrams? (Mermaid code, PNG, or both?)
2. Are there any specific style guidelines I should follow for consistency with existing documentation?
3. Where in the docs would these diagrams be most beneficial?

I'm happy to submit a PR to contribute these diagrams to the project once I have some guidance on the above questions.

[anvega]

liboqs Key Encapsulation Mechanism (KEM) Process from Minimal example of a post quantum KEM

sequenceDiagram
    participant A as Alice (Encapsulator)
    participant B as Bob (Decapsulator)
    participant KEM as OQS_KEM

    Note over B: Key Generation
    B->>KEM: OQS_KEM_keypair()
    KEM-->>B: public_key, secret_key

    B->>A: Send public_key

    Note over A: Encapsulation
    A->>KEM: OQS_KEM_encaps(public_key)
    KEM-->>A: ciphertext, shared_secret_e

    A->>B: Send ciphertext

    Note over B: Decapsulation
    B->>KEM: OQS_KEM_decaps(ciphertext, secret_key)
    KEM-->>B: shared_secret_d

    Note over A,B: shared_secret_e == shared_secret_d

    Note over A,B: Clean up
    A->>A: OQS_MEM_cleanse(shared_secret_e)
    B->>B: OQS_MEM_cleanse(secret_key, shared_secret_d)

Loading

[anvega]

liboqs Post-Quantum Signature Process from Minimal example of a post quantum signature

sequenceDiagram
    participant A as Alice (Signer)
    participant B as Bob (Verifier)
    participant SIG as Signature Algorithm

    Note over A,B: Key Generation (performed once)
    A->>SIG: OQS_SIG_keypair()
    SIG->>A: public_key, secret_key

    Note over A,B: Signature Generation
    A->>A: Prepare message
    A->>SIG: OQS_SIG_sign(message, secret_key)
    SIG->>A: signature

    A->>B: Send message, signature, public_key

    Note over A,B: Signature Verification
    B->>SIG: OQS_SIG_verify(message, signature, public_key)
    SIG->>B: valid/invalid

    alt Signature is valid
        B->>B: Accept message
    else Signature is invalid
        B->>B: Reject message
    end

Loading

[anvega]

liboqs Post-Quantum KEM Example (Kyber-768) from Example key encapsulation and decapsulation using liboqs

sequenceDiagram
    participant A as Alice (Encapsulator)
    participant B as Bob (Decapsulator)
    participant KEM as OQS_KEM

    Note over A,B: Stack-based Implementation
    B->>KEM: OQS_KEM_kyber_768_keypair()
    KEM-->>B: public_key, secret_key
    B->>A: Send public_key
    A->>KEM: OQS_KEM_kyber_768_encaps(public_key)
    KEM-->>A: ciphertext, shared_secret_e
    A->>B: Send ciphertext
    B->>KEM: OQS_KEM_kyber_768_decaps(ciphertext, secret_key)
    KEM-->>B: shared_secret_d

    Note over A,B: Heap-based Implementation
    B->>KEM: OQS_KEM_new(OQS_KEM_alg_kyber_768)
    KEM-->>B: kem object
    B->>KEM: OQS_KEM_keypair(kem, public_key, secret_key)
    KEM-->>B: public_key, secret_key
    B->>A: Send public_key
    A->>KEM: OQS_KEM_encaps(kem, ciphertext, shared_secret_e, public_key)
    KEM-->>A: ciphertext, shared_secret_e
    A->>B: Send ciphertext
    B->>KEM: OQS_KEM_decaps(kem, shared_secret_d, ciphertext, secret_key)
    KEM-->>B: shared_secret_d

    Note over A,B: Cleanup
    A->>A: OQS_MEM_cleanse(shared_secret_e)
    B->>B: OQS_MEM_cleanse(secret_key, shared_secret_d)
    B->>B: OQS_MEM_secure_free(secret_key, shared_secret_e, shared_secret_d)
    B->>B: OQS_MEM_insecure_free(public_key, ciphertext)
    B->>B: OQS_KEM_free(kem)

Loading

[anvega]

liboqs Post-Quantum Signature Example (Dilithium-2) from Example signing and verification using liboqs

sequenceDiagram
    participant A as Alice (Signer)
    participant B as Bob (Verifier)
    participant SIG as OQS_SIG

    Note over A,B: Stack-based Implementation
    A->>SIG: OQS_SIG_dilithium_2_keypair()
    SIG-->>A: public_key, secret_key
    A->>A: OQS_randombytes(message, MESSAGE_LEN)
    A->>SIG: OQS_SIG_dilithium_2_sign(message, secret_key)
    SIG-->>A: signature
    A->>B: Send message, signature, public_key
    B->>SIG: OQS_SIG_dilithium_2_verify(message, signature, public_key)
    SIG-->>B: verification result

    Note over A,B: Heap-based Implementation
    A->>SIG: OQS_SIG_new(OQS_SIG_alg_dilithium_2)
    SIG-->>A: sig object
    A->>A: OQS_randombytes(message, MESSAGE_LEN)
    A->>SIG: OQS_SIG_keypair(sig, public_key, secret_key)
    SIG-->>A: public_key, secret_key
    A->>SIG: OQS_SIG_sign(sig, message, secret_key)
    SIG-->>A: signature
    A->>B: Send message, signature, public_key
    B->>SIG: OQS_SIG_verify(sig, message, signature, public_key)
    SIG-->>B: verification result

    Note over A,B: Cleanup
    A->>A: OQS_MEM_cleanse(secret_key)
    A->>A: OQS_MEM_secure_free(secret_key)
    A->>A: OQS_MEM_insecure_free(public_key, message, signature)
    A->>A: OQS_SIG_free(sig)

Loading

[dstebila]

Very cool!

The wiki isn't directly in the project repository, making direct contributions challenging

True. But apparently it's possible to clone the wiki as a Git repository and make branches on it; I'm not sure about PRs, however.

What's the preferred format for submitting these diagrams? (Mermaid code, PNG, or both?)

I think it would be good to have the source code somewhere in our repositories, so that they can be updated if need be. And then also a rendered PNG.

Are there any specific style guidelines I should follow for consistency with existing documentation?

We don't have diagrams in the existing docs, so I don't think so.

Where in the docs would these diagrams be most beneficial?

If it was to go on existing pages, it could go on 1 and 2. Although we haven't given too much thought lately to the content or organization of the wiki, so if you have suggestions on how that can be improved, please go for it.

It could also go on the public website www.openquantumsafe.org, either on 3 or 4 (or somewhere else -- again we haven't given too much thought to documentation on their recently). The repository for the website is https://github.com/open-quantum-safe/www.

[baentsch]

Putting this into the Wiki (or making the Wiki a separate repo) seems suboptimal for me. IMO this should be/remain in lockstep with the code and reside in the code's repo, best arguably in the doc folder -- which needs some new container to "house" this in. What about moving the Wiki augmented with the graph to a new docs/examples folder?

Edit/add: Further benefit of housing this in the docs folder --if I'm not mistaken-- is that this would automatically wind up on the Web site that way, making bespoke 'www' code unnecessary, right, @dstebila ?

[dstebila]

Putting this into the Wiki (or making the Wiki a separate repo) seems suboptimal for me. IMO this should be/remain in lockstep with the code and reside in the code's repo, best arguably in the doc folder -- which needs some new container to "house" this in. What about moving the Wiki augmented with the graph to a new docs/examples folder?

We do have tests/examples_*.c, but maybe these would be better relocated into a new docs/examples folder, with the extra materials you're suggesting?

Edit/add: Further benefit of housing this in the docs folder --if I'm not mistaken-- is that this would automatically wind up on the Web site that way, making bespoke 'www' code unnecessary, right, @dstebila ?

We'd still need to edit the www code to pull in the relevant parts into the website template, but after that's done once the updates would be automatically pulled in.

[anvega]

Forking the wiki is possible, but it doesn’t offer much benefit beyond showcasing a view of changes.

There seems to be an opportunity here to assess how information is currently organized and determine the best structure for it—essentially, an exercise in Information Architecture. Information Architecture involves a series of discussions, but I can start by documenting how things are laid out on my own. After that, we can identify the differences between the existing structure and the improvements everyone would like to see.

Regarding where information should be found and maintained, @baentsch makes a strong case for keeping it in either the main repo or the site repo. One consideration for decoupling repo docs and the code is the codebase is more fluid than a static site which may break and slow down PR reviews on those failed deploy preview changes.

[jennybeth]

@anvega

I would be interested in helping you out with the information architecture for this project.

Jenny Beth

[baentsch]

We'd still need to edit the www code to pull in the relevant parts into the website template, but after that's done once the updates would be automatically pulled in.

That's a one-time edit, right -- afterwards everything is automatic (?), so I'd suggest pursuing that avenue.

One consideration for decoupling repo docs and the code is the codebase is more fluid than a static site which may break and slow down PR reviews on those failed deploy preview changes.

Such "breakage" would be goodness in my eyes if it highlights a disconnect between code and documentation. I'm not sure under which circumstances PR reviews would be slowed down (assuming sufficient automation for doc generation).

To @jennybeth : It'd be really great to get help on this front. You might also want to check out a discussion on a recent issue in this area to get your feet wet on (contributing to) OQS.