From 8e0ce8fee3a906dccf324a1ad2b3437b9d8e138d Mon Sep 17 00:00:00 2001 From: Koji Takeda Date: Fri, 11 Sep 2026 19:03:26 +0900 Subject: [PATCH 1/2] Add Doxygen documentation for the wolfCrypt PKCS#12 API --- .../header_files-ja/doxygen_groups.h | 1 + doc/dox_comments/header_files-ja/pkcs12.h | 56 ++ .../header_files/doxygen_groups.h | 16 + doc/dox_comments/header_files/pkcs12.h | 485 ++++++++++++++++++ 4 files changed, 558 insertions(+) create mode 100644 doc/dox_comments/header_files-ja/pkcs12.h create mode 100644 doc/dox_comments/header_files/pkcs12.h diff --git a/doc/dox_comments/header_files-ja/doxygen_groups.h b/doc/dox_comments/header_files-ja/doxygen_groups.h index 189a38d0731..c44d763ed8f 100644 --- a/doc/dox_comments/header_files-ja/doxygen_groups.h +++ b/doc/dox_comments/header_files-ja/doxygen_groups.h @@ -258,6 +258,7 @@ \defgroup MD5 アルゴリズム - MD5 \defgroup PKCS7 アルゴリズム - PKCS7 \defgroup PKCS11 アルゴリズム - PKCS11 + \defgroup PKCS12 アルゴリズム - PKCS12 \defgroup Password アルゴリズム - パスワードベース \defgroup Poly1305 アルゴリズム - Poly1305 \defgroup PUF アルゴリズム - PUF diff --git a/doc/dox_comments/header_files-ja/pkcs12.h b/doc/dox_comments/header_files-ja/pkcs12.h new file mode 100644 index 00000000000..2488a58b07b --- /dev/null +++ b/doc/dox_comments/header_files-ja/pkcs12.h @@ -0,0 +1,56 @@ +/*! + \ingroup PKCS12 +*/ +WC_PKCS12* wc_PKCS12_new(void); + +/*! + \ingroup PKCS12 +*/ +WC_PKCS12* wc_PKCS12_new_ex(void* heap); + +/*! + \ingroup PKCS12 +*/ +void wc_PKCS12_free(WC_PKCS12* pkcs12); + +/*! + \ingroup PKCS12 +*/ +int wc_d2i_PKCS12(const byte* der, word32 derSz, WC_PKCS12* pkcs12); + +/*! + \ingroup PKCS12 +*/ +int wc_d2i_PKCS12_fp(const char* file, WC_PKCS12** pkcs12); + +/*! + \ingroup PKCS12 +*/ +int wc_i2d_PKCS12(WC_PKCS12* pkcs12, byte** der, int* derSz); + +/*! + \ingroup PKCS12 +*/ +int wc_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw, + byte** pkey, word32* pkeySz, byte** cert, word32* certSz, + WC_DerCertList** ca); + +/*! + \ingroup PKCS12 +*/ +int wc_PKCS12_parse_ex(WC_PKCS12* pkcs12, const char* psw, + byte** pkey, word32* pkeySz, byte** cert, word32* certSz, + WC_DerCertList** ca, int keepKeyHeader); + +/*! + \ingroup PKCS12 +*/ +WC_PKCS12* wc_PKCS12_create(char* pass, word32 passSz, + char* name, byte* key, word32 keySz, byte* cert, word32 certSz, + WC_DerCertList* ca, int nidKey, int nidCert, int iter, int macIter, + int keyType, void* heap); + +/*! + \ingroup PKCS12 +*/ +void wc_FreeCertList(WC_DerCertList* list, void* heap); diff --git a/doc/dox_comments/header_files/doxygen_groups.h b/doc/dox_comments/header_files/doxygen_groups.h index 4db1423b303..9374fd34a1e 100644 --- a/doc/dox_comments/header_files/doxygen_groups.h +++ b/doc/dox_comments/header_files/doxygen_groups.h @@ -299,6 +299,22 @@ \defgroup PKCS7 Algorithms - PKCS7 \defgroup TSP Time-Stamp Protocol (RFC 3161) \defgroup PKCS11 Algorithms - PKCS11 + \defgroup PKCS12 Algorithms - PKCS12 + PKCS #12 (RFC 7292) defines the PFX bundle format, a single password + protected file that carries a private key together with its + certificate and any CA certificates in the chain. It is the format + behind the common .p12 and .pfx files. wolfCrypt support is enabled + with --enable-pkcs12 or by defining HAVE_PKCS12, and also requires + password based key derivation (--enable-pwdbased). + + A bundle is read by allocating a WC_PKCS12 structure + (wc_PKCS12_new() or wc_PKCS12_new_ex()), decoding the DER into it + (wc_d2i_PKCS12() or wc_d2i_PKCS12_fp()), then verifying the MAC and + decrypting the contents with wc_PKCS12_parse(), which returns the + DER private key, the certificate, and optionally the CA chain.\n + A bundle is written by building the structure with + wc_PKCS12_create() and encoding it with wc_i2d_PKCS12().\n + See . \defgroup Password Algorithms - Password Based \defgroup Poly1305 Algorithms - Poly1305 \defgroup PUF Algorithms - PUF diff --git a/doc/dox_comments/header_files/pkcs12.h b/doc/dox_comments/header_files/pkcs12.h new file mode 100644 index 00000000000..7ec55c1ba54 --- /dev/null +++ b/doc/dox_comments/header_files/pkcs12.h @@ -0,0 +1,485 @@ +/*! + \ingroup PKCS12 + + \brief This function creates a new empty WC_PKCS12 structure, using the + default heap hint for dynamic memory. It is equivalent to calling + wc_PKCS12_new_ex() with a NULL heap. The returned structure must be freed + with wc_PKCS12_free(). + + \return pointer Returns a pointer to a newly allocated WC_PKCS12 structure + on success + \return NULL Returned if the allocation fails + + \param none No parameters. + + _Example_ + \code + WC_PKCS12* pkcs12 = wc_PKCS12_new(); + if (pkcs12 == NULL) { + // error allocating PKCS12 structure + } + + // use the PKCS12 structure + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_new_ex + \sa wc_PKCS12_free +*/ +WC_PKCS12* wc_PKCS12_new(void); + +/*! + \ingroup PKCS12 + + \brief This function creates a new empty WC_PKCS12 structure, associating + it with the heap hint given. The heap hint is stored in the structure and + is used for every subsequent dynamic allocation and free made on behalf of + this WC_PKCS12 object. The returned structure must be freed with + wc_PKCS12_free(). + + \return pointer Returns a pointer to a newly allocated WC_PKCS12 structure + on success + \return NULL Returned if the allocation fails + + \param heap pointer to a heap hint used for dynamic memory allocation, or + NULL to use the default + + _Example_ + \code + void* heap = NULL; // or a custom static memory heap hint + WC_PKCS12* pkcs12 = wc_PKCS12_new_ex(heap); + if (pkcs12 == NULL) { + // error allocating PKCS12 structure + } + + // use the PKCS12 structure + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_new + \sa wc_PKCS12_free +*/ +WC_PKCS12* wc_PKCS12_new_ex(void* heap); + +/*! + \ingroup PKCS12 + + \brief This function frees a WC_PKCS12 structure and all of the memory + associated with it, including the parsed authenticated safe and the MAC + data. Passing NULL is safe and does nothing. + + \return none No returns. + + \param pkcs12 pointer to the WC_PKCS12 structure to free + + _Example_ + \code + WC_PKCS12* pkcs12 = wc_PKCS12_new(); + + // initialize and use the PKCS12 structure + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_new + \sa wc_PKCS12_new_ex +*/ +void wc_PKCS12_free(WC_PKCS12* pkcs12); + +/*! + \ingroup PKCS12 + + \brief This function converts a DER-encoded PKCS #12 (PFX) buffer into a + WC_PKCS12 structure. The raw contents of each ContentInfo are stored in the + structure without being completely parsed or decoded; call + wc_PKCS12_parse() afterwards to decrypt the bundle and recover the private + key and certificates. + + \return 0 Returned on successfully decoding the PKCS #12 buffer + \return BAD_FUNC_ARG Returned if der or pkcs12 is NULL + \return ASN_PARSE_E Returned if there is an error parsing the PKCS #12 + structure + \return ASN_VERSION_E Returned if the version in the bundle is not + supported + \return MEMORY_E Returned if there is an error allocating memory + + \param der pointer to a buffer holding the DER-encoded PKCS #12 bundle + \param derSz size of the DER buffer + \param pkcs12 pointer to an allocated WC_PKCS12 structure in which to store + the decoded bundle + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte der[] = { }; // initialize with a DER-encoded PKCS #12 bundle + word32 derSz = sizeof(der); + + pkcs12 = wc_PKCS12_new(); + if (pkcs12 == NULL) { + // error allocating PKCS12 structure + } + + if (wc_d2i_PKCS12(der, derSz, pkcs12) != 0) { + // error decoding PKCS12 bundle + } + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_d2i_PKCS12_fp + \sa wc_i2d_PKCS12 + \sa wc_PKCS12_parse +*/ +int wc_d2i_PKCS12(const byte* der, word32 derSz, WC_PKCS12* pkcs12); + +/*! + \ingroup PKCS12 + + \brief This function reads a DER-encoded PKCS #12 (PFX) file from the file + system and decodes it into a WC_PKCS12 structure. If `*pkcs12` is NULL, a new + WC_PKCS12 structure is allocated for the caller and returned through the + pkcs12 argument; that structure is freed automatically if the decode fails. + In either case, a successfully returned structure must be freed by the + caller with wc_PKCS12_free(). This function is not available when + NO_FILESYSTEM is defined. + + \return 0 Returned on successfully reading and decoding the file + \return BAD_FUNC_ARG Returned if pkcs12 is NULL + \return MEMORY_E Returned if there is an error allocating memory + \return BAD_PATH_ERROR Returned if the file cannot be opened or read + + \param file path of the DER-encoded PKCS #12 file to read + \param pkcs12 pointer to a WC_PKCS12 pointer. If `*pkcs12` is NULL, a new + structure is allocated and returned here; otherwise the existing structure + is used. + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + + // let wc_d2i_PKCS12_fp allocate the structure for us + if (wc_d2i_PKCS12_fp("./certs/test-servercert.p12", &pkcs12) != 0) { + // error reading or decoding the PKCS12 file + } + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_d2i_PKCS12 + \sa wc_i2d_PKCS12 + \sa wc_PKCS12_parse +*/ +int wc_d2i_PKCS12_fp(const char* file, WC_PKCS12** pkcs12); + +/*! + \ingroup PKCS12 + + \brief This function encodes a WC_PKCS12 structure into a DER-encoded + PKCS #12 (PFX) buffer. It supports three modes of operation, selected by + the der and derSz arguments. Passing NULL for der queries the required + buffer size only: the size is stored in `*derSz`, LENGTH_ONLY_E is + returned, and no data is written. Passing a non-NULL der whose `*der` is + NULL allocates a buffer of the required size and stores its address in + `*der`, which the caller must free with XFREE() using DYNAMIC_TYPE_PKCS. + Passing a non-NULL der whose `*der` points to a caller-supplied buffer + writes the DER into that buffer, and returns BUFFER_E if a non-NULL derSz + indicates that the buffer is too small. In that last case `*der` is + advanced on success to one byte past the end of the encoded DER, following + the usual i2d convention, so the caller must keep its own copy of the + original pointer. + + \return Success On success, returns the size of the DER encoding in bytes + \return LENGTH_ONLY_E Returned when der is NULL, indicating that only the + required size was computed and stored in `*derSz` + \return BAD_FUNC_ARG Returned if pkcs12 is NULL, if the structure holds no + authenticated safe, or if both der and derSz are NULL + \return BUFFER_E Returned if a caller-supplied buffer is too small to hold + the encoding + \return MEMORY_E Returned if there is an error allocating memory + + \param pkcs12 pointer to the WC_PKCS12 structure to encode + \param der pointer to a buffer pointer in which to store the encoding, or + NULL to query the required size + \param derSz on a size query, receives the required size. When a + caller-supplied buffer is used, holds the size of that buffer on input; a + NULL value disables the buffer size check. + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* der = NULL; + int derSz = 0; + + // pkcs12 previously created with wc_PKCS12_create or decoded with + // wc_d2i_PKCS12 + + // query the required size + if (wc_i2d_PKCS12(pkcs12, NULL, &derSz) != LENGTH_ONLY_E) { + // error getting the encoded size + } + + // let wc_i2d_PKCS12 allocate the buffer for us + if (wc_i2d_PKCS12(pkcs12, &der, NULL) <= 0) { + // error encoding the PKCS12 bundle + } + + XFREE(der, NULL, DYNAMIC_TYPE_PKCS); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_d2i_PKCS12 + \sa wc_PKCS12_create +*/ +int wc_i2d_PKCS12(WC_PKCS12* pkcs12, byte** der, int* derSz); + +/*! + \ingroup PKCS12 + + \brief This function parses and decodes a WC_PKCS12 structure that was + previously populated by wc_d2i_PKCS12() or wc_d2i_PKCS12_fp(). The MAC on + the bundle is verified with the given password, the contents are decrypted, + and the private key, the end entity certificate, and optionally the CA + certificate chain are returned to the caller. The key and certificate are + returned in newly allocated buffers which the caller is responsible for + freeing: use XFREE(pkey, heap, DYNAMIC_TYPE_PUBLIC_KEY) for the key and + XFREE(cert, heap, DYNAMIC_TYPE_PKCS) for the certificate, where heap is the + heap hint associated with the WC_PKCS12 structure. The CA list, when + requested, must be freed with wc_FreeCertList(). The private key is + returned with the PKCS #8 header removed; use wc_PKCS12_parse_ex() if the + PKCS #8 header should be kept. + + \note When USER_RSA is enabled this function may return a certificate that + is not the pair of the returned key when RSA key pairs are used. + + \return 0 Returned on successfully parsing the PKCS #12 bundle + \return BAD_FUNC_ARG Returned if pkcs12, psw, pkey, pkeySz, cert or certSz + is NULL + \return MAC_CMP_FAILED_E Returned if the MAC verification fails, which + usually means the password is incorrect + \return ASN_PARSE_E Returned if there is an error parsing the contents + \return MEMORY_E Returned if there is an error allocating memory + \return UNICODE_SIZE_E Returned if the password cannot be converted to the + Unicode form required for key derivation + + \param pkcs12 pointer to a WC_PKCS12 structure holding a decoded bundle + \param psw NULL-terminated password used to verify the MAC and decrypt the + bundle + \param[out] pkey receives a newly allocated buffer holding the DER-encoded + private key + \param[out] pkeySz receives the size of the private key buffer + \param[out] cert receives a newly allocated buffer holding the DER-encoded + certificate + \param[out] certSz receives the size of the certificate buffer + \param[out] ca optional. If non-NULL, receives a linked list of the + remaining DER-encoded certificates found in the bundle. Free with + wc_FreeCertList(). + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* key = NULL; + byte* cert = NULL; + WC_DerCertList* ca = NULL; + word32 keySz = 0; + word32 certSz = 0; + + if (wc_d2i_PKCS12_fp("./certs/test-servercert.p12", &pkcs12) != 0) { + // error reading the PKCS12 file + } + + if (wc_PKCS12_parse(pkcs12, "password", &key, &keySz, &cert, &certSz, + &ca) != 0) { + // error parsing the bundle, e.g. wrong password + } + + // use the key, cert and ca chain + + XFREE(key, NULL, DYNAMIC_TYPE_PUBLIC_KEY); + XFREE(cert, NULL, DYNAMIC_TYPE_PKCS); + wc_FreeCertList(ca, NULL); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_parse_ex + \sa wc_d2i_PKCS12 + \sa wc_FreeCertList +*/ +int wc_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw, + byte** pkey, word32* pkeySz, byte** cert, word32* certSz, + WC_DerCertList** ca); + +/*! + \ingroup PKCS12 + + \brief This function behaves exactly like wc_PKCS12_parse() but adds the + keepKeyHeader argument, which controls whether the PKCS #8 header is left + on the returned private key. Calling wc_PKCS12_parse() is equivalent to + calling this function with keepKeyHeader set to 0. The same ownership rules + as wc_PKCS12_parse() apply: free the key with XFREE(pkey, heap, + DYNAMIC_TYPE_PUBLIC_KEY), the certificate with XFREE(cert, heap, + DYNAMIC_TYPE_PKCS), and the CA list with wc_FreeCertList(). + + \note When USER_RSA is enabled this function may return a certificate that + is not the pair of the returned key when RSA key pairs are used. + + \return 0 Returned on successfully parsing the PKCS #12 bundle + \return BAD_FUNC_ARG Returned if pkcs12, psw, pkey, pkeySz, cert or certSz + is NULL + \return MAC_CMP_FAILED_E Returned if the MAC verification fails, which + usually means the password is incorrect + \return ASN_PARSE_E Returned if there is an error parsing the contents + \return MEMORY_E Returned if there is an error allocating memory + \return UNICODE_SIZE_E Returned if the password cannot be converted to the + Unicode form required for key derivation + + \param pkcs12 pointer to a WC_PKCS12 structure holding a decoded bundle + \param psw NULL-terminated password used to verify the MAC and decrypt the + bundle + \param[out] pkey receives a newly allocated buffer holding the DER-encoded + private key + \param[out] pkeySz receives the size of the private key buffer + \param[out] cert receives a newly allocated buffer holding the DER-encoded + certificate + \param[out] certSz receives the size of the certificate buffer + \param[out] ca optional. If non-NULL, receives a linked list of the + remaining DER-encoded certificates found in the bundle. Free with + wc_FreeCertList(). + \param keepKeyHeader 0 to strip the PKCS #8 header from the returned key, + any other value to keep it + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* key = NULL; + byte* cert = NULL; + WC_DerCertList* ca = NULL; + word32 keySz = 0; + word32 certSz = 0; + + // pkcs12 previously decoded with wc_d2i_PKCS12 or wc_d2i_PKCS12_fp + + // keep the PKCS #8 header on the returned private key + if (wc_PKCS12_parse_ex(pkcs12, "password", &key, &keySz, &cert, &certSz, + &ca, 1) != 0) { + // error parsing the bundle + } + + XFREE(key, NULL, DYNAMIC_TYPE_PUBLIC_KEY); + XFREE(cert, NULL, DYNAMIC_TYPE_PKCS); + wc_FreeCertList(ca, NULL); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_parse + \sa wc_d2i_PKCS12 + \sa wc_FreeCertList +*/ +int wc_PKCS12_parse_ex(WC_PKCS12* pkcs12, const char* psw, + byte** pkey, word32* pkeySz, byte** cert, word32* certSz, + WC_DerCertList** ca, int keepKeyHeader); + +/*! + \ingroup PKCS12 + + \brief This function creates a new WC_PKCS12 structure from a DER-encoded + private key, a DER-encoded certificate, and an optional list of extra + certificates. The key and certificate are each placed in their own + ContentInfo, optionally encrypted with the password given, and a MAC is + computed over the result. The returned structure can be encoded to DER with + wc_i2d_PKCS12() and must be freed with wc_PKCS12_free(). The nidKey and + nidCert arguments select the password-based encryption applied to the key + and to the certificate respectively. Supported values are + PBE_SHA1_RC4_128, PBE_SHA1_DES, PBE_SHA1_DES3, PBE_AES128_CBC and + PBE_AES256_CBC. Passing -1 stores the corresponding content unencrypted. + + \note The name and keyType arguments are accepted for API compatibility but + are not currently used. + + \return pointer Returns a pointer to a newly created WC_PKCS12 structure on + success + \return NULL Returned if the RNG cannot be initialized, if memory + allocation fails, if an unsupported nidKey or nidCert is given, or if the + bundle cannot be built + + \param pass password to use for encryption and for the MAC + \param passSz size of the password buffer + \param name friendlyName to use. Not currently used. + \param key buffer holding the DER-encoded private key + \param keySz size of the key buffer + \param cert buffer holding the DER-encoded certificate + \param certSz size of the certificate buffer + \param ca optional linked list of additional DER-encoded certificates to + include, or NULL + \param nidKey encryption to apply to the private key, or -1 for none + \param nidCert encryption to apply to the certificate, or -1 for none + \param iter number of iterations to use for the encryption. Values of 0 or + less select WC_PKCS12_ITT_DEFAULT. + \param macIter number of iterations to use when creating the MAC + \param keyType flag for a signature and/or encryption key. Not currently + used. + \param heap pointer to a heap hint used for dynamic memory allocation, or + NULL to use the default + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* der = NULL; + char pass[] = "password"; + byte key[] = { }; // initialize with a DER-encoded private key + byte cert[] = { }; // initialize with a DER-encoded certificate + + pkcs12 = wc_PKCS12_create(pass, sizeof(pass) - 1, NULL, + key, sizeof(key), cert, sizeof(cert), NULL, + PBE_AES256_CBC, PBE_AES256_CBC, + WC_PKCS12_ITT_DEFAULT, WC_PKCS12_ITT_DEFAULT, + 0, NULL); + if (pkcs12 == NULL) { + // error creating the PKCS12 bundle + } + + if (wc_i2d_PKCS12(pkcs12, &der, NULL) <= 0) { + // error encoding the bundle to DER + } + + XFREE(der, NULL, DYNAMIC_TYPE_PKCS); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_i2d_PKCS12 + \sa wc_PKCS12_parse + \sa wc_PKCS12_free +*/ +WC_PKCS12* wc_PKCS12_create(char* pass, word32 passSz, + char* name, byte* key, word32 keySz, byte* cert, word32 certSz, + WC_DerCertList* ca, int nidKey, int nidCert, int iter, int macIter, + int keyType, void* heap); + +/*! + \ingroup PKCS12 + + \brief This function frees a WC_DerCertList linked list, including the DER + buffer held by each node. It is used to release the CA certificate list + returned by wc_PKCS12_parse() and wc_PKCS12_parse_ex(). The heap hint given + must match the one associated with the WC_PKCS12 structure the list came + from. Passing NULL for the list is safe and does nothing. + + \return none No returns. + + \param list pointer to the head of the WC_DerCertList to free + \param heap pointer to the heap hint used when the list was allocated + + _Example_ + \code + WC_DerCertList* ca = NULL; + + // ca populated by a previous call to wc_PKCS12_parse + + wc_FreeCertList(ca, NULL); + \endcode + + \sa wc_PKCS12_parse + \sa wc_PKCS12_parse_ex +*/ +void wc_FreeCertList(WC_DerCertList* list, void* heap); From 33f6e27fd048db42d2fa0ae8efcfbf1f7f7f6b21 Mon Sep 17 00:00:00 2001 From: Koji Takeda Date: Fri, 11 Sep 2026 22:18:22 +0900 Subject: [PATCH 2/2] Add Japanese Doxygen documentation for the wolfCrypt PKCS#12 API --- .../header_files-ja/doxygen_groups.h | 14 + doc/dox_comments/header_files-ja/pkcs12.h | 326 ++++++++++++++++++ 2 files changed, 340 insertions(+) diff --git a/doc/dox_comments/header_files-ja/doxygen_groups.h b/doc/dox_comments/header_files-ja/doxygen_groups.h index c44d763ed8f..8e97faf7b50 100644 --- a/doc/dox_comments/header_files-ja/doxygen_groups.h +++ b/doc/dox_comments/header_files-ja/doxygen_groups.h @@ -259,6 +259,20 @@ \defgroup PKCS7 アルゴリズム - PKCS7 \defgroup PKCS11 アルゴリズム - PKCS11 \defgroup PKCS12 アルゴリズム - PKCS12 + PKCS #12（RFC 7292）はPFXバンドル形式を定義しています。これは、秘密鍵とその証明書、 + およびチェーン内のCA証明書をまとめて格納する、パスワードで保護された単一のファイルです。 + 一般的な.p12ファイルや.pfxファイルはこの形式です。wolfCryptのサポートは + --enable-pkcs12を指定するか、HAVE_PKCS12を定義することで有効になります。 + またパスワードベースの鍵導出（--enable-pwdbased）も必要です。 + + バンドルの読み込みは、WC_PKCS12構造体を割り当て（wc_PKCS12_new()または + wc_PKCS12_new_ex()）、DERをデコードし（wc_d2i_PKCS12()または + wc_d2i_PKCS12_fp()）、wc_PKCS12_parse()でMACを検証して内容を復号する、 + という手順で行います。wc_PKCS12_parse()はDER形式の秘密鍵、証明書、 + および任意でCAチェーンを返します。\n + バンドルの書き出しは、wc_PKCS12_create()で構造体を構築し、 + wc_i2d_PKCS12()でエンコードすることで行います。\n + をご参照ください。 \defgroup Password アルゴリズム - パスワードベース \defgroup Poly1305 アルゴリズム - Poly1305 \defgroup PUF アルゴリズム - PUF diff --git a/doc/dox_comments/header_files-ja/pkcs12.h b/doc/dox_comments/header_files-ja/pkcs12.h index 2488a58b07b..97bbc597fa0 100644 --- a/doc/dox_comments/header_files-ja/pkcs12.h +++ b/doc/dox_comments/header_files-ja/pkcs12.h @@ -1,35 +1,244 @@ /*! \ingroup PKCS12 + + \brief この関数は、空のWC_PKCS12構造体を新たに作成します。動的メモリにはデフォルトのヒープヒントを使用します。wc_PKCS12_new_ex()にNULLのヒープを渡して呼び出すことと同等です。返された構造体はwc_PKCS12_free()で解放する必要があります。 + + \return pointer 成功時に、新たに割り当てられたWC_PKCS12構造体へのポインタを返します。 + \return NULL メモリ割り当てに失敗した場合に返されます。 + + \param none パラメータはありません。 + + _Example_ + \code + WC_PKCS12* pkcs12 = wc_PKCS12_new(); + if (pkcs12 == NULL) { + // PKCS12構造体の割り当てエラー + } + + // PKCS12構造体を使用する + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_new_ex + \sa wc_PKCS12_free */ WC_PKCS12* wc_PKCS12_new(void); /*! \ingroup PKCS12 + + \brief この関数は、指定されたヒープヒントを関連付けて、空のWC_PKCS12構造体を新たに作成します。ヒープヒントは構造体に保存され、このWC_PKCS12オブジェクトのために行われる以降のすべての動的な割り当てと解放に使用されます。返された構造体はwc_PKCS12_free()で解放する必要があります。 + + \return pointer 成功時に、新たに割り当てられたWC_PKCS12構造体へのポインタを返します。 + \return NULL メモリ割り当てに失敗した場合に返されます。 + + \param heap 動的メモリ割り当てに使用するヒープヒントへのポインタ。デフォルトを使用する場合はNULLを指定します。 + + _Example_ + \code + void* heap = NULL; // またはカスタム静的メモリのヒープヒント + WC_PKCS12* pkcs12 = wc_PKCS12_new_ex(heap); + if (pkcs12 == NULL) { + // PKCS12構造体の割り当てエラー + } + + // PKCS12構造体を使用する + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_new + \sa wc_PKCS12_free */ WC_PKCS12* wc_PKCS12_new_ex(void* heap); /*! \ingroup PKCS12 + + \brief この関数は、WC_PKCS12構造体と、解析済みのAuthenticated SafeやMACデータを含む、それに関連するすべてのメモリを解放します。NULLを渡しても安全で、その場合は何も行いません。 + + \return none 戻り値はありません。 + + \param pkcs12 解放するWC_PKCS12構造体へのポインタ。 + + _Example_ + \code + WC_PKCS12* pkcs12 = wc_PKCS12_new(); + + // PKCS12構造体を初期化して使用する + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_new + \sa wc_PKCS12_new_ex */ void wc_PKCS12_free(WC_PKCS12* pkcs12); /*! \ingroup PKCS12 + + \brief この関数は、DERエンコードされたPKCS #12（PFX）バッファをWC_PKCS12構造体に変換します。各ContentInfoの内容は完全に解析またはデコードされることなく、そのままの形で構造体に格納されます。バンドルを復号して秘密鍵と証明書を取り出すには、この後にwc_PKCS12_parse()を呼び出してください。 + + \return 0 PKCS #12バッファのデコードに成功した場合に返されます。 + \return BAD_FUNC_ARG derまたはpkcs12がNULLの場合に返されます。 + \return ASN_PARSE_E PKCS #12構造の解析エラーがある場合に返されます。 + \return ASN_VERSION_E バンドル内のバージョンがサポートされていない場合に返されます。 + \return MEMORY_E メモリ割り当てエラーがある場合に返されます。 + + \param der DERエンコードされたPKCS #12バンドルを保持するバッファへのポインタ。 + \param derSz DERバッファのサイズ。 + \param pkcs12 デコードされたバンドルを格納する、割り当て済みのWC_PKCS12構造体へのポインタ。 + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte der[] = { }; // DERエンコードされたPKCS #12バンドルで初期化 + word32 derSz = sizeof(der); + + pkcs12 = wc_PKCS12_new(); + if (pkcs12 == NULL) { + // PKCS12構造体の割り当てエラー + } + + if (wc_d2i_PKCS12(der, derSz, pkcs12) != 0) { + // PKCS12バンドルのデコードエラー + } + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_d2i_PKCS12_fp + \sa wc_i2d_PKCS12 + \sa wc_PKCS12_parse */ int wc_d2i_PKCS12(const byte* der, word32 derSz, WC_PKCS12* pkcs12); /*! \ingroup PKCS12 + + \brief この関数は、DERエンコードされたPKCS #12（PFX）ファイルをファイルシステムから読み込み、WC_PKCS12構造体にデコードします。`*pkcs12`がNULLの場合、WC_PKCS12構造体が呼び出し元のために新たに割り当てられ、pkcs12引数を通じて返されます。この場合、デコードに失敗するとその構造体は自動的に解放されます。いずれの場合も、正常に返された構造体は呼び出し元がwc_PKCS12_free()で解放する必要があります。この関数はNO_FILESYSTEMが定義されている場合は使用できません。 + + \return 0 ファイルの読み込みとデコードに成功した場合に返されます。 + \return BAD_FUNC_ARG pkcs12がNULLの場合に返されます。 + \return MEMORY_E メモリ割り当てエラーがある場合に返されます。 + \return BAD_PATH_ERROR ファイルを開けないか読み込めない場合に返されます。 + + \param file 読み込むDERエンコードされたPKCS #12ファイルのパス。 + \param pkcs12 WC_PKCS12ポインタへのポインタ。`*pkcs12`がNULLの場合、新しい構造体が割り当てられてここに返されます。NULLでない場合は既存の構造体が使用されます。 + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + + // wc_d2i_PKCS12_fpに構造体を割り当てさせる + if (wc_d2i_PKCS12_fp("./certs/test-servercert.p12", &pkcs12) != 0) { + // PKCS12ファイルの読み込みまたはデコードのエラー + } + + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_d2i_PKCS12 + \sa wc_i2d_PKCS12 + \sa wc_PKCS12_parse */ int wc_d2i_PKCS12_fp(const char* file, WC_PKCS12** pkcs12); /*! \ingroup PKCS12 + + \brief この関数は、WC_PKCS12構造体をDERエンコードされたPKCS #12（PFX）バッファにエンコードします。der引数とderSz引数によって選択される3つの動作モードがあります。derにNULLを渡した場合は必要なバッファサイズの問い合わせのみを行い、サイズが`*derSz`に格納され、LENGTH_ONLY_Eが返されます。データは書き込まれません。derがNULLでなく`*der`がNULLの場合は必要なサイズのバッファを割り当て、そのアドレスを`*der`に格納します。呼び出し元はDYNAMIC_TYPE_PKCSを指定したXFREE()で解放する必要があります。derがNULLでなく`*der`が呼び出し元の用意したバッファを指している場合は、そのバッファにDERを書き込みます。derSzがNULLでなく、バッファが小さすぎることを示している場合はBUFFER_Eを返します。この最後のケースでは、成功時に`*der`が通常のi2dの慣例に従ってエンコードされたDERの末尾の次のバイトへ進められるため、呼び出し元は元のポインタを別途保持しておく必要があります。 + + \return Success 成功時に、DERエンコーディングのサイズをバイト単位で返します。 + \return LENGTH_ONLY_E derがNULLの場合に返され、必要なサイズのみが計算されて`*derSz`に格納されたことを示します。 + \return BAD_FUNC_ARG pkcs12がNULLの場合、構造体がAuthenticated Safeを保持していない場合、またはderとderSzの両方がNULLの場合に返されます。 + \return BUFFER_E 呼び出し元が用意したバッファがエンコーディングを格納するには小さすぎる場合に返されます。 + \return MEMORY_E メモリ割り当てエラーがある場合に返されます。 + + \param pkcs12 エンコードするWC_PKCS12構造体へのポインタ。 + \param der エンコーディングを格納するバッファポインタへのポインタ。必要なサイズを問い合わせる場合はNULLを指定します。 + \param derSz サイズ問い合わせ時には必要なサイズを受け取ります。呼び出し元が用意したバッファを使用する場合は、入力としてそのバッファのサイズを保持します。NULLを指定するとバッファサイズのチェックが無効になります。 + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* der = NULL; + int derSz = 0; + + // pkcs12はwc_PKCS12_createで作成済み、またはwc_d2i_PKCS12でデコード済みとする + + // 必要なサイズを問い合わせる + if (wc_i2d_PKCS12(pkcs12, NULL, &derSz) != LENGTH_ONLY_E) { + // エンコードサイズの取得エラー + } + + // wc_i2d_PKCS12にバッファを割り当てさせる + if (wc_i2d_PKCS12(pkcs12, &der, NULL) <= 0) { + // PKCS12バンドルのエンコードエラー + } + + XFREE(der, NULL, DYNAMIC_TYPE_PKCS); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_d2i_PKCS12 + \sa wc_PKCS12_create */ int wc_i2d_PKCS12(WC_PKCS12* pkcs12, byte** der, int* derSz); /*! \ingroup PKCS12 + + \brief この関数は、事前にwc_d2i_PKCS12()またはwc_d2i_PKCS12_fp()によって内容が設定されたWC_PKCS12構造体を解析してデコードします。指定されたパスワードでバンドルのMACを検証し、内容を復号して、秘密鍵、エンドエンティティ証明書、および任意でCA証明書チェーンを呼び出し元に返します。鍵と証明書は新たに割り当てられたバッファで返され、呼び出し元が解放する責任を負います。鍵にはXFREE(pkey, heap, DYNAMIC_TYPE_PUBLIC_KEY)を、証明書にはXFREE(cert, heap, DYNAMIC_TYPE_PKCS)を使用してください。ここでheapはWC_PKCS12構造体に関連付けられたヒープヒントです。CAリストを要求した場合は、wc_FreeCertList()で解放する必要があります。秘密鍵はPKCS #8ヘッダーが取り除かれた状態で返されます。PKCS #8ヘッダーを残したい場合はwc_PKCS12_parse_ex()を使用してください。 + + \note USER_RSAが有効な場合、RSA鍵ペアを使用していると、返された鍵と対にならない証明書が返される可能性があります。 + + \return 0 PKCS #12バンドルの解析に成功した場合に返されます。 + \return BAD_FUNC_ARG pkcs12、psw、pkey、pkeySz、certまたはcertSzがNULLの場合に返されます。 + \return MAC_CMP_FAILED_E MACの検証に失敗した場合に返されます。通常はパスワードが正しくないことを意味します。 + \return ASN_PARSE_E 内容の解析エラーがある場合に返されます。 + \return MEMORY_E メモリ割り当てエラーがある場合に返されます。 + \return UNICODE_SIZE_E 鍵導出に必要なUnicode形式にパスワードを変換できない場合に返されます。 + + \param pkcs12 デコード済みのバンドルを保持するWC_PKCS12構造体へのポインタ。 + \param psw MACの検証とバンドルの復号に使用するNULL終端のパスワード。 + \param[out] pkey DERエンコードされた秘密鍵を保持する、新たに割り当てられたバッファを受け取ります。 + \param[out] pkeySz 秘密鍵バッファのサイズを受け取ります。 + \param[out] cert DERエンコードされた証明書を保持する、新たに割り当てられたバッファを受け取ります。 + \param[out] certSz 証明書バッファのサイズを受け取ります。 + \param[out] ca 任意。NULLでない場合、バンドル内で見つかった残りのDERエンコード証明書のリンクリストを受け取ります。wc_FreeCertList()で解放してください。 + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* key = NULL; + byte* cert = NULL; + WC_DerCertList* ca = NULL; + word32 keySz = 0; + word32 certSz = 0; + + if (wc_d2i_PKCS12_fp("./certs/test-servercert.p12", &pkcs12) != 0) { + // PKCS12ファイルの読み込みエラー + } + + if (wc_PKCS12_parse(pkcs12, "password", &key, &keySz, &cert, &certSz, + &ca) != 0) { + // バンドルの解析エラー（パスワード誤りなど） + } + + // 鍵、証明書、CAチェーンを使用する + + XFREE(key, NULL, DYNAMIC_TYPE_PUBLIC_KEY); + XFREE(cert, NULL, DYNAMIC_TYPE_PKCS); + wc_FreeCertList(ca, NULL); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_parse_ex + \sa wc_d2i_PKCS12 + \sa wc_FreeCertList */ int wc_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw, byte** pkey, word32* pkeySz, byte** cert, word32* certSz, @@ -37,6 +246,53 @@ int wc_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw, /*! \ingroup PKCS12 + + \brief この関数はwc_PKCS12_parse()とまったく同じ動作をしますが、返される秘密鍵にPKCS #8ヘッダーを残すかどうかを制御するkeepKeyHeader引数が追加されています。wc_PKCS12_parse()を呼び出すことは、この関数をkeepKeyHeaderに0を指定して呼び出すことと同等です。所有権の規則もwc_PKCS12_parse()と同じです。鍵はXFREE(pkey, heap, DYNAMIC_TYPE_PUBLIC_KEY)で、証明書はXFREE(cert, heap, DYNAMIC_TYPE_PKCS)で、CAリストはwc_FreeCertList()で解放してください。 + + \note USER_RSAが有効な場合、RSA鍵ペアを使用していると、返された鍵と対にならない証明書が返される可能性があります。 + + \return 0 PKCS #12バンドルの解析に成功した場合に返されます。 + \return BAD_FUNC_ARG pkcs12、psw、pkey、pkeySz、certまたはcertSzがNULLの場合に返されます。 + \return MAC_CMP_FAILED_E MACの検証に失敗した場合に返されます。通常はパスワードが正しくないことを意味します。 + \return ASN_PARSE_E 内容の解析エラーがある場合に返されます。 + \return MEMORY_E メモリ割り当てエラーがある場合に返されます。 + \return UNICODE_SIZE_E 鍵導出に必要なUnicode形式にパスワードを変換できない場合に返されます。 + + \param pkcs12 デコード済みのバンドルを保持するWC_PKCS12構造体へのポインタ。 + \param psw MACの検証とバンドルの復号に使用するNULL終端のパスワード。 + \param[out] pkey DERエンコードされた秘密鍵を保持する、新たに割り当てられたバッファを受け取ります。 + \param[out] pkeySz 秘密鍵バッファのサイズを受け取ります。 + \param[out] cert DERエンコードされた証明書を保持する、新たに割り当てられたバッファを受け取ります。 + \param[out] certSz 証明書バッファのサイズを受け取ります。 + \param[out] ca 任意。NULLでない場合、バンドル内で見つかった残りのDERエンコード証明書のリンクリストを受け取ります。wc_FreeCertList()で解放してください。 + \param keepKeyHeader 返される鍵からPKCS #8ヘッダーを取り除く場合は0、残す場合は0以外を指定します。 + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* key = NULL; + byte* cert = NULL; + WC_DerCertList* ca = NULL; + word32 keySz = 0; + word32 certSz = 0; + + // pkcs12はwc_d2i_PKCS12またはwc_d2i_PKCS12_fpでデコード済みとする + + // 返される秘密鍵にPKCS #8ヘッダーを残す + if (wc_PKCS12_parse_ex(pkcs12, "password", &key, &keySz, &cert, &certSz, + &ca, 1) != 0) { + // バンドルの解析エラー + } + + XFREE(key, NULL, DYNAMIC_TYPE_PUBLIC_KEY); + XFREE(cert, NULL, DYNAMIC_TYPE_PKCS); + wc_FreeCertList(ca, NULL); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_PKCS12_parse + \sa wc_d2i_PKCS12 + \sa wc_FreeCertList */ int wc_PKCS12_parse_ex(WC_PKCS12* pkcs12, const char* psw, byte** pkey, word32* pkeySz, byte** cert, word32* certSz, @@ -44,6 +300,57 @@ int wc_PKCS12_parse_ex(WC_PKCS12* pkcs12, const char* psw, /*! \ingroup PKCS12 + + \brief この関数は、DERエンコードされた秘密鍵、DERエンコードされた証明書、および任意の追加証明書のリストから、新しいWC_PKCS12構造体を作成します。鍵と証明書はそれぞれ独自のContentInfoに配置され、指定されたパスワードで任意に暗号化された上で、その結果に対してMACが計算されます。返された構造体はwc_i2d_PKCS12()でDERにエンコードでき、wc_PKCS12_free()で解放する必要があります。nidKey引数とnidCert引数は、それぞれ鍵と証明書に適用されるパスワードベース暗号化を選択します。指定できる値はPBE_SHA1_RC4_128、PBE_SHA1_DES、PBE_SHA1_DES3、PBE_AES128_CBC、PBE_AES256_CBCです。-1を渡すと、対応する内容は暗号化されずに格納されます。 + + \note name引数とkeyType引数はAPIの互換性のために受け付けられますが、現在は使用されていません。 + + \return pointer 成功時に、新たに作成されたWC_PKCS12構造体へのポインタを返します。 + \return NULL RNGの初期化に失敗した場合、メモリ割り当てに失敗した場合、サポートされていないnidKeyまたはnidCertが指定された場合、あるいはバンドルを構築できなかった場合に返されます。 + + \param pass 暗号化とMACに使用するパスワード。 + \param passSz パスワードバッファのサイズ。 + \param name 使用するfriendlyName。現在は使用されていません。 + \param key DERエンコードされた秘密鍵を保持するバッファ。 + \param keySz 鍵バッファのサイズ。 + \param cert DERエンコードされた証明書を保持するバッファ。 + \param certSz 証明書バッファのサイズ。 + \param ca 任意。バンドルに含める追加のDERエンコード証明書のリンクリスト。不要な場合はNULLを指定します。 + \param nidKey 秘密鍵に適用する暗号化。暗号化しない場合は-1を指定します。 + \param nidCert 証明書に適用する暗号化。暗号化しない場合は-1を指定します。 + \param iter 暗号化に使用する反復回数。0以下の値を指定するとWC_PKCS12_ITT_DEFAULTが選択されます。 + \param macIter MACの作成に使用する反復回数。 + \param keyType 署名鍵または暗号化鍵を示すフラグ。現在は使用されていません。 + \param heap 動的メモリ割り当てに使用するヒープヒントへのポインタ。デフォルトを使用する場合はNULLを指定します。 + + _Example_ + \code + WC_PKCS12* pkcs12 = NULL; + byte* der = NULL; + char pass[] = "password"; + byte key[] = { }; // DERエンコードされた秘密鍵で初期化 + byte cert[] = { }; // DERエンコードされた証明書で初期化 + + pkcs12 = wc_PKCS12_create(pass, sizeof(pass) - 1, NULL, + key, sizeof(key), cert, sizeof(cert), NULL, + PBE_AES256_CBC, PBE_AES256_CBC, + WC_PKCS12_ITT_DEFAULT, WC_PKCS12_ITT_DEFAULT, + 0, NULL); + if (pkcs12 == NULL) { + // PKCS12バンドルの作成エラー + } + + if (wc_i2d_PKCS12(pkcs12, &der, NULL) <= 0) { + // バンドルのDERへのエンコードエラー + } + + XFREE(der, NULL, DYNAMIC_TYPE_PKCS); + wc_PKCS12_free(pkcs12); + \endcode + + \sa wc_i2d_PKCS12 + \sa wc_PKCS12_parse + \sa wc_PKCS12_free */ WC_PKCS12* wc_PKCS12_create(char* pass, word32 passSz, char* name, byte* key, word32 keySz, byte* cert, word32 certSz, @@ -52,5 +359,24 @@ WC_PKCS12* wc_PKCS12_create(char* pass, word32 passSz, /*! \ingroup PKCS12 + + \brief この関数は、WC_DerCertListのリンクリストを、各ノードが保持するDERバッファも含めて解放します。wc_PKCS12_parse()およびwc_PKCS12_parse_ex()が返すCA証明書リストの解放に使用します。指定するヒープヒントは、そのリストの取得元であるWC_PKCS12構造体に関連付けられたものと一致している必要があります。listにNULLを渡しても安全で、その場合は何も行いません。 + + \return none 戻り値はありません。 + + \param list 解放するWC_DerCertListの先頭へのポインタ。 + \param heap リストの割り当て時に使用されたヒープヒントへのポインタ。 + + _Example_ + \code + WC_DerCertList* ca = NULL; + + // caは事前のwc_PKCS12_parseの呼び出しによって設定されているとする + + wc_FreeCertList(ca, NULL); + \endcode + + \sa wc_PKCS12_parse + \sa wc_PKCS12_parse_ex */ void wc_FreeCertList(WC_DerCertList* list, void* heap);