-
Notifications
You must be signed in to change notification settings - Fork 453
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add diagrams for minimal examples in wiki and liboqs documentation #1851
Comments
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)
|
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
|
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)
|
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)
|
Very cool!
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.
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.
We don't have diagrams in the existing docs, so I don't think so.
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. |
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 ? |
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?
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. |
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. |
I would be interested in helping you out with the information architecture for this project. Jenny Beth |
That's a one-time edit, right -- afterwards everything is automatic (?), so I'd suggest pursuing that avenue.
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. |
@baentsch Thanks very much! I JUST started a 3-month contract at startup (think drinking from the firehose), after 3 glorious months of funemployment. I will dig into this when I have a second to take a breath! What I've done so far is watch videos and read things to teach myself about quantum computing and quantum-safe encryption so I have context when I circle back to this very interesting project. Warmly, |
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.
Proposal:
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:
I'm happy to submit a PR to contribute these diagrams to the project once I have some guidance on the above questions.
The text was updated successfully, but these errors were encountered: