fix: BIT STRING unused bits in PKCS#8 publicKey

Author: MarkAtwood

ChangeLog.md

@@ -38,6 +38,7 @@
   cache rows and columns, so an image written by a build with different
   dimensions is rejected with `CACHE_MATCH_ERROR` instead of being copied in.
   A saved cache from an older release cannot be restored by this one.
+* **BREAKING (RFC 5958)**: The `publicKey` field of PKCS#8 v2 private keys (`OneAsymmetricKey`) for Ed25519, Ed448, X25519, ML-DSA and Falcon is a BIT STRING and now carries its unused-bits byte, so keys written by wolfSSL load in ring and other conformant parsers, and wolfSSL reads theirs. X25519 key values are still stored in reversed byte order, a separate bug, so X25519 PKCS#8 keys do not yet interoperate. Keys written by earlier wolfSSL still decode, but earlier wolfSSL cannot read keys written by this release. To write keys that every version reads, use `wc_Ed25519PrivateKeyToDer` and the other `*PrivateKeyToDer` functions, which omit `publicKey`. `WC_MLDSA_44/65/87_BOTH_KEY_DER_SIZE` and `CURVE25519_MAX_KEY_TO_DER_SZ` each grow by one byte, so applications that size buffers from them must be recompiled. A non-empty `publicKey` that matches neither form is now rejected with `ASN_PARSE_E`; an empty one is still treated as absent. by @MarkAtwood (PR 11674)
 
 ## Post-Quantum Cryptography (PQC)
 

doc/dox_comments/header_files-ja/asn_public.h

