Version 0.2.0

GitOrigin-RevId: 1528895b6239add261beb98fc3c28d96993b4162

.github/workflows/docs.yml

@@ -19,9 +19,28 @@ jobs:
     - name: Copy includes
       shell: bash
       run: |
-        mkdir docs/_includes
         cp -R examples docs/_includes
 
+    - name: Gather changelog
+      shell: python
+      run: |
+        import requests
+
+        base_url = "https://api.github.com/repos/${{ github.repository }}"
+        r = requests.get(f"{base_url}/releases?per_page=100", headers={
+            "Authorization": "Bearer ${{ secrets.GITHUB_TOKEN }}",
+            "X-GitHub-Api-Version": "2022-11-28",
+        })
+        assert r.ok, r.text
+
+        with open("docs/changelog.md", "a") as f:
+            for release in r.json():
+                if not release['draft']:
+                    print(file=f)
+                    print(f"# [{release['name']}]({release['html_url']})", file=f)
+                    print(file=f)
+                    print(release['body'], file=f)
+
     - name: Setup Pages
       uses: actions/configure-pages@v5
 

.github/workflows/push.yml

@@ -5,7 +5,13 @@ on:
     branches: [main]
 
 jobs:
+  style:
+    name: Style
+    uses: ./.github/workflows/style.yml
+
   build:
+    needs: style
+
     strategy:
       matrix:
         include:

.github/workflows/style.yml

@@ -0,0 +1,57 @@
+on:
+  workflow_call:
+
+jobs:
+  style:
+    name: Style
+    runs-on: ubuntu-latest
+    container: silkeh/clang:16
+
+    steps:
+    - name: Checkout repository
+      uses: 'actions/checkout@v4'
+
+    - name: Install dependencies
+      run: |
+        apt-get update
+        apt-get install -y python3-pip
+        pip3 install gitignorefile --break-system-packages
+
+    - name: Style check
+      run: |
+        python3 -c 'if True:
+          import difflib
+          import os
+          import subprocess
+          import sys
+
+          import gitignorefile
+
+          gi = gitignorefile.Cache()
+          errors = 0
+          for root, directories, names in os.walk(os.getcwd()):
+            directories[:] = [d for d in directories if d != ".git" and not gi(os.path.join(root, d))]
+            for name in names:
+              path = os.path.join(root, name)
+              if os.path.splitext(name)[1] in (".h", ".c", ".cpp") and not gi(path):
+                r = subprocess.run(["clang-format", path], universal_newlines=True, stdout=subprocess.PIPE)
+                r.check_returncode()
+                with open(path) as f:
+                  t = f.read().splitlines()
+                e = r.stdout.splitlines()
+                m = difflib.SequenceMatcher(a=t, b=e)
+                for tag, i1, i2, j1, j2 in m.get_opcodes():
+                  if tag == "insert":
+                    expecting = "%0A".join(["```"] + e[j1:j2] + ["```"])
+                    print(f"::error file={os.path.relpath(path)},line={i1 or 1}::Please insert at line {i1+1}:%0A{expecting}")
+                    errors += 1
+                  elif tag == "replace":
+                    expecting = "%0A".join(["```"] + e[j1:j2] + ["```"])
+                    print(f"::error file={os.path.relpath(path)},line={i1+1},endLine={i2}::Please replace line(s) {i1+1}-{i2} with:%0A{expecting}")
+                    errors += 1
+                  elif tag == "delete":
+                    print(f"::error file={os.path.relpath(path)},line={i1+1},endLine={i2}::Please remove line(s) {i1+1}-{i2}")
+                    errors += 1
+
+          sys.exit(int(bool(errors)))
+        '

README.md

@@ -35,17 +35,19 @@ Symmetric Encryption:
 
 Key Encapsulation Mechanism:
 
