Skip to content

Fix BIT STRING unused-bits byte in PKCS#8 v2 publicKey (RFC 5958) #11674

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MarkAtwood wants to merge 1 commit into
base: master
Choose a base branch
from
+603 −68
Open

Fix BIT STRING unused-bits byte in PKCS#8 v2 publicKey (RFC 5958) #11674

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ChangeLog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
2 changes: 1 addition & 1 deletion doc/dox_comments/header_files-ja/asn_public.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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の場合に返されます
Expand Down
13 changes: 7 additions & 6 deletions doc/dox_comments/header_files-ja/wc_mldsa.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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。
Expand All @@ -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。
Expand Down
11 changes: 10 additions & 1 deletion doc/dox_comments/header_files/asn_public.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions doc/dox_comments/header_files/falcon.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
29 changes: 19 additions & 10 deletions doc/dox_comments/header_files/wc_mldsa.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
Loading
Loading