luna - wolfssl/doc/dox_comments/header

   1/*!
   2    \ingroup PKCS7
   3
   4    \brief Callback used for a custom AES key wrap/unwrap operation.
   5
   6    \return The size of the wrapped/unwrapped key written to the output buffer
   7    should be returned on success. A 0 return value or error code (< 0)
   8    indicates a failure.
   9
  10    \param[in] key Specify the key to use.
  11    \param[in] keySz Size of the key to use.
  12    \param[in] in Specify the input data to wrap/unwrap.
  13    \param[in] inSz Size of the input data.
  14    \param[in] wrap 1 if the requested operation is a key wrap, 0 for unwrap.
  15    \param[out] out Specify the output buffer.
  16    \param[out] outSz Size of the output buffer.
  17*/
  18typedef int (*CallbackAESKeyWrapUnwrap)(const byte* key, word32 keySz,
  19        const byte* in, word32 inSz, int wrap, byte* out, word32 outSz);
  20
  21/*!
  22    \ingroup PKCS7
  23
  24    \brief This function initializes a PKCS7 structure with a DER-formatted
  25    certificate. To initialize an empty PKCS7 structure, one can pass in a NULL
  26    cert and 0 for certSz.
  27
  28    \return 0 Returned on successfully initializing the PKCS7 structure
  29    \return MEMORY_E Returned if there is an error allocating memory
  30    with XMALLOC
  31    \return ASN_PARSE_E Returned if there is an error parsing the cert header
  32    \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  33    encryption type from the cert
  34    \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  35    encryption specification of the cert file
  36    \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  37    start date
  38    \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  39    expiration date
  40    \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  41    from the certificate
  42    \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC
  43    key from the certificate
  44    \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  45    key object id
  46    \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  47    defined and the certificate is a V1 or V2 certificate
  48    \return BAD_FUNC_ARG Returned if there is an error processing the
  49    certificate extension
  50    \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  51    encountered in processing the certificate
  52    \return ASN_SIG_OID_E Returned if the signature encryption type is not
  53    the same as the encryption type of the certificate in the provided file
  54    \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  55    signature fails
  56    \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  57    permitted by the CA name constraints
  58    \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
  59    the certificate’s authenticity
  60
  61    \param pkcs7 pointer to the PKCS7 structure in which to
  62    store the decoded cert
  63    \param der pointer to a buffer containing a DER formatted ASN.1
  64    certificate with which to initialize the PKCS7 structure
  65    \param derSz size of the certificate buffer
  66
  67    _Example_
  68    \code
  69    wc_PKCS7 pkcs7;
  70    byte derBuff[] = { }; // initialize with DER-encoded certificate
  71    if ( wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff)) != 0 ) {
  72    	// error parsing certificate into pkcs7 format
  73    }
  74    \endcode
  75
  76    \sa wc_PKCS7_Free
  77*/
  78int  wc_PKCS7_InitWithCert(wc_PKCS7* pkcs7, byte* der, word32 derSz);
  79
  80/*!
  81    \ingroup PKCS7
  82
  83    \brief This function releases any memory allocated by a PKCS7 initializer.
  84
  85    \return none No returns.
  86
  87    \param pkcs7 pointer to the PKCS7 structure to free
  88
  89    _Example_
  90    \code
  91    PKCS7 pkcs7;
  92    // initialize and use PKCS7 object
  93
  94    wc_PKCS7_Free(pkcs7);
  95    \endcode
  96
  97    \sa wc_PKCS7_InitWithCert
  98*/
  99void wc_PKCS7_Free(wc_PKCS7* pkcs7);
 100
 101/*!
 102    \ingroup PKCS7
 103
 104    \brief This function builds the PKCS7 data content type, encoding the
 105    PKCS7 structure into a buffer containing a parsable PKCS7 data packet.
 106
 107    \return Success On successfully encoding the PKCS7 data into the buffer,
 108    returns the index parsed up to in the PKCS7 structure. This index also
 109    corresponds to the bytes written to the output buffer.
 110    \return BUFFER_E Returned if the given buffer is not large enough to hold
 111    the encoded certificate
 112
 113    \param pkcs7 pointer to the PKCS7 structure to encode
 114    \param output pointer to the buffer in which to store the encoded
 115    certificate
 116    \param outputSz size available in the output buffer
 117
 118    _Example_
 119    \code
 120    PKCS7 pkcs7;
 121    int ret;
 122
 123    byte derBuff[] = { }; // initialize with DER-encoded certificate
 124    byte pkcs7Buff[FOURK_BUF];
 125
 126    wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
 127    // update message and data to encode
 128    pkcs7.privateKey = key;
 129    pkcs7.privateKeySz = keySz;
 130    pkcs7.content = data;
 131    pkcs7.contentSz = dataSz;
 132    ... etc.
 133
 134    ret = wc_PKCS7_EncodeData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
 135    if ( ret != 0 ) {
 136	    // error encoding into output buffer
 137    }
 138    \endcode
 139
 140    \sa wc_PKCS7_InitWithCert
 141*/
 142int  wc_PKCS7_EncodeData(wc_PKCS7* pkcs7, byte* output,
 143                                       word32 outputSz);
 144
 145/*!
 146    \ingroup PKCS7
 147
 148    \brief This function builds the PKCS7 signed data content type, encoding
 149    the PKCS7 structure into a buffer containing a parsable PKCS7
 150    signed data packet. For RSA-PSS signers (WC_RSA_PSS), see \ref PKCS7_RSA_PSS.
 151
 152    \return Success On successfully encoding the PKCS7 data into the buffer,
 153    returns the index parsed up to in the PKCS7 structure. This index also
 154    corresponds to the bytes written to the output buffer.
 155    \return BAD_FUNC_ARG Returned if the PKCS7 structure is missing one or
 156    more required elements to generate a signed data packet
 157    \return MEMORY_E Returned if there is an error allocating memory
 158    \return PUBLIC_KEY_E Returned if there is an error parsing the public key
 159    \return RSA_BUFFER_E Returned if buffer error, output too small or input
 160    too large
 161    \return BUFFER_E Returned if the given buffer is not large enough to hold
 162    the encoded certificate
 163    \return MP_INIT_E may be returned if there is an error generating
 164    the signature
 165    \return MP_READ_E may be returned if there is an error generating
 166    the signature
 167    \return MP_CMP_E may be returned if there is an error generating
 168    the signature
 169    \return MP_INVMOD_E may be returned if there is an error generating
 170    the signature
 171    \return MP_EXPTMOD_E may be returned if there is an error generating
 172    the signature
 173    \return MP_MOD_E may be returned if there is an error generating
 174    the signature
 175    \return MP_MUL_E may be returned if there is an error generating
 176    the signature
 177    \return MP_ADD_E may be returned if there is an error generating
 178    the signature
 179    \return MP_MULMOD_E may be returned if there is an error generating
 180    the signature
 181    \return MP_TO_E may be returned if there is an error generating
 182    the signature
 183    \return MP_MEM may be returned if there is an error generating the signature
 184
 185    \param pkcs7 pointer to the PKCS7 structure to encode
 186    \param output pointer to the buffer in which to store the
 187    encoded certificate
 188    \param outputSz size available in the output buffer
 189
 190    _Example_
 191    \code
 192    PKCS7 pkcs7;
 193    int ret;
 194
 195    byte data[] = {}; // initialize with data to sign
 196    byte derBuff[] = { }; // initialize with DER-encoded certificate
 197    byte pkcs7Buff[FOURK_BUF];
 198
 199    wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
 200    // update message and data to encode
 201    pkcs7.privateKey = key;
 202    pkcs7.privateKeySz = keySz;
 203    pkcs7.content = data;
 204    pkcs7.contentSz = dataSz;
 205    pkcs7.hashOID = SHAh;
 206    pkcs7.rng = &rng;
 207    ... etc.
 208
 209    ret = wc_PKCS7_EncodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
 210    if ( ret != 0 ) {
 211    	// error encoding into output buffer
 212    }
 213
 214    wc_PKCS7_Free(&pkcs7);
 215    \endcode
 216
 217    \sa wc_PKCS7_InitWithCert
 218    \sa wc_PKCS7_VerifySignedData
 219*/
 220int  wc_PKCS7_EncodeSignedData(wc_PKCS7* pkcs7,
 221                                       byte* output, word32 outputSz);
 222
 223/*!
 224    \ingroup PKCS7
 225
 226    \brief This function builds the PKCS7 signed data content type, encoding
 227    the PKCS7 structure into a header and footer buffer containing a parsable PKCS7
 228    signed data packet. This does not include the content.
 229    A hash must be computed and provided for the data
 230
 231    \return 0=Success
 232    \return BAD_FUNC_ARG Returned if the PKCS7 structure is missing one or
 233    more required elements to generate a signed data packet
 234    \return MEMORY_E Returned if there is an error allocating memory
 235    \return PUBLIC_KEY_E Returned if there is an error parsing the public key
 236    \return RSA_BUFFER_E Returned if buffer error, output too small or input
 237    too large
 238    \return BUFFER_E Returned if the given buffer is not large enough to hold
 239    the encoded certificate
 240    \return MP_INIT_E may be returned if there is an error generating
 241    the signature
 242    \return MP_READ_E may be returned if there is an error generating
 243    the signature
 244    \return MP_CMP_E may be returned if there is an error generating
 245    the signature
 246    \return MP_INVMOD_E may be returned if there is an error generating
 247    the signature
 248    \return MP_EXPTMOD_E may be returned if there is an error generating
 249    the signature
 250    \return MP_MOD_E may be returned if there is an error generating
 251    the signature
 252    \return MP_MUL_E may be returned if there is an error generating
 253    the signature
 254    \return MP_ADD_E may be returned if there is an error generating
 255    the signature
 256    \return MP_MULMOD_E may be returned if there is an error generating
 257    the signature
 258    \return MP_TO_E may be returned if there is an error generating
 259    the signature
 260    \return MP_MEM may be returned if there is an error generating the signature
 261
 262    \param pkcs7 pointer to the PKCS7 structure to encode
 263    \param hashBuf pointer to computed hash for the content data
 264    \param hashSz size of the digest
 265    \param outputHead pointer to the buffer in which to store the
 266    encoded certificate header
 267    \param outputHeadSz pointer populated with size of output header buffer
 268    and returns actual size
 269    \param outputFoot pointer to the buffer in which to store the
 270    encoded certificate footer
 271    \param outputFootSz pointer populated with size of output footer buffer
 272    and returns actual size
 273
 274    _Example_
 275    \code
 276    PKCS7 pkcs7;
 277    int ret;
 278    byte derBuff[] = { }; // initialize with DER-encoded certificate
 279    byte data[] = {}; // initialize with data to sign
 280    byte pkcs7HeadBuff[FOURK_BUF/2];
 281    byte pkcs7FootBuff[FOURK_BUF/2];
 282    word32 pkcs7HeadSz = (word32)sizeof(pkcs7HeadBuff);
 283    word32 pkcs7FootSz = (word32)sizeof(pkcs7HeadBuff);
 284    enum wc_HashType hashType = WC_HASH_TYPE_SHA;
 285    byte   hashBuf[WC_MAX_DIGEST_SIZE];
 286    word32 hashSz = wc_HashGetDigestSize(hashType);
 287
 288    wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
 289    // update message and data to encode
 290    pkcs7.privateKey = key;
 291    pkcs7.privateKeySz = keySz;
 292    pkcs7.content = NULL;
 293    pkcs7.contentSz = dataSz;
 294    pkcs7.hashOID = SHAh;
 295    pkcs7.rng = &rng;
 296    ... etc.
 297
 298    // calculate hash for content
 299    ret = wc_HashInit(&hash, hashType);
 300    if (ret == 0) {
 301        ret = wc_HashUpdate(&hash, hashType, data, sizeof(data));
 302        if (ret == 0) {
 303            ret = wc_HashFinal(&hash, hashType, hashBuf);
 304        }
 305        wc_HashFree(&hash, hashType);
 306    }
 307
 308    ret = wc_PKCS7_EncodeSignedData_ex(&pkcs7, hashBuf, hashSz, pkcs7HeadBuff,
 309        &pkcs7HeadSz, pkcs7FootBuff, &pkcs7FootSz);
 310    if ( ret != 0 ) {
 311        // error encoding into output buffer
 312    }
 313
 314    wc_PKCS7_Free(&pkcs7);
 315    \endcode
 316
 317    \sa wc_PKCS7_InitWithCert
 318    \sa wc_PKCS7_VerifySignedData_ex
 319*/
 320int wc_PKCS7_EncodeSignedData_ex(wc_PKCS7* pkcs7, const byte* hashBuf,
 321    word32 hashSz, byte* outputHead, word32* outputHeadSz, byte* outputFoot,
 322    word32* outputFootSz);
 323
 324/*!
 325    \ingroup PKCS7
 326
 327    \brief This function takes in a transmitted PKCS7 signed data message,
 328    extracts the certificate list and certificate revocation list, and then
 329    verifies the signature. It stores the extracted content in the given
 330    PKCS7 structure.
 331
 332    \return 0 Returned on successfully extracting the information
 333    from the message
 334    \return BAD_FUNC_ARG Returned if one of the input parameters is invalid
 335    \return ASN_PARSE_E Returned if there is an error parsing the given pkiMsg
 336    \return PKCS7_OID_E Returned if the given pkiMsg is not a signed data type
 337    \return ASN_VERSION_E Returned if the PKCS7 signer info is not version 1
 338    \return MEMORY_E Returned if there is an error allocating memory
 339    \return PUBLIC_KEY_E Returned if there is an error parsing the public key
 340    \return RSA_BUFFER_E Returned if buffer error, output too small or
 341    input too large
 342    \return BUFFER_E Returned if the given buffer is not large enough to
 343    hold the encoded certificate
 344    \return MP_INIT_E may be returned if there is an error generating
 345    the signature
 346    \return MP_READ_E may be returned if there is an error generating
 347    the signature
 348    \return MP_CMP_E may be returned if there is an error generating
 349    the signature
 350    \return MP_INVMOD_E may be returned if there is an error generating
 351    the signature
 352    \return MP_EXPTMOD_E may be returned if there is an error generating
 353    the signature
 354    \return MP_MOD_E may be returned if there is an error generating
 355    the signature
 356    \return MP_MUL_E may be returned if there is an error generating
 357    the signature
 358    \return MP_ADD_E may be returned if there is an error generating
 359    the signature
 360    \return MP_MULMOD_E may be returned if there is an error generating
 361    the signature
 362    \return MP_TO_E may be returned if there is an error generating
 363    the signature
 364    \return MP_MEM may be returned if there is an error generating the signature
 365
 366    \param pkcs7 pointer to the PKCS7 structure in which to store the parsed
 367    certificates
 368    \param pkiMsg pointer to the buffer containing the signed message to verify
 369    and decode
 370    \param pkiMsgSz size of the signed message
 371
 372    _Example_
 373    \code
 374    PKCS7 pkcs7;
 375    int ret;
 376    byte pkcs7Buff[] = {}; // the PKCS7 signature
 377
 378    wc_PKCS7_InitWithCert(&pkcs7, NULL, 0);
 379    // update message and data to encode
 380    pkcs7.privateKey = key;
 381    pkcs7.privateKeySz = keySz;
 382    pkcs7.content = data;
 383    pkcs7.contentSz = dataSz;
 384    ... etc.
 385
 386    ret = wc_PKCS7_VerifySignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
 387    if ( ret != 0 ) {
 388    	// error encoding into output buffer
 389    }
 390
 391    wc_PKCS7_Free(&pkcs7);
 392    \endcode
 393
 394    \sa wc_PKCS7_InitWithCert
 395    \sa wc_PKCS7_EncodeSignedData
 396*/
 397int  wc_PKCS7_VerifySignedData(wc_PKCS7* pkcs7,
 398                                       byte* pkiMsg, word32 pkiMsgSz);
 399
 400
 401/*!
 402    \ingroup PKCS7
 403
 404    \brief This function takes in a transmitted PKCS7 signed data message as
 405    hash/header/footer, then extracts the certificate list and certificate
 406    revocation list, and then verifies the signature. It stores the extracted
 407    content in the given PKCS7 structure.
 408
 409    \return 0 Returned on successfully extracting the information
 410    from the message
 411    \return BAD_FUNC_ARG Returned if one of the input parameters is invalid
 412    \return ASN_PARSE_E Returned if there is an error parsing the given pkiMsg
 413    \return PKCS7_OID_E Returned if the given pkiMsg is not a signed data type
 414    \return ASN_VERSION_E Returned if the PKCS7 signer info is not version 1
 415    \return MEMORY_E Returned if there is an error allocating memory
 416    \return PUBLIC_KEY_E Returned if there is an error parsing the public key
 417    \return RSA_BUFFER_E Returned if buffer error, output too small or
 418    input too large
 419    \return BUFFER_E Returned if the given buffer is not large enough to
 420    hold the encoded certificate
 421    \return MP_INIT_E may be returned if there is an error generating
 422    the signature
 423    \return MP_READ_E may be returned if there is an error generating
 424    the signature
 425    \return MP_CMP_E may be returned if there is an error generating
 426    the signature
 427    \return MP_INVMOD_E may be returned if there is an error generating
 428    the signature
 429    \return MP_EXPTMOD_E may be returned if there is an error generating
 430    the signature
 431    \return MP_MOD_E may be returned if there is an error generating
 432    the signature
 433    \return MP_MUL_E may be returned if there is an error generating
 434    the signature
 435    \return MP_ADD_E may be returned if there is an error generating
 436    the signature
 437    \return MP_MULMOD_E may be returned if there is an error generating
 438    the signature
 439    \return MP_TO_E may be returned if there is an error generating
 440    the signature
 441    \return MP_MEM may be returned if there is an error generating the signature
 442
 443    \param pkcs7 pointer to the PKCS7 structure in which to store the parsed
 444    certificates
 445    \param hashBuf pointer to computed hash for the content data
 446    \param hashSz size of the digest
 447    \param pkiMsgHead pointer to the buffer containing the signed message header
 448    to verify and decode
 449    \param pkiMsgHeadSz size of the signed message header
 450    \param pkiMsgFoot pointer to the buffer containing the signed message footer
 451    to verify and decode
 452    \param pkiMsgFootSz size of the signed message footer
 453
 454    _Example_
 455    \code
 456    PKCS7 pkcs7;
 457    int ret;
 458    byte data[] = {}; // initialize with data to sign
 459    byte pkcs7HeadBuff[] = {}; // initialize with PKCS7 header
 460    byte pkcs7FootBuff[] = {}; // initialize with PKCS7 footer
 461    enum wc_HashType hashType = WC_HASH_TYPE_SHA;
 462    byte   hashBuf[WC_MAX_DIGEST_SIZE];
 463    word32 hashSz = wc_HashGetDigestSize(hashType);
 464
 465    wc_PKCS7_InitWithCert(&pkcs7, NULL, 0);
 466    // update message and data to encode
 467    pkcs7.privateKey = key;
 468    pkcs7.privateKeySz = keySz;
 469    pkcs7.content = NULL;
 470    pkcs7.contentSz = dataSz;
 471    pkcs7.rng = &rng;
 472    ... etc.
 473
 474    // calculate hash for content
 475    ret = wc_HashInit(&hash, hashType);
 476    if (ret == 0) {
 477        ret = wc_HashUpdate(&hash, hashType, data, sizeof(data));
 478        if (ret == 0) {
 479            ret = wc_HashFinal(&hash, hashType, hashBuf);
 480        }
 481        wc_HashFree(&hash, hashType);
 482    }
 483
 484    ret = wc_PKCS7_VerifySignedData_ex(&pkcs7, hashBuf, hashSz, pkcs7HeadBuff,
 485        sizeof(pkcs7HeadBuff), pkcs7FootBuff, sizeof(pkcs7FootBuff));
 486    if ( ret != 0 ) {
 487        // error encoding into output buffer
 488    }
 489
 490    wc_PKCS7_Free(&pkcs7);
 491    \endcode
 492
 493    \sa wc_PKCS7_InitWithCert
 494    \sa wc_PKCS7_EncodeSignedData_ex
 495*/
 496int wc_PKCS7_VerifySignedData_ex(wc_PKCS7* pkcs7, const byte* hashBuf,
 497    word32 hashSz, byte* pkiMsgHead, word32 pkiMsgHeadSz, byte* pkiMsgFoot,
 498    word32 pkiMsgFootSz);
 499
 500/*!
 501    \ingroup PKCS7
 502
 503    \brief Set the callback function to be used to perform a custom AES key
 504    wrap/unwrap operation.
 505
 506    \retval 0 Callback function was set successfully
 507    \retval BAD_FUNC_ARG Parameter pkcs7 is NULL
 508
 509    \param pkcs7 pointer to the PKCS7 structure
 510    \param aesKeyWrapCb pointer to custom AES key wrap/unwrap function
 511*/
 512int wc_PKCS7_SetAESKeyWrapUnwrapCb(wc_PKCS7* pkcs7,
 513        CallbackAESKeyWrapUnwrap aesKeyWrapCb);
 514
 515/*!
 516    \ingroup PKCS7
 517
 518    \brief This function builds the PKCS7 enveloped data content type, encoding
 519    the PKCS7 structure into a buffer containing a parsable PKCS7 enveloped
 520    data packet.
 521
 522    \return Success Returned on successfully encoding the message in enveloped
 523    data format, returns the size written to the output buffer
 524    \return BAD_FUNC_ARG: Returned if one of the input parameters is invalid,
 525    or if the PKCS7 structure is missing required elements
 526    \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported
 527    algorithm type. Currently, only DESb and DES3b are supported
 528    \return BUFFER_E Returned if the given output buffer is too small to store
 529    the output data
 530    \return MEMORY_E Returned if there is an error allocating memory
 531    \return RNG_FAILURE_E Returned if there is an error initializing the random
 532    number generator for encryption
 533    \return DRBG_FAILED Returned if there is an error generating numbers with
 534    the random number generator used for encryption
 535    \return NOT_COMPILED_IN may be returned if using an ECC key and wolfssl was
 536    built without HAVE_X963_KDF support
 537
 538    \param pkcs7 pointer to the PKCS7 structure to encode
 539    \param output pointer to the buffer in which to store the encoded
 540    certificate
 541    \param outputSz size available in the output buffer
 542
 543    _Example_
 544    \code
 545    PKCS7 pkcs7;
 546    int ret;
 547
 548    byte derBuff[] = { }; // initialize with DER-encoded certificate
 549    byte pkcs7Buff[FOURK_BUF];
 550
 551    wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
 552    // update message and data to encode
 553    pkcs7.privateKey = key;
 554    pkcs7.privateKeySz = keySz;
 555    pkcs7.content = data;
 556    pkcs7.contentSz = dataSz;
 557    ... etc.
 558
 559    ret = wc_PKCS7_EncodeEnvelopedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
 560    if ( ret < 0 ) {
 561    	// error encoding into output buffer
 562    }
 563    \endcode
 564
 565    \sa wc_PKCS7_InitWithCert
 566    \sa wc_PKCS7_DecodeEnvelopedData
 567*/
 568int  wc_PKCS7_EncodeEnvelopedData(wc_PKCS7* pkcs7,
 569                                          byte* output, word32 outputSz);
 570
 571/*!
 572    \ingroup PKCS7
 573
 574    \brief This function unwraps and decrypts a PKCS7 enveloped data content
 575    type, decoding the message into output. It uses the private key of the
 576    PKCS7 object passed in to decrypt the message.
 577
 578    Note that if the EnvelopedData is encrypted using an ECC key and the
 579    KeyAgreementRecipientInfo structure, then either the HAVE_AES_KEYWRAP
 580    build option should be enabled to enable the wolfcrypt built-in AES key
 581    wrap/unwrap functionality, or a custom AES key wrap/unwrap callback should
 582    be set with wc_PKCS7_SetAESKeyWrapUnwrapCb(). If neither of these is true,
 583    decryption will fail.
 584
 585    \return On successfully extracting the information from the message,
 586    returns the bytes written to output
 587    \return BAD_FUNC_ARG Returned if one of the input parameters is invalid
 588    \return ASN_PARSE_E Returned if there is an error parsing the given pkiMsg
 589    \return PKCS7_OID_E Returned if the given pkiMsg is not an enveloped
 590    data type
 591    \return ASN_VERSION_E Returned if the PKCS7 signer info is not version 0
 592    \return MEMORY_E Returned if there is an error allocating memory
 593    \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported
 594    algorithm type. Currently, only DESb and DES3b are supported for
 595    encryption, with RSAk for signature generation
 596    \return PKCS7_RECIP_E Returned if there is no recipient found in the
 597    enveloped data that matches the recipient provided
 598    \return RSA_BUFFER_E Returned if there is an error during RSA signature
 599    verification due to buffer error, output too small or input too large.
 600    \return MP_INIT_E may be returned if there is an error during signature
 601    verification
 602    \return MP_READ_E may be returned if there is an error during signature
 603    verification
 604    \return MP_CMP_E may be returned if there is an error during signature
 605    verification
 606    \return MP_INVMOD_E may be returned if there is an error during signature
 607    verification
 608    \return MP_EXPTMOD_E may be returned if there is an error during signature
 609    verification
 610    \return MP_MOD_E may be returned if there is an error during signature
 611    verification
 612    \return MP_MUL_E may be returned if there is an error during signature
 613    verification
 614    \return MP_ADD_E may be returned if there is an error during signature
 615    verification
 616    \return MP_MULMOD_E may be returned if there is an error during signature
 617    verification
 618    \return MP_TO_E may be returned if there is an error during signature
 619    verification
 620    \return MP_MEM may be returned if there is an error during signature
 621    verification
 622    \return NOT_COMPILED_IN may be returned if the EnvelopedData is encrypted
 623    using an ECC key and wolfssl was built without HAVE_X963_KDF support
 624
 625    \param pkcs7 pointer to the PKCS7 structure containing the private key with
 626    which to decode the enveloped data package
 627    \param pkiMsg pointer to the buffer containing the enveloped data package
 628    \param pkiMsgSz size of the enveloped data package
 629    \param output pointer to the buffer in which to store the decoded message
 630    \param outputSz size available in the output buffer
 631
 632    _Example_
 633    \code
 634    PKCS7 pkcs7;
 635    byte received[] = { }; // initialize with received enveloped message
 636    byte decoded[FOURK_BUF];
 637    int decodedSz;
 638
 639    // initialize pkcs7 with certificate
 640    // update key
 641    pkcs7.privateKey = key;
 642    pkcs7.privateKeySz = keySz;
 643
 644    decodedSz = wc_PKCS7_DecodeEnvelopedData(&pkcs7, received,
 645        sizeof(received),decoded, sizeof(decoded));
 646    if ( decodedSz < 0 ) {
 647        // error decoding message
 648    }
 649    \endcode
 650
 651    \sa wc_PKCS7_InitWithCert
 652    \sa wc_PKCS7_EncodeEnvelopedData
 653*/
 654int wc_PKCS7_DecodeEnvelopedData(wc_PKCS7* pkcs7, byte* pkiMsg,
 655        word32 pkiMsgSz, byte* output, word32 outputSz);
 656
 657/*!
 658    \ingroup PKCS7
 659
 660    \brief This function extracts the KeyAgreeRecipientIdentifier object from
 661    an EnvelopedData package containing a KeyAgreeRecipientInfo RecipientInfo
 662    object. Only the first KeyAgreeRecipientIdentifer found in the first
 663    RecipientInfo is copied. This function does not support multiple
 664    RecipientInfo objects or multiple RecipientEncryptedKey objects within an
 665    KeyAgreeRecipientInfo.
 666
 667    \return Returns 0 on success.
 668    \return BAD_FUNC_ARG Returned if one of the input parameters is invalid.
 669    \return ASN_PARSE_E Returned if there is an error parsing the input message.
 670    \return PKCS7_OID_E Returned if the input message is not an enveloped
 671    data type.
 672    \return BUFFER_E Returned if there is not enough room in the output buffer.
 673
 674    \param[in] in Input buffer containing the EnvelopedData ContentInfo message.
 675    \param[in] inSz Size of the input buffer.
 676    \param[out] out Output buffer.
 677    \param[in,out] outSz Output buffer size on input, Size written on output.
 678*/
 679int wc_PKCS7_GetEnvelopedDataKariRid(const byte * in, word32 inSz,
 680        byte * out, word32 * outSz);
 681
 682/*!
 683    \ingroup PKCS7
 684
 685    \brief This function unwraps and decrypts a PKCS7 encrypted data content
 686    type, decoding the message into output. It uses the encryption key of the
 687    PKCS7 object passed in via pkcs7->encryptionKey and
 688    pkcs7->encryptionKeySz to decrypt the message.
 689
 690    \return On successfully extracting the information from the message,
 691    returns the bytes written to output
 692    \return BAD_FUNC_ARG Returned if one of the input parameters is invalid
 693    \return ASN_PARSE_E Returned if there is an error parsing the given pkiMsg
 694    \return PKCS7_OID_E Returned if the given pkiMsg is not an encrypted
 695    data type
 696    \return ASN_VERSION_E Returned if the PKCS7 signer info is not version 0
 697    \return MEMORY_E Returned if there is an error allocating memory
 698    \return BUFFER_E Returned if the encrypted content size is invalid
 699
 700    \param pkcs7 pointer to the PKCS7 structure containing the encryption key with
 701    which to decode the encrypted data package
 702    \param pkiMsg pointer to the buffer containing the encrypted data package
 703    \param pkiMsgSz size of the encrypted data package
 704    \param output pointer to the buffer in which to store the decoded message
 705    \param outputSz size available in the output buffer
 706
 707    _Example_
 708    \code
 709    PKCS7 pkcs7;
 710    byte received[] = { }; // initialize with received encrypted data message
 711    byte decoded[FOURK_BUF];
 712    int decodedSz;
 713
 714    // initialize pkcs7 with certificate
 715    // update key
 716    pkcs7.encryptionKey = key;
 717    pkcs7.encryptionKeySz = keySz;
 718
 719    decodedSz = wc_PKCS7_DecodeEncryptedData(&pkcs7, received,
 720        sizeof(received), decoded, sizeof(decoded));
 721    if ( decodedSz < 0 ) {
 722        // error decoding message
 723    }
 724    \endcode
 725
 726    \sa wc_PKCS7_InitWithCert
 727*/
 728int wc_PKCS7_DecodeEncryptedData(wc_PKCS7* pkcs7, byte* pkiMsg,
 729        word32 pkiMsgSz, byte* output, word32 outputSz);
 730
 731/*!
 732    \ingroup PKCS7
 733
 734    \brief This function unwraps and decrypts a PKCS7 encrypted key package
 735    content type, decoding the message into output. If the wrapped content
 736    type is EncryptedData, the encryption key must be set in the pkcs7 input
 737    structure (via pkcs7->encryptionKey and pkcs7->encryptionKeySz). If the
 738    wrapped content type is EnvelopedData, the private key must be set in the
 739    pkcs7 input structure (via pkcs7->privateKey and pkcs7->privateKeySz).
 740    A wrapped content type of AuthEnvelopedData is not currently supported.
 741
 742    This function will automatically call either wc_PKCS7_DecodeEnvelopedData()
 743    or wc_PKCS7_DecodeEncryptedData() depending on the wrapped content type.
 744    This function could also return any error code from either of those
 745    functions in addition to the error codes listed here.
 746
 747    \return On successfully extracting the information from the message,
 748    returns the bytes written to output
 749    \return BAD_FUNC_ARG Returned if one of the input parameters is invalid
 750    \return ASN_PARSE_E Returned if there is an error parsing the given pkiMsg
 751    or if the wrapped content type is EncryptedData and support for
 752    EncryptedData is not compiled in (e.g. NO_PKCS7_ENCRYPTED_DATA is set)
 753    \return PKCS7_OID_E Returned if the given pkiMsg is not an encrypted
 754    key package data type
 755
 756    \param pkcs7 pointer to the PKCS7 structure containing the private key or
 757    encryption key with which to decode the encrypted key package
 758    \param pkiMsg pointer to the buffer containing the encrypted key package message
 759    \param pkiMsgSz size of the encrypted key package message
 760    \param output pointer to the buffer in which to store the decoded output
 761    \param outputSz size available in the output buffer
 762
 763    _Example_
 764    \code
 765    PKCS7 pkcs7;
 766    byte received[] = { }; // initialize with received encrypted data message
 767    byte decoded[FOURK_BUF];
 768    int decodedSz;
 769
 770    // initialize pkcs7 with certificate
 771    // update key for expected EnvelopedData (example)
 772    pkcs7.privateKey = key;
 773    pkcs7.privateKeySz = keySz;
 774
 775    decodedSz = wc_PKCS7_DecodeEncryptedKeyPackage(&pkcs7, received,
 776        sizeof(received), decoded, sizeof(decoded));
 777    if ( decodedSz < 0 ) {
 778        // error decoding message
 779    }
 780    \endcode
 781
 782    \sa wc_PKCS7_InitWithCert
 783*/
 784int wc_PKCS7_DecodeEncryptedKeyPackage(wc_PKCS7 * pkcs7,
 785        byte * pkiMsg, word32 pkiMsgSz, byte * output, word32 outputSz);
 786
 787/*!
 788    \ingroup PKCS7
 789
 790    \brief This function provides access to a SymmetricKeyPackage attribute.
 791
 792    \return 0 The requested attribute has been successfully located.
 793    attr and attrSz output variables are populated with the address and size of
 794    the attribute. The attribute will be in the same buffer passed in via the
 795    skp input pointer.
 796    \return BAD_FUNC_ARG One of the input parameters is invalid.
 797    \return ASN_PARSE_E An error was encountered parsing the input object.
 798    \return BAD_INDEX_E The requested attribute index was invalid.
 799
 800    \param[in] skp Input buffer containing the SymmetricKeyPackage object.
 801    \param[in] skpSz Size of the SymmetricKeyPackage object.
 802    \param[in] index Index of the attribute to access.
 803    \param[out] attr Buffer in which to store the pointer to the requested
 804    attribute object.
 805    \param[out] attrSz Buffer in which to store the size of the requested
 806    attribute object.
 807*/
 808int wc_PKCS7_DecodeSymmetricKeyPackageAttribute(const byte * skp,
 809        word32 skpSz, size_t index, const byte ** attr, word32 * attrSz);
 810
 811/*!
 812    \ingroup PKCS7
 813
 814    \brief This function provides access to a SymmetricKeyPackage key.
 815
 816    \return 0 The requested key has been successfully located.
 817    key and keySz output variables are populated with the address and size of
 818    the key. The key will be in the same buffer passed in via the
 819    skp input pointer.
 820    \return BAD_FUNC_ARG One of the input parameters is invalid.
 821    \return ASN_PARSE_E An error was encountered parsing the input object.
 822    \return BAD_INDEX_E The requested key index was invalid.
 823
 824    \param[in] skp Input buffer containing the SymmetricKeyPackage object.
 825    \param[in] skpSz Size of the SymmetricKeyPackage object.
 826    \param[in] index Index of the key to access.
 827    \param[out] key Buffer in which to store the pointer to the requested
 828    key object.
 829    \param[out] keySz Buffer in which to store the size of the requested
 830    key object.
 831*/
 832int wc_PKCS7_DecodeSymmetricKeyPackageKey(const byte * skp,
 833        word32 skpSz, size_t index, const byte ** key, word32 * keySz);
 834
 835/*!
 836    \ingroup PKCS7
 837
 838    \brief This function provides access to a OneSymmetricKey attribute.
 839
 840    \return 0 The requested attribute has been successfully located.
 841    attr and attrSz output variables are populated with the address and size of
 842    the attribute. The attribute will be in the same buffer passed in via the
 843    osk input pointer.
 844    \return BAD_FUNC_ARG One of the input parameters is invalid.
 845    \return ASN_PARSE_E An error was encountered parsing the input object.
 846    \return BAD_INDEX_E The requested attribute index was invalid.
 847
 848    \param[in] osk Input buffer containing the OneSymmetricKey object.
 849    \param[in] oskSz Size of the OneSymmetricKey object.
 850    \param[in] index Index of the attribute to access.
 851    \param[out] attr Buffer in which to store the pointer to the requested
 852    attribute object.
 853    \param[out] attrSz Buffer in which to store the size of the requested
 854    attribute object.
 855*/
 856int wc_PKCS7_DecodeOneSymmetricKeyAttribute(const byte * osk,
 857        word32 oskSz, size_t index, const byte ** attr, word32 * attrSz);
 858
 859/*!
 860    \ingroup PKCS7
 861
 862    \brief This function provides access to a OneSymmetricKey key.
 863
 864    \return 0 The requested key has been successfully located.
 865    key and keySz output variables are populated with the address and size of
 866    the key. The key will be in the same buffer passed in via the
 867    osk input pointer.
 868    \return BAD_FUNC_ARG One of the input parameters is invalid.
 869    \return ASN_PARSE_E An error was encountered parsing the input object.
 870
 871    \param[in] osk Input buffer containing the OneSymmetricKey object.
 872    \param[in] oskSz Size of the OneSymmetricKey object.
 873    \param[out] key Buffer in which to store the pointer to the requested
 874    key object.
 875    \param[out] keySz Buffer in which to store the size of the requested
 876    key object.
 877*/
 878int wc_PKCS7_DecodeOneSymmetricKeyKey(const byte * osk,
 879        word32 oskSz, const byte ** key, word32 * keySz);
 880
 881/*!
 882    \ingroup PKCS7
 883    \brief Creates new PKCS7 structure.
 884
 885    \return Pointer to new PKCS7 structure on success
 886    \return NULL on error
 887
 888    \param none No parameters
 889
 890    _Example_
 891    \code
 892    PKCS7* pkcs7 = wolfSSL_PKCS7_new();
 893    if (pkcs7 != NULL) {
 894        // use pkcs7
 895        wolfSSL_PKCS7_free(pkcs7);
 896    }
 897    \endcode
 898
 899    \sa wolfSSL_PKCS7_free
 900*/
 901PKCS7* wolfSSL_PKCS7_new(void);
 902
 903/*!
 904    \ingroup PKCS7
 905    \brief Creates new PKCS7_SIGNED structure.
 906
 907    \return Pointer to new PKCS7_SIGNED structure on success
 908    \return NULL on error
 909
 910    \param none No parameters
 911
 912    _Example_
 913    \code
 914    PKCS7_SIGNED* p7 = wolfSSL_PKCS7_SIGNED_new();
 915    if (p7 != NULL) {
 916        // use p7
 917        wolfSSL_PKCS7_SIGNED_free(p7);
 918    }
 919    \endcode
 920
 921    \sa wolfSSL_PKCS7_SIGNED_free
 922*/
 923PKCS7_SIGNED* wolfSSL_PKCS7_SIGNED_new(void);
 924
 925/*!
 926    \ingroup PKCS7
 927    \brief Frees PKCS7 structure.
 928
 929    \return none No returns
 930
 931    \param p7 PKCS7 structure to free
 932
 933    _Example_
 934    \code
 935    PKCS7* pkcs7 = wolfSSL_PKCS7_new();
 936    wolfSSL_PKCS7_free(pkcs7);
 937    \endcode
 938
 939    \sa wolfSSL_PKCS7_new
 940*/
 941void wolfSSL_PKCS7_free(PKCS7* p7);
 942
 943/*!
 944    \ingroup PKCS7
 945    \brief Frees PKCS7_SIGNED structure.
 946
 947    \return none No returns
 948
 949    \param p7 PKCS7_SIGNED structure to free
 950
 951    _Example_
 952    \code
 953    PKCS7_SIGNED* p7 = wolfSSL_PKCS7_SIGNED_new();
 954    wolfSSL_PKCS7_SIGNED_free(p7);
 955    \endcode
 956
 957    \sa wolfSSL_PKCS7_SIGNED_new
 958*/
 959void wolfSSL_PKCS7_SIGNED_free(PKCS7_SIGNED* p7);
 960
 961/*!
 962    \ingroup PKCS7
 963    \brief Decodes DER-encoded PKCS7 structure.
 964
 965    \return Pointer to decoded PKCS7 structure on success
 966    \return NULL on error
 967
 968    \param p7 Pointer to PKCS7 pointer (can be NULL)
 969    \param in Pointer to DER-encoded data
 970    \param len Length of DER data
 971
 972    _Example_
 973    \code
 974    PKCS7* p7 = NULL;
 975    const unsigned char* der = ...; // DER data
 976    p7 = wolfSSL_d2i_PKCS7(&p7, &der, derLen);
 977    \endcode
 978
 979    \sa wolfSSL_i2d_PKCS7
 980*/
 981PKCS7* wolfSSL_d2i_PKCS7(PKCS7** p7, const unsigned char** in, int len);
 982
 983/*!
 984    \ingroup PKCS7
 985    \brief Decodes PKCS7 from BIO.
 986
 987    \return Pointer to decoded PKCS7 structure on success
 988    \return NULL on error
 989
 990    \param bio BIO to read from
 991    \param p7 Pointer to PKCS7 pointer (can be NULL)
 992
 993    _Example_
 994    \code
 995    WOLFSSL_BIO* bio = wolfSSL_BIO_new_file("pkcs7.der", "rb");
 996    PKCS7* p7 = wolfSSL_d2i_PKCS7_bio(bio, NULL);
 997    \endcode
 998
 999    \sa wolfSSL_i2d_PKCS7_bio
1000*/
1001PKCS7* wolfSSL_d2i_PKCS7_bio(WOLFSSL_BIO* bio, PKCS7** p7);
1002
1003/*!
1004    \ingroup PKCS7
1005    \brief Encodes PKCS7 to BIO.
1006
1007    \return Length written on success
1008    \return negative on error
1009
1010    \param bio BIO to write to
1011    \param p7 PKCS7 structure to encode
1012
1013    _Example_
1014    \code
1015    WOLFSSL_BIO* bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
1016    int ret = wolfSSL_i2d_PKCS7_bio(bio, p7);
1017    \endcode
1018
1019    \sa wolfSSL_d2i_PKCS7_bio
1020*/
1021int wolfSSL_i2d_PKCS7_bio(WOLFSSL_BIO *bio, PKCS7 *p7);
1022
1023/*!
1024    \ingroup PKCS7
1025    \brief Encodes PKCS7 to DER.
1026
1027    \return Length written on success
1028    \return negative on error
1029
1030    \param p7 PKCS7 structure to encode
1031    \param out Pointer to output buffer pointer
1032
1033    _Example_
1034    \code
1035    unsigned char* der = NULL;
1036    int len = wolfSSL_i2d_PKCS7(p7, &der);
1037    \endcode
1038
1039    \sa wolfSSL_d2i_PKCS7
1040*/
1041int wolfSSL_i2d_PKCS7(PKCS7 *p7, unsigned char **out);
1042
1043/*!
1044    \ingroup PKCS7
1045    \brief Creates signed PKCS7 message.
1046
1047    \return Pointer to signed PKCS7 structure on success
1048    \return NULL on error
1049
1050    \param signer Signer certificate
1051    \param pkey Private key
1052    \param certs Additional certificates
1053    \param in Input data BIO
1054    \param flags Operation flags
1055
1056    _Example_
1057    \code
1058    PKCS7* p7 = wolfSSL_PKCS7_sign(cert, pkey, NULL, bio, 0);
1059    \endcode
1060
1061    \sa wolfSSL_PKCS7_verify
1062*/
1063PKCS7* wolfSSL_PKCS7_sign(WOLFSSL_X509* signer, WOLFSSL_EVP_PKEY* pkey,
1064                          WOLFSSL_STACK* certs, WOLFSSL_BIO* in, int flags);
1065
1066/*!
1067    \ingroup PKCS7
1068    \brief Verifies signed PKCS7 message.
1069
1070    \return 1 on success
1071    \return 0 or negative on error
1072
1073    \param p7 PKCS7 structure to verify
1074    \param certs Certificate stack
1075    \param store Certificate store
1076    \param in Input data BIO
1077    \param out Output BIO
1078    \param flags Operation flags
1079
1080    _Example_
1081    \code
1082    int ret = wolfSSL_PKCS7_verify(p7, NULL, store, NULL, out, 0);
1083    \endcode
1084
1085    \sa wolfSSL_PKCS7_sign
1086*/
1087int wolfSSL_PKCS7_verify(PKCS7* p7, WOLFSSL_STACK* certs,
1088                         WOLFSSL_X509_STORE* store, WOLFSSL_BIO* in,
1089                         WOLFSSL_BIO* out, int flags);
1090
1091/*!
1092    \ingroup PKCS7
1093    \brief Finalizes PKCS7 structure with data.
1094
1095    \return 1 on success
1096    \return 0 or negative on error
1097
1098    \param pkcs7 PKCS7 structure
1099    \param in Input data BIO
1100    \param flags Operation flags
1101
1102    _Example_
1103    \code
1104    int ret = wolfSSL_PKCS7_final(pkcs7, bio, 0);
1105    \endcode
1106
1107    \sa wolfSSL_PKCS7_sign
1108*/
1109int wolfSSL_PKCS7_final(PKCS7* pkcs7, WOLFSSL_BIO* in, int flags);
1110
1111/*!
1112    \ingroup PKCS7
1113    \brief Encodes certificates into PKCS7.
1114
1115    \return 1 on success
1116    \return 0 or negative on error
1117
1118    \param p7 PKCS7 structure
1119    \param certs Certificate stack
1120    \param out Output BIO
1121
1122    _Example_
1123    \code
1124    int ret = wolfSSL_PKCS7_encode_certs(p7, certs, bio);
1125    \endcode
1126
1127    \sa wolfSSL_PKCS7_to_stack
1128*/
1129int wolfSSL_PKCS7_encode_certs(PKCS7* p7, WOLFSSL_STACK* certs,
1130                               WOLFSSL_BIO* out);
1131
1132/*!
1133    \ingroup PKCS7
1134    \brief Converts PKCS7 certificates to stack.
1135
1136    \return Pointer to certificate stack on success
1137    \return NULL on error
1138
1139    \param pkcs7 PKCS7 structure
1140
1141    _Example_
1142    \code
1143    WOLFSSL_STACK* certs = wolfSSL_PKCS7_to_stack(pkcs7);
1144    \endcode
1145
1146    \sa wolfSSL_PKCS7_encode_certs
1147*/
1148WOLFSSL_STACK* wolfSSL_PKCS7_to_stack(PKCS7* pkcs7);
1149
1150/*!
1151    \ingroup PKCS7
1152    \brief Gets signer certificates from PKCS7.
1153
1154    \return Pointer to signer certificate stack on success
1155    \return NULL on error
1156
1157    \param p7 PKCS7 structure
1158    \param certs Certificate stack
1159    \param flags Operation flags
1160
1161    _Example_
1162    \code
1163    WOLFSSL_STACK* signers = wolfSSL_PKCS7_get0_signers(p7, NULL, 0);
1164    \endcode
1165
1166    \sa wolfSSL_PKCS7_verify
1167*/
1168WOLFSSL_STACK* wolfSSL_PKCS7_get0_signers(PKCS7* p7, WOLFSSL_STACK* certs,
1169                                          int flags);
1170
1171/*!
1172    \ingroup PKCS7
1173    \brief Writes PKCS7 to BIO in PEM format.
1174
1175    \return 1 on success
1176    \return 0 or negative on error
1177
1178    \param bio Output BIO
1179    \param p7 PKCS7 structure
1180
1181    _Example_
1182    \code
1183    int ret = wolfSSL_PEM_write_bio_PKCS7(bio, p7);
1184    \endcode
1185
1186    \sa wolfSSL_SMIME_write_PKCS7
1187*/
1188int wolfSSL_PEM_write_bio_PKCS7(WOLFSSL_BIO* bio, PKCS7* p7);
1189
1190/*!
1191    \ingroup PKCS7
1192    \brief Reads S/MIME PKCS7 from BIO.
1193
1194    \return Pointer to PKCS7 structure on success
1195    \return NULL on error
1196
1197    \param in Input BIO
1198    \param bcont Pointer to content BIO pointer
1199
1200    _Example_
1201    \code
1202    WOLFSSL_BIO* cont = NULL;
1203    PKCS7* p7 = wolfSSL_SMIME_read_PKCS7(bio, &cont);
1204    \endcode
1205
1206    \sa wolfSSL_SMIME_write_PKCS7
1207*/
1208PKCS7* wolfSSL_SMIME_read_PKCS7(WOLFSSL_BIO* in, WOLFSSL_BIO** bcont);
1209
1210/*!
1211    \ingroup PKCS7
1212    \brief Writes PKCS7 to BIO in S/MIME format.
1213
1214    \return 1 on success
1215    \return 0 or negative on error
1216
1217    \param out Output BIO
1218    \param pkcs7 PKCS7 structure
1219    \param in Input data BIO
1220    \param flags Operation flags
1221
1222    _Example_
1223    \code
1224    int ret = wolfSSL_SMIME_write_PKCS7(out, pkcs7, in, 0);
1225    \endcode
1226
1227    \sa wolfSSL_SMIME_read_PKCS7
1228*/
1229int wolfSSL_SMIME_write_PKCS7(WOLFSSL_BIO* out, PKCS7* pkcs7,
1230                              WOLFSSL_BIO* in, int flags);
1231
1232/*!
1233    \ingroup PKCS7
1234    \brief Creates new wc_PKCS7 structure.
1235
1236    \return Pointer to new wc_PKCS7 structure on success
1237    \return NULL on error
1238
1239    \param heap Heap hint
1240    \param devId Device ID
1241
1242    _Example_
1243    \code
1244    wc_PKCS7* pkcs7 = wc_PKCS7_New(NULL, INVALID_DEVID);
1245    \endcode
1246
1247    \sa wc_PKCS7_Init
1248*/
1249wc_PKCS7* wc_PKCS7_New(void* heap, int devId);
1250
1251/*!
1252    \ingroup PKCS7
1253    \brief Sets unknown extension callback.
1254
1255    \return none No returns
1256
1257    \param pkcs7 PKCS7 structure
1258    \param cb Callback function
1259
1260    _Example_
1261    \code
1262    wc_PKCS7_SetUnknownExtCallback(pkcs7, myCallback);
1263    \endcode
1264
1265    \sa wc_PKCS7_Init
1266*/
1267void wc_PKCS7_SetUnknownExtCallback(wc_PKCS7* pkcs7,
1268                                    wc_UnknownExtCallback cb);
1269
1270/*!
1271    \ingroup PKCS7
1272    \brief Initializes wc_PKCS7 structure.
1273
1274    \return 0 on success
1275    \return negative on error
1276
1277    \param pkcs7 PKCS7 structure
1278    \param heap Heap hint
1279    \param devId Device ID
1280
1281    _Example_
1282    \code
1283    wc_PKCS7 pkcs7;
1284    int ret = wc_PKCS7_Init(&pkcs7, NULL, INVALID_DEVID);
1285    \endcode
1286
1287    \sa wc_PKCS7_New
1288*/
1289int wc_PKCS7_Init(wc_PKCS7* pkcs7, void* heap, int devId);
1290
1291/*!
1292    \ingroup PKCS7
1293    \brief Adds certificate to PKCS7.
1294
1295    \return 0 on success
1296    \return negative on error
1297
1298    \param pkcs7 PKCS7 structure
1299    \param der DER-encoded certificate
1300    \param derSz Certificate size
1301
1302    _Example_
1303    \code
1304    int ret = wc_PKCS7_AddCertificate(&pkcs7, cert, certSz);
1305    \endcode
1306
1307    \sa wc_PKCS7_Init
1308*/
1309int wc_PKCS7_AddCertificate(wc_PKCS7* pkcs7, byte* der, word32 derSz);
1310
1311/*!
1312    \ingroup PKCS7
1313    \brief Gets attribute value from PKCS7.
1314
1315    \return 0 on success
1316    \return negative on error
1317
1318    \param pkcs7 PKCS7 structure
1319    \param oid Attribute OID
1320    \param oidSz OID size
1321    \param out Output buffer
1322    \param outSz Output buffer size pointer
1323
1324    _Example_
1325    \code
1326    byte value[256];
1327    word32 valueSz = sizeof(value);
1328    int ret = wc_PKCS7_GetAttributeValue(&pkcs7, oid, oidSz, value,
1329                                         &valueSz);
1330    \endcode
1331
1332    \sa wc_PKCS7_Init
1333*/
1334int wc_PKCS7_GetAttributeValue(wc_PKCS7* pkcs7, const byte* oid,
1335                                word32 oidSz, byte* out, word32* outSz);
1336
1337/*!
1338    \ingroup PKCS7
1339    \brief Sets signer identifier type.
1340
1341    \return 0 on success
1342    \return negative on error
1343
1344    \param pkcs7 PKCS7 structure
1345    \param type Identifier type
1346
1347    _Example_
1348    \code
1349    int ret = wc_PKCS7_SetSignerIdentifierType(&pkcs7, CMS_SKID);
1350    \endcode
1351
1352    \sa wc_PKCS7_Init
1353*/
1354int wc_PKCS7_SetSignerIdentifierType(wc_PKCS7* pkcs7, int type);
1355
1356/*!
1357    \ingroup PKCS7
1358    \brief Sets content type.
1359
1360    \return 0 on success
1361    \return negative on error
1362
1363    \param pkcs7 PKCS7 structure
1364    \param contentType Content type OID
1365    \param sz OID size
1366
1367    _Example_
1368    \code
1369    int ret = wc_PKCS7_SetContentType(&pkcs7, DATA, sizeof(DATA));
1370    \endcode
1371
1372    \sa wc_PKCS7_Init
1373*/
1374int wc_PKCS7_SetContentType(wc_PKCS7* pkcs7, byte* contentType, word32 sz);
1375
1376/*!
1377    \ingroup PKCS7
1378    \brief Gets padding size for block cipher.
1379
1380    \return Padding size
1381
1382    \param inputSz Input size
1383    \param blockSz Block size
1384
1385    _Example_
1386    \code
1387    int padSz = wc_PKCS7_GetPadSize(dataSz, AES_BLOCK_SIZE);
1388    \endcode
1389
1390    \sa wc_PKCS7_PadData
1391*/
1392int wc_PKCS7_GetPadSize(word32 inputSz, word32 blockSz);
1393
1394/*!
1395    \ingroup PKCS7
1396    \brief Pads data for block cipher.
1397
1398    \return 0 on success
1399    \return negative on error
1400
1401    \param in Input data
1402    \param inSz Input size
1403    \param out Output buffer
1404    \param outSz Output buffer size
1405    \param blockSz Block size
1406
1407    _Example_
1408    \code
1409    int ret = wc_PKCS7_PadData(data, dataSz, padded, paddedSz,
1410                               AES_BLOCK_SIZE);
1411    \endcode
1412
1413    \sa wc_PKCS7_GetPadSize
1414*/
1415int wc_PKCS7_PadData(byte* in, word32 inSz, byte* out, word32 outSz,
1416                     word32 blockSz);
1417
1418/*!
1419    \ingroup PKCS7
1420    \brief Sets custom subject key identifier.
1421
1422    \return 0 on success
1423    \return negative on error
1424
1425    \param pkcs7 PKCS7 structure
1426    \param in SKID data
1427    \param inSz SKID size
1428
1429    _Example_
1430    \code
1431    int ret = wc_PKCS7_SetCustomSKID(&pkcs7, skid, skidSz);
1432    \endcode
1433
1434    \sa wc_PKCS7_Init
1435*/
1436int wc_PKCS7_SetCustomSKID(wc_PKCS7* pkcs7, const byte* in, word16 inSz);
1437
1438/*!
1439    \ingroup PKCS7
1440    \brief Sets detached signature flag.
1441
1442    \return 0 on success
1443    \return negative on error
1444
1445    \param pkcs7 PKCS7 structure
1446    \param flag Detached flag (1=detached, 0=attached)
1447
1448    _Example_
1449    \code
1450    int ret = wc_PKCS7_SetDetached(&pkcs7, 1);
1451    \endcode
1452
1453    \sa wc_PKCS7_Init
1454*/
1455int wc_PKCS7_SetDetached(wc_PKCS7* pkcs7, word16 flag);
1456
1457/*!
1458    \ingroup PKCS7
1459    \brief Disables default signed attributes.
1460
1461    \return 0 on success
1462    \return negative on error
1463
1464    \param pkcs7 PKCS7 structure
1465
1466    _Example_
1467    \code
1468    int ret = wc_PKCS7_NoDefaultSignedAttribs(&pkcs7);
1469    \endcode
1470
1471    \sa wc_PKCS7_SetDefaultSignedAttribs
1472*/
1473int wc_PKCS7_NoDefaultSignedAttribs(wc_PKCS7* pkcs7);
1474
1475/*!
1476    \ingroup PKCS7
1477    \brief Sets default signed attributes flag.
1478
1479    \return 0 on success
1480    \return negative on error
1481
1482    \param pkcs7 PKCS7 structure
1483    \param flag Default attributes flag
1484
1485    _Example_
1486    \code
1487    int ret = wc_PKCS7_SetDefaultSignedAttribs(&pkcs7, 1);
1488    \endcode
1489
1490    \sa wc_PKCS7_NoDefaultSignedAttribs
1491*/
1492int wc_PKCS7_SetDefaultSignedAttribs(wc_PKCS7* pkcs7, word16 flag);
1493
1494/*!
1495    \ingroup PKCS7
1496    \brief Allows degenerate PKCS7 (no signers).
1497
1498    \return none No returns
1499
1500    \param pkcs7 PKCS7 structure
1501    \param flag Allow degenerate flag
1502
1503    _Example_
1504    \code
1505    wc_PKCS7_AllowDegenerate(&pkcs7, 1);
1506    \endcode
1507
1508    \sa wc_PKCS7_Init
1509*/
1510void wc_PKCS7_AllowDegenerate(wc_PKCS7* pkcs7, word16 flag);
1511
1512/*!
1513    \ingroup PKCS7
1514    \brief Gets signer subject identifier.
1515
1516    \return 0 on success
1517    \return negative on error
1518
1519    \param pkcs7 PKCS7 structure
1520    \param out Output buffer
1521    \param outSz Output buffer size pointer
1522
1523    _Example_
1524    \code
1525    byte sid[256];
1526    word32 sidSz = sizeof(sid);
1527    int ret = wc_PKCS7_GetSignerSID(&pkcs7, sid, &sidSz);
1528    \endcode
1529
1530    \sa wc_PKCS7_Init
1531*/
1532int wc_PKCS7_GetSignerSID(wc_PKCS7* pkcs7, byte* out, word32* outSz);
1533
1534/*!
1535    \ingroup PKCS7
1536    \brief Encodes signed FirmwarePackageData.
1537
1538    \return Size of encoded data on success
1539    \return negative on error
1540
1541    \param pkcs7 PKCS7 structure
1542    \param privateKey Private key
1543    \param privateKeySz Private key size
1544    \param signOID Signature algorithm OID
1545    \param hashOID Hash algorithm OID
1546    \param content Content data
1547    \param contentSz Content size
1548    \param signedAttribs Signed attributes
1549    \param signedAttribsSz Signed attributes count
1550    \param output Output buffer
1551    \param outputSz Output buffer size
1552
1553    _Example_
1554    \code
1555    int ret = wc_PKCS7_EncodeSignedFPD(&pkcs7, key, keySz, RSAk, SHAh,
1556                                       data, dataSz, NULL, 0, out, outSz);
1557    \endcode
1558
1559    \sa wc_PKCS7_EncodeSignedData
1560*/
1561int wc_PKCS7_EncodeSignedFPD(wc_PKCS7* pkcs7, byte* privateKey,
1562                             word32 privateKeySz, int signOID, int hashOID,
1563                             byte* content, word32 contentSz,
1564                             PKCS7Attrib* signedAttribs,
1565                             word32 signedAttribsSz, byte* output,
1566                             word32 outputSz);
1567
1568/*!
1569    \ingroup PKCS7
1570    \brief Encodes signed encrypted FirmwarePackageData.
1571
1572    \return Size of encoded data on success
1573    \return negative on error
1574
1575    \param pkcs7 PKCS7 structure
1576    \param encryptKey Encryption key
1577    \param encryptKeySz Encryption key size
1578    \param privateKey Private key
1579    \param privateKeySz Private key size
1580    \param encryptOID Encryption algorithm OID
1581    \param signOID Signature algorithm OID
1582    \param hashOID Hash algorithm OID
1583    \param content Content data
1584    \param contentSz Content size
1585    \param unprotectedAttribs Unprotected attributes
1586    \param unprotectedAttribsSz Unprotected attributes count
1587    \param signedAttribs Signed attributes
1588    \param signedAttribsSz Signed attributes count
1589    \param output Output buffer
1590    \param outputSz Output buffer size
1591
1592    _Example_
1593    \code
1594    int ret = wc_PKCS7_EncodeSignedEncryptedFPD(&pkcs7, encKey, encKeySz,
1595                                                key, keySz, AES256CBCb,
1596                                                RSAk, SHAh, data, dataSz,
1597                                                NULL, 0, NULL, 0, out,
1598                                                outSz);
1599    \endcode
1600
1601    \sa wc_PKCS7_EncodeSignedFPD
1602*/
1603int wc_PKCS7_EncodeSignedEncryptedFPD(wc_PKCS7* pkcs7, byte* encryptKey,
1604                                     word32 encryptKeySz, byte* privateKey,
1605                                     word32 privateKeySz, int encryptOID,
1606                                     int signOID, int hashOID, byte* content,
1607                                     word32 contentSz,
1608                                     PKCS7Attrib* unprotectedAttribs,
1609                                     word32 unprotectedAttribsSz,
1610                                     PKCS7Attrib* signedAttribs,
1611                                     word32 signedAttribsSz, byte* output,
1612                                     word32 outputSz);
1613
1614/*!
1615    \ingroup PKCS7
1616    \brief Encodes signed compressed FirmwarePackageData.
1617
1618    \return Size of encoded data on success
1619    \return negative on error
1620
1621    \param pkcs7 PKCS7 structure
1622    \param privateKey Private key
1623    \param privateKeySz Private key size
1624    \param signOID Signature algorithm OID
1625    \param hashOID Hash algorithm OID
1626    \param content Content data
1627    \param contentSz Content size
1628    \param signedAttribs Signed attributes
1629    \param signedAttribsSz Signed attributes count
1630    \param output Output buffer
1631    \param outputSz Output buffer size
1632
1633    _Example_
1634    \code
1635    int ret = wc_PKCS7_EncodeSignedCompressedFPD(&pkcs7, key, keySz, RSAk,
1636                                                 SHAh, data, dataSz, NULL,
1637                                                 0, out, outSz);
1638    \endcode
1639
1640    \sa wc_PKCS7_EncodeSignedFPD
1641*/
1642int wc_PKCS7_EncodeSignedCompressedFPD(wc_PKCS7* pkcs7, byte* privateKey,
1643                                      word32 privateKeySz, int signOID,
1644                                      int hashOID, byte* content,
1645                                      word32 contentSz,
1646                                      PKCS7Attrib* signedAttribs,
1647                                      word32 signedAttribsSz, byte* output,
1648                                      word32 outputSz);
1649
1650/*!
1651    \ingroup PKCS7
1652    \brief Encodes signed encrypted compressed FirmwarePackageData.
1653
1654    \return Size of encoded data on success
1655    \return negative on error
1656
1657    \param pkcs7 PKCS7 structure
1658    \param encryptKey Encryption key
1659    \param encryptKeySz Encryption key size
1660    \param privateKey Private key
1661    \param privateKeySz Private key size
1662    \param encryptOID Encryption algorithm OID
1663    \param signOID Signature algorithm OID
1664    \param hashOID Hash algorithm OID
1665    \param content Content data
1666    \param contentSz Content size
1667    \param unprotectedAttribs Unprotected attributes
1668    \param unprotectedAttribsSz Unprotected attributes count
1669    \param signedAttribs Signed attributes
1670    \param signedAttribsSz Signed attributes count
1671    \param output Output buffer
1672    \param outputSz Output buffer size
1673
1674    _Example_
1675    \code
1676    int ret = wc_PKCS7_EncodeSignedEncryptedCompressedFPD(&pkcs7, encKey,
1677                                                          encKeySz, key,
1678                                                          keySz, AES256CBCb,
1679                                                          RSAk, SHAh, data,
1680                                                          dataSz, NULL, 0,
1681                                                          NULL, 0, out,
1682                                                          outSz);
1683    \endcode
1684
1685    \sa wc_PKCS7_EncodeSignedCompressedFPD
1686*/
1687int wc_PKCS7_EncodeSignedEncryptedCompressedFPD(wc_PKCS7* pkcs7,
1688                                               byte* encryptKey,
1689                                               word32 encryptKeySz,
1690                                               byte* privateKey,
1691                                               word32 privateKeySz,
1692                                               int encryptOID, int signOID,
1693                                               int hashOID, byte* content,
1694                                               word32 contentSz,
1695                                               PKCS7Attrib* unprotectedAttribs,
1696                                               word32 unprotectedAttribsSz,
1697                                               PKCS7Attrib* signedAttribs,
1698                                               word32 signedAttribsSz,
1699                                               byte* output, word32 outputSz);
1700
1701/*!
1702    \ingroup PKCS7
1703    \brief Adds KTRI recipient.
1704
1705    \return 0 on success
1706    \return negative on error
1707
1708    \param pkcs7 PKCS7 structure
1709    \param cert Recipient certificate
1710    \param certSz Certificate size
1711    \param options Options flags
1712
1713    _Example_
1714    \code
1715    int ret = wc_PKCS7_AddRecipient_KTRI(&pkcs7, cert, certSz, 0);
1716    \endcode
1717
1718    \sa wc_PKCS7_AddRecipient_KARI
1719*/
1720int wc_PKCS7_AddRecipient_KTRI(wc_PKCS7* pkcs7, const byte* cert,
1721                               word32 certSz, int options);
1722
1723/*!
1724    \ingroup PKCS7
1725    \brief Adds KARI recipient.
1726
1727    \return 0 on success
1728    \return negative on error
1729
1730    \param pkcs7 PKCS7 structure
1731    \param cert Recipient certificate
1732    \param certSz Certificate size
1733    \param keyWrapOID Key wrap algorithm OID
1734    \param keyAgreeOID Key agreement algorithm OID
1735    \param ukm User keying material
1736    \param ukmSz UKM size
1737    \param options Options flags
1738
1739    _Example_
1740    \code
1741    int ret = wc_PKCS7_AddRecipient_KARI(&pkcs7, cert, certSz, AES256_WRAP,
1742                                         dhSinglePass_stdDH_sha256kdf_scheme,
1743                                         NULL, 0, 0);
1744    \endcode
1745
1746    \sa wc_PKCS7_AddRecipient_KTRI
1747*/
1748int wc_PKCS7_AddRecipient_KARI(wc_PKCS7* pkcs7, const byte* cert,
1749                               word32 certSz, int keyWrapOID,
1750                               int keyAgreeOID, byte* ukm, word32 ukmSz,
1751                               int options);
1752
1753/*!
1754    \ingroup PKCS7
1755    \brief Sets encryption key.
1756
1757    \return 0 on success
1758    \return negative on error
1759
1760    \param pkcs7 PKCS7 structure
1761    \param key Encryption key
1762    \param keySz Key size
1763
1764    _Example_
1765    \code
1766    int ret = wc_PKCS7_SetKey(&pkcs7, key, keySz);
1767    \endcode
1768
1769    \sa wc_PKCS7_Init
1770*/
1771int wc_PKCS7_SetKey(wc_PKCS7* pkcs7, byte* key, word32 keySz);
1772
1773/*!
1774    \ingroup PKCS7
1775    \brief Adds KEKRI recipient.
1776
1777    \return 0 on success
1778    \return negative on error
1779
1780    \param pkcs7 PKCS7 structure
1781    \param keyWrapOID Key wrap algorithm OID
1782    \param kek Key encryption key
1783    \param kekSz KEK size
1784    \param keyID Key identifier
1785    \param keyIdSz Key ID size
1786    \param timePtr Time pointer
1787    \param otherOID Other OID
1788    \param otherOIDSz Other OID size
1789    \param other Other data
1790    \param otherSz Other data size
1791    \param options Options flags
1792
1793    _Example_
1794    \code
1795    int ret = wc_PKCS7_AddRecipient_KEKRI(&pkcs7, AES256_WRAP, kek, kekSz,
1796                                          keyId, keyIdSz, NULL, NULL, 0,
1797                                          NULL, 0, 0);
1798    \endcode
1799
1800    \sa wc_PKCS7_AddRecipient_KTRI
1801*/
1802int wc_PKCS7_AddRecipient_KEKRI(wc_PKCS7* pkcs7, int keyWrapOID, byte* kek,
1803                                word32 kekSz, byte* keyID, word32 keyIdSz,
1804                                void* timePtr, byte* otherOID,
1805                                word32 otherOIDSz, byte* other,
1806                                word32 otherSz, int options);
1807
1808/*!
1809    \ingroup PKCS7
1810    \brief Sets password for PWRI.
1811
1812    \return 0 on success
1813    \return negative on error
1814
1815    \param pkcs7 PKCS7 structure
1816    \param passwd Password
1817    \param pLen Password length
1818
1819    _Example_
1820    \code
1821    int ret = wc_PKCS7_SetPassword(&pkcs7, password, passwordLen);
1822    \endcode
1823
1824    \sa wc_PKCS7_AddRecipient_PWRI
1825*/
1826int wc_PKCS7_SetPassword(wc_PKCS7* pkcs7, byte* passwd, word32 pLen);
1827
1828/*!
1829    \ingroup PKCS7
1830    \brief Adds PWRI recipient.
1831
1832    \return 0 on success
1833    \return negative on error
1834
1835    \param pkcs7 PKCS7 structure
1836    \param passwd Password
1837    \param pLen Password length
1838    \param salt Salt
1839    \param saltSz Salt size
1840    \param kdfOID KDF algorithm OID
1841    \param prfOID PRF algorithm OID
1842    \param iterations Iteration count
1843    \param kekEncryptOID KEK encryption algorithm OID
1844    \param options Options flags
1845
1846    _Example_
1847    \code
1848    int ret = wc_PKCS7_AddRecipient_PWRI(&pkcs7, password, passwordLen,
1849                                         salt, saltSz, PBKDF2_OID, HMACh,
1850                                         10000, AES256CBCb, 0);
1851    \endcode
1852
1853    \sa wc_PKCS7_SetPassword
1854*/
1855int wc_PKCS7_AddRecipient_PWRI(wc_PKCS7* pkcs7, byte* passwd, word32 pLen,
1856                               byte* salt, word32 saltSz, int kdfOID,
1857                               int prfOID, int iterations,
1858                               int kekEncryptOID, int options);
1859
1860/*!
1861    \ingroup PKCS7
1862    \brief Sets originator encryption context.
1863
1864    \return 0 on success
1865    \return negative on error
1866
1867    \param pkcs7 PKCS7 structure
1868    \param ctx Context pointer
1869
1870    _Example_
1871    \code
1872    int ret = wc_PKCS7_SetOriEncryptCtx(&pkcs7, myContext);
1873    \endcode
1874
1875    \sa wc_PKCS7_SetOriDecryptCtx
1876*/
1877int wc_PKCS7_SetOriEncryptCtx(wc_PKCS7* pkcs7, void* ctx);
1878
1879/*!
1880    \ingroup PKCS7
1881    \brief Sets originator decryption context.
1882
1883    \return 0 on success
1884    \return negative on error
1885
1886    \param pkcs7 PKCS7 structure
1887    \param ctx Context pointer
1888
1889    _Example_
1890    \code
1891    int ret = wc_PKCS7_SetOriDecryptCtx(&pkcs7, myContext);
1892    \endcode
1893
1894    \sa wc_PKCS7_SetOriEncryptCtx
1895*/
1896int wc_PKCS7_SetOriDecryptCtx(wc_PKCS7* pkcs7, void* ctx);
1897
1898/*!
1899    \ingroup PKCS7
1900    \brief Sets originator decryption callback.
1901
1902    \return 0 on success
1903    \return negative on error
1904
1905    \param pkcs7 PKCS7 structure
1906    \param cb Callback function
1907
1908    _Example_
1909    \code
1910    int ret = wc_PKCS7_SetOriDecryptCb(&pkcs7, myDecryptCallback);
1911    \endcode
1912
1913    \sa wc_PKCS7_SetOriDecryptCtx
1914*/
1915int wc_PKCS7_SetOriDecryptCb(wc_PKCS7* pkcs7, CallbackOriDecrypt cb);
1916
1917/*!
1918    \ingroup PKCS7
1919    \brief Adds ORI recipient.
1920
1921    \return 0 on success
1922    \return negative on error
1923
1924    \param pkcs7 PKCS7 structure
1925    \param cb Originator encryption callback
1926    \param options Options flags
1927
1928    _Example_
1929    \code
1930    int ret = wc_PKCS7_AddRecipient_ORI(&pkcs7, myEncryptCallback, 0);
1931    \endcode
1932
1933    \sa wc_PKCS7_SetOriDecryptCb
1934*/
1935int wc_PKCS7_AddRecipient_ORI(wc_PKCS7* pkcs7, CallbackOriEncrypt cb,
1936                              int options);
1937
1938/*!
1939    \ingroup PKCS7
1940    \brief Sets CEK wrap callback.
1941
1942    \return 0 on success
1943    \return negative on error
1944
1945    \param pkcs7 PKCS7 structure
1946    \param wrapCEKCb Wrap CEK callback
1947
1948    _Example_
1949    \code
1950    int ret = wc_PKCS7_SetWrapCEKCb(&pkcs7, myWrapCEKCallback);
1951    \endcode
1952
1953    \sa wc_PKCS7_Init
1954*/
1955int wc_PKCS7_SetWrapCEKCb(wc_PKCS7* pkcs7, CallbackWrapCEK wrapCEKCb);
1956
1957/*!
1958    \ingroup PKCS7
1959    \brief Sets RSA sign raw digest callback.
1960
1961    \return 0 on success
1962    \return negative on error
1963
1964    \param pkcs7 PKCS7 structure
1965    \param cb Callback function
1966
1967    _Example_
1968    \code
1969    int ret = wc_PKCS7_SetRsaSignRawDigestCb(&pkcs7, mySignCallback);
1970    \endcode
1971
1972    \sa wc_PKCS7_Init
1973*/
1974int wc_PKCS7_SetRsaSignRawDigestCb(wc_PKCS7* pkcs7,
1975                                   CallbackRsaSignRawDigest cb);
1976
1977/*!
1978    \ingroup PKCS7
1979    \brief Encodes authenticated enveloped data.
1980
1981    \return Size of encoded data on success
1982    \return negative on error
1983
1984    \param pkcs7 PKCS7 structure
1985    \param output Output buffer
1986    \param outputSz Output buffer size
1987
1988    _Example_
1989    \code
1990    int ret = wc_PKCS7_EncodeAuthEnvelopedData(&pkcs7, out, outSz);
1991    \endcode
1992
1993    \sa wc_PKCS7_DecodeAuthEnvelopedData
1994*/
1995int wc_PKCS7_EncodeAuthEnvelopedData(wc_PKCS7* pkcs7, byte* output,
1996                                     word32 outputSz);
1997
1998/*!
1999    \ingroup PKCS7
2000    \brief Decodes authenticated enveloped data.
2001
2002    \return Size of decoded data on success
2003    \return negative on error
2004
2005    \param pkcs7 PKCS7 structure
2006    \param pkiMsg Input message
2007    \param pkiMsgSz Input message size
2008    \param output Output buffer
2009    \param outputSz Output buffer size
2010
2011    _Example_
2012    \code
2013    int ret = wc_PKCS7_DecodeAuthEnvelopedData(&pkcs7, msg, msgSz, out,
2014                                               outSz);
2015    \endcode
2016
2017    \sa wc_PKCS7_EncodeAuthEnvelopedData
2018*/
2019int wc_PKCS7_DecodeAuthEnvelopedData(wc_PKCS7* pkcs7, byte* pkiMsg,
2020                                     word32 pkiMsgSz, byte* output,
2021                                     word32 outputSz);
2022
2023/*!
2024    \ingroup PKCS7
2025    \brief Encodes encrypted data.
2026
2027    \return Size of encoded data on success
2028    \return negative on error
2029
2030    \param pkcs7 PKCS7 structure
2031    \param output Output buffer
2032    \param outputSz Output buffer size
2033
2034    _Example_
2035    \code
2036    int ret = wc_PKCS7_EncodeEncryptedData(&pkcs7, out, outSz);
2037    \endcode
2038
2039    \sa wc_PKCS7_DecodeEncryptedData
2040*/
2041int wc_PKCS7_EncodeEncryptedData(wc_PKCS7* pkcs7, byte* output,
2042                                 word32 outputSz);
2043
2044/*!
2045    \ingroup PKCS7
2046    \brief Sets decode encrypted callback.
2047
2048    \return 0 on success
2049    \return negative on error
2050
2051    \param pkcs7 PKCS7 structure
2052    \param decryptionCb Decryption callback
2053
2054    _Example_
2055    \code
2056    int ret = wc_PKCS7_SetDecodeEncryptedCb(&pkcs7, myDecryptCallback);
2057    \endcode
2058
2059    \sa wc_PKCS7_SetDecodeEncryptedCtx
2060*/
2061int wc_PKCS7_SetDecodeEncryptedCb(wc_PKCS7* pkcs7,
2062                                  CallbackDecryptContent decryptionCb);
2063
2064/*!
2065    \ingroup PKCS7
2066    \brief Sets decode encrypted context.
2067
2068    \return 0 on success
2069    \return negative on error
2070
2071    \param pkcs7 PKCS7 structure
2072    \param ctx Context pointer
2073
2074    _Example_
2075    \code
2076    int ret = wc_PKCS7_SetDecodeEncryptedCtx(&pkcs7, myContext);
2077    \endcode
2078
2079    \sa wc_PKCS7_SetDecodeEncryptedCb
2080*/
2081int wc_PKCS7_SetDecodeEncryptedCtx(wc_PKCS7* pkcs7, void* ctx);
2082
2083/*!
2084    \ingroup PKCS7
2085    \brief Sets stream mode for PKCS7.
2086
2087    \return 0 on success
2088    \return negative on error
2089
2090    \param pkcs7 PKCS7 structure
2091    \param flag Stream mode flag
2092    \param getContentCb Get content callback
2093    \param streamOutCb Stream output callback
2094    \param ctx Context pointer
2095
2096    _Example_
2097    \code
2098    int ret = wc_PKCS7_SetStreamMode(&pkcs7, 1, getContent, streamOut,
2099                                     ctx);
2100    \endcode
2101
2102    \sa wc_PKCS7_GetStreamMode
2103*/
2104int wc_PKCS7_SetStreamMode(wc_PKCS7* pkcs7, byte flag,
2105                           CallbackGetContent getContentCb,
2106                           CallbackStreamOut streamOutCb, void* ctx);
2107
2108/*!
2109    \ingroup PKCS7
2110    \brief Gets stream mode setting.
2111
2112    \return Stream mode flag
2113
2114    \param pkcs7 PKCS7 structure
2115
2116    _Example_
2117    \code
2118    int mode = wc_PKCS7_GetStreamMode(&pkcs7);
2119    \endcode
2120
2121    \sa wc_PKCS7_SetStreamMode
2122*/
2123int wc_PKCS7_GetStreamMode(wc_PKCS7* pkcs7);
2124
2125/*!
2126    \ingroup PKCS7
2127    \brief Sets no certificates flag.
2128
2129    \return 0 on success
2130    \return negative on error
2131
2132    \param pkcs7 PKCS7 structure
2133    \param flag No certificates flag
2134
2135    _Example_
2136    \code
2137    int ret = wc_PKCS7_SetNoCerts(&pkcs7, 1);
2138    \endcode
2139
2140    \sa wc_PKCS7_GetNoCerts
2141*/
2142int wc_PKCS7_SetNoCerts(wc_PKCS7* pkcs7, byte flag);
2143
2144/*!
2145    \ingroup PKCS7
2146    \brief Gets no certificates flag.
2147
2148    \return No certificates flag
2149
2150    \param pkcs7 PKCS7 structure
2151
2152    _Example_
2153    \code
2154    int noCerts = wc_PKCS7_GetNoCerts(&pkcs7);
2155    \endcode
2156
2157    \sa wc_PKCS7_SetNoCerts
2158*/
2159int wc_PKCS7_GetNoCerts(wc_PKCS7* pkcs7);
2160
2161/*!
2162    \ingroup PKCS7
2163    \brief Encodes compressed data.
2164
2165    \return Size of encoded data on success
2166    \return negative on error
2167
2168    \param pkcs7 PKCS7 structure
2169    \param output Output buffer
2170    \param outputSz Output buffer size
2171
2172    _Example_
2173    \code
2174    int ret = wc_PKCS7_EncodeCompressedData(&pkcs7, out, outSz);
2175    \endcode
2176
2177    \sa wc_PKCS7_DecodeCompressedData
2178*/
2179int wc_PKCS7_EncodeCompressedData(wc_PKCS7* pkcs7, byte* output,
2180                                  word32 outputSz);
2181
2182/*!
2183    \ingroup PKCS7
2184    \brief Decodes compressed data.
2185
2186    \return Size of decoded data on success
2187    \return negative on error
2188
2189    \param pkcs7 PKCS7 structure
2190    \param pkiMsg Input message
2191    \param pkiMsgSz Input message size
2192    \param output Output buffer
2193    \param outputSz Output buffer size
2194
2195    _Example_
2196    \code
2197    int ret = wc_PKCS7_DecodeCompressedData(&pkcs7, msg, msgSz, out,
2198                                            outSz);
2199    \endcode
2200
2201    \sa wc_PKCS7_EncodeCompressedData
2202*/
2203int wc_PKCS7_DecodeCompressedData(wc_PKCS7* pkcs7, byte* pkiMsg,
2204                                  word32 pkiMsgSz, byte* output,
2205                                  word32 outputSz);