+-   [ML-KEM](https://terra-quantum-public.github.io/tq42-pqc-oss/post_quantum_algs/kem/ml-kem.html)
 -   [Classic McEliece 8192128f](https://terra-quantum-public.github.io/tq42-pqc-oss/post_quantum_algs/kem/mceliece.html)
 
 Digital Signature:
-
+-   [ML-DSA](https://terra-quantum-public.github.io/tq42-pqc-oss/post_quantum_algs/digital_signature/ml-dsa.html)
 -   [Falcon padded 1024](https://terra-quantum-public.github.io/tq42-pqc-oss/post_quantum_algs/digital_signature/falcon.html)
 
 ### Key Management
 
 -   [Secure file removal (HDD, SSD)](https://terra-quantum-public.github.io/tq42-pqc-oss/keys/secureHDD&SSDRemoval.html)
 -   [Randomness source](https://terra-quantum-public.github.io/tq42-pqc-oss/keys/PRNG.html)
 -   [Key Containers](https://terra-quantum-public.github.io/tq42-pqc-oss/keys/keys_container.html)
+-   [PBKDF2](https://terra-quantum-public.github.io/tq42-pqc-oss/keys/pbkdf2.html)
 
 ## Security Notice
 While there are no known vulnerabilities in the quantum-safe algorithms within this library, caution is crucial. These algorithms have not undergone the same level of scrutiny as currently deployed ones. The NIST Post-Quantum Cryptography Standardization project's guidance should be followed diligently. As research progresses, algorithm security may rapidly change, including potential vulnerabilities to classical and quantum computers.

docs/_config.yml

@@ -18,15 +18,15 @@ plugins:
 # Footer content
 # appears at the bottom of every page's main content
 # Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust markup / liquid-based content.
-footer_content: "© Copyright 2024, Terra Quantum."
+footer_content: "© Copyright 2024, Terra Quantum AG."
 # Footer last edited timestamp
 last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
 last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
 
 # Footer "Edit this page on GitHub" link text
-gh_edit_link: true # show or hide edit this page link
+gh_edit_link: false # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
-gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
+gh_edit_repository: "https://github.com/terra-quantum-public/tq42-pqc-oss" # the github URL for your repo
 gh_edit_branch: "main" # the branch that your docs is served from
-# gh_edit_source: docs # the source that your files originate from
-gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
+gh_edit_source: "docs" # the source that your files originate from
+gh_edit_view_mode: "edit" # "tree" or "edit" if you want the user to jump into the editor immediately

docs/_includes/nav_footer_custom.html

@@ -0,0 +1 @@
+<!-- nav footer -->

docs/_plugins/copy-examples.rb

@@ -1,6 +1,5 @@
 require 'fileutils'
 
 Jekyll::Hooks.register :site, :after_init do |jekyll|
-    FileUtils.mkdir_p '_includes'
     FileUtils.cp_r '../examples', '_includes'
 end

docs/api_reference.md

@@ -28,6 +28,7 @@ Below you may find the reference to the all API methods or examples that exist i
 - [`PQC_kem_decode_secret`](post_quantum_algs/kem/api.html#pqc_kem_decode_secret)
 - [`PQC_close_context`](post_quantum_algs/kem/api.html#pqc_close_context)
 - [McEliece Example](post_quantum_algs/kem/mceliece.html#example)
+- [ML-KEM Example](post_quantum_algs/kem/ml-kem.html#example)
 
 ### Digital Signature
 - [`PQC_generate_key_pair`](post_quantum_algs/digital_signature/api.html#pqc_generate_key_pair)
@@ -36,6 +37,7 @@ Below you may find the reference to the all API methods or examples that exist i
 - [`PQC_verify`](post_quantum_algs/digital_signature/api.html#pqc_verify)
 - [`PQC_close_context`](post_quantum_algs/digital_signature/api.html#pqc_close_context)
 - [Falcon Example](post_quantum_algs/digital_signature/falcon.html#example)
+- [ML-DSA Example](post_quantum_algs/digital_signature/ml-dsa.html#example)
 
 ## Classic Quantum-Resistant Algorithms
 
@@ -99,6 +101,10 @@ Below you may find the reference to the all API methods or examples that exist i
 - [`PQC_file_delete`](keys/secureHDD&SSDRemoval.html#pqc_file_delete)
 - [Example](keys/secureHDD&SSDRemoval.html#example)
 
+### PBKDF2
+- [`PQC_pbkdf_2`](keys/pbkdf2.html#pqc_pbkdf_2)
+- [Example](keys/pbkdf2.html#example)
+
 ## Common functions
 - [`PQC_get_length`](common_functions.html#pqc_get_length)
 - [`PQC_context_get_length`](common_functions.html#pqc_context_get_length)

docs/changelog.md

@@ -0,0 +1,6 @@
+---
+layout: default
+title: Changelog
+nav_order: 2
+---
+

docs/classic_quantum_resistant_algs/aes.md

@@ -45,7 +45,7 @@ Each of these modes has a specific use case where it excels and others where it
 Quantum resistance
 ------------------
 
-AES-256 is considered to be [quantum](https://en.wikipedia.org/wiki/Quantum_computing) resistant, as it has similar quantum resistance to AES-128's resistance against traditional, non-quantum, attacks at 128 [bits of security](\"https://en.wikipedia.org/wiki/Bits_of_security\"). AES-192 and AES-128 are not considered quantum resistant due to their smaller key sizes. AES-192 has a strength of 96 bits against quantum attacks and AES-128 has 64 bits of strength against quantum attacks, making them both insecure.
+AES-256 is considered to be [quantum](https://en.wikipedia.org/wiki/Quantum_computing) resistant, as it has similar quantum resistance to AES-128's resistance against traditional, non-quantum, attacks at 128 [bits of security](https://en.wikipedia.org/wiki/Bits_of_security). AES-192 and AES-128 are not considered quantum resistant due to their smaller key sizes. AES-192 has a strength of 96 bits against quantum attacks and AES-128 has 64 bits of strength against quantum attacks, making them both insecure.
 
 NIST
 ----

docs/index.markdown

@@ -61,17 +61,20 @@ Symmetric Encryption:
 
 Key Encapsulation Mechanism:
 
+-   [ML-KEM](post_quantum_algs/kem/ml-kem.html)
 -   [Classic McEliece 8192128f](post_quantum_algs/kem/mceliece.html)
 
 Digital Signature:
 
+-   [ML-DSA](post_quantum_algs/digital_signature/ml-dsa.html)
 -   [Falcon padded 1024](post_quantum_algs/digital_signature/falcon.html)
 
 ### Key Management
 
 -   [Secure file removal (HDD, SSD)](keys/secureHDD&SSDRemoval.html)
 -   [Randomness source](keys/PRNG.html)
 -   [Key Containers](keys/keys_container.html)
+-   [PBKDF2](keys/pbkdf2.html)
 
 ## Enhancing Security with Post-Quantum Algorithms: Strategic Recommendations
 

docs/keys/PRNG.md

@@ -88,8 +88,8 @@ This function initializes the PQ17 pseudo-random number generator with a specifi
 
 *   `PQC_OK`: Indicates the operation was successful and the PQ17 pseudo-random generator was initialized correctly.
     
-*   `PQC_BAD_LEN`: Indicates that an invalid length for either the key or the IV was passed to the function. The valid lengths are 32 bytes for the key and 16 bytes for the IV [1](\"https://www.geeksforgeeks.org/pseudo-random-number-generator-prng/\") .
-    
+*   `PQC_BAD_LEN`: Indicates that an invalid length for either the key or the IV was passed to the function. The valid lengths are 32 bytes for the key and 16 bytes for the IV [1](https://www.geeksforgeeks.org/pseudo-random-number-generator-prng/).
+
 
 The initialization of the PRNG with `PQC_random_from_pq_17` influences the randomness source for subsequent operations within the library that require random data.
 

docs/keys/keys_container.md

@@ -343,7 +343,7 @@ PQC_CONTAINER_HANDLE PQC_asymmetric_container_create(uint32_t cipher);
 
 **Container Initialization**
 
--   **Key Fetching**: As part of the container's creation, cryptographic keys are sourced from a [specified randomness source](keys/PRNG.html). This ensures that the cryptographic keys are robust and secure, fitting the requirements for secure cryptographic operations.
+-   **Key Fetching**: As part of the container's creation, cryptographic keys are sourced from a [specified randomness source](/keys/PRNG.html). This ensures that the cryptographic keys are robust and secure, fitting the requirements for secure cryptographic operations.
 -   **Memory Residency**: It is crucial to note that the container exists only in the memory when created. There's no automatic storage or file association happening during the container's creation.
 
 **Important Note**

docs/keys/pbkdf2.md

@@ -0,0 +1,87 @@
+---
+layout: default
+title: PBKDF2
+parent: Keys Management
+nav_order: 4
+---
+
+Overview
+--------
+{: .no_toc }
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+
+PBKDF2, which stands for Password-Based Key Derivation Function 2, is a cryptographic algorithm designed to transform a password into a cryptographic key. It is widely used in applications that require secure password hashing and key generation, such as password storage, encryption key derivation, and digital signing. 
+
+
+NIST
+----
+
+[https://csrc.nist.gov/News/2023/proposal-to-revise-nist-sp-800-132-pbkdf](https://csrc.nist.gov/News/2023/proposal-to-revise-nist-sp-800-132-pbkdf)
+
+PBKDF2 (Password-Based Key Derivation Function 2) is recognized and standardized by the National Institute of Standards and Technology (NIST). NIST provides guidelines and recommendations on the use of PBKDF2 for secure password storage and key derivation. The relevant standards and publications include: **Recommendation for Password-Based Key Derivation**, **Authentication and Lifecycle Management**, **Salt and Key Length**, **Iteration Count**, **Hash Function**.
+
+PBKDF2 Implementation
+-----------------------------------
+
+**Initial Hashing**: The password and salt are concatenated and hashed using a pseudorandom function (usually HMAC-SHA-1, HMAC-SHA-256, or another HMAC-based hash function).
+
+**Iteration Process**: The resulting hash is repeatedly fed back into the hash function along with the original password and salt for the specified number of iterations.
+
+**Final Output**: The final output after all iterations is the derived key, which can be used for cryptographic purposes such as encryption or as a secure password hash for storage.
+
+
+PBKDF2 is standardized in RFC 8018 and widely implemented in many cryptographic libraries and frameworks. It is a recommended practice for password hashing due to its resistance to various attack vectors and its configurability in terms of security parameters.
+
+API
+----
+### `PQC_pbkdf_2`
+
+Include `pqc/pbkdf2.h`
+
+The `PQC_pbkdf_2` function  is used for securely deriving cryptographic keys from passwords.
+
+**Function signature:**
+
+```cpp
+size_t PQC_API PQC_pbkdf_2(
+    int mode, size_t hash_length, size_t password_length, const uint8_t * password, size_t key_length,
+    uint8_t * master_key, size_t master_key_length, uint8_t * salt, size_t salt_length, size_t iterations
+)
+```
+
+
+**Parameters:**
+*   `mode`:  Additional mode specifier which should always be set to **PQC_PBKDF2_HMAC_SHA3** as per the requirement.
+*   `hash_length`:  The length of the hash.
+*   `password_length`: The length of the password.
+*   `password`: Password used to encrypt the file for security.
+*   `key_length`: The length of the key buffer.
+*   `master_key`:  Buffer for storing the derived key.
+*   `master_key_length`: Define the length of the master key to be derived.
+*   `salt`: Salt value used in file encryption. It’s recommended to use a constant specific to the application for enhanced security.
+*   `salt_length`: The length of the salt.
+*   `iterations`: Number of iterations, positive integer value.
+
+
+**Return values:**
+
+*   `PQC_OK`: This return value indicates that the operation was executed successfully. The output will be a generated key of the length you have specified.
+
+*   `PQC_IO_ERROR`: This return value suggests that an unexpected error occurred during the deletion process. 
+
+
+Example
+---------
+
+**Code**
+
+```cpp
+{% include examples/pbkdf2/pbkdf2_example.cpp %}```

docs/post_quantum_algs/digital_signature/falcon.md

@@ -3,7 +3,7 @@ layout: default
 title: Falcon
 parent: Digital Signature
 grand_parent: Post-Quantum Algorithms
-nav_order: 1
+nav_order: 3
 ---
 
 # **Falcon Overview**