luna - wolfssl/doc/dox_comments/header_files/asn

   1/*!
   2    \ingroup ASN
   3
   4    \brief This function initializes a default cert, with the default options:
   5    version = 3 (0x2), serial = 0, sigType = SHA_WITH_RSA, issuer = blank,
   6    daysValid = 500, selfSigned = 1 (true) use subject as issuer,
   7    subject = blank
   8
   9    \return none No returns.
  10
  11    \param cert pointer to an uninitialized cert structure to initialize
  12
  13    _Example_
  14    \code
  15    Cert myCert;
  16    wc_InitCert(&myCert);
  17    \endcode
  18
  19    \sa wc_MakeCert
  20    \sa wc_MakeCertReq
  21*/
  22int wc_InitCert(Cert* cert);
  23
  24/*!
  25     \ingroup ASN
  26
  27     \brief This function allocates a new Cert structure for use during
  28     cert operations without the application having to allocate the structure
  29     itself. The Cert structure is also initialized by this function thus
  30     removing the need to call wc_InitCert(). When the application is finished
  31     using the allocated Cert structure wc_CertFree() must be called.
  32
  33     \return pointer If successful the call will return a pointer to the
  34     newly allocated and initialized Cert.
  35     \return NULL On a memory allocation failure.
  36
  37     \param A pointer to the heap used for dynamic allocation. Can be NULL.
  38
  39     _Example_
  40     \code
  41     Cert*   myCert;
  42
  43     myCert = wc_CertNew(NULL);
  44     if (myCert == NULL) {
  45         // Cert creation failure
  46     }
  47     \endcode
  48
  49     \sa wc_InitCert
  50     \sa wc_MakeCert
  51     \sa wc_CertFree
  52
  53*/
  54Cert* wc_CertNew(void* heap);
  55
  56/*!
  57    \ingroup ASN
  58    \brief Initializes certificate with heap hint and device ID.
  59
  60    \return 0 on success
  61    \return BAD_FUNC_ARG if cert is NULL
  62
  63    \param cert Cert structure to initialize
  64    \param heap Heap hint for memory allocation
  65    \param devId Device ID for hardware acceleration
  66
  67    _Example_
  68    \code
  69    Cert myCert;
  70    int ret = wc_InitCert_ex(&myCert, NULL, INVALID_DEVID);
  71    if (ret != 0) {
  72        // error initializing cert
  73    }
  74    \endcode
  75
  76    \sa wc_InitCert
  77    \sa wc_MakeCert_ex
  78*/
  79int wc_InitCert_ex(Cert* cert, void* heap, int devId);
  80
  81/*!
  82     \ingroup ASN
  83
  84     \brief This function frees the memory allocated for a cert structure
  85     by a previous call to wc_CertNew().
  86
  87     \return None.
  88
  89     \param A pointer to the cert structure to free.
  90
  91     _Example_
  92     \code
  93     Cert*   myCert;
  94
  95     myCert = wc_CertNew(NULL);
  96
  97     // Perform cert operations.
  98
  99     wc_CertFree(myCert);
 100     \endcode
 101
 102     \sa wc_InitCert
 103     \sa wc_MakeCert
 104     \sa wc_CertNew
 105
 106*/
 107void  wc_CertFree(Cert* cert);
 108
 109/*!
 110    \ingroup ASN
 111
 112    \brief Used to make CA signed certs. Called after the subject information
 113    has been entered. This function makes an x509 Certificate v3 RSA or ECC
 114    from a cert input. It then writes this cert to derBuffer. It takes in
 115    either an rsaKey or an eccKey to generate the certificate.  The certificate
 116    must be initialized with wc_InitCert before this method is called.
 117
 118    \return Success On successfully making an x509 certificate from the
 119    specified input cert, returns the size of the cert generated.
 120    \return MEMORY_E Returned if there is an error allocating memory
 121    with XMALLOC
 122    \return BUFFER_E Returned if the provided derBuffer is too small to
 123    store the generated certificate
 124    \return Others Additional error messages may be returned if the cert
 125    generation is not successful.
 126
 127    \param cert pointer to an initialized cert structure
 128    \param derBuffer pointer to the buffer in which to hold the generated cert
 129    \param derSz size of the buffer in which to store the cert
 130    \param rsaKey pointer to an RsaKey structure containing the rsa key used
 131    to generate the certificate
 132    \param eccKey pointer to an EccKey structure containing the ecc key used
 133    to generate the certificate
 134    \param rng pointer to the random number generator used to make the cert
 135
 136    _Example_
 137    \code
 138    Cert myCert;
 139    wc_InitCert(&myCert);
 140    WC_RNG rng;
 141    //initialize rng;
 142    RsaKey key;
 143    //initialize key;
 144    byte * derCert = malloc(FOURK_BUF);
 145    word32 certSz;
 146    certSz = wc_MakeCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
 147    \endcode
 148
 149    \sa wc_InitCert
 150    \sa wc_MakeCertReq
 151*/
 152int  wc_MakeCert(Cert* cert, byte* derBuffer, word32 derSz, RsaKey* rsaKey,
 153                             ecc_key* eccKey, WC_RNG* rng);
 154
 155/*!
 156    \ingroup ASN
 157    \brief Makes certificate with generic key type support.
 158
 159    \return Size of certificate on success
 160    \return MEMORY_E if memory allocation fails
 161    \return BUFFER_E if buffer too small
 162    \return Other error codes on failure
 163
 164    \param cert Initialized cert structure
 165    \param derBuffer Buffer for generated certificate
 166    \param derSz Size of derBuffer
 167    \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.)
 168    \param key Pointer to key structure
 169    \param rng Random number generator
 170
 171    _Example_
 172    \code
 173    Cert myCert;
 174    wc_InitCert(&myCert);
 175    byte derCert[4096];
 176    RsaKey key;
 177    WC_RNG rng;
 178    int certSz = wc_MakeCert_ex(&myCert, derCert, sizeof(derCert),
 179                                RSA_TYPE, &key, &rng);
 180    \endcode
 181
 182    \sa wc_MakeCert
 183    \sa wc_SignCert_ex
 184*/
 185int wc_MakeCert_ex(Cert* cert, byte* derBuffer, word32 derSz,
 186                  int keyType, void* key, WC_RNG* rng);
 187
 188/*!
 189    \ingroup ASN
 190    \brief Makes certificate request with generic key type support.
 191
 192    \return Size of certificate request on success
 193    \return MEMORY_E if memory allocation fails
 194    \return BUFFER_E if buffer too small
 195    \return Other error codes on failure
 196
 197    \param cert Initialized cert structure
 198    \param derBuffer Buffer for generated certificate request
 199    \param derSz Size of derBuffer
 200    \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.)
 201    \param key Pointer to key structure
 202
 203    _Example_
 204    \code
 205    Cert myCert;
 206    wc_InitCert(&myCert);
 207    byte derCert[4096];
 208    EccKey key;
 209    int certSz = wc_MakeCertReq_ex(&myCert, derCert, sizeof(derCert),
 210                                   ECC_TYPE, &key);
 211    \endcode
 212
 213    \sa wc_MakeCertReq
 214    \sa wc_SignCert_ex
 215*/
 216int wc_MakeCertReq_ex(Cert* cert, byte* derBuffer, word32 derSz,
 217                     int keyType, void* key);
 218
 219/*!
 220    \ingroup ASN
 221    \brief Signs certificate with generic key type support.
 222
 223    \return New size of certificate with signature on success
 224    \return MEMORY_E if memory allocation fails
 225    \return BUFFER_E if buffer too small
 226    \return Other error codes on failure
 227
 228    \param requestSz Size of certificate body to sign
 229    \param sType Signature type
 230    \param buf Buffer containing certificate to sign
 231    \param buffSz Total size of buffer
 232    \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.)
 233    \param key Pointer to key structure
 234    \param rng Random number generator
 235
 236    _Example_
 237    \code
 238    Cert myCert;
 239    byte derCert[4096];
 240    RsaKey key;
 241    WC_RNG rng;
 242    // Initialize cert and set fields (issuer, subject, dates, etc.)
 243    wc_InitCert(&myCert);
 244    // ... set myCert fields ...
 245    // Generate certificate body (TBS - To Be Signed)
 246    int bodySz = wc_MakeCert_ex(&myCert, derCert, sizeof(derCert),
 247                                RSA_TYPE, &key, &rng);
 248    if (bodySz > 0) {
 249        // bodySz is the size of the unsigned certificate body
 250        // Sign the certificate body and append signature
 251        int certSz = wc_SignCert_ex(bodySz, CTC_SHA256wRSA,
 252                                    derCert, sizeof(derCert), RSA_TYPE,
 253                                    &key, &rng);
 254        // derCert now contains complete signed certificate of size certSz
 255    }
 256    \endcode
 257
 258    \sa wc_SignCert
 259    \sa wc_MakeCert_ex
 260*/
 261int wc_SignCert_ex(int requestSz, int sType, byte* buf, word32 buffSz,
 262                  int keyType, void* key, WC_RNG* rng);
 263
 264/*!
 265    \ingroup ASN
 266    \brief Makes signature with bit string encoding. This function is used
 267    for dual algorithm certificate signing, where an alternative signature
 268    is created using a secondary key algorithm (e.g., a post-quantum algorithm
 269    alongside a traditional algorithm).
 270
 271    \note This API is only available when WOLFSSL_DUAL_ALG_CERTS is defined,
 272    which enables support for dual algorithm certificates used in Post-Quantum
 273    cryptography to provide hybrid signing with both traditional and PQ
 274    algorithms.
 275
 276    \return Size of signature on success
 277    \return Negative on error
 278
 279    \param sig Output buffer for signature
 280    \param sigSz Size of signature buffer
 281    \param sType Signature type
 282    \param buf Data to sign (typically the TBS - To Be Signed -
 283    certificate data)
 284    \param bufSz Size of data
 285    \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.)
 286    \param key Pointer to key structure
 287    \param rng Random number generator
 288
 289    _Example_
 290    \code
 291    byte sig[512], data[256];
 292    RsaKey key;
 293    WC_RNG rng;
 294    int sigSz = wc_MakeSigWithBitStr(sig, sizeof(sig), CTC_SHA256wRSA,
 295                                     data, sizeof(data), RSA_TYPE,
 296                                     &key, &rng);
 297    \endcode
 298
 299    \sa wc_SignCert_ex
 300    \sa wc_GeneratePreTBS
 301*/
 302int wc_MakeSigWithBitStr(byte *sig, int sigSz, int sType, byte* buf,
 303                         word32 bufSz, int keyType, void* key,
 304                         WC_RNG* rng);
 305
 306/*!
 307    \ingroup ASN
 308    \brief Gets certificate validity dates.
 309
 310    \return 0 on success
 311    \return BAD_FUNC_ARG if parameters invalid
 312
 313    \param cert Certificate structure
 314    \param before Output for notBefore date
 315    \param after Output for notAfter date
 316
 317    _Example_
 318    \code
 319    Cert myCert;
 320    struct tm beforeDate, afterDate;
 321    int ret = wc_GetCertDates(&myCert, &beforeDate, &afterDate);
 322    \endcode
 323
 324    \sa wc_InitCert
 325*/
 326int wc_GetCertDates(Cert* cert, struct tm* before, struct tm* after);
 327
 328/*!
 329    \ingroup ASN
 330    \brief Extracts date information from certificate date field. This
 331    function parses an ASN.1 encoded date (including tag and length) and
 332    returns a pointer to the raw date value bytes, the ASN.1 time type,
 333    and the length of the date value.
 334
 335    \return 0 on success
 336    \return BAD_FUNC_ARG if parameters invalid
 337    \return ASN_PARSE_E if date parsing fails
 338
 339    \param certDate Certificate date buffer containing ASN.1 encoded date
 340    (tag + length + value)
 341    \param certDateSz Size of certificate date buffer
 342    \param date Output pointer set to the raw date value bytes (without
 343    tag/length)
 344    \param format Output byte indicating ASN.1 time type: ASN_UTC_TIME
 345    (0x17) or ASN_GENERALIZED_TIME (0x18)
 346    \param length Output length of the raw date value in bytes
 347
 348    _Example_
 349    \code
 350    const byte* certDate;
 351    const byte* date;
 352    byte format;
 353    int length;
 354    int ret = wc_GetDateInfo(certDate, certDateSz, &date,
 355                             &format, &length);
 356    if (ret == 0) {
 357        // date points to raw time bytes, format indicates UTC or
 358        // Generalized time, length is the number of date value bytes
 359    }
 360    \endcode
 361
 362    \sa wc_GetCertDates
 363    \sa wc_GetDateAsCalendarTime
 364*/
 365int wc_GetDateInfo(const byte* certDate, int certDateSz,
 366                   const byte** date, byte* format, int* length);
 367
 368/*!
 369    \ingroup ASN
 370    \brief Converts certificate date to calendar time structure.
 371
 372    \return 0 on success
 373    \return BAD_FUNC_ARG if parameters invalid
 374    \return ASN_TIME_E if time conversion fails
 375
 376    \param date Date buffer
 377    \param length Length of date buffer
 378    \param format Date format (ASN_UTC_TIME or ASN_GENERALIZED_TIME)
 379    \param timearg Pointer to tm structure to fill
 380
 381    _Example_
 382    \code
 383    const byte* date;
 384    int length;
 385    byte format;
 386    struct tm timeInfo;
 387    int ret = wc_GetDateAsCalendarTime(date, length, format,
 388                                       &timeInfo);
 389    \endcode
 390
 391    \sa wc_GetDateInfo
 392    \sa wc_GetCertDates
 393*/
 394int wc_GetDateAsCalendarTime(const byte* date, int length,
 395                              byte format, struct tm* timearg);
 396
 397/*!
 398    \ingroup ASN
 399
 400    \brief This function makes a certificate signing request using the input
 401    certificate and writes the output to derBuffer. It takes in either an
 402    rsaKey or an eccKey to generate the certificate request. wc_SignCert()
 403    will need to be called after this function to sign the certificate request.
 404    Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an
 405    example usage of this function.
 406
 407    \return Success On successfully making an X.509 certificate request from
 408    the specified input cert, returns the size of the certificate
 409    request generated.
 410    \return MEMORY_E Returned if there is an error allocating memory
 411    with XMALLOC
 412    \return BUFFER_E Returned if the provided derBuffer is too small to store
 413    the generated certificate
 414    \return Other Additional error messages may be returned if the certificate
 415    request generation is not successful.
 416
 417    \param cert pointer to an initialized cert structure
 418    \param derBuffer pointer to the buffer in which to hold the generated
 419    certificate request
 420    \param derSz size of the buffer in which to store the certificate request
 421    \param rsaKey pointer to an RsaKey structure containing the rsa key used
 422    to generate the certificate request
 423    \param eccKey pointer to an EccKey structure containing the ecc key used
 424    to generate the certificate request
 425
 426    _Example_
 427    \code
 428    Cert myCert;
 429    // initialize myCert
 430    EccKey key;
 431    //initialize key;
 432    byte* derCert = (byte*)malloc(FOURK_BUF);
 433
 434    word32 certSz;
 435    certSz = wc_MakeCertReq(&myCert, derCert, FOURK_BUF, NULL, &key);
 436    \endcode
 437
 438    \sa wc_InitCert
 439    \sa wc_MakeCert
 440*/
 441int  wc_MakeCertReq(Cert* cert, byte* derBuffer, word32 derSz,
 442                                    RsaKey* rsaKey, ecc_key* eccKey);
 443
 444/*!
 445    \ingroup ASN
 446
 447    \brief This function signs buffer and adds the signature to the end of
 448    buffer. It takes in a signature type. Must be called after wc_MakeCert()
 449    or wc_MakeCertReq() if creating a CA signed cert.
 450
 451    \return Success On successfully signing the certificate, returns the new
 452    size of the cert (including signature).
 453    \return MEMORY_E Returned if there is an error allocating
 454    memory with XMALLOC
 455    \return BUFFER_E Returned if the provided buffer is too small to store
 456    the generated certificate
 457    \return Other Additional error messages may be returned if the cert
 458    generation is not successful.
 459
 460    \param requestSz the size of the certificate body we’re requesting
 461    to have signed
 462    \param sType Type of signature to create. Valid options are: CTC_MD5wRSA,
 463    CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, and CTC_SHA256wRSA
 464    \param buffer pointer to the buffer containing the certificate to be
 465    signed. On success: will hold the newly signed certificate
 466    \param buffSz the (total) size of the buffer in which to store the newly
 467    signed certificate
 468    \param rsaKey pointer to an RsaKey structure containing the rsa key
 469    to used to sign the certificate
 470    \param eccKey pointer to an EccKey structure containing the ecc key
 471    to used to sign the certificate
 472    \param rng pointer to the random number generator used to sign
 473    the certificate
 474
 475    _Example_
 476    \code
 477    Cert myCert;
 478    byte* derCert = (byte*)malloc(FOURK_BUF);
 479    // initialize myCert, derCert
 480    RsaKey key;
 481    // initialize key;
 482    WC_RNG rng;
 483    // initialize rng
 484
 485    word32 certSz;
 486    certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF,
 487    &key, NULL,
 488    &rng);
 489    \endcode
 490
 491    \sa wc_InitCert
 492    \sa wc_MakeCert
 493*/
 494int  wc_SignCert(int requestSz, int sigType, byte* derBuffer,
 495                 word32 derSz, RsaKey* rsaKey, ecc_key* eccKey, WC_RNG* rng);
 496
 497/*!
 498    \ingroup ASN
 499
 500    \brief This function is a combination of the previous two functions,
 501    wc_MakeCert and wc_SignCert for self signing (the previous functions may
 502    be used for CA requests). It makes a certificate, and then signs it,
 503    generating a self-signed certificate.
 504
 505    \return Success On successfully signing the certificate, returns the
 506    new size of the cert.
 507    \return MEMORY_E Returned if there is an error allocating memory
 508    with XMALLOC
 509    \return BUFFER_E Returned if the provided buffer is too small to store
 510    the generated certificate
 511    \return Other Additional error messages may be returned if the cert
 512    generation is not successful.
 513
 514    \param cert pointer to the cert to make and sign
 515    \param buffer pointer to the buffer in which to hold the signed certificate
 516    \param buffSz size of the buffer in which to store the signed certificate
 517    \param key pointer to an RsaKey structure containing the rsa key to
 518    used to sign the certificate
 519    \param rng pointer to the random number generator used to generate
 520    and sign the certificate
 521
 522    _Example_
 523    \code
 524    Cert myCert;
 525    byte* derCert = (byte*)malloc(FOURK_BUF);
 526    // initialize myCert, derCert
 527    RsaKey key;
 528    // initialize key;
 529    WC_RNG rng;
 530    // initialize rng
 531
 532    word32 certSz;
 533    certSz = wc_MakeSelfCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
 534    \endcode
 535
 536    \sa wc_InitCert
 537    \sa wc_MakeCert
 538    \sa wc_SignCert
 539*/
 540int  wc_MakeSelfCert(Cert* cert, byte* derBuffer, word32 derSz, RsaKey* key,
 541                             WC_RNG* rng);
 542
 543/*!
 544    \ingroup ASN
 545
 546    \brief This function sets the issuer for a certificate to the issuer
 547    in the provided pem issuerFile. It also changes the certificate’s
 548    self-signed attribute to false.  The issuer specified in issuerFile is
 549    verified prior to setting the cert issuer.  This method is used to set
 550    fields prior to signing.
 551
 552    \return 0 Returned on successfully setting the issuer for the certificate
 553    \return MEMORY_E Returned if there is an error allocating memory
 554    with XMALLOC
 555    \return ASN_PARSE_E Returned if there is an error parsing the
 556    cert header file
 557    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
 558    encryption type from the cert
 559    \return ASN_EXPECT_0_E Returned if there is a formatting error in
 560    the encryption specification of the cert file
 561    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
 562    start date
 563    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
 564    expiration date
 565    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
 566    from the certificate
 567    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
 568    from the certificate
 569    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
 570    key object id
 571    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
 572    defined and the certificate is a V1 or V2 certificate
 573    \return BAD_FUNC_ARG Returned if there is an error processing the
 574    certificate extension
 575    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
 576    encountered in processing the certificate
 577    \return ASN_SIG_OID_E Returned if the signature encryption type is not
 578    the same as the encryption type of the certificate in the provided file
 579    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
 580    signature fails
 581    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
 582    permitted by the CA name constraints
 583    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
 584    the certificate’s authenticity
 585
 586    \param cert pointer to the cert for which to set the issuer
 587    \param issuerFile path of the file containing the pem formatted certificate
 588
 589    _Example_
 590    \code
 591    Cert myCert;
 592    // initialize myCert
 593    if(wc_SetIssuer(&myCert, ”./path/to/ca-cert.pem”) != 0) {
 594    	// error setting issuer
 595    }
 596    \endcode
 597
 598    \sa wc_InitCert
 599    \sa wc_SetSubject
 600    \sa wc_SetIssuerBuffer
 601*/
 602int  wc_SetIssuer(Cert* cert, const char* issuerFile);
 603
 604/*!
 605    \ingroup ASN
 606
 607    \brief This function sets the subject for a certificate to the subject
 608    in the provided pem subjectFile.  This method is used to set fields prior
 609    to signing.
 610
 611    \return 0 Returned on successfully setting the issuer for the certificate
 612    \return MEMORY_E Returned if there is an error allocating memory with XMALLOC
 613    \return ASN_PARSE_E Returned if there is an error parsing the cert
 614    header file
 615    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
 616    encryption type from the cert
 617    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
 618    encryption specification of the cert file
 619    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
 620    start date
 621    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
 622    expiration date
 623    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
 624    from the certificate
 625    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
 626    from the certificate
 627    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
 628    key object id
 629    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
 630    defined and the certificate is a V1 or V2 certificate
 631    \return BAD_FUNC_ARG Returned if there is an error processing the
 632    certificate extension
 633    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
 634    encountered in processing the certificate
 635    \return ASN_SIG_OID_E Returned if the signature encryption type is not
 636    the same as the encryption type of the certificate in the provided file
 637    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
 638    signature fails
 639    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
 640    permitted by the CA name constraints
 641    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
 642    certificate’s authenticity
 643
 644    \param cert pointer to the cert for which to set the issuer
 645    \param subjectFile path of the file containing the pem formatted certificate
 646
 647    _Example_
 648    \code
 649    Cert myCert;
 650    // initialize myCert
 651    if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
 652    	// error setting subject
 653    }
 654    \endcode
 655
 656    \sa wc_InitCert
 657    \sa wc_SetIssuer
 658*/
 659int  wc_SetSubject(Cert* cert, const char* subjectFile);
 660
 661
 662/*!
 663    \ingroup ASN
 664
 665    \brief This function sets the raw subject for a certificate from the
 666    subject in the provided der buffer. This method is used to set the raw
 667    subject field prior to signing.
 668
 669    \return 0 Returned on successfully setting the subject for the certificate
 670    \return MEMORY_E Returned if there is an error allocating memory
 671    with XMALLOC
 672    \return ASN_PARSE_E Returned if there is an error parsing the cert
 673    header file
 674    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
 675    encryption type from the cert
 676    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
 677    encryption specification of the cert file
 678    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
 679    start date
 680    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
 681    expiration date
 682    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
 683    from the certificate
 684    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
 685    from the certificate
 686    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
 687    key object id
 688    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
 689    defined and the certificate is a V1 or V2 certificate
 690    \return BAD_FUNC_ARG Returned if there is an error processing the
 691    certificate extension
 692    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
 693    encountered in processing the certificate
 694    \return ASN_SIG_OID_E Returned if the signature encryption type is not
 695    the same as the encryption type of the certificate in the provided file
 696    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
 697    signature fails
 698    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
 699    permitted by the CA name constraints
 700    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
 701    certificate’s authenticity
 702
 703    \param cert pointer to the cert for which to set the raw subject
 704    \param der pointer to the buffer containing the der formatted certificate
 705    from which to grab the subject
 706    \param derSz size of the buffer containing the der formatted certificate
 707    from which to grab the subject
 708
 709    _Example_
 710    \code
 711    Cert myCert;
 712    // initialize myCert
 713    byte* der;
 714    der = (byte*)malloc(FOURK_BUF);
 715    // initialize der
 716    if(wc_SetSubjectRaw(&myCert, der, FOURK_BUF) != 0) {
 717        // error setting subject
 718    }
 719    \endcode
 720
 721    \sa wc_InitCert
 722    \sa wc_SetSubject
 723*/
 724int  wc_SetSubjectRaw(Cert* cert, const byte* der, int derSz);
 725
 726/*!
 727    \ingroup ASN
 728
 729    \brief This function gets the raw subject from the certificate structure.
 730
 731    \return 0 Returned on successfully getting the subject from the certificate
 732    \return BAD_FUNC_ARG Returned if there is an error processing the
 733    certificate extension
 734
 735    \param subjectRaw pointer-pointer to the raw subject upon successful return
 736    \param cert pointer to the cert from which to get the raw subject
 737
 738    _Example_
 739    \code
 740    Cert myCert;
 741    byte *subjRaw;
 742    // initialize myCert
 743
 744    if(wc_GetSubjectRaw(&subjRaw, &myCert) != 0) {
 745        // error setting subject
 746    }
 747    \endcode
 748
 749    \sa wc_InitCert
 750    \sa wc_SetSubjectRaw
 751*/
 752int  wc_GetSubjectRaw(byte **subjectRaw, Cert *cert);
 753
 754/*!
 755    \ingroup ASN
 756
 757    \brief This function sets the alternate names for a certificate to the
 758    alternate names in the provided pem file. This is useful in the case that
 759    one wishes to secure multiple domains with the same certificate. This
 760    method is used to set fields prior to signing.
 761
 762    \return 0 Returned on successfully setting the alt names for the certificate
 763    \return MEMORY_E Returned if there is an error allocating memory
 764    with XMALLOC
 765    \return ASN_PARSE_E Returned if there is an error parsing the cert
 766    header file
 767    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
 768    encryption type from the cert
 769    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
 770    encryption specification of the cert file
 771    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
 772    start date
 773    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
 774    expiration date
 775    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
 776    from the certificate
 777    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
 778    from the certificate
 779    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
 780    key object id
 781    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
 782    defined and the certificate is a V1 or V2 certificate
 783    \return BAD_FUNC_ARG Returned if there is an error processing the
 784    certificate extension
 785    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
 786    encountered in processing the certificate
 787    \return ASN_SIG_OID_E Returned if the signature encryption type is not
 788    the same as the encryption type of the certificate in the provided file
 789    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
 790    signature fails
 791    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
 792    permitted by the CA name constraints
 793    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
 794    certificate’s authenticity
 795
 796    \param cert pointer to the cert for which to set the alt names
 797    \param file path of the file containing the pem formatted certificate
 798
 799    _Example_
 800    \code
 801    Cert myCert;
 802    // initialize myCert
 803    if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
 804    	// error setting alt names
 805    }
 806    \endcode
 807
 808    \sa wc_InitCert
 809    \sa wc_SetIssuer
 810*/
 811int  wc_SetAltNames(Cert* cert, const char* file);
 812
 813/*!
 814    \ingroup ASN
 815
 816    \brief This function sets the issuer for a certificate from the issuer in
 817    the provided der buffer. It also changes the certificate’s self-signed
 818    attribute to false.  This method is used to set fields prior to signing.
 819
 820    \return 0 Returned on successfully setting the issuer for the certificate
 821    \return MEMORY_E Returned if there is an error allocating memory
 822    with XMALLOC
 823    \return ASN_PARSE_E Returned if there is an error parsing the cert
 824    header file
 825    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
 826    encryption type from the cert
 827    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
 828    encryption specification of the cert file
 829    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
 830    start date
 831    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
 832    expiration date
 833    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
 834    from the certificate
 835    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC
 836    key from the certificate
 837    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
 838    key object id
 839    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
 840    defined and the certificate is a V1 or V2 certificate
 841    \return BAD_FUNC_ARG Returned if there is an error processing the
 842    certificate extension
 843    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
 844    encountered in processing the certificate
 845    \return ASN_SIG_OID_E Returned if the signature encryption type is not
 846    the same as the encryption type of the certificate in the provided file
 847    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
 848    signature fails
 849    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
 850    permitted by the CA name constraints
 851    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
 852    the certificate’s authenticity
 853
 854    \param cert pointer to the cert for which to set the issuer
 855    \param der pointer to the buffer containing the der formatted certificate
 856    from which to grab the issuer
 857    \param derSz size of the buffer containing the der formatted certificate
 858    from which to grab the issuer
 859
 860    _Example_
 861    \code
 862    Cert myCert;
 863    // initialize myCert
 864    byte* der;
 865    der = (byte*)malloc(FOURK_BUF);
 866    // initialize der
 867    if(wc_SetIssuerBuffer(&myCert, der, FOURK_BUF) != 0) {
 868	    // error setting issuer
 869    }
 870    \endcode
 871
 872    \sa wc_InitCert
 873    \sa wc_SetIssuer
 874*/
 875int  wc_SetIssuerBuffer(Cert* cert, const byte* der, int derSz);
 876
 877/*!
 878    \ingroup ASN
 879
 880    \brief This function sets the raw issuer for a certificate from the
 881    issuer in the provided der buffer. This method is used to set the raw
 882    issuer field prior to signing.
 883
 884    \return 0 Returned on successfully setting the issuer for the certificate
 885    \return MEMORY_E Returned if there is an error allocating memory
 886    with XMALLOC
 887    \return ASN_PARSE_E Returned if there is an error parsing the cert
 888    header file
 889    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
 890    encryption type from the cert
 891    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
 892    encryption specification of the cert file
 893    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
 894    start date
 895    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
 896    expiration date
 897    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
 898    from the certificate
 899    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
 900    from the certificate
 901    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
 902    key object id
 903    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
 904    defined and the certificate is a V1 or V2 certificate
 905    \return BAD_FUNC_ARG Returned if there is an error processing the
 906    certificate extension
 907    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
 908    encountered in processing the certificate
 909    \return ASN_SIG_OID_E Returned if the signature encryption type is not
 910    the same as the encryption type of the certificate in the provided file
 911    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
 912    signature fails
 913    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
 914    permitted by the CA name constraints
 915    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
 916    certificate’s authenticity
 917
 918    \param cert pointer to the cert for which to set the raw issuer
 919    \param der pointer to the buffer containing the der formatted certificate
 920    from which to grab the subject
 921    \param derSz size of the buffer containing the der formatted certificate
 922    from which to grab the subject
 923
 924    _Example_
 925    \code
 926    Cert myCert;
 927    // initialize myCert
 928    byte* der;
 929    der = (byte*)malloc(FOURK_BUF);
 930    // initialize der
 931    if(wc_SetIssuerRaw(&myCert, der, FOURK_BUF) != 0) {
 932        // error setting subject
 933    }
 934    \endcode
 935
 936    \sa wc_InitCert
 937    \sa wc_SetIssuer
 938*/
 939int  wc_SetIssuerRaw(Cert* cert, const byte* der, int derSz);
 940
 941/*!
 942    \ingroup ASN
 943
 944    \brief This function sets the subject for a certificate from the subject in
 945    the provided der buffer. This method is used to set fields prior to signing.
 946
 947    \return 0 Returned on successfully setting the subject for the certificate
 948    \return MEMORY_E Returned if there is an error allocating memory
 949    with XMALLOC
 950    \return ASN_PARSE_E Returned if there is an error parsing the cert
 951    header file
 952    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
 953    encryption type from the cert
 954    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
 955    encryption specification of the cert file
 956    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
 957    start date
 958    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
 959    expiration date
 960    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
 961    from the certificate
 962    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
 963    from the certificate
 964    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
 965    key object id
 966    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
 967    defined and the certificate is a V1 or V2 certificate
 968    \return BAD_FUNC_ARG Returned if there is an error processing the
 969    certificate extension
 970    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
 971    encountered in processing the certificate
 972    \return ASN_SIG_OID_E Returned if the signature encryption type is not
 973    the same as the encryption type of the certificate in the provided file
 974    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
 975    signature fails
 976    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
 977    permitted by the CA name constraints
 978    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
 979    certificate’s authenticity
 980
 981    \param cert pointer to the cert for which to set the subject
 982    \param der pointer to the buffer containing the der formatted certificate
 983    from which to grab the subject
 984    \param derSz size of the buffer containing the der formatted certificate
 985    from which to grab the subject
 986
 987    _Example_
 988    \code
 989    Cert myCert;
 990    // initialize myCert
 991    byte* der;
 992    der = (byte*)malloc(FOURK_BUF);
 993    // initialize der
 994    if(wc_SetSubjectBuffer(&myCert, der, FOURK_BUF) != 0) {
 995    	// error setting subject
 996    }
 997    \endcode
 998
 999    \sa wc_InitCert
1000    \sa wc_SetSubject
1001*/
1002int  wc_SetSubjectBuffer(Cert* cert, const byte* der, int derSz);
1003
1004/*!
1005    \ingroup ASN
1006
1007    \brief This function sets the alternate names for a certificate from the
1008    alternate names in the provided der buffer. This is useful in the case that
1009    one wishes to secure multiple domains with the same certificate. This
1010    method is used to set fields prior to signing.
1011
1012    \return 0 Returned on successfully setting the alternate names for the
1013    certificate
1014    \return MEMORY_E Returned if there is an error allocating memory with
1015    XMALLOC
1016    \return ASN_PARSE_E Returned if there is an error parsing the cert
1017    header file
1018    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
1019    encryption type from the cert
1020    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
1021    encryption specification of the cert file
1022    \return ASN_BEFORE_DATE_E Returned if the date is before the
1023    certificate start date
1024    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
1025    expiration date
1026    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
1027    from the certificate
1028    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
1029    from the certificate
1030    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
1031    key object id
1032    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
1033    defined and the certificate is a V1 or V2 certificate
1034    \return BAD_FUNC_ARG Returned if there is an error processing the
1035    certificate extension
1036    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
1037    encountered in processing the certificate
1038    \return ASN_SIG_OID_E Returned if the signature encryption type is not the
1039    same as the encryption type of the certificate in the provided file
1040    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
1041    signature fails
1042    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
1043    permitted by the CA name constraints
1044    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
1045    certificate’s authenticity
1046
1047    \param cert pointer to the cert for which to set the alternate names
1048    \param der pointer to the buffer containing the der formatted certificate
1049    from which to grab the alternate names
1050    \param derSz size of the buffer containing the der formatted certificate
1051    from which to grab the alternate names
1052
1053    _Example_
1054    \code
1055    Cert myCert;
1056    // initialize myCert
1057    byte* der;
1058    der = (byte*)malloc(FOURK_BUF);
1059    // initialize der
1060    if(wc_SetAltNamesBuffer(&myCert, der, FOURK_BUF) != 0) {
1061    	// error setting subject
1062    }
1063    \endcode
1064
1065    \sa wc_InitCert
1066    \sa wc_SetAltNames
1067*/
1068int  wc_SetAltNamesBuffer(Cert* cert, const byte* der, int derSz);
1069
1070/*!
1071    \ingroup ASN
1072
1073    \brief This function sets the dates for a certificate from the date range
1074    in the provided der buffer. This method is used to set fields prior
1075    to signing.
1076
1077    \return 0 Returned on successfully setting the dates for the certificate
1078    \return MEMORY_E Returned if there is an error allocating memory
1079    with XMALLOC
1080    \return ASN_PARSE_E Returned if there is an error parsing the cert
1081    header file
1082    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
1083    encryption type from the cert
1084    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
1085    encryption specification of the cert file
1086    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
1087    start date
1088    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
1089    expiration date
1090    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
1091    from the certificate
1092    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
1093    from the certificate
1094    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
1095    key object id
1096    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
1097    defined and the certificate is a V1 or V2 certificate
1098    \return BAD_FUNC_ARG Returned if there is an error processing the
1099    certificate extension
1100    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
1101    encountered in processing the certificate
1102    \return ASN_SIG_OID_E Returned if the signature encryption type is not
1103    the same as the encryption type of the certificate in the provided file
1104    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
1105    signature fails
1106    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
1107    permitted by the CA name constraints
1108    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
1109    certificate’s authenticity
1110
1111    \param cert pointer to the cert for which to set the dates
1112    \param der pointer to the buffer containing the der formatted certificate
1113    from which to grab the date range
1114    \param derSz size of the buffer containing the der formatted certificate
1115    from which to grab the date range
1116
1117    _Example_
1118    \code
1119    Cert myCert;
1120    // initialize myCert
1121    byte* der;
1122    der = (byte*)malloc(FOURK_BUF);
1123    // initialize der
1124    if(wc_SetDatesBuffer(&myCert, der, FOURK_BUF) != 0) {
1125    	// error setting subject
1126    }
1127    \endcode
1128
1129    \sa wc_InitCert
1130*/
1131int  wc_SetDatesBuffer(Cert* cert, const byte* der, int derSz);
1132
1133/*!
1134    \ingroup ASN
1135
1136    \brief Set AKID from either an RSA or ECC public key. note: Only set one of
1137    rsakey or eckey, not both.
1138
1139    \return 0 Success
1140    \return BAD_FUNC_ARG Either cert is null or both rsakey and eckey are null.
1141    \return MEMORY_E Error allocating memory.
1142    \return PUBLIC_KEY_E Error writing to the key.
1143
1144    \param cert Pointer to the certificate to set the SKID.
1145    \param rsakey Pointer to the RsaKey struct to read from.
1146    \param eckey Pointer to the ecc_key to read from.
1147
1148    _Example_
1149    \code
1150    Cert myCert;
1151    RsaKey keypub;
1152
1153    wc_InitRsaKey(&keypub, 0);
1154
1155    if (wc_SetAuthKeyIdFromPublicKey(&myCert, &keypub, NULL) != 0)
1156    {
1157        // Handle error
1158    }
1159    \endcode
1160
1161    \sa wc_SetSubjectKeyId
1162    \sa wc_SetAuthKeyId
1163    \sa wc_SetAuthKeyIdFromCert
1164*/
1165int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
1166                                             ecc_key *eckey);
1167
1168/*!
1169    \ingroup ASN
1170    \brief Sets authority key ID from public key with generic key type.
1171
1172    \return 0 on success
1173    \return BAD_FUNC_ARG if parameters invalid
1174    \return MEMORY_E if memory allocation fails
1175
1176    \param cert Certificate structure
1177    \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.)
1178    \param key Pointer to key structure
1179
1180    _Example_
1181    \code
1182    Cert myCert;
1183    wc_InitCert(&myCert);
1184    RsaKey key;
1185    int ret = wc_SetAuthKeyIdFromPublicKey_ex(&myCert, RSA_TYPE,
1186                                              &key);
1187    \endcode
1188
1189    \sa wc_SetAuthKeyIdFromPublicKey
1190*/
1191int wc_SetAuthKeyIdFromPublicKey_ex(Cert *cert, int keyType,
1192                                    void* key);
1193
1194/*!
1195    \ingroup ASN
1196
1197    \brief Set AKID from from DER encoded certificate.
1198
1199    \return 0 Success
1200    \return BAD_FUNC_ARG Error if any argument is null or derSz is less than 0.
1201    \return MEMORY_E Error if problem allocating memory.
1202    \return ASN_NO_SKID No subject key ID found.
1203
1204    \param cert The Cert struct to write to.
1205    \param der The DER encoded certificate buffer.
1206    \param derSz Size of der in bytes.
1207
1208    _Example_
1209    \code
1210    Cert some_cert;
1211    byte some_der[] = { // Initialize a DER buffer };
1212    wc_InitCert(&some_cert);
1213    if(wc_SetAuthKeyIdFromCert(&some_cert, some_der, sizeof(some_der) != 0)
1214    {
1215        // Handle error
1216    }
1217    \endcode
1218
1219    \sa wc_SetAuthKeyIdFromPublicKey
1220    \sa wc_SetAuthKeyId
1221*/
1222int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz);
1223
1224/*!
1225    \ingroup ASN
1226
1227    \brief Set AKID from certificate file in PEM format.
1228
1229    \return 0 Success
1230    \return BAD_FUNC_ARG Error if cert or file is null.
1231    \return MEMORY_E Error if problem allocating memory.
1232
1233    \param cert Cert struct you want to set the AKID of.
1234    \param file Buffer containing PEM cert file.
1235
1236    _Example_
1237    \code
1238    char* file_name = "/path/to/file";
1239    cert some_cert;
1240    wc_InitCert(&some_cert);
1241
1242    if(wc_SetAuthKeyId(&some_cert, file_name) != 0)
1243    {
1244        // Handle Error
1245    }
1246    \endcode
1247
1248    \sa wc_SetAuthKeyIdFromPublicKey
1249    \sa wc_SetAuthKeyIdFromCert
1250*/
1251int wc_SetAuthKeyId(Cert *cert, const char* file);
1252
1253/*!
1254    \ingroup ASN
1255
1256    \brief Set SKID from RSA or ECC public key.
1257
1258    \return 0 Success
1259    \return BAD_FUNC_ARG Returned if cert or rsakey and eckey are null.
1260    \return MEMORY_E Returned if there is an error allocating memory.
1261    \return PUBLIC_KEY_E Returned if there is an error getting the public key.
1262
1263    \param cert Pointer to a Cert structure to be used.
1264    \param rsakey Pointer to an RsaKey structure
1265    \param eckey Pointer to an ecc_key structure
1266
1267    _Example_
1268    \code
1269    Cert some_cert;
1270    RsaKey some_key;
1271    wc_InitCert(&some_cert);
1272    wc_InitRsaKey(&some_key);
1273
1274    if(wc_SetSubjectKeyIdFromPublicKey(&some_cert,&some_key, NULL) != 0)
1275    {
1276        // Handle Error
1277    }
1278    \endcode
1279
1280    \sa wc_SetSubjectKeyId
1281*/
1282int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
1283                                                ecc_key *eckey);
1284
1285/*!
1286    \ingroup ASN
1287    \brief Sets subject key ID from public key with generic key type.
1288
1289    \return 0 on success
1290    \return BAD_FUNC_ARG if parameters invalid
1291    \return MEMORY_E if memory allocation fails
1292    \return PUBLIC_KEY_E if error getting public key
1293
1294    \param cert Certificate structure
1295    \param keyType Key type (RSA_TYPE, ECC_TYPE, ED25519_TYPE, etc.)
1296    \param key Pointer to key structure
1297
1298    _Example_
1299    \code
1300    Cert myCert;
1301    wc_InitCert(&myCert);
1302    EccKey key;
1303    int ret = wc_SetSubjectKeyIdFromPublicKey_ex(&myCert, ECC_TYPE,
1304                                                 &key);
1305    \endcode
1306
1307    \sa wc_SetSubjectKeyIdFromPublicKey
1308*/
1309int wc_SetSubjectKeyIdFromPublicKey_ex(Cert *cert, int keyType,
1310                                       void* key);
1311
1312/*!
1313    \ingroup ASN
1314
1315    \brief Set SKID from public key file in PEM format.  Both arguments
1316    are required.
1317
1318    \return 0 Success
1319    \return BAD_FUNC_ARG Returns if cert or file is null.
1320    \return MEMORY_E Returns if there is a problem allocating memory for key.
1321    \return PUBLIC_KEY_E Returns if there is an error decoding the public key.
1322
1323    \param cert Cert structure to set the SKID of.
1324    \param file Contains the PEM encoded file.
1325
1326    _Example_
1327    \code
1328    const char* file_name = "path/to/file";
1329    Cert some_cert;
1330    wc_InitCert(&some_cert);
1331
1332    if(wc_SetSubjectKeyId(&some_cert, file_name) != 0)
1333    {
1334        // Handle Error
1335    }
1336    \endcode
1337
1338    \sa wc_SetSubjectKeyIdFromPublicKey
1339*/
1340int wc_SetSubjectKeyId(Cert *cert, const char* file);
1341
1342/*!
1343    \ingroup RSA
1344
1345    \brief This function allows you to set the key usage using a comma
1346    delimited string of tokens. Accepted tokens are: digitalSignature,
1347    nonRepudiation, contentCommitment, keyCertSign, cRLSign, dataEncipherment,
1348    keyAgreement, keyEncipherment, encipherOnly, decipherOnly. Example:
1349    "digitalSignature,nonRepudiation" nonRepudiation and contentCommitment
1350    are for the same usage.
1351
1352    \return 0 Success
1353    \return BAD_FUNC_ARG Returned when either arg is null.
1354    \return MEMORY_E Returned when there is an error allocating memory.
1355    \return KEYUSAGE_E Returned if an unrecognized token is entered.
1356
1357    \param cert Pointer to initialized Cert structure.
1358    \param value Comma delimited string of tokens to set usage.
1359
1360    _Example_
1361    \code
1362    Cert cert;
1363    wc_InitCert(&cert);
1364
1365    if(wc_SetKeyUsage(&cert, "cRLSign,keyCertSign") != 0)
1366    {
1367        // Handle error
1368    }
1369    \endcode
1370
1371    \sa wc_InitCert
1372    \sa wc_MakeRsaKey
1373*/
1374int wc_SetKeyUsage(Cert *cert, const char *value);
1375
1376/*!
1377    \ingroup ASN
1378    \brief Sets extended key usage using comma-delimited string.
1379
1380    \return 0 on success
1381    \return BAD_FUNC_ARG if parameters invalid
1382    \return MEMORY_E if memory allocation fails
1383
1384    \param cert Certificate structure
1385    \param value Comma-delimited string of extended key usage values
1386
1387    _Example_
1388    \code
1389    Cert myCert;
1390    wc_InitCert(&myCert);
1391    int ret = wc_SetExtKeyUsage(&myCert,
1392                                "serverAuth,clientAuth");
1393    \endcode
1394
1395    \sa wc_SetKeyUsage
1396    \sa wc_SetExtKeyUsageOID
1397*/
1398int wc_SetExtKeyUsage(Cert *cert, const char *value);
1399
1400/*!
1401    \ingroup ASN
1402    \brief Sets extended key usage using OID string.
1403
1404    \return 0 on success
1405    \return BAD_FUNC_ARG if parameters invalid
1406    \return MEMORY_E if memory allocation fails
1407
1408    \param cert Certificate structure
1409    \param oid OID string
1410    \param sz Length of OID string
1411    \param idx Index for multiple OIDs
1412    \param heap Heap hint for memory allocation
1413
1414    _Example_
1415    \code
1416    Cert myCert;
1417    wc_InitCert(&myCert);
1418    const char* oid = "1.3.6.1.5.5.7.3.1";
1419    int ret = wc_SetExtKeyUsageOID(&myCert, oid, strlen(oid),
1420                                   0, NULL);
1421    \endcode
1422
1423    \sa wc_SetExtKeyUsage
1424*/
1425int wc_SetExtKeyUsageOID(Cert *cert, const char *oid, word32 sz,
1426                         byte idx, void* heap);
1427
1428/*!
1429    \ingroup ASN
1430
1431    \brief Loads a PEM key from a file and converts to a DER encoded buffer.
1432
1433    \return 0 Success
1434    \return <0 Error
1435    \return SSL_BAD_FILE There is a problem with opening the file.
1436    \return MEMORY_E There is an error allocating memory for the file buffer.
1437    \return BUFFER_E derBuf is not large enough to hold the converted key.
1438
1439    \param fileName Name of the file to load.
1440    \param derBuf Buffer for DER encoded key.
1441    \param derSz Size of DER buffer.
1442
1443    _Example_
1444    \code
1445    char* some_file = "filename";
1446    unsigned char der[];
1447
1448    if(wc_PemPubKeyToDer(some_file, der, sizeof(der)) != 0)
1449    {
1450        //Handle Error
1451    }
1452    \endcode
1453
1454    \sa wc_PubKeyPemToDer
1455*/
1456int wc_PemPubKeyToDer(const char* fileName,
1457                                       unsigned char* derBuf, int derSz);
1458
1459/*!
1460    \ingroup ASN
1461    \brief Loads PEM public key from file to DER buffer.
1462
1463    \return 0 on success
1464    \return negative on error
1465
1466    \param fileName Path to PEM file
1467    \param der Pointer to DerBuffer pointer to allocate
1468
1469    _Example_
1470    \code
1471    DerBuffer* der = NULL;
1472    int ret = wc_PemPubKeyToDer_ex("pubkey.pem", &der);
1473    if (ret == 0) {
1474        // Use der->buffer and der->length
1475        wc_FreeDer(&der);
1476    }
1477    \endcode
1478
1479    \sa wc_PemPubKeyToDer
1480    \sa wc_FreeDer
1481*/
1482int wc_PemPubKeyToDer_ex(const char* fileName, DerBuffer** der);
1483
1484/*!
1485    \ingroup ASN
1486
1487    \brief Convert a PEM encoded public key to DER.  Returns the number of
1488    bytes written to the buffer or a negative value for an error.
1489
1490    \return >0 Success, number of bytes written.
1491    \return BAD_FUNC_ARG Returns if pem, buff, or buffSz are null
1492    \return <0 An error occurred in the function.
1493
1494    \param pem PEM encoded key
1495    \param pemSz Size of pem
1496    \param buff Pointer to buffer for output.
1497    \param buffSz Size of buffer.
1498
1499    _Example_
1500    \code
1501    byte some_pem[] = { Initialize with PEM key }
1502    unsigned char out_buffer[1024]; // Ensure buffer is large enough to fit DER
1503
1504    if(wc_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer,
1505    sizeof(out_buffer)) < 0)
1506    {
1507        // Handle error
1508    }
1509    \endcode
1510
1511    \sa wc_PemPubKeyToDer
1512*/
1513int wc_PubKeyPemToDer(const unsigned char* pem, int pemSz,
1514                                      unsigned char* buff, int buffSz);
1515
1516/*!
1517    \ingroup ASN
1518    \brief Gets PEM header and footer strings for given type.
1519
1520    \return 0 on success
1521    \return BAD_FUNC_ARG if parameters invalid
1522
1523    \param type PEM type (CERT_TYPE, PRIVATEKEY_TYPE, etc.)
1524    \param header Pointer to header string pointer
1525    \param footer Pointer to footer string pointer
1526
1527    _Example_
1528    \code
1529    const char* header;
1530    const char* footer;
1531    int ret = wc_PemGetHeaderFooter(CERT_TYPE, &header, &footer);
1532    \endcode
1533
1534    \sa wc_PemToDer
1535*/
1536int wc_PemGetHeaderFooter(int type, const char** header,
1537                          const char** footer);
1538
1539/*!
1540    \ingroup ASN
1541    \brief Allocates DER buffer with specified length and type.
1542
1543    \return 0 on success
1544    \return BAD_FUNC_ARG if pDer is NULL
1545    \return MEMORY_E if allocation fails
1546
1547    \param pDer Pointer to DerBuffer pointer to allocate
1548    \param length Length of buffer to allocate
1549    \param type Buffer type for tracking
1550    \param heap Heap hint for memory allocation
1551
1552    _Example_
1553    \code
1554    DerBuffer* der = NULL;
1555    int ret = wc_AllocDer(&der, 1024, CERT_TYPE, NULL);
1556    if (ret == 0) {
1557        // Use der->buffer
1558        wc_FreeDer(&der);
1559    }
1560    \endcode
1561
1562    \sa wc_FreeDer
1563*/
1564int wc_AllocDer(DerBuffer** pDer, word32 length, int type,
1565                void* heap);
1566
1567/*!
1568    \ingroup ASN
1569    \brief Frees DER buffer allocated by wc_AllocDer or wc_PemToDer.
1570
1571    \param pDer Pointer to DerBuffer pointer to free
1572
1573    _Example_
1574    \code
1575    DerBuffer* der = NULL;
1576    wc_AllocDer(&der, 1024, CERT_TYPE, NULL);
1577    // Use der
1578    wc_FreeDer(&der);
1579    \endcode
1580
1581    \sa wc_AllocDer
1582    \sa wc_PemToDer
1583*/
1584void wc_FreeDer(DerBuffer** pDer);
1585
1586/*!
1587    \ingroup ASN
1588    \brief Converts PEM to DER format with encryption info support.
1589
1590    \return 0 on success
1591    \return negative on error
1592
1593    \param buff PEM buffer
1594    \param longSz Size of PEM buffer
1595    \param type PEM type (CERT_TYPE, PRIVATEKEY_TYPE, etc.)
1596    \param pDer Pointer to DerBuffer pointer to allocate
1597    \param heap Heap hint for memory allocation
1598    \param info Encryption info for encrypted PEM
1599    \param keyFormat Pointer to store key format
1600
1601    _Example_
1602    \code
1603    const unsigned char* pem;
1604    DerBuffer* der = NULL;
1605    EncryptedInfo info;
1606    int keyFormat;
1607    int ret = wc_PemToDer(pem, pemSz, PRIVATEKEY_TYPE, &der,
1608                          NULL, &info, &keyFormat);
1609    if (ret == 0) {
1610        wc_FreeDer(&der);
1611    }
1612    \endcode
1613
1614    \sa wc_PemCertToDer
1615    \sa wc_FreeDer
1616*/
1617int wc_PemToDer(const unsigned char* buff, long longSz, int type,
1618                DerBuffer** pDer, void* heap, EncryptedInfo* info,
1619                int* keyFormat);
1620
1621/*!
1622    \ingroup ASN
1623
1624    \brief This function converts a pem certificate to a der certificate,
1625    and places the resulting certificate in the derBuf buffer provided.
1626
1627    \return Success On success returns the size of the derBuf generated
1628    \return BUFFER_E Returned if the size of derBuf is too small to hold
1629    the certificate generated
1630    \return MEMORY_E Returned if the call to XMALLOC fails
1631
1632    \param fileName path to the file containing a pem certificate to
1633    convert to a der certificate
1634    \param derBuf pointer to a char buffer in which to store the
1635    converted certificate
1636    \param derSz size of the char buffer in which to store the
1637    converted certificate
1638
1639    _Example_
1640    \code
1641    char * file = “./certs/client-cert.pem”;
1642    int derSz;
1643    byte* der = (byte*)XMALLOC((8*1024), NULL, DYNAMIC_TYPE_CERT);
1644
1645    derSz = wc_PemCertToDer(file, der, (8*1024));
1646    if (derSz <= 0) {
1647        //PemCertToDer error
1648    }
1649    \endcode
1650
1651    \sa none
1652*/
1653
1654int wc_PemCertToDer(const char* fileName, unsigned char* derBuf, int derSz);
1655
1656/*!
1657    \ingroup ASN
1658
1659    \brief This function converts a der formatted input certificate, contained
1660    in the der buffer, into a pem formatted output certificate, contained in
1661    the output buffer. It should be noted that this is not an in place
1662    conversion, and a separate buffer must be utilized to store the pem
1663    formatted output.
1664
1665    \return Success On successfully making a pem certificate from the input
1666    der cert, returns the size of the pem cert generated.
1667    \return BAD_FUNC_ARG Returned if there is an error parsing the der file
1668    and storing it as a pem file
1669    \return MEMORY_E Returned if there is an error allocating memory
1670    with XMALLOC
1671    \return ASN_INPUT_E Returned in the case of a base64 encoding error
1672    \return BUFFER_E May be returned if the output buffer is too small to
1673    store the pem formatted certificate
1674
1675    \param der pointer to the buffer of the certificate to convert
1676    \param derSz size of the the certificate to convert
1677    \param output pointer to the buffer in which to store the pem
1678    formatted certificate
1679    \param outSz size of the buffer in which to store the pem formatted
1680    certificate
1681    \param type the type of certificate to generate. Valid types are:
1682    CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
1683
1684    _Example_
1685    \code
1686    byte* der;
1687    // initialize der with certificate
1688    byte* pemFormatted[FOURK_BUF];
1689
1690    word32 pemSz;
1691    pemSz = wc_DerToPem(der, derSz,pemFormatted,FOURK_BUF, CERT_TYPE);
1692    \endcode
1693
1694    \sa wc_PemCertToDer
1695*/
1696int wc_DerToPem(const byte* der, word32 derSz, byte* output,
1697                                word32 outSz, int type);
1698
1699/*!
1700    \ingroup ASN
1701
1702    \brief This function converts a der formatted input certificate,
1703    contained in the der buffer, into a pem formatted output certificate,
1704    contained in the output buffer. It should be noted that this is not an
1705    in place conversion, and a separate buffer must be utilized to store the
1706    pem formatted output.  Allows setting cipher info.
1707
1708    \return Success On successfully making a pem certificate from the input
1709    der cert, returns the size of the pem cert generated.
1710    \return BAD_FUNC_ARG Returned if there is an error parsing the der file
1711    and storing it as a pem file
1712    \return MEMORY_E Returned if there is an error allocating memory
1713    with XMALLOC
1714    \return ASN_INPUT_E Returned in the case of a base64 encoding error
1715    \return BUFFER_E May be returned if the output buffer is too small to
1716    store the pem formatted certificate
1717
1718    \param der pointer to the buffer of the certificate to convert
1719    \param derSz size of the the certificate to convert
1720    \param output pointer to the buffer in which to store the pem
1721    formatted certificate
1722    \param outSz size of the buffer in which to store the pem formatted
1723    certificate
1724    \param cipher_info Additional cipher information.
1725    \param type the type of certificate to generate. Valid types are:
1726    CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
1727
1728    _Example_
1729    \code
1730    byte* der;
1731    // initialize der with certificate
1732    byte* pemFormatted[FOURK_BUF];
1733
1734    word32 pemSz;
1735    byte* cipher_info[] { Additional cipher info. }
1736    pemSz = wc_DerToPemEx(der, derSz, pemFormatted, FOURK_BUF, cipher_info, CERT_TYPE);
1737    \endcode
1738
1739    \sa wc_PemCertToDer
1740*/
1741int wc_DerToPemEx(const byte* der, word32 derSz, byte* output,
1742                                word32 outSz, byte *cipher_info, int type);
1743
1744/*!
1745    \ingroup CertsKeys
1746
1747    \brief Converts a key in PEM format to DER format.
1748
1749    \return int the function returns the number of bytes written to
1750    the buffer on successful execution.
1751    \return int negative int returned indicating an error.
1752
1753    \param pem a pointer to the PEM encoded certificate.
1754    \param pemSz the size of the PEM buffer (pem)
1755    \param buff a pointer to the copy of the buffer member of the
1756    DerBuffer struct.
1757    \param buffSz size of the buffer space allocated in the DerBuffer struct.
1758    \param pass password passed into the function.
1759
1760    _Example_
1761    \code
1762    byte* loadBuf;
1763    long fileSz = 0;
1764    byte* bufSz;
1765    static int LoadKeyFile(byte** keyBuf, word32* keyBufSz,
1766    const char* keyFile,
1767                    int typeKey, const char* password);
1768    …
1769    bufSz = wc_KeyPemToDer(loadBuf, (int)fileSz, saveBuf,
1770    (int)fileSz, password);
1771
1772    if(saveBufSz > 0){
1773        // Bytes were written to the buffer.
1774    }
1775    \endcode
1776
1777    \sa wc_PemToDer
1778*/
1779int wc_KeyPemToDer(const unsigned char* pem, int pemSz,
1780                                    unsigned char* buff, int buffSz, const char* pass);
1781
1782/*!
1783    \ingroup CertsKeys
1784
1785    \brief This function converts a PEM formatted certificate to DER
1786    format. Calls OpenSSL function PemToDer.
1787
1788    \return buffer returns the bytes written to the buffer.
1789
1790    \param pem pointer PEM formatted certificate.
1791    \param pemSz size of the certificate.
1792    \param buff buffer to be copied to DER format.
1793    \param buffSz size of the buffer.
1794    \param type Certificate file type found in asn_public.h enum CertType.
1795
1796    _Example_
1797    \code
1798    const unsigned char* pem;
1799    int pemSz;
1800    unsigned char buff[BUFSIZE];
1801    int buffSz = sizeof(buff)/sizeof(char);
1802    int type;
1803    ...
1804    if(wc_CertPemToDer(pem, pemSz, buff, buffSz, type) <= 0) {
1805        // There were bytes written to buffer
1806    }
1807    \endcode
1808
1809    \sa wc_PemToDer
1810*/
1811int wc_CertPemToDer(const unsigned char* pem, int pemSz,
1812                    unsigned char* buff, int buffSz, int type);
1813
1814/*!
1815    \ingroup ASN
1816    \brief Loads PEM certificate from file to DER buffer.
1817
1818    \return 0 on success
1819    \return negative on error
1820
1821    \param fileName Path to PEM certificate file
1822    \param der Pointer to DerBuffer pointer to allocate
1823
1824    _Example_
1825    \code
1826    DerBuffer* der = NULL;
1827    int ret = wc_PemCertToDer_ex("cert.pem", &der);
1828    if (ret == 0) {
1829        // Use der->buffer and der->length
1830        wc_FreeDer(&der);
1831    }
1832    \endcode
1833
1834    \sa wc_CertPemToDer
1835    \sa wc_FreeDer
1836*/
1837int wc_PemCertToDer_ex(const char* fileName, DerBuffer** der);
1838
1839/*!
1840    \ingroup ASN
1841    \brief Adds PKCS padding to buffer for RSA encryption.
1842
1843    \return Padded size on success
1844    \return 0 on error
1845
1846    \param buf Buffer to pad
1847    \param sz Current size of data in buffer
1848    \param blockSz Block size for padding
1849
1850    _Example_
1851    \code
1852    byte buffer[256];
1853    word32 dataSz = 100;
1854    word32 paddedSz = wc_PkcsPad(buffer, dataSz, 256);
1855    \endcode
1856
1857    \sa wc_RsaPublicEncrypt
1858*/
1859word32 wc_PkcsPad(byte* buf, word32 sz, word32 blockSz);
1860
1861/*!
1862    \ingroup RSA
1863    \brief Decodes RSA public key and extracts modulus and exponent.
1864
1865    \return 0 on success
1866    \return negative on error
1867
1868    \param input DER encoded RSA public key buffer
1869    \param inOutIdx Pointer to index in buffer
1870    \param inSz Size of input buffer
1871    \param n Pointer to modulus pointer
1872    \param nSz Pointer to modulus size
1873    \param e Pointer to exponent pointer
1874    \param eSz Pointer to exponent size
1875
1876    _Example_
1877    \code
1878    const byte* n;
1879    const byte* e;
1880    word32 nSz, eSz, idx = 0;
1881    int ret = wc_RsaPublicKeyDecode_ex(derBuf, &idx, derSz,
1882                                       &n, &nSz, &e, &eSz);
1883    \endcode
1884
1885    \sa wc_RsaPublicKeyDecode
1886*/
1887int wc_RsaPublicKeyDecode_ex(const byte* input, word32* inOutIdx,
1888                              word32 inSz, const byte** n, word32* nSz,
1889                              const byte** e, word32* eSz);
1890
1891/*!
1892    \ingroup RSA
1893    \brief Calculates DER encoded RSA public key size.
1894
1895    \return Size on success
1896    \return negative on error
1897
1898    \param key RSA key structure
1899    \param with_header Include sequence header if non-zero
1900
1901    _Example_
1902    \code
1903    RsaKey key;
1904    int derSz = wc_RsaPublicKeyDerSize(&key, 1);
1905    \endcode
1906
1907    \sa wc_RsaKeyToDer
1908*/
1909int wc_RsaPublicKeyDerSize(RsaKey* key, int with_header);
1910
1911/*!
1912    \ingroup RSA
1913    \brief Validates DER encoded RSA private key format. This function
1914    validates the ASN.1 syntax and structure of the RSA private key
1915    (sequences, integer tags, and lengths) without loading the key values
1916    into an RsaKey structure. It does not perform mathematical validation
1917    of the RSA key parameters (e.g., checking if p and q are prime, or if
1918    the key components satisfy RSA mathematical relationships).
1919
1920    \return 0 on success (valid ASN.1 structure)
1921    \return ASN_PARSE_E if ASN.1 parsing fails
1922    \return ASN_RSA_KEY_E if RSA key structure is invalid
1923    \return BAD_FUNC_ARG if parameters are invalid
1924
1925    \param input DER encoded RSA private key buffer
1926    \param inOutIdx Pointer to index in buffer (updated on success)
1927    \param keySz Pointer to store modulus size in bytes
1928    \param inSz Size of input buffer
1929
1930    _Example_
1931    \code
1932    word32 idx = 0;
1933    int keySz;
1934    int ret = wc_RsaPrivateKeyValidate(derBuf, &idx, &keySz,
1935                                       derSz);
1936    if (ret == 0) {
1937        // ASN.1 structure is valid, keySz contains modulus size
1938    }
1939    \endcode
1940
1941    \sa wc_RsaPrivateKeyDecode
1942*/
1943int wc_RsaPrivateKeyValidate(const byte* input, word32* inOutIdx,
1944                              int* keySz, word32 inSz);
1945
1946/*!
1947    \ingroup CertsKeys
1948
1949    \brief This function gets the public key in DER format from a populated
1950    DecodedCert struct. Users must call wc_InitDecodedCert() and wc_ParseCert()
1951    before calling this API. wc_InitDecodedCert() accepts a DER/ASN.1 encoded
1952    certificate. To convert a PEM cert to DER, first use wc_CertPemToDer()
1953    before calling wc_InitDecodedCert().
1954
1955    \return 0 on success, negative on error. LENGTH_ONLY_E if derKey is NULL
1956    and returning length only.
1957
1958    \param cert populated DecodedCert struct holding X.509 certificate
1959    \param derKey output buffer to place DER encoded public key
1960    \param derKeySz [IN/OUT] size of derKey buffer on input, size of public key
1961    on return. If derKey is passed in as NULL, derKeySz will be set to required
1962    buffer size for public key and LENGTH_ONLY_E will be returned from function.
1963
1964    \sa wc_GetPubKeyDerFromCert
1965*/
1966int wc_GetPubKeyDerFromCert(struct DecodedCert* cert,
1967                                        byte* derKey, word32* derKeySz);
1968
1969/*!
1970    \ingroup DSA
1971    \brief Decodes DSA parameters from DER format.
1972
1973    \return 0 on success
1974    \return negative on error
1975
1976    \param input DER encoded DSA parameters buffer
1977    \param inOutIdx Pointer to index in buffer
1978    \param key DSA key structure to store parameters
1979    \param inSz Size of input buffer
1980
1981    _Example_
1982    \code
1983    DsaKey key;
1984    word32 idx = 0;
1985    int ret = wc_DsaParamsDecode(derBuf, &idx, &key, derSz);
1986    \endcode
1987
1988    \sa wc_DsaKeyToParamsDer
1989*/
1990int wc_DsaParamsDecode(const byte* input, word32* inOutIdx,
1991                       DsaKey* key, word32 inSz);
1992
1993/*!
1994    \ingroup DSA
1995    \brief Encodes DSA parameters to DER format.
1996
1997    \return Size on success
1998    \return negative on error
1999
2000    \param key DSA key structure with parameters
2001    \param output Buffer for DER encoded parameters
2002    \param inLen Size of output buffer
2003
2004    _Example_
2005    \code
2006    DsaKey key;
2007    byte der[1024];
2008    int derSz = wc_DsaKeyToParamsDer(&key, der, sizeof(der));
2009    \endcode
2010
2011    \sa wc_DsaParamsDecode
2012*/
2013int wc_DsaKeyToParamsDer(DsaKey* key, byte* output, word32 inLen);
2014
2015/*!
2016    \ingroup DSA
2017    \brief Encodes DSA parameters to DER with size output.
2018
2019    \return 0 on success
2020    \return negative on error
2021
2022    \param key DSA key structure with parameters
2023    \param output Buffer for DER encoded parameters
2024    \param inLen Pointer to buffer size (in/out)
2025
2026    _Example_
2027    \code
2028    DsaKey key;
2029    byte der[1024];
2030    word32 derSz = sizeof(der);
2031    int ret = wc_DsaKeyToParamsDer_ex(&key, der, &derSz);
2032    \endcode
2033
2034    \sa wc_DsaKeyToParamsDer
2035*/
2036int wc_DsaKeyToParamsDer_ex(DsaKey* key, byte* output,
2037                             word32* inLen);
2038
2039/*!
2040    \ingroup DH
2041    \brief Encodes DH parameters to DER format.
2042
2043    \return 0 on success
2044    \return negative on error
2045
2046    \param key DH key structure with parameters
2047    \param out Buffer for DER encoded parameters
2048    \param outSz Pointer to buffer size (in/out)
2049
2050    _Example_
2051    \code
2052    DhKey key;
2053    byte der[1024];
2054    word32 derSz = sizeof(der);
2055    int ret = wc_DhParamsToDer(&key, der, &derSz);
2056    \endcode
2057
2058    \sa wc_DhKeyToDer
2059*/
2060int wc_DhParamsToDer(DhKey* key, byte* out, word32* outSz);
2061
2062/*!
2063    \ingroup DH
2064    \brief Encodes DH public key to DER format.
2065
2066    \return 0 on success
2067    \return negative on error
2068
2069    \param key DH key structure with public key
2070    \param out Buffer for DER encoded public key
2071    \param outSz Pointer to buffer size (in/out)
2072
2073    _Example_
2074    \code
2075    DhKey key;
2076    byte der[1024];
2077    word32 derSz = sizeof(der);
2078    int ret = wc_DhPubKeyToDer(&key, der, &derSz);
2079    \endcode
2080
2081    \sa wc_DhKeyToDer
2082*/
2083int wc_DhPubKeyToDer(DhKey* key, byte* out, word32* outSz);
2084
2085/*!
2086    \ingroup DH
2087    \brief Encodes DH private key to DER format.
2088
2089    \return 0 on success
2090    \return negative on error
2091
2092    \param key DH key structure with private key
2093    \param out Buffer for DER encoded private key
2094    \param outSz Pointer to buffer size (in/out)
2095
2096    _Example_
2097    \code
2098    DhKey key;
2099    byte der[1024];
2100    word32 derSz = sizeof(der);
2101    int ret = wc_DhPrivKeyToDer(&key, der, &derSz);
2102    \endcode
2103
2104    \sa wc_DhKeyToDer
2105*/
2106int wc_DhPrivKeyToDer(DhKey* key, byte* out, word32* outSz);
2107
2108/*!
2109    \ingroup ASN
2110
2111    \brief This function reads in an ECC private key from the input buffer,
2112    input, parses the private key, and uses it to generate an ecc_key object,
2113    which it stores in key.
2114
2115    \return 0 On successfully decoding the private key and storing the result
2116    in the ecc_key struct
2117    \return ASN_PARSE_E: Returned if there is an error parsing the der file
2118    and storing it as a pem file
2119    \return MEMORY_E Returned if there is an error allocating memory
2120    with XMALLOC
2121    \return BUFFER_E Returned if the certificate to convert is large than
2122    the specified max certificate size
2123    \return ASN_OBJECT_ID_E Returned if the certificate encoding has an
2124    invalid object id
2125    \return ECC_CURVE_OID_E Returned if the ECC curve of the provided key is
2126    not supported
2127    \return ECC_BAD_ARG_E Returned if there is an error in the ECC key format
2128    \return NOT_COMPILED_IN Returned if the private key is compressed, and no
2129    compression key is provided
2130    \return MP_MEM Returned if there is an error in the math library used
2131    while parsing the private key
2132    \return MP_VAL Returned if there is an error in the math library used
2133    while parsing the private key
2134    \return MP_RANGE Returned if there is an error in the math library used
2135    while parsing the private key
2136
2137    \param input pointer to the buffer containing the input private key
2138    \param inOutIdx pointer to a word32 object containing the index in
2139    the buffer at which to start
2140    \param key pointer to an initialized ecc object, on which to store
2141    the decoded private key
2142    \param inSz size of the input buffer containing the private key
2143
2144    _Example_
2145    \code
2146    int ret, idx=0;
2147    ecc_key key; // to store key in
2148
2149    byte* tmp; // tmp buffer to read key from
2150    tmp = (byte*) malloc(FOURK_BUF);
2151
2152    int inSz;
2153    inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile);
2154    // read key into tmp buffer
2155
2156    wc_ecc_init(&key); // initialize key
2157    ret = wc_EccPrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
2158    if(ret < 0) {
2159        // error decoding ecc key
2160    }
2161    \endcode
2162
2163    \sa wc_RSA_PrivateKeyDecode
2164*/
2165int wc_EccPrivateKeyDecode(const byte* input, word32* inOutIdx,
2166                                           ecc_key* key, word32 inSz);
2167
2168/*!
2169    \ingroup ECC
2170    \brief Encodes ECC private key to DER format.
2171
2172    \return Size on success
2173    \return negative on error
2174
2175    \param key ECC key structure with private key
2176    \param output Buffer for DER encoded private key
2177    \param inLen Size of output buffer
2178
2179    _Example_
2180    \code
2181    ecc_key key;
2182    byte der[1024];
2183    int derSz = wc_EccPrivateKeyToDer(&key, der, sizeof(der));
2184    \endcode
2185
2186    \sa wc_EccPrivateKeyDecode
2187*/
2188int wc_EccPrivateKeyToDer(ecc_key* key, byte* output,
2189                          word32 inLen);
2190
2191/*!
2192    \ingroup ECC
2193    \brief Calculates DER encoded ECC key size.
2194
2195    \return Size on success
2196    \return negative on error
2197
2198    \param key ECC key structure
2199    \param pub Non-zero to include public key
2200
2201    _Example_
2202    \code
2203    ecc_key key;
2204    int derSz = wc_EccKeyDerSize(&key, 1);
2205    \endcode
2206
2207    \sa wc_EccPrivateKeyToDer
2208*/
2209int wc_EccKeyDerSize(ecc_key* key, int pub);
2210
2211/*!
2212    \ingroup ECC
2213    \brief Encodes ECC private key to PKCS#8 format.
2214
2215    \return Size on success
2216    \return negative on error
2217
2218    \param key ECC key structure with private key
2219    \param output Buffer for PKCS#8 encoded key
2220    \param inLen Pointer to buffer size (in/out)
2221
2222    _Example_
2223    \code
2224    ecc_key key;
2225    byte pkcs8[1024];
2226    word32 pkcs8Sz = sizeof(pkcs8);
2227    int ret = wc_EccPrivateKeyToPKCS8(&key, pkcs8, &pkcs8Sz);
2228    \endcode
2229
2230    \sa wc_EccPrivateKeyToDer
2231*/
2232int wc_EccPrivateKeyToPKCS8(ecc_key* key, byte* output,
2233                             word32* inLen);
2234
2235/*!
2236    \ingroup ECC
2237    \brief Encodes ECC key pair to PKCS#8 format.
2238
2239    \return Size on success
2240    \return negative on error
2241
2242    \param key ECC key structure with key pair
2243    \param output Buffer for PKCS#8 encoded key
2244    \param inLen Pointer to buffer size (in/out)
2245
2246    _Example_
2247    \code
2248    ecc_key key;
2249    byte pkcs8[1024];
2250    word32 pkcs8Sz = sizeof(pkcs8);
2251    int ret = wc_EccKeyToPKCS8(&key, pkcs8, &pkcs8Sz);
2252    \endcode
2253
2254    \sa wc_EccPrivateKeyToPKCS8
2255*/
2256int wc_EccKeyToPKCS8(ecc_key* key, byte* output,
2257                     word32* inLen);
2258
2259/*!
2260    \ingroup ECC
2261    \brief Calculates DER encoded ECC public key size.
2262
2263    \return Size on success
2264    \return negative on error
2265
2266    \param key ECC key structure
2267    \param with_AlgCurve Include algorithm and curve if non-zero
2268
2269    _Example_
2270    \code
2271    ecc_key key;
2272    int derSz = wc_EccPublicKeyDerSize(&key, 1);
2273    \endcode
2274
2275    \sa wc_EccPublicKeyToDer
2276*/
2277int wc_EccPublicKeyDerSize(ecc_key* key, int with_AlgCurve);
2278
2279/*!
2280    \ingroup ASN
2281
2282    \brief This function writes a private ECC key to der format.
2283
2284    \return Success On successfully writing the ECC key to der format,
2285    returns the length written to the buffer
2286    \return BAD_FUNC_ARG Returned if key or output is null, or inLen equals zero
2287    \return MEMORY_E Returned if there is an error allocating memory
2288    with XMALLOC
2289    \return BUFFER_E Returned if the converted certificate is too large
2290    to store in the output buffer
2291    \return ASN_UNKNOWN_OID_E Returned if the ECC key used is of an
2292    unknown type
2293    \return MP_MEM Returned if there is an error in the math library used
2294    while parsing the private key
2295    \return MP_VAL Returned if there is an error in the math library used
2296    while parsing the private key
2297    \return MP_RANGE Returned if there is an error in the math library used
2298    while parsing the private key
2299
2300    \param key pointer to the buffer containing the input ecc key
2301    \param output pointer to a buffer in which to store the der formatted key
2302    \param inLen the length of the buffer in which to store the
2303    der formatted key
2304
2305    _Example_
2306    \code
2307    int derSz;
2308    ecc_key key;
2309    // initialize and make key
2310    byte der[FOURK_BUF];
2311    // store der formatted key here
2312
2313    derSz = wc_EccKeyToDer(&key, der, FOURK_BUF);
2314    if(derSz < 0) {
2315        // error converting ecc key to der buffer
2316    }
2317    \endcode
2318
2319    \sa wc_RsaKeyToDer
2320*/
2321int wc_EccKeyToDer(ecc_key* key, byte* output, word32 inLen);
2322
2323/*!
2324    \ingroup ASN
2325
2326    \brief Decodes an ECC public key from an input buffer.  It will parse an
2327    ASN sequence to retrieve the ECC key.
2328
2329    \return 0 Success
2330    \return BAD_FUNC_ARG Returns if any arguments are null.
2331    \return ASN_PARSE_E Returns if there is an error parsing
2332    \return ASN_ECC_KEY_E Returns if there is an error importing the key.
2333    See wc_ecc_import_x963 for possible reasons.
2334
2335    \param input Buffer containing DER encoded key to decode.
2336    \param inOutIdx Index to start reading input buffer from.  On output,
2337    index is set to last position parsed of input buffer.
2338    \param key Pointer to ecc_key struct to store the public key.
2339    \param inSz Size of the input buffer.
2340
2341    _Example_
2342    \code
2343    int ret;
2344    word32 idx = 0;
2345    byte buff[] = { // initialize with key };
2346    ecc_key pubKey;
2347    wc_ecc_init(&pubKey);
2348    if ( wc_EccPublicKeyDecode(buff, &idx, &pubKey, sizeof(buff)) != 0) {
2349            // error decoding key
2350    }
2351    \endcode
2352
2353    \sa wc_ecc_import_x963
2354*/
2355int wc_EccPublicKeyDecode(const byte* input, word32* inOutIdx,
2356                          ecc_key* key, word32 inSz);
2357
2358/*!
2359    \ingroup ASN
2360
2361    \brief This function converts the ECC public key to DER format. It
2362    returns the size of buffer used. The public ECC key in DER format is stored
2363    in output buffer. The with_AlgCurve flag will include a header that
2364    has the Algorithm and Curve information
2365
2366    \return >0 Success, size of buffer used
2367    \return BAD_FUNC_ARG Returned if output or key is null.
2368    \return LENGTH_ONLY_E Error in getting ECC public key size.
2369    \return BUFFER_E Returned when output buffer is too small.
2370
2371    \param key Pointer to ECC key
2372    \param output Pointer to output buffer to write to.
2373    \param inLen Size of buffer.
2374    \param with_AlgCurve a flag for when to include a header that has the
2375    Algorithm and Curve information.
2376
2377    _Example_
2378    \code
2379    ecc_key key;
2380    wc_ecc_init(&key);
2381    WC_RNG rng;
2382    wc_InitRng(&rng);
2383    wc_ecc_make_key(&rng, 32, &key);
2384    int derSz = // Some appropriate size for der;
2385    byte der[derSz];
2386
2387    if(wc_EccPublicKeyToDer(&key, der, derSz, 1) < 0)
2388    {
2389        // Error converting ECC public key to der
2390    }
2391    \endcode
2392
2393    \sa wc_EccKeyToDer
2394    \sa wc_EccPrivateKeyDecode
2395*/
2396int wc_EccPublicKeyToDer(ecc_key* key, byte* output,
2397                                         word32 inLen, int with_AlgCurve);
2398
2399/*!
2400    \ingroup ASN
2401
2402    \brief This function converts the ECC public key to DER format. It
2403    returns the size of buffer used. The public ECC key in DER format is stored
2404    in output buffer. The with_AlgCurve flag will include a header that
2405    has the Algorithm and Curve information. The comp parameter determines if
2406    the public key will be exported as compressed.
2407
2408    \return >0 Success, size of buffer used
2409    \return BAD_FUNC_ARG Returned if output or key is null.
2410    \return LENGTH_ONLY_E Error in getting ECC public key size.
2411    \return BUFFER_E Returned when output buffer is too small.
2412
2413    \param key Pointer to ECC key
2414    \param output Pointer to output buffer to write to.
2415    \param inLen Size of buffer.
2416    \param with_AlgCurve a flag for when to include a header that has the
2417    Algorithm and Curve information.
2418    \param comp If 1 (non-zero) the ECC public key will be written in
2419    compressed form. If 0 it will be written in an uncompressed format.
2420
2421    _Example_
2422    \code
2423    ecc_key key;
2424    wc_ecc_init(&key);
2425    WC_RNG rng;
2426    wc_InitRng(&rng);
2427    wc_ecc_make_key(&rng, 32, &key);
2428    int derSz = // Some appropriate size for der;
2429    byte der[derSz];
2430
2431    // Write out a compressed ECC key
2432    if(wc_EccPublicKeyToDer_ex(&key, der, derSz, 1, 1) < 0)
2433    {
2434        // Error converting ECC public key to der
2435    }
2436    \endcode
2437
2438    \sa wc_EccKeyToDer
2439    \sa wc_EccPublicKeyDecode
2440*/
2441int wc_EccPublicKeyToDer_ex(ecc_key* key, byte* output,
2442                                     word32 inLen, int with_AlgCurve, int comp);
2443
2444
2445/*!
2446    \ingroup ASN
2447
2448    \brief This function decodes a Curve25519 private key (only) from a DER
2449    encoded buffer
2450
2451    \return 0 Success
2452    \return BAD_FUNC_ARG Returns if input, inOutIdx or key is null
2453    \return ASN_PARSE_E Returns if there is an error parsing the DER encoded
2454    data
2455    \return ECC_BAD_ARG_E Returns if the key length is not CURVE25519_KEYSIZE or
2456    the DER key contains other issues despite being properly formatted.
2457    \return BUFFER_E Returns if the input buffer is too small to contain a
2458    valid DER encoded key.
2459
2460    \param input Pointer to buffer containing DER encoded private key
2461    \param inOutIdx Index to start reading input buffer from.  On output,
2462    index is set to last position parsed of input buffer.
2463    \param key Pointer to curve25519_key structure to store decoded key
2464    \param inSz Size of input DER buffer
2465
2466    \sa wc_Curve25519KeyDecode
2467    \sa wc_Curve25519PublicKeyDecode
2468
2469    _Example_
2470    \code
2471    byte der[] = { // DER encoded key };
2472    word32 idx = 0;
2473    curve25519_key key;
2474    wc_curve25519_init(&key);
2475
2476    if (wc_Curve25519PrivateKeyDecode(der, &idx, &key, sizeof(der)) != 0) {
2477        // Error decoding private key
2478    }
2479    \endcode
2480*/
2481int wc_Curve25519PrivateKeyDecode(const byte* input, word32* inOutIdx,
2482                                  curve25519_key* key, word32 inSz);
2483
2484/*!
2485    \ingroup ASN
2486
2487    \brief This function decodes a Curve25519 public key (only) from a DER
2488    encoded buffer.
2489
2490    \return 0 Success
2491    \return BAD_FUNC_ARG Returns if input, inOutIdx or key is null
2492    \return ASN_PARSE_E Returns if there is an error parsing the DER encoded
2493    data
2494    \return ECC_BAD_ARG_E Returns if the key length is not CURVE25519_KEYSIZE or
2495    the DER key contains other issues despite being properly formatted.
2496    \return BUFFER_E Returns if the input buffer is too small to contain a
2497    valid DER encoded key.
2498
2499    \param input Pointer to buffer containing DER encoded public key
2500    \param inOutIdx Index to start reading input buffer from.  On output,
2501    index is set to last position parsed of input buffer.
2502    \param key Pointer to curve25519_key structure to store decoded key
2503    \param inSz Size of input DER buffer
2504
2505    \sa wc_Curve25519KeyDecode
2506    \sa wc_Curve25519PrivateKeyDecode
2507
2508    _Example_
2509    \code
2510    byte der[] = { // DER encoded key };
2511    word32 idx = 0;
2512    curve25519_key key;
2513    wc_curve25519_init(&key);
2514    if (wc_Curve25519PublicKeyDecode(der, &idx, &key, sizeof(der)) != 0) {
2515        // Error decoding public key
2516    }
2517    \endcode
2518*/
2519int wc_Curve25519PublicKeyDecode(const byte* input, word32* inOutIdx,
2520                                 curve25519_key* key, word32 inSz);
2521
2522/*!
2523    \ingroup ASN
2524
2525    \brief This function decodes a Curve25519 key from a DER encoded buffer. It
2526    can decode either a private key, a public key, or both.
2527
2528    \return 0 Success
2529    \return BAD_FUNC_ARG Returns if input, inOutIdx or key is null
2530    \return ASN_PARSE_E Returns if there is an error parsing the DER encoded
2531    data
2532    \return ECC_BAD_ARG_E Returns if the key length is not CURVE25519_KEYSIZE or
2533    the DER key contains other issues despite being properly formatted.
2534    \return BUFFER_E Returns if the input buffer is too small to contain a
2535    valid DER encoded key.
2536
2537    \param input Pointer to buffer containing DER encoded key
2538    \param inOutIdx Index to start reading input buffer from.  On output,
2539    index is set to last position parsed of input buffer.
2540    \param key Pointer to curve25519_key structure to store decoded key
2541    \param inSz Size of input DER buffer
2542
2543    \sa wc_Curve25519PrivateKeyDecode
2544    \sa wc_Curve25519PublicKeyDecode
2545
2546    _Example_
2547    \code
2548    byte der[] = { // DER encoded key };
2549    word32 idx = 0;
2550    curve25519_key key;
2551    wc_curve25519_init(&key);
2552    if (wc_Curve25519KeyDecode(der, &idx, &key, sizeof(der)) != 0) {
2553        // Error decoding key
2554    }
2555    \endcode
2556*/
2557int wc_Curve25519KeyDecode(const byte* input, word32* inOutIdx,
2558                           curve25519_key* key, word32 inSz);
2559
2560/*!
2561    \ingroup ASN
2562
2563    \brief This function encodes a Curve25519 private key to DER format. If the
2564    input key structure contains a public key, it will be ignored.
2565
2566    \return >0 Success, length of DER encoding
2567    \return BAD_FUNC_ARG Returns if key or output is null
2568    \return MEMORY_E Returns if there is an allocation failure
2569    \return BUFFER_E Returns if output buffer is too small
2570
2571    \param key Pointer to curve25519_key structure containing private key to
2572    encode
2573    \param output Buffer to hold DER encoding
2574    \param inLen Size of output buffer
2575
2576    \sa wc_Curve25519KeyToDer
2577    \sa wc_Curve25519PublicKeyToDer
2578
2579    _Example_
2580    \code
2581    curve25519_key key;
2582    wc_curve25519_init(&key);
2583    ...
2584    int derSz = 128; // Some appropriate size for output DER
2585    byte der[derSz];
2586    wc_Curve25519PrivateKeyToDer(&key, der, derSz);
2587    \endcode
2588*/
2589int wc_Curve25519PrivateKeyToDer(curve25519_key* key, byte* output,
2590                                 word32 inLen);
2591
2592/*!
2593    \ingroup ASN
2594
2595    \brief This function encodes a Curve25519 public key to DER format. If the
2596    input key structure contains a private key, it will be ignored.
2597
2598    \return >0 Success, length of DER encoding
2599    \return BAD_FUNC_ARG Returns if key or output is null
2600    \return MEMORY_E Returns if there is an allocation failure
2601    \return BUFFER_E Returns if output buffer is too small
2602
2603    \param key Pointer to curve25519_key structure containing public key to
2604    encode
2605    \param output Buffer to hold DER encoding
2606    \param inLen Size of output buffer
2607    \param withAlg Whether to include algorithm identifier in the DER encoding
2608
2609    \sa wc_Curve25519KeyToDer
2610    \sa wc_Curve25519PrivateKeyToDer
2611
2612    _Example_
2613    \code
2614    curve25519_key key;
2615    wc_curve25519_init(&key);
2616    ...
2617    int derSz = 128; // Some appropriate size for output DER
2618    byte der[derSz];
2619    wc_Curve25519PublicKeyToDer(&key, der, derSz, 1);
2620    \endcode
2621*/
2622int wc_Curve25519PublicKeyToDer(curve25519_key* key, byte* output, word32 inLen,
2623                                int withAlg);
2624
2625/*!
2626    \ingroup ASN
2627
2628    \brief This function encodes a Curve25519 key to DER format. It can encode
2629    either a private key, a public key, or both.
2630
2631    \return >0 Success, length of DER encoding
2632    \return BAD_FUNC_ARG Returns if key or output is null
2633    \return MEMORY_E Returns if there is an allocation failure
2634    \return BUFFER_E Returns if output buffer is too small
2635
2636    \param key Pointer to curve25519_key structure containing key to encode
2637    \param output Buffer to hold DER encoding
2638    \param inLen Size of output buffer
2639    \param withAlg Whether to include algorithm identifier in the DER encoding
2640
2641    \sa wc_Curve25519PrivateKeyToDer
2642    \sa wc_Curve25519PublicKeyToDer
2643
2644    _Example_
2645    \code
2646    curve25519_key key;
2647    wc_curve25519_init(&key);
2648    ...
2649    int derSz = 128; // Some appropriate size for output DER
2650    byte der[derSz];
2651    wc_Curve25519KeyToDer(&key, der, derSz, 1);
2652    \endcode
2653*/
2654int wc_Curve25519KeyToDer(curve25519_key* key, byte* output, word32 inLen,
2655                          int withAlg);
2656
2657/*!
2658    \ingroup Ed25519
2659    \brief Decodes Ed25519 private key from DER format.
2660
2661    \return 0 on success
2662    \return negative on error
2663
2664    \param input DER encoded Ed25519 private key buffer
2665    \param inOutIdx Pointer to index in buffer
2666    \param key Ed25519 key structure to store key
2667    \param inSz Size of input buffer
2668
2669    _Example_
2670    \code
2671    ed25519_key key;
2672    word32 idx = 0;
2673    int ret = wc_Ed25519PrivateKeyDecode(derBuf, &idx, &key,
2674                                         derSz);
2675    \endcode
2676
2677    \sa wc_Ed25519PrivateKeyToDer
2678*/
2679int wc_Ed25519PrivateKeyDecode(const byte* input, word32* inOutIdx,
2680                                ed25519_key* key, word32 inSz);
2681
2682/*!
2683    \ingroup Ed25519
2684    \brief Decodes Ed25519 public key from DER format.
2685
2686    \return 0 on success
2687    \return negative on error
2688
2689    \param input DER encoded Ed25519 public key buffer
2690    \param inOutIdx Pointer to index in buffer
2691    \param key Ed25519 key structure to store key
2692    \param inSz Size of input buffer
2693
2694    _Example_
2695    \code
2696    ed25519_key key;
2697    word32 idx = 0;
2698    int ret = wc_Ed25519PublicKeyDecode(derBuf, &idx, &key,
2699                                        derSz);
2700    \endcode
2701
2702    \sa wc_Ed25519PublicKeyToDer
2703*/
2704int wc_Ed25519PublicKeyDecode(const byte* input, word32* inOutIdx,
2705                               ed25519_key* key, word32 inSz);
2706
2707/*!
2708    \ingroup Ed25519
2709    \brief Encodes Ed25519 key to DER format.
2710
2711    \return Size on success
2712    \return negative on error
2713
2714    \param key Ed25519 key structure
2715    \param output Buffer for DER encoded key
2716    \param inLen Size of output buffer
2717
2718    _Example_
2719    \code
2720    ed25519_key key;
2721    byte der[1024];
2722    int derSz = wc_Ed25519KeyToDer(&key, der, sizeof(der));
2723    \endcode
2724
2725    \sa wc_Ed25519PrivateKeyToDer
2726*/
2727int wc_Ed25519KeyToDer(const ed25519_key* key, byte* output,
2728                       word32 inLen);
2729
2730/*!
2731    \ingroup Ed25519
2732    \brief Encodes Ed25519 private key to DER format.
2733
2734    \return Size on success
2735    \return negative on error
2736
2737    \param key Ed25519 key structure with private key
2738    \param output Buffer for DER encoded private key
2739    \param inLen Size of output buffer
2740
2741    _Example_
2742    \code
2743    ed25519_key key;
2744    byte der[1024];
2745    int derSz = wc_Ed25519PrivateKeyToDer(&key, der,
2746                                          sizeof(der));
2747    \endcode
2748
2749    \sa wc_Ed25519PrivateKeyDecode
2750*/
2751int wc_Ed25519PrivateKeyToDer(const ed25519_key* key, byte* output,
2752                               word32 inLen);
2753
2754/*!
2755    \ingroup Ed25519
2756    \brief Encodes Ed25519 public key to DER format.
2757
2758    \return Size on success
2759    \return negative on error
2760
2761    \param key Ed25519 key structure with public key
2762    \param output Buffer for DER encoded public key
2763    \param inLen Size of output buffer
2764
2765    _Example_
2766    \code
2767    ed25519_key key;
2768    byte der[1024];
2769    int derSz = wc_Ed25519PublicKeyToDer(&key, der,
2770                                         sizeof(der));
2771    \endcode
2772
2773    \sa wc_Ed25519PublicKeyDecode
2774*/
2775int wc_Ed25519PublicKeyToDer(const ed25519_key* key, byte* output,
2776                              int inLen);
2777
2778/*!
2779    \ingroup Ed448
2780    \brief Decodes Ed448 private key from DER format.
2781
2782    \return 0 on success
2783    \return negative on error
2784
2785    \param input DER encoded Ed448 private key buffer
2786    \param inOutIdx Pointer to index in buffer
2787    \param key Ed448 key structure to store key
2788    \param inSz Size of input buffer
2789
2790    _Example_
2791    \code
2792    ed448_key key;
2793    word32 idx = 0;
2794    int ret = wc_Ed448PrivateKeyDecode(derBuf, &idx, &key,
2795                                       derSz);
2796    \endcode
2797
2798    \sa wc_Ed448PrivateKeyToDer
2799*/
2800int wc_Ed448PrivateKeyDecode(const byte* input, word32* inOutIdx,
2801                              ed448_key* key, word32 inSz);
2802
2803/*!
2804    \ingroup Ed448
2805    \brief Decodes Ed448 public key from DER format.
2806
2807    \return 0 on success
2808    \return negative on error
2809
2810    \param input DER encoded Ed448 public key buffer
2811    \param inOutIdx Pointer to index in buffer
2812    \param key Ed448 key structure to store key
2813    \param inSz Size of input buffer
2814
2815    _Example_
2816    \code
2817    ed448_key key;
2818    word32 idx = 0;
2819    int ret = wc_Ed448PublicKeyDecode(derBuf, &idx, &key,
2820                                      derSz);
2821    \endcode
2822
2823    \sa wc_Ed448PublicKeyToDer
2824*/
2825int wc_Ed448PublicKeyDecode(const byte* input, word32* inOutIdx,
2826                             ed448_key* key, word32 inSz);
2827
2828/*!
2829    \ingroup Ed448
2830    \brief Encodes Ed448 key to DER format.
2831
2832    \return Size on success
2833    \return negative on error
2834
2835    \param key Ed448 key structure
2836    \param output Buffer for DER encoded key
2837    \param inLen Size of output buffer
2838
2839    _Example_
2840    \code
2841    ed448_key key;
2842    byte der[1024];
2843    int derSz = wc_Ed448KeyToDer(&key, der, sizeof(der));
2844    \endcode
2845
2846    \sa wc_Ed448PrivateKeyToDer
2847*/
2848int wc_Ed448KeyToDer(const ed448_key* key, byte* output, word32 inLen);
2849
2850/*!
2851    \ingroup Ed448
2852    \brief Encodes Ed448 private key to DER format.
2853
2854    \return Size on success
2855    \return negative on error
2856
2857    \param key Ed448 key structure with private key
2858    \param output Buffer for DER encoded private key
2859    \param inLen Size of output buffer
2860
2861    _Example_
2862    \code
2863    ed448_key key;
2864    byte der[1024];
2865    int derSz = wc_Ed448PrivateKeyToDer(&key, der,
2866                                        sizeof(der));
2867    \endcode
2868
2869    \sa wc_Ed448PrivateKeyDecode
2870*/
2871int wc_Ed448PrivateKeyToDer(const ed448_key* key, byte* output,
2872                             word32 inLen);
2873
2874/*!
2875    \ingroup Ed448
2876    \brief Encodes Ed448 public key to DER format.
2877
2878    \return Size on success
2879    \return negative on error
2880
2881    \param key Ed448 key structure with public key
2882    \param output Buffer for DER encoded public key
2883    \param inLen Size of output buffer
2884    \param withAlg 1 to include algorithm identifier, 0 for key data only
2885
2886    _Example_
2887    \code
2888    ed448_key key;
2889    byte der[1024];
2890    int derSz = wc_Ed448PublicKeyToDer(&key, der,
2891                                       sizeof(der), 1);
2892    \endcode
2893
2894    \sa wc_Ed448PublicKeyDecode
2895*/
2896int wc_Ed448PublicKeyToDer(const ed448_key* key, byte* output,
2897                            word32 inLen, int withAlg);
2898
2899/*!
2900    \ingroup Curve448
2901    \brief Decodes Curve448 private key from DER format.
2902
2903    \return 0 on success
2904    \return negative on error
2905
2906    \param input DER encoded Curve448 private key buffer
2907    \param inOutIdx Pointer to index in buffer
2908    \param key Curve448 key structure to store key
2909    \param inSz Size of input buffer
2910
2911    _Example_
2912    \code
2913    curve448_key key;
2914    word32 idx = 0;
2915    int ret = wc_Curve448PrivateKeyDecode(derBuf, &idx, &key,
2916                                          derSz);
2917    \endcode
2918
2919    \sa wc_Curve448PrivateKeyToDer
2920*/
2921int wc_Curve448PrivateKeyDecode(const byte* input, word32* inOutIdx,
2922                                 curve448_key* key, word32 inSz);
2923
2924/*!
2925    \ingroup Curve448
2926    \brief Decodes Curve448 public key from DER format.
2927
2928    \return 0 on success
2929    \return negative on error
2930
2931    \param input DER encoded Curve448 public key buffer
2932    \param inOutIdx Pointer to index in buffer
2933    \param key Curve448 key structure to store key
2934    \param inSz Size of input buffer
2935
2936    _Example_
2937    \code
2938    curve448_key key;
2939    word32 idx = 0;
2940    int ret = wc_Curve448PublicKeyDecode(derBuf, &idx, &key,
2941                                         derSz);
2942    \endcode
2943
2944    \sa wc_Curve448PublicKeyToDer
2945*/
2946int wc_Curve448PublicKeyDecode(const byte* input, word32* inOutIdx,
2947                                curve448_key* key, word32 inSz);
2948
2949/*!
2950    \ingroup Curve448
2951    \brief Encodes Curve448 private key to DER format.
2952
2953    \return Size on success
2954    \return negative on error
2955
2956    \param key Curve448 key structure with private key
2957    \param output Buffer for DER encoded private key
2958    \param inLen Size of output buffer
2959
2960    _Example_
2961    \code
2962    curve448_key key;
2963    byte der[1024];
2964    int derSz = wc_Curve448PrivateKeyToDer(&key, der,
2965                                           sizeof(der));
2966    \endcode
2967
2968    \sa wc_Curve448PrivateKeyDecode
2969*/
2970int wc_Curve448PrivateKeyToDer(curve448_key* key, byte* output,
2971                                word32 inLen);
2972
2973/*!
2974    \ingroup Curve448
2975    \brief Encodes Curve448 public key to DER format.
2976
2977    \return Size on success
2978    \return negative on error
2979
2980    \param key Curve448 key structure with public key
2981    \param output Buffer for DER encoded public key
2982    \param inLen Size of output buffer
2983
2984    _Example_
2985    \code
2986    curve448_key key;
2987    byte der[1024];
2988    int derSz = wc_Curve448PublicKeyToDer(&key, der,
2989                                          sizeof(der));
2990    \endcode
2991
2992    \sa wc_Curve448PublicKeyDecode
2993*/
2994int wc_Curve448PublicKeyToDer(curve448_key* key, byte* output,
2995                               word32 inLen);
2996
2997/*!
2998    \ingroup ASN
2999
3000    \brief This function encodes a digital signature into the output buffer,
3001    and returns the size of the encoded signature created.
3002
3003    \return Success On successfully writing the encoded signature to output,
3004    returns the length written to the buffer
3005
3006    \param out pointer to the buffer where the encoded signature will be written
3007    \param digest pointer to the digest to use to encode the signature
3008    \param digSz the length of the buffer containing the digest
3009    \param hashOID OID identifying the hash type used to generate the
3010    signature. Valid options, depending on build configurations, are: SHAh,
3011    SHA256h, SHA384h, SHA512h, MD2h, MD5h, DESb, DES3b, CTC_MD5wRSA,
3012    CTC_SHAwRSA, CTC_SHA256wRSA, CTC_SHA384wRSA, CTC_SHA512wRSA, CTC_SHAwECDSA,
3013    CTC_SHA256wECDSA, CTC_SHA384wECDSA, and CTC_SHA512wECDSA.
3014
3015    \endcode
3016    \code
3017    int signSz;
3018    byte encodedSig[MAX_ENCODED_SIG_SZ];
3019    Sha256 sha256;
3020    // initialize sha256 for hashing
3021
3022    byte* dig = = (byte*)malloc(WC_SHA256_DIGEST_SIZE);
3023    // perform hashing and hash updating so dig stores SHA-256 hash
3024    // (see wc_InitSha256, wc_Sha256Update and wc_Sha256Final)
3025    signSz = wc_EncodeSignature(encodedSig, dig, WC_SHA256_DIGEST_SIZE, SHA256h);
3026    \endcode
3027
3028    \sa none
3029*/
3030word32 wc_EncodeSignature(byte* out, const byte* digest,
3031                                      word32 digSz, int hashOID);
3032
3033/*!
3034    \ingroup ASN
3035
3036    \brief This function returns the hash OID that corresponds to a hashing
3037    type. For example, when given the type: WC_SHA512, this function returns the
3038    identifier corresponding to a SHA512 hash, SHA512h.
3039
3040    \return Success On success, returns the OID corresponding to the
3041    appropriate hash to use with that encryption type.
3042    \return 0 Returned if an unrecognized hash type is passed in as argument.
3043
3044    \param type the hash type for which to find the OID. Valid options,
3045    depending on build configuration, include: WC_MD5, WC_SHA, WC_SHA256,
3046    WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
3047
3048    _Example_
3049    \code
3050    int hashOID;
3051
3052    hashOID = wc_GetCTC_HashOID(WC_SHA512);
3053    if (hashOID == 0) {
3054	    // WOLFSSL_SHA512 not defined
3055    }
3056    \endcode
3057
3058    \sa none
3059*/
3060int wc_GetCTC_HashOID(int type);
3061
3062/*!
3063    \ingroup ASN
3064
3065    \brief This function cleans up memory and resources used by the certificate
3066     structure's decoded cert cache. When WOLFSSL_CERT_GEN_CACHE is defined the
3067     decoded cert structure is cached in the certificate structure. This allows
3068     subsequent calls to certificate set functions to avoid parsing the decoded
3069     cert on each call.
3070
3071    \return 0 on success.
3072    \return BAD_FUNC_ARG Returned if invalid pointer is passed in as argument.
3073
3074    \param cert pointer to an uninitialized certificate information structure.
3075
3076    _Example_
3077    \code
3078    Cert cert; // Initialized certificate structure
3079
3080    wc_SetCert_Free(&cert);
3081    \endcode
3082
3083    \sa wc_SetAuthKeyIdFromCert
3084    \sa wc_SetIssuerBuffer
3085    \sa wc_SetSubjectBuffer
3086    \sa wc_SetSubjectRaw
3087    \sa wc_SetIssuerRaw
3088    \sa wc_SetAltNamesBuffer
3089    \sa wc_SetDatesBuffer
3090*/
3091void wc_SetCert_Free(Cert* cert);
3092
3093/*!
3094    \ingroup ASN
3095
3096    \brief This function finds the beginning of the traditional private key
3097     inside a PKCS#8 unencrypted buffer.
3098
3099    \return Length of traditional private key on success.
3100    \return Negative values on failure.
3101
3102    \param input Buffer containing unencrypted PKCS#8 private key.
3103    \param inOutIdx Index into the input buffer. On input, it should be a byte
3104    offset to the beginning of the the PKCS#8 buffer. On output, it will be the
3105    byte offset to the traditional private key within the input buffer.
3106    \param sz The number of bytes in the input buffer.
3107
3108    _Example_
3109    \code
3110    byte* pkcs8Buf; // Buffer containing PKCS#8 key.
3111    word32 idx = 0;
3112    word32 sz; // Size of pkcs8Buf.
3113    ...
3114    ret = wc_GetPkcs8TraditionalOffset(pkcs8Buf, &idx, sz);
3115    // pkcs8Buf + idx is now the beginning of the traditional private key bytes.
3116    \endcode
3117
3118    \sa wc_CreatePKCS8Key
3119    \sa wc_EncryptPKCS8Key
3120    \sa wc_DecryptPKCS8Key
3121    \sa wc_CreateEncryptedPKCS8Key
3122*/
3123int wc_GetPkcs8TraditionalOffset(byte* input,
3124                                             word32* inOutIdx, word32 sz);
3125
3126/*!
3127    \ingroup ASN
3128
3129    \brief This function takes in a DER private key and converts it to PKCS#8
3130    format. Also used in creating PKCS#12 shrouded key bags. See RFC 5208.
3131
3132    \return The size of the PKCS#8 key placed into out on success.
3133    \return LENGTH_ONLY_E if out is NULL, with required output buffer size in
3134    outSz.
3135    \return Other negative values on failure.
3136
3137    \param out Buffer to place result in. If NULL, required out buffer size
3138    returned in outSz.
3139    \param outSz Size of out buffer.
3140    \param key Buffer with traditional DER key.
3141    \param keySz Size of key buffer.
3142    \param algoID Algorithm ID (e.g. RSAk).
3143    \param curveOID ECC curve OID if used. Should be NULL for RSA keys.
3144    \param oidSz Size of curve OID. Is set to 0 if curveOID is NULL.
3145
3146    _Example_
3147    \code
3148    ecc_key eccKey;              // wolfSSL ECC key object.
3149    byte* der;                   // DER-encoded ECC key.
3150    word32 derSize;              // Size of der.
3151    const byte* curveOid = NULL; // OID of curve used by eccKey.
3152    word32 curveOidSz = 0;       // Size of curve OID.
3153    byte* pkcs8;                 // Output buffer for PKCS#8 key.
3154    word32 pkcs8Sz;              // Size of output buffer.
3155
3156    derSize = wc_EccKeyDerSize(&eccKey, 1);
3157    ...
3158    derSize = wc_EccKeyToDer(&eccKey, der, derSize);
3159    ...
3160    ret = wc_ecc_get_oid(eccKey.dp->oidSum, &curveOid, &curveOidSz);
3161    ...
3162    ret = wc_CreatePKCS8Key(NULL, &pkcs8Sz, der,
3163        derSize, ECDSAk, curveOid, curveOidSz); // Get size needed in pkcs8Sz.
3164    ...
3165    ret = wc_CreatePKCS8Key(pkcs8, &pkcs8Sz, der,
3166        derSize, ECDSAk, curveOid, curveOidSz);
3167    \endcode
3168
3169    \sa wc_GetPkcs8TraditionalOffset
3170    \sa wc_EncryptPKCS8Key
3171    \sa wc_DecryptPKCS8Key
3172    \sa wc_CreateEncryptedPKCS8Key
3173*/
3174int wc_CreatePKCS8Key(byte* out, word32* outSz,
3175        byte* key, word32 keySz, int algoID, const byte* curveOID,
3176        word32 oidSz);
3177
3178/*!
3179    \ingroup ASN
3180
3181    \brief This function takes in an unencrypted PKCS#8 DER key (e.g. one
3182     created by wc_CreatePKCS8Key) and converts it to PKCS#8 encrypted format.
3183     The resulting encrypted key can be decrypted using wc_DecryptPKCS8Key. See
3184     RFC 5208.
3185
3186    \return The size of the encrypted key placed in out on success.
3187    \return LENGTH_ONLY_E if out is NULL, with required output buffer size in
3188    outSz.
3189    \return Other negative values on failure.
3190
3191    \param key Buffer with traditional DER key.
3192    \param keySz Size of key buffer.
3193    \param out Buffer to place result in. If NULL, required out buffer size
3194    returned in outSz.
3195    \param outSz Size of out buffer.
3196    \param password The password to use for the password-based encryption
3197    algorithm.
3198    \param passwordSz The length of the password (not including the NULL
3199    terminator).
3200    \param vPKCS The PKCS version to use. Can be 1 for PKCS12 or PKCS5.
3201    \param pbeOid The OID of the PBE scheme to use (e.g. PBES2 or one of the
3202    OIDs for PBES1 in RFC 2898 A.3).
3203    \param encAlgId The encryption algorithm ID to use (e.g. AES256CBCb).
3204    \param salt The salt buffer to use. If NULL, a random salt will be used.
3205    \param saltSz The length of the salt buffer. Can be 0 if passing NULL for
3206    salt.
3207    \param itt The number of iterations to use for the KDF.
3208    \param rng A pointer to an initialized WC_RNG object.
3209    \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
3210
3211    _Example_
3212    \code
3213    byte* pkcs8;          // Unencrypted PKCS#8 key.
3214    word32 pkcs8Sz;       // Size of pkcs8.
3215    byte* pkcs8Enc;       // Encrypted PKCS#8 key.
3216    word32 pkcs8EncSz;    // Size of pkcs8Enc.
3217    const char* password; // Password to use for encryption.
3218    int passwordSz;       // Length of password (not including NULL terminator).
3219    WC_RNG rng;
3220
3221    // The following produces an encrypted version of pkcs8 in pkcs8Enc. The
3222    // encryption uses password-based encryption scheme 2 (PBE2) from PKCS#5 and
3223    // the AES cipher in CBC mode with a 256-bit key. See RFC 8018 for more on
3224    // PKCS#5.
3225    ret = wc_EncryptPKCS8Key(pkcs8, pkcs8Sz, pkcs8Enc, &pkcs8EncSz, password,
3226            passwordSz, PKCS5, PBES2, AES256CBCb, NULL, 0,
3227            WC_PKCS12_ITT_DEFAULT, &rng, NULL);
3228    \endcode
3229
3230    \sa wc_GetPkcs8TraditionalOffset
3231    \sa wc_CreatePKCS8Key
3232    \sa wc_DecryptPKCS8Key
3233    \sa wc_CreateEncryptedPKCS8Key
3234*/
3235int wc_EncryptPKCS8Key(byte* key, word32 keySz, byte* out,
3236        word32* outSz, const char* password, int passwordSz, int vPKCS,
3237        int pbeOid, int encAlgId, byte* salt, word32 saltSz, int itt,
3238        WC_RNG* rng, void* heap);
3239
3240/*!
3241    \ingroup ASN
3242    \brief Encrypts PKCS#8 key with extended parameters.
3243
3244    \return Size on success
3245    \return negative on error
3246
3247    \param key Private key buffer
3248    \param keySz Size of private key
3249    \param out Output buffer for encrypted key
3250    \param outSz Pointer to output buffer size (in/out)
3251    \param password Password for encryption
3252    \param passwordSz Password length
3253    \param vPKCS PKCS version
3254    \param pbeOid PBE algorithm OID
3255    \param encAlgId Encryption algorithm ID
3256    \param salt Salt buffer
3257    \param saltSz Salt size
3258    \param itt Iteration count
3259    \param rng Random number generator
3260    \param heap Heap hint for memory allocation
3261    \param devId Device ID for hardware acceleration
3262
3263    _Example_
3264    \code
3265    byte key[256], encrypted[512];
3266    word32 encSz = sizeof(encrypted);
3267    WC_RNG rng;
3268    int ret = wc_EncryptPKCS8Key_ex(key, keySz, encrypted,
3269                                    &encSz, "password", 8,
3270                                    PKCS5, PBES2, AES256CBCb,
3271                                    NULL, 0, 2048, &rng, NULL,
3272                                    INVALID_DEVID);
3273    \endcode
3274
3275    \sa wc_EncryptPKCS8Key
3276*/
3277int wc_EncryptPKCS8Key_ex(byte* key, word32 keySz, byte* out,
3278                          word32* outSz, const char* password,
3279                          int passwordSz, int vPKCS, int pbeOid,
3280                          int encAlgId, byte* salt, word32 saltSz,
3281                          int itt, WC_RNG* rng, void* heap,
3282                          int devId);
3283
3284/*!
3285    \ingroup ASN
3286    \brief Gets current time for certificate operations.
3287
3288    \return 0 on success
3289    \return negative on error
3290
3291    \param timePtr Pointer to time buffer
3292    \param timeSize Size of time buffer
3293
3294    _Example_
3295    \code
3296    time_t currentTime;
3297    int ret = wc_GetTime(&currentTime, sizeof(currentTime));
3298    \endcode
3299
3300    \sa wc_GetDateInfo
3301*/
3302int wc_GetTime(void* timePtr, word32 timeSize);
3303
3304/*!
3305    \ingroup ASN
3306    \brief Gets encryption info from encrypted PEM.
3307
3308    \return 0 on success
3309    \return negative on error
3310
3311    \param info EncryptedInfo structure to populate
3312    \param cipherName Cipher name string
3313
3314    _Example_
3315    \code
3316    EncryptedInfo info;
3317    int ret = wc_EncryptedInfoGet(&info, "AES-256-CBC");
3318    \endcode
3319
3320    \sa wc_PemToDer
3321*/
3322int wc_EncryptedInfoGet(EncryptedInfo* info,
3323                        const char* cipherName);
3324
3325/*!
3326    \ingroup ASN
3327    \brief Parses PIV certificate format.
3328
3329    \return 0 on success
3330    \return negative on error
3331
3332    \param cert PIV certificate structure to populate
3333    \param buf Buffer containing PIV certificate
3334    \param totalSz Size of buffer
3335
3336    _Example_
3337    \code
3338    wc_CertPIV cert;
3339    int ret = wc_ParseCertPIV(&cert, pivBuf, pivSz);
3340    \endcode
3341
3342    \sa wc_InitDecodedCert
3343*/
3344int wc_ParseCertPIV(wc_CertPIV* cert, const byte* buf,
3345                    word32 totalSz);
3346
3347/*!
3348    \ingroup ASN
3349    \brief Extracts subject public key info from certificate.
3350
3351    \return Size on success
3352    \return negative on error
3353
3354    \param certDer DER encoded certificate buffer
3355    \param certDerSz Size of certificate
3356    \param pubKeyDer Output buffer for public key
3357    \param pubKeyDerSz Pointer to output buffer size (in/out)
3358
3359    _Example_
3360    \code
3361    byte pubKey[1024];
3362    word32 pubKeySz = sizeof(pubKey);
3363    int ret = wc_GetSubjectPubKeyInfoDerFromCert(certDer,
3364                                                 certSz,
3365                                                 pubKey,
3366                                                 &pubKeySz);
3367    \endcode
3368
3369    \sa wc_GetPubKeyDerFromCert
3370*/
3371int wc_GetSubjectPubKeyInfoDerFromCert(const byte* certDer,
3372                                       word32 certDerSz,
3373                                       byte* pubKeyDer,
3374                                       word32* pubKeyDerSz);
3375
3376/*!
3377    \ingroup ASN
3378
3379    \brief Retrieves the subject name from a decoded certificate.
3380
3381    This function copies the subject name string from a DecodedCert
3382    structure into the provided buffer. The string uses a one-line
3383    distinguished name format with "/" delimiters
3384    (e.g. "/C=US/O=Org/CN=example.com"). The output is NOT
3385    NUL-terminated; the caller should append a NUL byte if needed.
3386    If buf is NULL, the required buffer size is returned
3387    in bufSz and LENGTH_ONLY_E is returned.
3388
3389    \param cert   Pointer to the DecodedCert (must have been parsed).
3390    \param buf    Output buffer to receive the subject name string,
3391                  or NULL to query the required size.
3392    \param bufSz  Pointer to the buffer size. On input, the available
3393                  buffer size. On output, the number of bytes written
3394                  (excluding any NUL terminator) or the required size
3395                  if buf is NULL.
3396
3397    \return 0 on success.
3398    \return LENGTH_ONLY_E when buf is NULL (bufSz contains required size).
3399    \return BAD_FUNC_ARG if cert or bufSz is NULL.
3400    \return BUFFER_E if the provided buffer is too small.
3401
3402    \sa wc_GetDecodedCertIssuer
3403    \sa wc_GetDecodedCertSerial
3404    \sa wc_InitDecodedCert
3405    \sa wc_ParseCert
3406*/
3407int wc_GetDecodedCertSubject(const struct DecodedCert* cert,
3408                             char* buf, word32* bufSz);
3409
3410/*!
3411    \ingroup ASN
3412
3413    \brief Retrieves the issuer name from a decoded certificate.
3414
3415    This function copies the issuer name string from a DecodedCert
3416    structure into the provided buffer. The string uses a one-line
3417    distinguished name format with "/" delimiters
3418    (e.g. "/C=US/O=Org/CN=example.com"). The output is NOT
3419    NUL-terminated; the caller should append a NUL byte if needed.
3420    If buf is NULL, the required buffer size is returned
3421    in bufSz and LENGTH_ONLY_E is returned.
3422
3423    \param cert   Pointer to the DecodedCert (must have been parsed).
3424    \param buf    Output buffer to receive the issuer name string,
3425                  or NULL to query the required size.
3426    \param bufSz  Pointer to the buffer size. On input, the available
3427                  buffer size. On output, the number of bytes written
3428                  (excluding any NUL terminator) or the required size
3429                  if buf is NULL.
3430
3431    \return 0 on success.
3432    \return LENGTH_ONLY_E when buf is NULL (bufSz contains required size).
3433    \return BAD_FUNC_ARG if cert or bufSz is NULL.
3434    \return BUFFER_E if the provided buffer is too small.
3435
3436    \sa wc_GetDecodedCertSubject
3437    \sa wc_GetDecodedCertSerial
3438    \sa wc_InitDecodedCert
3439    \sa wc_ParseCert
3440*/
3441int wc_GetDecodedCertIssuer(const struct DecodedCert* cert,
3442                            char* buf, word32* bufSz);
3443
3444/*!
3445    \ingroup ASN
3446
3447    \brief Retrieves the serial number from a decoded certificate.
3448
3449    This function copies the serial number bytes from a DecodedCert
3450    structure into the provided buffer. If buf is NULL, the required
3451    buffer size is returned in bufSz and LENGTH_ONLY_E is returned.
3452
3453    \param cert   Pointer to the DecodedCert (must have been parsed).
3454    \param buf    Output buffer to receive the serial number bytes,
3455                  or NULL to query the required size.
3456    \param bufSz  Pointer to the buffer size. On input, the available
3457                  buffer size. On output, the number of bytes written
3458                  or the required size if buf is NULL.
3459
3460    \return 0 on success.
3461    \return LENGTH_ONLY_E when buf is NULL (bufSz contains required size).
3462    \return BAD_FUNC_ARG if cert or bufSz is NULL.
3463    \return BUFFER_E if the provided buffer is too small.
3464
3465    \sa wc_GetDecodedCertSubject
3466    \sa wc_GetDecodedCertIssuer
3467    \sa wc_InitDecodedCert
3468    \sa wc_ParseCert
3469*/
3470int wc_GetDecodedCertSerial(const struct DecodedCert* cert,
3471                            byte* buf, word32* bufSz);
3472
3473/*!
3474    \ingroup ASN
3475    \brief Extracts UUID from certificate.
3476
3477    \return 0 on success
3478    \return negative on error
3479
3480    \param cert Decoded certificate structure
3481    \param uuid Output buffer for UUID
3482    \param uuidSz Pointer to UUID buffer size (in/out)
3483
3484    _Example_
3485    \code
3486    DecodedCert cert;
3487    byte uuid[16];
3488    int uuidSz = sizeof(uuid);
3489    int ret = wc_GetUUIDFromCert(&cert, uuid, &uuidSz);
3490    \endcode
3491
3492    \sa wc_ParseCert
3493*/
3494int wc_GetUUIDFromCert(struct DecodedCert* cert,
3495                       byte* uuid, int* uuidSz);
3496
3497/*!
3498    \ingroup ASN
3499    \brief Extracts FASCN from certificate.
3500
3501    \return 0 on success
3502    \return negative on error
3503
3504    \param cert Decoded certificate structure
3505    \param fascn Output buffer for FASCN
3506    \param fascnSz Pointer to FASCN buffer size (in/out)
3507
3508    _Example_
3509    \code
3510    DecodedCert cert;
3511    byte fascn[25];
3512    int fascnSz = sizeof(fascn);
3513    int ret = wc_GetFASCNFromCert(&cert, fascn, &fascnSz);
3514    \endcode
3515
3516    \sa wc_ParseCert
3517*/
3518int wc_GetFASCNFromCert(struct DecodedCert* cert,
3519                        byte* fascn, int* fascnSz);
3520
3521/*!
3522    \ingroup ASN
3523    \brief Generates the pre-TBS (To Be Signed) certificate data from a
3524    decoded certificate. The TBS portion is the certificate data that gets
3525    signed by the certificate authority. This function is used in dual
3526    algorithm certificate creation where the TBS data needs to be extracted
3527    for signing with an alternative algorithm (e.g., a post-quantum algorithm).
3528
3529    \note This API is only available when WOLFSSL_DUAL_ALG_CERTS is defined,
3530    which enables support for dual algorithm certificates used in Post-Quantum
3531    cryptography to provide hybrid signing with both traditional and PQ
3532    algorithms.
3533
3534    \return Size of the pre-TBS data on success
3535    \return Negative error code on failure
3536
3537    \param cert Decoded certificate structure containing the certificate to
3538    extract TBS data from
3539    \param der Output buffer for the pre-TBS DER-encoded data
3540    \param derSz Size of output buffer in bytes
3541
3542    _Example_
3543    \code
3544    DecodedCert cert;
3545    byte preTbs[2048];
3546    int ret = wc_GeneratePreTBS(&cert, preTbs, sizeof(preTbs));
3547    if (ret > 0) {
3548        // ret contains the size of the pre-TBS data
3549        // preTbs can now be signed with an alternative algorithm
3550    }
3551    \endcode
3552
3553    \sa wc_MakeCert
3554    \sa wc_MakeSigWithBitStr
3555*/
3556int wc_GeneratePreTBS(struct DecodedCert* cert, byte *der,
3557                      int derSz);
3558
3559/*!
3560    \ingroup ASN
3561    \brief Initializes decoded attribute certificate structure.
3562
3563    \return void
3564
3565    \param acert Attribute certificate structure to initialize
3566    \param heap Heap hint for memory allocation
3567
3568    _Example_
3569    \code
3570    DecodedAcert acert;
3571    wc_InitDecodedAcert(&acert, NULL);
3572    \endcode
3573
3574    \sa wc_FreeDecodedAcert
3575*/
3576void wc_InitDecodedAcert(struct DecodedAcert* acert,
3577                         void* heap);
3578
3579/*!
3580    \ingroup ASN
3581    \brief Frees decoded attribute certificate structure.
3582
3583    \return void
3584
3585    \param acert Attribute certificate structure to free
3586
3587    _Example_
3588    \code
3589    DecodedAcert acert;
3590    wc_InitDecodedAcert(&acert, NULL);
3591    wc_FreeDecodedAcert(&acert);
3592    \endcode
3593
3594    \sa wc_InitDecodedAcert
3595*/
3596void wc_FreeDecodedAcert(struct DecodedAcert * acert);
3597
3598/*!
3599    \ingroup ASN
3600    \brief Parses X.509 attribute certificate.
3601
3602    \return 0 on success
3603    \return negative on error
3604
3605    \param acert Decoded attribute certificate structure
3606    \param verify Non-zero to verify signature
3607
3608    _Example_
3609    \code
3610    DecodedAcert acert;
3611    wc_InitDecodedAcert(&acert, NULL);
3612    int ret = wc_ParseX509Acert(&acert, 1);
3613    \endcode
3614
3615    \sa wc_VerifyX509Acert
3616*/
3617int wc_ParseX509Acert(struct DecodedAcert* acert, int verify);
3618
3619/*!
3620    \ingroup ASN
3621    \brief Verifies X.509 attribute certificate.
3622
3623    \return 0 on success
3624    \return negative on error
3625
3626    \param acert Attribute certificate buffer
3627    \param acertSz Size of attribute certificate
3628    \param issuerCert Issuer certificate buffer
3629    \param issuerCertSz Size of issuer certificate
3630    \param cm Certificate manager
3631
3632    _Example_
3633    \code
3634    int ret = wc_VerifyX509Acert(acertBuf, acertSz,
3635                                 issuerBuf, issuerSz, cm);
3636    \endcode
3637
3638    \sa wc_ParseX509Acert
3639*/
3640int wc_VerifyX509Acert(const byte* acert, word32 acertSz,
3641                       const byte* issuerCert,
3642                       word32 issuerCertSz, void* cm);
3643
3644/*!
3645    \ingroup ASN
3646
3647    \brief This function takes an encrypted PKCS#8 DER key and decrypts it to
3648     PKCS#8 unencrypted DER.Undoes the encryption done by wc_EncryptPKCS8Key.
3649     See RFC5208. The input buffer is overwritten with the decrypted data.
3650
3651    \return The length of the decrypted buffer on success.
3652    \return Negative values on failure.
3653
3654    \param input On input, buffer containing encrypted PKCS#8 key. On successful
3655    output, contains the decrypted key.
3656    \param sz Size of the input buffer.
3657    \param password The password used to encrypt the key.
3658    \param passwordSz The length of the password (not including NULL
3659    terminator).
3660
3661    _Example_
3662    \code
3663    byte* pkcs8Enc;       // Encrypted PKCS#8 key made with wc_EncryptPKCS8Key.
3664    word32 pkcs8EncSz;    // Size of pkcs8Enc.
3665    const char* password; // Password to use for decryption.
3666    int passwordSz;       // Length of password (not including NULL terminator).
3667
3668    ret = wc_DecryptPKCS8Key(pkcs8Enc, pkcs8EncSz, password, passwordSz);
3669    \endcode
3670
3671    \sa wc_GetPkcs8TraditionalOffset
3672    \sa wc_CreatePKCS8Key
3673    \sa wc_EncryptPKCS8Key
3674    \sa wc_CreateEncryptedPKCS8Key
3675*/
3676int wc_DecryptPKCS8Key(byte* input, word32 sz, const char* password,
3677        int passwordSz);
3678
3679/*!
3680    \ingroup ASN
3681
3682    \brief This function takes a traditional, DER key, converts it to PKCS#8
3683     format, and encrypts it. It uses wc_CreatePKCS8Key and wc_EncryptPKCS8Key
3684     to do this.
3685
3686    \return The size of the encrypted key placed in out on success.
3687    \return LENGTH_ONLY_E if out is NULL, with required output buffer size in
3688    outSz.
3689    \return Other negative values on failure.
3690
3691    \param key Buffer with traditional DER key.
3692    \param keySz Size of key buffer.
3693    \param out Buffer to place result in. If NULL, required out buffer size
3694    returned in outSz.
3695    \param outSz Size of out buffer.
3696    \param password The password to use for the password-based encryption
3697    algorithm.
3698    \param passwordSz The length of the password (not including the NULL
3699    terminator).
3700    \param vPKCS The PKCS version to use. Can be 1 for PKCS12 or PKCS5.
3701    \param pbeOid The OID of the PBE scheme to use (e.g. PBES2 or one of the
3702    OIDs for PBES1 in RFC 2898 A.3).
3703    \param encAlgId The encryption algorithm ID to use (e.g. AES256CBCb).
3704    \param salt The salt buffer to use. If NULL, a random salt will be used.
3705    \param saltSz The length of the salt buffer. Can be 0 if passing NULL for
3706    salt.
3707    \param itt The number of iterations to use for the KDF.
3708    \param rng A pointer to an initialized WC_RNG object.
3709    \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
3710
3711    _Example_
3712    \code
3713    byte* key;            // Traditional private key (DER formatted).
3714    word32 keySz;         // Size of key.
3715    byte* pkcs8Enc;       // Encrypted PKCS#8 key.
3716    word32 pkcs8EncSz;    // Size of pkcs8Enc.
3717    const char* password; // Password to use for encryption.
3718    int passwordSz;       // Length of password (not including NULL terminator).
3719    WC_RNG rng;
3720
3721    // The following produces an encrypted, PKCS#8 version of key in pkcs8Enc.
3722    // The encryption uses password-based encryption scheme 2 (PBE2) from PKCS#5
3723    // and the AES cipher in CBC mode with a 256-bit key. See RFC 8018 for more
3724    // on PKCS#5.
3725    ret = wc_CreateEncryptedPKCS8Key(key, keySz, pkcs8Enc, &pkcs8EncSz,
3726            password, passwordSz, PKCS5, PBES2, AES256CBCb, NULL, 0,
3727            WC_PKCS12_ITT_DEFAULT, &rng, NULL);
3728    \endcode
3729
3730    \sa wc_GetPkcs8TraditionalOffset
3731    \sa wc_CreatePKCS8Key
3732    \sa wc_EncryptPKCS8Key
3733    \sa wc_DecryptPKCS8Key
3734*/
3735int wc_CreateEncryptedPKCS8Key(byte* key, word32 keySz, byte* out,
3736        word32* outSz, const char* password, int passwordSz, int vPKCS,
3737        int pbeOid, int encAlgId, byte* salt, word32 saltSz, int itt,
3738        WC_RNG* rng, void* heap);
3739
3740/*!
3741    \ingroup ASN
3742
3743    \brief This function initializes the DecodedCert pointed to by the "cert"
3744     parameter. It saves the "source" pointer to a DER-encoded certificate of
3745     length "inSz." This certificate can be parsed by a subsequent call to
3746     wc_ParseCert.
3747
3748    \param cert Pointer to an allocated DecodedCert object.
3749    \param source Pointer to a DER-encoded certificate.
3750    \param inSz Length of the DER-encoded certificate in bytes.
3751    \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
3752
3753    _Example_
3754    \code
3755    DecodedCert decodedCert; // Decoded certificate object.
3756    byte* certBuf;           // DER-encoded certificate buffer.
3757    word32 certBufSz;        // Size of certBuf in bytes.
3758
3759    wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
3760    \endcode
3761
3762    \sa wc_ParseCert
3763    \sa wc_FreeDecodedCert
3764*/
3765void wc_InitDecodedCert(struct DecodedCert* cert,
3766    const byte* source, word32 inSz, void* heap);
3767
3768/*!
3769    \ingroup ASN
3770
3771    \brief This function parses the DER-encoded certificate saved in the
3772    DecodedCert object and populates the fields of that object. The DecodedCert
3773    must have been initialized with a prior call to wc_InitDecodedCert. This
3774    function takes an optional pointer to a CertificateManager object, which
3775    is used to populate the certificate authority information of the
3776    DecodedCert, if the CA is found in the CertificateManager.
3777
3778    \return 0 on success.
3779    \return Other negative values on failure.
3780
3781    \param cert Pointer to an initialized DecodedCert object.
3782    \param type Type of certificate. See the CertType enum in asn_public.h.
3783    \param verify Flag that, if set, indicates the user wants to verify the
3784    validity of the certificate.
3785    \param cm An optional pointer to a CertificateManager. Can be NULL.
3786
3787    _Example_
3788    \code
3789    int ret;
3790    DecodedCert decodedCert; // Decoded certificate object.
3791    byte* certBuf;           // DER-encoded certificate buffer.
3792    word32 certBufSz;        // Size of certBuf in bytes.
3793
3794    wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
3795    ret = wc_ParseCert(&decodedCert, CERT_TYPE, NO_VERIFY, NULL);
3796    if (ret != 0) {
3797        fprintf(stderr, "wc_ParseCert failed.\n");
3798    }
3799    \endcode
3800
3801    \sa wc_InitDecodedCert
3802    \sa wc_FreeDecodedCert
3803*/
3804int wc_ParseCert(DecodedCert* cert, int type, int verify, void* cm);
3805
3806/*!
3807    \ingroup ASN
3808
3809    \brief This function frees a DecodedCert that was previously initialized
3810    with wc_InitDecodedCert.
3811
3812    \param cert Pointer to an initialized DecodedCert object.
3813
3814    _Example_
3815    \code
3816    int ret;
3817    DecodedCert decodedCert; // Decoded certificate object.
3818    byte* certBuf;           // DER-encoded certificate buffer.
3819    word32 certBufSz;        // Size of certBuf in bytes.
3820
3821    wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
3822    ret = wc_ParseCert(&decodedCert, CERT_TYPE, NO_VERIFY, NULL);
3823    if (ret != 0) {
3824        fprintf(stderr, "wc_ParseCert failed.\n");
3825    }
3826    wc_FreeDecodedCert(&decodedCert);
3827    \endcode
3828
3829    \sa wc_InitDecodedCert
3830    \sa wc_ParseCert
3831*/
3832void wc_FreeDecodedCert(struct DecodedCert* cert);
3833
3834/*!
3835    \ingroup ASN
3836
3837    \brief This function registers a time callback that will be used anytime
3838    wolfSSL needs to get the current time. The prototype of the callback should
3839    be the same as the "time" function from the C standard library.
3840
3841    \return 0 Returned on success.
3842
3843    \param f function to register as the time callback.
3844
3845    _Example_
3846    \code
3847    int ret = 0;
3848    // Time callback prototype
3849    time_t my_time_cb(time_t* t);
3850    // Register it
3851    ret = wc_SetTimeCb(my_time_cb);
3852    if (ret != 0) {
3853        // failed to set time callback
3854    }
3855    time_t my_time_cb(time_t* t)
3856    {
3857        // custom time function
3858    }
3859    \endcode
3860
3861    \sa wc_Time
3862*/
3863int wc_SetTimeCb(wc_time_cb f);
3864
3865/*!
3866    \ingroup ASN
3867
3868    \brief This function gets the current time. By default, it uses the XTIME
3869    macro, which varies between platforms. The user can use a function of their
3870    choosing instead via the wc_SetTimeCb function.
3871
3872    \return Time Current time returned on success.
3873
3874    \param t Optional time_t pointer to populate with current time.
3875
3876    _Example_
3877    \code
3878    time_t currentTime = 0;
3879    currentTime = wc_Time(NULL);
3880    wc_Time(&currentTime);
3881    \endcode
3882
3883    \sa wc_SetTimeCb
3884*/
3885time_t wc_Time(time_t* t);
3886
3887/*!
3888    \ingroup ASN
3889
3890    \brief This function injects a custom extension in to an X.509 certificate.
3891     note: The content at the address pointed to by any of the parameters that
3892           are pointers must not be modified until the certificate is generated
3893           and you have the der output. This function does NOT copy the
3894           contents to another buffer.
3895
3896    \return 0 Returned on success.
3897    \return Other negative values on failure.
3898
3899    \param cert Pointer to an initialized DecodedCert object.
3900    \param critical If 0, the extension will not be marked critical, otherwise
3901     it will be marked critical.
3902    \param oid Dot separated oid as a string. For example "1.2.840.10045.3.1.7"
3903    \param der The der encoding of the content of the extension.
3904    \param derSz The size in bytes of the der encoding.
3905
3906
3907    _Example_
3908    \code
3909    int ret = 0;
3910    Cert newCert;
3911    wc_InitCert(&newCert);
3912
3913    // Code to setup subject, public key, issuer, and other things goes here.
3914
3915    ret = wc_SetCustomExtension(&newCert, 1, "1.2.3.4.5",
3916              (const byte *)"This is a critical extension", 28);
3917    if (ret < 0) {
3918        // Failed to set the extension.
3919    }
3920
3921    ret = wc_SetCustomExtension(&newCert, 0, "1.2.3.4.6",
3922              (const byte *)"This is NOT a critical extension", 32)
3923    if (ret < 0) {
3924        // Failed to set the extension.
3925    }
3926
3927    // Code to sign the certificate and then write it out goes here.
3928
3929    \endcode
3930
3931    \sa wc_InitCert
3932    \sa wc_SetUnknownExtCallback
3933*/
3934int wc_SetCustomExtension(Cert *cert, int critical, const char *oid,
3935                                      const byte *der, word32 derSz);
3936
3937/*!
3938    \ingroup ASN
3939
3940    \brief This function registers a callback that will be used anytime
3941    wolfSSL encounters an unknown X.509 extension in a certificate while parsing
3942    a certificate. The prototype of the callback should be:
3943
3944    \return 0 Returned on success.
3945    \return Other negative values on failure.
3946
3947    \param cert the DecodedCert struct that is to be associated with this
3948    callback.
3949    \param cb function to register as the time callback.
3950
3951    _Example_
3952    \code
3953    int ret = 0;
3954    // Unknown extension callback prototype
3955    int myUnknownExtCallback(const word16* oid, word32 oidSz, int crit,
3956                             const unsigned char* der, word32 derSz);
3957
3958    // Register it
3959    ret = wc_SetUnknownExtCallback(cert, myUnknownExtCallback);
3960    if (ret != 0) {
3961        // failed to set the callback
3962    }
3963
3964    // oid: Array of integers that are the dot separated values in an oid.
3965    // oidSz: Number of values in oid.
3966    // crit: Whether the extension was mark critical.
3967    // der: The der encoding of the content of the extension.
3968    // derSz: The size in bytes of the der encoding.
3969    int myCustomExtCallback(const word16* oid, word32 oidSz, int crit,
3970                            const unsigned char* der, word32 derSz) {
3971
3972        // Logic to parse extension goes here.
3973
3974        // NOTE: by returning zero, we are accepting this extension and
3975        // informing wolfSSL that it is acceptable. If you find an extension
3976        // that you do not find acceptable, you should return an error. The
3977        // standard behavior upon encountering an unknown extension with the
3978        // critical flag set is to return ASN_CRIT_EXT_E. For the sake of
3979        // brevity, this example is always accepting every extension; you
3980        // should use different logic.
3981        return 0;
3982    }
3983    \endcode
3984
3985    \sa ParseCert
3986    \sa wc_SetCustomExtension
3987*/
3988int wc_SetUnknownExtCallback(DecodedCert* cert,
3989                                             wc_UnknownExtCallback cb);
3990/*!
3991    \ingroup ASN
3992
3993    \brief This function verifies the signature in the der form of an X.509
3994    certificate against a public key. The public key is expected to be the full
3995    subject public key info in der form.
3996
3997    \return 0 Returned on success.
3998    \return Other negative values on failure.
3999
4000    \param cert The der encoding of the X.509 certificate.
4001    \param certSz The size in bytes of cert.
4002    \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
4003    \param pubKey The der encoding of the public key.
4004    \param pubKeySz The size in bytes of pubKey.
4005    \param pubKeyOID OID identifying the algorithm of the public key.
4006    (ie: ECDSAk, DSAk or RSAk)
4007*/
4008int wc_CheckCertSigPubKey(const byte* cert, word32 certSz,
4009                                      void* heap, const byte* pubKey,
4010                                      word32 pubKeySz, int pubKeyOID);
4011
4012/*!
4013    \ingroup ASN
4014
4015    \brief This function initializes the ASN.1 print options.
4016
4017    \return  0 on success.
4018    \return  BAD_FUNC_ARG when asn1 is NULL.
4019
4020    \param opts  The ASN.1 options for printing.
4021
4022    _Example_
4023    \code
4024    Asn1PrintOptions opt;
4025
4026    // Initialize ASN.1 print options before use.
4027    wc_Asn1PrintOptions_Init(&opt);
4028    \endcode
4029
4030    \sa wc_Asn1PrintOptions_Set
4031    \sa wc_Asn1_PrintAll
4032*/
4033int wc_Asn1PrintOptions_Init(Asn1PrintOptions* opts);
4034
4035/*!
4036    \ingroup ASN
4037
4038    \brief This function sets a print option into an ASN.1 print options object.
4039
4040    \return  0 on success.
4041    \return  BAD_FUNC_ARG when asn1 is NULL.
4042    \return  BAD_FUNC_ARG when val is out of range for option.
4043
4044    \param opts  The ASN.1 options for printing.
4045    \param opt   An option to set value for.
4046    \param val   The value to set.
4047
4048    _Example_
4049    \code
4050    Asn1PrintOptions opt;
4051
4052    // Initialize ASN.1 print options before use.
4053    wc_Asn1PrintOptions_Init(&opt);
4054    // Set the number of indents when printing tag name to be 1.
4055    wc_Asn1PrintOptions_Set(&opt, ASN1_PRINT_OPT_INDENT, 1);
4056    \endcode
4057
4058    \sa wc_Asn1PrintOptions_Init
4059    \sa wc_Asn1_PrintAll
4060*/
4061int wc_Asn1PrintOptions_Set(Asn1PrintOptions* opts, enum Asn1PrintOpt opt,
4062    word32 val);
4063
4064/*!
4065    \ingroup ASN
4066
4067    \brief This function initializes an ASN.1 parsing object.
4068
4069    \return  0 on success.
4070    \return  BAD_FUNC_ARG when asn1 is NULL.
4071
4072    \param asn1  ASN.1 parse object.
4073
4074    _Example_
4075    \code
4076    Asn1 asn1;
4077
4078    // Initialize ASN.1 parse object before use.
4079    wc_Asn1_Init(&asn1);
4080    \endcode
4081
4082    \sa wc_Asn1_SetFile
4083    \sa wc_Asn1_PrintAll
4084 */
4085int wc_Asn1_Init(Asn1* asn1);
4086
4087/*!
4088    \ingroup ASN
4089
4090    \brief This function sets the file to use when printing into an ASN.1
4091    parsing object.
4092
4093    \return  0 on success.
4094    \return  BAD_FUNC_ARG when asn1 is NULL.
4095    \return  BAD_FUNC_ARG when file is XBADFILE.
4096
4097    \param asn1  The ASN.1 parse object.
4098    \param file  File to print to.
4099
4100    _Example_
4101    \code
4102    Asn1 asn1;
4103
4104    // Initialize ASN.1 parse object before use.
4105    wc_Asn1_Init(&asn1);
4106    // Set standard out to be the file descriptor to write to.
4107    wc_Asn1_SetFile(&asn1, stdout);
4108    \endcode
4109
4110    \sa wc_Asn1_Init
4111    \sa wc_Asn1_PrintAll
4112 */
4113int wc_Asn1_SetFile(Asn1* asn1, XFILE file);
4114
4115/*!
4116    \ingroup ASN
4117
4118    \brief Print all ASN.1 items.
4119
4120    \return  0 on success.
4121    \return  BAD_FUNC_ARG when asn1 or opts is NULL.
4122    \return  ASN_LEN_E when ASN.1 item's length too long.
4123    \return  ASN_DEPTH_E when end offset invalid.
4124    \return  ASN_PARSE_E when not all of an ASN.1 item parsed.
4125
4126    \param asn1  The ASN.1 parse object.
4127    \param opts  The ASN.1 print options.
4128    \param data  Buffer containing BER/DER data to print.
4129    \param len   Length of data to print in bytes.
4130
4131    \code
4132    Asn1PrintOptions opts;
4133    Asn1 asn1;
4134    unsigned char data[] = { Initialize with DER/BER data };
4135    word32 len = sizeof(data);
4136
4137    // Initialize ASN.1 print options before use.
4138    wc_Asn1PrintOptions_Init(&opt);
4139    // Set the number of indents when printing tag name to be 1.
4140    wc_Asn1PrintOptions_Set(&opt, ASN1_PRINT_OPT_INDENT, 1);
4141
4142    // Initialize ASN.1 parse object before use.
4143    wc_Asn1_Init(&asn1);
4144    // Set standard out to be the file descriptor to write to.
4145    wc_Asn1_SetFile(&asn1, stdout);
4146    // Print all ASN.1 items in buffer with the specified print options.
4147    wc_Asn1_PrintAll(&asn1, &opts, data, len);
4148    \endcode
4149
4150    \sa wc_Asn1_Init
4151    \sa wc_Asn1_SetFile
4152 */
4153int wc_Asn1_PrintAll(Asn1* asn1, Asn1PrintOptions* opts, unsigned char* data,
4154    word32 len);
4155
4156/*!
4157    \ingroup ASN
4158    \brief Sets OID to name callback for ASN.1 parsing.
4159
4160    \return 0 on success
4161    \return negative on error
4162
4163    \param asn1 ASN.1 structure
4164    \param nameCb Callback function to convert OID to name
4165
4166    _Example_
4167    \code
4168    Asn1 asn1;
4169    int ret = wc_Asn1_SetOidToNameCb(&asn1, myOidToNameCb);
4170    \endcode
4171
4172    \sa wc_Asn1_PrintAll
4173*/
4174int wc_Asn1_SetOidToNameCb(Asn1* asn1, Asn1OidToNameCb nameCb);
4175