pQCee SafeQuard API for signing and verifying using ML-DSA-65 and encrypting and decrypting using ML-KEM-768. More...
#include <stdint.h>#include <stdlib.h>
Go to the source code of this file.
Functions | |
| void | safequard_panic_wrap (void) |
| Panic the current thread. | |
| int | safequard_init (uint32_t max_log_level) |
| Initialise the safequard_api library. | |
| int | safequard_mldsa65_sign (const uint8_t *seed, size_t seed_size, const uint8_t *data, size_t data_size, uint8_t *signature, size_t signature_size) |
| Sign an ML-DSA-65 message. | |
| int | safequard_mldsa65_verify (const uint8_t *public_key, size_t public_key_size, const uint8_t *data, size_t data_size, const uint8_t *signature, size_t signature_size) |
| Verify an ML-DSA-65-signed data. | |
| int | safequard_fv_import_key (uint8_t *context, size_t context_size, const uint8_t *trusted_cert, size_t trusted_cert_size, const uint8_t *leaf_cert, size_t leaf_cert_size, size_t *out) |
| Import an ML-DSA-65 public key to prepare for verification. | |
| int | safequard_fv_verify (const uint8_t *context, size_t context_size, const uint8_t *data, size_t data_size, const uint8_t *signature, size_t signature_size) |
| Verify an ML-DSA-65-signed data using a certificate trust chain. | |
| int | safequard_mlkem768_init (uint8_t *context, size_t context_size, uint8_t *encap_key, size_t encap_key_size, size_t *out) |
| Generate a new ML-KEM-768 keypair for encrypting and decrypting messages. | |
| int | safequard_mlkem768_encrypt (const uint8_t *message, size_t message_size, const uint8_t *encap_key, size_t encap_key_size, uint8_t *ciphertext, size_t ciphertext_size, uint8_t *encrypted_message, size_t encrypted_message_size) |
| Encrypt a message using an encapsulation key. | |
| int | safequard_mlkem768_decrypt (const uint8_t *context, size_t context_size, const uint8_t *encrypted_message, size_t encrypted_message_size, const uint8_t *ciphertext, size_t ciphertext_size, uint8_t *message, size_t message_size) |
| Decrypt an ML-KEM-768 encrypted message. | |
| int | safequard_mlkem768_finalise (uint8_t *context, size_t context_size) |
| Finalise the decryption process. | |
| int | safequard_sha512_init (uint8_t *context, size_t context_size, size_t *out) |
| Generate a new SHA-512 context for streaming hash operations. | |
| int | safequard_sha512_update (uint8_t *context, size_t context_size, const uint8_t *chunk, size_t chunk_size) |
| Update a SHA-512 context for streaming hashing operations. | |
| int | safequard_sha512_finalise (uint8_t *context, size_t context_size, uint8_t *hash, size_t hash_size) |
| Finalise a SHA-512 operation and receive the hash. | |
| int | safequard_sha512 (const uint8_t *message, size_t message_size, uint8_t *hash, size_t hash_size) |
| Compute a SHA-512 digest of a message. | |
| void | safequard_log_message (uint32_t level, const char *message, size_t message_length) |
| Log a message. | |
| int64_t | get_current_time (void) |
| Get the current unix time. | |
Detailed Description
pQCee SafeQuard API for signing and verifying using ML-DSA-65 and encrypting and decrypting using ML-KEM-768.
- Copyright
- Copyright 2026 pQCee Pte Ltd. All rights reserved. Confidential.
Macro Definition Documentation
◆ ML_DSA_65_PUBLIC_KEY_SIZE
| #define ML_DSA_65_PUBLIC_KEY_SIZE 1952 |
Size of an ML-DSA-65 public key.
◆ ML_DSA_65_SEED_SIZE
| #define ML_DSA_65_SEED_SIZE 32 |
Size of an ML-DSA-65 seed.
◆ ML_DSA_65_SIGNATURE_SIZE
| #define ML_DSA_65_SIGNATURE_SIZE 3309 |
Size of an ML-DSA-65 signature.
◆ ML_KEM_768_CIPHERTEXT_SIZE
| #define ML_KEM_768_CIPHERTEXT_SIZE 1088 |
Size of an ML-KEM-768 ciphertext.
◆ ML_KEM_768_DECAP_KEY_SIZE
| #define ML_KEM_768_DECAP_KEY_SIZE 2400 |
Size of an ML-KEM-768 decapsulation (private) key.
◆ ML_KEM_768_ENCAP_KEY_SIZE
| #define ML_KEM_768_ENCAP_KEY_SIZE 1184 |
Size of an ML-KEM-768 encapsulation (public) key.
◆ ML_KEM_768_SEED_SIZE
| #define ML_KEM_768_SEED_SIZE 64 |
Size of an ML-KEM-768 seed.
◆ ML_KEM_SHARED_SECRET_IV_SIZE
| #define ML_KEM_SHARED_SECRET_IV_SIZE 16 |
Size of an ML-KEM-768 shared secret IV.
◆ ML_KEM_SHARED_SECRET_SIZE
| #define ML_KEM_SHARED_SECRET_SIZE 32 |
Size of an ML-KEM-768 shared secret.
◆ SAFEQUARD_ERROR_ALREADY_EXISTS
| #define SAFEQUARD_ERROR_ALREADY_EXISTS -1004 |
The item that already exists
◆ SAFEQUARD_ERROR_BACKEND
| #define SAFEQUARD_ERROR_BACKEND -1099 |
An error occurred on the backend
◆ SAFEQUARD_ERROR_BAD_STATE
| #define SAFEQUARD_ERROR_BAD_STATE -1006 |
The requested action cannot be performed in the current state
◆ SAFEQUARD_ERROR_BASIC_CONSTRAINTS_NOT_CRITICAL
| #define SAFEQUARD_ERROR_BASIC_CONSTRAINTS_NOT_CRITICAL -1116 |
A CA certificate's Basic Constraints extension is not marked critical.
◆ SAFEQUARD_ERROR_BUFFER_TOO_SMALL
| #define SAFEQUARD_ERROR_BUFFER_TOO_SMALL -1003 |
An output buffer is too small
◆ SAFEQUARD_ERROR_CERTIFICATE_EXPIRED
| #define SAFEQUARD_ERROR_CERTIFICATE_EXPIRED -1110 |
The certificate's notAfter value is earlier than the current trusted time.
◆ SAFEQUARD_ERROR_CERTIFICATE_MUST_BE_V3
| #define SAFEQUARD_ERROR_CERTIFICATE_MUST_BE_V3 -1112 |
The certificate is not an X.509 version 3 certificate.
Version 3 is required because this validator relies on certificate extensions such as Basic Constraints, Key Usage, and Extended Key Usage.
◆ SAFEQUARD_ERROR_CERTIFICATE_NOT_YET_VALID
| #define SAFEQUARD_ERROR_CERTIFICATE_NOT_YET_VALID -1109 |
The certificate's notBefore value is later than the current trusted time.
◆ SAFEQUARD_ERROR_COMMUNICATION_FAILURE
| #define SAFEQUARD_ERROR_COMMUNICATION_FAILURE -1010 |
There was a communication failure inside the implementation
◆ SAFEQUARD_ERROR_CORRUPTION_DETECTED
| #define SAFEQUARD_ERROR_CORRUPTION_DETECTED -1015 |
A tampering attempt was detected
◆ SAFEQUARD_ERROR_DATA_CORRUPT
| #define SAFEQUARD_ERROR_DATA_CORRUPT -1012 |
Stored data has been corrupted
◆ SAFEQUARD_ERROR_DATA_INVALID
| #define SAFEQUARD_ERROR_DATA_INVALID -1013 |
Data read from storage is not valid for the implementation
◆ SAFEQUARD_ERROR_DOES_NOT_EXIST
| #define SAFEQUARD_ERROR_DOES_NOT_EXIST -1005 |
The item does not exists
◆ SAFEQUARD_ERROR_DUPLICATE_EXTENSION
| #define SAFEQUARD_ERROR_DUPLICATE_EXTENSION -1113 |
The certificate contains more than one instance of an extension that must occur at most once.
◆ SAFEQUARD_ERROR_EXPECTED_CA
| #define SAFEQUARD_ERROR_EXPECTED_CA -1117 |
A certificate used as a root or intermediate CA does not have CA = TRUE in its Basic Constraints extension.
◆ SAFEQUARD_ERROR_EXTENDED_KEY_USAGE_NOT_CRITICAL
| #define SAFEQUARD_ERROR_EXTENDED_KEY_USAGE_NOT_CRITICAL -1124 |
The leaf certificate's Extended Key Usage extension is not marked critical.
◆ SAFEQUARD_ERROR_GENERIC
| #define SAFEQUARD_ERROR_GENERIC -1000 |
An error occurred that does not correspond to any defined failure cause
◆ SAFEQUARD_ERROR_HARDWARE_FAILURE
| #define SAFEQUARD_ERROR_HARDWARE_FAILURE -1014 |
A hardware failure was detected
◆ SAFEQUARD_ERROR_INSUFFICIENT_DATA
| #define SAFEQUARD_ERROR_INSUFFICIENT_DATA -1019 |
Insufficient data when attempting to read from a resource
◆ SAFEQUARD_ERROR_INSUFFICIENT_ENTROPY
| #define SAFEQUARD_ERROR_INSUFFICIENT_ENTROPY -1016 |
There is not enough entropy to generate random data needed for the requested action
◆ SAFEQUARD_ERROR_INSUFFICIENT_MEMORY
| #define SAFEQUARD_ERROR_INSUFFICIENT_MEMORY -1008 |
There is not enough runtime memory
◆ SAFEQUARD_ERROR_INSUFFICIENT_STORAGE
| #define SAFEQUARD_ERROR_INSUFFICIENT_STORAGE -1009 |
There is not enough persistent storage
◆ SAFEQUARD_ERROR_INVALID_ARGUMENT
| #define SAFEQUARD_ERROR_INVALID_ARGUMENT -1007 |
An argument passed to the function is invalid
◆ SAFEQUARD_ERROR_INVALID_CA_KEY_USAGE
| #define SAFEQUARD_ERROR_INVALID_CA_KEY_USAGE -1121 |
A CA certificate's Key Usage extension does not permit certificate signing or contains usage flags that violate the configured CA profile.
◆ SAFEQUARD_ERROR_INVALID_CODE_SIGNING_USAGE
| #define SAFEQUARD_ERROR_INVALID_CODE_SIGNING_USAGE -1125 |
The leaf certificate's Extended Key Usage does not contain exactly codeSigning, or it contains additional extended key purposes.
◆ SAFEQUARD_ERROR_INVALID_HANDLE
| #define SAFEQUARD_ERROR_INVALID_HANDLE -1020 |
The key handle is not valid
◆ SAFEQUARD_ERROR_INVALID_LEAF_KEY_USAGE
| #define SAFEQUARD_ERROR_INVALID_LEAF_KEY_USAGE -1122 |
The leaf certificate's Key Usage extension does not contain exactly the permitted code-signing key usage.
The current profile requires digitalSignature and rejects additional incompatible key usages.
◆ SAFEQUARD_ERROR_INVALID_LOG_LEVEL
| #define SAFEQUARD_ERROR_INVALID_LOG_LEVEL -1 |
Invalid log filter level supplied.
◆ SAFEQUARD_ERROR_INVALID_PADDING
| #define SAFEQUARD_ERROR_INVALID_PADDING -1018 |
The decrypted padding is incorrect
◆ SAFEQUARD_ERROR_INVALID_PKCS8
| #define SAFEQUARD_ERROR_INVALID_PKCS8 -1128 |
The input is not a valid DER-encoded PKCS#8 encrypted private-key structure or decrypted private-key structure.
◆ SAFEQUARD_ERROR_INVALID_PRIVATE_KEY_ALGORITHM
| #define SAFEQUARD_ERROR_INVALID_PRIVATE_KEY_ALGORITHM -1130 |
The PKCS#8 private key does not identify an ML-DSA-65 private key or contains unexpected algorithm parameters.
◆ SAFEQUARD_ERROR_INVALID_PUBLIC_KEY
| #define SAFEQUARD_ERROR_INVALID_PUBLIC_KEY -1103 |
The certificate contains a malformed public key or a public key with an unexpected encoding or size.
◆ SAFEQUARD_ERROR_INVALID_ROOT_SIGNATURE
| #define SAFEQUARD_ERROR_INVALID_ROOT_SIGNATURE -1106 |
The self-signature on the explicitly trusted root certificate is invalid.
Trust still comes from the application selecting the root certificate. This check detects corruption or inconsistent provisioning.
◆ SAFEQUARD_ERROR_INVALID_SEED_ENCODING
| #define SAFEQUARD_ERROR_INVALID_SEED_ENCODING -1132 |
The ML-DSA seed representation is malformed or does not contain exactly 32 seed bytes.
◆ SAFEQUARD_ERROR_INVALID_SIGNATURE
| #define SAFEQUARD_ERROR_INVALID_SIGNATURE -1017 |
The signature, MAC or hash is incorrect
◆ SAFEQUARD_ERROR_INVALID_TIME
| #define SAFEQUARD_ERROR_INVALID_TIME -1107 |
A certificate validity time could not be parsed or represents an invalid calendar date or time range.
◆ SAFEQUARD_ERROR_ISSUER_MISMATCH
| #define SAFEQUARD_ERROR_ISSUER_MISMATCH -1111 |
A certificate's issuer name does not match the subject name of the certificate expected to have issued it.
◆ SAFEQUARD_ERROR_KEY_USAGE_NOT_CRITICAL
| #define SAFEQUARD_ERROR_KEY_USAGE_NOT_CRITICAL -1120 |
The certificate's Key Usage extension is not marked critical.
◆ SAFEQUARD_ERROR_LEAF_IS_CA
| #define SAFEQUARD_ERROR_LEAF_IS_CA -1118 |
The leaf certificate is marked as a certificate authority.
◆ SAFEQUARD_ERROR_MALFORMED_DER
| #define SAFEQUARD_ERROR_MALFORMED_DER -1100 |
The input is not a well-formed DER value or does not have the expected ASN.1 structure.
◆ SAFEQUARD_ERROR_MISSING_BASIC_CONSTRAINTS
| #define SAFEQUARD_ERROR_MISSING_BASIC_CONSTRAINTS -1115 |
A CA certificate does not contain the required Basic Constraints extension.
◆ SAFEQUARD_ERROR_MISSING_EXTENDED_KEY_USAGE
| #define SAFEQUARD_ERROR_MISSING_EXTENDED_KEY_USAGE -1123 |
The leaf certificate does not contain the required Extended Key Usage extension.
◆ SAFEQUARD_ERROR_MISSING_KEY_USAGE
| #define SAFEQUARD_ERROR_MISSING_KEY_USAGE -1119 |
The certificate does not contain the required Key Usage extension.
◆ SAFEQUARD_ERROR_NOT_PERMITTED
| #define SAFEQUARD_ERROR_NOT_PERMITTED -1002 |
The requested action is denied by a policy
◆ SAFEQUARD_ERROR_NOT_SUPPORTED
| #define SAFEQUARD_ERROR_NOT_SUPPORTED -1001 |
The requested operation or a parameter is not supported by this implementation
◆ SAFEQUARD_ERROR_PATH_LENGTH_EXCEEDED
| #define SAFEQUARD_ERROR_PATH_LENGTH_EXCEEDED -1126 |
A CA certificate's Basic Constraints path-length limit would be exceeded by the supplied intermediate certificate chain.
◆ SAFEQUARD_ERROR_PKCS8_DECRYPTION_FAILED
| #define SAFEQUARD_ERROR_PKCS8_DECRYPTION_FAILED -1129 |
The encrypted PKCS#8 private key could not be decrypted.
This can indicate an incorrect password, corrupted ciphertext, or an unsupported password-based encryption scheme. These causes are grouped together to avoid exposing password-validation details.
◆ SAFEQUARD_ERROR_ROOT_NOT_SELF_ISSUED
| #define SAFEQUARD_ERROR_ROOT_NOT_SELF_ISSUED -1105 |
The explicitly trusted root certificate is not self-issued.
The root certificate's issuer and subject names are expected to match.
◆ SAFEQUARD_ERROR_SEED_NOT_AVAILABLE
| #define SAFEQUARD_ERROR_SEED_NOT_AVAILABLE -1131 |
The PKCS#8 private key contains only an expanded private key.
The original ML-DSA seed cannot be recovered from an expanded-only private key.
◆ SAFEQUARD_ERROR_STORAGE_FAILURE
| #define SAFEQUARD_ERROR_STORAGE_FAILURE -1011 |
There was a storage failure that may have led to data loss
◆ SAFEQUARD_ERROR_TIME_SOURCE_UNAVAILABLE
| #define SAFEQUARD_ERROR_TIME_SOURCE_UNAVAILABLE -1108 |
The integrating application could not provide a trusted current time.
◆ SAFEQUARD_ERROR_TOO_MANY_INTERMEDIATES
| #define SAFEQUARD_ERROR_TOO_MANY_INTERMEDIATES -1127 |
The supplied intermediate certificate count exceeds the limit supported by this implementation.
◆ SAFEQUARD_ERROR_TRAILING_DATA
| #define SAFEQUARD_ERROR_TRAILING_DATA -1101 |
Additional data remains after the complete DER object was parsed.
◆ SAFEQUARD_ERROR_UNKNOWN_CRITICAL_EXTENSION
| #define SAFEQUARD_ERROR_UNKNOWN_CRITICAL_EXTENSION -1114 |
The certificate contains a critical extension that this validator does not recognize or implement.
Ignoring an unknown critical extension could bypass a restriction imposed by the certificate issuer.
◆ SAFEQUARD_ERROR_UNSUPPORTED_ALGORITHM
| #define SAFEQUARD_ERROR_UNSUPPORTED_ALGORITHM -1102 |
The certificate uses an algorithm that this library does not support.
The current implementation expects ML-DSA-65.
◆ SAFEQUARD_LOG_LEVEL_DEBUG
| #define SAFEQUARD_LOG_LEVEL_DEBUG 4 |
Debug-level message.
◆ SAFEQUARD_LOG_LEVEL_ERROR
| #define SAFEQUARD_LOG_LEVEL_ERROR 1 |
Error-level message.
◆ SAFEQUARD_LOG_LEVEL_INFO
| #define SAFEQUARD_LOG_LEVEL_INFO 3 |
Informational message.
◆ SAFEQUARD_LOG_LEVEL_WARN
| #define SAFEQUARD_LOG_LEVEL_WARN 2 |
Warning-level message.
◆ SAFEQUARD_LOG_MESSAGE_CAPACITY
| #define SAFEQUARD_LOG_MESSAGE_CAPACITY 64 |
Maximum number of bytes in one formatted log message.
The logger uses a fixed-size per-call stack buffer so that logging does not require a heap allocator. Messages larger than this value are truncated.
◆ SAFEQUARD_SUCCESS
| #define SAFEQUARD_SUCCESS 0 |
Successful operation.
◆ SHA_512_BLOCK_SIZE
| #define SHA_512_BLOCK_SIZE 128 |
Size of a SHA-512 block.
◆ SHA_512_DIGEST_SIZE
| #define SHA_512_DIGEST_SIZE 64 |
Size of a SHA-512 digest.
Function Documentation
◆ get_current_time()
|
extern |
Get the current unix time.
Returns the current time, represented in the number of seconds since 1970-01-01 00:00:00 UTC, aka unix time.
- Note
- To be supplied by the integrating application.
- Returns
- The current unix time.
◆ safequard_fv_import_key()
| int safequard_fv_import_key | ( | uint8_t * | context, |
| size_t | context_size, | ||
| const uint8_t * | trusted_cert, | ||
| size_t | trusted_cert_size, | ||
| const uint8_t * | leaf_cert, | ||
| size_t | leaf_cert_size, | ||
| size_t * | out ) |
Import an ML-DSA-65 public key to prepare for verification.
Import an ML-DSA-65 public key from a two-tiered certificate chain. This leaf cert public key will be used to verify signed data in safequard_fv_verify().
Pass NULL to context to get the required buffer size returned in out.
- Parameters
-
[out] context An allocated buffer for the context. [in] context_size Size of the above buffer. [in] trusted_cert The buffer to the DER-formatted trusted root certificate. [in] trusted_cert_size Size of the above buffer. [in] leaf_cert The buffer to the DER-formatted leaf certificate. [in] leaf_cert_size Size of the above buffer. [out] out If context is NULL, the requested size of the context buffer. If context is not NULL, the actual size of context used.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if trusted_cert, leaf_cert or out is NULL. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if any of the buffers provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected. SAFEQUARD_ERROR_INVALID_ROOT_SIGNATURE if the root certificate signature is invalid. SAFEQUARD_ERROR_CERTIFICATE_EXPIRED if the certificate has expired. SAFEQUARD_ERROR_MALFORMED_DER if the certificate could not be parsed.
◆ safequard_fv_verify()
| int safequard_fv_verify | ( | const uint8_t * | context, |
| size_t | context_size, | ||
| const uint8_t * | data, | ||
| size_t | data_size, | ||
| const uint8_t * | signature, | ||
| size_t | signature_size ) |
Verify an ML-DSA-65-signed data using a certificate trust chain.
Verify an ML-DSA-65-signed data using an ML-DSA-65 two-tiered certificate chain and signature. The caller should initialise context by calling safequard_fv_import_key() first.
context can be freed when no further verification is needed with this key.
- Parameters
-
[in] context The buffer to the context previously passed to safequard_fv_import_key(). [in] context_size Size of the above buffer. [in] data The buffer to the data to verify. [in] data_size Size of the above buffer. [in] signature The buffer to the signature. [in] signature_size Size of the above buffer. Must be at least ML_DSA_65_SIGNATURE_SIZE.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if any pointers are null. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if the buffer provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected. SAFEQUARD_ERROR_INVALID_SIGNATURE if the signature is invalid.
◆ safequard_init()
| int safequard_init | ( | uint32_t | max_log_level | ) |
Initialise the safequard_api library.
- Parameters
-
[in] max_log_level The maximum log filter level.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_LOG_LEVEL if the log level is invalid.
◆ safequard_log_message()
|
extern |
Log a message.
The function must consume or copy the message before returning. The pointer refers to temporary storage and becomes invalid as soon as the call returns.
- Note
- To be supplied by the integrating application.
- Parameters
-
[in] level The log level of the message. [in] message Non-NUL-terminated message. Valid only for the duration of this call. [in] message_length Length of the message. Messages longer than SAFEQUARD_LOG_MESSAGE_CAPACITY are truncated.
◆ safequard_mldsa65_sign()
| int safequard_mldsa65_sign | ( | const uint8_t * | seed, |
| size_t | seed_size, | ||
| const uint8_t * | data, | ||
| size_t | data_size, | ||
| uint8_t * | signature, | ||
| size_t | signature_size ) |
Sign an ML-DSA-65 message.
Sign an ML-DSA-65 message using an ML-DSA-65 seed.
- Parameters
-
[in] seed The buffer to an ML-DSA-65 seed. [in] seed_size Size of the above buffer. [in] data The buffer to the data to sign. [in] data_size Size of the above buffer. [out] signature An allocated buffer to hold the signature. [in] signature_size Size of the above buffer. Must be at least ML_DSA_65_SIGNATURE_SIZE.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if any pointers are null. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if the buffer provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected.
◆ safequard_mldsa65_verify()
| int safequard_mldsa65_verify | ( | const uint8_t * | public_key, |
| size_t | public_key_size, | ||
| const uint8_t * | data, | ||
| size_t | data_size, | ||
| const uint8_t * | signature, | ||
| size_t | signature_size ) |
Verify an ML-DSA-65-signed data.
Verify an ML-DSA-65-signed data using an ML-DSA-65 public key and signature.
- Parameters
-
[in] public_key The buffer to the public key. [in] public_key_size Size of the above buffer. [in] data The buffer to the data to verify. [in] data_size Size of the above buffer. [in] signature The buffer to the signature. [in] signature_size Size of the above buffer. Must be at least ML_DSA_65_SIGNATURE_SIZE.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if any pointers are null. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if the buffer provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected. SAFEQUARD_ERROR_INVALID_SIGNATURE if the signature is invalid.
◆ safequard_mlkem768_decrypt()
| int safequard_mlkem768_decrypt | ( | const uint8_t * | context, |
| size_t | context_size, | ||
| const uint8_t * | encrypted_message, | ||
| size_t | encrypted_message_size, | ||
| const uint8_t * | ciphertext, | ||
| size_t | ciphertext_size, | ||
| uint8_t * | message, | ||
| size_t | message_size ) |
Decrypt an ML-KEM-768 encrypted message.
Decrypt an ML-KEM-768 encrypted message using a previously initialised context from safequard_mlkem768_init().
The caller should call safequard_mlkem768_finalise() when no further decryption is needed with this key, and then context can be freed.
- Parameters
-
[in] context The buffer to the context. [in] context_size Size of the above buffer. [in] encrypted_message The buffer to the encrypted message. [in] encrypted_message_size Size of the above buffer. [in] ciphertext The buffer to the ciphertext. [in] ciphertext_size Size of the above buffer. Must be at least ML_KEM_768_CIPHERTEXT_SIZE. [out] message An allocated and initialised buffer for the decrypted message. [in] message_size Size of the above buffer. Must be encrypted_message_size - ML_KEM_SHARED_SECRET_IV_SIZE.
◆ safequard_mlkem768_encrypt()
| int safequard_mlkem768_encrypt | ( | const uint8_t * | message, |
| size_t | message_size, | ||
| const uint8_t * | encap_key, | ||
| size_t | encap_key_size, | ||
| uint8_t * | ciphertext, | ||
| size_t | ciphertext_size, | ||
| uint8_t * | encrypted_message, | ||
| size_t | encrypted_message_size ) |
Encrypt a message using an encapsulation key.
Encrypt a message by encapsulating the encapsulation key and encrypting the message with the resulting shared secret. This function can be called multiple times.
- Parameters
-
[in] message The buffer to the message to encrypt. [in] message_size Size of the above buffer. [in] encap_key The buffer to the encapsulation key. [in] encap_key_size Size of the above buffer. Must be at least ML_KEM_768_ENCAP_KEY_SIZE. [out] ciphertext An allocated buffer for the ciphertext. [in] ciphertext_size Size of the above buffer. Must be at least ML_KEM_768_CIPHERTEXT_SIZE. [out] encrypted_message An allocated buffer for the encrypted message. [in] encrypted_message_size Size of the above buffer. Must be message_size + ML_KEM_SHARED_SECRET_IV_SIZE.
◆ safequard_mlkem768_finalise()
| int safequard_mlkem768_finalise | ( | uint8_t * | context, |
| size_t | context_size ) |
Finalise the decryption process.
Finalise the decryption process. This function must be called by the receiver at the end of all decryption with this context. context can be freed after calling this function.
- Parameters
-
[in,out] context The buffer to the context. [in] context_size Size of the above buffer.
◆ safequard_mlkem768_init()
| int safequard_mlkem768_init | ( | uint8_t * | context, |
| size_t | context_size, | ||
| uint8_t * | encap_key, | ||
| size_t | encap_key_size, | ||
| size_t * | out ) |
Generate a new ML-KEM-768 keypair for encrypting and decrypting messages.
Generate a new ML-KEM-768 keypair.
This function should be called by the receiver of the encrypted messages. On successful execution of this function, context contains information for the receiver to decrypt the messages sent by the sender. The encapsulation (public) key bytes encap_key are expected to be transferred to the sender.
Related functions: safequard_mlkem768_encrypt(), safequard_mlkem768_decrypt(), safequard_mlkem768_finalise().
Pass NULL to context to get the required buffer size returned in out.
- Parameters
-
[out] context An allocated buffer for the context. [in] context_size Size of the above buffer. [in] encap_key An allocated buffer to the encapsulation key. [in] encap_key_size Size of the above buffer. [out] out If context is NULL, the requested size of the context buffer. If context is not NULL, the actual size of context used.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if encap_key or out is NULL. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if any of the buffers provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected.
◆ safequard_panic_wrap()
|
extern |
Panic the current thread.
This allows a program to terminate immediately and provide feedback to the caller of the program.
- Note
- To be supplied by the integrating application.
◆ safequard_sha512()
| int safequard_sha512 | ( | const uint8_t * | message, |
| size_t | message_size, | ||
| uint8_t * | hash, | ||
| size_t | hash_size ) |
Compute a SHA-512 digest of a message.
- Parameters
-
[in] message The buffer to the message. [in] message_size Size of the above buffer. [out] hash The buffer to the hash. [in] hash_size Size of the above buffer. Must be SHA_512_DIGEST_SIZE.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if message or hash is NULL. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if any of the buffers provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected.
◆ safequard_sha512_finalise()
| int safequard_sha512_finalise | ( | uint8_t * | context, |
| size_t | context_size, | ||
| uint8_t * | hash, | ||
| size_t | hash_size ) |
Finalise a SHA-512 operation and receive the hash.
- Parameters
-
[in] context The buffer to the context. [in] context_size Size of the above buffer. [out] hash The buffer to the hash. [in] hash_size Size of the above buffer. Must be SHA_512_DIGEST_SIZE.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if chunk is NULL. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if any of the buffers provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected.
◆ safequard_sha512_init()
| int safequard_sha512_init | ( | uint8_t * | context, |
| size_t | context_size, | ||
| size_t * | out ) |
Generate a new SHA-512 context for streaming hash operations.
Generate a new SHA-512 context for hashing a message in chunks.
Related functions: safequard_sha512_update(), safequard_sha512_finalise().
Pass NULL to context to get the required buffer size returned in out.
- Parameters
-
[out] context An allocated buffer for the context. [in] context_size Size of the above buffer. [out] out If context is NULL, the requested size of the context buffer. If context is not NULL, the actual size of context used.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if encap_key or out is NULL. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if any of the buffers provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected.
◆ safequard_sha512_update()
| int safequard_sha512_update | ( | uint8_t * | context, |
| size_t | context_size, | ||
| const uint8_t * | chunk, | ||
| size_t | chunk_size ) |
Update a SHA-512 context for streaming hashing operations.
Update a SHA-512 context with a chunk of message. The caller should call this function zero, one or more times with every sequential chunk (of size SHA_512_BLOCK_SIZE) of the message, including the final chunk (of up to SHA_512_BLOCK_SIZE), and then call safequard_sha512_finalise().
- Parameters
-
[in] context The buffer to the context. [in] context_size Size of the above buffer. [in] chunk The buffer to the message chunk. [in] chunk_size Size of the above buffer. Must be less than or equal to SHA_512_BLOCK_SIZE.
- Return values
-
SAFEQUARD_SUCCESS if successful. SAFEQUARD_ERROR_INVALID_ARGUMENT if chunk is NULL. SAFEQUARD_ERROR_BUFFER_TOO_SMALL if any of the buffers provided is too small. SAFEQUARD_ERROR_NOT_SUPPORTED if the requested operation or a parameter is not supported by this implementation. SAFEQUARD_ERROR_HARDWARE_FAILURE if a hardware failure is detected.
