pq_crypto 0.6.0 → 0.6.2

data/ext/pqcrypto/pqcrypto_secure.c

@@ -15,6 +15,9 @@
 #include <openssl/crypto.h>
 #include <openssl/evp.h>
 #include <openssl/rand.h>
+#include <openssl/x509.h>
+#include <openssl/pkcs12.h>
+#include <openssl/objects.h>
 
 #if OPENSSL_VERSION_NUMBER < 0x30000000L
 #error "OpenSSL 3.0 or later is required for pq_crypto"
@@ -1159,6 +1162,535 @@ int pq_secret_key_from_pqc_container_pem(char **algorithm_out, uint8_t **key_out
     return ret;
 }
 
+#define PQ_PKCS8_PRIVATE_KEY_PEM_LABEL           "PRIVATE KEY"
+#define PQ_PKCS8_ENCRYPTED_PRIVATE_KEY_PEM_LABEL "ENCRYPTED PRIVATE KEY"
+
+static size_t pq_der_length_octets(size_t len) {
+    size_t octets = 0;
+    size_t v = len;
+
+    if (len < 0x80)
+        return 1;
+    do {
+        octets++;
+        v >>= 8;
+    } while (v != 0);
+    return 1 + octets;
+}
+
+static int pq_der_write_length(uint8_t **cursor, size_t len) {
+    uint8_t *p;
+    size_t octets = 0;
+    size_t v = len;
+
+    if (!cursor || !*cursor)
+        return PQ_ERROR_BUFFER;
+
+    p = *cursor;
+    if (len < 0x80) {
+        *p++ = (uint8_t)len;
+        *cursor = p;
+        return PQ_SUCCESS;
+    }
+
+    do {
+        octets++;
+        v >>= 8;
+    } while (v != 0);
+    if (octets > sizeof(size_t))
+        return PQ_ERROR_BUFFER;
+
+    *p++ = (uint8_t)(0x80u | (uint8_t)octets);
+    for (size_t i = 0; i < octets; ++i) {
+        size_t shift = 8 * (octets - 1 - i);
+        *p++ = (uint8_t)((len >> shift) & 0xffu);
+    }
+    *cursor = p;
+    return PQ_SUCCESS;
+}
+
+static int pq_der_read_length(const uint8_t *input, size_t input_len, size_t *offset,
+                              size_t *len_out) {
+    uint8_t first;
+    size_t len = 0;
+    size_t length_octets;
+
+    if (!input || !offset || !len_out || *offset >= input_len)
+        return PQ_ERROR_BUFFER;
+
+    first = input[(*offset)++];
+    if (first < 0x80) {
+        *len_out = (size_t)first;
+        return PQ_SUCCESS;
+    }
+
+    length_octets = (size_t)(first & 0x7fu);
+    if (length_octets == 0 || length_octets > sizeof(size_t))
+        return PQ_ERROR_BUFFER;
+    if (input_len - *offset < length_octets)
+        return PQ_ERROR_BUFFER;
+    if (input[*offset] == 0)
+        return PQ_ERROR_BUFFER;
+
+    for (size_t i = 0; i < length_octets; ++i) {
+        if (len > (SIZE_MAX >> 8))
+            return PQ_ERROR_BUFFER;
+        len = (len << 8) | (size_t)input[*offset + i];
+    }
+    if (len < 0x80)
+        return PQ_ERROR_BUFFER;
+
+    *offset += length_octets;
+    *len_out = len;
+    return PQ_SUCCESS;
+}
+
+static int pq_der_expect_tlv(const uint8_t *input, size_t input_len, size_t *offset,
+                             uint8_t expected_tag, size_t *value_offset_out,
+                             size_t *value_len_out) {
+    size_t value_len;
+    size_t value_offset;
+
+    if (!input || !offset || !value_offset_out || !value_len_out || *offset >= input_len)
+        return PQ_ERROR_BUFFER;
+    if (input[(*offset)++] != expected_tag)
+        return PQ_ERROR_BUFFER;
+    if (pq_der_read_length(input, input_len, offset, &value_len) != PQ_SUCCESS)
+        return PQ_ERROR_BUFFER;
+    value_offset = *offset;
+    if (input_len - value_offset < value_len)
+        return PQ_ERROR_BUFFER;
+    *offset = value_offset + value_len;
+    *value_offset_out = value_offset;
+    *value_len_out = value_len;
+    return PQ_SUCCESS;
+}
+
+static int pq_oid_text_to_der(const char *oid_text, uint8_t **oid_der_out,
+                              size_t *oid_der_len_out) {
+    ASN1_OBJECT *obj = NULL;
+    uint8_t *der = NULL;
+    unsigned char *cursor;
+    int der_len;
+    int ret = PQ_ERROR_OPENSSL;
+
+    if (!oid_text || !oid_der_out || !oid_der_len_out)
+        return PQ_ERROR_BUFFER;
+    *oid_der_out = NULL;
+    *oid_der_len_out = 0;
+
+    obj = OBJ_txt2obj(oid_text, 1);
+    if (!obj)
+        goto cleanup;
+    der_len = i2d_ASN1_OBJECT(obj, NULL);
+    if (der_len <= 0)
+        goto cleanup;
+    der = malloc((size_t)der_len);
+    if (!der) {
+        ret = PQ_ERROR_NOMEM;
+        goto cleanup;
+    }
+    cursor = der;
+    if (i2d_ASN1_OBJECT(obj, &cursor) != der_len || (size_t)(cursor - der) != (size_t)der_len)
+        goto cleanup;
+
+    *oid_der_out = der;
+    *oid_der_len_out = (size_t)der_len;
+    der = NULL;
+    ret = PQ_SUCCESS;
+
+cleanup:
+    if (der) {
+        pq_secure_wipe(der, (size_t)(der_len > 0 ? der_len : 0));
+        free(der);
+    }
+    if (obj)
+        ASN1_OBJECT_free(obj);
+    return ret;
+}
+
+static int pq_oid_der_to_text(const uint8_t *oid_der, size_t oid_der_len, char **oid_text_out) {
+    ASN1_OBJECT *obj = NULL;
+    const unsigned char *cursor;
+    char tmp[128];
+    int text_len;
+    char *copy = NULL;
+    int ret = PQ_ERROR_OPENSSL;
+
+    if (!oid_der || oid_der_len == 0 || oid_der_len > (size_t)LONG_MAX || !oid_text_out)
+        return PQ_ERROR_BUFFER;
+    *oid_text_out = NULL;
+
+    cursor = oid_der;
+    obj = d2i_ASN1_OBJECT(NULL, &cursor, (long)oid_der_len);
+    if (!obj || cursor != oid_der + oid_der_len)
+        goto cleanup;
+    text_len = OBJ_obj2txt(tmp, sizeof(tmp), obj, 1);
+    if (text_len <= 0 || (size_t)text_len >= sizeof(tmp))
+        goto cleanup;
+    copy = malloc((size_t)text_len + 1);
+    if (!copy) {
+        ret = PQ_ERROR_NOMEM;
+        goto cleanup;
+    }
+    memcpy(copy, tmp, (size_t)text_len + 1);
+    *oid_text_out = copy;
+    copy = NULL;
+    ret = PQ_SUCCESS;
+
+cleanup:
+    if (copy)
+        free(copy);
+    if (obj)
+        ASN1_OBJECT_free(obj);
+    return ret;
+}
+
+int pq_pkcs8_private_key_info_to_der(uint8_t **output, size_t *output_len, const char *oid_text,
+                                     const uint8_t *private_key, size_t private_key_len) {
+    uint8_t *oid_der = NULL;
+    size_t oid_der_len = 0;
+    size_t alg_body_len, alg_len, priv_len, inner_len, total_len;
+    uint8_t *buf = NULL;
+    uint8_t *cur;
+    int ret;
+
+    if (!output || !output_len || !oid_text || !private_key)
+        return PQ_ERROR_BUFFER;
+    *output = NULL;
+    *output_len = 0;
+
+    ret = pq_oid_text_to_der(oid_text, &oid_der, &oid_der_len);
+    if (ret != PQ_SUCCESS)
+        return ret;
+
+    alg_body_len = oid_der_len;
+    alg_len = 1 + pq_der_length_octets(alg_body_len) + alg_body_len;
+    priv_len = 1 + pq_der_length_octets(private_key_len) + private_key_len;
+    if (pq_size_add(3, alg_len, &inner_len) != PQ_SUCCESS ||
+        pq_size_add(inner_len, priv_len, &inner_len) != PQ_SUCCESS) {
+        ret = PQ_ERROR_BUFFER;
+        goto cleanup;
+    }
+    if (pq_size_add(1 + pq_der_length_octets(inner_len), inner_len, &total_len) != PQ_SUCCESS) {
+        ret = PQ_ERROR_BUFFER;
+        goto cleanup;
+    }
+
+    buf = malloc(total_len);
+    if (!buf) {
+        ret = PQ_ERROR_NOMEM;
+        goto cleanup;
+    }
+
+    cur = buf;
+    *cur++ = 0x30;
+    ret = pq_der_write_length(&cur, inner_len);
+    if (ret != PQ_SUCCESS)
+        goto cleanup;
+    *cur++ = 0x02;
+    *cur++ = 0x01;
+    *cur++ = 0x00;
+    *cur++ = 0x30;
+    ret = pq_der_write_length(&cur, alg_body_len);
+    if (ret != PQ_SUCCESS)
+        goto cleanup;
+    memcpy(cur, oid_der, oid_der_len);
+    cur += oid_der_len;
+    *cur++ = 0x04;
+    ret = pq_der_write_length(&cur, private_key_len);
+    if (ret != PQ_SUCCESS)
+        goto cleanup;
+    memcpy(cur, private_key, private_key_len);
+    cur += private_key_len;
+    if ((size_t)(cur - buf) != total_len) {
+        ret = PQ_ERROR_BUFFER;
+        goto cleanup;
+    }
+
+    *output = buf;
+    *output_len = total_len;
+    buf = NULL;
+    ret = PQ_SUCCESS;
+
+cleanup:
+    if (buf) {
+        pq_secure_wipe(buf, total_len);
+        free(buf);
+    }
+    if (oid_der) {
+        pq_secure_wipe(oid_der, oid_der_len);
+        free(oid_der);
+    }
+    return ret;
+}
+
+int pq_pkcs8_private_key_info_from_der(char **oid_text_out, uint8_t **private_key_out,
+                                       size_t *private_key_len_out, const uint8_t *input,
+                                       size_t input_len) {
+    size_t offset = 0;
+    size_t outer_off = 0, outer_len = 0, outer_end;
+    size_t alg_off = 0, alg_len = 0, alg_end;
+    size_t oid_off = 0, oid_len = 0;
+    size_t priv_off = 0, priv_len = 0;
+    uint8_t *private_key = NULL;
+    char *oid_text = NULL;
+    int ret;
+
+    if (!oid_text_out || !private_key_out || !private_key_len_out || !input)
+        return PQ_ERROR_BUFFER;
+    *oid_text_out = NULL;
+    *private_key_out = NULL;
+    *private_key_len_out = 0;
+
+    ret = pq_der_expect_tlv(input, input_len, &offset, 0x30, &outer_off, &outer_len);
+    if (ret != PQ_SUCCESS)
+        return ret;
+    outer_end = outer_off + outer_len;
+    if (offset != input_len || outer_end != input_len)
+        return PQ_ERROR_BUFFER;
+
+    offset = outer_off;
+    {
+        size_t version_off = 0, version_len = 0;
+        ret = pq_der_expect_tlv(input, outer_end, &offset, 0x02, &version_off, &version_len);
+        if (ret != PQ_SUCCESS)
+            return ret;
+        if (version_len != 1 || input[version_off] != 0x00)
+            return PQ_ERROR_BUFFER;
+    }
+
+    ret = pq_der_expect_tlv(input, outer_end, &offset, 0x30, &alg_off, &alg_len);
+    if (ret != PQ_SUCCESS)
+        return ret;
+    alg_end = alg_off + alg_len;
+    {
+        size_t alg_cursor = alg_off;
+        size_t oid_tlv_start = alg_cursor;
+        ret = pq_der_expect_tlv(input, alg_end, &alg_cursor, 0x06, &oid_off, &oid_len);
+        if (ret != PQ_SUCCESS)
+            return ret;
+        if (alg_cursor != alg_end)
+            return PQ_ERROR_BUFFER;
+        ret = pq_oid_der_to_text(input + oid_tlv_start, alg_cursor - oid_tlv_start, &oid_text);
+    }
+    if (ret != PQ_SUCCESS)
+        return ret;
+
+    ret = pq_der_expect_tlv(input, outer_end, &offset, 0x04, &priv_off, &priv_len);
+    if (ret != PQ_SUCCESS)
+        goto cleanup;
+    if (offset != outer_end) {
+        ret = PQ_ERROR_BUFFER;
+        goto cleanup;
+    }
+    private_key = malloc(priv_len ? priv_len : 1);
+    if (!private_key) {
+        ret = PQ_ERROR_NOMEM;
+        goto cleanup;
+    }
+    if (priv_len)
+        memcpy(private_key, input + priv_off, priv_len);
+
+    *oid_text_out = oid_text;
+    *private_key_out = private_key;
+    *private_key_len_out = priv_len;
+    oid_text = NULL;
+    private_key = NULL;
+    ret = PQ_SUCCESS;
+
+cleanup:
+    if (oid_text)
+        free(oid_text);
+    if (private_key) {
+        pq_secure_wipe(private_key, priv_len);
+        free(private_key);
+    }
+    return ret;
+}
+
+int pq_pkcs8_encrypt_private_key_info_der(uint8_t **output, size_t *output_len,
+                                          const uint8_t *plain_der, size_t plain_der_len,
+                                          const char *passphrase, size_t passphrase_len,
+                                          int iterations) {
+    const unsigned char *cursor;
+    PKCS8_PRIV_KEY_INFO *p8 = NULL;
+    X509_SIG *encrypted = NULL;
+    unsigned char salt[16];
+    unsigned char *der = NULL;
+    unsigned char *der_cursor;
+    int der_len;
+    int ret = PQ_ERROR_OPENSSL;
+
+    if (!output || !output_len || !plain_der || !passphrase || iterations <= 0 ||
+        passphrase_len > (size_t)INT_MAX || plain_der_len > (size_t)LONG_MAX)
+        return PQ_ERROR_BUFFER;
+    *output = NULL;
+    *output_len = 0;
+
+    cursor = plain_der;
+    p8 = d2i_PKCS8_PRIV_KEY_INFO(NULL, &cursor, (long)plain_der_len);
+    if (!p8 || cursor != plain_der + plain_der_len)
+        goto cleanup;
+    if (RAND_bytes(salt, sizeof(salt)) != 1)
+        goto cleanup;
+
+    encrypted = PKCS8_encrypt(-1, EVP_aes_256_cbc(), passphrase, (int)passphrase_len, salt,
+                              (int)sizeof(salt), iterations, p8);
+    if (!encrypted)
+        goto cleanup;
+
+    der_len = i2d_X509_SIG(encrypted, NULL);
+    if (der_len <= 0) {
+        ret = PQ_ERROR_OPENSSL;
+        goto cleanup;
+    }
+    der = malloc((size_t)der_len);
+    if (!der) {
+        ret = PQ_ERROR_NOMEM;
+        goto cleanup;
+    }
+    der_cursor = der;
+    if (i2d_X509_SIG(encrypted, &der_cursor) != der_len ||
+        (size_t)(der_cursor - der) != (size_t)der_len)
+        goto cleanup;
+
+    *output = der;
+    *output_len = (size_t)der_len;
+    der = NULL;
+    ret = PQ_SUCCESS;
+
+cleanup:
+    pq_secure_wipe(salt, sizeof(salt));
+    if (der) {
+        pq_secure_wipe(der, (size_t)(der_len > 0 ? der_len : 0));
+        free(der);
+    }
+    if (encrypted)
+        X509_SIG_free(encrypted);
+    if (p8)
+        PKCS8_PRIV_KEY_INFO_free(p8);
+    return ret;
+}
+
+int pq_pkcs8_decrypt_private_key_info_der(uint8_t **output, size_t *output_len,
+                                          const uint8_t *encrypted_der, size_t encrypted_der_len,
+                                          const char *passphrase, size_t passphrase_len) {
+    const unsigned char *cursor;
+    X509_SIG *encrypted = NULL;
+    PKCS8_PRIV_KEY_INFO *p8 = NULL;
+    unsigned char *der = NULL;
+    unsigned char *der_cursor;
+    int der_len;
+    int ret = PQ_ERROR_OPENSSL;
+
+    if (!output || !output_len || !encrypted_der || !passphrase ||
+        passphrase_len > (size_t)INT_MAX || encrypted_der_len > (size_t)LONG_MAX)
+        return PQ_ERROR_BUFFER;
+    *output = NULL;
+    *output_len = 0;
+
+    cursor = encrypted_der;
+    encrypted = d2i_X509_SIG(NULL, &cursor, (long)encrypted_der_len);
+    if (!encrypted || cursor != encrypted_der + encrypted_der_len)
+        goto cleanup;
+    p8 = PKCS8_decrypt(encrypted, passphrase, (int)passphrase_len);
+    if (!p8)
+        goto cleanup;
+
+    der_len = i2d_PKCS8_PRIV_KEY_INFO(p8, NULL);
+    if (der_len <= 0)
+        goto cleanup;
+    der = malloc((size_t)der_len);
+    if (!der) {
+        ret = PQ_ERROR_NOMEM;
+        goto cleanup;
+    }
+    der_cursor = der;
+    if (i2d_PKCS8_PRIV_KEY_INFO(p8, &der_cursor) != der_len ||
+        (size_t)(der_cursor - der) != (size_t)der_len)
+        goto cleanup;
+
+    *output = der;
+    *output_len = (size_t)der_len;
+    der = NULL;
+    ret = PQ_SUCCESS;
+
+cleanup:
+    if (der) {
+        pq_secure_wipe(der, (size_t)(der_len > 0 ? der_len : 0));
+        free(der);
+    }
+    if (p8)
+        PKCS8_PRIV_KEY_INFO_free(p8);
+    if (encrypted)
+        X509_SIG_free(encrypted);
+    return ret;
+}
+
+int pq_pkcs8_der_is_encrypted_private_key_info(const uint8_t *input, size_t input_len) {
+    const unsigned char *cursor;
+    X509_SIG *encrypted = NULL;
+    const X509_ALGOR *alg = NULL;
+    const ASN1_OCTET_STRING *digest = NULL;
+    const ASN1_OBJECT *obj = NULL;
+    int ptype = 0;
+    const void *pval = NULL;
+    int ret = 0;
+
+    if (!input || input_len > (size_t)LONG_MAX)
+        return 0;
+    cursor = input;
+    encrypted = d2i_X509_SIG(NULL, &cursor, (long)input_len);
+    if (!encrypted || cursor != input + input_len)
+        goto cleanup;
+    X509_SIG_get0(encrypted, &alg, &digest);
+    if (!alg || !digest)
+        goto cleanup;
+    X509_ALGOR_get0(&obj, &ptype, &pval, alg);
+    (void)ptype;
+    (void)pval;
+    if (obj && OBJ_obj2nid(obj) == NID_pbes2)
+        ret = 1;
+
+cleanup:
+    if (encrypted)
+        X509_SIG_free(encrypted);
+    return ret;
+}
+
+int pq_pkcs8_der_to_pem(char **output, size_t *output_len, const uint8_t *der, size_t der_len,
+                        int encrypted) {
+    return pq_der_to_pem(encrypted ? PQ_PKCS8_ENCRYPTED_PRIVATE_KEY_PEM_LABEL
+                                   : PQ_PKCS8_PRIVATE_KEY_PEM_LABEL,
+                         der, der_len, output, output_len);
+}
+
+int pq_pkcs8_pem_to_der(uint8_t **der_out, size_t *der_len_out, int *encrypted_out,
+                        const char *input, size_t input_len) {
+    int ret;
+
+    if (!der_out || !der_len_out || !encrypted_out || !input)
+        return PQ_ERROR_BUFFER;
+    *der_out = NULL;
+    *der_len_out = 0;
+    *encrypted_out = 0;
+
+    ret = pq_pem_to_der(PQ_PKCS8_PRIVATE_KEY_PEM_LABEL, input, input_len, der_out, der_len_out);
+    if (ret == PQ_SUCCESS) {
+        *encrypted_out = 0;
+        return PQ_SUCCESS;
+    }
+
+    ret = pq_pem_to_der(PQ_PKCS8_ENCRYPTED_PRIVATE_KEY_PEM_LABEL, input, input_len, der_out,
+                        der_len_out);
+    if (ret == PQ_SUCCESS) {
+        *encrypted_out = 1;
+        return PQ_SUCCESS;
+    }
+    return PQ_ERROR_BUFFER;
+}
+
 const char *pq_version(void) {
     return PQCRYPTO_VERSION;
 }