@@ -1414,7 +1414,7 @@ int wc_Curve25519PublicKeyToDer(curve25519_key* key, byte* output, word32 inLen,
 /*!
     \ingroup ASN
 
-    \brief この関数は、Curve25519キーをDER形式にエンコードします。秘密鍵、公開鍵、または両方をエンコードできます。
+    \brief この関数は、Curve25519キーをDER形式にエンコードします。秘密鍵、公開鍵、または両方をエンコードできます。両方が設定されている場合、[1] publicKeyはRFC 5958に従いBIT STRINGとして書き込まれるため、この変更より前のwolfSSLリリースでは読み込めません。wc_Curve25519PrivateKeyToDer()はこのフィールドを出力しません。
 
     \return >0 成功、DERエンコーディングの長さ
     \return BAD_FUNC_ARG keyまたはoutputがnullの場合に返されます

doc/dox_comments/header_files-ja/wc_mldsa.h

@@ -757,12 +757,11 @@ int wc_MlDsaKey_PublicKeyToDer(wc_MlDsaKey* key, byte* output,
 /*!
     \ingroup ML_DSA
 
-    \brief ML-DSA鍵ペア(公開鍵+秘密鍵)をPKCS#8 OneAsymmetricKey構造としてDERにエンコードします。必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。
+    \brief ML-DSA鍵ペア(公開鍵+秘密鍵)をPKCS#8 OneAsymmetricKey構造としてDERにエンコードします。必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。WC_MLDSA_*_BOTH_KEY_DER_SIZEをハードコードするより、この方法を推奨します。この変更で1バイト増えたように、エンコード長が変わっても正しいサイズが得られます。[1] publicKeyはRFC 5958に従いBIT STRINGとして書き込まれるため、この変更より前のwolfSSLリリースでは読み込めません。wc_MlDsaKey_PrivateKeyToDer()はこのフィールドを出力しません。
 
     \return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。
-    \return BAD_FUNC_ARG keyがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
-    \return MISSING_KEY 秘密鍵が設定されていない場合に返されます。
-    \return BUFFER_E outputがNULLでなく、inLenが小さすぎる場合に返されます。
+    \return BAD_FUNC_ARG keyがNULLの場合、秘密鍵または公開鍵が設定されていない場合、パラメータセットが選択されていない場合、またはoutputがNULLでなくinLenがエンコードサイズより小さい場合に返されます。
+    \return BUFFER_E outputがNULLでなく、inLenが0の場合に返されます。
 
     \param [in] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
     \param [out] output DERエンコードを受け取るバッファ。サイズを問い合わせる場合はNULL。
@@ -777,10 +776,12 @@ int wc_MlDsaKey_KeyToDer(wc_MlDsaKey* key, byte* output, word32 inLen);
 /*!
     \ingroup ML_DSA
 
-    \brief ML-DSA秘密鍵をDERにエンコードします。FIPS 204では秘密鍵のエンコードに公開鍵の要素が含まれるため、この関数は現在wc_MlDsaKey_KeyToDer()のエイリアスであり、他のアルゴリズムとのAPIの一貫性のために維持されています。
+    \brief ML-DSA秘密鍵を、[1] publicKeyフィールドを含まないPKCS#8 OneAsymmetricKey v1構造としてDERにエンコードします。この出力は以前のwolfSSLリリースでも読み込めます。必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。
 
     \return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。
-    \return wc_MlDsaKey_KeyToDer()から引き継がれたエラーコードが返されます。
+    \return BAD_FUNC_ARG keyがNULLの場合、秘密鍵が設定されていない場合、パラメータセットが選択されていない場合、またはoutputがNULLでなくinLenが小さすぎる場合に返されます。
+    \return BUFFER_E outputがNULLでなく、inLenが0の場合に返されます。
+    \return MEMORY_E 動的メモリの割り当てに失敗した場合に返されます。
 
     \param [in] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
     \param [out] output DERエンコードを受け取るバッファ。サイズを問い合わせる場合はNULL。

doc/dox_comments/header_files/asn_public.h

@@ -2798,7 +2798,10 @@ int wc_Curve25519PublicKeyToDer(curve25519_key* key, byte* output, word32 outLen
     \ingroup ASN
 
     \brief This function encodes a Curve25519 key to DER format. It can encode
-    either a private key, a public key, or both.
+    either a private key, a public key, or both. When both are set, the
+    [1] publicKey is written as an RFC 5958 BIT STRING, which wolfSSL
+    releases before this change cannot read;
+    wc_Curve25519PrivateKeyToDer() omits it.
 
     \return >0 Success, length of DER encoding
     \return BAD_FUNC_ARG Returns if key or output is null
@@ -2917,6 +2920,9 @@ int wc_Ed25519PublicKeyDecode(const byte* input, word32* inOutIdx,
 /*!
     \ingroup Ed25519
     \brief Encodes Ed25519 key to DER format.
+    The [1] publicKey is written as an RFC 5958 BIT STRING, which
+    wolfSSL releases before this change cannot read; wc_Ed25519PrivateKeyToDer()
+    omits it.
 
     \return Size on success
     \return negative on error
@@ -3077,6 +3083,9 @@ int wc_Ed448PublicKeyDecode(const byte* input, word32* inOutIdx,
 /*!
     \ingroup Ed448
     \brief Encodes Ed448 key to DER format.
+    The [1] publicKey is written as an RFC 5958 BIT STRING, which
+    wolfSSL releases before this change cannot read; wc_Ed448PrivateKeyToDer()
+    omits it.
 
     \return Size on success
     \return negative on error

doc/dox_comments/header_files/falcon.h

@@ -549,6 +549,9 @@ int wc_Falcon_PublicKeyDecode(const byte* input, word32* inOutIdx,
 
     \brief Encodes a Falcon private key (with its public key) as a DER/ASN.1
     (PKCS#8) structure. Pass a NULL output to query the required length.
+    The [1] publicKey is written as an RFC 5958 BIT STRING, which
+    wolfSSL releases before this change cannot read; wc_Falcon_PrivateKeyToDer()
+    omits it.
 
     \return Number of bytes written (or required, if output is NULL) on success.
     \return BAD_FUNC_ARG or BUFFER_E on error.

doc/dox_comments/header_files/wc_mldsa.h

@@ -953,13 +953,18 @@ int wc_MlDsaKey_PublicKeyToDer(wc_MlDsaKey* key, byte* output,
 
     \brief Encodes an ML-DSA key pair (public + private) to DER as a
     PKCS#8 OneAsymmetricKey structure. Pass NULL as output to query
-    the required buffer size.
+    the required buffer size. Prefer this over hardcoding
+    WC_MLDSA_*_BOTH_KEY_DER_SIZE: the query stays correct if the
+    encoding length changes, as it did by one byte with this change.
+    The [1] publicKey is written as an RFC 5958 BIT STRING, which
+    wolfSSL releases before this change cannot read;
+    wc_MlDsaKey_PrivateKeyToDer() omits it.
 
     \return Size of the encoded DER in bytes on success.
-    \return BAD_FUNC_ARG if key is NULL or no parameter set is
-    selected.
-    \return MISSING_KEY if the private key has not been set.
-    \return BUFFER_E if output is non-NULL and inLen is too small.
+    \return BAD_FUNC_ARG if key is NULL, the private or public key
+    has not been set, no parameter set is selected, or output is
+    non-NULL and inLen is smaller than the encoding.
+    \return BUFFER_E if output is non-NULL and inLen is 0.
 
     \param [in] key Pointer to a wc_MlDsaKey with the private key.
     \param [out] output Buffer that receives the DER encoding, or
@@ -975,13 +980,17 @@ int wc_MlDsaKey_KeyToDer(wc_MlDsaKey* key, byte* output, word32 inLen);
 /*!
     \ingroup ML_DSA
 
-    \brief Encodes the ML-DSA private key to DER. Per FIPS 204 the
-    private key encoding includes the public component, so this
-    function is currently an alias of wc_MlDsaKey_KeyToDer() kept for
-    API parity with other algorithms.
+    \brief Encodes the ML-DSA private key to DER as a PKCS#8
+    OneAsymmetricKey v1 structure with no [1] publicKey field. Earlier
+    wolfSSL releases can read this output. Pass NULL as output to query
+    the required buffer size.
 
     \return Size of the encoded DER in bytes on success.
-    \return Inherited error codes from wc_MlDsaKey_KeyToDer().
+    \return BAD_FUNC_ARG if key is NULL, the private key has not been
+    set, no parameter set is selected, or output is non-NULL and inLen
+    is too small.
+    \return BUFFER_E if output is non-NULL and inLen is 0.
+    \return MEMORY_E if dynamic memory allocation fails.
 
     \param [in] key Pointer to a wc_MlDsaKey with the private key.
     \param [out] output Buffer that receives the DER encoding, or