Version 0.1.1

GitOrigin-RevId: a7984031024f269526c68791766ded6aeca283e6

CONTRIBUTING.md

@@ -3,24 +3,24 @@
 We highly value your interest and proposals to enhance this project. Here's how you can contribute effectively:
 
 ## Proposals for Improvement:
-- **Discussion for Input or Feedback:** We appreciate discussions around potential improvements. Please feel free to start a discussion to share your innovative ideas or feedback.
-- **Bug Reports and Feature Requests:** If you come across any bugs or believe a new feature can enhance the project, please submit an issue. This helps us track potential improvements systematically.
+- **Discussion for Input or Feedback:** We appreciate discussions around potential improvements. Please feel free to [start a discussion](https://github.com/terra-quantum-public/tq42-pqc-oss/discussions/new/choose) to share your innovative ideas or feedback.
+- **Bug Reports and Feature Requests:** If you come across any bugs or believe a new feature can enhance the project, please [submit an issue](https://github.com/terra-quantum-public/tq42-pqc-oss/issues/new). This helps us track potential improvements systematically.
 ## Review and Feedback:
 - **Timely Responses:** We strive to provide swift and constructive feedback on all inputs. Your contributions are crucial to the project, and we aim to acknowledge them promptly.
 - **Clarification and Queries:** If you are unsure about the appropriateness, necessity, or timing of your contributions, do not hesitate to open a new issue. This is especially recommended for reporting potential bugs or suggesting new features.
 
 ## Pull Requests:
 -  **Current Policy on Pull Requests:** At this time, we are not accepting contributions through Pull Requests. The TQ42 team prioritizes maintaining the stability and security of the codebase.
-s
+  
 **Alternative Contribution Methods:**
-- **Initiating Discussions:** If you have ideas or enhancements in mind, starting a discussion is the best way forward. This allows for a collaborative evaluation of ideas before formalizing them into the project.
-- **Creating Issues:** For any bugs found or features envisaged, creating an issue is encouraged. This not only helps in maintaining an organized approach but ensures that every suggestion is carefully considered and aligned with the project's objectives. Please utilize [Code of Conduct](https://github.com/terra-quantum-public/tq42-pqc-oss/tree/main/CODE_OF_CONDUCT.md) when reporting an issue.
+- **Initiating Discussions:** If you have ideas or enhancements in mind, [starting a discussion](https://github.com/terra-quantum-public/tq42-pqc-oss/discussions/new/choose) is the best way forward. This allows for a collaborative evaluation of ideas before formalizing them into the project.
+- **Creating Issues:** For any bugs found or features envisaged, [creating an issue](https://github.com/terra-quantum-public/tq42-pqc-oss/issues/new) is encouraged. This not only helps in maintaining an organized approach but ensures that every suggestion is carefully considered and aligned with the project's objectives. Please utilize [Code of Conduct](https://github.com/terra-quantum-public/tq42-pqc-oss/tree/main/CODE_OF_CONDUCT.md) when reporting an issue.
 
 ## General Guidelines:
 - **Communication:** Keep all communications respectful and professional. Adhering to this ensures a positive environment where ideas can flourish.
 - **Code of Conduct:** Please read our [Code of Conduct](https://github.com/terra-quantum-public/tq42-pqc-oss/tree/main/CODE_OF_CONDUCT.md) to understand the standards to which we hold ourselves and our contributors.
 
 ## Seeking Assistance:
-If you encounter any trouble or need clarification on the processes, feel free to reach out through our community support channels or directly via our project's contact email - [email protected]
+If you encounter any trouble or need clarification on the processes, feel free to reach out through our community support channels or directly via our project's contact email - [[email protected]](mailto:[email protected])
 
 Your contributions, whether they are suggestions, discussions, or issue reports, are invaluable to us. Thank you for helping us improve the TQ42 Cryptography project. Together, we can achieve more secure and robust cryptographic solutions.

LICENSE.md

@@ -1,4 +1,13 @@
-Terra Quantum AG - Licensee | AGPLv3
+# TQ42 Cryptography Licenses
+
+## Available Licenses
+The TQ42 Cryptography library is available under two primary licensing options to accommodate the diverse needs of organizations at different stages of their post-quantum migration journeys:
+- Free Use is permitted under **AGPLv3**
+- A **Commercial license** is available by contacting Terra Quantum at [[email protected]](mailto:[email protected])
+
+Contributions will be welcomed in the near future under a **Contributor license**.
+
+## Open-Source License AGPLv3
 
 Version: 2024-01
 
@@ -8,7 +17,7 @@ Date: May 7, 2024
 
 Version 3, 19 November 2007
 
-Copyright © 2007 Free Software Foundation, Inc. <<https://fsf.org/>>
+Copyright © 2007 Free Software Foundation, Inc. <<https://fsf.org/>>
 
 Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
 

README.md

@@ -1,4 +1,11 @@
-![TQ42_Cryptography_Banner.png](https://terra-quantum-public.github.io/tq42-pqc-oss/img/TQ42_Banner.png)
+![TQ42_Cryptography_Banner.png](https://terra-quantum-public.github.io/tq42-pqc-oss/img/readme_banner.png)
+
+<p align="center">
+  <a href="https://terra-quantum-public.github.io/tq42-pqc-oss">Documentation</a> &nbsp;&bull;&nbsp;
+  <a href="https://terra-quantum-public.github.io/tq42-pqc-oss/getting_started.html">Getting Started</a> &nbsp;&bull;&nbsp;
+  <a href="https://terra-quantum-public.github.io/tq42-pqc-oss/use_cases.html">Use Cases</a> &nbsp;&bull;&nbsp;
+  <a href="https://terra-quantum-public.github.io/tq42-pqc-oss/api_reference.html">API reference</a>
+</p>
 
 # Introduction to TQ42 Cryptography
 TQ42 Cryptography by [Terra Quantum](https://terraquantum.swiss) is a comprehensive, low-level cryptography library designed to cover Encryption, Hashing, Electronic Signatures, and Key Management Systems. It is specifically crafted to help individual developers, businesses, and governmental entities prepare for the quantum era and enhance the security of their data, and expands upon the existing functionality offered in [TQ42](https://tq42.com), the quantum-as-a-service ecosystem by Terra Quantum.

SECURITY.md

@@ -0,0 +1,43 @@
+
+# Security Policy for TQ42 Cryptography
+
+## Introduction
+
+This document outlines the security processes and policies for the TQ42 Cryptography. Our aim is to maintain the highest security standards in post-quantum cryptographic development and to be transparent about our security practices. We encourage responsible disclosure of any security vulnerabilities.
+
+## Supported Versions
+
+We support the following versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| [0.1](https://github.com/terra-quantum-public/tq42-pqc-oss/releases/tag/v0.1.0)   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+We take all security bugs in TQ42 Cryptography seriously. We appreciate your efforts and responsible disclosure and will make every effort to acknowledge your contributions. Please open a [new issue](https://github.com/terra-quantum-public/tq42-pqc-oss/security/advisories/new) and clearly document the specifics of the vulnerability.
+
+
+### Response Expectations
+
+Upon receipt of a vulnerability issue, the following actions will be taken:
+- We will acknowledge receipt of your vulnerability report.
+- We will perform an initial analysis to verify the validity of the report.
+- Once the vulnerability is confirmed, we will schedule a fix to be implemented.
+- We will publicly announce the vulnerability after the fix and release, respecting confidentiality agreements where applicable.
+
+## Security Updates Policy
+
+- Security updates will be issued as part of regular library updates.
+- Emergency updates will be triggered by critical vulnerability discoveries that directly impact the usability and integrity of cryptographic modules.
+
+## Known Security Gaps & Future Enhancements
+
+As with any cryptographic library, there may be undiscovered vulnerabilities. The field of post-quantum cryptography is rapidly evolving, and TQ42 Cryptography is committed to integrating robust and innovative security practices as the landscape evolves.
+
+## Resolved Issues
+
+As of the current date, there have been no security issues reported.
+
+
+

benchmark/pqc_benchmark.cpp

@@ -3,14 +3,14 @@
 
 #include <pqc/aes.h>
 
-template <uint32_t Mechanism> void aes_encrypt(benchmark::State & state)
+template <uint32_t mode> void aes_encrypt(benchmark::State & state)
 {
     CIPHER_HANDLE context;
 
     uint8_t iv[PQC_AES_IVLEN] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15};
 
     uint8_t key[PQC_AES_KEYLEN] = {'1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'A', 'B', 'C', 'D', 'E', 'F',
-                                  'G', 'H', 'I', 'J', '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'K', 'L'};
+                                   'G', 'H', 'I', 'J', '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'K', 'L'};
 
     const int64_t data_len = state.range(0);
     uint8_t * data = new uint8_t[data_len];
@@ -20,7 +20,7 @@ template <uint32_t Mechanism> void aes_encrypt(benchmark::State & state)
     size_t res = 0;
     for (auto _ : state)
     {
-        res = PQC_encrypt(context, Mechanism, data, data_len);
+        res = PQC_encrypt(context, mode, data, data_len);
     }
 
     if (res != PQC_OK)
@@ -36,14 +36,14 @@ template <uint32_t Mechanism> void aes_encrypt(benchmark::State & state)
 }
 
 
-template <uint32_t Mechanism> void aes_decrypt(benchmark::State & state)
+template <uint32_t mode> void aes_decrypt(benchmark::State & state)
 {
     CIPHER_HANDLE context;
 
     uint8_t iv[PQC_AES_IVLEN] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15};
 
     uint8_t key[PQC_AES_KEYLEN] = {'1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'A', 'B', 'C', 'D', 'E', 'F',
-                                  'G', 'H', 'I', 'J', '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'K', 'L'};
+                                   'G', 'H', 'I', 'J', '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'K', 'L'};
 
     const int64_t data_len = state.range(0);
     uint8_t * data = new uint8_t[data_len];
@@ -53,7 +53,7 @@ template <uint32_t Mechanism> void aes_decrypt(benchmark::State & state)
     size_t res = 0;
     for (auto _ : state)
     {
-        res = PQC_decrypt(context, Mechanism, data, data_len);
+        res = PQC_decrypt(context, mode, data, data_len);
     }
 
     if (res != PQC_OK)
@@ -81,4 +81,4 @@ BENCHMARK(aes_decrypt<PQC_AES_M_CBC>)->Arg(PQC_AES_BLOCKLEN * 100);
 BENCHMARK(aes_encrypt<PQC_AES_M_OFB>)->Arg(PQC_AES_BLOCKLEN * 100);
 BENCHMARK(aes_decrypt<PQC_AES_M_OFB>)->Arg(PQC_AES_BLOCKLEN * 100);
 
-BENCHMARK_MAIN();
+BENCHMARK_MAIN();

docs/api_reference.md

@@ -24,6 +24,8 @@ Below you may find the reference to the all API methods or examples that exist i
 - [`PQC_init_context`](post_quantum_algs/kem/api.html#pqc_init_context)
 - [`PQC_kem_encode`](post_quantum_algs/kem/api.html#pqc_kem_encode)
 - [`PQC_kem_decode`](post_quantum_algs/kem/api.html#pqc_kem_decode)
+- [`PQC_kem_encode_secret`](post_quantum_algs/kem/api.html#pqc_kem_encode_secret)
+- [`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)
 
@@ -58,25 +60,33 @@ Below you may find the reference to the all API methods or examples that exist i
 ### Symmetric Key Containers
 - [`PQC_symmetric_container_create`](keys/keys_container.html#pqc_symmetric_container_create)
 - [`PQC_symmetric_container_size`](keys/keys_container.html#pqc_symmetric_container_size)
+- [`PQC_symmetric_container_get_version`](keys/keys_container.html#pqc_symmetric_container_get_version)
+- [`PQC_symmetric_container_get_creation_time`](keys/keys_container.html#pqc_symmetric_container_get_creation_time)
+- [`PQC_symmetric_container_get_expiration_time`](keys/keys_container.html#pqc_symmetric_container_get_expiration_time)
 - [`PQC_symmetric_container_get_data`](keys/keys_container.html#pqc_symmetric_container_get_data)
 - [`PQC_symmetric_container_from_data`](keys/keys_container.html#pqc_symmetric_container_from_data)
-- [`PQC_symmetric_container_save_as` or `PQC_symmetric_container_save_as_pair`](keys/keys_container.html#pqc_symmetric_container_save_as-or-pqc_symmetric_container_save_as_pair)
-- [`PQC_symmetric_container_open` or `PQC_symmetric_container_pair_open`](keys/keys_container.html#pqc_symmetric_container_save_as-or-pqc_symmetric_container_save_as_pair)
+- [`PQC_symmetric_container_save_as`](keys/keys_container.html#pqc_symmetric_container_save_as)
+- [`PQC_symmetric_container_open`](keys/keys_container.html#pqc_symmetric_container_save_as)
 - [`PQC_symmetric_container_get_key`](keys/keys_container.html#pqc_symmetric_container_get_key)
 - [`PQC_symmetric_container_close`](keys/keys_container.html#pqc_symmetric_container_close)
+- [`PQC_symmetric_container_delete`](keys/keys_container.html#pqc_symmetric_container_delete)
 - [Example](keys/keys_container.html#symmetric-container-example)
 
 ### Asymmetric Key Containers
 - [`PQC_asymmetric_container_create`](keys/keys_container.html#pqc_asymmetric_container_create)
 - [`PQC_asymmetric_container_size`](keys/keys_container.html#pqc_asymmetric_container_size)
 - [`PQC_asymmetric_container_size_special`](keys/keys_container.html#pqc_asymmetric_container_size_special)
+- [`PQC_asymmetric_container_get_version`](keys/keys_container.html#pqc_asymmetric_container_get_version)
+- [`PQC_asymmetric_container_get_creation_time`](keys/keys_container.html#pqc_asymmetric_container_get_creation_time)
+- [`PQC_asymmetric_container_get_expiration_time`](keys/keys_container.html#pqc_asymmetric_container_get_expiration_time)
 - [`PQC_asymmetric_container_get_data`](keys/keys_container.html#pqc_asymmetric_container_get_data)
 - [`PQC_asymmetric_container_from_data`](keys/keys_container.html#pqc_asymmetric_container_from_data)
 - [`PQC_asymmetric_container_put_keys`](keys/keys_container.html#pqc_asymmetric_container_put_keys)
 - [`PQC_asymmetric_container_get_keys`](keys/keys_container.html#pqc_asymmetric_container_get_keys)
 - [`PQC_asymmetric_container_save_as`](keys/keys_container.html#pqc_asymmetric_container_save_as)
 - [`PQC_asymmetric_container_open`](keys/keys_container.html#pqc_asymmetric_container_open)
 - [`PQC_asymmetric_container_close`](keys/keys_container.html#pqc_asymmetric_container_close)
+- [`PQC_asymmetric_container_delete`](keys/keys_container.html#pqc_asymmetric_container_delete)
 - [Example](keys/keys_container.html#asymmetric-container-example)
 
 ### Randomness Source
@@ -88,3 +98,8 @@ Below you may find the reference to the all API methods or examples that exist i
 ### Secure file removal (HDD & SSD)
 - [`PQC_file_delete`](keys/secureHDD&SSDRemoval.html#pqc_file_delete)
 - [Example](keys/secureHDD&SSDRemoval.html#example)
+
+## Common functions
+- [`PQC_get_length`](common_functions.html#pqc_get_length)
+- [`PQC_context_get_length`](common_functions.html#pqc_context_get_length)
+- [Constants](common_functions.html#сonstants)

docs/classic_quantum_resistant_algs/aes.md

@@ -144,16 +144,16 @@ The provided code snippet describes a function for encrypting data using an init
 **Function signature:**
 
 ```cpp
-int PQC_encrypt(CIPHER_HANDLE ctx, uint32_t mechanism, uint8_t* buffer, size_t length);
+int PQC_encrypt(CIPHER_HANDLE ctx, uint32_t mode, uint8_t* buffer, size_t length);
 ```
 
-**Purpose**: This function is used to encrypt data using the specified encryption context and encryption mechanism.
+**Purpose**: This function is used to encrypt data using the specified encryption context and encryption mode.
 
 **Parameters**:
 
 *   `ctx`: Handle of the initialized encryption context.
 
-*   `mechanism`: Constant to select the encryption mechanism. The possible values depend on the selected cipher. For PQC\_CIPHER\_AES, the available mechanisms are PQC\_AES\_M\_ECB, PQC\_AES\_M\_CBC, and PQC\_AES\_M\_OFB.
+*   `mode`: Constant to select the encryption mode. The possible values depend on the selected cipher. For PQC\_CIPHER\_AES, the available modes are PQC\_AES\_M\_ECB, PQC\_AES\_M\_CBC, and PQC\_AES\_M\_OFB.
 
 *   `buffer` (in/out): Pointer to the data array. The data is encrypted in place within the same buffer.
 
@@ -166,11 +166,11 @@ The function returns the following values:
 
 *   `PQC_BAD_CONTEXT`: Indicates that the context was not properly initialized, suggesting an issue with the encryption context handle.
 
-*   `PQC_BAD_LEN`: Indicates that the length of the data does not match the requirements for the selected cipher/mechanism.
+*   `PQC_BAD_LEN`: Indicates that the length of the data does not match the requirements for the selected cipher/mode.
 
-*   `PQC_NO_IV`: Indicates that an initialization vector is required for the selected cipher/mechanism, but it was not set.
+*   `PQC_NO_IV`: Indicates that an initialization vector is required for the selected cipher/mode, but it was not set.
 
-*   `PQC_BAD_MECHANISM`: Indicates that the mechanism parameter provided is invalid.
+*   `PQC_BAD_MODE`: Indicates that the mode parameter provided is invalid.
 
 *   `PQC_BAD_CIPHER`: Indicates that the selected cipher does not support symmetric encryption.
 
@@ -180,16 +180,16 @@ The function returns the following values:
 **Function signature:**
 
 ```cpp
-int PQC_decrypt(CIPHER_HANDLE ctx, uint32_t mechanism, uint8_t* buffer, size_t length);
+int PQC_decrypt(CIPHER_HANDLE ctx, uint32_t mode, uint8_t* buffer, size_t length);
 ```
 
-**Purpose**: This function is used to decrypt data using the specified encryption context and encryption mechanism.
+**Purpose**: This function is used to decrypt data using the specified encryption context and encryption mode.
 
 **Parameters**:
 
 *   `ctx`: Handle of the initialized encryption context.
     
-*   `mechanism`: Constant to select the encryption mechanism. The possible values depend on the selected cipher. For PQC\_CIPHER\_AES, the available mechanisms are PQC\_AES\_M\_ECB, PQC\_AES\_M\_CBC and PQC\_AES\_M\_OFB.
+*   `mode`: Constant to select the encryption mode. The possible values depend on the selected cipher. For PQC\_CIPHER\_AES, the available modes are PQC\_AES\_M\_ECB, PQC\_AES\_M\_CBC and PQC\_AES\_M\_OFB.
     
 *   `buffer` (in/out): Pointer to the data array. The data is decrypted in place within the same buffer.
     
@@ -202,11 +202,11 @@ The function returns the following values:
     
 *   `P_BAD_CONTEXT`: Indicates that the context was not properly initialized, suggesting an issue with the encryption context handle.
     
-*   `PQC_BAD_LEN`: Indicates that the length of the data does not match the requirements for the selected cipher/mechanism.
+*   `PQC_BAD_LEN`: Indicates that the length of the data does not match the requirements for the selected cipher/mode.
     
-*   `PQC_NO_IV`: Indicates that an initialization vector is required for the selected cipher/mechanism, but it was not set.
+*   `PQC_NO_IV`: Indicates that an initialization vector is required for the selected cipher/mode, but it was not set.
     
-*   `PQC_BAD_MECHANISM`: Indicates that the mechanism parameter provided is invalid.
+*   `PQC_BAD_MODE`: Indicates that the mode parameter provided is invalid.
     
 *   `PQC_BAD_CIPHER`: Indicates that the selected cipher does not support symmetric encryption.