data/ext/pqcrypto/pqcrypto_secure.h

@@ -132,6 +132,26 @@ int pq_secret_key_from_pqc_container_pem(char **algorithm_out, uint8_t **key_out
                                           size_t *key_len_out, const char *input,
                                           size_t input_len);
 
+int pq_pkcs8_private_key_info_to_der(uint8_t **output, size_t *output_len,
+                                     const char *oid_text, const uint8_t *private_key,
+                                     size_t private_key_len);
+int pq_pkcs8_private_key_info_from_der(char **oid_text_out, uint8_t **private_key_out,
+                                       size_t *private_key_len_out, const uint8_t *input,
+                                       size_t input_len);
+int pq_pkcs8_encrypt_private_key_info_der(uint8_t **output, size_t *output_len,
+                                          const uint8_t *plain_der, size_t plain_der_len,
+                                          const char *passphrase, size_t passphrase_len,
+                                          int iterations);
+int pq_pkcs8_decrypt_private_key_info_der(uint8_t **output, size_t *output_len,
+                                          const uint8_t *encrypted_der,
+                                          size_t encrypted_der_len, const char *passphrase,
+                                          size_t passphrase_len);
+int pq_pkcs8_der_is_encrypted_private_key_info(const uint8_t *input, size_t input_len);
+int pq_pkcs8_der_to_pem(char **output, size_t *output_len, const uint8_t *der, size_t der_len,
+                        int encrypted);
+int pq_pkcs8_pem_to_der(uint8_t **der_out, size_t *der_len_out, int *encrypted_out,
+                        const char *input, size_t input_len);
+
 int pq_testing_mlkem_keypair_from_seed(uint8_t *public_key, uint8_t *secret_key,
                                        const uint8_t *seed, size_t seed_len);
 int pq_testing_mlkem512_keypair_from_seed(uint8_t *public_key, uint8_t *secret_key,

data/ext/pqcrypto/pqcrypto_version.h

@@ -2,6 +2,6 @@
 #ifndef PQCRYPTO_VERSION_H
 #define PQCRYPTO_VERSION_H
 
-#define PQCRYPTO_VERSION "0.6.0"
+#define PQCRYPTO_VERSION "0.6.2"
 
 #endif

data/ext/pqcrypto/vendor/.vendored

@@ -6,7 +6,7 @@ mlkem_native_ref=v1.1.0
 mlkem_native_commit=d2cae2be522a67bfae26100fdb520576f1b2ef90
 mlkem_native_tree_sha256=c225de87a69e6d6360cddc4b5839b03e65fa9d5a1112a5f19700c905b7e74512
 mldsa_native_repo=https://github.com/pq-code-package/mldsa-native.git
-mldsa_native_ref=v1.0.0-beta
-mldsa_native_commit=db65535319d9750d75d34c6d170677415f9d2c46
-mldsa_native_tree_sha256=3b2cb648dade4540191f08d606b422042bf781fb37b434934ab02b58a0121f5c
-manifest_sha256=aeb28860537e30f4da0d28dc2961ba6bb06e700195a56f1648e5caddf1b6e1be
+mldsa_native_ref=v1.0.0-beta2
+mldsa_native_commit=9b0ee84f4cf399043eca59eca4e5f8531ca1d61b
+mldsa_native_tree_sha256=2887f59926c18a877e8c5a5e30727e84497c357032093d00d7135aedf53f011e
+manifest_sha256=cfcf998232945760d5fd66cc3ec0af54925e13844e1758f559eeb1c7ecf16ffc

data/ext/pqcrypto/vendor/mldsa-native/README.md

@@ -59,19 +59,14 @@ mldsa-native is used in
 
 We use the [C Bounded Model Checker (CBMC)](https://github.com/diffblue/cbmc) to prove absence of various classes of undefined behaviour in C, including out of bounds memory accesses and integer overflows. The proofs cover all C code in [mldsa/src/*](mldsa) and [mldsa/src/fips202/*](mldsa/src/fips202) involved in running mldsa-native with its C backend. See [proofs/cbmc](proofs/cbmc) for details.
 
-**Note:** The `MLD_CONFIG_REDUCE_RAM` configuration option is not currently covered by CBMC proofs.
-
-HOL-Light functional correctness proofs can be found in [proofs/hol_light](proofs/hol_light). So far, the following functions have been proven correct:
-
-- AArch64 poly_caddq [poly_caddq_asm.S](mldsa/src/native/aarch64/src/poly_caddq_asm.S)
-- x86_64 NTT [ntt.S](mldsa/src/native/x86_64/src/ntt.S)
-
-These proofs utilize the verification infrastructure in [s2n-bignum](https://github.com/awslabs/s2n-bignum).
+HOL-Light functional correctness proofs can be found in [proofs/hol_light](proofs/hol_light). See the [HOL-Light README](proofs/hol_light/README.md) for the list of functions that have been proven correct. These proofs utilize the verification infrastructure in [s2n-bignum](https://github.com/awslabs/s2n-bignum).
 
 Finally, [proofs/isabelle](proofs/isabelle/compress) contains proofs in [Isabelle/HOL](https://isabelle.in.tum.de/) of the correctness of
 different approaches for computing the scalar decomposition routines used in ML-DSA. Those are still experimental and do not yet operate
 on the source level.
 
+**NOTE:** Formal Verification is never absolute. See [SOUNDNESS.md](SOUNDNESS.md) for an analysis of the scope, assumptions and risks of the formal verification efforts around mldsa-native.
+
 ## Security
 
 All assembly in mldsa-native is constant-time in the sense that it is free of secret-dependent control flow, memory access,
@@ -81,6 +76,8 @@ timing side channels through suitable barriers and constant-time patterns.
 Absence of secret-dependent branches, memory-access patterns and variable-latency instructions is also tested using `valgrind`
 with various combinations of compilers and compilation options.
 
+**Other attacks.** mldsa-native targets resistance against timing side-channels only. Other attack classes, such as power and electromagnetic side-channels, microarchitectural side-channels (e.g. speculative execution), or fault-injection attacks, are currently out of scope.
+
 ## Design
 
 mldsa-native is split into a _frontend_ and two _backends_ for arithmetic and FIPS202 / SHA3. The frontend is
@@ -98,9 +95,12 @@ mldsa-native currently offers the following backends:
 
 If you'd like contribute new backends, please reach out!
 
-## ACVP Testing
+## Test Vectors
+
+mldsa-native is tested against all official ACVP ML-DSA test vectors[^ACVP] and the
+Wycheproof[^wycheproof] ML-DSA test vectors.
 
-mldsa-native is tested against all official ACVP ML-DSA test vectors[^ACVP].
+### ACVP
 
 You can run ACVP tests using the [`tests`](./scripts/tests) script or the [ACVP client](./test/acvp/acvp_client.py) directly:
 
@@ -122,6 +122,18 @@ python3 ./test/acvp/acvp_client.py \
   -e ./test/acvp/.acvp-data/v1.1.0.41/files/ML-DSA-sigVer-FIPS204/expectedResults.json
 ```
 
+### Wycheproof
+
+You can run Wycheproof[^wycheproof] tests using the [`tests`](./scripts/tests) script or the [Wycheproof client](./test/wycheproof/wycheproof_client.py) directly:
+
+```bash
+# Using the tests script
+./scripts/tests wycheproof
+
+# Using the Wycheproof client directly
+python3 ./test/wycheproof/wycheproof_client.py
+```
+
 ## Benchmarking
 
 You can measure performance, memory usage, and binary size using the [`tests`](./scripts/tests) script:
@@ -219,3 +231,4 @@ through the [PQCA Discord](https://discord.com/invite/xyVnwzfg5R). See also [CON
 [^NIST_FIPS204_SEC6]: National Institute of Standards and Technology: FIPS 204 Section 6 Guidance, [https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/faq/fips204-sec6-03192025.pdf](https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/faq/fips204-sec6-03192025.pdf)
 [^REF]: Bai, Ducas, Kiltz, Lepoint, Lyubashevsky, Schwabe, Seiler, Stehlé: CRYSTALS-Dilithium reference implementation, [https://github.com/pq-crystals/dilithium/tree/master/ref](https://github.com/pq-crystals/dilithium/tree/master/ref)
 [^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)
+[^wycheproof]: Community Cryptography Specification Project: Project Wycheproof, [https://github.com/C2SP/wycheproof](https://github.com/C2SP/wycheproof)

data/ext/pqcrypto/vendor/mldsa-native/mldsa/README.md

@@ -0,0 +1,23 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# mldsa-native source tree
+
+This is the main source tree of mldsa-native.
+
+## Building
+
+To build mldsa-native for a fixed parameter set (ML-DSA-44/65/87), build the compilation units in `src/*` separately, and link to an RNG and your application. See [examples/basic](../examples/basic) for a simple example.
+
+Alternatively, you can use the auto-generated helper files [mldsa_native.c](mldsa_native.c) and [mldsa_native_asm.S](mldsa_native_asm.S), which bundle all *.c and *.S files together. See [examples/monolithic_build](../examples/monolithic_build) and [examples/monolithic_build_native](../examples/monolithic_build_native) for examples with and without native code.
+
+## Configuration
+
+The build is configured by [mldsa_native_config.h](mldsa_native_config.h), or by the file pointed to by `MLD_CONFIG_FILE`. Note in particular `MLD_CONFIG_PARAMETER_SET` and `MLD_CONFIG_NAMESPACE_PREFIX`, which set the parameter set and namespace prefix, respectively.
+
+## API
+
+The public API is defined in [mldsa_native.h](mldsa_native.h).
+
+## Supporting multiple parameter sets
+
+If you want to support multiple parameter sets, build the library once per parameter set you want to support. Set `MLD_CONFIG_MULTILEVEL_WITH_SHARED` for one of the builds, and `MLD_CONFIG_MULTILEVEL_NO_SHARED` for the others, to avoid duplicating shared functionality. Finally, link with RNG and your application as before. This is demonstrated in the examples [examples/multilevel_build](../examples/multilevel_build), [examples/multilevel_build_native](../examples/multilevel_build_native), [examples/monolithic_build_multilevel](../examples/monolithic_build_multilevel) and [examples/monolithic_build_multilevel_native](../examples/monolithic_build_multilevel_native).