luna - wolfssl/doc/dox_comments/header

    1/*!
    2    \brief This function initializes the DTLS v1.2 client method.
    3
    4    \return pointer This function returns a pointer to a new
    5    WOLFSSL_METHOD structure.
    6
    7    \param heap pointer to a heap hint for memory allocation.
    8
    9    _Example_
   10    \code
   11    wolfSSL_Init();
   12    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_client_method());
   13    …
   14    WOLFSSL* ssl = wolfSSL_new(ctx);
   15    …
   16    \endcode
   17
   18    \sa wolfSSL_Init
   19    \sa wolfSSL_CTX_new
   20*/
   21WOLFSSL_METHOD *wolfDTLSv1_2_client_method_ex(void* heap);
   22
   23/*!
   24    \ingroup Setup
   25
   26    \brief This function returns a WOLFSSL_METHOD similar to
   27    wolfSSLv23_client_method except that it is not determined
   28    which side yet (server/client).
   29
   30    \return WOLFSSL_METHOD* On successful creations returns a WOLFSSL_METHOD
   31    pointer
   32    \return NULL Null if memory allocation error or failure to create method
   33
   34    \param none No parameters.
   35
   36    _Example_
   37    \code
   38    WOLFSSL* ctx;
   39    ctx  = wolfSSL_CTX_new(wolfSSLv23_method());
   40    // check ret value
   41    \endcode
   42
   43    \sa wolfSSL_new
   44    \sa wolfSSL_free
   45*/
   46WOLFSSL_METHOD *wolfSSLv23_method(void);
   47
   48/*!
   49    \ingroup Setup
   50
   51    \brief The wolfSSLv3_server_method() function is used to indicate
   52    that the application is a server and will only support the SSL 3.0
   53    protocol.  This function allocates memory for and initializes a new
   54    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
   55    with wolfSSL_CTX_new().
   56
   57    \return * If successful, the call will return a pointer to the newly
   58    created WOLFSSL_METHOD structure.
   59    \return FAIL If memory allocation fails when calling XMALLOC, the
   60    failure value of the underlying malloc() implementation will be returned
   61    (typically NULL with errno will be set to ENOMEM).
   62
   63    \param none No parameters.
   64
   65    _Example_
   66    \code
   67    #include <wolfssl/ssl.h>
   68
   69    WOLFSSL_METHOD* method;
   70    WOLFSSL_CTX* ctx;
   71
   72    method = wolfSSLv3_server_method();
   73    if (method == NULL) {
   74	    unable to get method
   75    }
   76
   77    ctx = wolfSSL_CTX_new(method);
   78    ...
   79    \endcode
   80
   81    \sa wolfTLSv1_server_method
   82    \sa wolfTLSv1_1_server_method
   83    \sa wolfTLSv1_2_server_method
   84    \sa wolfTLSv1_3_server_method
   85    \sa wolfDTLSv1_server_method
   86    \sa wolfSSLv23_server_method
   87    \sa wolfSSL_CTX_new
   88
   89*/
   90WOLFSSL_METHOD *wolfSSLv3_server_method(void);
   91
   92/*!
   93    \ingroup Setup
   94
   95    \brief The wolfSSLv3_client_method() function is used to indicate
   96    that the application is a client and will only support the SSL 3.0
   97    protocol.  This function allocates memory for and initializes a
   98    new wolfSSL_METHOD structure to be used when creating the SSL/TLS
   99    context with wolfSSL_CTX_new().
  100
  101    \return * If successful, the call will return a pointer to the newly
  102    created WOLFSSL_METHOD structure.
  103    \return FAIL If memory allocation fails when calling XMALLOC, the
  104    failure value of the underlying malloc() implementation will be
  105    returned (typically NULL with errno will be set to ENOMEM).
  106
  107    \param none No parameters.
  108
  109    _Example_
  110    \code
  111    #include <wolfssl/ssl.h>
  112
  113    WOLFSSL_METHOD* method;
  114    WOLFSSL_CTX* ctx;
  115
  116    method = wolfSSLv3_client_method();
  117    if (method == NULL) {
  118	    unable to get method
  119    }
  120
  121    ctx = wolfSSL_CTX_new(method);
  122    ...
  123    \endcode
  124
  125    \sa wolfTLSv1_client_method
  126    \sa wolfTLSv1_1_client_method
  127    \sa wolfTLSv1_2_client_method
  128    \sa wolfTLSv1_3_client_method
  129    \sa wolfDTLSv1_client_method
  130    \sa wolfSSLv23_client_method
  131    \sa wolfSSL_CTX_new
  132*/
  133WOLFSSL_METHOD *wolfSSLv3_client_method(void);
  134
  135/*!
  136    \ingroup Setup
  137
  138    \brief The wolfTLSv1_server_method() function is used to indicate that the
  139    application is a server and will only support the TLS 1.0 protocol. This
  140    function allocates memory for and initializes a new wolfSSL_METHOD
  141    structure to be used when creating the SSL/TLS context with
  142    wolfSSL_CTX_new().
  143
  144    \return * If successful, the call will return a pointer to the newly
  145    created WOLFSSL_METHOD structure.
  146    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  147    value of the underlying malloc() implementation will be returned
  148    (typically NULL with errno will be set to ENOMEM).
  149
  150    \param none No parameters.
  151
  152    _Example_
  153    \code
  154    #include <wolfssl/ssl.h>
  155
  156    WOLFSSL_METHOD* method;
  157    WOLFSSL_CTX* ctx;
  158
  159    method = wolfTLSv1_server_method();
  160    if (method == NULL) {
  161	    unable to get method
  162    }
  163
  164    ctx = wolfSSL_CTX_new(method);
  165    ...
  166    \endcode
  167
  168    \sa wolfSSLv3_server_method
  169    \sa wolfTLSv1_1_server_method
  170    \sa wolfTLSv1_2_server_method
  171    \sa wolfTLSv1_3_server_method
  172    \sa wolfDTLSv1_server_method
  173    \sa wolfSSLv23_server_method
  174    \sa wolfSSL_CTX_new
  175*/
  176WOLFSSL_METHOD *wolfTLSv1_server_method(void);
  177
  178/*!
  179    \ingroup Setup
  180
  181    \brief The wolfTLSv1_client_method() function is used to indicate
  182    that the application is a client and will only support the TLS 1.0
  183    protocol.  This function allocates memory for and initializes a new
  184    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  185    with wolfSSL_CTX_new().
  186
  187    \return * If successful, the call will return a pointer to the newly
  188    created WOLFSSL_METHOD structure.
  189    \return FAIL If memory allocation fails when calling XMALLOC,
  190    the failure value of the underlying malloc() implementation
  191    will be returned (typically NULL with errno will be set to ENOMEM).
  192
  193    \param none No parameters.
  194
  195    _Example_
  196    \code
  197    #include <wolfssl/ssl.h>
  198
  199    WOLFSSL_METHOD* method;
  200    WOLFSSL_CTX* ctx;
  201
  202    method = wolfTLSv1_client_method();
  203    if (method == NULL) {
  204	    unable to get method
  205    }
  206
  207    ctx = wolfSSL_CTX_new(method);
  208    ...
  209    \endcode
  210
  211    \sa wolfSSLv3_client_method
  212    \sa wolfTLSv1_1_client_method
  213    \sa wolfTLSv1_2_client_method
  214    \sa wolfTLSv1_3_client_method
  215    \sa wolfDTLSv1_client_method
  216    \sa wolfSSLv23_client_method
  217    \sa wolfSSL_CTX_new
  218*/
  219WOLFSSL_METHOD *wolfTLSv1_client_method(void);
  220
  221/*!
  222    \ingroup Setup
  223
  224    \brief The wolfTLSv1_1_server_method() function is used to indicate
  225    that the application is a server and will only support the TLS 1.1
  226    protocol. This function allocates memory for and initializes a new
  227    wolfSSL_METHOD structure to be used when creating the SSL/TLS
  228    context with wolfSSL_CTX_new().
  229
  230    \return * If successful, the call will return a pointer to the newly
  231    created WOLFSSL_METHOD structure.
  232    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  233    value of the underlying malloc() implementation will be returned
  234    (typically NULL with errno will be set to ENOMEM).
  235
  236    \param none No parameters.
  237
  238    _Example_
  239    \code
  240    #include <wolfssl/ssl.h>
  241
  242    WOLFSSL_METHOD* method;
  243    WOLFSSL_CTX* ctx;
  244
  245    method = wolfTLSv1_1_server_method();
  246    if (method == NULL) {
  247        // unable to get method
  248    }
  249
  250    ctx = wolfSSL_CTX_new(method);
  251    ...
  252    \endcode
  253
  254    \sa wolfSSLv3_server_method
  255    \sa wolfTLSv1_server_method
  256    \sa wolfTLSv1_2_server_method
  257    \sa wolfTLSv1_3_server_method
  258    \sa wolfDTLSv1_server_method
  259    \sa wolfSSLv23_server_method
  260    \sa wolfSSL_CTX_new
  261*/
  262WOLFSSL_METHOD *wolfTLSv1_1_server_method(void);
  263
  264/*!
  265    \ingroup Setup
  266
  267    \brief The wolfTLSv1_1_client_method() function is used to indicate
  268    that the application is a client and will only support the TLS 1.0
  269    protocol. This function allocates memory for and initializes a
  270    new wolfSSL_METHOD structure to be used when creating the SSL/TLS
  271    context with wolfSSL_CTX_new().
  272
  273    \return * If successful, the call will return a pointer to the
  274    newly created WOLFSSL_METHOD structure.
  275    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  276    value of the underlying malloc() implementation will be returned
  277    (typically NULL with errno will be set to ENOMEM).
  278
  279    \param none No parameters.
  280
  281    _Example_
  282    \code
  283    #include <wolfssl/ssl.h>
  284
  285    WOLFSSL_METHOD* method;
  286    WOLFSSL_CTX* ctx;
  287
  288    method = wolfTLSv1_1_client_method();
  289    if (method == NULL) {
  290        // unable to get method
  291    }
  292
  293    ctx = wolfSSL_CTX_new(method);
  294    ...
  295    \endcode
  296
  297    \sa wolfSSLv3_client_method
  298    \sa wolfTLSv1_client_method
  299    \sa wolfTLSv1_2_client_method
  300    \sa wolfTLSv1_3_client_method
  301    \sa wolfDTLSv1_client_method
  302    \sa wolfSSLv23_client_method
  303    \sa wolfSSL_CTX_new
  304*/
  305WOLFSSL_METHOD *wolfTLSv1_1_client_method(void);
  306
  307/*!
  308    \ingroup Setup
  309
  310    \brief The wolfTLSv1_2_server_method() function is used to indicate
  311    that the application is a server and will only support the TLS 1.2
  312    protocol. This function allocates memory for and initializes a new
  313    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  314    with wolfSSL_CTX_new().
  315
  316    \return * If successful, the call will return a pointer to the newly
  317    created WOLFSSL_METHOD structure.
  318    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  319    value of the underlying malloc() implementation will be returned
  320    (typically NULL with errno will be set to ENOMEM).
  321
  322    \param none No parameters.
  323
  324    _Example_
  325    \code
  326    #include <wolfssl/ssl.h>
  327
  328    WOLFSSL_METHOD* method;
  329    WOLFSSL_CTX* ctx;
  330
  331    method = wolfTLSv1_2_server_method();
  332    if (method == NULL) {
  333	    // unable to get method
  334    }
  335
  336    ctx = wolfSSL_CTX_new(method);
  337    ...
  338    \endcode
  339
  340    \sa wolfSSLv3_server_method
  341    \sa wolfTLSv1_server_method
  342    \sa wolfTLSv1_1_server_method
  343    \sa wolfTLSv1_3_server_method
  344    \sa wolfDTLSv1_server_method
  345    \sa wolfSSLv23_server_method
  346    \sa wolfSSL_CTX_new
  347*/
  348WOLFSSL_METHOD *wolfTLSv1_2_server_method(void);
  349
  350/*!
  351    \ingroup Setup
  352
  353    \brief The wolfTLSv1_2_client_method() function is used to indicate
  354    that the application is a client and will only support the TLS 1.2
  355    protocol. This function allocates memory for and initializes a new
  356    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  357    with wolfSSL_CTX_new().
  358
  359    \return * If successful, the call will return a pointer to the newly
  360    created WOLFSSL_METHOD structure.
  361    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  362    value of the underlying malloc() implementation will be returned
  363    (typically NULL with errno will be set to ENOMEM).
  364
  365    \param none No parameters.
  366
  367    _Example_
  368    \code
  369    #include <wolfssl/ssl.h>
  370
  371    WOLFSSL_METHOD* method;
  372    WOLFSSL_CTX* ctx;
  373
  374    method = wolfTLSv1_2_client_method();
  375    if (method == NULL) {
  376	    // unable to get method
  377    }
  378
  379    ctx = wolfSSL_CTX_new(method);
  380    ...
  381    \endcode
  382
  383    \sa wolfSSLv3_client_method
  384    \sa wolfTLSv1_client_method
  385    \sa wolfTLSv1_1_client_method
  386    \sa wolfTLSv1_3_client_method
  387    \sa wolfDTLSv1_client_method
  388    \sa wolfSSLv23_client_method
  389    \sa wolfSSL_CTX_new
  390*/
  391WOLFSSL_METHOD *wolfTLSv1_2_client_method(void);
  392
  393/*!
  394    \ingroup Setup
  395
  396    \brief The wolfDTLSv1_client_method() function is used to indicate that
  397    the application is a client and will only support the DTLS 1.0 protocol.
  398    This function allocates memory for and initializes a new
  399    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  400    with wolfSSL_CTX_new(). This function is only available when wolfSSL has
  401    been compiled with DTLS support (--enable-dtls,
  402    or by defining wolfSSL_DTLS).
  403
  404    \return * If successful, the call will return a pointer to the newly
  405    created WOLFSSL_METHOD structure.
  406    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  407    value of the underlying malloc() implementation will be returned
  408    (typically NULL with errno will be set to ENOMEM).
  409
  410    \param none No parameters.
  411
  412    _Example_
  413    \code
  414    WOLFSSL_METHOD* method;
  415    WOLFSSL_CTX* ctx;
  416
  417    method = wolfDTLSv1_client_method();
  418    if (method == NULL) {
  419	    // unable to get method
  420    }
  421
  422    ctx = wolfSSL_CTX_new(method);
  423    ...
  424    \endcode
  425
  426    \sa wolfSSLv3_client_method
  427    \sa wolfTLSv1_client_method
  428    \sa wolfTLSv1_1_client_method
  429    \sa wolfTLSv1_2_client_method
  430    \sa wolfTLSv1_3_client_method
  431    \sa wolfSSLv23_client_method
  432    \sa wolfSSL_CTX_new
  433*/
  434WOLFSSL_METHOD *wolfDTLSv1_client_method(void);
  435
  436/*!
  437    \ingroup Setup
  438
  439    \brief The wolfDTLSv1_server_method() function is used to indicate
  440    that the application is a server and will only support the DTLS 1.0
  441    protocol.  This function allocates memory for and initializes a
  442    new wolfSSL_METHOD structure to be used when creating the SSL/TLS
  443    context with wolfSSL_CTX_new(). This function is only available
  444    when wolfSSL has been compiled with DTLS support (--enable-dtls,
  445    or by defining wolfSSL_DTLS).
  446
  447    \return * If successful, the call will return a pointer to the newly
  448    created WOLFSSL_METHOD structure.
  449    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  450    value of the underlying malloc() implementation will be returned
  451    (typically NULL with errno will be set to ENOMEM).
  452
  453    \param none No parameters.
  454
  455    _Example_
  456    \code
  457    WOLFSSL_METHOD* method;
  458    WOLFSSL_CTX* ctx;
  459
  460    method = wolfDTLSv1_server_method();
  461    if (method == NULL) {
  462	    // unable to get method
  463    }
  464
  465    ctx = wolfSSL_CTX_new(method);
  466    ...
  467    \endcode
  468
  469    \sa wolfSSLv3_server_method
  470    \sa wolfTLSv1_server_method
  471    \sa wolfTLSv1_1_server_method
  472    \sa wolfTLSv1_2_server_method
  473    \sa wolfTLSv1_3_server_method
  474    \sa wolfSSLv23_server_method
  475    \sa wolfSSL_CTX_new
  476*/
  477WOLFSSL_METHOD *wolfDTLSv1_server_method(void);
  478/*!
  479    \ingroup Setup
  480
  481    \brief The wolfDTLSv1_3_server_method() function is used to indicate that
  482    the application is a server and will only support the DTLS 1.3
  483    protocol. This function allocates memory for and initializes a new
  484    wolfSSL_METHOD structure to be used when creating the SSL/TLS context with
  485    wolfSSL_CTX_new(). This function is only available when wolfSSL has been
  486    compiled with DTLSv1.3 support (--enable-dtls13, or by defining
  487    wolfSSL_DTLS13).
  488
  489    \return * If successful, the call will return a pointer to the newly
  490    created WOLFSSL_METHOD structure.
  491    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  492    value of the underlying malloc() implementation will be returned
  493    (typically NULL with errno will be set to ENOMEM).
  494
  495    \param none No parameters.
  496
  497    _Example_
  498    \code
  499    WOLFSSL_METHOD* method;
  500    WOLFSSL_CTX* ctx;
  501
  502    method = wolfDTLSv1_3_server_method();
  503    if (method == NULL) {
  504	    // unable to get method
  505    }
  506
  507    ctx = wolfSSL_CTX_new(method);
  508    ...
  509    \endcode
  510
  511
  512    \sa wolfDTLSv1_3_client_method
  513*/
  514
  515WOLFSSL_METHOD *wolfDTLSv1_3_server_method(void);
  516/*!
  517    \ingroup Setup
  518
  519    \brief The wolfDTLSv1_3_client_method() function is used to indicate that
  520    the application is a client and will only support the DTLS 1.3
  521    protocol. This function allocates memory for and initializes a new
  522    wolfSSL_METHOD structure to be used when creating the SSL/TLS context with
  523    wolfSSL_CTX_new(). This function is only available when wolfSSL has been
  524    compiled with DTLSv1.3 support (--enable-dtls13, or by defining
  525    wolfSSL_DTLS13).
  526
  527    \return * If successful, the call will return a pointer to the newly
  528    created WOLFSSL_METHOD structure.
  529    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  530    value of the underlying malloc() implementation will be returned
  531    (typically NULL with errno will be set to ENOMEM).
  532
  533    \param none No parameters.
  534
  535    _Example_
  536    \code
  537    WOLFSSL_METHOD* method;
  538    WOLFSSL_CTX* ctx;
  539
  540    method = wolfDTLSv1_3_client_method();
  541    if (method == NULL) {
  542	    // unable to get method
  543    }
  544
  545    ctx = wolfSSL_CTX_new(method);
  546    ...
  547    \endcode
  548
  549
  550    \sa wolfDTLSv1_3_server_method
  551*/
  552WOLFSSL_METHOD* wolfDTLSv1_3_client_method(void);
  553/*!
  554    \ingroup Setup
  555
  556    \brief The wolfDTLS_server_method() function is used to indicate that the
  557    application is a server and will support the highest version of DTLS
  558    available and all the version up to the minimum version allowed.  The
  559    default minimum version allowed is based on the define
  560    WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using
  561    wolfSSL_SetMinVersion(). This function allocates memory for and initializes
  562    a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  563    with wolfSSL_CTX_new(). This function is only available when wolfSSL has
  564    been compiled with DTLS support (--enable-dtls, or by defining
  565    wolfSSL_DTLS).
  566
  567    \return * If successful, the call will return a pointer to the newly
  568    created WOLFSSL_METHOD structure.
  569    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  570    value of the underlying malloc() implementation will be returned
  571    (typically NULL with errno will be set to ENOMEM).
  572
  573    \param none No parameters.
  574
  575    _Example_
  576    \code
  577    WOLFSSL_METHOD* method;
  578    WOLFSSL_CTX* ctx;
  579
  580    method = wolfDTLS_server_method();
  581    if (method == NULL) {
  582	    // unable to get method
  583    }
  584
  585    ctx = wolfSSL_CTX_new(method);
  586    ...
  587    \endcode
  588
  589
  590    \sa wolfDTLS_client_method
  591    \sa wolfSSL_SetMinVersion
  592*/
  593WOLFSSL_METHOD *wolfDTLS_server_method(void);
  594/*!
  595    \ingroup Setup
  596
  597    \brief The wolfDTLS_client_method() function is used to indicate that the
  598    application is a client and will support the highest version of DTLS
  599    available and all the version up to the minimum version allowed.  The
  600    default minimum version allowed is based on the define
  601    WOLFSSL_MIN_DTLS_DOWNGRADE and can be changed at runtime using
  602    wolfSSL_SetMinVersion(). This function allocates memory for and initializes
  603    a new wolfSSL_METHOD structure to be used when creating the SSL/TLS context
  604    with wolfSSL_CTX_new(). This function is only available when wolfSSL has
  605    been compiled with DTLS support (--enable-dtls, or by defining
  606    wolfSSL_DTLS).
  607
  608    \return * If successful, the call will return a pointer to the newly
  609    created WOLFSSL_METHOD structure.
  610    \return FAIL If memory allocation fails when calling XMALLOC, the failure
  611    value of the underlying malloc() implementation will be returned
  612    (typically NULL with errno will be set to ENOMEM).
  613
  614    \param none No parameters.
  615
  616    _Example_
  617    \code
  618    WOLFSSL_METHOD* method;
  619    WOLFSSL_CTX* ctx;
  620
  621    method = wolfDTLS_client_method();
  622    if (method == NULL) {
  623	    // unable to get method
  624    }
  625
  626    ctx = wolfSSL_CTX_new(method);
  627    ...
  628    \endcode
  629
  630
  631    \sa wolfDTLS_server_method
  632    \sa wolfSSL_SetMinVersion
  633*/
  634WOLFSSL_METHOD *wolfDTLS_client_method(void);
  635/*!
  636    \brief This function creates and initializes a WOLFSSL_METHOD for the
  637    server side.
  638
  639    \return This function returns a WOLFSSL_METHOD pointer.
  640
  641    \param none No parameters.
  642
  643    _Example_
  644    \code
  645    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_server_method());
  646    WOLFSSL* ssl = WOLFSSL_new(ctx);
  647    …
  648    \endcode
  649
  650    \sa wolfSSL_CTX_new
  651*/
  652WOLFSSL_METHOD *wolfDTLSv1_2_server_method(void);
  653
  654/*!
  655    \ingroup Setup
  656
  657    \brief Since there is some differences between the first release and
  658    newer versions of chacha-poly AEAD construction we have added an option
  659    to communicate with servers/clients using the older version. By default
  660    wolfSSL uses the new version.
  661
  662    \return 0 upon success
  663
  664    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  665    \param value whether or not to use the older version of setting up the
  666    information for poly1305. Passing a flag value of 1 indicates yes use the
  667    old poly AEAD, to switch back to using the new version pass a flag value
  668    of 0.
  669
  670    _Example_
  671    \code
  672    int ret = 0;
  673    WOLFSSL* ssl;
  674    ...
  675
  676    ret = wolfSSL_use_old_poly(ssl, 1);
  677    if (ret != 0) {
  678        // failed to set poly1305 AEAD version
  679    }
  680    \endcode
  681
  682    \sa none
  683*/
  684int wolfSSL_use_old_poly(WOLFSSL* ssl, int value);
  685
  686/*!
  687    \brief The wolfSSL_dtls_import() function is used to parse in a serialized
  688    session state. This allows for picking up the connection after the
  689    handshake has been completed.
  690
  691    \return Success If successful, the amount of the buffer read will be
  692    returned.
  693    \return Failure All unsuccessful return values will be less than 0.
  694    \return VERSION_ERROR If a version mismatch is found ie DTLS v1 and ctx
  695    was set up for DTLS v1.2 then VERSION_ERROR is returned.
  696
  697    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  698    \param buf serialized session to import.
  699    \param sz size of serialized session buffer.
  700
  701    _Example_
  702    \code
  703    WOLFSSL* ssl;
  704    int ret;
  705    unsigned char buf[MAX];
  706    bufSz = MAX;
  707    ...
  708    //get information sent from wc_dtls_export function and place it in buf
  709    fread(buf, 1, bufSz, input);
  710    ret = wolfSSL_dtls_import(ssl, buf, bufSz);
  711    if (ret < 0) {
  712    // handle error case
  713    }
  714    // no wolfSSL_accept needed since handshake was already done
  715    ...
  716    ret = wolfSSL_write(ssl) and wolfSSL_read(ssl);
  717    ...
  718    \endcode
  719
  720    \sa wolfSSL_new
  721    \sa wolfSSL_CTX_new
  722    \sa wolfSSL_CTX_dtls_set_export
  723*/
  724int wolfSSL_dtls_import(WOLFSSL* ssl, const unsigned char* buf,
  725                                                               unsigned int sz);
  726
  727
  728/*!
  729    \brief Used to import a serialized TLS session. This function is for
  730    importing the state of the connection.
  731    WARNING: buf contains sensitive information about the state and is best to
  732    be encrypted before storing if stored.
  733    Additional debug info can be displayed with the macro
  734    WOLFSSL_SESSION_EXPORT_DEBUG defined.
  735
  736    \return the number of bytes read from buffer 'buf'
  737
  738    \param ssl WOLFSSL structure to import the session into
  739    \param buf serialized session
  740    \param sz  size of buffer 'buf'
  741
  742    \sa wolfSSL_dtls_import
  743    \sa wolfSSL_tls_export
  744 */
  745int wolfSSL_tls_import(WOLFSSL* ssl, const unsigned char* buf,
  746        unsigned int sz);
  747
  748/*!
  749    \brief The wolfSSL_CTX_dtls_set_export() function is used to set
  750    the callback function for exporting a session. It is allowed to
  751    pass in NULL as the parameter func to clear the export function
  752    previously stored. Used on the server side and is called immediately
  753    after handshake is completed.
  754
  755    \return SSL_SUCCESS upon success.
  756    \return BAD_FUNC_ARG If null or not expected arguments are passed in
  757
  758    \param ctx a pointer to a WOLFSSL_CTX structure, created
  759    with wolfSSL_CTX_new().
  760    \param func wc_dtls_export function to use when exporting a session.
  761
  762    _Example_
  763    \code
  764    int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);
  765    // body of send session (wc_dtls_export) that passes
  766    // buf (serialized session) to destination
  767    WOLFSSL_CTX* ctx;
  768    int ret;
  769    ...
  770    ret = wolfSSL_CTX_dtls_set_export(ctx, send_session);
  771    if (ret != SSL_SUCCESS) {
  772        // handle error case
  773    }
  774    ...
  775    ret = wolfSSL_accept(ssl);
  776    ...
  777    \endcode
  778
  779    \sa wolfSSL_new
  780    \sa wolfSSL_CTX_new
  781    \sa wolfSSL_dtls_set_export
  782    \sa Static buffer use
  783*/
  784int wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX* ctx,
  785                                                           wc_dtls_export func);
  786
  787/*!
  788    \brief The wolfSSL_dtls_set_export() function is used to set the callback
  789    function for exporting a session. It is allowed to pass in NULL as the
  790    parameter func to clear the export function previously stored. Used on
  791    the server side and is called immediately after handshake is completed.
  792
  793    \return SSL_SUCCESS upon success.
  794    \return BAD_FUNC_ARG If null or not expected arguments are passed in
  795
  796    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  797    \param func wc_dtls_export function to use when exporting a session.
  798
  799    _Example_
  800    \code
  801    int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx);
  802    // body of send session (wc_dtls_export) that passes
  803    // buf (serialized session) to destination
  804    WOLFSSL* ssl;
  805    int ret;
  806    ...
  807    ret = wolfSSL_dtls_set_export(ssl, send_session);
  808    if (ret != SSL_SUCCESS) {
  809        // handle error case
  810    }
  811    ...
  812    ret = wolfSSL_accept(ssl);
  813    ...
  814    \endcode
  815
  816    \sa wolfSSL_new
  817    \sa wolfSSL_CTX_new
  818    \sa wolfSSL_CTX_dtls_set_export
  819*/
  820int wolfSSL_dtls_set_export(WOLFSSL* ssl, wc_dtls_export func);
  821
  822/*!
  823    \brief The wolfSSL_dtls_export() function is used to serialize a
  824    WOLFSSL session into the provided buffer. Allows for less memory
  825    overhead than using a function callback for sending a session and
  826    choice over when the session is serialized. If buffer is NULL when
  827    passed to function then sz will be set to the size of buffer needed
  828    for serializing the WOLFSSL session.
  829
  830    \return Success If successful, the amount of the buffer used will
  831    be returned.
  832    \return Failure All unsuccessful return values will be less than 0.
  833
  834    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  835    \param buf buffer to hold serialized session.
  836    \param sz size of buffer.
  837
  838    _Example_
  839    \code
  840    WOLFSSL* ssl;
  841    int ret;
  842    unsigned char buf[MAX];
  843    bufSz = MAX;
  844    ...
  845    ret = wolfSSL_dtls_export(ssl, buf, bufSz);
  846    if (ret < 0) {
  847        // handle error case
  848    }
  849    ...
  850    \endcode
  851
  852    \sa wolfSSL_new
  853    \sa wolfSSL_CTX_new
  854    \sa wolfSSL_CTX_dtls_set_export
  855    \sa wolfSSL_dtls_import
  856*/
  857int wolfSSL_dtls_export(WOLFSSL* ssl, unsigned char* buf,
  858                                                              unsigned int* sz);
  859
  860/*!
  861    \brief Used to export a serialized TLS session. This function is for
  862    exporting a serialized state of the connection.
  863    In most cases wolfSSL_get1_session should be used instead of
  864    wolfSSL_tls_export.
  865    Additional debug info can be displayed with the macro
  866    WOLFSSL_SESSION_EXPORT_DEBUG defined.
  867    WARNING: buf contains sensitive information about the state and is best to
  868             be encrypted before storing if stored.
  869
  870    \return the number of bytes written into buffer 'buf'
  871
  872    \param ssl WOLFSSL structure to export the session from
  873    \param buf output of serialized session
  874    \param sz  size in bytes set in 'buf'
  875
  876    \sa wolfSSL_dtls_import
  877    \sa wolfSSL_tls_import
  878 */
  879int wolfSSL_tls_export(WOLFSSL* ssl, unsigned char* buf,
  880        unsigned int* sz);
  881
  882/*!
  883    \brief This function is used to set aside static memory for a CTX. Memory
  884    set aside is then used for the CTX’s lifetime and for any SSL objects
  885    created from the CTX. By passing in a NULL ctx pointer and a
  886    wolfSSL_method_func function the creation of the CTX itself will also
  887    use static memory. wolfSSL_method_func has the function signature of
  888    WOLFSSL_METHOD* (*wolfSSL_method_func)(void* heap);. Passing in 0 for max
  889    makes it behave as if not set and no max concurrent use restrictions is
  890    in place. The flag value passed in determines how the memory is used and
  891    behavior while operating. Available flags are the following: 0 - default
  892    general memory, WOLFMEM_IO_POOL - used for input/output buffer when
  893    sending receiving messages and overrides general memory, so all memory
  894    in buffer passed in is used for IO, WOLFMEM_IO_FIXED - same as
  895    WOLFMEM_IO_POOL but each SSL now keeps two buffers to themselves for
  896    their lifetime, WOLFMEM_TRACK_STATS - each SSL keeps track of memory
  897    stats while running.
  898
  899    \return SSL_SUCCESS upon success.
  900    \return SSL_FAILURE upon failure.
  901
  902    \param ctx address of pointer to a WOLFSSL_CTX structure.
  903    \param method function to create protocol. (should be NULL if ctx is not
  904    also NULL)
  905    \param buf memory to use for all operations.
  906    \param sz size of memory buffer being passed in.
  907    \param flag type of memory.
  908    \param max max concurrent operations.
  909
  910    _Example_
  911    \code
  912    WOLFSSL_CTX* ctx;
  913    WOLFSSL* ssl;
  914    int ret;
  915    unsigned char memory[MAX];
  916    int memorySz = MAX;
  917    unsigned char IO[MAX];
  918    int IOSz = MAX;
  919    int flag = WOLFMEM_IO_FIXED | WOLFMEM_TRACK_STATS;
  920    ...
  921    // create ctx also using static memory, start with general memory to use
  922    ctx = NULL:
  923    ret = wolfSSL_CTX_load_static_memory(&ctx, wolfSSLv23_server_method_ex,
  924    memory, memorySz, 0,    MAX_CONCURRENT_HANDSHAKES);
  925    if (ret != SSL_SUCCESS) {
  926    // handle error case
  927    }
  928    // load in memory for use with IO
  929    ret = wolfSSL_CTX_load_static_memory(&ctx, NULL, IO, IOSz, flag,
  930    MAX_CONCURRENT_IO);
  931    if (ret != SSL_SUCCESS) {
  932    // handle error case
  933    }
  934    ...
  935    \endcode
  936
  937    \sa wolfSSL_CTX_new
  938    \sa wolfSSL_CTX_is_static_memory
  939    \sa wolfSSL_is_static_memory
  940*/
  941int wolfSSL_CTX_load_static_memory(WOLFSSL_CTX** ctx,
  942                                            wolfSSL_method_func method,
  943                                            unsigned char* buf, unsigned int sz,
  944                                            int flag, int max);
  945
  946/*!
  947    \brief This function does not change any of the connections behavior
  948    and is used only for gathering information about the static memory usage.
  949
  950    \return 1 is returned if using static memory for the CTX is true.
  951    \return 0 is returned if not using static memory.
  952
  953    \param ctx a pointer to a WOLFSSL_CTX structure, created using
  954    wolfSSL_CTX_new().
  955    \param mem_stats structure to hold information about static memory usage.
  956
  957    _Example_
  958    \code
  959    WOLFSSL_CTX* ctx;
  960    int ret;
  961    WOLFSSL_MEM_STATS mem_stats;
  962    ...
  963    //get information about static memory with CTX
  964    ret = wolfSSL_CTX_is_static_memory(ctx, &mem_stats);
  965    if (ret == 1) {
  966        // handle case of is using static memory
  967        // print out or inspect elements of mem_stats
  968    }
  969    if (ret == 0) {
  970        //handle case of ctx not using static memory
  971    }
  972    …
  973    \endcode
  974
  975    \sa wolfSSL_CTX_new
  976    \sa wolfSSL_CTX_load_static_memory
  977    \sa wolfSSL_is_static_memory
  978*/
  979int wolfSSL_CTX_is_static_memory(WOLFSSL_CTX* ctx,
  980                                                 WOLFSSL_MEM_STATS* mem_stats);
  981
  982/*!
  983    \brief wolfSSL_is_static_memory is used to gather information about
  984    a SSL’s static memory usage. The return value indicates if static
  985    memory is being used and WOLFSSL_MEM_CONN_STATS will be filled out
  986    if and only if the flag WOLFMEM_TRACK_STATS was passed to the parent
  987    CTX when loading in static memory.
  988
  989    \return 1 is returned if using static memory for the CTX is true.
  990    \return 0 is returned if not using static memory.
  991
  992    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  993    \param mem_stats structure to contain static memory usage.
  994
  995    _Example_
  996    \code
  997    WOLFSSL* ssl;
  998    int ret;
  999    WOLFSSL_MEM_CONN_STATS mem_stats;
 1000    ...
 1001    ret = wolfSSL_is_static_memory(ssl, mem_stats);
 1002    if (ret == 1) {
 1003        // handle case when is static memory
 1004        // investigate elements in mem_stats if WOLFMEM_TRACK_STATS flag
 1005    }
 1006    ...
 1007    \endcode
 1008
 1009    \sa wolfSSL_new
 1010    \sa wolfSSL_CTX_is_static_memory
 1011*/
 1012int wolfSSL_is_static_memory(WOLFSSL* ssl,
 1013                                            WOLFSSL_MEM_CONN_STATS* mem_stats);
 1014
 1015/*!
 1016    \ingroup CertsKeys
 1017
 1018    \brief This function loads a certificate file into the SSL context
 1019    (WOLFSSL_CTX).  The file is provided by the file argument. The
 1020    format argument specifies the format type of the file, either
 1021    SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.  Please see the examples
 1022    for proper usage.
 1023
 1024    \return SSL_SUCCESS upon success.
 1025    \return SSL_FAILURE If the function call fails, possible causes might
 1026    include the file is in the wrong format, or the wrong format has been
 1027    given using the “format” argument, file doesn’t exist, can’t be read,
 1028    or is corrupted, an out of memory condition occurs, Base16 decoding
 1029    fails on the file.
 1030
 1031    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 1032    wolfSSL_CTX_new()
 1033    \param file a pointer to the name of the file containing the certificate
 1034    to be loaded into the wolfSSL SSL context.
 1035    \param format - format of the certificates pointed to by file. Possible
 1036    options are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 1037
 1038    _Example_
 1039    \code
 1040    int ret = 0;
 1041    WOLFSSL_CTX* ctx;
 1042    ...
 1043    ret = wolfSSL_CTX_use_certificate_file(ctx, “./client-cert.pem”,
 1044                                     SSL_FILETYPE_PEM);
 1045    if (ret != SSL_SUCCESS) {
 1046	    // error loading cert file
 1047    }
 1048    ...
 1049    \endcode
 1050
 1051    \sa wolfSSL_CTX_use_certificate_buffer
 1052    \sa wolfSSL_use_certificate_file
 1053    \sa wolfSSL_use_certificate_buffer
 1054*/
 1055int wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX* ctx, const char* file,
 1056                                     int format);
 1057
 1058/*!
 1059    \ingroup CertsKeys
 1060
 1061    \brief This function loads a private key file into the SSL context
 1062    (WOLFSSL_CTX). The file is provided by the file argument. The format
 1063    argument specifies the format type of the file - SSL_FILETYPE_ASN1or
 1064    SSL_FILETYPE_PEM.  Please see the examples for proper usage.
 1065
 1066    If using an external key store and do not have the private key you can
 1067    instead provide the public key and register the crypro callback to handle
 1068    the signing. For this you can build with either build with crypto callbacks
 1069    or PK callbacks. To enable crypto callbacks use --enable-cryptocb
 1070    or WOLF_CRYPTO_CB and register a crypto callback using
 1071    wc_CryptoCb_RegisterDevice and set the associated devId using
 1072    wolfSSL_CTX_SetDevId.
 1073
 1074    \return SSL_SUCCESS upon success.
 1075    \return SSL_FAILURE The file is in the wrong format, or the wrong format
 1076    has been given using the “format” argument. The file doesn’t exist, can’t
 1077    be read, or is corrupted. An out of memory condition occurs. Base16
 1078    decoding fails on the file. The key file is encrypted but no password
 1079    is provided.
 1080
 1081    \param ctx pointer to a WOLFSSL_CTX structure.
 1082    \param file path to the private key file.
 1083    \param format format of the key file (SSL_FILETYPE_PEM or
 1084    SSL_FILETYPE_ASN1).
 1085
 1086    _Example_
 1087    \code
 1088    int ret = 0;
 1089    WOLFSSL_CTX* ctx;
 1090    ...
 1091    ret = wolfSSL_CTX_use_PrivateKey_file(ctx, “./server-key.pem”,
 1092                                    SSL_FILETYPE_PEM);
 1093    if (ret != SSL_SUCCESS) {
 1094	    // error loading key file
 1095    }
 1096    ...
 1097    \endcode
 1098
 1099    \sa wolfSSL_CTX_use_PrivateKey_buffer
 1100    \sa wolfSSL_use_PrivateKey_file
 1101    \sa wolfSSL_use_PrivateKey_buffer
 1102    \sa wc_CryptoCb_RegisterDevice
 1103    \sa wolfSSL_CTX_SetDevId
 1104*/
 1105int wolfSSL_CTX_use_PrivateKey_file(WOLFSSL_CTX* ctx, const char* file, int format);
 1106
 1107/*!
 1108    \ingroup CertsKeys
 1109
 1110    \brief This function loads PEM-formatted CA certificate files into the SSL
 1111    context (WOLFSSL_CTX).  These certificates will be treated as trusted root
 1112    certificates and used to verify certs received from peers during the SSL
 1113    handshake. The root certificate file, provided by the file argument, may
 1114    be a single certificate or a file containing multiple certificates.
 1115    If multiple CA certs are included in the same file, wolfSSL will load them
 1116    in the same order they are presented in the file.  The path argument is
 1117    a pointer to the name of a directory that contains certificates of
 1118    trusted root CAs. If the value of file is not NULL, path may be specified
 1119    as NULL if not needed.  If path is specified and NO_WOLFSSL_DIR was not
 1120    defined when building the library, wolfSSL will load all CA certificates
 1121    located in the given directory. This function will attempt to load all
 1122    files in the directory. This function expects PEM formatted CERT_TYPE
 1123    file with header “-----BEGIN CERTIFICATE-----”.
 1124
 1125    \return SSL_SUCCESS up success.
 1126    \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
 1127    path are NULL.
 1128    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 1129    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
 1130    read, or is corrupted.
 1131    \return MEMORY_E will be returned if an out of memory condition occurs.
 1132    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 1133    \return ASN_BEFORE_DATE_E will be returned if the current date is before the
 1134    before date.
 1135    \return ASN_AFTER_DATE_E will be returned if the current date is after the
 1136    after date.
 1137    \return BUFFER_E will be returned if a chain buffer is bigger than the
 1138    receiving buffer.
 1139    \return BAD_PATH_ERROR will be returned if opendir() fails when trying
 1140    to open path.
 1141
 1142    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 1143    \param file pointer to name of the file containing PEM-formatted CA
 1144    certificates.
 1145    \param path pointer to the name of a directory to load PEM-formatted
 1146    certificates from.
 1147
 1148    _Example_
 1149    \code
 1150    int ret = 0;
 1151    WOLFSSL_CTX* ctx;
 1152    ...
 1153    ret = wolfSSL_CTX_load_verify_locations(ctx, “./ca-cert.pem”, NULL);
 1154    if (ret != WOLFSSL_SUCCESS) {
 1155    	// error loading CA certs
 1156    }
 1157    ...
 1158    \endcode
 1159
 1160    \sa wolfSSL_CTX_load_verify_locations_ex
 1161    \sa wolfSSL_CTX_load_verify_buffer
 1162    \sa wolfSSL_CTX_use_certificate_file
 1163    \sa wolfSSL_CTX_use_PrivateKey_file
 1164    \sa wolfSSL_CTX_use_certificate_chain_file
 1165    \sa wolfSSL_use_certificate_file
 1166    \sa wolfSSL_use_PrivateKey_file
 1167    \sa wolfSSL_use_certificate_chain_file
 1168*/
 1169int wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX* ctx, const char* file,
 1170                                                const char* path);
 1171
 1172/*!
 1173    \ingroup CertsKeys
 1174
 1175    \brief This function loads PEM-formatted CA certificate files into the SSL
 1176    context (WOLFSSL_CTX).  These certificates will be treated as trusted root
 1177    certificates and used to verify certs received from peers during the SSL
 1178    handshake. The root certificate file, provided by the file argument, may
 1179    be a single certificate or a file containing multiple certificates.
 1180    If multiple CA certs are included in the same file, wolfSSL will load them
 1181    in the same order they are presented in the file.  The path argument is
 1182    a pointer to the name of a directory that contains certificates of
 1183    trusted root CAs. If the value of file is not NULL, path may be specified
 1184    as NULL if not needed.  If path is specified and NO_WOLFSSL_DIR was not
 1185    defined when building the library, wolfSSL will load all CA certificates
 1186    located in the given directory. This function will attempt to load all
 1187    files in the directory based on flags specified. This function expects PEM
 1188    formatted CERT_TYPE files with header “-----BEGIN CERTIFICATE-----”.
 1189
 1190    \return SSL_SUCCESS up success.
 1191    \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
 1192    path are NULL. This will also be returned if at least one cert is loaded
 1193    successfully but there is one or more that failed. Check error stack for reason.
 1194    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 1195    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
 1196    read, or is corrupted.
 1197    \return MEMORY_E will be returned if an out of memory condition occurs.
 1198    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 1199    \return BUFFER_E will be returned if a chain buffer is bigger than the
 1200    receiving buffer.
 1201    \return BAD_PATH_ERROR will be returned if opendir() fails when trying
 1202    to open path.
 1203
 1204    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 1205    \param file pointer to name of the file containing PEM-formatted CA
 1206    certificates.
 1207    \param path pointer to the name of a directory to load PEM-formatted
 1208    certificates from.
 1209    \param flags possible mask values are: WOLFSSL_LOAD_FLAG_IGNORE_ERR,
 1210    WOLFSSL_LOAD_FLAG_DATE_ERR_OKAY and WOLFSSL_LOAD_FLAG_PEM_CA_ONLY
 1211
 1212    _Example_
 1213    \code
 1214    int ret = 0;
 1215    WOLFSSL_CTX* ctx;
 1216    ...
 1217    ret = wolfSSL_CTX_load_verify_locations_ex(ctx, NULL, “./certs/external",
 1218        WOLFSSL_LOAD_FLAG_PEM_CA_ONLY);
 1219    if (ret != WOLFSSL_SUCCESS) {
 1220        // error loading CA certs
 1221    }
 1222    ...
 1223    \endcode
 1224
 1225    \sa wolfSSL_CTX_load_verify_locations
 1226    \sa wolfSSL_CTX_load_verify_buffer
 1227    \sa wolfSSL_CTX_use_certificate_file
 1228    \sa wolfSSL_CTX_use_PrivateKey_file
 1229    \sa wolfSSL_CTX_use_certificate_chain_file
 1230    \sa wolfSSL_use_certificate_file
 1231    \sa wolfSSL_use_PrivateKey_file
 1232    \sa wolfSSL_use_certificate_chain_file
 1233*/
 1234int wolfSSL_CTX_load_verify_locations_ex(WOLFSSL_CTX* ctx, const char* file,
 1235                                         const char* path, word32 flags);
 1236
 1237/*!
 1238    \ingroup CertsKeys
 1239
 1240    \brief This function returns a pointer to an array of strings representing
 1241    directories wolfSSL will search for system CA certs when
 1242    wolfSSL_CTX_load_system_CA_certs is called. On systems that don't store
 1243    certificates in an accessible system directory (such as Apple platforms),
 1244    this function will always return NULL.
 1245
 1246    \return Valid pointer on success.
 1247    \return NULL pointer on failure.
 1248
 1249    \param num pointer to a word32 that will be populated with the length of the
 1250    array of strings.
 1251
 1252    _Example_
 1253    \code
 1254    WOLFSSL_CTX* ctx;
 1255    const char** dirs;
 1256    word32 numDirs;
 1257
 1258    dirs = wolfSSL_get_system_CA_dirs(&numDirs);
 1259    for (int i = 0; i < numDirs; ++i) {
 1260        printf("Potential system CA dir: %s\n", dirs[i]);
 1261    }
 1262    ...
 1263    \endcode
 1264
 1265    \sa wolfSSL_CTX_load_system_CA_certs
 1266    \sa wolfSSL_CTX_load_verify_locations
 1267    \sa wolfSSL_CTX_load_verify_locations_ex
 1268*/
 1269const char** wolfSSL_get_system_CA_dirs(word32* num);
 1270
 1271/*!
 1272    \ingroup CertsKeys
 1273
 1274    \brief On most platforms (including Linux and Windows), this function
 1275    attempts to load CA certificates into a WOLFSSL_CTX from an OS-dependent
 1276    CA certificate store. Loaded certificates will be trusted.
 1277
 1278    On Apple platforms (excluding macOS), certificates can't be obtained from
 1279    the system, and therefore cannot be loaded into the wolfSSL certificate
 1280    manager. For these platforms, this function enables TLS connections bound to
 1281    the WOLFSSL_CTX to use the native system trust APIs to verify authenticity
 1282    of the peer certificate chain if the authenticity of the peer cannot first
 1283    be authenticated against certificates loaded by the user.
 1284
 1285    The platforms supported and tested are: Linux (Debian, Ubuntu,
 1286    Gentoo, Fedora, RHEL), Windows 10/11, Android, macOS, and iOS.
 1287
 1288    \return WOLFSSL_SUCCESS on success.
 1289    \return WOLFSSL_BAD_PATH if no system CA certs were loaded.
 1290    \return WOLFSSL_FAILURE for other failure types (e.g. Windows cert store
 1291    wasn't properly closed).
 1292
 1293    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 1294
 1295    _Example_
 1296    \code
 1297    int ret = 0;
 1298    WOLFSSL_CTX* ctx;
 1299    ...
 1300    ret = wolfSSL_CTX_load_system_CA_certs(ctx,);
 1301    if (ret != WOLFSSL_SUCCESS) {
 1302        // error loading system CA certs
 1303    }
 1304    ...
 1305    \endcode
 1306
 1307    \sa wolfSSL_get_system_CA_dirs
 1308    \sa wolfSSL_CTX_load_verify_locations
 1309    \sa wolfSSL_CTX_load_verify_locations_ex
 1310*/
 1311int wolfSSL_CTX_load_system_CA_certs(WOLFSSL_CTX* ctx);
 1312
 1313/*!
 1314    \ingroup Setup
 1315
 1316    \brief This function loads a certificate to use for verifying a peer
 1317    when performing a TLS/SSL handshake. The peer certificate sent during the
 1318    handshake is compared by using the SKID when available and the signature.
 1319    If these two things do not match then any loaded CAs are used. Feature is
 1320    enabled by defining the macro WOLFSSL_TRUST_PEER_CERT. Please see the
 1321    examples for proper usage.
 1322
 1323    \return SSL_SUCCES upon success.
 1324    \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
 1325    type are invalid.
 1326    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 1327    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
 1328    read, or is corrupted.
 1329    \return MEMORY_E will be returned if an out of memory condition occurs.
 1330    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 1331
 1332    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 1333    \param file pointer to name of the file containing certificates
 1334    \param type type of certificate being loaded ie SSL_FILETYPE_ASN1
 1335    or SSL_FILETYPE_PEM.
 1336
 1337    _Example_
 1338    \code
 1339    int ret = 0;
 1340    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 1341    ...
 1342
 1343    ret = wolfSSL_CTX_trust_peer_cert(ctx, “./peer-cert.pem”,
 1344    SSL_FILETYPE_PEM);
 1345    if (ret != SSL_SUCCESS) {
 1346        // error loading trusted peer cert
 1347    }
 1348    ...
 1349    \endcode
 1350
 1351    \sa wolfSSL_CTX_load_verify_buffer
 1352    \sa wolfSSL_CTX_use_certificate_file
 1353    \sa wolfSSL_CTX_use_PrivateKey_file
 1354    \sa wolfSSL_CTX_use_certificate_chain_file
 1355    \sa wolfSSL_CTX_trust_peer_buffer
 1356    \sa wolfSSL_CTX_Unload_trust_peers
 1357    \sa wolfSSL_use_certificate_file
 1358    \sa wolfSSL_use_PrivateKey_file
 1359    \sa wolfSSL_use_certificate_chain_file
 1360*/
 1361int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX* ctx, const char* file, int type);
 1362
 1363/*!
 1364    \ingroup CertsKeys
 1365
 1366    \brief This function loads a chain of certificates into the SSL
 1367    context (WOLFSSL_CTX).  The file containing the certificate chain
 1368    is provided by the file argument, and must contain PEM-formatted
 1369    certificates. This function will process up to MAX_CHAIN_DEPTH
 1370    (default = 9, defined in internal.h) certificates, plus the subject cert.
 1371
 1372    \return SSL_SUCCESS upon success
 1373    \return SSL_FAILURE If the function call fails, possible causes might
 1374    include the file is in the wrong format, or the wrong format has been
 1375    given using the “format” argument, file doesn’t exist, can’t be read,
 1376    or is corrupted, an out of memory condition occurs.
 1377
 1378    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 1379    wolfSSL_CTX_new()
 1380    \param file a pointer to the name of the file containing the chain of
 1381    certificates to be loaded into the wolfSSL SSL context.  Certificates
 1382    must be in PEM format.
 1383
 1384    _Example_
 1385    \code
 1386    int ret = 0;
 1387    WOLFSSL_CTX* ctx;
 1388    ...
 1389    ret = wolfSSL_CTX_use_certificate_chain_file(ctx, “./cert-chain.pem”);
 1390    if (ret != SSL_SUCCESS) {
 1391	    // error loading cert file
 1392    }
 1393    ...
 1394    \endcode
 1395
 1396    \sa wolfSSL_CTX_use_certificate_file
 1397    \sa wolfSSL_CTX_use_certificate_buffer
 1398    \sa wolfSSL_use_certificate_file
 1399    \sa wolfSSL_use_certificate_buffer
 1400*/
 1401int wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX *ctx,
 1402                                                     const char *file);
 1403
 1404/*!
 1405    \ingroup openSSL
 1406
 1407    \brief This function loads the private RSA key used in the SSL connection
 1408    into the SSL context (WOLFSSL_CTX).  This function is only available when
 1409    wolfSSL has been compiled with the OpenSSL compatibility layer enabled
 1410    (--enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the
 1411    more-typically used wolfSSL_CTX_use_PrivateKey_file() function. The file
 1412    argument contains a pointer to the RSA private key file, in the format
 1413    specified by format.
 1414
 1415    \return SSL_SUCCESS upon success.
 1416    \return SSL_FAILURE  If the function call fails, possible causes might
 1417    include: The input key file is in the wrong format, or the wrong format
 1418    has been given using the “format” argument, file doesn’t exist, can’t
 1419    be read, or is corrupted, an out of memory condition occurs.
 1420
 1421    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 1422    wolfSSL_CTX_new()
 1423    \param file a pointer to the name of the file containing the RSA private
 1424    key to be loaded into the wolfSSL SSL context, with format as specified
 1425    by format.
 1426    \param format the encoding type of the RSA private key specified by file.
 1427    Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
 1428
 1429    _Example_
 1430    \code
 1431    int ret = 0;
 1432    WOLFSSL_CTX* ctx;
 1433    ...
 1434    ret = wolfSSL_CTX_use_RSAPrivateKey_file(ctx, “./server-key.pem”,
 1435                                       SSL_FILETYPE_PEM);
 1436    if (ret != SSL_SUCCESS) {
 1437	    // error loading private key file
 1438    }
 1439    ...
 1440    \endcode
 1441
 1442    \sa wolfSSL_CTX_use_PrivateKey_buffer
 1443    \sa wolfSSL_CTX_use_PrivateKey_file
 1444    \sa wolfSSL_use_RSAPrivateKey_file
 1445    \sa wolfSSL_use_PrivateKey_buffer
 1446    \sa wolfSSL_use_PrivateKey_file
 1447*/
 1448int wolfSSL_CTX_use_RSAPrivateKey_file(WOLFSSL_CTX* ctx, const char* file, int format);
 1449
 1450/*!
 1451    \ingroup IO
 1452
 1453    \brief This function returns the maximum chain depth allowed, which is 9 by
 1454    default, for a valid session i.e. there is a non-null session object (ssl).
 1455
 1456    \return MAX_CHAIN_DEPTH returned if the WOLFSSL structure is not
 1457    NULL. By default the value is 9.
 1458    \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
 1459
 1460    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 1461
 1462    _Example_
 1463    \code
 1464    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 1465    WOLFSSL* ssl = wolfSSL_new(ctx);
 1466    ...
 1467    long sslDep = wolfSSL_get_verify_depth(ssl);
 1468
 1469    if(sslDep > EXPECTED){
 1470    	// The verified depth is greater than what was expected
 1471    } else {
 1472    	// The verified depth is smaller or equal to the expected value
 1473    }
 1474    \endcode
 1475
 1476    \sa wolfSSL_CTX_get_verify_depth
 1477*/
 1478long wolfSSL_get_verify_depth(WOLFSSL* ssl);
 1479
 1480/*!
 1481    \ingroup Setup
 1482
 1483    \brief This function gets the certificate chaining depth using the
 1484    CTX structure.
 1485
 1486    \return MAX_CHAIN_DEPTH returned if the CTX struct is not NULL. The
 1487    constant representation of the max certificate chain peer depth.
 1488    \return BAD_FUNC_ARG returned if the CTX structure is NULL.
 1489
 1490    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 1491    wolfSSL_CTX_new().
 1492
 1493    _Example_
 1494    \code
 1495    WOLFSSL_METHOD method; // protocol method
 1496    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
 1497    …
 1498    long ret = wolfSSL_CTX_get_verify_depth(ctx);
 1499
 1500    if(ret == EXPECTED){
 1501    	//  You have the expected value
 1502    } else {
 1503    	//  Handle an unexpected depth
 1504    }
 1505    \endcode
 1506
 1507    \sa wolfSSL_CTX_use_certificate_chain_file
 1508    \sa wolfSSL_get_verify_depth
 1509*/
 1510long wolfSSL_CTX_get_verify_depth(WOLFSSL_CTX* ctx);
 1511
 1512/*!
 1513    \ingroup openSSL
 1514
 1515    \brief This function loads a certificate file into the SSL session
 1516    (WOLFSSL structure).  The certificate file is provided by the file
 1517    argument.  The format argument specifies the format type of the file -
 1518    either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 1519
 1520    \return SSL_SUCCESS upon success
 1521    \return SSL_FAILURE If the function call fails, possible causes might
 1522    include: The file is in the wrong format, or the wrong format has been
 1523    given using the “format” argument, file doesn’t exist, can’t be read,
 1524    or is corrupted, an out of memory condition occurs, Base16 decoding
 1525    fails on the file
 1526
 1527    \param ssl a pointer to a WOLFSSL structure, created with wolfSSL_new().
 1528    \param file a pointer to the name of the file containing the certificate to
 1529    be loaded into the wolfSSL SSL session, with format as specified by format.
 1530    \param format the encoding type of the certificate specified by file.
 1531    Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
 1532
 1533    _Example_
 1534    \code
 1535    int ret = 0;
 1536    WOLFSSL* ssl;
 1537    ...
 1538    ret = wolfSSL_use_certificate_file(ssl, “./client-cert.pem”,
 1539                                 SSL_FILETYPE_PEM);
 1540    if (ret != SSL_SUCCESS) {
 1541    	// error loading cert file
 1542    }
 1543    ...
 1544    \endcode
 1545
 1546    \sa wolfSSL_CTX_use_certificate_buffer
 1547    \sa wolfSSL_CTX_use_certificate_file
 1548    \sa wolfSSL_use_certificate_buffer
 1549*/
 1550int wolfSSL_use_certificate_file(WOLFSSL* ssl, const char* file, int format);
 1551
 1552/*!
 1553    \ingroup openSSL
 1554
 1555    \brief This function loads a private key file into the SSL session
 1556    (WOLFSSL structure).  The key file is provided by the file argument.
 1557    The format argument specifies the format type of the file -
 1558    SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 1559
 1560    If using an external key store and do not have the private key you can
 1561    instead provide the public key and register the crypro callback to handle
 1562    the signing. For this you can build with either build with crypto callbacks
 1563    or PK callbacks. To enable crypto callbacks use --enable-cryptocb or
 1564    WOLF_CRYPTO_CB and register a crypto callback using
 1565    wc_CryptoCb_RegisterDevice and set the associated devId using
 1566    wolfSSL_SetDevId.
 1567
 1568    \return SSL_SUCCESS upon success.
 1569    \return SSL_FAILURE If the function call fails, possible causes might
 1570    include: The file is in the wrong format, or the wrong format has been
 1571    given using the “format” argument, The file doesn’t exist, can’t be read,
 1572    or is corrupted, An out of memory condition occurs, Base16 decoding
 1573    fails on the file, The key file is encrypted but no password is provided
 1574
 1575    \param ssl a pointer to a WOLFSSL structure, created with wolfSSL_new().
 1576    \param file a pointer to the name of the file containing the key file to
 1577    be loaded into the wolfSSL SSL session, with format as specified by format.
 1578    \param format the encoding type of the key specified by file.  Possible
 1579    values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
 1580
 1581    _Example_
 1582    \code
 1583    int ret = 0;
 1584    WOLFSSL* ssl;
 1585    ...
 1586    ret = wolfSSL_use_PrivateKey_file(ssl, “./server-key.pem”,
 1587                                SSL_FILETYPE_PEM);
 1588    if (ret != SSL_SUCCESS) {
 1589	    // error loading key file
 1590    }
 1591    ...
 1592    \endcode
 1593
 1594    \sa wolfSSL_CTX_use_PrivateKey_buffer
 1595    \sa wolfSSL_CTX_use_PrivateKey_file
 1596    \sa wolfSSL_use_PrivateKey_buffer
 1597    \sa wc_CryptoCb_RegisterDevice
 1598    \sa wolfSSL_SetDevId
 1599*/
 1600int wolfSSL_use_PrivateKey_file(WOLFSSL* ssl, const char* file, int format);
 1601
 1602/*!
 1603    \ingroup openSSL
 1604
 1605    \brief This function loads a chain of certificates into the SSL
 1606    session (WOLFSSL structure).  The file containing the certificate
 1607    chain is provided by the file argument, and must contain PEM-formatted
 1608    certificates.  This function will process up to MAX_CHAIN_DEPTH
 1609    (default = 9, defined in internal.h) certificates, plus the
 1610    subject certificate.
 1611
 1612    \return SSL_SUCCESS upon success.
 1613    \return SSL_FAILURE If the function call fails, possible causes
 1614    might include: The file is in the wrong format, or the wrong format
 1615    has been given using the “format” argument, file doesn’t exist,
 1616    can’t be read, or is corrupted, an out of memory condition occurs
 1617
 1618    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new()
 1619    \param file a pointer to the name of the file containing the chain
 1620    of certificates to be loaded into the wolfSSL SSL session.
 1621    Certificates must be in PEM format.
 1622
 1623    _Example_
 1624    \code
 1625    int ret = 0;
 1626    WOLFSSL* ctx;
 1627    ...
 1628    ret = wolfSSL_use_certificate_chain_file(ssl, “./cert-chain.pem”);
 1629    if (ret != SSL_SUCCESS) {
 1630    	// error loading cert file
 1631    }
 1632    ...
 1633    \endcode
 1634
 1635    \sa wolfSSL_CTX_use_certificate_chain_file
 1636    \sa wolfSSL_CTX_use_certificate_chain_buffer
 1637    \sa wolfSSL_use_certificate_chain_buffer
 1638*/
 1639int wolfSSL_use_certificate_chain_file(WOLFSSL* ssl, const char *file);
 1640
 1641/*!
 1642    \ingroup openSSL
 1643
 1644    \brief This function loads the private RSA key used in the SSL
 1645    connection into the SSL session (WOLFSSL structure). This
 1646    function is only available when wolfSSL has been compiled with
 1647    the OpenSSL compatibility layer enabled (--enable-opensslExtra,
 1648    #define OPENSSL_EXTRA), and is identical to the more-typically
 1649    used wolfSSL_use_PrivateKey_file() function. The file argument
 1650    contains a pointer to the RSA private key file, in the format
 1651    specified by format.
 1652
 1653    \return SSL_SUCCESS upon success
 1654    \return SSL_FAILURE If the function call fails, possible causes might
 1655    include: The input key file is in the wrong format, or the wrong format
 1656    has been given using the “format” argument, file doesn’t exist, can’t
 1657    be read, or is corrupted, an out of memory condition occurs
 1658
 1659    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new()
 1660    \param file a pointer to the name of the file containing the RSA private
 1661    key to be loaded into the wolfSSL SSL session, with format as specified
 1662    by format.
 1663    \param format the encoding type of the RSA private key specified by file.
 1664    Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
 1665
 1666    _Example_
 1667    \code
 1668    int ret = 0;
 1669    WOLFSSL* ssl;
 1670    ...
 1671    ret = wolfSSL_use_RSAPrivateKey_file(ssl, “./server-key.pem”,
 1672                                   SSL_FILETYPE_PEM);
 1673    if (ret != SSL_SUCCESS) {
 1674	    // error loading private key file
 1675    }
 1676    ...
 1677    \endcode
 1678
 1679    \sa wolfSSL_CTX_use_RSAPrivateKey_file
 1680    \sa wolfSSL_CTX_use_PrivateKey_buffer
 1681    \sa wolfSSL_CTX_use_PrivateKey_file
 1682    \sa wolfSSL_use_PrivateKey_buffer
 1683    \sa wolfSSL_use_PrivateKey_file
 1684*/
 1685int wolfSSL_use_RSAPrivateKey_file(WOLFSSL* ssl, const char* file, int format);
 1686
 1687/*!
 1688    \ingroup CertsKeys
 1689
 1690    \brief This function is similar to wolfSSL_CTX_load_verify_locations,
 1691    but allows the loading of DER-formatted CA files into the SSL context
 1692    (WOLFSSL_CTX).  It may still be used to load PEM-formatted CA files as
 1693    well. These certificates will be treated as trusted root certificates
 1694    and used to verify certs received from peers during the SSL handshake.
 1695    The root certificate file, provided by the file argument, may be a single
 1696    certificate or a file containing multiple certificates.  If multiple CA
 1697    certs are included in the same file, wolfSSL will load them in the same
 1698    order they are presented in the file.  The format argument specifies the
 1699    format which the certificates are in either, SSL_FILETYPE_PEM or
 1700    SSL_FILETYPE_ASN1 (DER). Unlike wolfSSL_CTX_load_verify_locations,
 1701    this function does not allow the loading of CA certificates from a given
 1702    directory path. Note that this function is only available when the wolfSSL
 1703    library was compiled with WOLFSSL_DER_LOAD defined.
 1704
 1705    \return SSL_SUCCESS upon success.
 1706    \return SSL_FAILURE upon failure.
 1707
 1708    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 1709    wolfSSL_CTX_new()
 1710    \param file a pointer to the name of the file containing the CA
 1711    certificates to be loaded into the wolfSSL SSL context, with format
 1712    as specified by format.
 1713    \param format the encoding type of the certificates specified by file.
 1714    Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.
 1715
 1716    _Example_
 1717    \code
 1718    int ret = 0;
 1719    WOLFSSL_CTX* ctx;
 1720    ...
 1721    ret = wolfSSL_CTX_der_load_verify_locations(ctx, “./ca-cert.der”,
 1722                                          SSL_FILETYPE_ASN1);
 1723    if (ret != SSL_SUCCESS) {
 1724	    // error loading CA certs
 1725    }
 1726    ...
 1727    \endcode
 1728
 1729    \sa wolfSSL_CTX_load_verify_locations
 1730    \sa wolfSSL_CTX_load_verify_buffer
 1731*/
 1732int wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX* ctx,
 1733                                          const char* file, int format);
 1734
 1735/*!
 1736    \ingroup Setup
 1737
 1738    \brief This function creates a new SSL context, taking a desired
 1739    SSL/TLS protocol method for input.
 1740
 1741    \return pointer If successful the call will return a pointer to the
 1742    newly-created WOLFSSL_CTX.
 1743    \return NULL upon failure.
 1744
 1745    \param method pointer to the desired WOLFSSL_METHOD to use for the SSL
 1746    context. This is created using one of the wolfSSLvXX_XXXX_method()
 1747    functions to specify SSL/TLS/DTLS protocol level.
 1748    This function frees the passed in WOLFSSL_METHOD struct on failure.
 1749
 1750    _Example_
 1751    \code
 1752    WOLFSSL_CTX*    ctx    = 0;
 1753    WOLFSSL_METHOD* method = 0;
 1754
 1755    method = wolfSSLv3_client_method();
 1756    if (method == NULL) {
 1757    	// unable to get method
 1758    }
 1759
 1760    ctx = wolfSSL_CTX_new(method);
 1761    if (ctx == NULL) {
 1762    	// context creation failed
 1763    }
 1764    \endcode
 1765
 1766    \sa wolfSSL_new
 1767*/
 1768WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD*);
 1769
 1770/*!
 1771    \ingroup Setup
 1772
 1773    \brief This function creates a new SSL session, taking an already
 1774    created SSL context as input.
 1775
 1776    \return * If successful the call will return a pointer to the
 1777    newly-created wolfSSL structure.
 1778    \return NULL Upon failure.
 1779
 1780    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 1781
 1782    _Example_
 1783    \code
 1784    #include <wolfssl/ssl.h>
 1785
 1786    WOLFSSL*     ssl = NULL;
 1787    WOLFSSL_CTX* ctx = 0;
 1788
 1789    ctx = wolfSSL_CTX_new(method);
 1790    if (ctx == NULL) {
 1791	    // context creation failed
 1792    }
 1793
 1794    ssl = wolfSSL_new(ctx);
 1795    if (ssl == NULL) {
 1796	    // SSL object creation failed
 1797    }
 1798    \endcode
 1799
 1800    \sa wolfSSL_CTX_new
 1801*/
 1802WOLFSSL* wolfSSL_new(WOLFSSL_CTX*);
 1803
 1804/*!
 1805    \ingroup Setup
 1806
 1807    \brief This function assigns a file descriptor (fd) as the
 1808    input/output facility for the SSL connection. Typically this will be
 1809    a socket file descriptor.
 1810
 1811    \return SSL_SUCCESS upon success.
 1812    \return BAD_FUNC_ARG upon failure.
 1813
 1814    \param ssl pointer to the SSL session, created with wolfSSL_new().
 1815    \param fd file descriptor to use with SSL/TLS connection.
 1816
 1817    _Example_
 1818    \code
 1819    int sockfd;
 1820    WOLFSSL* ssl = 0;
 1821    ...
 1822
 1823    ret = wolfSSL_set_fd(ssl, sockfd);
 1824    if (ret != SSL_SUCCESS) {
 1825    	// failed to set SSL file descriptor
 1826    }
 1827    \endcode
 1828
 1829    \sa wolfSSL_CTX_SetIOSend
 1830    \sa wolfSSL_CTX_SetIORecv
 1831    \sa wolfSSL_SetIOReadCtx
 1832    \sa wolfSSL_SetIOWriteCtx
 1833*/
 1834int  wolfSSL_set_fd(WOLFSSL* ssl, int fd);
 1835
 1836/*!
 1837    \ingroup Setup
 1838
 1839    \brief This function assigns a file descriptor (fd) as the
 1840    input/output facility for the SSL connection. Typically this will be
 1841    a socket file descriptor. This is a DTLS specific API because it marks that
 1842    the socket is connected. recvfrom and sendto calls on this fd will have the
 1843    addr and addr_len parameters set to NULL.
 1844
 1845    \return SSL_SUCCESS upon success.
 1846    \return BAD_FUNC_ARG upon failure.
 1847
 1848    \param ssl pointer to the SSL session, created with wolfSSL_new().
 1849    \param fd file descriptor to use with SSL/TLS connection.
 1850
 1851    _Example_
 1852    \code
 1853    int sockfd;
 1854    WOLFSSL* ssl = 0;
 1855    ...
 1856    if (connect(sockfd, peer_addr, peer_addr_len) != 0) {
 1857        // handle connect error
 1858    }
 1859    ...
 1860    ret = wolfSSL_set_dtls_fd_connected(ssl, sockfd);
 1861    if (ret != SSL_SUCCESS) {
 1862        // failed to set SSL file descriptor
 1863    }
 1864    \endcode
 1865
 1866    \sa wolfSSL_CTX_SetIOSend
 1867    \sa wolfSSL_CTX_SetIORecv
 1868    \sa wolfSSL_SetIOReadCtx
 1869    \sa wolfSSL_SetIOWriteCtx
 1870    \sa wolfDTLS_SetChGoodCb
 1871*/
 1872int wolfSSL_set_dtls_fd_connected(WOLFSSL* ssl, int fd);
 1873
 1874/*!
 1875    \ingroup Setup
 1876
 1877    \brief Allows setting a callback for a correctly processed and verified DTLS
 1878           client hello. When using a cookie exchange mechanism (either the
 1879           HelloVerifyRequest in DTLS 1.2 or the HelloRetryRequest with a cookie
 1880           extension in DTLS 1.3) this callback is called after the cookie
 1881           exchange has succeeded. This is useful to use one WOLFSSL object as
 1882           the listener for new connections and being able to isolate the
 1883           WOLFSSL object once the ClientHello is verified (either through a
 1884           cookie exchange or just checking if the ClientHello had the correct
 1885           format).
 1886           DTLS 1.2:
 1887           https://datatracker.ietf.org/doc/html/rfc6347#section-4.2.1
 1888           DTLS 1.3:
 1889           https://www.rfc-editor.org/rfc/rfc8446#section-4.2.2
 1890
 1891    \return SSL_SUCCESS upon success.
 1892    \return BAD_FUNC_ARG upon failure.
 1893
 1894    \param ssl pointer to the SSL session, created with wolfSSL_new().
 1895    \param cb ClientHelloGoodCb callback function pointer.
 1896    \param user_ctx pointer to user context to be passed to callback.
 1897
 1898    _Example_
 1899    \code
 1900
 1901    // Called when we have verified a connection
 1902    static int chGoodCb(WOLFSSL* ssl, void* arg)
 1903    {
 1904        // setup peer and file descriptors
 1905
 1906    }
 1907
 1908    if (wolfDTLS_SetChGoodCb(ssl, chGoodCb, NULL) != WOLFSSL_SUCCESS) {
 1909         // error setting callback
 1910    }
 1911    \endcode
 1912
 1913    \sa wolfSSL_set_dtls_fd_connected
 1914*/
 1915int wolfDTLS_SetChGoodCb(WOLFSSL* ssl, ClientHelloGoodCb cb, void* user_ctx);
 1916
 1917/*!
 1918    \ingroup IO
 1919
 1920    \brief Get the name of cipher at priority level passed in.
 1921
 1922    \return string Success
 1923    \return 0 Priority is either out of bounds or not valid.
 1924
 1925    \param priority Integer representing the priority level of a cipher.
 1926
 1927    _Example_
 1928    \code
 1929    printf("The cipher at 1 is %s", wolfSSL_get_cipher_list(1));
 1930    \endcode
 1931
 1932    \sa wolfSSL_CIPHER_get_name
 1933    \sa wolfSSL_get_current_cipher
 1934*/
 1935char* wolfSSL_get_cipher_list(int priority);
 1936
 1937/*!
 1938    \ingroup IO
 1939
 1940    \brief This function gets the ciphers enabled in wolfSSL.
 1941
 1942    \return SSL_SUCCESS returned if the function executed without error.
 1943    \return BAD_FUNC_ARG returned if the buf parameter was NULL or if the
 1944    len argument was less than or equal to zero.
 1945    \return BUFFER_E returned if the buffer is not large enough and
 1946    will overflow.
 1947
 1948    \param buf a char pointer representing the buffer.
 1949    \param len the length of the buffer.
 1950
 1951    _Example_
 1952    \code
 1953    static void ShowCiphers(void){
 1954	char* ciphers;
 1955	int ret = wolfSSL_get_ciphers(ciphers, (int)sizeof(ciphers));
 1956
 1957	if(ret == SSL_SUCCES){
 1958	    	printf(“%s\n”, ciphers);
 1959	    }
 1960    }
 1961    \endcode
 1962
 1963    \sa GetCipherNames
 1964    \sa wolfSSL_get_cipher_list
 1965    \sa ShowCiphers
 1966*/
 1967int  wolfSSL_get_ciphers(char* buf, int len);
 1968
 1969/*!
 1970    \ingroup IO
 1971
 1972    \brief This function gets the cipher name in the format DHE-RSA by
 1973    passing through argument to wolfSSL_get_cipher_name_internal.
 1974
 1975    \return string This function returns the string representation of the
 1976    cipher suite that was matched.
 1977    \return NULL error or cipher not found.
 1978
 1979    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 1980
 1981    _Example_
 1982    \code
 1983    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 1984    WOLFSSL* ssl = wolfSSL_new(ctx);
 1985    …
 1986    char* cipherS = wolfSSL_get_cipher_name(ssl);
 1987
 1988    if(cipher == NULL){
 1989	    // There was not a cipher suite matched
 1990    } else {
 1991	    // There was a cipher suite matched
 1992	    printf(“%s\n”, cipherS);
 1993    }
 1994    \endcode
 1995
 1996    \sa wolfSSL_CIPHER_get_name
 1997    \sa wolfSSL_get_current_cipher
 1998    \sa wolfSSL_get_cipher_name_internal
 1999*/
 2000const char* wolfSSL_get_cipher_name(WOLFSSL* ssl);
 2001
 2002/*!
 2003    \ingroup IO
 2004
 2005    \brief This function returns the read file descriptor (fd) used as the
 2006    input facility for the SSL connection.  Typically this
 2007    will be a socket file descriptor.
 2008
 2009    \return fd If successful the call will return the SSL session file
 2010    descriptor.
 2011
 2012    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2013
 2014    _Example_
 2015    \code
 2016    int sockfd;
 2017    WOLFSSL* ssl = 0;
 2018    ...
 2019    sockfd = wolfSSL_get_fd(ssl);
 2020    ...
 2021    \endcode
 2022
 2023    \sa wolfSSL_set_fd
 2024    \sa wolfSSL_set_read_fd
 2025    \sa wolfSSL_set_write_fd
 2026*/
 2027int  wolfSSL_get_fd(const WOLFSSL* ssl);
 2028
 2029/*!
 2030    \ingroup IO
 2031
 2032    \brief This function returns the write file descriptor (fd) used as the
 2033    output facility for the SSL connection.  Typically this
 2034    will be a socket file descriptor.
 2035
 2036    \return fd If successful the call will return the SSL session file
 2037    descriptor.
 2038
 2039    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2040
 2041    _Example_
 2042    \code
 2043    int sockfd;
 2044    WOLFSSL* ssl = 0;
 2045    ...
 2046    sockfd = wolfSSL_get_wfd(ssl);
 2047    ...
 2048    \endcode
 2049
 2050    \sa wolfSSL_set_fd
 2051    \sa wolfSSL_set_read_fd
 2052    \sa wolfSSL_set_write_fd
 2053*/
 2054int  wolfSSL_get_wfd(const WOLFSSL* ssl);
 2055
 2056/*!
 2057    \ingroup Setup
 2058
 2059    \brief This function informs the WOLFSSL object that the underlying
 2060     I/O is non-blocking. After an application creates a WOLFSSL object,
 2061     if it will be used with a non-blocking socket, call
 2062    wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know
 2063     that receiving EWOULDBLOCK means that the recvfrom call would
 2064    block rather than that it timed out.
 2065
 2066    \return none No return.
 2067
 2068    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2069    \param nonblock value used to set non-blocking flag on WOLFSSL object.
 2070    Use 1 to specify non-blocking, otherwise 0.
 2071
 2072    _Example_
 2073    \code
 2074    WOLFSSL* ssl = 0;
 2075    ...
 2076    wolfSSL_set_using_nonblock(ssl, 1);
 2077    \endcode
 2078
 2079    \sa wolfSSL_get_using_nonblock
 2080    \sa wolfSSL_dtls_got_timeout
 2081    \sa wolfSSL_dtls_get_current_timeout
 2082*/
 2083void wolfSSL_set_using_nonblock(WOLFSSL* ssl, int nonblock);
 2084
 2085/*!
 2086    \ingroup IO
 2087
 2088    \brief This function allows the application to determine if wolfSSL is
 2089    using non-blocking I/O.  If wolfSSL is using non-blocking I/O, this
 2090    function will return 1, otherwise 0. After an application creates a
 2091    WOLFSSL object, if it will be used with a non-blocking socket, call
 2092    wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know
 2093    that receiving EWOULDBLOCK means that the recvfrom call would block
 2094    rather than that it timed out.
 2095
 2096    \return 0 underlying I/O is blocking.
 2097    \return 1 underlying I/O is non-blocking.
 2098
 2099    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2100
 2101    _Example_
 2102    \code
 2103    int ret = 0;
 2104    WOLFSSL* ssl = 0;
 2105    ...
 2106    ret = wolfSSL_get_using_nonblock(ssl);
 2107    if (ret == 1) {
 2108    	// underlying I/O is non-blocking
 2109    }
 2110    ...
 2111    \endcode
 2112
 2113    \sa wolfSSL_set_session
 2114*/
 2115int  wolfSSL_get_using_nonblock(WOLFSSL*);
 2116
 2117/*!
 2118    \ingroup IO
 2119
 2120    \brief This function writes sz bytes from the buffer, data, to the SSL
 2121    connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS
 2122    session if the handshake has not already been performed yet by
 2123    wolfSSL_connect() or wolfSSL_accept(). When using (D)TLSv1.3 and early data
 2124    feature is compiled in, this function progresses the handshake only up to
 2125    the point when it is possible to send data. Next invocations of
 2126    wolfSSL_Connect()/wolfSSL_Accept()/wolfSSL_read() will complete the
 2127    handshake. wolfSSL_write() works with both blocking and non-blocking I/O.
 2128    When the underlying I/O is non-blocking, wolfSSL_write() will return when
 2129    the underlying I/O could not satisfy the needs of wolfSSL_write() to
 2130    continue.  In this case, a call to wolfSSL_get_error() will yield either
 2131    SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process must then
 2132    repeat the call to wolfSSL_write() when the underlying I/O is ready. If the
 2133    underlying I/O is blocking, wolfSSL_write() will only return once the buffer
 2134    data of size sz has been completely written or an error occurred.
 2135
 2136    \return >0 the number of bytes written upon success.
 2137    \return 0 will be returned upon failure.  Call wolfSSL_get_error() for
 2138    the specific error code.
 2139    \return SSL_FATAL_ERROR will be returned upon failure when either an error
 2140    occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
 2141    SSL_ERROR_WANT_WRITE error was received and and the application needs to
 2142    call wolfSSL_write() again.  Use wolfSSL_get_error() to get a specific
 2143    error code.
 2144
 2145    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2146    \param data data buffer which will be sent to peer.
 2147    \param sz size, in bytes, of data to send to the peer (data).
 2148
 2149    _Example_
 2150    \code
 2151    WOLFSSL* ssl = 0;
 2152    char msg[64] = “hello wolfssl!”;
 2153    int msgSz = (int)strlen(msg);
 2154    int flags;
 2155    int ret;
 2156    ...
 2157
 2158    ret = wolfSSL_write(ssl, msg, msgSz);
 2159    if (ret <= 0) {
 2160    	// wolfSSL_write() failed, call wolfSSL_get_error()
 2161    }
 2162    \endcode
 2163
 2164    \sa wolfSSL_send
 2165    \sa wolfSSL_read
 2166    \sa wolfSSL_recv
 2167*/
 2168int  wolfSSL_write(WOLFSSL* ssl, const void* data, int sz);
 2169
 2170/*!
 2171    \ingroup IO
 2172
 2173    \brief This function reads sz bytes from the SSL session (ssl)
 2174    internal read buffer into the buffer data. The bytes read are removed
 2175    from the internal receive buffer. If necessary wolfSSL_read() will
 2176    negotiate an SSL/TLS session if the handshake has not already been
 2177    performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS
 2178    protocol uses SSL records which have a maximum size of 16kB (the max
 2179    record size can be controlled by the MAX_RECORD_SIZE define in
 2180    <wolfssl_root>/wolfssl/internal.h).  As such, wolfSSL needs to read an
 2181    entire SSL record internally before it is able to process and decrypt the
 2182    record.  Because of this, a call to wolfSSL_read() will only be able to
 2183    return the maximum buffer size which has been decrypted at the time of
 2184    calling.  There may be additional not-yet-decrypted data waiting in the
 2185    internal wolfSSL receive buffer which will be retrieved and decrypted with
 2186    the next call to wolfSSL_read(). If sz is larger than the number of bytes
 2187    in the internal read buffer, SSL_read() will return the bytes available in
 2188    the internal read buffer.  If no bytes are buffered in the internal read
 2189    buffer yet, a call to wolfSSL_read() will trigger processing of the next
 2190    record.
 2191
 2192    \return >0 the number of bytes read upon success.
 2193    \return 0 will be returned upon failure.  This may be caused by a either a
 2194    clean (close notify alert) shutdown or just that the peer closed the
 2195    connection.  Call wolfSSL_get_error() for the specific error code.
 2196    \return SSL_FATAL_ERROR will be returned upon failure when either an error
 2197    occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
 2198    SSL_ERROR_WANT_WRITE error was received and and the application needs to
 2199    call wolfSSL_read() again.  Use wolfSSL_get_error() to get a specific
 2200    error code.
 2201
 2202    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2203    \param data buffer where wolfSSL_read() will place data read.
 2204    \param sz number of bytes to read into data.
 2205
 2206    _Example_
 2207    \code
 2208    WOLFSSL* ssl = 0;
 2209    char reply[1024];
 2210    ...
 2211
 2212    input = wolfSSL_read(ssl, reply, sizeof(reply));
 2213    if (input > 0) {
 2214    	// “input” number of bytes returned into buffer “reply”
 2215    }
 2216
 2217    See wolfSSL examples (client, server, echoclient, echoserver) for more
 2218    complete examples of wolfSSL_read().
 2219    \endcode
 2220
 2221    \sa wolfSSL_recv
 2222    \sa wolfSSL_write
 2223    \sa wolfSSL_peek
 2224    \sa wolfSSL_pending
 2225*/
 2226int  wolfSSL_read(WOLFSSL* ssl, void* data, int sz);
 2227
 2228/*!
 2229    \ingroup IO
 2230
 2231    \brief This function copies sz bytes from the SSL session (ssl) internal
 2232    read buffer into the buffer data. This function is identical to
 2233    wolfSSL_read() except that the data in the internal SSL session
 2234    receive buffer is not removed or modified. If necessary, like
 2235    wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if
 2236    the handshake has not already been performed yet by wolfSSL_connect()
 2237    or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a
 2238    maximum size of 16kB (the max record size can be controlled by the
 2239    MAX_RECORD_SIZE define in <wolfssl_root>/wolfssl/internal.h).  As such,
 2240    wolfSSL needs to read an entire SSL record internally before it is able
 2241    to process and decrypt the record.  Because of this, a call to
 2242    wolfSSL_peek() will only be able to return the maximum buffer size which
 2243    has been decrypted at the time of calling.  There may be additional
 2244    not-yet-decrypted data waiting in the internal wolfSSL receive buffer
 2245    which will be retrieved and decrypted with the next call to
 2246    wolfSSL_peek() / wolfSSL_read(). If sz is larger than the number of bytes
 2247    in the internal read buffer, SSL_peek() will return the bytes available
 2248    in the internal read buffer.  If no bytes are buffered in the internal
 2249    read buffer yet, a call to wolfSSL_peek() will trigger processing of the
 2250    next record.
 2251
 2252    \return >0 the number of bytes read upon success.
 2253    \return 0 will be returned upon failure.  This may be caused by a either
 2254    a clean (close notify alert) shutdown or just that the peer closed the
 2255    connection.  Call wolfSSL_get_error() for the specific error code.
 2256    \return SSL_FATAL_ERROR will be returned upon failure when either an
 2257    error occurred or, when using non-blocking sockets, the
 2258    SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and
 2259    the application needs to call wolfSSL_peek() again. Use
 2260    wolfSSL_get_error() to get a specific error code.
 2261
 2262    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2263    \param data buffer where wolfSSL_peek() will place data read.
 2264    \param sz number of bytes to read into data.
 2265
 2266    _Example_
 2267    \code
 2268    WOLFSSL* ssl = 0;
 2269    char reply[1024];
 2270    ...
 2271
 2272    input = wolfSSL_peek(ssl, reply, sizeof(reply));
 2273    if (input > 0) {
 2274	    // “input” number of bytes returned into buffer “reply”
 2275    }
 2276    \endcode
 2277
 2278    \sa wolfSSL_read
 2279*/
 2280int  wolfSSL_peek(WOLFSSL* ssl, void* data, int sz);
 2281
 2282/*!
 2283    \ingroup IO
 2284
 2285    \brief This function is called on the server side and waits for an SSL
 2286    client to initiate the SSL/TLS handshake.  When this function is called,
 2287    the underlying communication channel has already been set up.
 2288    wolfSSL_accept() works with both blocking and non-blocking I/O.
 2289    When the underlying I/O is non-blocking, wolfSSL_accept() will return
 2290    when the underlying I/O could not satisfy the needs of wolfSSL_accept
 2291    to continue the handshake.  In this case, a call to wolfSSL_get_error()
 2292    will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.
 2293    The calling process must then repeat the call to wolfSSL_accept when
 2294    data is available to read and wolfSSL will pick up where it left off.
 2295    When using a non-blocking socket, nothing needs to be done, but select()
 2296    can be used to check for the required condition. If the underlying I/O
 2297    is blocking, wolfSSL_accept() will only return once the handshake has
 2298    been finished or an error occurred.
 2299
 2300    \return SSL_SUCCESS upon success.
 2301    \return SSL_FATAL_ERROR will be returned if an error occurred. To get a
 2302    more detailed error code, call wolfSSL_get_error().
 2303
 2304    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 2305
 2306    _Example_
 2307    \code
 2308    int ret = 0;
 2309    int err = 0;
 2310    WOLFSSL* ssl;
 2311    char buffer[80];
 2312    ...
 2313
 2314    ret = wolfSSL_accept(ssl);
 2315    if (ret != SSL_SUCCESS) {
 2316        err = wolfSSL_get_error(ssl, ret);
 2317        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
 2318    }
 2319    \endcode
 2320
 2321    \sa wolfSSL_get_error
 2322    \sa wolfSSL_connect
 2323*/
 2324int  wolfSSL_accept(WOLFSSL* ssl);
 2325
 2326/*!
 2327    \ingroup IO
 2328
 2329    \brief This function is called on the server side and statelessly listens
 2330    for an SSL client to initiate the DTLS handshake.
 2331
 2332    \return WOLFSSL_SUCCESS ClientHello containing a valid cookie was received.
 2333    The connection can be continued with wolfSSL_accept().
 2334    \return WOLFSSL_FAILURE The I/O layer returned WANT_READ. This is either
 2335    because there is no data to read and we are using non-blocking sockets or
 2336    we sent a cookie request and we are waiting for a reply. The user should
 2337    call wolfDTLS_accept_stateless again after data becomes available in
 2338    the I/O layer.
 2339    \return WOLFSSL_FATAL_ERROR A fatal error occurred. The ssl object should be
 2340    free'd and allocated again to continue.
 2341
 2342    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 2343
 2344    _Example_
 2345    \code
 2346    int ret = 0;
 2347    int err = 0;
 2348    WOLFSSL* ssl;
 2349    ...
 2350    do {
 2351        ret = wolfDTLS_accept_stateless(ssl);
 2352        if (ret == WOLFSSL_FATAL_ERROR)
 2353            // re-allocate the ssl object with wolfSSL_free() and wolfSSL_new()
 2354    } while (ret != WOLFSSL_SUCCESS);
 2355    ret = wolfSSL_accept(ssl);
 2356    if (ret != SSL_SUCCESS) {
 2357        err = wolfSSL_get_error(ssl, ret);
 2358        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
 2359    }
 2360    \endcode
 2361
 2362    \sa wolfSSL_accept
 2363    \sa wolfSSL_get_error
 2364    \sa wolfSSL_connect
 2365*/
 2366int  wolfDTLS_accept_stateless(WOLFSSL* ssl);
 2367
 2368/*!
 2369    \ingroup Setup
 2370
 2371    \brief This function frees an allocated WOLFSSL_CTX object.  This
 2372    function decrements the CTX reference count and only frees the context
 2373    when the reference count has reached 0.
 2374
 2375    \return none No return.
 2376
 2377    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 2378
 2379    _Example_
 2380    \code
 2381    WOLFSSL_CTX* ctx = 0;
 2382    ...
 2383    wolfSSL_CTX_free(ctx);
 2384    \endcode
 2385
 2386    \sa wolfSSL_CTX_new
 2387    \sa wolfSSL_new
 2388    \sa wolfSSL_free
 2389*/
 2390void wolfSSL_CTX_free(WOLFSSL_CTX* ctx);
 2391
 2392/*!
 2393    \ingroup Setup
 2394
 2395    \brief This function frees an allocated wolfSSL object.
 2396
 2397    \return none No return.
 2398
 2399    \param ssl pointer to the SSL object, created with wolfSSL_new().
 2400
 2401    _Example_
 2402    \code
 2403    #include <wolfssl/ssl.h>
 2404
 2405    WOLFSSL* ssl = 0;
 2406    ...
 2407    wolfSSL_free(ssl);
 2408    \endcode
 2409
 2410    \sa wolfSSL_CTX_new
 2411    \sa wolfSSL_new
 2412    \sa wolfSSL_CTX_free
 2413*/
 2414void wolfSSL_free(WOLFSSL* ssl);
 2415
 2416/*!
 2417    \ingroup TLS
 2418
 2419    \brief This function shuts down an active SSL/TLS connection using
 2420    the SSL session, ssl.  This function will try to send a “close notify”
 2421    alert to the peer. The calling application can choose to wait for the
 2422    peer to send its “close notify” alert in response or just go ahead
 2423    and shut down the underlying connection after directly calling
 2424    wolfSSL_shutdown (to save resources).  Either option is allowed by
 2425    the TLS specification.  If the underlying connection will be used
 2426    again in the future, the complete two-directional shutdown procedure
 2427    must be performed to keep synchronization intact between the peers.
 2428    wolfSSL_shutdown() works with both blocking and non-blocking I/O.
 2429    When the underlying I/O is non-blocking, wolfSSL_shutdown() will
 2430    return an error if the underlying I/O could not satisfy the needs of
 2431    wolfSSL_shutdown() to continue. In this case, a call to
 2432    wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or
 2433    SSL_ERROR_WANT_WRITE.  The calling process must then repeat the call
 2434    to wolfSSL_shutdown() when the underlying I/O is ready.
 2435
 2436    \return SSL_SUCCESS will be returned upon success.
 2437    \return SSL_SHUTDOWN_NOT_DONE will be returned when shutdown has not
 2438    finished, and the function should be called again.
 2439    \return SSL_FATAL_ERROR will be returned upon failure. Call
 2440    wolfSSL_get_error() for a more specific error code.
 2441
 2442    \param ssl pointer to the SSL session created with wolfSSL_new().
 2443
 2444    _Example_
 2445    \code
 2446    #include <wolfssl/ssl.h>
 2447
 2448    int ret = 0;
 2449    WOLFSSL* ssl = 0;
 2450    ...
 2451    ret = wolfSSL_shutdown(ssl);
 2452    if (ret != 0) {
 2453	    // failed to shut down SSL connection
 2454    }
 2455    \endcode
 2456
 2457    \sa wolfSSL_free
 2458    \sa wolfSSL_CTX_free
 2459*/
 2460int  wolfSSL_shutdown(WOLFSSL* ssl);
 2461
 2462/*!
 2463    \ingroup IO
 2464
 2465    \brief This function writes sz bytes from the buffer, data, to the SSL
 2466    connection, ssl, using the specified flags for the underlying write
 2467    operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session
 2468    if the handshake has not already been performed yet by wolfSSL_connect()
 2469    or wolfSSL_accept(). wolfSSL_send() works with both blocking and
 2470    non-blocking I/O.  When the underlying I/O is non-blocking, wolfSSL_send()
 2471    will return when the underlying I/O could not satisfy the needs of
 2472    wolfSSL_send to continue.  In this case, a call to wolfSSL_get_error()
 2473    will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.
 2474    The calling process must then repeat the call to wolfSSL_send() when
 2475    the underlying I/O is ready. If the underlying I/O is blocking,
 2476    wolfSSL_send() will only return once the buffer data of size sz has
 2477    been completely written or an error occurred.
 2478
 2479    \return >0 the number of bytes written upon success.
 2480    \return 0 will be returned upon failure.  Call wolfSSL_get_error() for
 2481    the specific error code.
 2482    \return SSL_FATAL_ERROR will be returned upon failure when either an error
 2483    occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
 2484    SSL_ERROR_WANT_WRITE error was received and and the application needs to
 2485    call wolfSSL_send() again.  Use wolfSSL_get_error() to get a specific
 2486    error code.
 2487
 2488    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2489    \param data data buffer to send to peer.
 2490    \param sz size, in bytes, of data to be sent to peer.
 2491    \param flags the send flags to use for the underlying send operation.
 2492
 2493    _Example_
 2494    \code
 2495    WOLFSSL* ssl = 0;
 2496    char msg[64] = “hello wolfssl!”;
 2497    int msgSz = (int)strlen(msg);
 2498    int flags = ... ;
 2499    ...
 2500
 2501    input = wolfSSL_send(ssl, msg, msgSz, flags);
 2502    if (input != msgSz) {
 2503    	// wolfSSL_send() failed
 2504    }
 2505    \endcode
 2506
 2507    \sa wolfSSL_write
 2508    \sa wolfSSL_read
 2509    \sa wolfSSL_recv
 2510*/
 2511int  wolfSSL_send(WOLFSSL* ssl, const void* data, int sz, int flags);
 2512
 2513/*!
 2514    \ingroup IO
 2515
 2516    \brief This function reads sz bytes from the SSL session (ssl) internal
 2517    read buffer into the buffer data using the specified flags for the
 2518    underlying recv operation.  The bytes read are removed from the internal
 2519    receive buffer.  This function is identical to wolfSSL_read() except
 2520    that it allows the application to set the recv flags for the underlying
 2521    read operation. If necessary wolfSSL_recv() will negotiate an SSL/TLS
 2522    session if the handshake has not already been performed yet by
 2523    wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses
 2524    SSL records which have a maximum size of 16kB (the max record size
 2525    can be controlled by the MAX_RECORD_SIZE define in
 2526    <wolfssl_root>/wolfssl/internal.h). As such, wolfSSL needs to read an
 2527    entire SSL record internally before it is able to process and decrypt
 2528    the record. Because of this, a call to wolfSSL_recv() will only be
 2529    able to return the maximum buffer size which has been decrypted at
 2530    the time of calling.  There may be additional not-yet-decrypted data
 2531    waiting in the internal wolfSSL receive buffer which will be
 2532    retrieved and decrypted with the next call to wolfSSL_recv(). If sz
 2533    is larger than the number of bytes in the internal read buffer,
 2534    SSL_recv() will return the bytes available in the internal read buffer.
 2535    If no bytes are buffered in the internal read buffer yet, a call to
 2536    wolfSSL_recv() will trigger processing of the next record.
 2537
 2538    \return >0 the number of bytes read upon success.
 2539    \return 0 will be returned upon failure. This may be caused by a either
 2540    a clean (close notify alert) shutdown or just that the peer closed the
 2541    connection. Call wolfSSL_get_error() for the specific error code.
 2542    \return SSL_FATAL_ERROR will be returned upon failure when either an error
 2543    occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
 2544    SSL_ERROR_WANT_WRITE error was received and and the application needs to
 2545    call wolfSSL_recv() again.  Use wolfSSL_get_error() to get a specific
 2546    error code.
 2547
 2548    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2549    \param data buffer where wolfSSL_recv() will place data read.
 2550    \param sz number of bytes to read into data.
 2551    \param flags the recv flags to use for the underlying recv operation.
 2552
 2553    _Example_
 2554    \code
 2555    WOLFSSL* ssl = 0;
 2556    char reply[1024];
 2557    int flags = ... ;
 2558    ...
 2559
 2560    input = wolfSSL_recv(ssl, reply, sizeof(reply), flags);
 2561    if (input > 0) {
 2562    	// “input” number of bytes returned into buffer “reply”
 2563    }
 2564    \endcode
 2565
 2566    \sa wolfSSL_read
 2567    \sa wolfSSL_write
 2568    \sa wolfSSL_peek
 2569    \sa wolfSSL_pending
 2570*/
 2571int  wolfSSL_recv(WOLFSSL* ssl, void* data, int sz, int flags);
 2572
 2573/*!
 2574    \ingroup Debug
 2575
 2576    \brief This function returns a unique error code describing why the
 2577    previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read,
 2578    wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE).
 2579    The return value of the previous function is passed to wolfSSL_get_error
 2580    through ret. After wolfSSL_get_error is called and returns the unique
 2581    error code, wolfSSL_ERR_error_string() may be called to get a
 2582    human-readable error string.  See wolfSSL_ERR_error_string() for more
 2583    information.
 2584
 2585    \return On successful completion, this function will return the
 2586    unique error code describing why the previous API function failed.
 2587    \return SSL_ERROR_NONE will be returned if ret > 0. For ret <= 0, there are
 2588    some cases when this value can also be returned when a previous API appeared
 2589    to return an error code but no error actually occurred. An example is
 2590    calling wolfSSL_read() with a zero sz parameter. A 0 return from
 2591    wolfSSL_read() usually indicates an error but in this case no error
 2592    occurred. If wolfSSL_get_error() is called afterwards, SSL_ERROR_NONE will
 2593    be returned.
 2594
 2595    \param ssl pointer to the SSL object, created with wolfSSL_new().
 2596    \param ret return value of the previous function that resulted in an error
 2597    return code.
 2598
 2599    _Example_
 2600    \code
 2601    int err = 0;
 2602    WOLFSSL* ssl;
 2603    char buffer[80];
 2604    ...
 2605    err = wolfSSL_get_error(ssl, 0);
 2606    wolfSSL_ERR_error_string(err, buffer);
 2607    printf(“err = %d, %s\n”, err, buffer);
 2608    \endcode
 2609
 2610    \sa wolfSSL_ERR_error_string
 2611    \sa wolfSSL_ERR_error_string_n
 2612    \sa wolfSSL_ERR_print_errors_fp
 2613    \sa wolfSSL_load_error_strings
 2614*/
 2615int  wolfSSL_get_error(WOLFSSL* ssl, int ret);
 2616
 2617/*!
 2618    \ingroup IO
 2619
 2620    \brief This function gets the alert history.
 2621
 2622    \return SSL_SUCCESS returned when the function completed successfully.
 2623    Either there was alert history or there wasn’t, either way, the
 2624    return value is SSL_SUCCESS.
 2625
 2626    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 2627    \param h a pointer to a WOLFSSL_ALERT_HISTORY structure that will hold the
 2628    WOLFSSL struct’s alert_history member’s value.
 2629
 2630    _Example_
 2631    \code
 2632    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
 2633    WOLFSSL* ssl = wolfSSL_new(ctx);
 2634    WOLFSSL_ALERT_HISTORY* h;
 2635    ...
 2636    wolfSSL_get_alert_history(ssl, h);
 2637    // h now has a copy of the ssl->alert_history  contents
 2638    \endcode
 2639
 2640    \sa wolfSSL_get_error
 2641*/
 2642int  wolfSSL_get_alert_history(WOLFSSL* ssl, WOLFSSL_ALERT_HISTORY *h);
 2643
 2644/*!
 2645    \ingroup Setup
 2646
 2647    \brief This function sets the session to be used when the SSL object,
 2648    ssl, is used to establish a SSL/TLS connection. For session resumption,
 2649    before calling wolfSSL_shutdown() with your session object, an application
 2650    should save the session ID from the object with a call to
 2651    wolfSSL_get1_session(), which returns a pointer to the session.
 2652    Later, the application should create a new WOLFSSL object and assign
 2653    the saved session with wolfSSL_set_session().  At this point, the
 2654    application may call wolfSSL_connect() and wolfSSL will try to resume
 2655    the session.  The wolfSSL server code allows session resumption by default.
 2656    The object returned by wolfSSL_get1_session() needs to be freed after the
 2657    application is done with it by calling wolfSSL_SESSION_free() on it.
 2658
 2659    \return SSL_SUCCESS will be returned upon successfully setting the session.
 2660    \return SSL_FAILURE will be returned on failure.  This could be caused
 2661    by the session cache being disabled, or if the session has timed out.
 2662
 2663    \return When OPENSSL_EXTRA and WOLFSSL_ERROR_CODE_OPENSSL are defined,
 2664    SSL_SUCCESS will be returned even if the session has timed out.
 2665
 2666    \param ssl pointer to the SSL object, created with wolfSSL_new().
 2667    \param session pointer to the WOLFSSL_SESSION used to set the session
 2668    for ssl.
 2669
 2670    _Example_
 2671    \code
 2672    int ret;
 2673    WOLFSSL* ssl;
 2674    WOLFSSL_SESSION* session;
 2675    ...
 2676    session = wolfSSL_get1_session(ssl);
 2677    if (session == NULL) {
 2678        // failed to get session object from ssl object
 2679    }
 2680    ...
 2681    ret = wolfSSL_set_session(ssl, session);
 2682    if (ret != SSL_SUCCESS) {
 2683    	// failed to set the SSL session
 2684    }
 2685    wolfSSL_SESSION_free(session);
 2686    ...
 2687    \endcode
 2688
 2689    \sa wolfSSL_get1_session
 2690*/
 2691int        wolfSSL_set_session(WOLFSSL* ssl, WOLFSSL_SESSION* session);
 2692
 2693/*!
 2694    \ingroup IO
 2695
 2696    \brief When NO_SESSION_CACHE_REF is defined this function returns a pointer
 2697    to the current session (WOLFSSL_SESSION) used in ssl. This function returns
 2698    a non-persistent pointer to the WOLFSSL_SESSION object. The pointer returned
 2699    will be freed when wolfSSL_free is called. This call should only be used to
 2700    inspect or modify the current session. For session resumption it is
 2701    recommended to use wolfSSL_get1_session(). For backwards compatibility when
 2702    NO_SESSION_CACHE_REF is not defined this function returns a persistent
 2703    session object pointer that is stored in the local cache. The cache size is
 2704    finite and there is a risk that the session object will be overwritten by
 2705    another ssl connection by the time the application calls
 2706    wolfSSL_set_session() on it. It is recommended to define
 2707    NO_SESSION_CACHE_REF in your application and to use wolfSSL_get1_session()
 2708    for session resumption.
 2709
 2710    \return pointer If successful the call will return a pointer to the the
 2711    current SSL session object.
 2712    \return NULL will be returned if ssl is NULL, the SSL session cache is
 2713    disabled, wolfSSL doesn’t have the Session ID available, or mutex
 2714    functions fail.
 2715
 2716    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2717
 2718    _Example_
 2719    \code
 2720    WOLFSSL* ssl;
 2721    WOLFSSL_SESSION* session;
 2722    ...
 2723    session = wolfSSL_get_session(ssl);
 2724    if (session == NULL) {
 2725	    // failed to get session pointer
 2726    }
 2727    ...
 2728    \endcode
 2729
 2730    \sa wolfSSL_get1_session
 2731    \sa wolfSSL_set_session
 2732*/
 2733WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);
 2734
 2735/*!
 2736    \ingroup IO
 2737
 2738    \brief This function flushes session from the session cache which
 2739    have expired. The time, tm, is used for the time comparison. Note
 2740    that wolfSSL currently uses a static table for sessions, so no flushing
 2741    is needed. As such, this function is currently just a stub. This
 2742    function provides OpenSSL compatibility (SSL_flush_sessions) when
 2743    wolfSSL is compiled with the OpenSSL compatibility layer.
 2744
 2745    \return none No returns.
 2746
 2747    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 2748    wolfSSL_CTX_new().
 2749    \param tm time used in session expiration comparison.
 2750
 2751    _Example_
 2752    \code
 2753    WOLFSSL_CTX* ssl;
 2754    ...
 2755    wolfSSL_flush_sessions(ctx, time(0));
 2756    \endcode
 2757
 2758    \sa wolfSSL_get1_session
 2759    \sa wolfSSL_set_session
 2760*/
 2761void       wolfSSL_flush_sessions(WOLFSSL_CTX* ctx, long tm);
 2762
 2763/*!
 2764    \ingroup TLS
 2765
 2766    \brief This function associates the client session with the server id.
 2767    If the newSession flag is on, an existing session won’t be reused.
 2768
 2769    \return SSL_SUCCESS returned if the function executed without error.
 2770    \return BAD_FUNC_ARG returned if the WOLFSSL struct or id parameter
 2771    is NULL or if len is not greater than zero.
 2772
 2773    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 2774    \param id a constant byte pointer that will be copied to the
 2775    serverID member of the WOLFSSL_SESSION structure.
 2776    \param len an int type representing the length of the session id parameter.
 2777    \param newSession an int type representing the flag to denote whether
 2778    to reuse a session or not.
 2779
 2780    _Example_
 2781    \code
 2782    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol );
 2783    WOLFSSL* ssl = WOLFSSL_new(ctx);
 2784    const byte id[MAX_SIZE];  // or dynamically create space
 2785    int len = 0; // initialize length
 2786    int newSession = 0; // flag to allow
 2787    …
 2788    int ret = wolfSSL_SetServerID(ssl, id, len, newSession);
 2789
 2790    if (ret == WOLFSSL_SUCCESS) {
 2791	    // The Id was successfully set
 2792    }
 2793    \endcode
 2794
 2795    \sa wolfSSL_set_session
 2796*/
 2797int        wolfSSL_SetServerID(WOLFSSL* ssl, const unsigned char* id,
 2798                                         int len, int newSession);
 2799
 2800/*!
 2801    \ingroup IO
 2802
 2803    \brief This function gets the session index of the WOLFSSL structure.
 2804
 2805    \return int The function returns an int type representing the
 2806    sessionIndex within the WOLFSSL struct.
 2807
 2808    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 2809
 2810    _Example_
 2811    \code
 2812    WOLFSSL_CTX_new( protocol method );
 2813    WOLFSSL* ssl = WOLFSSL_new(ctx);
 2814    ...
 2815    int sesIdx = wolfSSL_GetSessionIndex(ssl);
 2816
 2817    if(sesIdx < 0 || sesIdx > sizeof(ssl->sessionIndex)/sizeof(int)){
 2818    	// You have an out of bounds index number and something is not right.
 2819    }
 2820    \endcode
 2821
 2822    \sa wolfSSL_GetSessionAtIndex
 2823*/
 2824int wolfSSL_GetSessionIndex(WOLFSSL* ssl);
 2825
 2826/*!
 2827    \ingroup IO
 2828
 2829    \brief This function gets the session at specified index of the session
 2830    cache and copies it into memory. The WOLFSSL_SESSION structure holds
 2831    the session information.
 2832
 2833    \return SSL_SUCCESS returned if the function executed successfully and
 2834    no errors were thrown.
 2835    \return BAD_MUTEX_E returned if there was an unlock or lock mutex error.
 2836    \return SSL_FAILURE returned if the function did not execute successfully.
 2837
 2838    \param index an int type representing the session index.
 2839    \param session a pointer to the WOLFSSL_SESSION structure.
 2840
 2841    _Example_
 2842    \code
 2843    int idx; // The index to locate the session.
 2844    WOLFSSL_SESSION* session;  // Buffer to copy to.
 2845    ...
 2846    if(wolfSSL_GetSessionAtIndex(idx, session) != SSL_SUCCESS){
 2847    	// Failure case.
 2848    }
 2849    \endcode
 2850
 2851    \sa UnLockMutex
 2852    \sa LockMutex
 2853    \sa wolfSSL_GetSessionIndex
 2854*/
 2855int wolfSSL_GetSessionAtIndex(int index, WOLFSSL_SESSION* session);
 2856
 2857/*!
 2858    \ingroup IO
 2859
 2860    \brief Returns the peer certificate chain from the WOLFSSL_SESSION struct.
 2861
 2862    \return pointer A pointer to a WOLFSSL_X509_CHAIN structure that
 2863    contains the peer certification chain.
 2864
 2865    \param session a pointer to a WOLFSSL_SESSION structure.
 2866
 2867    _Example_
 2868    \code
 2869    WOLFSSL_SESSION* session;
 2870    WOLFSSL_X509_CHAIN* chain;
 2871    ...
 2872    chain = wolfSSL_SESSION_get_peer_chain(session);
 2873    if(!chain){
 2874    	// There was no chain. Failure case.
 2875    }
 2876    \endcode
 2877
 2878    \sa wolfSSL_GetSessionAtIndex
 2879    \sa wolfSSL_GetSessionIndex
 2880    \sa AddSession
 2881*/
 2882
 2883    WOLFSSL_X509_CHAIN* wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION* session);
 2884
 2885/*!
 2886    \ingroup Setup
 2887
 2888    \brief This function sets the verification method for remote peers and
 2889    also allows a verify callback to be registered with the SSL context.
 2890    The verify callback will be called only when a verification failure has
 2891    occurred.  If no verify callback is desired, the NULL pointer can be used
 2892    for verify_callback. The verification mode of peer certificates is a
 2893    logically OR’d list of flags.  The possible flag values include:
 2894    SSL_VERIFY_NONE Client mode: the client will not verify the certificate
 2895    received from the server and the handshake will continue as normal.
 2896    Server mode: the server will not send a certificate request to the client.
 2897    As such, client verification will not be enabled. SSL_VERIFY_PEER Client
 2898    mode: the client will verify the certificate received from the server
 2899    during the handshake.  This is turned on by default in wolfSSL, therefore,
 2900    using this option has no effect. Server mode: the server will send a
 2901    certificate request to the client and verify the client certificate
 2902    received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when
 2903    used on the client side. Server mode: the verification will fail on the
 2904    server side if the client fails to send a certificate when requested to
 2905    do so (when using SSL_VERIFY_PEER on the SSL server).
 2906    SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client
 2907    side. Server mode: the verification is the same as
 2908    SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection.
 2909    If a PSK connection is being made then the connection will go through
 2910    without a peer cert.
 2911
 2912    \return none No return.
 2913
 2914    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 2915    \param mode flags indicating verification mode for peer's cert.
 2916    \param verify_callback callback to be called when verification fails.
 2917    If no callback is desired, the NULL pointer can be used for
 2918    verify_callback.
 2919
 2920    _Example_
 2921    \code
 2922    WOLFSSL_CTX*    ctx    = 0;
 2923    ...
 2924    wolfSSL_CTX_set_verify(ctx, (WOLFSSL_VERIFY_PEER |
 2925                           WOLFSSL_VERIFY_FAIL_IF_NO_PEER_CERT), NULL);
 2926    \endcode
 2927
 2928    \sa wolfSSL_set_verify
 2929*/
 2930void wolfSSL_CTX_set_verify(WOLFSSL_CTX* ctx, int mode,
 2931                                      VerifyCallback verify_callback);
 2932
 2933/*!
 2934    \ingroup Setup
 2935
 2936    \brief This function sets the verification method for remote peers and
 2937    also allows a verify callback to be registered with the SSL session.
 2938    The verify callback will be called only when a verification failure has
 2939    occurred. If no verify callback is desired, the NULL pointer can be used
 2940    for verify_callback. The verification mode of peer certificates is a
 2941    logically OR’d list of flags.  The possible flag values include:
 2942    SSL_VERIFY_NONE Client mode: the client will not verify the certificate
 2943    received from the server and the handshake will continue as normal. Server
 2944    mode: the server will not send a certificate request to the client.
 2945    As such, client verification will not be enabled. SSL_VERIFY_PEER Client
 2946    mode: the client will verify the certificate received from the server
 2947    during the handshake. This is turned on by default in wolfSSL, therefore,
 2948    using this option has no effect. Server mode: the server will send a
 2949    certificate request to the client and verify the client certificate
 2950    received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when
 2951    used on the client side. Server mode: the verification will fail on the
 2952    server side if the client fails to send a certificate when requested to do
 2953    so (when using SSL_VERIFY_PEER on the SSL server).
 2954    SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client
 2955    side. Server mode: the verification is the same as
 2956    SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection.
 2957    If a PSK connection is being made then the connection will go through
 2958    without a peer cert.
 2959
 2960    \return none No return.
 2961
 2962    \param ssl pointer to the SSL session, created with wolfSSL_new().
 2963    \param mode flags indicating verification mode for peer's cert.
 2964    \param verify_callback callback to be called when verification fails.
 2965    If no callback is desired, the NULL pointer can
 2966    be used for verify_callback.
 2967
 2968    _Example_
 2969    \code
 2970    WOLFSSL* ssl = 0;
 2971    ...
 2972    wolfSSL_set_verify(ssl, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0);
 2973    \endcode
 2974
 2975    \sa wolfSSL_CTX_set_verify
 2976*/
 2977void wolfSSL_set_verify(WOLFSSL* ssl, int mode, VerifyCallback verify_callback);
 2978
 2979/*!
 2980    \ingroup CertsKeys
 2981
 2982    \brief This function stores user CTX object information for verify callback.
 2983
 2984    \return none No return.
 2985
 2986    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 2987    \param ctx a void pointer that is set to WOLFSSL structure’s verifyCbCtx
 2988    member’s value.
 2989
 2990    _Example_
 2991    \code
 2992    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 2993    WOLFSSL* ssl = wolfSSL_new(ctx);
 2994    (void*)ctx;
 2995    ...
 2996    if(ssl != NULL){
 2997    wolfSSL_SetCertCbCtx(ssl, ctx);
 2998    } else {
 2999	    // Error case, the SSL is not initialized properly.
 3000    }
 3001    \endcode
 3002
 3003    \sa wolfSSL_CTX_save_cert_cache
 3004    \sa wolfSSL_CTX_restore_cert_cache
 3005    \sa wolfSSL_CTX_set_verify
 3006*/
 3007void wolfSSL_SetCertCbCtx(WOLFSSL* ssl, void* ctx);
 3008
 3009/*!
 3010    \ingroup CertsKeys
 3011
 3012    \brief This function stores user CTX object information for verify callback.
 3013
 3014    \return none No return.
 3015
 3016    \param ctx a pointer to a WOLFSSL_CTX structure.
 3017    \param userCtx a void pointer that is used to set WOLFSSL_CTX structure’s
 3018    verifyCbCtx member’s value.
 3019
 3020    _Example_
 3021    \code
 3022    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 3023    void* userCtx = NULL; // Assign some user defined context
 3024    ...
 3025    if(ctx != NULL){
 3026        wolfSSL_SetCertCbCtx(ctx, userCtx);
 3027    } else {
 3028        // Error case, the SSL is not initialized properly.
 3029    }
 3030    \endcode
 3031
 3032    \sa wolfSSL_CTX_save_cert_cache
 3033    \sa wolfSSL_CTX_restore_cert_cache
 3034    \sa wolfSSL_CTX_set_verify
 3035*/
 3036void wolfSSL_CTX_SetCertCbCtx(WOLFSSL_CTX* ctx, void* userCtx);
 3037
 3038/*!
 3039    \ingroup IO
 3040
 3041    \brief This function returns the number of bytes which are buffered and
 3042    available in the SSL object to be read by wolfSSL_read().
 3043
 3044    \return int This function returns the number of bytes pending.
 3045
 3046    \param ssl pointer to the SSL session, created with wolfSSL_new().
 3047
 3048    _Example_
 3049    \code
 3050    int pending = 0;
 3051    WOLFSSL* ssl = 0;
 3052    ...
 3053
 3054    pending = wolfSSL_pending(ssl);
 3055    printf(“There are %d bytes buffered and available for reading”, pending);
 3056    \endcode
 3057
 3058    \sa wolfSSL_recv
 3059    \sa wolfSSL_read
 3060    \sa wolfSSL_peek
 3061*/
 3062int  wolfSSL_pending(WOLFSSL* ssl);
 3063
 3064/*!
 3065    \ingroup Debug
 3066
 3067    \brief This function is for OpenSSL compatibility (SSL_load_error_string)
 3068    only and takes no action.
 3069
 3070    \return none No returns.
 3071
 3072    \param none No parameters.
 3073
 3074    _Example_
 3075    \code
 3076    wolfSSL_load_error_strings();
 3077    \endcode
 3078
 3079    \sa wolfSSL_get_error
 3080    \sa wolfSSL_ERR_error_string
 3081    \sa wolfSSL_ERR_error_string_n
 3082    \sa wolfSSL_ERR_print_errors_fp
 3083    \sa wolfSSL_load_error_strings
 3084*/
 3085void wolfSSL_load_error_strings(void);
 3086
 3087/*!
 3088    \ingroup TLS
 3089
 3090    \brief This function is called internally in wolfSSL_CTX_new(). This
 3091    function is a wrapper around wolfSSL_Init() and exists for OpenSSL
 3092    compatibility (SSL_library_init) when wolfSSL has been compiled with
 3093    OpenSSL compatibility layer.  wolfSSL_Init() is the more typically-used
 3094    wolfSSL initialization function.
 3095
 3096    \return SSL_SUCCESS If successful the call will return.
 3097    \return SSL_FATAL_ERROR is returned upon failure.
 3098
 3099    \param none No parameters.
 3100
 3101    _Example_
 3102    \code
 3103    int ret = 0;
 3104    ret = wolfSSL_library_init();
 3105    if (ret != SSL_SUCCESS) {
 3106	    failed to initialize wolfSSL
 3107    }
 3108    ...
 3109    \endcode
 3110
 3111    \sa wolfSSL_Init
 3112    \sa wolfSSL_Cleanup
 3113*/
 3114int  wolfSSL_library_init(void);
 3115
 3116/*!
 3117    \brief This function sets the Device Id at the WOLFSSL session level.
 3118
 3119    \return WOLFSSL_SUCCESS upon success.
 3120    \return BAD_FUNC_ARG if ssl is NULL.
 3121
 3122    \param ssl pointer to a SSL object, created with wolfSSL_new().
 3123    \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
 3124
 3125    _Example_
 3126    \code
 3127    WOLFSSL* ssl;
 3128    int DevId = -2;
 3129
 3130    wolfSSL_SetDevId(ssl, devId);
 3131
 3132    \endcode
 3133
 3134    \sa wolfSSL_CTX_SetDevId
 3135    \sa wolfSSL_CTX_GetDevId
 3136*/
 3137int wolfSSL_SetDevId(WOLFSSL* ssl, int devId);
 3138
 3139/*!
 3140    \brief This function sets the Device Id at the WOLFSSL_CTX context level.
 3141
 3142    \return WOLFSSL_SUCCESS upon success.
 3143    \return BAD_FUNC_ARG if ssl is NULL.
 3144
 3145    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 3146    \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
 3147
 3148    _Example_
 3149    \code
 3150    WOLFSSL_CTX* ctx;
 3151    int DevId = -2;
 3152
 3153    wolfSSL_CTX_SetDevId(ctx, devId);
 3154
 3155    \endcode
 3156
 3157    \sa wolfSSL_SetDevId
 3158    \sa wolfSSL_CTX_GetDevId
 3159*/
 3160int wolfSSL_CTX_SetDevId(WOLFSSL_CTX* ctx, int devId);
 3161
 3162/*!
 3163    \brief This function retrieves the Device Id.
 3164
 3165    \return devId upon success.
 3166    \return INVALID_DEVID if both ssl and ctx are NULL.
 3167
 3168    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 3169    \param ssl pointer to a SSL object, created with wolfSSL_new().
 3170
 3171    _Example_
 3172    \code
 3173    WOLFSSL_CTX* ctx;
 3174
 3175    wolfSSL_CTX_GetDevId(ctx, ssl);
 3176
 3177    \endcode
 3178
 3179    \sa wolfSSL_SetDevId
 3180    \sa wolfSSL_CTX_SetDevId
 3181
 3182*/
 3183int wolfSSL_CTX_GetDevId(WOLFSSL_CTX* ctx, WOLFSSL* ssl);
 3184
 3185/*!
 3186    \ingroup Setup
 3187
 3188    \brief This function enables or disables SSL session caching.
 3189    Behavior depends on the value used for mode. The following values
 3190    for mode are available: SSL_SESS_CACHE_OFF- disable session caching.
 3191    Session caching is turned on by default. SSL_SESS_CACHE_NO_AUTO_CLEAR -
 3192    Disable auto-flushing of the session cache. Auto-flushing is turned on
 3193    by default.
 3194
 3195    \return SSL_SUCCESS will be returned upon success.
 3196
 3197    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 3198    \param mode modifier used to change behavior of the session cache.
 3199
 3200    _Example_
 3201    \code
 3202    WOLFSSL_CTX* ctx = 0;
 3203    ...
 3204    ret = wolfSSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_OFF);
 3205    if (ret != SSL_SUCCESS) {
 3206    	// failed to turn SSL session caching off
 3207    }
 3208    \endcode
 3209
 3210    \sa wolfSSL_flush_sessions
 3211    \sa wolfSSL_get1_session
 3212    \sa wolfSSL_set_session
 3213    \sa wolfSSL_get_sessionID
 3214    \sa wolfSSL_CTX_set_timeout
 3215*/
 3216long wolfSSL_CTX_set_session_cache_mode(WOLFSSL_CTX* ctx, long mode);
 3217
 3218/*!
 3219    \brief This function sets the session secret callback function. The
 3220    SessionSecretCb type has the signature: int (*SessionSecretCb)(WOLFSSL* ssl,
 3221    void* secret, int* secretSz, void* ctx). The sessionSecretCb member of
 3222    the WOLFSSL struct is set to the parameter cb.
 3223
 3224    \return SSL_SUCCESS returned if the execution of the function did not
 3225    return an error.
 3226    \return SSL_FATAL_ERROR returned if the WOLFSSL structure is NULL.
 3227
 3228    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3229    \param cb a SessionSecretCb type that is a function pointer with the above
 3230    signature.
 3231    \param ctx a pointer to the user context to be stored
 3232
 3233    _Example_
 3234    \code
 3235    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 3236    WOLFSSL* ssl = wolfSSL_new(ctx);
 3237    // Signature of SessionSecretCb
 3238    int SessionSecretCB (WOLFSSL* ssl, void* secret, int* secretSz,
 3239    void* ctx) = SessionSecretCb;
 3240    …
 3241    int wolfSSL_set_session_secret_cb(ssl, SessionSecretCB, (void*)ssl->ctx){
 3242	    // Function body.
 3243    }
 3244    \endcode
 3245
 3246    \sa SessionSecretCb
 3247*/
 3248int  wolfSSL_set_session_secret_cb(WOLFSSL* ssl, SessionSecretCb cb, void* ctx);
 3249
 3250/*!
 3251    \ingroup IO
 3252
 3253    \brief This function persists the session cache to file. It doesn’t use
 3254    memsave because of additional memory use.
 3255
 3256    \return SSL_SUCCESS returned if the function executed without error.
 3257    The session cache has been written to a file.
 3258    \return SSL_BAD_FILE returned if fname cannot be opened or is otherwise
 3259    corrupt.
 3260    \return FWRITE_ERROR returned if XFWRITE failed to write to the file.
 3261    \return BAD_MUTEX_E returned if there was a mutex lock failure.
 3262
 3263    \param fname is a constant char pointer that points to a file for writing.
 3264
 3265    _Example_
 3266    \code
 3267    const char* fname;
 3268    ...
 3269    if(wolfSSL_save_session_cache(fname) != SSL_SUCCESS){
 3270    	// Fail to write to file.
 3271    }
 3272    \endcode
 3273
 3274    \sa XFWRITE
 3275    \sa wolfSSL_restore_session_cache
 3276    \sa wolfSSL_memrestore_session_cache
 3277*/
 3278int  wolfSSL_save_session_cache(const char* fname);
 3279
 3280/*!
 3281    \ingroup IO
 3282
 3283    \brief This function restores the persistent session cache from file. It
 3284    does not use memstore because of additional memory use.
 3285
 3286    \return SSL_SUCCESS returned if the function executed without error.
 3287    \return SSL_BAD_FILE returned if the file passed into the function was
 3288    corrupted and could not be opened by XFOPEN.
 3289    \return FREAD_ERROR returned if the file had a read error from XFREAD.
 3290    \return CACHE_MATCH_ERROR returned if the session cache header match
 3291    failed.
 3292    \return BAD_MUTEX_E returned if there was a mutex lock failure.
 3293
 3294    \param fname a constant char pointer file input that will be read.
 3295
 3296    _Example_
 3297    \code
 3298    const char *fname;
 3299    ...
 3300    if(wolfSSL_restore_session_cache(fname) != SSL_SUCCESS){
 3301        // Failure case. The function did not return SSL_SUCCESS.
 3302    }
 3303    \endcode
 3304
 3305    \sa XFREAD
 3306    \sa XFOPEN
 3307*/
 3308int  wolfSSL_restore_session_cache(const char* fname);
 3309
 3310/*!
 3311    \ingroup IO
 3312
 3313    \brief This function persists session cache to memory.
 3314
 3315    \return SSL_SUCCESS returned if the function executed without error.
 3316    The session cache has been successfully persisted to memory.
 3317    \return BAD_MUTEX_E returned if there was a mutex lock error.
 3318    \return BUFFER_E returned if the buffer size was too small.
 3319
 3320    \param mem a void pointer representing the destination for the memory
 3321    copy, XMEMCPY().
 3322    \param sz an int type representing the size of mem.
 3323
 3324    _Example_
 3325    \code
 3326    void* mem;
 3327    int sz; // Max size of the memory buffer.
 3328    …
 3329    if(wolfSSL_memsave_session_cache(mem, sz) != SSL_SUCCESS){
 3330    	// Failure case, you did not persist the session cache to memory
 3331    }
 3332    \endcode
 3333
 3334    \sa XMEMCPY
 3335    \sa wolfSSL_get_session_cache_memsize
 3336*/
 3337int  wolfSSL_memsave_session_cache(void* mem, int sz);
 3338
 3339/*!
 3340    \ingroup IO
 3341
 3342    \brief This function restores the persistent session cache from memory.
 3343
 3344    \return SSL_SUCCESS returned if the function executed without an error.
 3345    \return BUFFER_E returned if the memory buffer is too small.
 3346    \return BAD_MUTEX_E returned if the session cache mutex lock failed.
 3347    \return CACHE_MATCH_ERROR returned if the session cache header match
 3348    failed.
 3349
 3350    \param mem a constant void pointer containing the source of the
 3351    restoration.
 3352    \param sz an integer representing the size of the memory buffer.
 3353
 3354    _Example_
 3355    \code
 3356    const void* memoryFile;
 3357    int szMf;
 3358    ...
 3359    if(wolfSSL_memrestore_session_cache(memoryFile, szMf) != SSL_SUCCESS){
 3360    	// Failure case. SSL_SUCCESS was not returned.
 3361    }
 3362    \endcode
 3363
 3364    \sa wolfSSL_save_session_cache
 3365*/
 3366int  wolfSSL_memrestore_session_cache(const void* mem, int sz);
 3367
 3368/*!
 3369    \ingroup IO
 3370
 3371    \brief This function returns how large the session cache save buffer
 3372    should be.
 3373
 3374    \return int This function returns an integer that represents the size of
 3375    the session cache save buffer.
 3376
 3377    \param none No parameters.
 3378
 3379    _Example_
 3380    \code
 3381    int sz = // Minimum size for error checking;
 3382    ...
 3383    if(sz < wolfSSL_get_session_cache_memsize()){
 3384        // Memory buffer is too small
 3385    }
 3386    \endcode
 3387
 3388    \sa wolfSSL_memrestore_session_cache
 3389*/
 3390int  wolfSSL_get_session_cache_memsize(void);
 3391
 3392/*!
 3393    \ingroup CertsKeys
 3394
 3395    \brief This function writes the cert cache from memory to file.
 3396
 3397    \return SSL_SUCCESS if CM_SaveCertCache exits normally.
 3398    \return BAD_FUNC_ARG is returned if either of the arguments are NULL.
 3399    \return SSL_BAD_FILE if the cert cache save file could not be opened.
 3400    \return BAD_MUTEX_E if the lock mutex failed.
 3401    \return MEMORY_E the allocation of memory failed.
 3402    \return FWRITE_ERROR Certificate cache file write failed.
 3403
 3404    \param ctx a pointer to a WOLFSSL_CTX structure, holding the
 3405    certificate information.
 3406    \param fname  a constant char pointer that points to a file for writing.
 3407
 3408    _Example_
 3409    \code
 3410    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def );
 3411    const char* fname;
 3412    ...
 3413    if(wolfSSL_CTX_save_cert_cache(ctx, fname)){
 3414	    // file was written.
 3415    }
 3416    \endcode
 3417
 3418    \sa CM_SaveCertCache
 3419    \sa DoMemSaveCertCache
 3420*/
 3421int  wolfSSL_CTX_save_cert_cache(WOLFSSL_CTX* ctx, const char* fname);
 3422
 3423/*!
 3424    \ingroup CertsKeys
 3425
 3426    \brief This function persistes certificate cache from a file.
 3427
 3428    \return SSL_SUCCESS returned if the function, CM_RestoreCertCache,
 3429    executes normally.
 3430    \return SSL_BAD_FILE returned if XFOPEN returns XBADFILE. The file is
 3431    corrupted.
 3432    \return MEMORY_E returned if the allocated memory for the temp buffer
 3433    fails.
 3434    \return BAD_FUNC_ARG returned if fname or ctx have a NULL value.
 3435
 3436    \param ctx a pointer to a WOLFSSL_CTX structure, holding the certificate
 3437    information.
 3438    \param fname a constant char pointer that points to a file for reading.
 3439
 3440    _Example_
 3441    \code
 3442    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 3443    WOLFSSL* ssl = wolfSSL_new(ctx);
 3444    const char* fname = "path to file";
 3445    ...
 3446    if(wolfSSL_CTX_restore_cert_cache(ctx, fname)){
 3447    	// check to see if the execution was successful
 3448    }
 3449    \endcode
 3450
 3451    \sa CM_RestoreCertCache
 3452    \sa XFOPEN
 3453*/
 3454int  wolfSSL_CTX_restore_cert_cache(WOLFSSL_CTX* ctx, const char* fname);
 3455
 3456/*!
 3457    \ingroup CertsKeys
 3458
 3459    \brief This function persists the certificate cache to memory.
 3460
 3461    \return SSL_SUCCESS returned on successful execution of the function.
 3462    No errors were thrown.
 3463    \return BAD_MUTEX_E mutex error where the WOLFSSL_CERT_MANAGER member
 3464    caLock was not 0 (zero).
 3465    \return BAD_FUNC_ARG returned if ctx, mem, or used is NULL or if sz
 3466    is less than or equal to 0 (zero).
 3467    \return BUFFER_E output buffer mem was too small.
 3468
 3469    \param ctx a pointer to a WOLFSSL_CTX structure, created
 3470    using wolfSSL_CTX_new().
 3471    \param mem a void pointer to the destination (output buffer).
 3472    \param sz the size of the output buffer.
 3473    \param used a pointer to size of the cert cache header.
 3474
 3475    _Example_
 3476    \code
 3477    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol );
 3478    void* mem;
 3479    int sz;
 3480    int* used;
 3481    ...
 3482    if(wolfSSL_CTX_memsave_cert_cache(ctx, mem, sz, used) != SSL_SUCCESS){
 3483	    // The function returned with an error
 3484    }
 3485    \endcode
 3486
 3487    \sa DoMemSaveCertCache
 3488    \sa GetCertCacheMemSize
 3489    \sa CM_MemRestoreCertCache
 3490    \sa CM_GetCertCacheMemSize
 3491*/
 3492int  wolfSSL_CTX_memsave_cert_cache(WOLFSSL_CTX* ctx, void* mem, int sz, int* used);
 3493
 3494/*!
 3495    \ingroup Setup
 3496
 3497    \brief This function restores the certificate cache from memory.
 3498
 3499    \return SSL_SUCCESS returned if the function and subroutines
 3500    executed without an error.
 3501    \return BAD_FUNC_ARG returned if the ctx or mem parameters are
 3502    NULL or if the sz parameter is less than or equal to zero.
 3503    \return BUFFER_E returned if the cert cache memory buffer is too small.
 3504    \return CACHE_MATCH_ERROR returned if there was a cert cache
 3505    header mismatch.
 3506    \return BAD_MUTEX_E returned if the lock mutex on failed.
 3507
 3508    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 3509    wolfSSL_CTX_new().
 3510    \param mem a void pointer with a value that will be restored to
 3511    the certificate cache.
 3512    \param sz an int type that represents the size of the mem parameter.
 3513
 3514    _Example_
 3515    \code
 3516    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
 3517    WOLFSSL* ssl = WOLFSSL_new(ctx);
 3518    void* mem;
 3519    int sz = (*int) sizeof(mem);
 3520    …
 3521    if(wolfSSL_CTX_memrestore_cert_cache(ssl->ctx, mem, sz)){
 3522    	// The success case
 3523    }
 3524    \endcode
 3525
 3526    \sa CM_MemRestoreCertCache
 3527*/
 3528int  wolfSSL_CTX_memrestore_cert_cache(WOLFSSL_CTX* ctx, const void* mem, int sz);
 3529
 3530/*!
 3531    \ingroup CertsKeys
 3532
 3533    \brief Returns the size the certificate cache save buffer needs to be.
 3534
 3535    \return int integer value returned representing the memory size
 3536    upon success.
 3537    \return BAD_FUNC_ARG is returned if the WOLFSSL_CTX struct is NULL.
 3538    \return BAD_MUTEX_E - returned if there was a mutex lock error.
 3539
 3540    \param ctx a pointer to a wolfSSL_CTX structure, created using
 3541    wolfSSL_CTX_new().
 3542
 3543    _Example_
 3544    \code
 3545    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol);
 3546    ...
 3547    int certCacheSize = wolfSSL_CTX_get_cert_cache_memsize(ctx);
 3548
 3549    if(certCacheSize != BAD_FUNC_ARG || certCacheSize != BAD_MUTEX_E){
 3550	// Successfully retrieved the memory size.
 3551    }
 3552    \endcode
 3553
 3554    \sa CM_GetCertCacheMemSize
 3555*/
 3556int  wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX* ctx);
 3557
 3558/*!
 3559    \ingroup Setup
 3560
 3561    \brief This function sets the cipher suite list for a given WOLFSSL_CTX.
 3562    The list becomes the default cipher suite list for any new WOLFSSL
 3563    sessions created from the context, and the order in the string is the
 3564    local preference order from highest to lowest. Each call replaces the
 3565    previous list. The list is a null-terminated, colon-delimited text
 3566    string of suite names and/or OpenSSL-style group keywords, for example
 3567    "TLS13-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-SHA256".
 3568
 3569    Each token in the colon-delimited list is one of the following:
 3570
 3571    1. A specific cipher suite name. wolfSSL accepts both its own short name
 3572       and the IANA name (when WOLFSSL_NO_ERROR_STRINGS is not defined). For
 3573       example "ECDHE-RSA-AES128-GCM-SHA256" and
 3574       "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" are equivalent. The complete
 3575       authoritative list of accepted names lives in the cipher_names[] array
 3576       in src/internal.c; programs may also enumerate the suites compiled
 3577       into the current build at runtime via wolfSSL_get_ciphers().
 3578
 3579    2. An OpenSSL-compatible keyword that selects a family of suites or
 3580       toggles a class on/off (see the keyword table below). Some keywords
 3581       require OPENSSL_EXTRA or OPENSSL_ALL to be defined.
 3582
 3583    3. A negated keyword "!keyword" to disallow a class (requires
 3584       OPENSSL_EXTRA or OPENSSL_ALL). For example "HIGH:!aNULL".
 3585
 3586    A "+" operator (e.g. "ECDHE+AESGCM") is recognized only to extract the
 3587    leading public-key family token ("ECDHE", "RSA" or "DHE"); trailing parts
 3588    after "+" are ignored by wolfSSL. To intersect with a specific cipher
 3589    use the explicit suite name instead.
 3590
 3591    OpenSSL-compatible group keywords:
 3592
 3593    | Keyword           | Effect                                                       | Required build option |
 3594    | ----------------- | ------------------------------------------------------------ | --------------------- |
 3595    | DEFAULT / ALL     | Include all built suites; "ALL" also enables anonymous (aNULL) | OPENSSL_EXTRA / OPENSSL_ALL (also accepted as the entire string with no other tokens) |
 3596    | HIGH              | All suites except static, anonymous, and NULL ciphers        | OPENSSL_EXTRA / OPENSSL_ALL (also accepted as the entire string with no other tokens) |
 3597    | LOW / MEDIUM      | Accepted but do not restrict by bit size; behave as "RSA"    | OPENSSL_EXTRA / OPENSSL_ALL |
 3598    | aNULL             | Anonymous (no authentication) suites                         | OPENSSL_EXTRA / OPENSSL_ALL; suites require HAVE_ANON |
 3599    | eNULL / NULL      | Null encryption suites                                       | OPENSSL_EXTRA / OPENSSL_ALL; suites require HAVE_NULL_CIPHER |
 3600    | kDH               | Static DH key exchange                                       | OPENSSL_EXTRA / OPENSSL_ALL |
 3601    | DHE / EDH         | Ephemeral DH key exchange                                    | OPENSSL_EXTRA / OPENSSL_ALL; suites require !NO_DH |
 3602    | ECDHE / EECDH     | Ephemeral ECDH key exchange                                  | OPENSSL_EXTRA / OPENSSL_ALL; suites require HAVE_ECC |
 3603    | kRSA / RSA        | Static RSA key exchange                                      | OPENSSL_EXTRA / OPENSSL_ALL; suites require !NO_RSA |
 3604    | PSK               | Pre-shared-key suites                                        | OPENSSL_EXTRA / OPENSSL_ALL; suites require !NO_PSK |
 3605    | DSS               | Silently ignored — wolfSSL has no DSA ciphersuites           | OPENSSL_EXTRA / OPENSSL_ALL |
 3606    | EXP / EXPORT      | Silently ignored — export-grade ciphers are not supported    | OPENSSL_EXTRA / OPENSSL_ALL |
 3607    | AES128 / SHA1 / RC4 | When negated ("!AES128", etc.), disable that class         | WOLFSSL_SYS_CRYPTO_POLICY |
 3608    | @SECLEVEL=n       | Set OpenSSL-compatible security level                        | WOLFSSL_SYS_CRYPTO_POLICY |
 3609
 3610    Representative TLS 1.3 cipher suite names (each guarded by its own
 3611    BUILD_* macro; most are enabled automatically by --enable-tls13):
 3612
 3613    | Name (wolfSSL)               | IANA name                       | Required build option |
 3614    | ---------------------------- | ------------------------------- | --------------------- |
 3615    | TLS13-AES128-GCM-SHA256      | TLS_AES_128_GCM_SHA256          | BUILD_TLS_AES_128_GCM_SHA256 (default with TLS 1.3) |
 3616    | TLS13-AES256-GCM-SHA384      | TLS_AES_256_GCM_SHA384          | BUILD_TLS_AES_256_GCM_SHA384 |
 3617    | TLS13-CHACHA20-POLY1305-SHA256 | TLS_CHACHA20_POLY1305_SHA256  | BUILD_TLS_CHACHA20_POLY1305_SHA256 (HAVE_CHACHA + HAVE_POLY1305) |
 3618    | TLS13-AES128-CCM-SHA256      | TLS_AES_128_CCM_SHA256          | BUILD_TLS_AES_128_CCM_SHA256 (HAVE_AESCCM) |
 3619    | TLS13-AES128-CCM-8-SHA256    | TLS_AES_128_CCM_8_SHA256        | BUILD_TLS_AES_128_CCM_8_SHA256 (HAVE_AESCCM) |
 3620    | TLS13-SM4-GCM-SM3            | TLS_SM4_GCM_SM3                 | BUILD_TLS_SM4_GCM_SM3 (WOLFSSL_SM4_GCM + WOLFSSL_SM3) |
 3621    | TLS13-SM4-CCM-SM3            | TLS_SM4_CCM_SM3                 | BUILD_TLS_SM4_CCM_SM3 (WOLFSSL_SM4_CCM + WOLFSSL_SM3) |
 3622    | TLS13-SHA256-SHA256          | TLS_SHA256_SHA256               | BUILD_TLS_SHA256_SHA256 (integrity-only) |
 3623    | TLS13-SHA384-SHA384          | TLS_SHA384_SHA384               | BUILD_TLS_SHA384_SHA384 |
 3624
 3625    Representative TLS 1.2 cipher suite name families (each individual suite
 3626    is guarded by its own BUILD_* macro derived from the IANA name; the
 3627    common build-option requirements are summarized below):
 3628
 3629    | Name family / example                         | Typical requirements |
 3630    | --------------------------------------------- | -------------------- |
 3631    | ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305 | HAVE_ECC, HAVE_AESGCM (or HAVE_CHACHA + HAVE_POLY1305) |
 3632    | ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305 | HAVE_ECC, !NO_RSA, HAVE_AESGCM (or HAVE_CHACHA + HAVE_POLY1305) |
 3633    | DHE-RSA-AES128-GCM-SHA256, DHE-RSA-AES256-GCM-SHA384, DHE-RSA-CHACHA20-POLY1305 | !NO_DH, !NO_RSA, HAVE_AESGCM (or HAVE_CHACHA + HAVE_POLY1305) |
 3634    | AES128-SHA, AES256-SHA, AES128-SHA256, AES256-SHA256, AES128-GCM-SHA256, AES256-GCM-SHA384 (static-RSA) | !NO_RSA, !NO_AES_CBC and/or HAVE_AESGCM |
 3635    | DES-CBC3-SHA, RC4-SHA, RC4-MD5                | Legacy: !NO_DES3 / !NO_RC4, !NO_OLD_TLS |
 3636    | NULL-SHA, NULL-SHA256, NULL-MD5               | HAVE_NULL_CIPHER |
 3637    | PSK-AES128-CBC-SHA256, PSK-AES256-GCM-SHA384, ECDHE-PSK-AES128-CBC-SHA256, DHE-PSK-AES256-GCM-SHA384 | !NO_PSK (HAVE_ECC for ECDHE-PSK, !NO_DH for DHE-PSK) |
 3638    | ADH-AES128-SHA, ADH-AES256-SHA                | HAVE_ANON |
 3639    | ECDHE-ECDSA-SM4-GCM-SM3, ECDHE-ECDSA-SM4-CCM-SM3 | WOLFSSL_SM2, WOLFSSL_SM3, WOLFSSL_SM4_GCM/WOLFSSL_SM4_CCM |
 3640
 3641    Notes:
 3642    - TLS 1.3 suite names and TLS 1.2 suite names may be mixed in the same
 3643      list; wolfSSL groups them by version internally.
 3644    - For DTLS, RC4-based stream ciphers in the list are silently dropped.
 3645    - When set as the literal whole-string "DEFAULT", "ALL", "HIGH", or the
 3646      empty string, wolfSSL installs its built-in default suite list and
 3647      returns success without parsing further tokens.
 3648
 3649    \return WOLFSSL_SUCCESS will be returned upon successful function completion.
 3650    \return WOLFSSL_FAILURE will be returned on failure.
 3651
 3652    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 3653    \param list null-terminated text string and a colon-delimited list of
 3654    cipher suites and/or keywords to use with the specified SSL context.
 3655
 3656    _Example_
 3657    \code
 3658    WOLFSSL_CTX* ctx = 0;
 3659    ...
 3660    ret = wolfSSL_CTX_set_cipher_list(ctx,
 3661        "TLS13-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
 3662        "DHE-RSA-AES256-SHA256");
 3663    if (ret != WOLFSSL_SUCCESS) {
 3664        // failed to set cipher suite list
 3665    }
 3666    \endcode
 3667
 3668    \sa wolfSSL_set_cipher_list
 3669    \sa wolfSSL_get_ciphers
 3670    \sa wolfSSL_get_cipher_list
 3671    \sa wolfSSL_CTX_new
 3672*/
 3673int  wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX* ctx, const char* list);
 3674
 3675/*!
 3676    \ingroup Setup
 3677
 3678    \brief This function sets the cipher suite list for a given WOLFSSL
 3679    session. The list format and the set of recognized suite names and
 3680    keywords are identical to those documented for wolfSSL_CTX_set_cipher_list();
 3681    refer to that function for the full keyword/suite tables and required
 3682    build options. Each call replaces the previous list on the session.
 3683
 3684    \return WOLFSSL_SUCCESS will be returned upon successful function completion.
 3685    \return WOLFSSL_FAILURE will be returned on failure.
 3686
 3687    \param ssl pointer to the SSL session, created with wolfSSL_new().
 3688    \param list null-terminated text string and a colon-delimited list of
 3689    cipher suites and/or keywords to use with the specified SSL session.
 3690
 3691    _Example_
 3692    \code
 3693    int ret = 0;
 3694    WOLFSSL* ssl = 0;
 3695    ...
 3696    ret = wolfSSL_set_cipher_list(ssl,
 3697        "TLS13-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:"
 3698        "DHE-RSA-AES256-SHA256");
 3699    if (ret != WOLFSSL_SUCCESS) {
 3700        // failed to set cipher suite list
 3701    }
 3702    \endcode
 3703
 3704    \sa wolfSSL_CTX_set_cipher_list
 3705    \sa wolfSSL_get_ciphers
 3706    \sa wolfSSL_get_cipher_list
 3707    \sa wolfSSL_new
 3708*/
 3709int  wolfSSL_set_cipher_list(WOLFSSL* ssl, const char* list);
 3710
 3711/*!
 3712    \brief This function informs the WOLFSSL DTLS object that the underlying
 3713     UDP I/O is non-blocking. After an application creates a WOLFSSL object,
 3714     if it will be used with a non-blocking UDP socket, call
 3715    wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know
 3716     that receiving EWOULDBLOCK means that the recvfrom call would
 3717    block rather than that it timed out.
 3718
 3719    \return none No return.
 3720
 3721    \param ssl pointer to the DTLS session, created with wolfSSL_new().
 3722    \param nonblock value used to set non-blocking flag on WOLFSSL object.
 3723    Use 1 to specify non-blocking, otherwise 0.
 3724
 3725    _Example_
 3726    \code
 3727    WOLFSSL* ssl = 0;
 3728    ...
 3729    wolfSSL_dtls_set_using_nonblock(ssl, 1);
 3730    \endcode
 3731
 3732    \sa wolfSSL_dtls_get_using_nonblock
 3733    \sa wolfSSL_dtls_got_timeout
 3734    \sa wolfSSL_dtls_get_current_timeout
 3735*/
 3736void wolfSSL_dtls_set_using_nonblock(WOLFSSL* ssl, int nonblock);
 3737/*!
 3738    \brief This function allows the application to determine if wolfSSL is
 3739    using non-blocking I/O with UDP. If wolfSSL is using non-blocking I/O, this
 3740    function will return 1, otherwise 0. After an application creates a
 3741    WOLFSSL object, if it will be used with a non-blocking UDP socket, call
 3742    wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know
 3743    that receiving EWOULDBLOCK means that the recvfrom call would block
 3744    rather than that it timed out. This function is only meaningful to DTLS
 3745    sessions.
 3746
 3747    \return 0 underlying I/O is blocking.
 3748    \return 1 underlying I/O is non-blocking.
 3749
 3750    \param ssl pointer to the DTLS session, created with wolfSSL_new().
 3751
 3752    _Example_
 3753    \code
 3754    int ret = 0;
 3755    WOLFSSL* ssl = 0;
 3756    ...
 3757    ret = wolfSSL_dtls_get_using_nonblock(ssl);
 3758    if (ret == 1) {
 3759    	// underlying I/O is non-blocking
 3760    }
 3761    ...
 3762    \endcode
 3763
 3764    \sa wolfSSL_dtls_set_using_nonblock
 3765    \sa wolfSSL_dtls_got_timeout
 3766    \sa wolfSSL_dtls_set_using_nonblock
 3767*/
 3768int  wolfSSL_dtls_get_using_nonblock(WOLFSSL* ssl);
 3769/*!
 3770    \brief This function returns the current timeout value in seconds for
 3771    the WOLFSSL object. When using non-blocking sockets, something in the user
 3772    code needs to decide when to check for available recv data and how long
 3773    it has been waiting. The value returned by this function indicates how
 3774    long the application should wait.
 3775
 3776    \return seconds The current DTLS timeout value in seconds
 3777    \return NOT_COMPILED_IN if wolfSSL was not built with DTLS support.
 3778
 3779    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3780
 3781    _Example_
 3782    \code
 3783    int timeout = 0;
 3784    WOLFSSL* ssl;
 3785    ...
 3786    timeout = wolfSSL_get_dtls_current_timeout(ssl);
 3787    printf(“DTLS timeout (sec) = %d\n”, timeout);
 3788    \endcode
 3789
 3790    \sa wolfSSL_dtls
 3791    \sa wolfSSL_dtls_get_peer
 3792    \sa wolfSSL_dtls_got_timeout
 3793    \sa wolfSSL_dtls_set_peer
 3794*/
 3795int  wolfSSL_dtls_get_current_timeout(WOLFSSL* ssl);
 3796/*!
 3797    \brief This function returns true if the application should setup a quicker
 3798    timeout. When using non-blocking sockets, something in the user code needs
 3799    to decide when to check for available data and how long it needs to wait. If
 3800    this function returns true, it means that the library already detected some
 3801    disruption in the communication, but it wants to wait for a little longer in
 3802    case some messages from the other peers are still in flight. Is up to the
 3803    application to fine tune the value of this timer, a good one may be
 3804    dtls_get_current_timeout() / 4.
 3805
 3806    \return true if the application code should setup a quicker timeout
 3807
 3808    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3809
 3810    \sa wolfSSL_dtls
 3811    \sa wolfSSL_dtls_get_peer
 3812    \sa wolfSSL_dtls_got_timeout
 3813    \sa wolfSSL_dtls_set_peer
 3814    \sa wolfSSL_dtls13_set_send_more_acks
 3815*/
 3816int  wolfSSL_dtls13_use_quick_timeout(WOLFSSL *ssl);
 3817/*!
 3818  \ingroup Setup
 3819
 3820    \brief This function sets whether the library should send ACKs to the other
 3821    peer immediately when detecting disruption or not. Sending ACKs immediately
 3822    assures minimum latency but it may consume more bandwidth than necessary. If
 3823    the application manages the timer by itself and this option is set to 0 then
 3824    application code can use wolfSSL_dtls13_use_quick_timeout() to determine if
 3825    it should setup a quicker timeout to send those delayed ACKs.
 3826
 3827    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3828    \param value 1 to set the option, 0 to disable the option
 3829
 3830    \sa wolfSSL_dtls
 3831    \sa wolfSSL_dtls_get_peer
 3832    \sa wolfSSL_dtls_got_timeout
 3833    \sa wolfSSL_dtls_set_peer
 3834    \sa wolfSSL_dtls13_use_quick_timeout
 3835*/
 3836void  wolfSSL_dtls13_set_send_more_acks(WOLFSSL *ssl, int value);
 3837
 3838/*!
 3839    \ingroup Setup
 3840
 3841    \brief This function sets the dtls timeout.
 3842
 3843    \return SSL_SUCCESS returned if the function executes without an error.
 3844    The dtls_timeout_init and the dtls_timeout members of SSL have been set.
 3845    \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if
 3846    the timeout is not greater than 0. It will also return if the timeout
 3847    argument exceeds the maximum value allowed.
 3848
 3849    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3850    \param timeout an int type that will be set to the dtls_timeout_init
 3851    member of the WOLFSSL structure.
 3852
 3853    _Example_
 3854    \code
 3855    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 3856    WOLFSSL* ssl = wolfSSL_new(ctx);
 3857    int timeout = TIMEOUT;
 3858    ...
 3859    if(wolfSSL_dtls_set_timeout_init(ssl, timeout)){
 3860    	// the dtls timeout was set
 3861    } else {
 3862    	// Failed to set DTLS timeout.
 3863    }
 3864    \endcode
 3865
 3866    \sa wolfSSL_dtls_set_timeout_max
 3867    \sa wolfSSL_dtls_got_timeout
 3868*/
 3869int  wolfSSL_dtls_set_timeout_init(WOLFSSL* ssl, int timeout);
 3870
 3871/*!
 3872    \brief This function sets the maximum dtls timeout.
 3873
 3874    \return SSL_SUCCESS returned if the function executed without an error.
 3875    \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if
 3876    the timeout argument is not greater than zero or is less than the
 3877    dtls_timeout_init member of the WOLFSSL structure.
 3878
 3879    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3880    \param timeout an int type representing the dtls maximum timeout.
 3881
 3882    _Example_
 3883    \code
 3884    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 3885    WOLFSSL* ssl = wolfSSL_new(ctx);
 3886    int timeout = TIMEOUTVAL;
 3887    ...
 3888    int ret = wolfSSL_dtls_set_timeout_max(ssl);
 3889    if(!ret){
 3890    	// Failed to set the max timeout
 3891    }
 3892    \endcode
 3893
 3894    \sa wolfSSL_dtls_set_timeout_init
 3895    \sa wolfSSL_dtls_got_timeout
 3896*/
 3897int  wolfSSL_dtls_set_timeout_max(WOLFSSL* ssl, int timeout);
 3898
 3899/*!
 3900    \brief When using non-blocking sockets with DTLS, this function should
 3901    be called on the WOLFSSL object when the controlling code thinks the
 3902    transmission has timed out. It performs the actions needed to retry
 3903    the last transmit, including adjusting the timeout value. If it
 3904    has been too long, this will return a failure.
 3905
 3906    \return SSL_SUCCESS will be returned upon success
 3907    \return SSL_FATAL_ERROR will be returned if there have been too many
 3908    retransmissions/timeouts without getting a response from the peer.
 3909    \return NOT_COMPILED_IN will be returned if wolfSSL was not compiled with
 3910    DTLS support.
 3911
 3912    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3913
 3914    _Example_
 3915    \code
 3916    See the following files for usage examples:
 3917    <wolfssl_root>/examples/client/client.c
 3918    <wolfssl_root>/examples/server/server.c
 3919    \endcode
 3920
 3921    \sa wolfSSL_dtls_get_current_timeout
 3922    \sa wolfSSL_dtls_get_peer
 3923    \sa wolfSSL_dtls_set_peer
 3924    \sa wolfSSL_dtls
 3925*/
 3926int  wolfSSL_dtls_got_timeout(WOLFSSL* ssl);
 3927
 3928/*!
 3929    \brief When using non-blocking sockets with DTLS, this function retransmits
 3930    the last handshake flight ignoring the expected timeout value and
 3931    retransmit count. It is useful for applications that are using DTLS and
 3932    need to manage even the timeout and retry count.
 3933
 3934    \return SSL_SUCCESS will be returned upon success
 3935    \return SSL_FATAL_ERROR will be returned if there have been too many
 3936    retransmissions/timeouts without getting a response from the peer.
 3937
 3938    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3939
 3940    _Example_
 3941    \code
 3942    int ret = 0;
 3943    WOLFSSL* ssl;
 3944    ...
 3945    ret = wolfSSL_dtls_retransmit(ssl);
 3946    \endcode
 3947
 3948    \sa wolfSSL_dtls_get_current_timeout
 3949    \sa wolfSSL_dtls_got_timeout
 3950    \sa wolfSSL_dtls
 3951*/
 3952int wolfSSL_dtls_retransmit(WOLFSSL* ssl);
 3953
 3954/*!
 3955    \brief This function is used to determine if the SSL session has been
 3956    configured to use DTLS.
 3957
 3958    \return 1 If the SSL session (ssl) has been configured to use DTLS, this
 3959    function will return 1.
 3960    \return 0 otherwise.
 3961
 3962    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3963
 3964    _Example_
 3965    \code
 3966    int ret = 0;
 3967    WOLFSSL* ssl;
 3968    ...
 3969    ret = wolfSSL_dtls(ssl);
 3970    if (ret) {
 3971    	// SSL session has been configured to use DTLS
 3972    }
 3973    \endcode
 3974
 3975    \sa wolfSSL_dtls_get_current_timeout
 3976    \sa wolfSSL_dtls_get_peer
 3977    \sa wolfSSL_dtls_got_timeout
 3978    \sa wolfSSL_dtls_set_peer
 3979*/
 3980int  wolfSSL_dtls(WOLFSSL* ssl);
 3981
 3982/*!
 3983    \brief This function sets the DTLS peer, peer (sockaddr_in) with size of
 3984    peerSz.
 3985
 3986    \return SSL_SUCCESS will be returned upon success.
 3987    \return SSL_FAILURE will be returned upon failure.
 3988    \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled
 3989    with DTLS support.
 3990
 3991    \param ssl    a pointer to a WOLFSSL structure, created using wolfSSL_new().
 3992    \param peer   pointer to peer’s sockaddr_in structure. If NULL then the peer
 3993                  information in ssl is cleared.
 3994    \param peerSz size of the sockaddr_in structure pointed to by peer. If 0
 3995                  then the peer information in ssl is cleared.
 3996
 3997    _Example_
 3998    \code
 3999    int ret = 0;
 4000    WOLFSSL* ssl;
 4001    sockaddr_in addr;
 4002    ...
 4003    ret = wolfSSL_dtls_set_peer(ssl, &addr, sizeof(addr));
 4004    if (ret != SSL_SUCCESS) {
 4005	    // failed to set DTLS peer
 4006    }
 4007    \endcode
 4008
 4009    \sa wolfSSL_dtls_get_current_timeout
 4010    \sa wolfSSL_dtls_set_pending_peer
 4011    \sa wolfSSL_dtls_get_peer
 4012    \sa wolfSSL_dtls_got_timeout
 4013    \sa wolfSSL_dtls
 4014*/
 4015int  wolfSSL_dtls_set_peer(WOLFSSL* ssl, void* peer, unsigned int peerSz);
 4016
 4017/*!
 4018    \brief This function sets the pending DTLS peer, peer (sockaddr_in) with
 4019    size of peerSz. This sets the pending peer that will be upgraded to a
 4020    regular peer when we successfully de-protect the next record. This is useful
 4021    in scenarios where the peer's address can change to avoid off-path attackers
 4022    from changing the peer address. This should be used with Connection ID's to
 4023    allow seamless and safe transition to a new peer address.
 4024
 4025    \return SSL_SUCCESS will be returned upon success.
 4026    \return SSL_FAILURE will be returned upon failure.
 4027    \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled
 4028    with DTLS support.
 4029
 4030    \param ssl    a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4031    \param peer   pointer to peer’s sockaddr_in structure. If NULL then the peer
 4032                  information in ssl is cleared.
 4033    \param peerSz size of the sockaddr_in structure pointed to by peer. If 0
 4034                  then the peer information in ssl is cleared.
 4035
 4036    _Example_
 4037    \code
 4038    int ret = 0;
 4039    WOLFSSL* ssl;
 4040    sockaddr_in addr;
 4041    ...
 4042    ret = wolfSSL_dtls_set_pending_peer(ssl, &addr, sizeof(addr));
 4043    if (ret != SSL_SUCCESS) {
 4044	    // failed to set DTLS peer
 4045    }
 4046    \endcode
 4047
 4048    \sa wolfSSL_dtls_get_current_timeout
 4049    \sa wolfSSL_dtls_set_peer
 4050    \sa wolfSSL_dtls_get_peer
 4051    \sa wolfSSL_dtls_got_timeout
 4052    \sa wolfSSL_dtls
 4053*/
 4054int  wolfSSL_dtls_set_pending_peer(WOLFSSL* ssl, void* peer,
 4055                                   unsigned int peerSz);
 4056
 4057/*!
 4058    \brief This function gets the sockaddr_in (of size peerSz) of the current
 4059    DTLS peer.  The function will compare peerSz to the actual DTLS peer size
 4060    stored in the SSL session.  If the peer will fit into peer, the peer’s
 4061    sockaddr_in will be copied into peer, with peerSz set to the size of peer.
 4062
 4063    \return SSL_SUCCESS will be returned upon success.
 4064    \return SSL_FAILURE will be returned upon failure.
 4065    \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled
 4066    with DTLS support.
 4067
 4068    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4069    \param peer pointer to memory location to store peer’s sockaddr_in
 4070    structure.
 4071    \param peerSz input/output size. As input, the size of the allocated memory
 4072    pointed to by peer.  As output, the size of the actual sockaddr_in structure
 4073    pointed to by peer.
 4074
 4075    _Example_
 4076    \code
 4077    int ret = 0;
 4078    WOLFSSL* ssl;
 4079    sockaddr_in addr;
 4080    ...
 4081    ret = wolfSSL_dtls_get_peer(ssl, &addr, sizeof(addr));
 4082    if (ret != SSL_SUCCESS) {
 4083	    // failed to get DTLS peer
 4084    }
 4085    \endcode
 4086
 4087    \sa wolfSSL_dtls_get_current_timeout
 4088    \sa wolfSSL_dtls_got_timeout
 4089    \sa wolfSSL_dtls_set_peer
 4090    \sa wolfSSL_dtls
 4091*/
 4092int  wolfSSL_dtls_get_peer(WOLFSSL* ssl, void* peer, unsigned int* peerSz);
 4093
 4094/*!
 4095    \brief This function gets the sockaddr_in (of size peerSz) of the current
 4096    DTLS peer.  This is a zero-copy alternative to wolfSSL_dtls_get_peer().
 4097
 4098    \return SSL_SUCCESS will be returned upon success.
 4099    \return SSL_FAILURE will be returned upon failure.
 4100    \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled
 4101    with DTLS support.
 4102
 4103    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4104    \param peer pointer to return the internal buffer holding the peer address
 4105    \param peerSz output the size of the actual sockaddr_in structure
 4106    pointed to by peer.
 4107
 4108    _Example_
 4109    \code
 4110    int ret = 0;
 4111    WOLFSSL* ssl;
 4112    sockaddr_in* addr;
 4113    unsigned int addrSz;
 4114    ...
 4115    ret = wolfSSL_dtls_get_peer(ssl, &addr, &addrSz);
 4116    if (ret != SSL_SUCCESS) {
 4117	    // failed to get DTLS peer
 4118    }
 4119    \endcode
 4120
 4121    \sa wolfSSL_dtls_get_current_timeout
 4122    \sa wolfSSL_dtls_got_timeout
 4123    \sa wolfSSL_dtls_set_peer
 4124    \sa wolfSSL_dtls
 4125*/
 4126int  wolfSSL_dtls_get0_peer(WOLFSSL* ssl, const void** peer,
 4127                            unsigned int* peerSz);
 4128
 4129/*!
 4130    \ingroup Debug
 4131
 4132    \brief This function converts an error code returned by
 4133    wolfSSL_get_error() into a more human-readable error string.
 4134    errNumber is the error code returned by wolfSSL_get_error() and data
 4135    is the storage buffer which the error string will be placed in.
 4136    The maximum length of data is 80 characters by default, as defined by
 4137    MAX_ERROR_SZ is wolfssl/wolfcrypt/error.h.
 4138
 4139    \return success On successful completion, this function returns the same
 4140    string as is returned in data.
 4141    \return failure Upon failure, this function returns a string with the
 4142    appropriate failure reason, msg.
 4143
 4144    \param errNumber error code returned by wolfSSL_get_error().
 4145    \param data output buffer containing human-readable error string matching
 4146    errNumber.
 4147
 4148    _Example_
 4149    \code
 4150    int err = 0;
 4151    WOLFSSL* ssl;
 4152    char buffer[80];
 4153    ...
 4154    err = wolfSSL_get_error(ssl, 0);
 4155    wolfSSL_ERR_error_string(err, buffer);
 4156    printf(“err = %d, %s\n”, err, buffer);
 4157    \endcode
 4158
 4159    \sa wolfSSL_get_error
 4160    \sa wolfSSL_ERR_error_string_n
 4161    \sa wolfSSL_ERR_print_errors_fp
 4162    \sa wolfSSL_load_error_strings
 4163*/
 4164char* wolfSSL_ERR_error_string(unsigned long errNumber, char* data);
 4165
 4166/*!
 4167    \ingroup Debug
 4168
 4169    \brief This function is a version of wolfSSL_ERR_error_string() where
 4170    len specifies the maximum number of characters that may be written to buf.
 4171    Like wolfSSL_ERR_error_string(), this function converts an error code
 4172    returned from wolfSSL_get_error() into a more human-readable error string.
 4173    The human-readable string is placed in buf.
 4174
 4175    \return none No returns.
 4176
 4177    \param e error code returned by wolfSSL_get_error().
 4178    \param buff output buffer containing human-readable error string matching e.
 4179    \param len maximum length in characters which may be written to buf.
 4180
 4181    _Example_
 4182    \code
 4183    int err = 0;
 4184    WOLFSSL* ssl;
 4185    char buffer[80];
 4186    ...
 4187    err = wolfSSL_get_error(ssl, 0);
 4188    wolfSSL_ERR_error_string_n(err, buffer, 80);
 4189    printf(“err = %d, %s\n”, err, buffer);
 4190    \endcode
 4191
 4192    \sa wolfSSL_get_error
 4193    \sa wolfSSL_ERR_error_string
 4194    \sa wolfSSL_ERR_print_errors_fp
 4195    \sa wolfSSL_load_error_strings
 4196*/
 4197void  wolfSSL_ERR_error_string_n(unsigned long e, char* buf,
 4198                                           unsigned long len);
 4199
 4200/*!
 4201    \ingroup TLS
 4202
 4203    \brief This function checks the shutdown conditions in closeNotify or
 4204    connReset or sentNotify members of the Options structure. The Options
 4205    structure is within the WOLFSSL structure.
 4206
 4207    \return 1 SSL_SENT_SHUTDOWN is returned.
 4208    \return 2 SSL_RECEIVED_SHUTDOWN is returned.
 4209
 4210    \param ssl a constant pointer to a WOLFSSL structure, created using
 4211    wolfSSL_new().
 4212
 4213    _Example_
 4214    \code
 4215    #include <wolfssl/ssl.h>
 4216
 4217    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
 4218    WOLFSSL* ssl = WOLFSSL_new(ctx);
 4219    …
 4220    int ret;
 4221    ret = wolfSSL_get_shutdown(ssl);
 4222
 4223    if(ret == 1){
 4224	    SSL_SENT_SHUTDOWN
 4225    } else if(ret == 2){
 4226	    SSL_RECEIVED_SHUTDOWN
 4227    } else {
 4228	    Fatal error.
 4229    }
 4230    \endcode
 4231
 4232    \sa wolfSSL_SESSION_free
 4233*/
 4234int  wolfSSL_get_shutdown(const WOLFSSL* ssl);
 4235
 4236/*!
 4237    \ingroup IO
 4238
 4239    \brief This function returns the resuming member of the options struct. The
 4240    flag indicates whether or not to reuse a session. If not, a new session must
 4241    be established.
 4242
 4243    \return This function returns an int type held in the Options structure
 4244    representing the flag for session reuse.
 4245
 4246    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4247
 4248    _Example_
 4249    \code
 4250    WOLFSSL* ssl = wolfSSL_new(ctx);
 4251    …
 4252    if(!wolfSSL_session_reused(sslResume)){
 4253	    // No session reuse allowed.
 4254    }
 4255    \endcode
 4256
 4257    \sa wolfSSL_SESSION_free
 4258    \sa wolfSSL_GetSessionIndex
 4259    \sa wolfSSL_memsave_session_cache
 4260*/
 4261int  wolfSSL_session_reused(WOLFSSL* ssl);
 4262
 4263/*!
 4264    \ingroup TLS
 4265
 4266    \brief This function checks to see if the connection is established.
 4267
 4268    \return 0 returned if the connection is not established, i.e. the WOLFSSL
 4269    struct is NULL or the handshake is not done.
 4270    \return 1 returned if the connection is established i.e. the WOLFSSL
 4271    handshake is done.
 4272
 4273    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4274
 4275    _EXAMPLE_
 4276    \code
 4277    #include <wolfssl/ssl.h>
 4278
 4279    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 4280    WOLFSSL* ssl = wolfSSL_new(ctx);
 4281    ...
 4282    if(wolfSSL_is_init_finished(ssl)){
 4283	    Handshake is done and connection is established
 4284    }
 4285    \endcode
 4286
 4287    \sa wolfSSL_set_accept_state
 4288    \sa wolfSSL_get_keys
 4289    \sa wolfSSL_set_shutdown
 4290*/
 4291int  wolfSSL_is_init_finished(const WOLFSSL* ssl);
 4292
 4293/*!
 4294    \ingroup IO
 4295
 4296    \brief Returns the SSL version being used as a string.
 4297
 4298    \return "SSLv3" Using SSLv3
 4299    \return "TLSv1" Using TLSv1
 4300    \return "TLSv1.1" Using TLSv1.1
 4301    \return "TLSv1.2" Using TLSv1.2
 4302    \return "TLSv1.3" Using TLSv1.3
 4303    \return "DTLS": Using DTLS
 4304    \return "DTLSv1.2" Using DTLSv1.2
 4305    \return "unknown" There was a problem determining which version of TLS
 4306    being used.
 4307
 4308    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4309
 4310    _Example_
 4311    \code
 4312    wolfSSL_Init();
 4313    WOLFSSL_CTX* ctx;
 4314    WOLFSSL* ssl;
 4315    WOLFSSL_METHOD method = // Some wolfSSL method
 4316    ctx = wolfSSL_CTX_new(method);
 4317    ssl = wolfSSL_new(ctx);
 4318    printf(wolfSSL_get_version("Using version: %s", ssl));
 4319    \endcode
 4320
 4321    \sa wolfSSL_lib_version
 4322*/
 4323const char*  wolfSSL_get_version(WOLFSSL* ssl);
 4324
 4325/*!
 4326    \ingroup IO
 4327
 4328    \brief Returns the current cipher suit an ssl session is using.
 4329
 4330    \return ssl->options.cipherSuite An integer representing the current
 4331    cipher suite.
 4332    \return 0 The ssl session provided is null.
 4333
 4334    \param ssl The SSL session to check.
 4335
 4336    _Example_
 4337    \code
 4338    wolfSSL_Init();
 4339    WOLFSSL_CTX* ctx;
 4340    WOLFSSL* ssl;
 4341    WOLFSSL_METHOD method = // Some wolfSSL method
 4342    ctx = wolfSSL_CTX_new(method);
 4343    ssl = wolfSSL_new(ctx);
 4344
 4345    if(wolfSSL_get_current_cipher_suite(ssl) == 0)
 4346    {
 4347        // Error getting cipher suite
 4348    }
 4349    \endcode
 4350
 4351    \sa wolfSSL_CIPHER_get_name
 4352    \sa wolfSSL_get_current_cipher
 4353    \sa wolfSSL_get_cipher_list
 4354*/
 4355int  wolfSSL_get_current_cipher_suite(WOLFSSL* ssl);
 4356
 4357/*!
 4358    \ingroup IO
 4359
 4360    \brief This function returns a pointer to the current cipher in the
 4361    ssl session.
 4362
 4363    \return The function returns the address of the cipher member of the
 4364    WOLFSSL struct. This is a pointer to the WOLFSSL_CIPHER structure.
 4365    \return NULL returned if the WOLFSSL structure is NULL.
 4366
 4367    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4368
 4369    _Example_
 4370    \code
 4371    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 4372    WOLFSSL* ssl = wolfSSL_new(ctx);
 4373    …
 4374    WOLFSSL_CIPHER* cipherCurr = wolfSSL_get_current_cipher;
 4375
 4376    if(!cipherCurr){
 4377    	// Failure case.
 4378    } else {
 4379    	// The cipher was returned to cipherCurr
 4380    }
 4381    \endcode
 4382
 4383    \sa wolfSSL_get_cipher
 4384    \sa wolfSSL_get_cipher_name_internal
 4385    \sa wolfSSL_get_cipher_name
 4386*/
 4387WOLFSSL_CIPHER*  wolfSSL_get_current_cipher(WOLFSSL* ssl);
 4388
 4389/*!
 4390    \ingroup IO
 4391
 4392    \brief This function matches the cipher suite in the SSL object with
 4393    the available suites and returns the string representation.
 4394
 4395    \return string This function returns the string representation of the
 4396    matched cipher suite.
 4397    \return none It will return “None” if there are no suites matched.
 4398
 4399    \param cipher a constant pointer to a WOLFSSL_CIPHER structure.
 4400
 4401    _Example_
 4402    \code
 4403    // gets cipher name in the format DHE_RSA ...
 4404    const char* wolfSSL_get_cipher_name_internal(WOLFSSL* ssl){
 4405	WOLFSSL_CIPHER* cipher;
 4406	const char* fullName;
 4407    …
 4408	cipher = wolfSSL_get_curent_cipher(ssl);
 4409	fullName = wolfSSL_CIPHER_get_name(cipher);
 4410
 4411	if(fullName){
 4412		// sanity check on returned cipher
 4413	}
 4414    \endcode
 4415
 4416    \sa wolfSSL_get_cipher
 4417    \sa wolfSSL_get_current_cipher
 4418    \sa wolfSSL_get_cipher_name_internal
 4419    \sa wolfSSL_get_cipher_name
 4420*/
 4421const char*  wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER* cipher);
 4422
 4423/*!
 4424    \ingroup IO
 4425
 4426    \brief This function matches the cipher suite in the SSL object with
 4427    the available suites.
 4428
 4429    \return This function returns the string value of the suite matched. It
 4430    will return “None” if there are no suites matched.
 4431
 4432    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 4433
 4434    _Example_
 4435    \code
 4436    #ifdef WOLFSSL_DTLS
 4437    …
 4438    // make sure a valid suite is used
 4439    if(wolfSSL_get_cipher(ssl) == NULL){
 4440	    WOLFSSL_MSG(“Can not match cipher suite imported”);
 4441	    return MATCH_SUITE_ERROR;
 4442    }
 4443    …
 4444    #endif // WOLFSSL_DTLS
 4445    \endcode
 4446
 4447    \sa wolfSSL_CIPHER_get_name
 4448    \sa wolfSSL_get_current_cipher
 4449*/
 4450const char*  wolfSSL_get_cipher(WOLFSSL*);
 4451
 4452/*!
 4453    \ingroup Setup
 4454
 4455    \brief This function returns the WOLFSSL_SESSION from the WOLFSSL structure
 4456    as a reference type. This requires calling wolfSSL_SESSION_free to release
 4457    the session reference. The WOLFSSL_SESSION pointed to contains all the
 4458    necessary information required to perform a session resumption and
 4459    reestablish the connection without a new handshake. For
 4460    session resumption, before calling wolfSSL_shutdown() with your session
 4461    object, an application should save the session ID from the object with a
 4462    call to wolfSSL_get1_session(), which returns a pointer to the session.
 4463    Later, the application should create a new WOLFSSL object and assign the
 4464    saved session with wolfSSL_set_session().  At this point, the application
 4465    may call wolfSSL_connect() and wolfSSL will try to resume the session.
 4466    The wolfSSL server code allows session resumption by default. The object
 4467    returned by wolfSSL_get1_session() needs to be freed after the application
 4468    is done with it by calling wolfSSL_SESSION_free() on it.
 4469
 4470    \return WOLFSSL_SESSION On success return session pointer.
 4471    \return NULL will be returned if ssl is NULL, the SSL session cache is
 4472    disabled, wolfSSL doesn’t have the Session ID available, or mutex
 4473    functions fail.
 4474
 4475    \param ssl WOLFSSL structure to get session from.
 4476
 4477    _Example_
 4478    \code
 4479    WOLFSSL* ssl;
 4480    WOLFSSL_SESSION* ses;
 4481    // attempt/complete handshake
 4482    wolfSSL_connect(ssl);
 4483    ses  = wolfSSL_get1_session(ssl);
 4484    // check ses information
 4485    // disconnect / setup new SSL instance
 4486    wolfSSL_set_session(ssl, ses);
 4487    // attempt/resume handshake
 4488    wolfSSL_SESSION_free(ses);
 4489    \endcode
 4490
 4491    \sa wolfSSL_new
 4492    \sa wolfSSL_free
 4493    \sa wolfSSL_SESSION_free
 4494*/
 4495WOLFSSL_SESSION* wolfSSL_get1_session(WOLFSSL* ssl);
 4496
 4497/*!
 4498    \ingroup Setup
 4499
 4500    \brief The wolfSSLv23_client_method() function is used to indicate that
 4501    the application is a client and will support the highest protocol
 4502    version supported by the server between SSL 3.0 - TLS 1.3.  This function
 4503    allocates memory for and initializes a new WOLFSSL_METHOD structure
 4504    to be used when creating the SSL/TLS context with wolfSSL_CTX_new().
 4505    Both wolfSSL clients and servers have robust version downgrade capability.
 4506    If a specific protocol version method is used on either side, then only
 4507    that version will be negotiated or an error will be returned.  For
 4508    example, a client that uses TLSv1 and tries to connect to a SSLv3 only
 4509    server will fail, likewise connecting to a TLSv1.1 will fail as well.
 4510    To resolve this issue, a client that uses the wolfSSLv23_client_method()
 4511    function will use the highest protocol version supported by the server and
 4512    downgrade to SSLv3 if needed. In this case, the client will be able to
 4513    connect to a server running SSLv3 - TLSv1.3.
 4514
 4515    \return pointer upon success a pointer to a WOLFSSL_METHOD.
 4516    \return Failure If memory allocation fails when calling XMALLOC,
 4517    the failure value of the underlying malloc() implementation will be
 4518    returned (typically NULL with errno will be set to ENOMEM).
 4519
 4520    \param none No parameters
 4521
 4522    _Example_
 4523    \code
 4524    WOLFSSL_METHOD* method;
 4525    WOLFSSL_CTX* ctx;
 4526    method = wolfSSLv23_client_method();
 4527    if (method == NULL) {
 4528	// unable to get method
 4529    }
 4530
 4531    ctx = wolfSSL_CTX_new(method);
 4532    ...
 4533    \endcode
 4534
 4535    \sa wolfSSLv3_client_method
 4536    \sa wolfTLSv1_client_method
 4537    \sa wolfTLSv1_1_client_method
 4538    \sa wolfTLSv1_2_client_method
 4539    \sa wolfTLSv1_3_client_method
 4540    \sa wolfDTLSv1_client_method
 4541    \sa wolfSSL_CTX_new
 4542*/
 4543WOLFSSL_METHOD* wolfSSLv23_client_method(void);
 4544
 4545/*!
 4546    \ingroup IO
 4547
 4548    \brief This is used to set a byte pointer to the start of the
 4549    internal memory buffer.
 4550
 4551    \return size On success the size of the buffer is returned
 4552    \return SSL_FATAL_ERROR If an error case was encountered.
 4553
 4554    \param bio WOLFSSL_BIO structure to get memory buffer of.
 4555    \param p byte pointer to set to memory buffer.
 4556
 4557    _Example_
 4558    \code
 4559    WOLFSSL_BIO* bio;
 4560    const byte* p;
 4561    int ret;
 4562    bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
 4563    ret  = wolfSSL_BIO_get_mem_data(bio, &p);
 4564    // check ret value
 4565    \endcode
 4566
 4567    \sa wolfSSL_BIO_new
 4568    \sa wolfSSL_BIO_s_mem
 4569    \sa wolfSSL_BIO_set_fp
 4570    \sa wolfSSL_BIO_free
 4571*/
 4572int wolfSSL_BIO_get_mem_data(WOLFSSL_BIO* bio,void* p);
 4573
 4574/*!
 4575    \ingroup IO
 4576
 4577    \brief This is used to set the init flag of a BIO, indicating whether
 4578    the BIO has been initialised and is ready for use. Typically called
 4579    from a custom BIO create callback.
 4580
 4581    \param bio WOLFSSL_BIO structure to set the init flag on.
 4582    \param init value to set (0 = not initialised, 1 = initialised).
 4583
 4584    _Example_
 4585    \code
 4586    WOLFSSL_BIO* bio;
 4587    // inside a custom BIO create callback
 4588    wolfSSL_BIO_set_init(bio, 1);
 4589    \endcode
 4590
 4591    \sa wolfSSL_BIO_get_init
 4592    \sa wolfSSL_BIO_new
 4593*/
 4594void wolfSSL_BIO_set_init(WOLFSSL_BIO* bio, int init);
 4595
 4596/*!
 4597    \ingroup IO
 4598
 4599    \brief This is used to retrieve the init flag of a BIO, indicating
 4600    whether the BIO has been initialised and is ready for use.
 4601
 4602    \return 1 if the BIO has been initialised.
 4603    \return 0 if the BIO has not been initialised or bio is NULL.
 4604
 4605    \param bio WOLFSSL_BIO structure to query.
 4606
 4607    _Example_
 4608    \code
 4609    WOLFSSL_BIO* bio;
 4610    // create bio with custom method
 4611    if (wolfSSL_BIO_get_init(bio)) {
 4612        // bio is ready
 4613    }
 4614    \endcode
 4615
 4616    \sa wolfSSL_BIO_set_init
 4617    \sa wolfSSL_BIO_new
 4618*/
 4619int wolfSSL_BIO_get_init(WOLFSSL_BIO* bio);
 4620
 4621/*!
 4622    \ingroup IO
 4623
 4624    \brief Sets the file descriptor for bio to use.
 4625
 4626    \return SSL_SUCCESS(1) upon success.
 4627
 4628    \param b WOLFSSL_BIO structure to set fd.
 4629    \param fd file descriptor to use.
 4630    \param flag flag for behavior when closing fd.
 4631
 4632    _Example_
 4633    \code
 4634    WOLFSSL_BIO* bio;
 4635    int fd;
 4636    // setup bio
 4637    wolfSSL_BIO_set_fd(bio, fd, BIO_NOCLOSE);
 4638    \endcode
 4639
 4640    \sa wolfSSL_BIO_new
 4641    \sa wolfSSL_BIO_free
 4642*/
 4643long wolfSSL_BIO_set_fd(WOLFSSL_BIO* b, int fd, int flag);
 4644
 4645/*!
 4646    \ingroup IO
 4647
 4648    \brief Sets the close flag, used to indicate that the i/o stream should be
 4649     closed when the BIO is freed
 4650
 4651    \return SSL_SUCCESS(1) upon success.
 4652
 4653    \param b WOLFSSL_BIO structure.
 4654    \param flag flag for behavior when closing i/o stream.
 4655
 4656    _Example_
 4657    \code
 4658    WOLFSSL_BIO* bio;
 4659    // setup bio
 4660    wolfSSL_BIO_set_close(bio, BIO_NOCLOSE);
 4661    \endcode
 4662
 4663    \sa wolfSSL_BIO_new
 4664    \sa wolfSSL_BIO_free
 4665*/
 4666int wolfSSL_BIO_set_close(WOLFSSL_BIO *b, long flag);
 4667
 4668/*!
 4669    \ingroup IO
 4670
 4671    \brief This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD.
 4672
 4673    \return WOLFSSL_BIO_METHOD pointer to a WOLFSSL_BIO_METHOD structure
 4674    that is a socket type
 4675
 4676    \param none No parameters.
 4677
 4678    _Example_
 4679    \code
 4680    WOLFSSL_BIO* bio;
 4681    bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket);
 4682    \endcode
 4683
 4684    \sa wolfSSL_BIO_new
 4685    \sa wolfSSL_BIO_s_mem
 4686*/
 4687WOLFSSL_BIO_METHOD *wolfSSL_BIO_s_socket(void);
 4688
 4689/*!
 4690    \ingroup IO
 4691
 4692    \brief This is used to set the size of write buffer for a
 4693    WOLFSSL_BIO. If write buffer has been previously set this
 4694    function will free it when resetting the size. It is similar to
 4695    wolfSSL_BIO_reset in that it resets read and write indexes to 0.
 4696
 4697    \return SSL_SUCCESS On successfully setting the write buffer.
 4698    \return SSL_FAILURE If an error case was encountered.
 4699
 4700    \param b WOLFSSL_BIO structure to set write buffer size.
 4701    \param size size of buffer to allocate.
 4702
 4703    _Example_
 4704    \code
 4705    WOLFSSL_BIO* bio;
 4706    int ret;
 4707    bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
 4708    ret = wolfSSL_BIO_set_write_buf_size(bio, 15000);
 4709    // check return value
 4710    \endcode
 4711
 4712    \sa wolfSSL_BIO_new
 4713    \sa wolfSSL_BIO_s_mem
 4714    \sa wolfSSL_BIO_free
 4715*/
 4716int  wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO *b, long size);
 4717
 4718/*!
 4719    \ingroup IO
 4720
 4721    \brief This is used to pair two bios together. A pair of bios acts
 4722    similar to a two way pipe writing to one can be read by the other
 4723    and vice versa. It is expected that both bios be in the same thread,
 4724    this function is not thread safe. Freeing one of the two bios removes
 4725    both from being paired. If a write buffer size was not previously
 4726    set for either of the bios it is set to a default size of 17000
 4727    (WOLFSSL_BIO_SIZE) before being paired.
 4728
 4729    \return SSL_SUCCESS On successfully pairing the two bios.
 4730    \return SSL_FAILURE If an error case was encountered.
 4731
 4732    \param b1 WOLFSSL_BIO structure to set pair.
 4733    \param b2 second WOLFSSL_BIO structure to complete pair.
 4734
 4735    _Example_
 4736    \code
 4737    WOLFSSL_BIO* bio;
 4738    WOLFSSL_BIO* bio2;
 4739    int ret;
 4740    bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());
 4741    bio2 = wolfSSL_BIO_new(wolfSSL_BIO_s_bio());
 4742    ret = wolfSSL_BIO_make_bio_pair(bio, bio2);
 4743    // check ret value
 4744    \endcode
 4745
 4746    \sa wolfSSL_BIO_new
 4747    \sa wolfSSL_BIO_s_mem
 4748    \sa wolfSSL_BIO_free
 4749*/
 4750int  wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO *b1, WOLFSSL_BIO *b2);
 4751
 4752/*!
 4753    \ingroup IO
 4754
 4755    \brief This is used to set the read request flag back to 0.
 4756
 4757    \return SSL_SUCCESS On successfully setting value.
 4758    \return SSL_FAILURE If an error case was encountered.
 4759
 4760    \param b WOLFSSL_BIO structure to set read request flag.
 4761
 4762    _Example_
 4763    \code
 4764    WOLFSSL_BIO* bio;
 4765    int ret;
 4766    ...
 4767    ret = wolfSSL_BIO_ctrl_reset_read_request(bio);
 4768    // check ret value
 4769    \endcode
 4770
 4771    \sa wolfSSL_BIO_new, wolfSSL_BIO_s_mem
 4772    \sa wolfSSL_BIO_new, wolfSSL_BIO_free
 4773*/
 4774int  wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO *b);
 4775
 4776/*!
 4777    \ingroup IO
 4778
 4779    \brief This is used to get a buffer pointer for reading from. Unlike
 4780    wolfSSL_BIO_nread the internal read index is not advanced by the number
 4781    returned from the function call. Reading past the value returned can
 4782    result in reading out of array bounds.
 4783
 4784    \return >=0 on success return the number of bytes to read
 4785
 4786    \param bio WOLFSSL_BIO structure to read from.
 4787    \param buf pointer to set at beginning of read array.
 4788
 4789    _Example_
 4790    \code
 4791    WOLFSSL_BIO* bio;
 4792    char* bufPt;
 4793    int ret;
 4794    // set up bio
 4795    ret = wolfSSL_BIO_nread0(bio, &bufPt); // read as many bytes as possible
 4796    // handle negative ret check
 4797    // read ret bytes from bufPt
 4798    \endcode
 4799
 4800    \sa wolfSSL_BIO_new
 4801*/
 4802int  wolfSSL_BIO_nread0(WOLFSSL_BIO *bio, char **buf);
 4803
 4804/*!
 4805    \ingroup IO
 4806
 4807    \brief This is used to get a buffer pointer for reading from. The internal
 4808    read index is advanced by the number returned from the function call with
 4809    buf being pointed to the beginning of the buffer to read from. In the
 4810    case that less bytes are in the read buffer than the value requested with
 4811    num the lesser value is returned. Reading past the value returned can
 4812    result in reading out of array bounds.
 4813
 4814    \return >=0 on success return the number of bytes to read
 4815    \return WOLFSSL_BIO_ERROR(-1) on error case with nothing to read return -1
 4816
 4817    \param bio WOLFSSL_BIO structure to read from.
 4818    \param buf pointer to set at beginning of read array.
 4819    \param num number of bytes to try and read.
 4820
 4821    _Example_
 4822    \code
 4823    WOLFSSL_BIO* bio;
 4824    char* bufPt;
 4825    int ret;
 4826
 4827    // set up bio
 4828    ret = wolfSSL_BIO_nread(bio, &bufPt, 10); // try to read 10 bytes
 4829    // handle negative ret check
 4830    // read ret bytes from bufPt
 4831    \endcode
 4832
 4833    \sa wolfSSL_BIO_new
 4834    \sa wolfSSL_BIO_nwrite
 4835*/
 4836int  wolfSSL_BIO_nread(WOLFSSL_BIO *bio, char **buf, int num);
 4837
 4838/*!
 4839    \ingroup IO
 4840
 4841    \brief Gets a pointer to the buffer for writing as many bytes as returned by
 4842    the function. Writing more bytes to the pointer returned then the value
 4843    returned can result in writing out of bounds.
 4844
 4845    \return int Returns the number of bytes that can be written to the buffer
 4846    pointer returned.
 4847    \return WOLFSSL_BIO_UNSET(-2) in the case that is not part of a bio pair
 4848    \return WOLFSSL_BIO_ERROR(-1) in the case that there is no more room to
 4849    write to
 4850
 4851    \param bio WOLFSSL_BIO structure to write to.
 4852    \param buf pointer to buffer to write to.
 4853    \param num number of bytes desired to be written.
 4854
 4855    _Example_
 4856    \code
 4857    WOLFSSL_BIO* bio;
 4858    char* bufPt;
 4859    int ret;
 4860    // set up bio
 4861    ret = wolfSSL_BIO_nwrite(bio, &bufPt, 10); // try to write 10 bytes
 4862    // handle negative ret check
 4863    // write ret bytes to bufPt
 4864    \endcode
 4865
 4866    \sa wolfSSL_BIO_new
 4867    \sa wolfSSL_BIO_free
 4868    \sa wolfSSL_BIO_nread
 4869*/
 4870int  wolfSSL_BIO_nwrite(WOLFSSL_BIO *bio, char **buf, int num);
 4871
 4872/*!
 4873    \ingroup IO
 4874
 4875    \brief Resets bio to an initial state. As an example for type BIO_BIO
 4876    this resets the read and write index.
 4877
 4878    \return 0 On successfully resetting the bio.
 4879    \return WOLFSSL_BIO_ERROR(-1) Returned on bad input or unsuccessful reset.
 4880
 4881    \param bio WOLFSSL_BIO structure to reset.
 4882
 4883    _Example_
 4884    \code
 4885    WOLFSSL_BIO* bio;
 4886    // setup bio
 4887    wolfSSL_BIO_reset(bio);
 4888    //use pt
 4889    \endcode
 4890
 4891    \sa wolfSSL_BIO_new
 4892    \sa wolfSSL_BIO_free
 4893*/
 4894int  wolfSSL_BIO_reset(WOLFSSL_BIO *bio);
 4895
 4896/*!
 4897    \ingroup IO
 4898
 4899    \brief This function adjusts the file pointer to the offset given. This
 4900    is the offset from the head of the file.
 4901
 4902    \return 0 On successfully seeking.
 4903    \return -1 If an error case was encountered.
 4904
 4905    \param bio WOLFSSL_BIO structure to set.
 4906    \param ofs offset into file.
 4907
 4908    _Example_
 4909    \code
 4910    WOLFSSL_BIO* bio;
 4911    XFILE fp;
 4912    int ret;
 4913    bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
 4914    ret  = wolfSSL_BIO_set_fp(bio, &fp);
 4915    // check ret value
 4916    ret  = wolfSSL_BIO_seek(bio, 3);
 4917    // check ret value
 4918    \endcode
 4919
 4920    \sa wolfSSL_BIO_new
 4921    \sa wolfSSL_BIO_s_mem
 4922    \sa wolfSSL_BIO_set_fp
 4923    \sa wolfSSL_BIO_free
 4924*/
 4925int  wolfSSL_BIO_seek(WOLFSSL_BIO *bio, int ofs);
 4926
 4927/*!
 4928    \ingroup IO
 4929
 4930    \brief This is used to set and write to a file. WIll overwrite any data
 4931    currently in the file and is set to close the file when the bio is freed.
 4932
 4933    \return SSL_SUCCESS On successfully opening and setting file.
 4934    \return SSL_FAILURE If an error case was encountered.
 4935
 4936    \param bio WOLFSSL_BIO structure to set file.
 4937    \param name name of file to write to.
 4938
 4939    _Example_
 4940    \code
 4941    WOLFSSL_BIO* bio;
 4942    int ret;
 4943    bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
 4944    ret  = wolfSSL_BIO_write_filename(bio, “test.txt”);
 4945    // check ret value
 4946    \endcode
 4947
 4948    \sa wolfSSL_BIO_new
 4949    \sa wolfSSL_BIO_s_file
 4950    \sa wolfSSL_BIO_set_fp
 4951    \sa wolfSSL_BIO_free
 4952*/
 4953int  wolfSSL_BIO_write_filename(WOLFSSL_BIO *bio, char *name);
 4954
 4955/*!
 4956    \ingroup IO
 4957
 4958    \brief This is used to set the end of file value. Common value is -1 so
 4959    as not to get confused with expected positive values.
 4960
 4961    \return 0 returned on completion
 4962
 4963    \param bio WOLFSSL_BIO structure to set end of file value.
 4964    \param v value to set in bio.
 4965
 4966    _Example_
 4967    \code
 4968    WOLFSSL_BIO* bio;
 4969    int ret;
 4970    bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
 4971    ret  = wolfSSL_BIO_set_mem_eof_return(bio, -1);
 4972    // check ret value
 4973    \endcode
 4974
 4975    \sa wolfSSL_BIO_new
 4976    \sa wolfSSL_BIO_s_mem
 4977    \sa wolfSSL_BIO_set_fp
 4978    \sa wolfSSL_BIO_free
 4979*/
 4980long wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO *bio, int v);
 4981
 4982/*!
 4983    \ingroup IO
 4984
 4985    \brief This is a getter function for WOLFSSL_BIO memory pointer.
 4986
 4987    \return SSL_SUCCESS On successfully getting the pointer SSL_SUCCESS is
 4988    returned (currently value of 1).
 4989    \return SSL_FAILURE Returned if NULL arguments are passed in (currently
 4990    value of 0).
 4991
 4992    \param bio pointer to the WOLFSSL_BIO structure for getting memory pointer.
 4993    \param m pointer to WOLFSSL_BUF_MEM structure. Is set to point to
 4994    bio’s memory.
 4995
 4996    _Example_
 4997    \code
 4998    WOLFSSL_BIO* bio;
 4999    WOLFSSL_BUF_MEM* pt;
 5000    // setup bio
 5001    wolfSSL_BIO_get_mem_ptr(bio, &pt);
 5002    //use pt
 5003    \endcode
 5004
 5005    \sa wolfSSL_BIO_new
 5006    \sa wolfSSL_BIO_s_mem
 5007*/
 5008long wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO *bio, WOLFSSL_BUF_MEM **m);
 5009
 5010/*!
 5011    \ingroup CertsKeys
 5012
 5013    \brief This function copies the name of the x509 into a buffer.
 5014
 5015    \return A char pointer to the buffer with the WOLFSSL_X509_NAME structures
 5016    name member’s data is returned if the function executed normally.
 5017
 5018    \param name a pointer to a WOLFSSL_X509 structure.
 5019    \param in a buffer to hold the name copied from the
 5020    WOLFSSL_X509_NAME structure.
 5021    \param sz the maximum size of the buffer.
 5022
 5023    _Example_
 5024    \code
 5025    WOLFSSL_X509 x509;
 5026    char* name;
 5027    ...
 5028    name = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);
 5029
 5030    if(name <= 0){
 5031    	// There’s nothing in the buffer.
 5032    }
 5033    \endcode
 5034
 5035    \sa wolfSSL_X509_get_subject_name
 5036    \sa wolfSSL_X509_get_issuer_name
 5037    \sa wolfSSL_X509_get_isCA
 5038    \sa wolfSSL_get_peer_certificate
 5039    \sa wolfSSL_X509_version
 5040*/
 5041char*       wolfSSL_X509_NAME_oneline(WOLFSSL_X509_NAME* name, char* in, int sz);
 5042
 5043/*!
 5044    \ingroup CertsKeys
 5045
 5046    \brief This function returns the name of the certificate issuer.
 5047
 5048    \return point a pointer to the WOLFSSL_X509 struct’s issuer member is
 5049    returned.
 5050    \return NULL if the cert passed in is NULL.
 5051
 5052    \param cert a pointer to a WOLFSSL_X509 structure.
 5053
 5054    _Example_
 5055    \code
 5056    WOLFSSL_X509* x509;
 5057    WOLFSSL_X509_NAME issuer;
 5058    ...
 5059    issuer = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0);
 5060
 5061    if(!issuer){
 5062    	// NULL was returned
 5063    } else {
 5064    	// issuer hods the name of the certificate issuer.
 5065    }
 5066    \endcode
 5067
 5068    \sa wolfSSL_X509_get_subject_name
 5069    \sa wolfSSL_X509_get_isCA
 5070    \sa wolfSSL_get_peer_certificate
 5071    \sa wolfSSL_X509_NAME_oneline
 5072*/
 5073WOLFSSL_X509_NAME*  wolfSSL_X509_get_issuer_name(WOLFSSL_X509* cert);
 5074
 5075/*!
 5076    \ingroup CertsKeys
 5077
 5078    \brief This function returns the subject member of the WOLFSSL_X509
 5079    structure.
 5080
 5081    \return pointer a pointer to the WOLFSSL_X509_NAME structure. The pointer
 5082    may be NULL if the WOLFSSL_X509 struct is NULL or if the subject member of
 5083    the structure is NULL.
 5084
 5085    \param cert a pointer to a WOLFSSL_X509 structure.
 5086
 5087    _Example_
 5088    \code
 5089    WOLFSSL_X509* cert;
 5090    WOLFSSL_X509_NAME name;
 5091    …
 5092    name = wolfSSL_X509_get_subject_name(cert);
 5093    if(name == NULL){
 5094	    // Deal with the NULL cacse
 5095    }
 5096    \endcode
 5097
 5098    \sa wolfSSL_X509_get_issuer_name
 5099    \sa wolfSSL_X509_get_isCA
 5100    \sa wolfSSL_get_peer_certificate
 5101*/
 5102WOLFSSL_X509_NAME*  wolfSSL_X509_get_subject_name(WOLFSSL_X509* cert);
 5103
 5104/*!
 5105    \ingroup CertsKeys
 5106
 5107    \brief Checks the isCa member of the WOLFSSL_X509 structure and returns
 5108    the value.
 5109
 5110    \return isCA returns the value in the isCA member of the WOLFSSL_X509
 5111    structure is returned.
 5112    \return 0 returned if there is not a valid x509 structure passed in.
 5113
 5114    \param x509 a pointer to a WOLFSSL_X509 structure.
 5115
 5116    _Example_
 5117    \code
 5118    WOLFSSL* ssl;
 5119    ...
 5120    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 5121    WOLFSSL* ssl = wolfSSL_new(ctx);
 5122    ...
 5123    if(wolfSSL_X509_get_isCA(ssl)){
 5124    	// This is the CA
 5125    }else {
 5126    	// Failure case
 5127    }
 5128    \endcode
 5129
 5130    \sa wolfSSL_X509_get_issuer_name
 5131    \sa wolfSSL_X509_get_isCA
 5132*/
 5133int  wolfSSL_X509_get_isCA(WOLFSSL_X509* x509);
 5134
 5135/*!
 5136    \ingroup CertsKeys
 5137
 5138    \brief This function gets the text related to the passed in NID value.
 5139
 5140    \return int returns the size of the text buffer.
 5141
 5142    \param name WOLFSSL_X509_NAME to search for text.
 5143    \param nid NID to search for.
 5144    \param buf buffer to hold text when found.
 5145    \param len length of buffer.
 5146
 5147    _Example_
 5148    \code
 5149    WOLFSSL_X509_NAME* name;
 5150    char buffer[100];
 5151    int bufferSz;
 5152    int ret;
 5153    // get WOLFSSL_X509_NAME
 5154    ret = wolfSSL_X509_NAME_get_text_by_NID(name, NID_commonName,
 5155    buffer, bufferSz);
 5156
 5157    //check ret value
 5158    \endcode
 5159
 5160    \sa none
 5161*/
 5162int wolfSSL_X509_NAME_get_text_by_NID(WOLFSSL_X509_NAME* name, int nid,
 5163                                      char* buf, int len);
 5164
 5165/*!
 5166    \ingroup CertsKeys
 5167
 5168    \brief This function returns the value stored in the sigOID
 5169    member of the WOLFSSL_X509 structure.
 5170
 5171    \return 0 returned if the WOLFSSL_X509 structure is NULL.
 5172    \return int an integer value is returned which was retrieved from
 5173    the x509 object.
 5174
 5175    \param x509 a pointer to a WOLFSSL_X509 structure.
 5176
 5177    _Example_
 5178    \code
 5179    WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
 5180							DYNAMIC_TYPE_X509);
 5181    ...
 5182    int x509SigType = wolfSSL_X509_get_signature_type(x509);
 5183
 5184    if(x509SigType != EXPECTED){
 5185	// Deal with an unexpected value
 5186    }
 5187    \endcode
 5188
 5189    \sa wolfSSL_X509_get_signature
 5190    \sa wolfSSL_X509_version
 5191    \sa wolfSSL_X509_get_der
 5192    \sa wolfSSL_X509_get_serial_number
 5193    \sa wolfSSL_X509_notBefore
 5194    \sa wolfSSL_X509_notAfter
 5195    \sa wolfSSL_X509_free
 5196*/
 5197int wolfSSL_X509_get_signature_type(WOLFSSL_X509* x509);
 5198
 5199/*!
 5200    \brief This function frees a WOLFSSL_X509 structure.
 5201
 5202
 5203    \param x509 a pointer to the WOLFSSL_X509 struct.
 5204
 5205    _Example_
 5206    \code
 5207    WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALOC(sizeof(WOLFSSL_X509), NULL,
 5208    DYNAMIC_TYPE_X509) ;
 5209
 5210    wolfSSL_X509_free(x509);
 5211
 5212    \endcode
 5213
 5214    \sa wolfSSL_X509_get_signature
 5215    \sa wolfSSL_X509_version
 5216    \sa wolfSSL_X509_get_der
 5217    \sa wolfSSL_X509_get_serial_number
 5218    \sa wolfSSL_X509_notBefore
 5219    \sa wolfSSL_X509_notAfter
 5220
 5221*/
 5222void wolfSSL_X509_free(WOLFSSL_X509* x509);
 5223
 5224/*!
 5225    \ingroup CertsKeys
 5226
 5227    \brief Gets the X509 signature and stores it in the buffer.
 5228
 5229    \return SSL_SUCCESS returned if the function successfully executes.
 5230    The signature is loaded into the buffer.
 5231    \return SSL_FATAL_ERRROR returns if the x509 struct or the bufSz member
 5232    is NULL. There is also a check for the length member of the sig structure
 5233    (sig is a member of x509).
 5234
 5235    \param x509 pointer to a WOLFSSL_X509 structure.
 5236    \param buf a char pointer to the buffer.
 5237    \param bufSz an integer pointer to the size of the buffer.
 5238
 5239    _Example_
 5240    \code
 5241    WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
 5242    DYNAMIC_TYPE_X509);
 5243    unsigned char* buf; // Initialize
 5244    int* bufSz = sizeof(buf)/sizeof(unsigned char);
 5245    ...
 5246    if(wolfSSL_X509_get_signature(x509, buf, bufSz) != SSL_SUCCESS){
 5247	    // The function did not execute successfully.
 5248    } else{
 5249	    // The buffer was written to correctly.
 5250    }
 5251    \endcode
 5252
 5253    \sa wolfSSL_X509_get_serial_number
 5254    \sa wolfSSL_X509_get_signature_type
 5255    \sa wolfSSL_X509_get_device_type
 5256*/
 5257int wolfSSL_X509_get_signature(WOLFSSL_X509* x509, unsigned char* buf, int* bufSz);
 5258
 5259/*!
 5260    \ingroup CertsKeys
 5261
 5262    \brief This function adds a certificate to the WOLFSSL_X509_STRE structure.
 5263
 5264    \return SSL_SUCCESS If certificate is added successfully.
 5265    \return SSL_FATAL_ERROR: If certificate is not added successfully.
 5266
 5267    \param store certificate store to add the certificate to.
 5268    \param x509 certificate to add.
 5269
 5270    _Example_
 5271    \code
 5272    WOLFSSL_X509_STORE* str;
 5273    WOLFSSL_X509* x509;
 5274    int ret;
 5275    ret = wolfSSL_X509_STORE_add_cert(str, x509);
 5276    //check ret value
 5277    \endcode
 5278
 5279    \sa wolfSSL_X509_free
 5280*/
 5281int wolfSSL_X509_STORE_add_cert(WOLFSSL_X509_STORE* store, WOLFSSL_X509* x509);
 5282
 5283/*!
 5284    \ingroup CertsKeys
 5285
 5286    \brief This function is a getter function for chain variable
 5287    in WOLFSSL_X509_STORE_CTX structure. Currently chain is not populated.
 5288
 5289    \return pointer if successful returns WOLFSSL_STACK
 5290    (same as STACK_OF(WOLFSSL_X509)) pointer
 5291    \return Null upon failure
 5292
 5293    \param ctx certificate store ctx to get parse chain from.
 5294
 5295    _Example_
 5296    \code
 5297    WOLFSSL_STACK* sk;
 5298    WOLFSSL_X509_STORE_CTX* ctx;
 5299    sk = wolfSSL_X509_STORE_CTX_get_chain(ctx);
 5300    //check sk for NULL and then use it. sk needs freed after done.
 5301    \endcode
 5302
 5303    \sa wolfSSL_sk_X509_free
 5304*/
 5305WOLFSSL_STACK* wolfSSL_X509_STORE_CTX_get_chain(
 5306                                                   WOLFSSL_X509_STORE_CTX* ctx);
 5307
 5308/*!
 5309    \ingroup CertsKeys
 5310
 5311    \brief This function takes in a flag to change the behavior of the
 5312    WOLFSSL_X509_STORE structure passed in. An example of a flag used
 5313    is WOLFSSL_CRL_CHECK.
 5314
 5315    \return SSL_SUCCESS If no errors were encountered when setting the flag.
 5316    \return <0 a negative value will be returned upon failure.
 5317
 5318    \param str certificate store to set flag in.
 5319    \param flag flag for behavior.
 5320
 5321    _Example_
 5322    \code
 5323    WOLFSSL_X509_STORE* str;
 5324    int ret;
 5325    // create and set up str
 5326    ret = wolfSSL_X509_STORE_set_flags(str, WOLFSSL_CRL_CHECKALL);
 5327    If (ret != SSL_SUCCESS) {
 5328    	//check ret value and handle error case
 5329    }
 5330    \endcode
 5331
 5332    \sa wolfSSL_X509_STORE_new
 5333    \sa wolfSSL_X509_STORE_free
 5334*/
 5335int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store,
 5336                                                            unsigned long flag);
 5337
 5338/*!
 5339    \ingroup CertsKeys
 5340
 5341    \brief This function the certificate "not before" validity encoded as
 5342    a byte array.
 5343
 5344
 5345    \return NULL returned if the WOLFSSL_X509 structure is NULL.
 5346    \return byte is returned that contains the notBeforeData.
 5347
 5348    \param x509 pointer to a WOLFSSL_X509 structure.
 5349
 5350    _Example_
 5351    \code
 5352    WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
 5353							DYNAMIC_TYPE_X509);
 5354    ...
 5355    byte* notBeforeData = wolfSSL_X509_notBefore(x509);
 5356
 5357
 5358    \endcode
 5359
 5360    \sa wolfSSL_X509_get_signature
 5361    \sa wolfSSL_X509_version
 5362    \sa wolfSSL_X509_get_der
 5363    \sa wolfSSL_X509_get_serial_number
 5364    \sa wolfSSL_X509_notAfter
 5365    \sa wolfSSL_X509_free
 5366*/
 5367const byte* wolfSSL_X509_notBefore(WOLFSSL_X509* x509);
 5368
 5369/*!
 5370    \ingroup CertsKeys
 5371
 5372    \brief This function the certificate "not after" validity encoded as
 5373    a byte array.
 5374
 5375    \return NULL returned if the WOLFSSL_X509 structure is NULL.
 5376    \return byte is returned that contains the notAfterData.
 5377
 5378    \param x509 pointer to a WOLFSSL_X509 structure.
 5379
 5380    _Example_
 5381    \code
 5382    WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
 5383							DYNAMIC_TYPE_X509);
 5384    ...
 5385    byte* notAfterData = wolfSSL_X509_notAfter(x509);
 5386
 5387
 5388    \endcode
 5389
 5390    \sa wolfSSL_X509_get_signature
 5391    \sa wolfSSL_X509_version
 5392    \sa wolfSSL_X509_get_der
 5393    \sa wolfSSL_X509_get_serial_number
 5394    \sa wolfSSL_X509_notBefore
 5395    \sa wolfSSL_X509_free
 5396*/
 5397const byte* wolfSSL_X509_notAfter(WOLFSSL_X509* x509);
 5398
 5399/*!
 5400    \ingroup Setup
 5401
 5402    \brief This function is used to copy a WOLFSSL_ASN1_INTEGER
 5403    value to a WOLFSSL_BIGNUM structure.
 5404
 5405    \return pointer On successfully copying the WOLFSSL_ASN1_INTEGER
 5406    value a WOLFSSL_BIGNUM pointer is returned.
 5407    \return Null upon failure.
 5408
 5409    \param ai WOLFSSL_ASN1_INTEGER structure to copy from.
 5410    \param bn if wanting to copy into an already existing
 5411    WOLFSSL_BIGNUM struct then pass in a pointer to it.
 5412    Optionally this can be NULL and a new WOLFSSL_BIGNUM
 5413    structure will be created.
 5414
 5415    _Example_
 5416    \code
 5417    WOLFSSL_ASN1_INTEGER* ai;
 5418    WOLFSSL_BIGNUM* bn;
 5419    // create ai
 5420    bn = wolfSSL_ASN1_INTEGER_to_BN(ai, NULL);
 5421
 5422    // or if having already created bn and wanting to reuse structure
 5423    // wolfSSL_ASN1_INTEGER_to_BN(ai, bn);
 5424    // check bn is or return value is not NULL
 5425    \endcode
 5426
 5427    \sa none
 5428*/
 5429WOLFSSL_BIGNUM *wolfSSL_ASN1_INTEGER_to_BN(const WOLFSSL_ASN1_INTEGER *ai,
 5430                                       WOLFSSL_BIGNUM *bn);
 5431
 5432/*!
 5433    \ingroup Setup
 5434
 5435    \brief This function adds the certificate to the internal chain
 5436    being built in the WOLFSSL_CTX structure.
 5437
 5438    \return SSL_SUCCESS after successfully adding the certificate.
 5439    \return SSL_FAILURE if failing to add the certificate to the chain.
 5440
 5441    \param ctx WOLFSSL_CTX structure to add certificate to.
 5442    \param x509 certificate to add to the chain.
 5443
 5444    _Example_
 5445    \code
 5446    WOLFSSL_CTX* ctx;
 5447    WOLFSSL_X509* x509;
 5448    int ret;
 5449    // create ctx
 5450    ret = wolfSSL_CTX_add_extra_chain_cert(ctx, x509);
 5451    // check ret value
 5452    \endcode
 5453
 5454    \sa wolfSSL_CTX_new
 5455    \sa wolfSSL_CTX_free
 5456*/
 5457long wolfSSL_CTX_add_extra_chain_cert(WOLFSSL_CTX* ctx, WOLFSSL_X509* x509);
 5458
 5459/*!
 5460    \ingroup Setup
 5461
 5462    \brief This function returns the get read ahead flag from a
 5463    WOLFSSL_CTX structure.
 5464
 5465    \return flag On success returns the read ahead flag.
 5466    \return SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.
 5467
 5468    \param ctx WOLFSSL_CTX structure to get read ahead flag from.
 5469
 5470    _Example_
 5471    \code
 5472    WOLFSSL_CTX* ctx;
 5473    int flag;
 5474    // setup ctx
 5475    flag = wolfSSL_CTX_get_read_ahead(ctx);
 5476    //check flag
 5477    \endcode
 5478
 5479    \sa wolfSSL_CTX_new
 5480    \sa wolfSSL_CTX_free
 5481    \sa wolfSSL_CTX_set_read_ahead
 5482*/
 5483int  wolfSSL_CTX_get_read_ahead(WOLFSSL_CTX* ctx);
 5484
 5485/*!
 5486    \ingroup Setup
 5487
 5488    \brief This function sets the read ahead flag in the WOLFSSL_CTX structure.
 5489
 5490    \return SSL_SUCCESS If ctx read ahead flag set.
 5491    \return SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned.
 5492
 5493    \param ctx WOLFSSL_CTX structure to set read ahead flag.
 5494    \param v read ahead flag
 5495
 5496    _Example_
 5497    \code
 5498    WOLFSSL_CTX* ctx;
 5499    int flag;
 5500    int ret;
 5501    // setup ctx
 5502    ret = wolfSSL_CTX_set_read_ahead(ctx, flag);
 5503    // check return value
 5504    \endcode
 5505
 5506    \sa wolfSSL_CTX_new
 5507    \sa wolfSSL_CTX_free
 5508    \sa wolfSSL_CTX_get_read_ahead
 5509*/
 5510int  wolfSSL_CTX_set_read_ahead(WOLFSSL_CTX* ctx, int v);
 5511
 5512/*!
 5513    \ingroup Setup
 5514
 5515    \brief This function sets the options argument to use with OCSP.
 5516
 5517    \return SSL_FAILURE If ctx or it’s cert manager is NULL.
 5518    \return SSL_SUCCESS If successfully set.
 5519
 5520    \param ctx WOLFSSL_CTX structure to set user argument.
 5521    \param arg user argument.
 5522
 5523    _Example_
 5524    \code
 5525    WOLFSSL_CTX* ctx;
 5526    void* data;
 5527    int ret;
 5528    // setup ctx
 5529    ret = wolfSSL_CTX_set_tlsext_status_arg(ctx, data);
 5530
 5531    //check ret value
 5532    \endcode
 5533
 5534    \sa wolfSSL_CTX_new
 5535    \sa wolfSSL_CTX_free
 5536*/
 5537long wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX* ctx, void* arg);
 5538
 5539/*!
 5540    \ingroup CertsKeys
 5541
 5542    \brief Sets a callback to select the client certificate and private key.
 5543
 5544    This function allows the application to register a callback that will be invoked
 5545    when a client certificate is requested during the handshake. The callback can
 5546    select and provide the certificate and key to use.
 5547
 5548    \param ctx The WOLFSSL_CTX object.
 5549    \param cb  The callback function to select the client certificate and key.
 5550
 5551    \return void
 5552
 5553    _Example_
 5554    \code
 5555    int my_client_cert_cb(WOLFSSL *ssl, WOLFSSL_X509 **x509, WOLFSSL_EVP_PKEY **pkey) { ... }
 5556    wolfSSL_CTX_set_client_cert_cb(ctx, my_client_cert_cb);
 5557    \endcode
 5558
 5559    \sa wolfSSL_CTX_set_cert_cb
 5560*/
 5561void wolfSSL_CTX_set_client_cert_cb(WOLFSSL_CTX *ctx, client_cert_cb cb);
 5562
 5563/*!
 5564    \ingroup CertsKeys
 5565
 5566    \brief Sets a generic certificate setup callback.
 5567
 5568    This function allows the application to register a callback that will be invoked
 5569    during certificate setup. The callback can perform custom certificate selection
 5570    or loading logic.
 5571
 5572    \param ctx The WOLFSSL_CTX object.
 5573    \param cb  The callback function for certificate setup.
 5574    \param arg User argument to pass to the callback.
 5575
 5576    \return void
 5577
 5578    _Example_
 5579    \code
 5580    int my_cert_setup_cb(WOLFSSL* ssl, void* arg) { ... }
 5581    wolfSSL_CTX_set_cert_cb(ctx, my_cert_setup_cb, NULL);
 5582    \endcode
 5583
 5584    \sa wolfSSL_CTX_set_client_cert_cb
 5585*/
 5586void wolfSSL_CTX_set_cert_cb(WOLFSSL_CTX* ctx, CertSetupCallback cb, void *arg);
 5587
 5588/*!
 5589    \ingroup OCSP
 5590
 5591    \brief Sets the callback to be used for handling OCSP status requests (OCSP stapling).
 5592
 5593    This function allows the application to register a callback that will be invoked
 5594    when an OCSP status request is received during the TLS handshake. The callback
 5595    can provide an OCSP response to be stapled to the handshake. This API is only
 5596    useful on the server side.
 5597
 5598    \param ctx The WOLFSSL_CTX object.
 5599    \param cb  The callback function to handle OCSP status requests.
 5600
 5601    \return SSL_SUCCESS on success, SSL_FAILURE otherwise.
 5602
 5603    _Example_
 5604    \code
 5605    int my_ocsp_status_cb(WOLFSSL* ssl, void* arg) { ... }
 5606    wolfSSL_CTX_set_tlsext_status_cb(ctx, my_ocsp_status_cb);
 5607    \endcode
 5608
 5609    \sa wolfSSL_CTX_get_tlsext_status_cb
 5610    \sa wolfSSL_CTX_set_tlsext_status_arg
 5611*/
 5612int wolfSSL_CTX_set_tlsext_status_cb(WOLFSSL_CTX* ctx, tlsextStatusCb cb);
 5613
 5614/*!
 5615    \ingroup OCSP
 5616
 5617    \brief Gets the currently set OCSP status callback for the context.
 5618
 5619    \param ctx The WOLFSSL_CTX object.
 5620    \param cb  Pointer to receive the callback function.
 5621
 5622    \return SSL_SUCCESS on success, SSL_FAILURE otherwise.
 5623
 5624    \sa wolfSSL_CTX_set_tlsext_status_cb
 5625*/
 5626int wolfSSL_CTX_get_tlsext_status_cb(WOLFSSL_CTX* ctx, tlsextStatusCb* cb);
 5627
 5628/*!
 5629    \ingroup OCSP
 5630
 5631    \brief Sets the argument to be passed to the OCSP status callback.
 5632
 5633    \param ctx The WOLFSSL_CTX object.
 5634    \param arg The user argument to pass to the callback.
 5635
 5636    \return SSL_SUCCESS on success, SSL_FAILURE otherwise.
 5637
 5638    \sa wolfSSL_CTX_set_tlsext_status_cb
 5639*/
 5640long wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX* ctx, void* arg);
 5641
 5642/*!
 5643    \ingroup OCSP
 5644
 5645    \brief Gets the OCSP response that will be sent (stapled) to the peer.
 5646
 5647    \param ssl The WOLFSSL session.
 5648    \param resp Pointer to receive the response buffer.
 5649
 5650    \return Length of the response, or negative value on error.
 5651
 5652    \sa wolfSSL_set_tlsext_status_ocsp_resp
 5653*/
 5654long wolfSSL_get_tlsext_status_ocsp_resp(WOLFSSL *ssl, unsigned char **resp);
 5655
 5656/*!
 5657    \ingroup OCSP
 5658
 5659    \brief Sets the OCSP response to be sent (stapled) to the peer.
 5660
 5661    The buffer in resp becomes owned by wolfSSL and will be freed by
 5662    wolfSSL. The application must not free the buffer after calling this
 5663    function.
 5664
 5665    \param ssl The WOLFSSL session.
 5666    \param resp Pointer to the response buffer.
 5667    \param len  Length of the response buffer.
 5668
 5669    \return SSL_SUCCESS on success, SSL_FAILURE otherwise.
 5670
 5671    \sa wolfSSL_get_tlsext_status_ocsp_resp
 5672*/
 5673long wolfSSL_set_tlsext_status_ocsp_resp(WOLFSSL *ssl, unsigned char *resp, int len);
 5674
 5675/*!
 5676    \ingroup OCSP
 5677
 5678    \brief Sets multiple OCSP responses for TLS multi-certificate chains.
 5679
 5680    The buffer in resp becomes owned by wolfSSL and will be freed by
 5681    wolfSSL. The application must not free the buffer after calling this
 5682    function.
 5683
 5684    \param ssl The WOLFSSL session.
 5685    \param resp Pointer to the response buffer.
 5686    \param len  Length of the response buffer.
 5687    \param idx  Index of the certificate chain.
 5688
 5689    \return SSL_SUCCESS on success, SSL_FAILURE otherwise.
 5690*/
 5691int wolfSSL_set_tlsext_status_ocsp_resp_multi(WOLFSSL* ssl, unsigned char *resp, int len, word32 idx);
 5692
 5693/*!
 5694    \ingroup OCSP
 5695
 5696    \brief Sets a callback to verify the OCSP status response.
 5697
 5698    It is recommended to enable SESSION_CERTS in order to have access to the
 5699    peer's certificate chain during OCSP verification.
 5700
 5701    \param ctx   The WOLFSSL_CTX object.
 5702    \param cb    The callback function.
 5703    \param cbArg User argument to pass to the callback.
 5704
 5705    \return void
 5706
 5707    _Example_
 5708    \code
 5709    void my_ocsp_verify_cb(WOLFSSL* ssl, int err, byte* resp, word32 respSz, word32 idx, void* arg)
 5710    {
 5711        (void)arg;
 5712        if (err == 0 && staple && stapleSz > 0) {
 5713            printf("Client: OCSP staple received, size=%u\n", stapleSz);
 5714            return 0;
 5715        }
 5716        // Manual OCSP staple verification if err != 0
 5717        if (err != 0 && staple && stapleSz > 0) {
 5718            WOLFSSL_CERT_MANAGER* cm = NULL;
 5719            DecodedCert cert;
 5720            byte certInit = 0;
 5721            WOLFSSL_OCSP* ocsp = NULL;
 5722            WOLFSSL_X509_CHAIN* peerCerts;
 5723            int i;
 5724
 5725            cm = wolfSSL_CertManagerNew();
 5726            if (cm == NULL)
 5727                goto cleanup;
 5728            if (wolfSSL_CertManagerLoadCA(cm, CA_CERT, NULL) != WOLFSSL_SUCCESS)
 5729                goto cleanup;
 5730
 5731            peerCerts = wolfSSL_get_peer_chain(ssl);
 5732            if (peerCerts == NULL || wolfSSL_get_chain_count(peerCerts) <= (int)idx)
 5733                goto cleanup;
 5734
 5735            for (i = idx + 1; i < wolfSSL_get_chain_count(peerCerts); i++) {
 5736                if (wolfSSL_CertManagerLoadCABuffer(cm, wolfSSL_get_chain_cert(peerCerts, i),
 5737                        wolfSSL_get_chain_length(peerCerts, i), WOLFSSL_FILETYPE_ASN1) != WOLFSSL_SUCCESS)
 5738                    goto cleanup;
 5739            }
 5740
 5741            wc_InitDecodedCert(&cert, wolfSSL_get_chain_cert(peerCerts, idx), wolfSSL_get_chain_length(peerCerts, idx), NULL);
 5742            certInit = 1;
 5743            if (wc_ParseCert(&cert, CERT_TYPE, VERIFY, cm) != 0)
 5744                goto cleanup;
 5745            if ((ocsp = wc_NewOCSP(cm)) == NULL)
 5746                goto cleanup;
 5747            if (wc_CheckCertOcspResponse(ocsp, &cert, staple, stapleSz, NULL) != 0)
 5748                goto cleanup;
 5749
 5750            printf("Client: Manual OCSP staple verification succeeded for idx=%u\n", idx);
 5751            err = 0;
 5752    cleanup:
 5753            wc_FreeOCSP(ocsp);
 5754            if (certInit)
 5755                wc_FreeDecodedCert(&cert);
 5756            wolfSSL_CertManagerFree(cm);
 5757            if (err == 0)
 5758                return 0;
 5759            printf("Client: Manual OCSP staple verification failed for idx=%u\n", idx);
 5760        }
 5761        printf("Client: OCSP staple verify error=%d\n", err);
 5762        return err;
 5763    }
 5764    wolfSSL_CTX_set_ocsp_status_verify_cb(ctx, my_ocsp_verify_cb, NULL);
 5765    \endcode
 5766*/
 5767void wolfSSL_CTX_set_ocsp_status_verify_cb(WOLFSSL_CTX* ctx, ocspVerifyStatusCb cb, void* cbArg);
 5768
 5769/*!
 5770    \ingroup Setup
 5771
 5772    \brief This function sets the optional argument to be passed to
 5773    the PRF callback.
 5774
 5775    \return SSL_FAILURE If ctx is NULL.
 5776    \return SSL_SUCCESS If successfully set.
 5777
 5778    \param ctx WOLFSSL_CTX structure to set user argument.
 5779    \param arg user argument.
 5780
 5781    _Example_
 5782    \code
 5783    WOLFSSL_CTX* ctx;
 5784    void* data;
 5785    int ret;
 5786    // setup ctx
 5787    ret = wolfSSL_CTX_set_tlsext_opaques_prf_input_callback_arg(ctx, data);
 5788    //check ret value
 5789    \endcode
 5790
 5791    \sa wolfSSL_CTX_new
 5792    \sa wolfSSL_CTX_free
 5793*/
 5794long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg(
 5795        WOLFSSL_CTX* ctx, void* arg);
 5796
 5797/*!
 5798    \ingroup Setup
 5799
 5800    \brief This function ORs the bits in \p opt into the options mask of the
 5801    given WOLFSSL_CTX. The options mask is inherited by every WOLFSSL session
 5802    later created from this context. Bits are accumulated — to remove an
 5803    option, use wolfSSL_CTX_clear_options(). The OpenSSL-style "SSL_OP_*"
 5804    macros are aliases for the corresponding "WOLFSSL_OP_*" values; either
 5805    spelling may be used.
 5806
 5807    Effective options:
 5808
 5809    | Macro                                | Effect |
 5810    | ------------------------------------ | ------ |
 5811    | SSL_OP_NO_SSLv2                      | Disable SSLv2 (wolfSSL never supports SSLv2; flag is accepted for OpenSSL compatibility) |
 5812    | SSL_OP_NO_SSLv3                      | Disable SSLv3 |
 5813    | SSL_OP_NO_TLSv1                      | Disable TLS 1.0 |
 5814    | SSL_OP_NO_TLSv1_1                    | Disable TLS 1.1 |
 5815    | SSL_OP_NO_TLSv1_2                    | Disable TLS 1.2 |
 5816    | SSL_OP_NO_TLSv1_3                    | Disable TLS 1.3 (requires WOLFSSL_TLS13) |
 5817    | SSL_OP_NO_COMPRESSION                | Disable record-layer compression (no-op unless HAVE_LIBZ) |
 5818    | SSL_OP_NO_TICKET                     | Disable RFC 5077 session tickets (TLS 1.2 only; TLS 1.3 ignores this flag); requires HAVE_SESSION_TICKET and (OPENSSL_EXTRA or HAVE_WEBSERVER or WOLFSSL_WPAS_SMALL) |
 5819    | SSL_OP_NO_RENEGOTIATION              | Reject peer-initiated renegotiation |
 5820    | SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION | Disable session resumption on renegotiation |
 5821    | SSL_OP_COOKIE_EXCHANGE               | Enable HelloVerifyRequest cookie exchange (default-on for DTLS) |
 5822    | SSL_OP_NO_QUERY_MTU                  | DTLS: do not query the path MTU |
 5823    | SSL_OP_CIPHER_SERVER_PREFERENCE      | Server uses its own cipher preference order rather than the client's |
 5824    | SSL_OP_SINGLE_DH_USE                 | Generate a fresh DH key for every handshake |
 5825    | SSL_OP_SINGLE_ECDH_USE               | Generate a fresh ECDH key for every handshake |
 5826    | SSL_OP_EPHEMERAL_RSA                 | Use ephemeral RSA (legacy, accepted for OpenSSL compatibility) |
 5827    | SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS   | Do not insert empty fragments before a record (CBC BEAST workaround) |
 5828    | SSL_OP_PKCS1_CHECK_1 / _2            | Accepted for OpenSSL compatibility |
 5829    | SSL_OP_LEGACY_SERVER_CONNECT         | Always allow legacy (unsafe) initial connect; defined as 0 — no effect (requires the openssl/ssl.h compatibility header) |
 5830
 5831    Convenience macros and bug-workaround flags (all members of SSL_OP_ALL,
 5832    accepted for OpenSSL compatibility but otherwise no-ops in wolfSSL):
 5833
 5834    - SSL_OP_ALL (bitwise OR of all bug-workaround flags below)
 5835    - SSL_OP_MICROSOFT_SESS_ID_BUG
 5836    - SSL_OP_NETSCAPE_CHALLENGE_BUG
 5837    - SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
 5838    - SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
 5839    - SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
 5840    - SSL_OP_MSIE_SSLV2_RSA_PADDING
 5841    - SSL_OP_SSLEAY_080_CLIENT_DH_BUG
 5842    - SSL_OP_TLS_D5_BUG
 5843    - SSL_OP_TLS_BLOCK_PADDING_BUG
 5844    - SSL_OP_TLS_ROLLBACK_BUG
 5845    - SSL_OP_NETSCAPE_CA_DN_BUG
 5846    - SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
 5847
 5848    Convenience composite:
 5849
 5850    - SSL_OP_NO_SSL_MASK = SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1 | SSL_OP_NO_TLSv1_2 | SSL_OP_NO_TLSv1_3
 5851
 5852    \param ctx WOLFSSL_CTX structure on which to set the options mask.
 5853    \param opt the bitmask of SSL_OP_* / WOLFSSL_OP_* flags to OR into the
 5854    current mask.
 5855
 5856    \return BAD_FUNC_ARG if \p ctx is NULL.
 5857    \return The updated options mask value stored in \p ctx on success.
 5858
 5859    _Example_
 5860    \code
 5861    WOLFSSL_CTX* ctx;
 5862    long mask;
 5863    mask = wolfSSL_CTX_set_options(ctx,
 5864        SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1 |
 5865        SSL_OP_NO_COMPRESSION | SSL_OP_CIPHER_SERVER_PREFERENCE);
 5866    // 'mask' now reflects the accumulated options stored in ctx
 5867    \endcode
 5868
 5869    \sa wolfSSL_CTX_clear_options
 5870    \sa wolfSSL_CTX_get_options
 5871    \sa wolfSSL_set_options
 5872    \sa wolfSSL_get_options
 5873*/
 5874long wolfSSL_CTX_set_options(WOLFSSL_CTX* ctx, long opt);
 5875
 5876/*!
 5877    \ingroup Setup
 5878
 5879    \brief This function ORs the bits in \p op into the options mask of the
 5880    given WOLFSSL session. The set of recognized "SSL_OP_*" / "WOLFSSL_OP_*"
 5881    flags is identical to that documented for wolfSSL_CTX_set_options();
 5882    refer to that function for the full options table and the build-option
 5883    requirements of individual flags. Flags inherited from the parent
 5884    WOLFSSL_CTX remain set; setting SSL_OP_NO_TLSv1_3 here lowers the
 5885    session's negotiated minor version to TLS 1.2.
 5886
 5887    \param s WOLFSSL session on which to set the options mask.
 5888    \param op the bitmask of SSL_OP_* / WOLFSSL_OP_* flags to OR into the
 5889    current mask.
 5890
 5891    \return The updated options mask value stored in \p s on success, or 0 if
 5892    \p s is NULL.
 5893
 5894    _Example_
 5895    \code
 5896    WOLFSSL* ssl;
 5897    long mask;
 5898    mask = wolfSSL_set_options(ssl, SSL_OP_NO_TLSv1_3);
 5899    // 'mask' now reflects the accumulated options stored in ssl
 5900    \endcode
 5901
 5902    \sa wolfSSL_CTX_set_options
 5903    \sa wolfSSL_clear_options
 5904    \sa wolfSSL_get_options
 5905    \sa wolfSSL_new
 5906    \sa wolfSSL_free
 5907*/
 5908long wolfSSL_set_options(WOLFSSL *s, long op);
 5909
 5910/*!
 5911    \ingroup Setup
 5912
 5913    \brief This function returns the current options mask.
 5914
 5915    \return val Returns the mask value stored in ssl.
 5916
 5917    \param s WOLFSSL structure to get options mask from.
 5918
 5919    _Example_
 5920    \code
 5921    WOLFSSL* ssl;
 5922    unsigned long mask;
 5923    mask  = wolfSSL_get_options(ssl);
 5924    // check mask
 5925    \endcode
 5926
 5927    \sa wolfSSL_new
 5928    \sa wolfSSL_free
 5929    \sa wolfSSL_set_options
 5930*/
 5931long wolfSSL_get_options(const WOLFSSL *s);
 5932
 5933/*!
 5934    \ingroup Setup
 5935
 5936    \brief This is used to set the debug argument passed around.
 5937
 5938    \return SSL_SUCCESS On successful setting argument.
 5939    \return SSL_FAILURE If an NULL ssl passed in.
 5940
 5941    \param s WOLFSSL structure to set argument in.
 5942    \param arg argument to use.
 5943
 5944    _Example_
 5945    \code
 5946    WOLFSSL* ssl;
 5947    void* args;
 5948    int ret;
 5949    // create ssl object
 5950    ret  = wolfSSL_set_tlsext_debug_arg(ssl, args);
 5951    // check ret value
 5952    \endcode
 5953
 5954    \sa wolfSSL_new
 5955    \sa wolfSSL_free
 5956*/
 5957long wolfSSL_set_tlsext_debug_arg(WOLFSSL *s, void *arg);
 5958
 5959/*!
 5960    \ingroup openSSL
 5961
 5962    \brief This function is called when the client application request
 5963    that a server send back an OCSP status response (also known as
 5964    OCSP stapling).Currently, the only supported type is
 5965    TLSEXT_STATUSTYPE_ocsp.
 5966
 5967    \return 1 upon success.
 5968    \return 0 upon error.
 5969
 5970    \param s pointer to WOLFSSL struct which is created by SSL_new() function
 5971    \param type ssl extension type which TLSEXT_STATUSTYPE_ocsp is
 5972    only supported.
 5973
 5974    _Example_
 5975    \code
 5976    WOLFSSL *ssl;
 5977    WOLFSSL_CTX *ctx;
 5978    int ret;
 5979    ctx = wolfSSL_CTX_new(wolfSSLv23_server_method());
 5980    ssl = wolfSSL_new(ctx);
 5981    ret = WolfSSL_set_tlsext_status_type(ssl,TLSEXT_STATUSTYPE_ocsp);
 5982    wolfSSL_free(ssl);
 5983    wolfSSL_CTX_free(ctx);
 5984    \endcode
 5985
 5986    \sa wolfSSL_new
 5987    \sa wolfSSL_CTX_new
 5988    \sa wolfSSL_free
 5989    \sa wolfSSL_CTX_free
 5990*/
 5991long wolfSSL_set_tlsext_status_type(WOLFSSL *s, int type);
 5992
 5993/*!
 5994    \ingroup Setup
 5995
 5996    \brief This is used to get the results after trying to verify the peer's
 5997    certificate.
 5998
 5999    \return X509_V_OK On successful verification.
 6000    \return SSL_FAILURE If an NULL ssl passed in.
 6001
 6002    \param ssl WOLFSSL structure to get verification results from.
 6003
 6004    _Example_
 6005    \code
 6006    WOLFSSL* ssl;
 6007    long ret;
 6008    // attempt/complete handshake
 6009    ret  = wolfSSL_get_verify_result(ssl);
 6010    // check ret value
 6011    \endcode
 6012
 6013    \sa wolfSSL_new
 6014    \sa wolfSSL_free
 6015*/
 6016long wolfSSL_get_verify_result(const WOLFSSL *ssl);
 6017
 6018/*!
 6019    \ingroup Debug
 6020
 6021    \brief This function converts an error code returned by
 6022    wolfSSL_get_error() into a more human-readable error string
 6023    and prints that string to the output file - fp.  err is the
 6024    error code returned by wolfSSL_get_error() and fp is the
 6025    file which the error string will be placed in.
 6026
 6027    \return none No returns.
 6028
 6029    \param fp output file for human-readable error string to be written to.
 6030    \param err error code returned by wolfSSL_get_error().
 6031
 6032    _Example_
 6033    \code
 6034    int err = 0;
 6035    WOLFSSL* ssl;
 6036    FILE* fp = ...
 6037    ...
 6038    err = wolfSSL_get_error(ssl, 0);
 6039    wolfSSL_ERR_print_errors_fp(fp, err);
 6040    \endcode
 6041
 6042    \sa wolfSSL_get_error
 6043    \sa wolfSSL_ERR_error_string
 6044    \sa wolfSSL_ERR_error_string_n
 6045    \sa wolfSSL_load_error_strings
 6046*/
 6047void  wolfSSL_ERR_print_errors_fp(XFILE fp, int err);
 6048
 6049/*!
 6050    \ingroup Debug
 6051
 6052    \brief This function uses the provided callback to handle error reporting.
 6053    The callback function is executed for each error line. The string, length,
 6054    and userdata are passed into the callback parameters.
 6055
 6056    \return none No returns.
 6057
 6058    \param cb the callback function.
 6059    \param u userdata to pass into the callback function.
 6060
 6061    _Example_
 6062    \code
 6063    int error_cb(const char *str, size_t len, void *u)
 6064    { fprintf((FILE*)u, "%-*.*s\n", (int)len, (int)len, str); return 0; }
 6065    ...
 6066    FILE* fp = ...
 6067    wolfSSL_ERR_print_errors_cb(error_cb, fp);
 6068    \endcode
 6069
 6070    \sa wolfSSL_get_error
 6071    \sa wolfSSL_ERR_error_string
 6072    \sa wolfSSL_ERR_error_string_n
 6073    \sa wolfSSL_load_error_strings
 6074*/
 6075void  wolfSSL_ERR_print_errors_cb (
 6076        int (*cb)(const char *str, size_t len, void *u), void *u);
 6077
 6078/*!
 6079    \brief The function sets the client_psk_cb member of the
 6080    WOLFSSL_CTX structure.
 6081
 6082    \return none No returns.
 6083
 6084    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 6085    wolfSSL_CTX_new().
 6086    \param cb wc_psk_client_callback is a function pointer that will be
 6087    stored in the WOLFSSL_CTX structure. Return value is the key length on
 6088    success or zero on error.
 6089    unsigned int (*wc_psk_client_callback)
 6090    PSK client callback parameters:
 6091    WOLFSSL* ssl - Pointer to the wolfSSL structure
 6092    const char* hint - A stored string that could be displayed to provide a
 6093                        hint to the user.
 6094    char* identity - The ID will be stored here.
 6095    unsigned int id_max_len - Size of the ID buffer.
 6096    unsigned char* key - The key will be stored here.
 6097    unsigned int key_max_len - The max size of the key.
 6098
 6099    _Example_
 6100    \code
 6101    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def );
 6102    …
 6103    static WC_INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint,
 6104    char* identity, unsigned int id_max_len, unsigned char* key,
 6105    Unsigned int key_max_len){
 6106    …
 6107    wolfSSL_CTX_set_psk_client_callback(ctx, my_psk_client_cb);
 6108    \endcode
 6109
 6110    \sa wolfSSL_set_psk_client_callback
 6111    \sa wolfSSL_set_psk_server_callback
 6112    \sa wolfSSL_CTX_set_psk_server_callback
 6113    \sa wolfSSL_CTX_set_psk_client_callback
 6114*/
 6115void wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX* ctx,
 6116                                                    wc_psk_client_callback cb);
 6117
 6118/*!
 6119    \brief Sets the PSK client side callback.
 6120
 6121    \return none No returns.
 6122
 6123    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6124    \param cb a function pointer to type wc_psk_client_callback. Return value
 6125    is the key length on success or zero on error.
 6126    unsigned int (*wc_psk_client_callback)
 6127    PSK client callback parameters:
 6128    WOLFSSL* ssl - Pointer to the wolfSSL structure
 6129    const char* hint - A stored string that could be displayed to provide a
 6130                        hint to the user.
 6131    char* identity - The ID will be stored here.
 6132    unsigned int id_max_len - Size of the ID buffer.
 6133    unsigned char* key - The key will be stored here.
 6134    unsigned int key_max_len - The max size of the key.
 6135
 6136    _Example_
 6137    \code
 6138    WOLFSSL* ssl;
 6139    static WC_INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint,
 6140    char* identity, unsigned int id_max_len, unsigned char* key,
 6141    Unsigned int key_max_len){
 6142    …
 6143    if(ssl){
 6144    wolfSSL_set_psk_client_callback(ssl, my_psk_client_cb);
 6145    } else {
 6146    	// could not set callback
 6147    }
 6148    \endcode
 6149
 6150    \sa wolfSSL_CTX_set_psk_client_callback
 6151    \sa wolfSSL_CTX_set_psk_server_callback
 6152    \sa wolfSSL_set_psk_server_callback
 6153*/
 6154void wolfSSL_set_psk_client_callback(WOLFSSL* ssl,
 6155                                                    wc_psk_client_callback cb);
 6156
 6157/*!
 6158    \ingroup CertsKeys
 6159
 6160    \brief This function returns the psk identity hint.
 6161
 6162    \return pointer a const char pointer to the value that was stored in
 6163    the arrays member of the WOLFSSL structure is returned.
 6164    \return NULL returned if the WOLFSSL or Arrays structures are NULL.
 6165
 6166    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6167
 6168    _Example_
 6169    \code
 6170    WOLFSSL* ssl = wolfSSL_new(ctx);
 6171    char* idHint;
 6172    ...
 6173    idHint = wolfSSL_get_psk_identity_hint(ssl);
 6174    if(idHint){
 6175    	// The hint was retrieved
 6176    	return idHint;
 6177    } else {
 6178    	// Hint wasn’t successfully retrieved
 6179    }
 6180    \endcode
 6181
 6182    \sa wolfSSL_get_psk_identity
 6183*/
 6184const char* wolfSSL_get_psk_identity_hint(const WOLFSSL*);
 6185
 6186/*!
 6187    \ingroup CertsKeys
 6188
 6189    \brief The function returns a constant pointer to the client_identity
 6190    member of the Arrays structure.
 6191
 6192    \return string the string value of the client_identity member of the
 6193    Arrays structure.
 6194    \return NULL if the WOLFSSL structure is NULL or if the Arrays member of
 6195    the WOLFSSL structure is NULL.
 6196
 6197    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6198
 6199    _Example_
 6200    \code
 6201    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 6202    WOLFSSL* ssl = wolfSSL_new(ctx);
 6203    const char* pskID;
 6204    ...
 6205    pskID = wolfSSL_get_psk_identity(ssl);
 6206
 6207    if(pskID == NULL){
 6208	    // There is not a value in pskID
 6209    }
 6210    \endcode
 6211
 6212    \sa wolfSSL_get_psk_identity_hint
 6213    \sa wolfSSL_use_psk_identity_hint
 6214*/
 6215const char* wolfSSL_get_psk_identity(const WOLFSSL*);
 6216
 6217/*!
 6218    \ingroup CertsKeys
 6219
 6220    \brief This function stores the hint argument in the server_hint
 6221    member of the WOLFSSL_CTX structure.
 6222
 6223    \return SSL_SUCCESS returned for successful execution of the function.
 6224
 6225    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 6226    wolfSSL_CTX_new().
 6227    \param hint a constant char pointer that will be copied to the
 6228    WOLFSSL_CTX structure.
 6229
 6230    _Example_
 6231    \code
 6232    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 6233    const char* hint;
 6234    int ret;
 6235    …
 6236    ret = wolfSSL_CTX_use_psk_identity_hint(ctx, hint);
 6237    if(ret == SSL_SUCCESS){
 6238    	// Function was successful.
 6239	return ret;
 6240    } else {
 6241    	// Failure case.
 6242    }
 6243    \endcode
 6244
 6245    \sa wolfSSL_use_psk_identity_hint
 6246*/
 6247int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX* ctx, const char* hint);
 6248
 6249/*!
 6250    \ingroup CertsKeys
 6251
 6252    \brief This function stores the hint argument in the server_hint member
 6253    of the Arrays structure within the WOLFSSL structure.
 6254
 6255    \return SSL_SUCCESS returned if the hint was successfully stored in the
 6256    WOLFSSL structure.
 6257    \return SSL_FAILURE returned if the WOLFSSL or Arrays structures are NULL.
 6258
 6259    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6260    \param hint a constant character pointer that holds the hint to be saved
 6261    in memory.
 6262
 6263    _Example_
 6264    \code
 6265    WOLFSSL* ssl = wolfSSL_new(ctx);
 6266    const char* hint;
 6267    ...
 6268    if(wolfSSL_use_psk_identity_hint(ssl, hint) != SSL_SUCCESS){
 6269    	// Handle failure case.
 6270    }
 6271    \endcode
 6272
 6273    \sa wolfSSL_CTX_use_psk_identity_hint
 6274*/
 6275int wolfSSL_use_psk_identity_hint(WOLFSSL* ssl, const char* hint);
 6276
 6277/*!
 6278    \brief This function sets the psk callback for the server side in
 6279    the WOLFSSL_CTX structure.
 6280
 6281    \return none No returns.
 6282
 6283    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6284    \param cb a function pointer for the callback and will be stored in
 6285    the WOLFSSL_CTX structure. Return value is the key length on success or
 6286    zero on error.
 6287    unsigned int (*wc_psk_server_callback)
 6288    PSK server callback parameters
 6289    WOLFSSL* ssl - Pointer to the wolfSSL structure
 6290    char* identity - The ID will be stored here.
 6291    unsigned char* key - The key will be stored here.
 6292    unsigned int key_max_len - The max size of the key.
 6293
 6294    _Example_
 6295    \code
 6296    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 6297    WOLFSSL* ssl = wolfSSL_new(ctx);
 6298    …
 6299    static unsigned int my_psk_server_cb(WOLFSSL* ssl, const char* identity,
 6300                           unsigned char* key, unsigned int key_max_len)
 6301    {
 6302        // Function body.
 6303    }
 6304    …
 6305    if(ctx != NULL){
 6306        wolfSSL_CTX_set_psk_server_callback(ctx, my_psk_server_cb);
 6307    } else {
 6308    	// The CTX object was not properly initialized.
 6309    }
 6310    \endcode
 6311
 6312    \sa wc_psk_server_callback
 6313    \sa wolfSSL_set_psk_client_callback
 6314    \sa wolfSSL_set_psk_server_callback
 6315    \sa wolfSSL_CTX_set_psk_client_callback
 6316*/
 6317void wolfSSL_CTX_set_psk_server_callback(WOLFSSL_CTX* ctx,
 6318                                                    wc_psk_server_callback cb);
 6319
 6320/*!
 6321    \brief Sets the psk callback for the server side by setting the
 6322    WOLFSSL structure options members.
 6323
 6324    \return none No returns.
 6325
 6326    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6327    \param cb a function pointer for the callback and will be stored in
 6328    the WOLFSSL structure. Return value is the key length on success or  zero
 6329    on error.
 6330    unsigned int (*wc_psk_server_callback)
 6331    PSK server callback parameters
 6332    WOLFSSL* ssl - Pointer to the wolfSSL structure
 6333    char* identity - The ID will be stored here.
 6334    unsigned char* key - The key will be stored here.
 6335    unsigned int key_max_len - The max size of the key.
 6336
 6337
 6338    _Example_
 6339    \code
 6340    WOLFSSL_CTX* ctx;
 6341    WOLFSSL* ssl;
 6342    …
 6343    static unsigned int my_psk_server_cb(WOLFSSL* ssl, const char* identity,
 6344                           unsigned char* key, unsigned int key_max_len)
 6345    {
 6346        // Function body.
 6347    }
 6348    …
 6349    if(ssl != NULL && cb != NULL){
 6350        wolfSSL_set_psk_server_callback(ssl, my_psk_server_cb);
 6351    }
 6352    \endcode
 6353
 6354    \sa wolfSSL_set_psk_client_callback
 6355    \sa wolfSSL_CTX_set_psk_server_callback
 6356    \sa wolfSSL_CTX_set_psk_client_callback
 6357    \sa wolfSSL_get_psk_identity_hint
 6358    \sa wc_psk_server_callback
 6359    \sa InitSuites
 6360*/
 6361void wolfSSL_set_psk_server_callback(WOLFSSL* ssl,
 6362                                                    wc_psk_server_callback cb);
 6363
 6364
 6365/*!
 6366    \brief Sets a PSK user context in the WOLFSSL structure options member.
 6367
 6368    \return WOLFSSL_SUCCESS or WOLFSSL_FAILURE
 6369
 6370    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6371    \param psk_ctx void pointer to user PSK context
 6372
 6373    \sa wolfSSL_get_psk_callback_ctx
 6374    \sa wolfSSL_CTX_set_psk_callback_ctx
 6375    \sa wolfSSL_CTX_get_psk_callback_ctx
 6376*/
 6377int wolfSSL_set_psk_callback_ctx(WOLFSSL* ssl, void* psk_ctx);
 6378
 6379/*!
 6380    \brief Sets a PSK user context in the WOLFSSL_CTX structure.
 6381
 6382    \return WOLFSSL_SUCCESS or WOLFSSL_FAILURE
 6383
 6384    \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
 6385    \param psk_ctx void pointer to user PSK context
 6386
 6387    \sa wolfSSL_set_psk_callback_ctx
 6388    \sa wolfSSL_get_psk_callback_ctx
 6389    \sa wolfSSL_CTX_get_psk_callback_ctx
 6390*/
 6391int wolfSSL_CTX_set_psk_callback_ctx(WOLFSSL_CTX* ctx, void* psk_ctx);
 6392
 6393/*!
 6394    \brief Get a PSK user context in the WOLFSSL structure options member.
 6395
 6396    \return void pointer to user PSK context
 6397
 6398    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6399
 6400    \sa wolfSSL_set_psk_callback_ctx
 6401    \sa wolfSSL_CTX_set_psk_callback_ctx
 6402    \sa wolfSSL_CTX_get_psk_callback_ctx
 6403*/
 6404void* wolfSSL_get_psk_callback_ctx(WOLFSSL* ssl);
 6405
 6406/*!
 6407    \brief Get a PSK user context in the WOLFSSL_CTX structure.
 6408
 6409    \return void pointer to user PSK context
 6410
 6411    \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new().
 6412
 6413    \sa wolfSSL_CTX_set_psk_callback_ctx
 6414    \sa wolfSSL_set_psk_callback_ctx
 6415    \sa wolfSSL_get_psk_callback_ctx
 6416*/
 6417void* wolfSSL_CTX_get_psk_callback_ctx(WOLFSSL_CTX* ctx);
 6418
 6419/*!
 6420    \ingroup Setup
 6421
 6422    \brief This function enables the havAnon member of the CTX structure if
 6423    HAVE_ANON is defined during compilation.
 6424
 6425    \return SSL_SUCCESS returned if the function executed successfully and the
 6426    haveAnnon member of the CTX is set to 1.
 6427    \return SSL_FAILURE returned if the CTX structure was NULL.
 6428
 6429    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 6430    wolfSSL_CTX_new().
 6431
 6432    _Example_
 6433    \code
 6434    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 6435    WOLFSSL* ssl = wolfSSL_new(ctx);
 6436    ...
 6437    #ifdef HAVE_ANON
 6438	if(cipherList == NULL){
 6439	    wolfSSL_CTX_allow_anon_cipher(ctx);
 6440	    if(wolfSSL_CTX_set_cipher_list(ctx, “ADH_AES128_SHA”) != SSL_SUCCESS){
 6441		    // failure case
 6442	    }
 6443    }
 6444    #endif
 6445    \endcode
 6446
 6447    \sa none
 6448*/
 6449int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX* ctx);
 6450
 6451/*!
 6452    \ingroup Setup
 6453
 6454    \brief The wolfSSLv23_server_method() function is used to indicate
 6455    that the application is a server and will support clients connecting
 6456    with protocol version from SSL 3.0 - TLS 1.3.  This function allocates
 6457    memory for and initializes a new WOLFSSL_METHOD structure to be used when
 6458    creating the SSL/TLS context with wolfSSL_CTX_new().
 6459
 6460    \return pointer If successful, the call will return a pointer to the newly
 6461    created WOLFSSL_METHOD structure.
 6462    \return Failure If memory allocation fails when calling XMALLOC, the
 6463    failure value of the underlying malloc() implementation will be returned
 6464    (typically NULL with errno will be set to ENOMEM).
 6465
 6466    \param none No parameters
 6467
 6468    _Example_
 6469    \code
 6470    WOLFSSL_METHOD* method;
 6471    WOLFSSL_CTX* ctx;
 6472
 6473    method = wolfSSLv23_server_method();
 6474    if (method == NULL) {
 6475    	// unable to get method
 6476    }
 6477
 6478    ctx = wolfSSL_CTX_new(method);
 6479    ...
 6480    \endcode
 6481
 6482    \sa wolfSSLv3_server_method
 6483    \sa wolfTLSv1_server_method
 6484    \sa wolfTLSv1_1_server_method
 6485    \sa wolfTLSv1_2_server_method
 6486    \sa wolfTLSv1_3_server_method
 6487    \sa wolfDTLSv1_server_method
 6488    \sa wolfSSL_CTX_new
 6489*/
 6490WOLFSSL_METHOD *wolfSSLv23_server_method(void);
 6491
 6492/*!
 6493    \ingroup Setup
 6494
 6495    \brief This is used to get the internal error state of the WOLFSSL structure.
 6496
 6497    \return wolfssl_error returns ssl error state, usually a negative
 6498    \return BAD_FUNC_ARG if ssl is NULL.
 6499
 6500    \return ssl WOLFSSL structure to get state from.
 6501
 6502    _Example_
 6503    \code
 6504    WOLFSSL* ssl;
 6505    int ret;
 6506    // create ssl object
 6507    ret  = wolfSSL_state(ssl);
 6508    // check ret value
 6509    \endcode
 6510
 6511    \sa wolfSSL_new
 6512    \sa wolfSSL_free
 6513*/
 6514int  wolfSSL_state(WOLFSSL* ssl);
 6515
 6516/*!
 6517    \ingroup CertsKeys
 6518
 6519    \brief This function gets the peer’s certificate.
 6520
 6521    \return pointer a pointer to the peerCert member of the WOLFSSL_X509
 6522    structure if it exists.
 6523    \return 0 returned if the peer certificate issuer size is not defined.
 6524
 6525    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6526
 6527    _Example_
 6528    \code
 6529    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 6530    WOLFSSL* ssl = wolfSSL_new(ctx);
 6531    ...
 6532    WOLFSSL_X509* peerCert = wolfSSL_get_peer_certificate(ssl);
 6533
 6534    if(peerCert){
 6535    	// You have a pointer peerCert to the peer certification
 6536    }
 6537    \endcode
 6538
 6539    \sa wolfSSL_X509_get_issuer_name
 6540    \sa wolfSSL_X509_get_subject_name
 6541    \sa wolfSSL_X509_get_isCA
 6542*/
 6543WOLFSSL_X509* wolfSSL_get_peer_certificate(WOLFSSL* ssl);
 6544
 6545/*!
 6546    \ingroup Debug
 6547
 6548    \brief This function is similar to calling wolfSSL_get_error() and
 6549    getting SSL_ERROR_WANT_READ in return.  If the underlying error state
 6550    is SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0.
 6551
 6552    \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_READ, the
 6553    underlying I/O has data available for reading.
 6554    \return 0 There is no SSL_ERROR_WANT_READ error state.
 6555
 6556    \param ssl pointer to the SSL session, created with wolfSSL_new().
 6557
 6558    _Example_
 6559    \code
 6560    int ret;
 6561    WOLFSSL* ssl = 0;
 6562    ...
 6563
 6564    ret = wolfSSL_want_read(ssl);
 6565    if (ret == 1) {
 6566    	// underlying I/O has data available for reading (SSL_ERROR_WANT_READ)
 6567    }
 6568    \endcode
 6569
 6570    \sa wolfSSL_want_write
 6571    \sa wolfSSL_get_error
 6572*/
 6573int wolfSSL_want_read(WOLFSSL* ssl);
 6574
 6575/*!
 6576    \ingroup Debug
 6577
 6578    \brief This function is similar to calling wolfSSL_get_error() and getting
 6579    SSL_ERROR_WANT_WRITE in return. If the underlying error state is
 6580    SSL_ERROR_WANT_WRITE, this function will return 1, otherwise, 0.
 6581
 6582    \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_WRITE, the
 6583    underlying I/O needs data to be written in order for progress to be
 6584    made in the underlying SSL connection.
 6585    \return 0 There is no SSL_ERROR_WANT_WRITE error state.
 6586
 6587    \param ssl pointer to the SSL session, created with wolfSSL_new().
 6588
 6589    _Example_
 6590    \code
 6591    int ret;
 6592    WOLFSSL* ssl = 0;
 6593    ...
 6594    ret = wolfSSL_want_write(ssl);
 6595    if (ret == 1) {
 6596    	// underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE)
 6597    }
 6598    \endcode
 6599
 6600    \sa wolfSSL_want_read
 6601    \sa wolfSSL_get_error
 6602*/
 6603int wolfSSL_want_write(WOLFSSL* ssl);
 6604
 6605/*!
 6606    \ingroup Setup
 6607
 6608    \brief wolfSSL by default checks the peer certificate for a valid date
 6609    range and a verified signature.  Calling this function before
 6610    wolfSSL_connect() or wolfSSL_accept() will add a domain name check to
 6611    the list of checks to perform.  dn holds the domain name to check
 6612    against the peer certificate when it’s received.
 6613
 6614    \return SSL_SUCCESS upon success.
 6615    \return SSL_FAILURE will be returned if a memory error was encountered.
 6616
 6617    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6618    \param dn domain name to check against the peer certificate when received.
 6619
 6620    _Example_
 6621    \code
 6622    int ret = 0;
 6623    WOLFSSL* ssl;
 6624    char* domain = (char*) “www.yassl.com”;
 6625    ...
 6626
 6627    ret = wolfSSL_check_domain_name(ssl, domain);
 6628    if (ret != SSL_SUCCESS) {
 6629       // failed to enable domain name check
 6630    }
 6631    \endcode
 6632
 6633    \sa none
 6634*/
 6635int wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn);
 6636
 6637/*!
 6638    \ingroup Setup
 6639
 6640    \brief Calling this function before wolfSSL_connect() or wolfSSL_accept()
 6641    adds an IP-address identity check against the peer certificate SAN
 6642    iPAddress entries.
 6643
 6644    \return SSL_SUCCESS upon success.
 6645    \return SSL_FAILURE if parameters are invalid or memory allocation fails.
 6646
 6647    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 6648    \param ipaddr NULL-terminated ASCII IP address string to verify against the
 6649    peer certificate.
 6650
 6651    _Example_
 6652    \code
 6653    int ret = 0;
 6654    WOLFSSL* ssl;
 6655    const char* ip = "127.0.0.1";
 6656    ...
 6657
 6658    ret = wolfSSL_check_ip_address(ssl, ip);
 6659    if (ret != SSL_SUCCESS) {
 6660       // failed to enable IP check
 6661    }
 6662    \endcode
 6663
 6664    \sa wolfSSL_check_domain_name
 6665*/
 6666int wolfSSL_check_ip_address(WOLFSSL* ssl, const char* ipaddr);
 6667
 6668/*!
 6669    \ingroup TLS
 6670
 6671    \brief Initializes the wolfSSL library for use.  Must be called once per
 6672    application and before any other call to the library.
 6673
 6674    \return SSL_SUCCESS If successful the call will return.
 6675    \return BAD_MUTEX_E is an error that may be returned.
 6676    \return WC_INIT_E wolfCrypt initialization error returned.
 6677
 6678    _Example_
 6679    \code
 6680    int ret = 0;
 6681    ret = wolfSSL_Init();
 6682    if (ret != SSL_SUCCESS) {
 6683	    failed to initialize wolfSSL library
 6684    }
 6685
 6686    \endcode
 6687
 6688    \sa wolfSSL_Cleanup
 6689*/
 6690int wolfSSL_Init(void);
 6691
 6692/*!
 6693    \ingroup TLS
 6694
 6695    \brief Un-initializes the wolfSSL library from further use. Doesn’t have
 6696    to be called, though it will free any resources used by the library.
 6697
 6698    \return SSL_SUCCESS return no errors.
 6699    \return BAD_MUTEX_E a mutex error return.]
 6700
 6701    _Example_
 6702    \code
 6703    wolfSSL_Cleanup();
 6704    \endcode
 6705
 6706    \sa wolfSSL_Init
 6707*/
 6708int wolfSSL_Cleanup(void);
 6709
 6710/*!
 6711    \ingroup IO
 6712
 6713    \brief This function returns the current library version.
 6714
 6715    \return LIBWOLFSSL_VERSION_STRING a const char pointer defining the
 6716    version.
 6717
 6718    \param none No parameters.
 6719
 6720    _Example_
 6721    \code
 6722    char version[MAXSIZE];
 6723    version = wolfSSL_KeepArrays();
 6724    …
 6725    if(version != ExpectedVersion){
 6726	    // Handle the mismatch case
 6727    }
 6728    \endcode
 6729
 6730    \sa word32_wolfSSL_lib_version_hex
 6731*/
 6732const char* wolfSSL_lib_version(void);
 6733
 6734/*!
 6735    \ingroup IO
 6736
 6737    \brief This function returns the current library version in hexadecimal
 6738    notation.
 6739
 6740    \return LILBWOLFSSL_VERSION_HEX returns the hexadecimal version defined in
 6741     wolfssl/version.h.
 6742
 6743    \param none No parameters.
 6744
 6745    _Example_
 6746    \code
 6747    word32 libV;
 6748    libV = wolfSSL_lib_version_hex();
 6749
 6750    if(libV != EXPECTED_HEX){
 6751	    // How to handle an unexpected value
 6752    } else {
 6753	    // The expected result for libV
 6754    }
 6755    \endcode
 6756
 6757    \sa wolfSSL_lib_version
 6758*/
 6759word32 wolfSSL_lib_version_hex(void);
 6760
 6761/*!
 6762    \ingroup IO
 6763
 6764    \brief Performs the actual connect or accept based on the side of the SSL
 6765    method.  If called from the client side then an wolfSSL_connect() is done
 6766    while a wolfSSL_accept() is performed if called from the server side.
 6767
 6768    \return SSL_SUCCESS will be returned if successful. (Note, older versions
 6769    will return 0.)
 6770    \return SSL_FATAL_ERROR will be returned if the underlying call resulted
 6771    in an error. Use wolfSSL_get_error() to get a specific error code.
 6772
 6773    \param ssl pointer to the SSL session, created with wolfSSL_new().
 6774
 6775    _Example_
 6776    \code
 6777    int ret = SSL_FATAL_ERROR;
 6778    WOLFSSL* ssl = 0;
 6779    ...
 6780    ret = wolfSSL_negotiate(ssl);
 6781    if (ret == SSL_FATAL_ERROR) {
 6782    	// SSL establishment failed
 6783	int error_code = wolfSSL_get_error(ssl);
 6784	...
 6785    }
 6786    ...
 6787    \endcode
 6788
 6789    \sa SSL_connect
 6790    \sa SSL_accept
 6791*/
 6792int wolfSSL_negotiate(WOLFSSL* ssl);
 6793
 6794/*!
 6795    \ingroup Setup
 6796
 6797    \brief Turns on the ability to use compression for the SSL connection.
 6798    Both sides must have compression turned on otherwise compression will not be
 6799    used. The zlib library performs the actual data compression. To compile
 6800    into the library use --with-libz for the configure system and define
 6801    HAVE_LIBZ otherwise. Keep in mind that while compressing data before
 6802    sending decreases the actual size of the messages being sent and received,
 6803    the amount of data saved by compression usually takes longer in time to
 6804    analyze than it does to send it raw on all but the slowest of networks.
 6805
 6806    \return SSL_SUCCESS upon success.
 6807    \return NOT_COMPILED_IN will be returned if compression support wasn’t
 6808    built into the library.
 6809
 6810    \param ssl pointer to the SSL session, created with wolfSSL_new().
 6811
 6812    _Example_
 6813    \code
 6814    int ret = 0;
 6815    WOLFSSL* ssl = 0;
 6816    ...
 6817    ret = wolfSSL_set_compression(ssl);
 6818    if (ret == SSL_SUCCESS) {
 6819    	// successfully enabled compression for SSL session
 6820    }
 6821    \endcode
 6822
 6823    \sa none
 6824*/
 6825int wolfSSL_set_compression(WOLFSSL* ssl);
 6826
 6827/*!
 6828    \ingroup Setup
 6829
 6830    \brief This function sets the SSL session timeout value in seconds.
 6831
 6832    \return SSL_SUCCESS will be returned upon successfully setting the session.
 6833    \return BAD_FUNC_ARG will be returned if ssl is NULL.
 6834
 6835    \param ssl pointer to the SSL object, created with wolfSSL_new().
 6836    \param to value, in seconds, used to set the SSL session timeout.
 6837
 6838    _Example_
 6839    \code
 6840    int ret = 0;
 6841    WOLFSSL* ssl = 0;
 6842    ...
 6843
 6844    ret = wolfSSL_set_timeout(ssl, 500);
 6845    if (ret != SSL_SUCCESS) {
 6846    	// failed to set session timeout value
 6847    }
 6848    ...
 6849    \endcode
 6850
 6851    \sa wolfSSL_get1_session
 6852    \sa wolfSSL_set_session
 6853*/
 6854int wolfSSL_set_timeout(WOLFSSL* ssl, unsigned int to);
 6855
 6856/*!
 6857    \ingroup Setup
 6858
 6859    \brief This function sets the timeout value for SSL sessions, in seconds,
 6860    for the specified SSL context.
 6861
 6862    \return the previous timeout value, if WOLFSSL_ERROR_CODE_OPENSSL is
 6863    \return defined on success. If not defined, SSL_SUCCESS will be returned.
 6864    \return BAD_FUNC_ARG will be returned when the input context (ctx) is null.
 6865
 6866    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 6867    \param to session timeout value in seconds.
 6868
 6869    _Example_
 6870    \code
 6871    WOLFSSL_CTX*    ctx    = 0;
 6872    ...
 6873    ret = wolfSSL_CTX_set_timeout(ctx, 500);
 6874    if (ret != SSL_SUCCESS) {
 6875	    // failed to set session timeout value
 6876    }
 6877    \endcode
 6878
 6879    \sa wolfSSL_flush_sessions
 6880    \sa wolfSSL_get1_session
 6881    \sa wolfSSL_set_session
 6882    \sa wolfSSL_get_sessionID
 6883    \sa wolfSSL_CTX_set_session_cache_mode
 6884*/
 6885int wolfSSL_CTX_set_timeout(WOLFSSL_CTX* ctx, unsigned int to);
 6886
 6887/*!
 6888    \ingroup openSSL
 6889
 6890    \brief Retrieves the peer’s certificate chain.
 6891
 6892    \return chain If successful the call will return the peer’s
 6893    certificate chain.
 6894    \return 0 will be returned if an invalid WOLFSSL pointer is passed to the
 6895    function.
 6896
 6897    \param ssl pointer to a valid WOLFSSL structure.
 6898
 6899    _Example_
 6900    \code
 6901    none
 6902    \endcode
 6903
 6904    \sa wolfSSL_get_chain_count
 6905    \sa wolfSSL_get_chain_length
 6906    \sa wolfSSL_get_chain_cert
 6907    \sa wolfSSL_get_chain_cert_pem
 6908*/
 6909WOLFSSL_X509_CHAIN* wolfSSL_get_peer_chain(WOLFSSL* ssl);
 6910
 6911/*!
 6912    \ingroup openSSL
 6913
 6914    \brief Retrieve's the peers certificate chain count.
 6915
 6916    \return Success If successful the call will return the peer’s certificate
 6917    chain count.
 6918    \return 0 will be returned if an invalid chain pointer is passed to
 6919    the function.
 6920
 6921    \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
 6922
 6923    _Example_
 6924    \code
 6925    none
 6926    \endcode
 6927
 6928    \sa wolfSSL_get_peer_chain
 6929    \sa wolfSSL_get_chain_length
 6930    \sa wolfSSL_get_chain_cert
 6931    \sa wolfSSL_get_chain_cert_pem
 6932*/
 6933int  wolfSSL_get_chain_count(WOLFSSL_X509_CHAIN* chain);
 6934
 6935/*!
 6936    \ingroup openSSL
 6937
 6938    \brief Retrieves the peer’s ASN1.DER certificate length in bytes
 6939    at index (idx).
 6940
 6941    \return Success If successful the call will return the peer’s
 6942    certificate length in bytes by index.
 6943    \return 0 will be returned if an invalid chain pointer is passed
 6944    to the function.
 6945
 6946    \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
 6947    \param idx index to start of chain.
 6948
 6949    _Example_
 6950    \code
 6951    none
 6952    \endcode
 6953
 6954    \sa wolfSSL_get_peer_chain
 6955    \sa wolfSSL_get_chain_count
 6956    \sa wolfSSL_get_chain_cert
 6957    \sa wolfSSL_get_chain_cert_pem
 6958*/
 6959int  wolfSSL_get_chain_length(WOLFSSL_X509_CHAIN* chain, int idx);
 6960
 6961/*!
 6962    \ingroup openSSL
 6963
 6964    \brief Retrieves the peer’s ASN1.DER certificate at index (idx).
 6965
 6966    \return Success If successful the call will return the peer’s
 6967    certificate by index.
 6968    \return 0 will be returned if an invalid chain pointer is passed
 6969    to the function.
 6970
 6971    \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
 6972    \param idx index to start of chain.
 6973
 6974    _Example_
 6975    \code
 6976    none
 6977    \endcode
 6978
 6979    \sa wolfSSL_get_peer_chain
 6980    \sa wolfSSL_get_chain_count
 6981    \sa wolfSSL_get_chain_length
 6982    \sa wolfSSL_get_chain_cert_pem
 6983*/
 6984unsigned char* wolfSSL_get_chain_cert(WOLFSSL_X509_CHAIN* chain, int idx);
 6985
 6986/*!
 6987    \ingroup CertsKeys
 6988
 6989    \brief This function gets the peer’s wolfSSL_X509_certificate at
 6990    index (idx) from the chain of certificates.
 6991
 6992    \return pointer returns a pointer to a WOLFSSL_X509 structure.
 6993
 6994    \param chain a pointer to the WOLFSSL_X509_CHAIN used for no dynamic
 6995    memory SESSION_CACHE.
 6996    \param idx the index of the WOLFSSL_X509 certificate.
 6997
 6998    Note that it is the user's responsibility to free the returned memory
 6999    by calling wolfSSL_FreeX509().
 7000
 7001    _Example_
 7002    \code
 7003    WOLFSSL_X509_CHAIN* chain = &session->chain;
 7004    int idx = 999; // set idx
 7005    ...
 7006    WOLFSSL_X509_CHAIN ptr;
 7007    prt = wolfSSL_get_chain_X509(chain, idx);
 7008
 7009    if(ptr != NULL){
 7010        // ptr contains the cert at the index specified
 7011        wolfSSL_FreeX509(ptr);
 7012    } else {
 7013        // ptr is NULL
 7014    }
 7015    \endcode
 7016
 7017    \sa InitDecodedCert
 7018    \sa ParseCertRelative
 7019    \sa CopyDecodedToX509
 7020*/
 7021WOLFSSL_X509* wolfSSL_get_chain_X509(WOLFSSL_X509_CHAIN* chain, int idx);
 7022
 7023/*!
 7024    \ingroup openSSL
 7025
 7026    \brief Retrieves the peer’s PEM certificate at index (idx).
 7027
 7028    \return Success If successful the call will return the peer’s
 7029    certificate by index.
 7030    \return 0 will be returned if an invalid chain pointer is passed to
 7031    the function.
 7032
 7033    \param chain pointer to a valid WOLFSSL_X509_CHAIN structure.
 7034    \param idx indexto start of chain.
 7035
 7036    _Example_
 7037    \code
 7038    none
 7039    \endcode
 7040
 7041    \sa wolfSSL_get_peer_chain
 7042    \sa wolfSSL_get_chain_count
 7043    \sa wolfSSL_get_chain_length
 7044    \sa wolfSSL_get_chain_cert
 7045*/
 7046int  wolfSSL_get_chain_cert_pem(WOLFSSL_X509_CHAIN* chain, int idx,
 7047                                unsigned char* buf, int inLen, int* outLen);
 7048
 7049/*!
 7050    \ingroup openSSL
 7051
 7052    \brief Retrieves the session’s ID.  The session ID is always 32 bytes long.
 7053
 7054    \return id The session ID.
 7055
 7056    \param session pointer to a valid wolfssl session.
 7057
 7058    _Example_
 7059    \code
 7060    none
 7061    \endcode
 7062
 7063    \sa SSL_get_session
 7064*/
 7065const unsigned char* wolfSSL_get_sessionID(const WOLFSSL_SESSION* s);
 7066
 7067/*!
 7068    \ingroup openSSL
 7069
 7070    \brief Retrieves the peer’s certificate serial number. The serial
 7071    number buffer (in) should be at least 32 bytes long and be provided
 7072    as the *inOutSz argument as input. After calling the function *inOutSz
 7073    will hold the actual length in bytes written to the in buffer.
 7074
 7075    \return SSL_SUCCESS upon success.
 7076    \return BAD_FUNC_ARG will be returned if a bad function argument
 7077    was encountered.
 7078
 7079    \param in The serial number buffer and should be at least 32 bytes long
 7080    \param inOutSz will hold the actual length in bytes written to the
 7081    in buffer.
 7082
 7083    _Example_
 7084    \code
 7085    none
 7086    \endcode
 7087
 7088    \sa SSL_get_peer_certificate
 7089*/
 7090int  wolfSSL_X509_get_serial_number(WOLFSSL_X509* x509, unsigned char* in,
 7091                                    int* inOutSz);
 7092
 7093/*!
 7094    \ingroup CertsKeys
 7095
 7096    \brief Returns the common name of the subject from the certificate.
 7097
 7098    \return NULL returned if the x509 structure is null
 7099    \return string a string representation of the subject's common
 7100    name is returned upon success
 7101
 7102    \param x509 a pointer to a WOLFSSL_X509 structure containing
 7103    certificate information.
 7104
 7105    _Example_
 7106    \code
 7107    WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
 7108							DYNAMIC_TYPE_X509);
 7109    ...
 7110    int x509Cn = wolfSSL_X509_get_subjectCN(x509);
 7111    if(x509Cn == NULL){
 7112	    // Deal with NULL case
 7113    } else {
 7114	    // x509Cn contains the common name
 7115    }
 7116    \endcode
 7117
 7118    \sa wolfSSL_X509_Name_get_entry
 7119    \sa wolfSSL_X509_get_next_altname
 7120    \sa wolfSSL_X509_get_issuer_name
 7121    \sa wolfSSL_X509_get_subject_name
 7122
 7123*/
 7124char*  wolfSSL_X509_get_subjectCN(WOLFSSL_X509*);
 7125
 7126/*!
 7127    \ingroup CertsKeys
 7128
 7129    \brief This function gets the DER encoded certificate in the
 7130    WOLFSSL_X509 struct.
 7131
 7132    \return buffer This function returns the DerBuffer structure’s
 7133    buffer member, which is of type byte.
 7134    \return NULL returned if the x509 or outSz parameter is NULL.
 7135
 7136    \param x509 a pointer to a WOLFSSL_X509 structure containing
 7137    certificate information.
 7138    \param outSz length of the derBuffer member of the WOLFSSL_X509 struct.
 7139
 7140    _Example_
 7141    \code
 7142    WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
 7143							DYNAMIC_TYPE_X509);
 7144    int* outSz; // initialize
 7145    ...
 7146    byte* x509Der = wolfSSL_X509_get_der(x509, outSz);
 7147    if(x509Der == NULL){
 7148	    // Failure case one of the parameters was NULL
 7149    }
 7150    \endcode
 7151
 7152    \sa wolfSSL_X509_version
 7153    \sa wolfSSL_X509_Name_get_entry
 7154    \sa wolfSSL_X509_get_next_altname
 7155    \sa wolfSSL_X509_get_issuer_name
 7156    \sa wolfSSL_X509_get_subject_name
 7157*/
 7158const unsigned char* wolfSSL_X509_get_der(WOLFSSL_X509* x509, int* outSz);
 7159
 7160/*!
 7161    \ingroup CertsKeys
 7162
 7163    \brief This function checks to see if x509 is NULL and if it’s not,
 7164    it returns the notAfter member of the x509 struct.
 7165
 7166    \return pointer to struct with ASN1_TIME to the notAfter
 7167    member of the x509 struct.
 7168    \return NULL returned if the x509 object is NULL.
 7169
 7170    \param x509 a pointer to the WOLFSSL_X509 struct.
 7171
 7172    _Example_
 7173    \code
 7174    WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
 7175    DYNAMIC_TYPE_X509) ;
 7176    ...
 7177    const WOLFSSL_ASN1_TIME* notAfter = wolfSSL_X509_get_notAfter(x509);
 7178    if(notAfter == NULL){
 7179        // Failure case, the x509 object is null.
 7180    }
 7181    \endcode
 7182
 7183    \sa wolfSSL_X509_get_notBefore
 7184*/
 7185WOLFSSL_ASN1_TIME* wolfSSL_X509_get_notAfter(WOLFSSL_X509*);
 7186
 7187/*!
 7188    \ingroup CertsKeys
 7189
 7190    \brief This function retrieves the version of the X509 certificate.
 7191
 7192    \return 0 returned if the x509 structure is NULL.
 7193    \return version the version stored in the x509 structure will be returned.
 7194
 7195    \param x509 a pointer to a WOLFSSL_X509 structure.
 7196
 7197    _Example_
 7198    \code
 7199    WOLFSSL_X509* x509;
 7200    int version;
 7201    ...
 7202    version = wolfSSL_X509_version(x509);
 7203    if(!version){
 7204	    // The function returned 0, failure case.
 7205    }
 7206    \endcode
 7207
 7208    \sa wolfSSL_X509_get_subject_name
 7209    \sa wolfSSL_X509_get_issuer_name
 7210    \sa wolfSSL_X509_get_isCA
 7211    \sa wolfSSL_get_peer_certificate
 7212*/
 7213int wolfSSL_X509_version(WOLFSSL_X509* x509);
 7214
 7215/*!
 7216    \ingroup CertsKeys
 7217
 7218    \brief If NO_STDIO_FILESYSTEM is defined this function will allocate
 7219    heap memory, initialize a WOLFSSL_X509 structure and return a pointer to it.
 7220
 7221    \return *WOLFSSL_X509 WOLFSSL_X509 structure pointer is returned if
 7222    the function executes successfully.
 7223    \return NULL if the call to XFTELL macro returns a negative value.
 7224
 7225    \param x509 a pointer to a WOLFSSL_X509 pointer.
 7226    \param file a defined type that is a pointer to a FILE.
 7227
 7228    _Example_
 7229    \code
 7230    WOLFSSL_X509* x509a = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
 7231    DYNAMIC_TYPE_X509);
 7232    WOLFSSL_X509** x509 = x509a;
 7233    XFILE file;  (mapped to struct fs_file*)
 7234    ...
 7235    WOLFSSL_X509* newX509 = wolfSSL_X509_d2i_fp(x509, file);
 7236    if(newX509 == NULL){
 7237	    // The function returned NULL
 7238    }
 7239    \endcode
 7240
 7241    \sa wolfSSL_X509_d2i
 7242    \sa XFTELL
 7243    \sa XREWIND
 7244    \sa XFSEEK
 7245*/
 7246WOLFSSL_X509*
 7247        wolfSSL_X509_d2i_fp(WOLFSSL_X509** x509, FILE* file);
 7248
 7249/*!
 7250    \ingroup CertsKeys
 7251
 7252    \brief The function loads the x509 certificate into memory.
 7253
 7254    \return pointer a successful execution returns pointer to a
 7255    WOLFSSL_X509 structure.
 7256    \return NULL returned if the certificate was not able to be written.
 7257
 7258    \param fname the certificate file to be loaded.
 7259    \param format the format of the certificate.
 7260
 7261    _Example_
 7262    \code
 7263    #define cliCert    “certs/client-cert.pem”
 7264    …
 7265    X509* x509;
 7266    …
 7267    x509 = wolfSSL_X509_load_certificate_file(cliCert, SSL_FILETYPE_PEM);
 7268    AssertNotNull(x509);
 7269    \endcode
 7270
 7271    \sa InitDecodedCert
 7272    \sa PemToDer
 7273    \sa wolfSSL_get_certificate
 7274    \sa AssertNotNull
 7275*/
 7276WOLFSSL_X509*
 7277    wolfSSL_X509_load_certificate_file(const char* fname, int format);
 7278
 7279/*!
 7280    \ingroup CertsKeys
 7281
 7282    \brief This function copies the device type from the x509 structure
 7283    to the buffer.
 7284
 7285    \return pointer returns a byte pointer holding the device type from
 7286    the x509 structure.
 7287    \return NULL returned if the buffer size is NULL.
 7288
 7289    \param x509 pointer to a WOLFSSL_X509 structure, created with
 7290    WOLFSSL_X509_new().
 7291    \param in a pointer to a byte type that will hold the device type
 7292    (the buffer).
 7293    \param inOutSz the minimum of either the parameter inOutSz or the
 7294    deviceTypeSz member of the x509 structure.
 7295
 7296    _Example_
 7297    \code
 7298    WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL,
 7299    DYNAMIC_TYPE_X509);
 7300    byte* in;
 7301    int* inOutSz;
 7302    ...
 7303    byte* deviceType = wolfSSL_X509_get_device_type(x509, in, inOutSz);
 7304
 7305    if(!deviceType){
 7306	    // Failure case, NULL was returned.
 7307    }
 7308    \endcode
 7309
 7310    \sa wolfSSL_X509_get_hw_type
 7311    \sa wolfSSL_X509_get_hw_serial_number
 7312    \sa wolfSSL_X509_d2i
 7313*/
 7314unsigned char*
 7315           wolfSSL_X509_get_device_type(WOLFSSL_X509* x509, unsigned char* in,
 7316                                        int* inOutSz);
 7317
 7318/*!
 7319    \ingroup CertsKeys
 7320
 7321    \brief The function copies the hwType member of the WOLFSSL_X509
 7322    structure to the buffer.
 7323
 7324    \return byte The function returns a byte type of the data previously held
 7325    in the hwType member of the WOLFSSL_X509 structure.
 7326    \return NULL returned if  inOutSz is NULL.
 7327
 7328    \param x509 a pointer to a WOLFSSL_X509 structure containing certificate
 7329    information.
 7330    \param in pointer to type byte that represents the buffer.
 7331    \param inOutSz pointer to type int that represents the size of the buffer.
 7332
 7333    _Example_
 7334    \code
 7335    WOLFSSL_X509* x509;  // X509 certificate
 7336    byte* in;  // initialize the buffer
 7337    int* inOutSz;  // holds the size of the buffer
 7338    ...
 7339    byte* hwType = wolfSSL_X509_get_hw_type(x509, in, inOutSz);
 7340
 7341    if(hwType == NULL){
 7342	    // Failure case function returned NULL.
 7343    }
 7344    \endcode
 7345
 7346    \sa wolfSSL_X509_get_hw_serial_number
 7347    \sa wolfSSL_X509_get_device_type
 7348*/
 7349unsigned char*
 7350           wolfSSL_X509_get_hw_type(WOLFSSL_X509* x509, unsigned char* in,
 7351                                    int* inOutSz);
 7352
 7353/*!
 7354    \ingroup CertsKeys
 7355
 7356    \brief This function returns the hwSerialNum member of the x509 object.
 7357
 7358    \return pointer the function returns a byte pointer to the in buffer that
 7359    will contain the serial number loaded from the x509 object.
 7360
 7361    \param x509 pointer to a WOLFSSL_X509 structure containing certificate
 7362    information.
 7363    \param in a pointer to the buffer that will be copied to.
 7364    \param inOutSz a pointer to the size of the buffer.
 7365
 7366    _Example_
 7367    \code
 7368    char* serial;
 7369    byte* in;
 7370    int* inOutSz;
 7371    WOLFSSL_X509 x509;
 7372    ...
 7373    serial = wolfSSL_X509_get_hw_serial_number(x509, in, inOutSz);
 7374
 7375    if(serial == NULL || serial <= 0){
 7376    	// Failure case
 7377    }
 7378    \endcode
 7379
 7380    \sa wolfSSL_X509_get_subject_name
 7381    \sa wolfSSL_X509_get_issuer_name
 7382    \sa wolfSSL_X509_get_isCA
 7383    \sa wolfSSL_get_peer_certificate
 7384    \sa wolfSSL_X509_version
 7385*/
 7386unsigned char*
 7387           wolfSSL_X509_get_hw_serial_number(WOLFSSL_X509* x509,
 7388                                             unsigned char* in, int* inOutSz);
 7389
 7390/*!
 7391    \ingroup IO
 7392
 7393    \brief This function is called on the client side and initiates an
 7394    SSL/TLS handshake with a server only long enough to get the peer’s
 7395    certificate chain.  When this function is called, the underlying
 7396    communication channel has already been set up. wolfSSL_connect_cert()
 7397    works with both blocking and non-blocking I/O.  When the underlying I/O
 7398    is non-blocking, wolfSSL_connect_cert() will return when the underlying
 7399    I/O could not satisfy the needs of wolfSSL_connect_cert() to continue the
 7400    handshake.  In this case, a call to wolfSSL_get_error() will yield either
 7401    SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process must then
 7402    repeat the call to wolfSSL_connect_cert() when the underlying I/O is ready
 7403    and wolfSSL will pick up where it left off. When using a non-blocking
 7404    socket, nothing needs to be done, but select() can be used to check for
 7405    the required condition. If the underlying I/O is blocking,
 7406    wolfSSL_connect_cert() will only return once the peer’s certificate chain
 7407    has been received.
 7408
 7409    \return SSL_SUCCESS upon success.
 7410    \return SSL_FAILURE will be returned if the SSL session parameter is NULL.
 7411    \return SSL_FATAL_ERROR will be returned if an error occurred. To get a more
 7412    detailed error code, call wolfSSL_get_error().
 7413
 7414    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 7415
 7416    _Example_
 7417    \code
 7418    int ret = 0;
 7419    int err = 0;
 7420    WOLFSSL* ssl;
 7421    char buffer[80];
 7422    ...
 7423    ret = wolfSSL_connect_cert(ssl);
 7424    if (ret != SSL_SUCCESS) {
 7425        err = wolfSSL_get_error(ssl, ret);
 7426        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
 7427    }
 7428    \endcode
 7429
 7430    \sa wolfSSL_get_error
 7431    \sa wolfSSL_connect
 7432    \sa wolfSSL_accept
 7433*/
 7434int  wolfSSL_connect_cert(WOLFSSL* ssl);
 7435
 7436/*!
 7437    \ingroup openSSL
 7438
 7439    \brief wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12
 7440    information from WOLFSSL_BIO to the structure WC_PKCS12. The information
 7441    is divided up in the structure as a list of Content Infos along with a
 7442    structure to hold optional MAC information. After the information has been
 7443    divided into chunks (but not decrypted) in the structure WC_PKCS12, it can
 7444    then be parsed and decrypted by calling.
 7445
 7446    \return WC_PKCS12 pointer to a WC_PKCS12 structure.
 7447    \return Failure If function failed it will return NULL.
 7448
 7449    \param bio WOLFSSL_BIO structure to read PKCS12 buffer from.
 7450    \param pkcs12 WC_PKCS12 structure pointer for new PKCS12 structure created.
 7451    Can be NULL
 7452
 7453    _Example_
 7454    \code
 7455    WC_PKCS12* pkcs;
 7456    WOLFSSL_BIO* bio;
 7457    WOLFSSL_X509* cert;
 7458    WOLFSSL_EVP_PKEY* pkey;
 7459    STACK_OF(X509) certs;
 7460    //bio loads in PKCS12 file
 7461    wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
 7462    wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
 7463    wc_PKCS12_free(pkcs)
 7464    //use cert, pkey, and optionally certs stack
 7465    \endcode
 7466
 7467    \sa wolfSSL_PKCS12_parse
 7468    \sa wc_PKCS12_free
 7469*/
 7470WC_PKCS12* wolfSSL_d2i_PKCS12_bio(WOLFSSL_BIO* bio,
 7471                                       WC_PKCS12** pkcs12);
 7472
 7473/*!
 7474    \ingroup openSSL
 7475
 7476    \brief wolfSSL_i2d_PKCS12_bio (i2d_PKCS12_bio) copies in the cert
 7477    information from the structure WC_PKCS12 to WOLFSSL_BIO.
 7478
 7479    \return 1 for success.
 7480    \return Failure 0.
 7481
 7482    \param bio WOLFSSL_BIO structure to write PKCS12 buffer to.
 7483    \param pkcs12 WC_PKCS12 structure for PKCS12 structure as input.
 7484
 7485    _Example_
 7486    \code
 7487    WC_PKCS12 pkcs12;
 7488    FILE *f;
 7489    byte buffer[5300];
 7490    char file[] = "./test.p12";
 7491    int bytes;
 7492    WOLFSSL_BIO* bio;
 7493    pkcs12 = wc_PKCS12_new();
 7494    f = fopen(file, "rb");
 7495    bytes = (int)fread(buffer, 1, sizeof(buffer), f);
 7496    fclose(f);
 7497    //convert the DER file into an internal structure
 7498    wc_d2i_PKCS12(buffer, bytes, pkcs12);
 7499    bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
 7500    //convert PKCS12 structure into bio
 7501    wolfSSL_i2d_PKCS12_bio(bio, pkcs12);
 7502    wc_PKCS12_free(pkcs)
 7503    //use bio
 7504    \endcode
 7505
 7506    \sa wolfSSL_PKCS12_parse
 7507    \sa wc_PKCS12_free
 7508*/
 7509WC_PKCS12* wolfSSL_i2d_PKCS12_bio(WOLFSSL_BIO* bio,
 7510                                       WC_PKCS12* pkcs12);
 7511
 7512/*!
 7513    \ingroup openSSL
 7514
 7515    \brief PKCS12 can be enabled with adding –enable-opensslextra to the
 7516    configure command. It can use triple DES and RC4 for decryption so would
 7517    recommend also enabling these features when enabling opensslextra
 7518    (--enable-des3 –enable-arc4). wolfSSL does not currently support RC2 so
 7519    decryption with RC2 is currently not available. This may be noticeable
 7520    with default encryption schemes used by OpenSSL command line to create
 7521    .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this
 7522    function does is check the MAC is correct if present. If the MAC fails
 7523    then the function returns and does not try to decrypt any of the stored
 7524    Content Infos. This function then parses through each Content Info
 7525    looking for a bag type, if the bag type is known it is decrypted as
 7526    needed and either stored in the list of certificates being built or as
 7527    a key found. After parsing through all bags the key found is then
 7528    compared with the certificate list until a matching pair is found.
 7529    This matching pair is then returned as the key and certificate,
 7530    optionally the certificate list found is returned as a STACK_OF
 7531    certificates. At the moment a CRL, Secret or SafeContents bag will be
 7532    skipped over and not parsed. It can be seen if these or other “Unknown”
 7533    bags are skipped over by viewing the debug print out. Additional attributes
 7534    such as friendly name are skipped over when parsing a PKCS12 file.
 7535
 7536    \return SSL_SUCCESS On successfully parsing PKCS12.
 7537    \return SSL_FAILURE If an error case was encountered.
 7538
 7539    \param pkcs12 WC_PKCS12 structure to parse.
 7540    \param paswd password for decrypting PKCS12.
 7541    \param pkey structure to hold private key decoded from PKCS12.
 7542    \param cert structure to hold certificate decoded from PKCS12.
 7543    \param stack optional stack of extra certificates.
 7544
 7545    _Example_
 7546    \code
 7547    WC_PKCS12* pkcs;
 7548    WOLFSSL_BIO* bio;
 7549    WOLFSSL_X509* cert;
 7550    WOLFSSL_EVP_PKEY* pkey;
 7551    STACK_OF(X509) certs;
 7552    //bio loads in PKCS12 file
 7553    wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
 7554    wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
 7555    wc_PKCS12_free(pkcs)
 7556    //use cert, pkey, and optionally certs stack
 7557    \endcode
 7558
 7559    \sa wolfSSL_d2i_PKCS12_bio
 7560    \sa wc_PKCS12_free
 7561*/
 7562int wolfSSL_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw,
 7563     WOLFSSL_EVP_PKEY** pkey, WOLFSSL_X509** cert, WOLF_STACK_OF(WOLFSSL_X509)** ca);
 7564
 7565/*!
 7566    \ingroup CertsKeys
 7567
 7568    \brief Server Diffie-Hellman Ephemeral parameters setting. This function
 7569    sets up the group parameters to be used if the server negotiates a cipher
 7570    suite that uses DHE.
 7571
 7572    \return SSL_SUCCESS upon success.
 7573    \return MEMORY_ERROR will be returned if a memory error was encountered.
 7574    \return SIDE_ERROR will be returned if this function is called on an SSL
 7575    client instead of an SSL server.
 7576
 7577    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 7578    \param p Diffie-Hellman prime number parameter.
 7579    \param pSz size of p.
 7580    \param g Diffie-Hellman “generator” parameter.
 7581    \param gSz size of g.
 7582
 7583    _Example_
 7584    \code
 7585    WOLFSSL* ssl;
 7586    static unsigned char p[] = {...};
 7587    static unsigned char g[] = {...};
 7588    ...
 7589    wolfSSL_SetTmpDH(ssl, p, sizeof(p), g, sizeof(g));
 7590    \endcode
 7591
 7592    \sa SSL_accept
 7593*/
 7594int  wolfSSL_SetTmpDH(WOLFSSL* ssl, const unsigned char* p, int pSz,
 7595                                const unsigned char* g, int gSz);
 7596
 7597/*!
 7598    \ingroup CertsKeys
 7599
 7600    \brief The function calls the wolfSSL_SetTMpDH_buffer_wrapper,
 7601    which is a wrapper for Diffie-Hellman parameters.
 7602
 7603    \return SSL_SUCCESS on successful execution.
 7604    \return SSL_BAD_FILETYPE if the file type is not PEM and is not
 7605    ASN.1. It will also be returned if the wc_DhParamsLoad does not
 7606    return normally.
 7607    \return SSL_NO_PEM_HEADER returns from PemToDer if there is not
 7608    a PEM header.
 7609    \return SSL_BAD_FILE returned if there is a file error in PemToDer.
 7610    \return SSL_FATAL_ERROR returned from PemToDer if there was a copy error.
 7611    \return MEMORY_E - if there was a memory allocation error.
 7612    \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if
 7613    there was otherwise a NULL argument passed to a subroutine.
 7614    \return DH_KEY_SIZE_E is returned if their is a key size error in
 7615    wolfSSL_SetTmpDH() or in wolfSSL_CTX_SetTmpDH().
 7616    \return SIDE_ERROR returned if it is not the server side
 7617    in wolfSSL_SetTmpDH.
 7618
 7619    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 7620    \param buf allocated buffer passed in from wolfSSL_SetTMpDH_file_wrapper.
 7621    \param sz a long int that holds the size of the file
 7622    (fname within wolfSSL_SetTmpDH_file_wrapper).
 7623    \param format an integer type passed through from
 7624    wolfSSL_SetTmpDH_file_wrapper() that is a representation of the certificate
 7625    format.
 7626
 7627    _Example_
 7628    \code
 7629    Static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,
 7630    Const char* fname, int format);
 7631    long sz = 0;
 7632    byte* myBuffer = staticBuffer[FILE_BUFFER_SIZE];
 7633    …
 7634    if(ssl)
 7635    ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);
 7636    \endcode
 7637
 7638    \sa wolfSSL_SetTmpDH_buffer_wrapper
 7639    \sa wc_DhParamsLoad
 7640    \sa wolfSSL_SetTmpDH
 7641    \sa PemToDer
 7642    \sa wolfSSL_CTX_SetTmpDH
 7643    \sa wolfSSL_CTX_SetTmpDH_file
 7644*/
 7645int  wolfSSL_SetTmpDH_buffer(WOLFSSL* ssl, const unsigned char* b, long sz,
 7646                                       int format);
 7647
 7648/*!
 7649    \ingroup CertsKeys
 7650
 7651    \brief This function calls wolfSSL_SetTmpDH_file_wrapper to set server
 7652    Diffie-Hellman parameters.
 7653
 7654    \return SSL_SUCCESS returned on successful completion of this function
 7655    and its subroutines.
 7656    \return MEMORY_E returned if a memory allocation failed in this function
 7657    or a subroutine.
 7658    \return SIDE_ERROR if the side member of the Options structure found
 7659    in the WOLFSSL struct is not the server side.
 7660    \return SSL_BAD_FILETYPE returns if the certificate fails a set of checks.
 7661    \return DH_KEY_SIZE_E returned if the DH parameter's key size is less than
 7662    the value of the minDhKeySz member in the WOLFSSL struct.
 7663    \return DH_KEY_SIZE_E returned if the DH parameter's key size is greater
 7664    than the value of the maxDhKeySz member in the WOLFSSL struct.
 7665    \return BAD_FUNC_ARG returns if an argument value is NULL that is not
 7666    permitted such as, the WOLFSSL structure.
 7667
 7668    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 7669    \param fname a constant char pointer holding the certificate.
 7670    \param format an integer type that holds the format of the certification.
 7671
 7672    _Example_
 7673    \code
 7674    WOLFSSL* ssl = wolfSSL_new(ctx);
 7675    const char* dhParam;
 7676    …
 7677    AssertIntNE(SSL_SUCCESS,
 7678    wolfSSL_SetTmpDH_file(ssl, dhParam, SSL_FILETYPE_PEM));
 7679    \endcode
 7680
 7681    \sa wolfSSL_CTX_SetTmpDH_file
 7682    \sa wolfSSL_SetTmpDH_file_wrapper
 7683    \sa wolfSSL_SetTmpDH_buffer
 7684    \sa wolfSSL_CTX_SetTmpDH_buffer
 7685    \sa wolfSSL_SetTmpDH_buffer_wrapper
 7686    \sa wolfSSL_SetTmpDH
 7687    \sa wolfSSL_CTX_SetTmpDH
 7688*/
 7689int  wolfSSL_SetTmpDH_file(WOLFSSL* ssl, const char* f, int format);
 7690
 7691/*!
 7692    \ingroup CertsKeys
 7693
 7694    \brief Sets the parameters for the server CTX Diffie-Hellman.
 7695
 7696    \return SSL_SUCCESS returned if the function and all subroutines
 7697    return without error.
 7698    \return BAD_FUNC_ARG returned if the CTX, p or g parameters are NULL.
 7699    \return DH_KEY_SIZE_E returned if the DH parameter's key size is less than
 7700    the value of the minDhKeySz member of the WOLFSSL_CTX struct.
 7701    \return DH_KEY_SIZE_E returned if the DH parameter's key size is greater
 7702    than the value of the maxDhKeySz member of the WOLFSSL_CTX struct.
 7703    \return MEMORY_E returned if the allocation of memory failed in this
 7704    function or a subroutine.
 7705
 7706    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 7707    wolfSSL_CTX_new().
 7708    \param p a constant unsigned char pointer loaded into the buffer
 7709    member of the serverDH_P struct.
 7710    \param pSz an int type representing the size of p, initialized
 7711    to MAX_DH_SIZE.
 7712    \param g a constant unsigned char pointer loaded into the buffer
 7713    member of the serverDH_G struct.
 7714    \param gSz an int type representing the size of g, initialized to
 7715    MAX_DH_SIZE.
 7716
 7717    _Exmaple_
 7718    \code
 7719    WOLFSSL_CTX* ctx =  WOLFSSL_CTX_new( protocol );
 7720    byte* p;
 7721    byte* g;
 7722    word32 pSz = (word32)sizeof(p)/sizeof(byte);
 7723    word32 gSz = (word32)sizeof(g)/sizeof(byte);
 7724    …
 7725    int ret =  wolfSSL_CTX_SetTmpDH(ctx, p, pSz, g, gSz);
 7726
 7727    if(ret != SSL_SUCCESS){
 7728    	// Failure case
 7729    }
 7730    \endcode
 7731
 7732    \sa wolfSSL_SetTmpDH
 7733    \sa wc_DhParamsLoad
 7734*/
 7735int  wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX* ctx, const unsigned char* p,
 7736                                    int pSz, const unsigned char* g, int gSz);
 7737
 7738/*!
 7739    \ingroup CertsKeys
 7740
 7741    \brief A wrapper function that calls wolfSSL_SetTmpDH_buffer_wrapper
 7742
 7743    \return 0 returned for a successful execution.
 7744    \return BAD_FUNC_ARG returned if the ctx or buf parameters are NULL.
 7745    \return MEMORY_E if there is a memory allocation error.
 7746    \return SSL_BAD_FILETYPE returned if format is not correct.
 7747
 7748    \param ctx a pointer to a WOLFSSL structure, created using
 7749    wolfSSL_CTX_new().
 7750    \param buf a pointer to a constant unsigned char type that is
 7751    allocated as the buffer and passed through to
 7752    wolfSSL_SetTmpDH_buffer_wrapper.
 7753    \param sz a long integer type that is derived from the fname parameter
 7754    in wolfSSL_SetTmpDH_file_wrapper().
 7755    \param format an integer type passed through from
 7756    wolfSSL_SetTmpDH_file_wrapper().
 7757
 7758    _Example_
 7759    \code
 7760    static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl,
 7761    Const char* fname, int format);
 7762    #ifdef WOLFSSL_SMALL_STACK
 7763    byte staticBuffer[1]; // force heap usage
 7764    #else
 7765    byte* staticBuffer;
 7766    long sz = 0;
 7767    …
 7768    if(ssl){
 7769    	ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format);
 7770    } else {
 7771    ret = wolfSSL_CTX_SetTmpDH_buffer(ctx, myBuffer, sz, format);
 7772    }
 7773    \endcode
 7774
 7775    \sa wolfSSL_SetTmpDH_buffer_wrapper
 7776    \sa wolfSSL_SetTMpDH_buffer
 7777    \sa wolfSSL_SetTmpDH_file_wrapper
 7778    \sa wolfSSL_CTX_SetTmpDH_file
 7779*/
 7780int  wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX* ctx, const unsigned char* b,
 7781                                           long sz, int format);
 7782
 7783/*!
 7784    \ingroup CertsKeys
 7785
 7786    \brief The function calls wolfSSL_SetTmpDH_file_wrapper to set the server
 7787    Diffie-Hellman parameters.
 7788
 7789    \return SSL_SUCCESS returned if the wolfSSL_SetTmpDH_file_wrapper or any
 7790    of its subroutines return successfully.
 7791    \return MEMORY_E returned if an allocation of dynamic memory fails in a
 7792    subroutine.
 7793    \return BAD_FUNC_ARG returned if the ctx or fname parameters are NULL or
 7794    if
 7795    a subroutine is passed a NULL argument.
 7796    \return SSL_BAD_FILE returned if the certificate file is unable to open or
 7797    if the a set of checks on the file fail from wolfSSL_SetTmpDH_file_wrapper.
 7798    \return SSL_BAD_FILETYPE returned if the format is not PEM or ASN.1 from
 7799    wolfSSL_SetTmpDH_buffer_wrapper().
 7800    \return DH_KEY_SIZE_E returned if the DH parameter's key size is less than
 7801    the value of the minDhKeySz member of the WOLFSSL_CTX struct.
 7802    \return DH_KEY_SIZE_E returned if the DH parameter's key size is greater
 7803    than the value of the maxDhKeySz member of the WOLFSSL_CTX struct.
 7804    \return SIDE_ERROR returned in wolfSSL_SetTmpDH() if the side is not the
 7805    server end.
 7806    \return SSL_NO_PEM_HEADER returned from PemToDer if there is no PEM header.
 7807    \return SSL_FATAL_ERROR returned from PemToDer if there is a memory copy
 7808    failure.
 7809
 7810    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 7811    wolfSSL_CTX_new().
 7812    \param fname a constant character pointer to a certificate file.
 7813    \param format an integer type passed through from
 7814    wolfSSL_SetTmpDH_file_wrapper() that is a representation of
 7815    the certificate format.
 7816
 7817    _Example_
 7818    \code
 7819    #define dhParam     “certs/dh2048.pem”
 7820    #DEFINE aSSERTiNTne(x, y)     AssertInt(x, y, !=, ==)
 7821    WOLFSSL_CTX* ctx;
 7822    …
 7823    AssertNotNull(ctx = wolfSSL_CTX_new(wolfSSLv23_client_method()))
 7824    …
 7825    AssertIntNE(SSL_SUCCESS, wolfSSL_CTX_SetTmpDH_file(NULL, dhParam,
 7826    SSL_FILETYPE_PEM));
 7827    \endcode
 7828
 7829    \sa wolfSSL_SetTmpDH_buffer_wrapper
 7830    \sa wolfSSL_SetTmpDH
 7831    \sa wolfSSL_CTX_SetTmpDH
 7832    \sa wolfSSL_SetTmpDH_buffer
 7833    \sa wolfSSL_CTX_SetTmpDH_buffer
 7834    \sa wolfSSL_SetTmpDH_file_wrapper
 7835    \sa AllocDer
 7836    \sa PemToDer
 7837*/
 7838int  wolfSSL_CTX_SetTmpDH_file(WOLFSSL_CTX* ctx, const char* f,
 7839                                             int format);
 7840
 7841/*!
 7842    \ingroup CertsKeys
 7843
 7844    \brief This function sets the minimum size (in bits) of the Diffie Hellman
 7845    key size by accessing the minDhKeySz member in the WOLFSSL_CTX structure.
 7846
 7847    \return SSL_SUCCESS returned if the function completes successfully.
 7848    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if
 7849    the keySz_bits is greater than 16,000 or not divisible by 8.
 7850
 7851    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 7852    wolfSSL_CTX_new().
 7853    \param keySz_bits a word16 type used to set the minimum DH key size in bits.
 7854    The WOLFSSL_CTX struct holds this information in the minDhKeySz member.
 7855
 7856    _Example_
 7857    \code
 7858    public static int CTX_SetMinDhKey_Sz(IntPtr ctx, short minDhKey){
 7859    …
 7860    return wolfSSL_CTX_SetMinDhKey_Sz(local_ctx, minDhKeyBits);
 7861    \endcode
 7862
 7863    \sa wolfSSL_SetMinDhKey_Sz
 7864    \sa wolfSSL_CTX_SetMaxDhKey_Sz
 7865    \sa wolfSSL_SetMaxDhKey_Sz
 7866    \sa wolfSSL_GetDhKey_Sz
 7867    \sa wolfSSL_CTX_SetTMpDH_file
 7868*/
 7869int wolfSSL_CTX_SetMinDhKey_Sz(WOLFSSL_CTX* ctx, word16 keySz_bits);
 7870
 7871/*!
 7872    \ingroup CertsKeys
 7873
 7874    \brief Sets the minimum size (in bits) for a Diffie-Hellman key in the
 7875    WOLFSSL structure.
 7876
 7877    \return SSL_SUCCESS the minimum size was successfully set.
 7878    \return BAD_FUNC_ARG the WOLFSSL structure was NULL or if the keySz_bits is
 7879    greater than 16,000 or not divisible by 8.
 7880
 7881    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 7882    \param keySz_bits a word16 type used to set the minimum DH key size in bits.
 7883    The WOLFSSL_CTX struct holds this information in the minDhKeySz member.
 7884
 7885    _Example_
 7886    \code
 7887    WOLFSSL* ssl = wolfSSL_new(ctx);
 7888    word16 keySz_bits;
 7889    ...
 7890    if(wolfSSL_SetMinDhKey_Sz(ssl, keySz_bits) != SSL_SUCCESS){
 7891	    // Failed to set.
 7892    }
 7893    \endcode
 7894
 7895    \sa wolfSSL_CTX_SetMinDhKey_Sz
 7896    \sa wolfSSL_GetDhKey_Sz
 7897*/
 7898int wolfSSL_SetMinDhKey_Sz(WOLFSSL* ssl, word16 keySz_bits);
 7899
 7900/*!
 7901    \ingroup CertsKeys
 7902
 7903    \brief This function sets the maximum size (in bits) of the Diffie Hellman
 7904    key size by accessing the maxDhKeySz member in the WOLFSSL_CTX structure.
 7905
 7906    \return SSL_SUCCESS returned if the function completes successfully.
 7907    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if
 7908    the keySz_bits is greater than 16,000 or not divisible by 8.
 7909
 7910    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 7911    wolfSSL_CTX_new().
 7912    \param keySz_bits a word16 type used to set the maximum DH key size in bits.
 7913    The WOLFSSL_CTX struct holds this information in the maxDhKeySz member.
 7914
 7915    _Example_
 7916    \code
 7917    public static int CTX_SetMaxDhKey_Sz(IntPtr ctx, short maxDhKey){
 7918    …
 7919    return wolfSSL_CTX_SetMaxDhKey_Sz(local_ctx, keySz_bits);
 7920    \endcode
 7921
 7922    \sa wolfSSL_SetMinDhKey_Sz
 7923    \sa wolfSSL_CTX_SetMinDhKey_Sz
 7924    \sa wolfSSL_SetMaxDhKey_Sz
 7925    \sa wolfSSL_GetDhKey_Sz
 7926    \sa wolfSSL_CTX_SetTMpDH_file
 7927*/
 7928int wolfSSL_CTX_SetMaxDhKey_Sz(WOLFSSL_CTX* ctx, word16 keySz_bits);
 7929
 7930/*!
 7931    \ingroup CertsKeys
 7932
 7933    \brief Sets the maximum size (in bits) for a Diffie-Hellman key in the
 7934    WOLFSSL structure.
 7935
 7936    \return SSL_SUCCESS the maximum size was successfully set.
 7937    \return BAD_FUNC_ARG the WOLFSSL structure was NULL or the keySz parameter
 7938    was greater than the allowable size or not divisible by 8.
 7939
 7940    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 7941    \param keySz a word16 type representing the bit size of the maximum DH key.
 7942
 7943    _Example_
 7944    \code
 7945    WOLFSSL* ssl = wolfSSL_new(ctx);
 7946    word16 keySz;
 7947    ...
 7948    if(wolfSSL_SetMaxDhKey(ssl, keySz) != SSL_SUCCESS){
 7949	    // Failed to set.
 7950    }
 7951    \endcode
 7952
 7953    \sa wolfSSL_CTX_SetMaxDhKey_Sz
 7954    \sa wolfSSL_GetDhKey_Sz
 7955*/
 7956int wolfSSL_SetMaxDhKey_Sz(WOLFSSL* ssl, word16 keySz_bits);
 7957
 7958/*!
 7959    \ingroup CertsKeys
 7960
 7961    \brief Returns the value of dhKeySz (in bits) that is a member of the
 7962    options structure. This value represents the Diffie-Hellman key size in
 7963    bytes.
 7964
 7965    \return dhKeySz returns the value held in ssl->options.dhKeySz which is an
 7966    integer value representing a size in bits.
 7967    \return BAD_FUNC_ARG returns if the WOLFSSL struct is NULL.
 7968
 7969    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 7970
 7971    _Example_
 7972    \code
 7973    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 7974    WOLFSSL* ssl = wolfSSL_new(ctx);
 7975    int dhKeySz;
 7976    ...
 7977    dhKeySz = wolfSSL_GetDhKey_Sz(ssl);
 7978
 7979    if(dhKeySz == BAD_FUNC_ARG || dhKeySz <= 0){
 7980    	// Failure case
 7981    } else {
 7982    	// dhKeySz holds the size of the key.
 7983    }
 7984    \endcode
 7985
 7986    \sa wolfSSL_SetMinDhKey_sz
 7987    \sa wolfSSL_CTX_SetMinDhKey_Sz
 7988    \sa wolfSSL_CTX_SetTmpDH
 7989    \sa wolfSSL_SetTmpDH
 7990    \sa wolfSSL_CTX_SetTmpDH_file
 7991*/
 7992int wolfSSL_GetDhKey_Sz(WOLFSSL* ssl);
 7993
 7994/*!
 7995    \ingroup CertsKeys
 7996
 7997    \brief Sets the minimum RSA key size in both the WOLFSSL_CTX structure
 7998    and the WOLFSSL_CERT_MANAGER structure.
 7999
 8000    \return SSL_SUCCESS returned on successful execution of the function.
 8001    \return BAD_FUNC_ARG returned if the ctx structure is NULL or the keySz
 8002    is less than zero or not divisible by 8.
 8003
 8004    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 8005    wolfSSL_CTX_new().
 8006    \param keySz a short integer type stored in minRsaKeySz in the ctx
 8007    structure and the cm structure converted to bytes.
 8008
 8009    _Example_
 8010    \code
 8011    WOLFSSL_CTX* ctx = SSL_CTX_new(method);
 8012    (void)minDhKeyBits;
 8013    ourCert = myoptarg;
 8014    …
 8015    minDhKeyBits = atoi(myoptarg);
 8016    …
 8017    if(wolfSSL_CTX_SetMinRsaKey_Sz(ctx, minRsaKeyBits) != SSL_SUCCESS){
 8018    …
 8019    \endcode
 8020
 8021    \sa wolfSSL_SetMinRsaKey_Sz
 8022*/
 8023int wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX* ctx, short keySz);
 8024
 8025/*!
 8026    \ingroup CertsKeys
 8027
 8028    \brief Sets the minimum allowable key size in bits for RSA located in the
 8029    WOLFSSL structure.
 8030
 8031    \return SSL_SUCCESS the minimum was set successfully.
 8032    \return BAD_FUNC_ARG returned if the ssl structure is NULL or if the ksySz
 8033    is less than zero or not divisible by 8.
 8034
 8035    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 8036    \param keySz a short integer value representing the the minimum key in bits.
 8037
 8038    _Example_
 8039    \code
 8040    WOLFSSL* ssl = wolfSSL_new(ctx);
 8041    short keySz;
 8042    …
 8043
 8044    int isSet =  wolfSSL_SetMinRsaKey_Sz(ssl, keySz);
 8045    if(isSet != SSL_SUCCESS){
 8046	    Failed to set.
 8047    }
 8048    \endcode
 8049
 8050    \sa wolfSSL_CTX_SetMinRsaKey_Sz
 8051*/
 8052int wolfSSL_SetMinRsaKey_Sz(WOLFSSL* ssl, short keySz);
 8053
 8054/*!
 8055    \ingroup CertsKeys
 8056
 8057    \brief Sets the minimum size in bits for the ECC key in the WOLF_CTX
 8058    structure and the WOLFSSL_CERT_MANAGER structure.
 8059
 8060    \return SSL_SUCCESS returned for a successful execution and the minEccKeySz
 8061    member is set.
 8062    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if
 8063    the keySz is negative or not divisible by 8.
 8064
 8065    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 8066    wolfSSL_CTX_new().
 8067    \param keySz a short integer type that represents the minimum ECC key
 8068    size in bits.
 8069
 8070    _Example_
 8071    \code
 8072    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
 8073    short keySz; // minimum key size
 8074    …
 8075    if(wolfSSL_CTX_SetMinEccKey(ctx, keySz) != SSL_SUCCESS){
 8076	    // Failed to set min key size
 8077    }
 8078    \endcode
 8079
 8080    \sa wolfSSL_SetMinEccKey_Sz
 8081*/
 8082int wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX* ctx, short keySz);
 8083
 8084/*!
 8085    \ingroup CertsKeys
 8086
 8087    \brief Sets the value of the minEccKeySz member of the options structure.
 8088    The options struct is a member of the WOLFSSL structure and is
 8089    accessed through the ssl parameter.
 8090
 8091    \return SSL_SUCCESS if the function successfully set the minEccKeySz
 8092    member of the options structure.
 8093    \return BAD_FUNC_ARG if the WOLFSSL_CTX structure is NULL or if the
 8094    key size (keySz) is less than 0 (zero) or not divisible by 8.
 8095
 8096    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 8097    \param keySz value used to set the minimum ECC key size. Sets
 8098    value in the options structure.
 8099
 8100    _Example_
 8101    \code
 8102    WOLFSSL* ssl = wolfSSL_new(ctx); // New session
 8103    short keySz = 999; // should be set to min key size allowable
 8104    ...
 8105    if(wolfSSL_SetMinEccKey_Sz(ssl, keySz) != SSL_SUCCESS){
 8106	    // Failure case.
 8107    }
 8108    \endcode
 8109
 8110    \sa wolfSSL_CTX_SetMinEccKey_Sz
 8111    \sa wolfSSL_CTX_SetMinRsaKey_Sz
 8112    \sa wolfSSL_SetMinRsaKey_Sz
 8113*/
 8114int wolfSSL_SetMinEccKey_Sz(WOLFSSL* ssl, short keySz);
 8115
 8116/*!
 8117    \ingroup CertsKeys
 8118
 8119    \brief This function is used by EAP_TLS and EAP-TTLS to derive
 8120    keying material from the master secret.
 8121
 8122    \return BUFFER_E returned if the actual size of the buffer exceeds
 8123    the maximum size allowable.
 8124    \return MEMORY_E returned if there is an error with memory allocation.
 8125
 8126    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 8127    \param key a void pointer variable that will hold the result
 8128    of the p_hash function.
 8129    \param len an unsigned integer that represents the length of
 8130    the key variable.
 8131    \param label a constant char pointer that is copied from in wc_PRF().
 8132
 8133    _Example_
 8134    \code
 8135    WOLFSSL* ssl = wolfSSL_new(ctx);;
 8136    void* key;
 8137    unsigned int len;
 8138    const char* label;
 8139    …
 8140    return wolfSSL_make_eap_keys(ssl, key, len, label);
 8141    \endcode
 8142
 8143    \sa wc_PRF
 8144    \sa wc_HmacFinal
 8145    \sa wc_HmacUpdate
 8146*/
 8147int wolfSSL_make_eap_keys(WOLFSSL* ssl, void* key, unsigned int len,
 8148                                                             const char* label);
 8149
 8150/*!
 8151    \ingroup IO
 8152
 8153    \brief Simulates writev semantics but doesn’t actually do block at a time
 8154    because of SSL_write() behavior and because front adds may be small.
 8155    Makes porting into software that uses writev easier.
 8156
 8157    \return >0 the number of bytes written upon success.
 8158    \return 0 will be returned upon failure.  Call wolfSSL_get_error() for
 8159    the specific error code.
 8160    \return MEMORY_ERROR will be returned if a memory error was encountered.
 8161    \return SSL_FATAL_ERROR will be returned upon failure when either an error
 8162    occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or
 8163    SSL_ERROR_WANT_WRITE error was received and and the application needs to
 8164    call wolfSSL_write() again.  Use wolfSSL_get_error() to get a specific
 8165    error code.
 8166
 8167    \param ssl pointer to the SSL session, created with wolfSSL_new().
 8168    \param iov array of I/O vectors to write
 8169    \param iovcnt number of vectors in iov array.
 8170
 8171    _Example_
 8172    \code
 8173    WOLFSSL* ssl = 0;
 8174    char *bufA = “hello\n”;
 8175    char *bufB = “hello world\n”;
 8176    int iovcnt;
 8177    struct iovec iov[2];
 8178
 8179    iov[0].iov_base = buffA;
 8180    iov[0].iov_len = strlen(buffA);
 8181    iov[1].iov_base = buffB;
 8182    iov[1].iov_len = strlen(buffB);
 8183    iovcnt = 2;
 8184    ...
 8185    ret = wolfSSL_writev(ssl, iov, iovcnt);
 8186    // wrote “ret” bytes, or error if <= 0.
 8187    \endcode
 8188
 8189    \sa wolfSSL_write
 8190*/
 8191int wolfSSL_writev(WOLFSSL* ssl, const struct iovec* iov,
 8192                                     int iovcnt);
 8193
 8194/*!
 8195    \ingroup Setup
 8196
 8197    \brief This function unloads the CA signer list and frees
 8198    the whole signer table.
 8199
 8200    \return SSL_SUCCESS returned on successful execution of the function.
 8201    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there
 8202    are otherwise unpermitted argument values passed in a subroutine.
 8203    \return BAD_MUTEX_E returned if there was a mutex error. The LockMutex()
 8204    did not return 0.
 8205
 8206    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 8207    wolfSSL_CTX_new().
 8208
 8209    _Example_
 8210    \code
 8211    WOLFSSL_METHOD method = wolfTLSv1_2_client_method();
 8212    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
 8213    …
 8214    if(wolfSSL_CTX_UnloadCAs(ctx) != SSL_SUCCESS){
 8215    	// The function did not unload CAs
 8216    }
 8217    \endcode
 8218
 8219    \sa wolfSSL_CertManagerUnloadCAs
 8220    \sa LockMutex
 8221    \sa UnlockMutex
 8222*/
 8223int wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX* ctx);
 8224
 8225
 8226/*!
 8227    \ingroup Setup
 8228
 8229    \brief This function unloads intermediate certificates added to the CA
 8230    signer list and frees them.
 8231
 8232    \return SSL_SUCCESS returned on successful execution of the function.
 8233    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there
 8234    are otherwise unpermitted argument values passed in a subroutine.
 8235    \return BAD_STATE_E returned if the WOLFSSL_CTX has a reference count > 1.
 8236    \return BAD_MUTEX_E returned if there was a mutex error. The LockMutex()
 8237    did not return 0.
 8238
 8239    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 8240    wolfSSL_CTX_new().
 8241
 8242    _Example_
 8243    \code
 8244    WOLFSSL_METHOD method = wolfTLSv1_2_client_method();
 8245    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method);
 8246    …
 8247    if(wolfSSL_CTX_UnloadIntermediateCerts(ctx) != NULL){
 8248        // The function did not unload CAs
 8249    }
 8250    \endcode
 8251
 8252    \sa wolfSSL_CTX_UnloadCAs
 8253    \sa wolfSSL_CertManagerUnloadIntermediateCerts
 8254*/
 8255int wolfSSL_CTX_UnloadIntermediateCerts(WOLFSSL_CTX* ctx);
 8256
 8257/*!
 8258    \ingroup Setup
 8259
 8260    \brief This function is used to unload all previously loaded trusted peer
 8261    certificates. Feature is enabled by defining the macro
 8262    WOLFSSL_TRUST_PEER_CERT.
 8263
 8264    \return SSL_SUCCESS upon success.
 8265    \return BAD_FUNC_ARG will be returned if ctx is NULL.
 8266    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
 8267    can’t be read, or is corrupted.
 8268    \return MEMORY_E will be returned if an out of memory condition occurs.
 8269
 8270    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8271
 8272    _Example_
 8273    \code
 8274    int ret = 0;
 8275    WOLFSSL_CTX* ctx;
 8276    ...
 8277    ret = wolfSSL_CTX_Unload_trust_peers(ctx);
 8278    if (ret != SSL_SUCCESS) {
 8279        // error unloading trusted peer certs
 8280    }
 8281    ...
 8282    \endcode
 8283
 8284    \sa wolfSSL_CTX_trust_peer_buffer
 8285    \sa wolfSSL_CTX_trust_peer_cert
 8286*/
 8287int wolfSSL_CTX_Unload_trust_peers(WOLFSSL_CTX* ctx);
 8288
 8289/*!
 8290    \ingroup Setup
 8291
 8292    \brief This function loads a certificate to use for verifying a peer
 8293    when performing a TLS/SSL handshake. The peer certificate sent during
 8294    the handshake is compared by using the SKID when available and the
 8295    signature. If these two things do not match then any loaded CAs are used.
 8296    Is the same functionality as wolfSSL_CTX_trust_peer_cert except is from
 8297    a buffer instead of a file. Feature is enabled by defining the macro
 8298    WOLFSSL_TRUST_PEER_CERT Please see the examples for proper usage.
 8299
 8300    \return SSL_SUCCESS upon success
 8301    \return SSL_FAILURE will be returned if ctx is NULL, or if both file and
 8302    type are invalid.
 8303    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8304    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
 8305    read, or is corrupted.
 8306    \return MEMORY_E will be returned if an out of memory condition occurs.
 8307    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8308
 8309    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8310    \param buffer pointer to the buffer containing certificates.
 8311    \param sz length of the buffer input.
 8312    \param type type of certificate being loaded i.e. SSL_FILETYPE_ASN1 or
 8313    SSL_FILETYPE_PEM.
 8314
 8315    _Example_
 8316    \code
 8317    int ret = 0;
 8318    WOLFSSL_CTX* ctx;
 8319    ...
 8320
 8321    ret = wolfSSL_CTX_trust_peer_buffer(ctx, bufferPtr, bufferSz,
 8322    SSL_FILETYPE_PEM);
 8323    if (ret != SSL_SUCCESS) {
 8324    // error loading trusted peer cert
 8325    }
 8326    ...
 8327    \endcode
 8328
 8329    \sa wolfSSL_CTX_load_verify_buffer
 8330    \sa wolfSSL_CTX_use_certificate_file
 8331    \sa wolfSSL_CTX_use_PrivateKey_file
 8332    \sa wolfSSL_CTX_use_certificate_chain_file
 8333    \sa wolfSSL_CTX_trust_peer_cert
 8334    \sa wolfSSL_CTX_Unload_trust_peers
 8335    \sa wolfSSL_use_certificate_file
 8336    \sa wolfSSL_use_PrivateKey_file
 8337    \sa wolfSSL_use_certificate_chain_file
 8338*/
 8339int wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,
 8340                                  long sz, int format);
 8341
 8342/*!
 8343    \ingroup CertsKeys
 8344
 8345    \brief This function loads a CA certificate buffer into the WOLFSSL
 8346    Context. It behaves like the non-buffered version, only differing in
 8347    its ability to be called with a buffer as input instead of a file.
 8348    The buffer is provided by the in argument of size sz. format specifies
 8349    the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8350    More than one CA certificate may be loaded per buffer as long as the
 8351    format is in PEM.  Please see the examples for proper usage.
 8352
 8353    \return SSL_SUCCESS upon success
 8354    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8355    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
 8356    can’t be read, or is corrupted.
 8357    \return MEMORY_E will be returned if an out of memory condition occurs.
 8358    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8359    \return BUFFER_E will be returned if a chain buffer is bigger than
 8360    the receiving buffer.
 8361
 8362    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8363    \param in pointer to the CA certificate buffer.
 8364    \param sz size of the input CA certificate buffer, in.
 8365    \param format format of the buffer certificate, either SSL_FILETYPE_ASN1
 8366    or SSL_FILETYPE_PEM.
 8367
 8368    _Example_
 8369    \code
 8370    int ret = 0;
 8371    WOLFSSL_CTX* ctx;
 8372    byte certBuff[...];
 8373    long sz = sizeof(certBuff);
 8374    ...
 8375
 8376    ret = wolfSSL_CTX_load_verify_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM);
 8377    if (ret != SSL_SUCCESS) {
 8378    	// error loading CA certs from buffer
 8379    }
 8380    ...
 8381    \endcode
 8382
 8383    \sa wolfSSL_CTX_load_verify_locations
 8384    \sa wolfSSL_CTX_use_certificate_buffer
 8385    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8386    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8387    \sa wolfSSL_use_certificate_buffer
 8388    \sa wolfSSL_use_PrivateKey_buffer
 8389    \sa wolfSSL_use_certificate_chain_buffer
 8390*/
 8391int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,
 8392                                   long sz, int format);
 8393
 8394
 8395/*!
 8396    \ingroup CertsKeys
 8397
 8398    \brief This function loads a CA certificate buffer into the WOLFSSL
 8399    Context. It behaves like the non-buffered version, only differing in
 8400    its ability to be called with a buffer as input instead of a file.
 8401    The buffer is provided by the in argument of size sz. format specifies
 8402    the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8403    More than one CA certificate may be loaded per buffer as long as the
 8404    format is in PEM.  The _ex version was added in PR 2413 and supports
 8405    additional arguments for userChain and flags.
 8406
 8407    \return SSL_SUCCESS upon success
 8408    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8409    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
 8410    can’t be read, or is corrupted.
 8411    \return MEMORY_E will be returned if an out of memory condition occurs.
 8412    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8413    \return BUFFER_E will be returned if a chain buffer is bigger than
 8414    the receiving buffer.
 8415
 8416    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8417    \param in pointer to the CA certificate buffer.
 8418    \param sz size of the input CA certificate buffer, in.
 8419    \param format format of the buffer certificate, either SSL_FILETYPE_ASN1
 8420    or SSL_FILETYPE_PEM.
 8421    \param userChain If using format WOLFSSL_FILETYPE_ASN1 this set to non-zero
 8422    indicates a chain of DER's is being presented.
 8423    \param flags: See ssl.h around WOLFSSL_LOAD_VERIFY_DEFAULT_FLAGS.
 8424
 8425    _Example_
 8426    \code
 8427    int ret = 0;
 8428    WOLFSSL_CTX* ctx;
 8429    byte certBuff[...];
 8430    long sz = sizeof(certBuff);
 8431    ...
 8432
 8433    // Example for force loading an expired certificate
 8434    ret = wolfSSL_CTX_load_verify_buffer_ex(ctx, certBuff, sz, SSL_FILETYPE_PEM,
 8435        0, (WOLFSSL_LOAD_FLAG_DATE_ERR_OKAY));
 8436    if (ret != SSL_SUCCESS) {
 8437    	// error loading CA certs from buffer
 8438    }
 8439    ...
 8440    \endcode
 8441
 8442    \sa wolfSSL_CTX_load_verify_buffer
 8443    \sa wolfSSL_CTX_load_verify_locations
 8444    \sa wolfSSL_CTX_use_certificate_buffer
 8445    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8446    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8447    \sa wolfSSL_use_certificate_buffer
 8448    \sa wolfSSL_use_PrivateKey_buffer
 8449    \sa wolfSSL_use_certificate_chain_buffer
 8450*/
 8451int wolfSSL_CTX_load_verify_buffer_ex(WOLFSSL_CTX* ctx,
 8452                                      const unsigned char* in, long sz,
 8453                                      int format, int userChain, word32 flags);
 8454
 8455/*!
 8456    \ingroup CertsKeys
 8457
 8458    \brief This function loads a CA certificate chain buffer into the WOLFSSL
 8459    Context. It behaves like the non-buffered version, only differing in
 8460    its ability to be called with a buffer as input instead of a file.
 8461    The buffer is provided by the in argument of size sz. format specifies
 8462    the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8463    More than one CA certificate may be loaded per buffer as long as the
 8464    format is in PEM.  Please see the examples for proper usage.
 8465
 8466    \return SSL_SUCCESS upon success
 8467    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8468    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
 8469    can’t be read, or is corrupted.
 8470    \return MEMORY_E will be returned if an out of memory condition occurs.
 8471    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8472    \return BUFFER_E will be returned if a chain buffer is bigger than
 8473    the receiving buffer.
 8474
 8475    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8476    \param in pointer to the CA certificate buffer.
 8477    \param sz size of the input CA certificate buffer, in.
 8478    \param format format of the buffer certificate, either SSL_FILETYPE_ASN1
 8479    or SSL_FILETYPE_PEM.
 8480
 8481    _Example_
 8482    \code
 8483    int ret = 0;
 8484    WOLFSSL_CTX* ctx;
 8485    byte certBuff[...];
 8486    long sz = sizeof(certBuff);
 8487    ...
 8488
 8489    ret = wolfSSL_CTX_load_verify_chain_buffer_format(ctx,
 8490                         certBuff, sz, WOLFSSL_FILETYPE_ASN1);
 8491    if (ret != SSL_SUCCESS) {
 8492        // error loading CA certs from buffer
 8493    }
 8494    ...
 8495    \endcode
 8496
 8497    \sa wolfSSL_CTX_load_verify_locations
 8498    \sa wolfSSL_CTX_use_certificate_buffer
 8499    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8500    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8501    \sa wolfSSL_use_certificate_buffer
 8502    \sa wolfSSL_use_PrivateKey_buffer
 8503    \sa wolfSSL_use_certificate_chain_buffer
 8504*/
 8505int wolfSSL_CTX_load_verify_chain_buffer_format(WOLFSSL_CTX* ctx,
 8506                                               const unsigned char* in,
 8507                                               long sz, int format);
 8508
 8509/*!
 8510    \ingroup CertsKeys
 8511
 8512    \brief This function loads a certificate buffer into the WOLFSSL Context.
 8513    It behaves like the non-buffered version, only differing in its ability
 8514    to be called with a buffer as input instead of a file.  The buffer is
 8515    provided by the in argument of size sz.  format specifies the format
 8516    type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.  Please
 8517    see the examples for proper usage.
 8518
 8519    \return SSL_SUCCESS upon success
 8520    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8521    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
 8522    can’t be read, or is corrupted.
 8523    \return MEMORY_E will be returned if an out of memory condition occurs.
 8524    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8525
 8526    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8527    \param in the input buffer containing the certificate to be loaded.
 8528    \param sz the size of the input buffer.
 8529    \param format the format of the certificate located in the input
 8530    buffer (in).  Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8531
 8532    _Example_
 8533    \code
 8534    int ret = 0;
 8535    WOLFSSL_CTX* ctx;
 8536    byte certBuff[...];
 8537    long sz = sizeof(certBuff);
 8538    ...
 8539    ret = wolfSSL_CTX_use_certificate_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM);
 8540    if (ret != SSL_SUCCESS) {
 8541	    // error loading certificate from buffer
 8542    }
 8543    ...
 8544    \endcode
 8545
 8546    \sa wolfSSL_CTX_load_verify_buffer
 8547    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8548    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8549    \sa wolfSSL_use_certificate_buffer
 8550    \sa wolfSSL_use_PrivateKey_buffer
 8551    \sa wolfSSL_use_certificate_chain_buffer
 8552*/
 8553int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX* ctx,
 8554                                       const unsigned char* in, long sz,
 8555                                       int format);
 8556
 8557/*!
 8558    \ingroup CertsKeys
 8559
 8560    \brief This function loads a private key buffer into the SSL Context.
 8561    It behaves like the non-buffered version, only differing in its ability
 8562    to be called with a buffer as input instead of a file.  The buffer is
 8563    provided by the in argument of size sz.  format specifies the format type
 8564    of the buffer; SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM.  Please see the
 8565    examples for proper usage.
 8566
 8567    \return SSL_SUCCESS upon success
 8568    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8569    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
 8570    read, or is corrupted.
 8571    \return MEMORY_E will be returned if an out of memory condition occurs.
 8572    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8573    \return NO_PASSWORD will be returned if the key file is encrypted but no
 8574    password is provided.
 8575
 8576    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8577    \param in the input buffer containing the private key to be loaded.
 8578    \param sz the size of the input buffer.
 8579    \param format the format of the private key located in the input
 8580    buffer (in).  Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8581
 8582    _Example_
 8583    \code
 8584    int ret = 0;
 8585    WOLFSSL_CTX* ctx;
 8586    byte keyBuff[...];
 8587    long sz = sizeof(certBuff);
 8588    ...
 8589    ret = wolfSSL_CTX_use_PrivateKey_buffer(ctx, keyBuff, sz, SSL_FILETYPE_PEM);
 8590    if (ret != SSL_SUCCESS) {
 8591    	// error loading private key from buffer
 8592    }
 8593    ...
 8594    \endcode
 8595
 8596    \sa wolfSSL_CTX_load_verify_buffer
 8597    \sa wolfSSL_CTX_use_certificate_buffer
 8598    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8599    \sa wolfSSL_use_certificate_buffer
 8600    \sa wolfSSL_use_PrivateKey_buffer
 8601    \sa wolfSSL_use_certificate_chain_buffer
 8602*/
 8603int wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX* ctx,
 8604                                      const unsigned char* in, long sz,
 8605                                      int format);
 8606
 8607/*!
 8608    \ingroup CertsKeys
 8609
 8610    \brief This function loads a certificate chain buffer into the WOLFSSL
 8611    Context. It behaves like the non-buffered version, only differing in
 8612    its ability to be called with a buffer as input instead of a file.
 8613    The buffer is provided by the in argument of size sz.  The buffer must
 8614    be in PEM format and start with the subject’s certificate, ending with
 8615    the root certificate. Please see the examples for proper usage.
 8616
 8617    \return SSL_SUCCESS upon success
 8618    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8619    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
 8620    can’t be read, or is corrupted.
 8621    \return MEMORY_E will be returned if an out of memory condition occurs.
 8622    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8623    \return BUFFER_E will be returned if a chain buffer is bigger than
 8624    the receiving buffer.
 8625
 8626    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8627    \param in the input buffer containing the PEM-formatted certificate
 8628    chain to be loaded.
 8629    \param sz the size of the input buffer.
 8630
 8631    _Example_
 8632    \code
 8633    int ret = 0;
 8634    WOLFSSL_CTX* ctx;
 8635    byte certChainBuff[...];
 8636    long sz = sizeof(certBuff);
 8637    ...
 8638    ret = wolfSSL_CTX_use_certificate_chain_buffer(ctx, certChainBuff, sz);
 8639    if (ret != SSL_SUCCESS) {
 8640    	// error loading certificate chain from buffer
 8641    }
 8642    ...
 8643    \endcode
 8644
 8645    \sa wolfSSL_CTX_load_verify_buffer
 8646    \sa wolfSSL_CTX_use_certificate_buffer
 8647    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8648    \sa wolfSSL_use_certificate_buffer
 8649    \sa wolfSSL_use_PrivateKey_buffer
 8650    \sa wolfSSL_use_certificate_chain_buffer
 8651*/
 8652int wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX* ctx,
 8653                                             const unsigned char* in, long sz);
 8654
 8655/*!
 8656    \ingroup CertsKeys
 8657
 8658    \brief This function loads a certificate buffer into the WOLFSSL object.
 8659    It behaves like the non-buffered version, only differing in its ability
 8660    to be called with a buffer as input instead of a file. The buffer
 8661    is provided by the in argument of size sz.  format specifies the format
 8662    type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8663    Please see the examples for proper usage.
 8664
 8665    \return SSL_SUCCESS upon success.
 8666    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8667    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t
 8668    be read, or is corrupted.
 8669    \return MEMORY_E will be returned if an out of memory condition occurs.
 8670    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8671
 8672    \param ssl pointer to the SSL session, created with wolfSSL_new().
 8673    \param in buffer containing certificate to load.
 8674    \param sz size of the certificate located in buffer.
 8675    \param format format of the certificate to be loaded.
 8676    Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8677
 8678    _Example_
 8679    \code
 8680    int ret;
 8681    byte certBuff[...];
 8682    WOLFSSL* ssl = 0;
 8683    long buffSz = sizeof(certBuff);
 8684    ...
 8685
 8686    ret = wolfSSL_use_certificate_buffer(ssl, certBuff, buffSz, SSL_FILETYPE_PEM);
 8687    if (ret != SSL_SUCCESS) {
 8688    	// failed to load certificate from buffer
 8689    }
 8690    \endcode
 8691
 8692    \sa wolfSSL_CTX_load_verify_buffer
 8693    \sa wolfSSL_CTX_use_certificate_buffer
 8694    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8695    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8696    \sa wolfSSL_use_PrivateKey_buffer
 8697    \sa wolfSSL_use_certificate_chain_buffer
 8698*/
 8699int wolfSSL_use_certificate_buffer(WOLFSSL* ssl, const unsigned char* in,
 8700                                               long sz, int format);
 8701
 8702/*!
 8703    \ingroup CertsKeys
 8704
 8705    \brief This function loads a private key buffer into the WOLFSSL object.
 8706    It behaves like the non-buffered version, only differing in its ability
 8707    to be called with a buffer as input instead of a file.  The buffer is
 8708    provided by the in argument of size sz. format specifies the format
 8709    type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.  Please
 8710    see the examples for proper usage.
 8711
 8712    \return SSL_SUCCESS upon success.
 8713    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8714    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
 8715    read, or is corrupted.
 8716    \return MEMORY_E will be returned if an out of memory condition occurs.
 8717    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8718    \return NO_PASSWORD will be returned if the key file is encrypted but no
 8719    password is provided.
 8720
 8721    \param ssl pointer to the SSL session, created with wolfSSL_new().
 8722    \param in buffer containing private key to load.
 8723    \param sz size of the private key located in buffer.
 8724    \param format format of the private key to be loaded.  Possible values are
 8725    SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
 8726
 8727    _Example_
 8728    \code
 8729    int ret;
 8730    byte keyBuff[...];
 8731    WOLFSSL* ssl = 0;
 8732    long buffSz = sizeof(certBuff);
 8733    ...
 8734    ret = wolfSSL_use_PrivateKey_buffer(ssl, keyBuff, buffSz, SSL_FILETYPE_PEM);
 8735    if (ret != SSL_SUCCESS) {
 8736    	// failed to load private key from buffer
 8737    }
 8738    \endcode
 8739
 8740    \sa wolfSSL_use_PrivateKey
 8741    \sa wolfSSL_CTX_load_verify_buffer
 8742    \sa wolfSSL_CTX_use_certificate_buffer
 8743    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8744    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8745    \sa wolfSSL_use_certificate_buffer
 8746    \sa wolfSSL_use_certificate_chain_buffer
 8747*/
 8748int wolfSSL_use_PrivateKey_buffer(WOLFSSL* ssl, const unsigned char* in,
 8749                                               long sz, int format);
 8750
 8751/*!
 8752    \ingroup CertsKeys
 8753
 8754    \brief This function loads a certificate chain buffer into the WOLFSSL
 8755    object.  It behaves like the non-buffered version, only differing in its
 8756    ability to be called with a buffer as input instead of a file. The buffer
 8757    is provided by the in argument of size sz.  The buffer must be in PEM format
 8758    and start with the subject’s certificate, ending with the root certificate.
 8759    Please see the examples for proper usage.
 8760
 8761    \return SSL_SUCCES upon success.
 8762    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
 8763    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
 8764    can’t be read, or is corrupted.
 8765    \return MEMORY_E will be returned if an out of memory condition occurs.
 8766    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
 8767    \return BUFFER_E will be returned if a chain buffer is bigger than
 8768    the receiving buffer.
 8769
 8770    \param ssl pointer to the SSL session, created with wolfSSL_new().
 8771    \param in buffer containing certificate to load.
 8772    \param sz size of the certificate located in buffer.
 8773
 8774    _Example_
 8775    \code
 8776    int ret;
 8777    byte certChainBuff[...];
 8778    WOLFSSL* ssl = 0;
 8779    long buffSz = sizeof(certBuff);
 8780    ...
 8781    ret = wolfSSL_use_certificate_chain_buffer(ssl, certChainBuff, buffSz);
 8782    if (ret != SSL_SUCCESS) {
 8783    	// failed to load certificate chain from buffer
 8784    }
 8785    \endcode
 8786
 8787    \sa wolfSSL_CTX_load_verify_buffer
 8788    \sa wolfSSL_CTX_use_certificate_buffer
 8789    \sa wolfSSL_CTX_use_PrivateKey_buffer
 8790    \sa wolfSSL_CTX_use_certificate_chain_buffer
 8791    \sa wolfSSL_use_certificate_buffer
 8792    \sa wolfSSL_use_PrivateKey_buffer
 8793*/
 8794int wolfSSL_use_certificate_chain_buffer(WOLFSSL* ssl,
 8795                                         const unsigned char* in, long sz);
 8796
 8797/*!
 8798    \ingroup CertsKeys
 8799
 8800    \brief This function unloads any certificates or keys that SSL owns.
 8801
 8802    \return SSL_SUCCESS - returned if the function executed successfully.
 8803    \return BAD_FUNC_ARG - returned if the WOLFSSL object is NULL.
 8804
 8805    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 8806
 8807    _Example_
 8808    \code
 8809    WOLFSSL* ssl = wolfSSL_new(ctx);
 8810    ...
 8811    int unloadKeys = wolfSSL_UnloadCertsKeys(ssl);
 8812    if(unloadKeys != SSL_SUCCESS){
 8813	    // Failure case.
 8814    }
 8815    \endcode
 8816
 8817    \sa wolfSSL_CTX_UnloadCAs
 8818*/
 8819int wolfSSL_UnloadCertsKeys(WOLFSSL* ssl);
 8820
 8821/*!
 8822    \ingroup Setup
 8823
 8824    \brief This function turns on grouping of handshake messages where possible.
 8825
 8826    \return SSL_SUCCESS will be returned upon success.
 8827    \return BAD_FUNC_ARG will be returned if the input context is null.
 8828
 8829    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 8830
 8831    _Example_
 8832    \code
 8833    WOLFSSL_CTX* ctx = 0;
 8834    ...
 8835    ret = wolfSSL_CTX_set_group_messages(ctx);
 8836    if (ret != SSL_SUCCESS) {
 8837	    // failed to set handshake message grouping
 8838    }
 8839    \endcode
 8840
 8841    \sa wolfSSL_set_group_messages
 8842    \sa wolfSSL_CTX_new
 8843*/
 8844int wolfSSL_CTX_set_group_messages(WOLFSSL_CTX* ctx);
 8845
 8846/*!
 8847    \ingroup Setup
 8848
 8849    \brief This function turns on grouping of handshake messages where possible.
 8850
 8851    \return SSL_SUCCESS will be returned upon success.
 8852    \return BAD_FUNC_ARG will be returned if the input context is null.
 8853
 8854    \param ssl pointer to the SSL session, created with wolfSSL_new().
 8855
 8856    _Example_
 8857    \code
 8858    WOLFSSL* ssl = 0;
 8859    ...
 8860    ret = wolfSSL_set_group_messages(ssl);
 8861    if (ret != SSL_SUCCESS) {
 8862	// failed to set handshake message grouping
 8863    }
 8864    \endcode
 8865
 8866    \sa wolfSSL_CTX_set_group_messages
 8867    \sa wolfSSL_new
 8868*/
 8869int wolfSSL_set_group_messages(WOLFSSL* ssl);
 8870
 8871/*!
 8872    \brief This function sets the fuzzer callback.
 8873
 8874    \return none No returns.
 8875
 8876    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 8877    \param cbf a CallbackFuzzer type that is a function pointer of the form:
 8878    int (*CallbackFuzzer)(WOLFSSL* ssl, const unsigned char* buf, int sz, int
 8879    type, void* fuzzCtx);
 8880    \param fCtx a void pointer type that will be set to the fuzzerCtx member of
 8881    the WOLFSSL structure.
 8882
 8883    _Example_
 8884    \code
 8885    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 8886    WOLFSSL* ssl = wolfSSL_new(ctx);
 8887    void* fCtx;
 8888
 8889    int callbackFuzzerCB(WOLFSSL* ssl, const unsigned char* buf, int sz,
 8890				int type, void* fuzzCtx){
 8891    // function definition
 8892    }
 8893    …
 8894    wolfSSL_SetFuzzerCb(ssl, callbackFuzzerCB, fCtx);
 8895    \endcode
 8896
 8897    \sa CallbackFuzzer
 8898*/
 8899void wolfSSL_SetFuzzerCb(WOLFSSL* ssl, CallbackFuzzer cbf, void* fCtx);
 8900
 8901/*!
 8902    \brief This function sets a new dtls cookie secret.
 8903
 8904    \return 0 returned if the function executed without an error.
 8905    \return BAD_FUNC_ARG returned if there was an argument passed
 8906    to the function with an unacceptable value.
 8907    \return COOKIE_SECRET_SZ returned if the secret size is 0.
 8908    \return MEMORY_ERROR returned if there was a problem allocating
 8909    memory for a new cookie secret.
 8910
 8911    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 8912    \param secret a constant byte pointer representing the secret buffer.
 8913    \param secretSz the size of the buffer.
 8914
 8915    _Example_
 8916    \code
 8917    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 8918    WOLFSSL* ssl = wolfSSL_new(ctx);
 8919    const* byte secret;
 8920    word32 secretSz; // size of secret
 8921    …
 8922    if(!wolfSSL_DTLS_SetCookieSecret(ssl, secret, secretSz)){
 8923    	// Code block for failure to set DTLS cookie secret
 8924    } else {
 8925    	// Success! Cookie secret is set.
 8926    }
 8927    \endcode
 8928
 8929    \sa ForceZero
 8930    \sa wc_RNG_GenerateBlock
 8931*/
 8932int   wolfSSL_DTLS_SetCookieSecret(WOLFSSL* ssl,
 8933                                               const byte* secret,
 8934                                               word32 secretSz);
 8935
 8936/*!
 8937    \brief This function retrieves the random number.
 8938
 8939    \return rng upon success.
 8940    \return NULL if ssl is NULL.
 8941
 8942    \param ssl pointer to a SSL object, created with wolfSSL_new().
 8943
 8944    _Example_
 8945    \code
 8946    WOLFSSL* ssl;
 8947
 8948    wolfSSL_GetRNG(ssl);
 8949
 8950    \endcode
 8951
 8952    \sa  wolfSSL_CTX_new_rng
 8953
 8954*/
 8955WC_RNG* wolfSSL_GetRNG(WOLFSSL* ssl);
 8956
 8957/*!
 8958    \ingroup Setup
 8959
 8960    \brief This function sets the minimum downgrade version allowed.
 8961    Applicable only when the connection allows downgrade using
 8962    (wolfSSLv23_client_method or wolfSSLv23_server_method).
 8963
 8964    \return SSL_SUCCESS returned if the function returned without
 8965    error and the minimum version is set.
 8966    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure was
 8967    NULL or if the minimum version is not supported.
 8968
 8969    \param ctx a pointer to a WOLFSSL_CTX structure, created using
 8970    wolfSSL_CTX_new().
 8971    \param version an integer representation of the version to be set as the
 8972    minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or
 8973    WOLFSSL_TLSV1_2 = 3.
 8974
 8975    _Example_
 8976    \code
 8977    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
 8978    WOLFSSL* ssl = WOLFSSL_new(ctx);
 8979    int version; // macrop representation
 8980    …
 8981    if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
 8982    	// Failed to set min version
 8983    }
 8984    \endcode
 8985
 8986    \sa SetMinVersionHelper
 8987*/
 8988int wolfSSL_CTX_SetMinVersion(WOLFSSL_CTX* ctx, int version);
 8989
 8990/*!
 8991    \ingroup TLS
 8992
 8993    \brief This function sets the minimum downgrade version allowed.
 8994    Applicable only when the connection allows downgrade using
 8995    (wolfSSLv23_client_method or wolfSSLv23_server_method).
 8996
 8997    \return SSL_SUCCESS returned if this function and its subroutine executes
 8998    without error.
 8999    \return BAD_FUNC_ARG returned if the SSL object is NULL.  In
 9000    the subroutine this error is thrown if there is not a good version match.
 9001
 9002    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 9003    \param version an integer representation of the version to be set as the
 9004    minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or
 9005    WOLFSSL_TLSV1_2 = 3.
 9006
 9007    _Example_
 9008    \code
 9009    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol method);
 9010    WOLFSSL* ssl = WOLFSSL_new(ctx);
 9011    int version;  macro representation
 9012    …
 9013    if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){
 9014	    Failed to set min version
 9015    }
 9016    \endcode
 9017
 9018    \sa SetMinVersionHelper
 9019*/
 9020int wolfSSL_SetMinVersion(WOLFSSL* ssl, int version);
 9021
 9022/*!
 9023    \brief This function returns the size of the WOLFSSL object and will be
 9024    dependent on build options and settings.  If SHOW_SIZES has been defined
 9025    when building wolfSSL, this function will also print the sizes of individual
 9026    objects within the WOLFSSL object (Suites, Ciphers, etc.) to stdout.
 9027
 9028    \return size This function returns the size of the WOLFSSL object.
 9029
 9030    \param none No parameters.
 9031
 9032    _Example_
 9033    \code
 9034    int size = 0;
 9035    size = wolfSSL_GetObjectSize();
 9036    printf(“sizeof(WOLFSSL) = %d\n”, size);
 9037    \endcode
 9038
 9039    \sa wolfSSL_new
 9040*/
 9041int wolfSSL_GetObjectSize(void);  /* object size based on build */
 9042/*!
 9043    \brief Returns the record layer size of the plaintext input. This is helpful
 9044    when an application wants to know how many bytes will be sent across the
 9045    Transport layer, given a specified plaintext input size. This function
 9046    must be called after the SSL/TLS handshake has been completed.
 9047
 9048    \return size Upon success, the requested size will be returned
 9049    \return INPUT_SIZE_E will be returned if the input size is greater than the
 9050    maximum TLS fragment size (see wolfSSL_GetMaxOutputSize())
 9051    \return BAD_FUNC_ARG will be returned upon invalid function argument, or if
 9052    the SSL/TLS handshake has not been completed yet
 9053
 9054    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9055    \param inSz size of plaintext data.
 9056
 9057    _Example_
 9058    \code
 9059    none
 9060    \endcode
 9061
 9062    \sa wolfSSL_GetMaxOutputSize
 9063*/
 9064int wolfSSL_GetOutputSize(WOLFSSL* ssl, int inSz);
 9065
 9066/*!
 9067    \brief Returns the maximum record layer size for plaintext data.  This
 9068    will correspond to either the maximum SSL/TLS record size as specified
 9069    by the protocol standard, the maximum TLS fragment size as set by the
 9070    TLS Max Fragment Length extension. This function is helpful when the
 9071    application has called wolfSSL_GetOutputSize() and received a INPUT_SIZE_E
 9072    error. This function must be called after the SSL/TLS handshake has been
 9073    completed.
 9074
 9075    \return size Upon success, the maximum output size will be returned
 9076    \return BAD_FUNC_ARG will be returned upon invalid function argument,
 9077    or if the SSL/TLS handshake has not been completed yet.
 9078
 9079    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9080
 9081    _Example_
 9082    \code
 9083    none
 9084    \endcode
 9085
 9086    \sa wolfSSL_GetOutputSize
 9087*/
 9088int wolfSSL_GetMaxOutputSize(WOLFSSL* ssl);
 9089
 9090/*!
 9091    \ingroup Setup
 9092
 9093    \brief This function sets the SSL/TLS protocol version for the specified
 9094    SSL session (WOLFSSL object) using the version as specified by version.
 9095    This will override the protocol setting for the SSL session (ssl) -
 9096    originally defined and set by the SSL context (wolfSSL_CTX_new())
 9097    method type.
 9098
 9099    \return SSL_SUCCESS upon success.
 9100    \return BAD_FUNC_ARG will be returned if the input SSL object is
 9101    NULL or an incorrect protocol version is given for version.
 9102
 9103    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 9104    \param version SSL/TLS protocol version.  Possible values include
 9105    WOLFSSL_SSLV3, WOLFSSL_TLSV1, WOLFSSL_TLSV1_1, WOLFSSL_TLSV1_2.
 9106
 9107    _Example_
 9108    \code
 9109    int ret = 0;
 9110    WOLFSSL* ssl;
 9111    ...
 9112
 9113    ret = wolfSSL_SetVersion(ssl, WOLFSSL_TLSV1);
 9114    if (ret != SSL_SUCCESS) {
 9115        // failed to set SSL session protocol version
 9116    }
 9117    \endcode
 9118
 9119    \sa wolfSSL_CTX_new
 9120*/
 9121int wolfSSL_SetVersion(WOLFSSL* ssl, int version);
 9122
 9123/*!
 9124    \brief Allows caller to set the Atomic User Record Processing
 9125    Mac/Encrypt Callback.  The callback should return 0 for success
 9126    or < 0 for an error.  The ssl and ctx pointers are available
 9127    for the user’s convenience.  macOut is the output buffer where
 9128    the result of the mac should be stored.  macIn is the mac input
 9129    buffer and macInSz notes the size of the buffer.  macContent
 9130    and macVerify are needed for wolfSSL_SetTlsHmacInner() and be
 9131    passed along as is.  encOut is the output buffer where the result
 9132    on the encryption should be stored.  encIn is the input buffer to
 9133    encrypt while encSz is the size of the input.  An example callback
 9134    can be found wolfssl/test.h myMacEncryptCb().
 9135
 9136    \return none No return.
 9137
 9138    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9139    \param cb callback function to register for Mac/Encrypt.
 9140
 9141    _Example_
 9142    \code
 9143    none
 9144    \endcode
 9145
 9146    \sa wolfSSL_SetMacEncryptCtx
 9147    \sa wolfSSL_GetMacEncryptCtx
 9148*/
 9149void  wolfSSL_CTX_SetMacEncryptCb(WOLFSSL_CTX* ctx, CallbackMacEncrypt cb);
 9150
 9151/*!
 9152    \brief Allows caller to set the Atomic User Record Processing Mac/Encrypt
 9153    Callback Context to ctx.
 9154
 9155    \return none No return.
 9156
 9157    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9158    \param ctx pointer to the user context to be stored.
 9159
 9160    _Example_
 9161    \code
 9162    none
 9163    \endcode
 9164
 9165    \sa wolfSSL_CTX_SetMacEncryptCb
 9166    \sa wolfSSL_GetMacEncryptCtx
 9167*/
 9168void  wolfSSL_SetMacEncryptCtx(WOLFSSL* ssl, void *ctx);
 9169
 9170/*!
 9171    \brief Allows caller to retrieve the Atomic User Record Processing
 9172    Mac/Encrypt Callback Context previously stored with
 9173    wolfSSL_SetMacEncryptCtx().
 9174
 9175    \return pointer If successful the call will return a valid pointer
 9176    to the context.
 9177    \return NULL will be returned for a blank context.
 9178
 9179    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9180
 9181    _Example_
 9182    \code
 9183    none
 9184    \endcode
 9185
 9186    \sa wolfSSL_CTX_SetMacEncryptCb
 9187    \sa wolfSSL_SetMacEncryptCtx
 9188*/
 9189void* wolfSSL_GetMacEncryptCtx(WOLFSSL* ssl);
 9190
 9191/*!
 9192    \brief Allows caller to set the Atomic User Record Processing
 9193    Decrypt/Verify Callback.  The callback should return 0 for success
 9194    or < 0 for an error.  The ssl and ctx pointers are available for
 9195    the user’s convenience.  decOut is the output buffer where the result
 9196    of the decryption should be stored.  decIn is the encrypted input
 9197    buffer and decInSz notes the size of the buffer.  content and verify
 9198    are needed for wolfSSL_SetTlsHmacInner() and be passed along as is.
 9199    padSz is an output variable that should be set with the total value
 9200    of the padding.  That is, the mac size plus any padding and pad bytes.
 9201    An example callback can be found wolfssl/test.h myDecryptVerifyCb().
 9202
 9203    \return none No returns.
 9204
 9205    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9206    \param cb callback function to register for Decrypt/Verify.
 9207
 9208    _Example_
 9209    \code
 9210    none
 9211    \endcode
 9212
 9213    \sa wolfSSL_SetMacEncryptCtx
 9214    \sa wolfSSL_GetMacEncryptCtx
 9215*/
 9216void  wolfSSL_CTX_SetDecryptVerifyCb(WOLFSSL_CTX* ctx,
 9217                                               CallbackDecryptVerify cb);
 9218
 9219/*!
 9220    \brief Allows caller to set the Atomic User Record Processing
 9221    Decrypt/Verify Callback Context to ctx.
 9222
 9223    \return none No returns.
 9224
 9225    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9226    \param ctx pointer to the user context to be stored.
 9227
 9228    _Example_
 9229    \code
 9230    none
 9231    \endcode
 9232
 9233    \sa wolfSSL_CTX_SetDecryptVerifyCb
 9234    \sa wolfSSL_GetDecryptVerifyCtx
 9235*/
 9236void  wolfSSL_SetDecryptVerifyCtx(WOLFSSL* ssl, void *ctx);
 9237
 9238/*!
 9239    \brief Allows caller to retrieve the Atomic User Record Processing
 9240    Decrypt/Verify Callback Context previously stored with
 9241    wolfSSL_SetDecryptVerifyCtx().
 9242
 9243    \return pointer If successful the call will return a valid pointer to the
 9244    context.
 9245    \return NULL will be returned for a blank context.
 9246
 9247    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9248
 9249    _Example_
 9250    \code
 9251    none
 9252    \endcode
 9253
 9254    \sa wolfSSL_CTX_SetDecryptVerifyCb
 9255    \sa wolfSSL_SetDecryptVerifyCtx
 9256*/
 9257void* wolfSSL_GetDecryptVerifyCtx(WOLFSSL* ssl);
 9258
 9259/*!
 9260    \brief Allows retrieval of the Hmac/Mac secret from the handshake process.
 9261    The verify parameter specifies whether this is for verification of a
 9262    peer message.
 9263
 9264    \return pointer If successful the call will return a valid pointer to the
 9265    secret.  The size of the secret can be obtained from wolfSSL_GetHmacSize().
 9266    \return NULL will be returned for an error state.
 9267
 9268    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9269    \param verify specifies whether this is for verification of a peer message.
 9270
 9271    _Example_
 9272    \code
 9273    none
 9274    \endcode
 9275
 9276    \sa wolfSSL_GetHmacSize
 9277*/
 9278const unsigned char* wolfSSL_GetMacSecret(WOLFSSL* ssl, int verify);
 9279
 9280/*!
 9281    \brief Allows retrieval of the client write key from the handshake process.
 9282
 9283    \return pointer If successful the call will return a valid pointer to the
 9284    key. The size of the key can be obtained from wolfSSL_GetKeySize().
 9285    \return NULL will be returned for an error state.
 9286
 9287    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9288
 9289    _Example_
 9290    \code
 9291    none
 9292    \endcode
 9293
 9294    \sa wolfSSL_GetKeySize
 9295    \sa wolfSSL_GetClientWriteIV
 9296*/
 9297const unsigned char* wolfSSL_GetClientWriteKey(WOLFSSL*);
 9298
 9299/*!
 9300    \brief Allows retrieval of the client write IV (initialization vector)
 9301    from the handshake process.
 9302
 9303    \return pointer If successful the call will return a valid pointer to the
 9304    IV.  The size of the IV can be obtained from wolfSSL_GetCipherBlockSize().
 9305    \return NULL will be returned for an error state.
 9306
 9307    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9308
 9309    _Example_
 9310    \code
 9311    none
 9312    \endcode
 9313
 9314    \sa wolfSSL_GetCipherBlockSize()
 9315    \sa wolfSSL_GetClientWriteKey()
 9316*/
 9317const unsigned char* wolfSSL_GetClientWriteIV(WOLFSSL*);
 9318
 9319/*!
 9320    \brief Allows retrieval of the server write key from the handshake process.
 9321
 9322    \return pointer If successful the call will return a valid pointer to the
 9323    key.  The size of the key can be obtained from wolfSSL_GetKeySize().
 9324    \return NULL will be returned for an error state.
 9325
 9326    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9327
 9328    _Example_
 9329    \code
 9330    none
 9331    \endcode
 9332
 9333    \sa wolfSSL_GetKeySize
 9334    \sa wolfSSL_GetServerWriteIV
 9335*/
 9336const unsigned char* wolfSSL_GetServerWriteKey(WOLFSSL*);
 9337
 9338/*!
 9339    \brief Allows retrieval of the server write IV (initialization vector)
 9340    from the handshake process.
 9341
 9342    \return pointer If successful the call will return a valid pointer to the
 9343    IV.  The size of the IV can be obtained from wolfSSL_GetCipherBlockSize().
 9344    \return NULL will be returned for an error state.
 9345
 9346    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9347
 9348    \sa wolfSSL_GetCipherBlockSize
 9349    \sa wolfSSL_GetClientWriteKey
 9350*/
 9351const unsigned char* wolfSSL_GetServerWriteIV(WOLFSSL*);
 9352
 9353/*!
 9354    \brief Allows retrieval of the key size from the handshake process.
 9355
 9356    \return size If successful the call will return the key size in bytes.
 9357    \return BAD_FUNC_ARG will be returned for an error state.
 9358
 9359    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9360
 9361    _Example_
 9362    \code
 9363    none
 9364    \endcode
 9365
 9366    \sa wolfSSL_GetClientWriteKey
 9367    \sa wolfSSL_GetServerWriteKey
 9368*/
 9369int                  wolfSSL_GetKeySize(WOLFSSL* ssl);
 9370
 9371/*!
 9372    \ingroup CertsKeys
 9373
 9374    \brief Returns the iv_size member of the specs structure
 9375    held in the WOLFSSL struct.
 9376
 9377    \return iv_size returns the value held in ssl->specs.iv_size.
 9378    \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
 9379
 9380    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
 9381
 9382    _Example_
 9383    \code
 9384    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
 9385    WOLFSSL* ssl = wolfSSL_new(ctx);
 9386    int ivSize;
 9387    ...
 9388    ivSize = wolfSSL_GetIVSize(ssl);
 9389
 9390    if(ivSize > 0){
 9391    	// ivSize holds the specs.iv_size value.
 9392    }
 9393    \endcode
 9394
 9395    \sa wolfSSL_GetKeySize
 9396    \sa wolfSSL_GetClientWriteIV
 9397    \sa wolfSSL_GetServerWriteIV
 9398*/
 9399int                  wolfSSL_GetIVSize(WOLFSSL* ssl);
 9400
 9401/*!
 9402    \brief Allows retrieval of the side of this WOLFSSL connection.
 9403
 9404    \return success If successful the call will return either
 9405    WOLFSSL_SERVER_END or WOLFSSL_CLIENT_END depending on the
 9406    side of WOLFSSL object.
 9407    \return BAD_FUNC_ARG will be returned for an error state.
 9408
 9409    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9410
 9411    _Example_
 9412    \code
 9413    none
 9414    \endcode
 9415
 9416    \sa wolfSSL_GetClientWriteKey
 9417    \sa wolfSSL_GetServerWriteKey
 9418*/
 9419int                  wolfSSL_GetSide(WOLFSSL* ssl);
 9420
 9421/*!
 9422    \brief Allows caller to determine if the negotiated protocol version
 9423    is at least TLS version 1.1 or greater.
 9424
 9425    \return true/false If successful the call will return 1 for true or
 9426    0 for false.
 9427    \return BAD_FUNC_ARG will be returned for an error state.
 9428
 9429    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9430
 9431    _Example_
 9432    \code
 9433    none
 9434    \endcode
 9435
 9436    \sa wolfSSL_GetSide
 9437*/
 9438int                  wolfSSL_IsTLSv1_1(WOLFSSL* ssl);
 9439
 9440/*!
 9441    \brief Allows caller to determine the negotiated bulk cipher algorithm
 9442    from the handshake.
 9443
 9444    \return If successful the call will return one of the following:
 9445    wolfssl_cipher_null, wolfssl_des, wolfssl_triple_des, wolfssl_aes,
 9446    wolfssl_aes_gcm, wolfssl_aes_ccm, wolfssl_camellia.
 9447    \return BAD_FUNC_ARG will be returned for an error state.
 9448
 9449    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9450
 9451    _Example_
 9452    \code
 9453    none
 9454    \endcode
 9455
 9456    \sa wolfSSL_GetCipherBlockSize
 9457    \sa wolfSSL_GetKeySize
 9458*/
 9459int                  wolfSSL_GetBulkCipher(WOLFSSL* ssl);
 9460
 9461/*!
 9462    \brief Allows caller to determine the negotiated cipher block size from
 9463    the handshake.
 9464
 9465    \return size If successful the call will return the size in bytes of the
 9466    cipher block size.
 9467    \return BAD_FUNC_ARG will be returned for an error state.
 9468
 9469    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9470
 9471    _Example_
 9472    \code
 9473    none
 9474    \endcode
 9475
 9476    \sa wolfSSL_GetBulkCipher
 9477    \sa wolfSSL_GetKeySize
 9478*/
 9479int                  wolfSSL_GetCipherBlockSize(WOLFSSL* ssl);
 9480
 9481/*!
 9482    \brief Allows caller to determine the negotiated aead mac size from the
 9483    handshake.  For cipher type WOLFSSL_AEAD_TYPE.
 9484
 9485    \return size If successful the call will return the size in bytes of the
 9486    aead mac size.
 9487    \return BAD_FUNC_ARG will be returned for an error state.
 9488
 9489    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9490
 9491    _Example_
 9492    \code
 9493    none
 9494    \endcode
 9495
 9496    \sa wolfSSL_GetBulkCipher
 9497    \sa wolfSSL_GetKeySize
 9498*/
 9499int                  wolfSSL_GetAeadMacSize(WOLFSSL* ssl);
 9500
 9501/*!
 9502    \brief Allows caller to determine the negotiated (h)mac size from the
 9503    handshake. For cipher types except WOLFSSL_AEAD_TYPE.
 9504
 9505    \return size If successful the call will return the size in bytes of
 9506    the (h)mac size.
 9507    \return BAD_FUNC_ARG will be returned for an error state.
 9508
 9509    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9510
 9511    _Example_
 9512    \code
 9513    none
 9514    \endcode
 9515
 9516    \sa wolfSSL_GetBulkCipher
 9517    \sa wolfSSL_GetHmacType
 9518*/
 9519int                  wolfSSL_GetHmacSize(WOLFSSL* ssl);
 9520
 9521/*!
 9522    \brief Allows caller to determine the negotiated (h)mac type from the
 9523    handshake.  For cipher types except WOLFSSL_AEAD_TYPE.
 9524
 9525    \return If successful the call will return one of the following:
 9526    MD5, SHA, SHA256, SHA384.
 9527    \return BAD_FUNC_ARG may be returned for an error state.
 9528    \return SSL_FATAL_ERROR may also be returned for an error state.
 9529
 9530    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9531
 9532    _Example_
 9533    \code
 9534    none
 9535    \endcode
 9536
 9537    \sa wolfSSL_GetBulkCipher
 9538    \sa wolfSSL_GetHmacSize
 9539*/
 9540int                  wolfSSL_GetHmacType(WOLFSSL* ssl);
 9541
 9542/*!
 9543    \brief Allows caller to determine the negotiated cipher type
 9544    from the handshake.
 9545
 9546    \return If successful the call will return one of the following:
 9547    WOLFSSL_BLOCK_TYPE, WOLFSSL_STREAM_TYPE, WOLFSSL_AEAD_TYPE.
 9548    \return BAD_FUNC_ARG will be returned for an error state.
 9549
 9550    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9551
 9552    _Example_
 9553    \code
 9554    none
 9555    \endcode
 9556
 9557    \sa wolfSSL_GetBulkCipher
 9558    \sa wolfSSL_GetHmacType
 9559*/
 9560int                  wolfSSL_GetCipherType(WOLFSSL* ssl);
 9561
 9562/*!
 9563    \brief Allows caller to set the Hmac Inner vector for message
 9564    sending/receiving.  The result is written to inner which should
 9565    be at least wolfSSL_GetHmacSize() bytes.  The size of the message
 9566    is specified by sz, content is the type of message, and verify
 9567    specifies whether this is a verification of a peer message. Valid
 9568    for cipher types excluding WOLFSSL_AEAD_TYPE.
 9569
 9570    \return 1 upon success.
 9571    \return BAD_FUNC_ARG will be returned for an error state.
 9572
 9573    \param none No parameters.
 9574
 9575    _Example_
 9576    \code
 9577    none
 9578    \endcode
 9579
 9580    \sa wolfSSL_GetBulkCipher
 9581    \sa wolfSSL_GetHmacType
 9582*/
 9583int wolfSSL_SetTlsHmacInner(WOLFSSL* ssl, byte* inner,
 9584                            word32 sz, int content, int verify);
 9585
 9586/*!
 9587    \brief Allows caller to set the Public Key Callback for ECC Signing.
 9588    The callback should return 0 for success or < 0 for an error.
 9589    The ssl and ctx pointers are available for the user’s convenience.
 9590    in is the input buffer to sign while inSz denotes the length of the input.
 9591    out is the output buffer where the result of the signature should be stored.
 9592    outSz is an input/output variable that specifies the size of the output
 9593    buffer upon invocation and the actual size of the signature should be stored
 9594    there before returning.  keyDer is the ECC Private key in ASN1 format and
 9595    keySz is the length of the key in bytes.  An example callback can be found
 9596    wolfssl/test.h myEccSign().
 9597
 9598    \return none No returns.
 9599
 9600    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9601    \param cb callback function to register for ECC signing.
 9602
 9603    _Example_
 9604    \code
 9605    none
 9606    \endcode
 9607
 9608    \sa wolfSSL_SetEccSignCtx
 9609    \sa wolfSSL_GetEccSignCtx
 9610*/
 9611void  wolfSSL_CTX_SetEccSignCb(WOLFSSL_CTX* ctx, CallbackEccSign cb);
 9612
 9613/*!
 9614    \brief Allows caller to set the Public Key Ecc Signing Callback
 9615    Context to ctx.
 9616
 9617    \return none No returns.
 9618
 9619    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9620    \param ctx a pointer to the user context to be stored
 9621
 9622    _Example_
 9623    \code
 9624    none
 9625    \endcode
 9626
 9627    \sa wolfSSL_CTX_SetEccSignCb
 9628    \sa wolfSSL_GetEccSignCtx
 9629*/
 9630void  wolfSSL_SetEccSignCtx(WOLFSSL* ssl, void *ctx);
 9631
 9632/*!
 9633    \brief Allows caller to retrieve the Public Key Ecc Signing Callback
 9634    Context previously stored with wolfSSL_SetEccSignCtx().
 9635
 9636    \return pointer If successful the call will return a valid pointer
 9637    to the context.
 9638    \return NULL will be returned for a blank context.
 9639
 9640    \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new().
 9641
 9642    _Example_
 9643    \code
 9644    none
 9645    \endcode
 9646
 9647    \sa wolfSSL_CTX_SetEccSignCb
 9648    \sa wolfSSL_SetEccSignCtx
 9649*/
 9650void* wolfSSL_GetEccSignCtx(WOLFSSL* ssl);
 9651
 9652/*!
 9653    \brief Allows caller to set the Public Key Ecc Signing Callback
 9654    Context to ctx.
 9655
 9656    \return none No returns.
 9657
 9658    \param ctx a pointer to a WOLFSSL_CTX structure, created
 9659    with wolfSSL_CTX_new().
 9660    \param ctx a pointer to the user context to be stored
 9661
 9662    _Example_
 9663    \code
 9664    none
 9665    \endcode
 9666
 9667    \sa wolfSSL_CTX_SetEccSignCb
 9668    \sa wolfSSL_CTX_GetEccSignCtx
 9669*/
 9670void  wolfSSL_CTX_SetEccSignCtx(WOLFSSL_CTX* ctx, void *userCtx);
 9671
 9672/*!
 9673    \brief Allows caller to retrieve the Public Key Ecc Signing Callback
 9674    Context previously stored with wolfSSL_SetEccSignCtx().
 9675
 9676    \return pointer If successful the call will return a valid pointer
 9677    to the context.
 9678    \return NULL will be returned for a blank context.
 9679
 9680    \param ctx a pointer to a WOLFSSL_CTX structure, created
 9681    with wolfSSL_CTX_new().
 9682
 9683    _Example_
 9684    \code
 9685    none
 9686    \endcode
 9687
 9688    \sa wolfSSL_CTX_SetEccSignCb
 9689    \sa wolfSSL_CTX_SetEccSignCtx
 9690*/
 9691void* wolfSSL_CTX_GetEccSignCtx(WOLFSSL_CTX* ctx);
 9692
 9693/*!
 9694    \brief Allows caller to set the Public Key Callback for ECC Verification.
 9695    The callback should return 0 for success or < 0 for an error.
 9696    The ssl and ctx pointers are available for the user’s convenience.
 9697    sig is the signature to verify and sigSz denotes the length of the
 9698    signature. hash is an input buffer containing the digest of the message
 9699    and hashSz denotes the length in bytes of the hash.  result is an output
 9700    variable where the result of the verification should be stored, 1 for
 9701    success and 0 for failure.  keyDer is the ECC Private key in ASN1
 9702    format and keySz is the length of the key in bytes.  An example
 9703    callback can be found wolfssl/test.h myEccVerify().
 9704
 9705    \return none No returns.
 9706
 9707    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9708    \param cb callback function to register for ECC verification.
 9709
 9710    _Example_
 9711    \code
 9712    none
 9713    \endcode
 9714
 9715    \sa wolfSSL_SetEccVerifyCtx
 9716    \sa wolfSSL_GetEccVerifyCtx
 9717*/
 9718void  wolfSSL_CTX_SetEccVerifyCb(WOLFSSL_CTX* ctx, CallbackEccVerify cb);
 9719
 9720/*!
 9721    \brief Allows caller to set the Public Key Ecc Verification Callback
 9722    Context to ctx.
 9723
 9724    \return none No returns.
 9725
 9726    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9727    \param ctx pointer to the user context to be stored.
 9728
 9729    _Example_
 9730    \code
 9731    none
 9732    \endcode
 9733
 9734    \sa wolfSSL_CTX_SetEccVerifyCb
 9735    \sa wolfSSL_GetEccVerifyCtx
 9736*/
 9737void  wolfSSL_SetEccVerifyCtx(WOLFSSL* ssl, void *ctx);
 9738
 9739/*!
 9740    \brief Allows caller to retrieve the Public Key Ecc Verification Callback
 9741    Context previously stored with wolfSSL_SetEccVerifyCtx().
 9742
 9743    \return pointer If successful the call will return a valid pointer to the
 9744    context.
 9745    \return NULL will be returned for a blank context.
 9746
 9747    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9748
 9749    _Example_
 9750    \code
 9751    none
 9752    \endcode
 9753
 9754    \sa wolfSSL_CTX_SetEccVerifyCb
 9755    \sa wolfSSL_SetEccVerifyCtx
 9756*/
 9757void* wolfSSL_GetEccVerifyCtx(WOLFSSL* ssl);
 9758
 9759/*!
 9760    \brief Allows caller to set the Public Key Callback for RSA Signing.
 9761    The callback should return 0 for success or < 0 for an error.
 9762    The ssl and ctx pointers are available for the user’s convenience.
 9763    in is the input buffer to sign while inSz denotes the length of the input.
 9764    out is the output buffer where the result of the signature should be stored.
 9765    outSz is an input/output variable that specifies the size of the output
 9766    buffer upon invocation and the actual size of the signature should be
 9767    stored there before returning.  keyDer is the RSA Private key in ASN1 format
 9768    and keySz is the length of the key in bytes.  An example callback can be
 9769    found wolfssl/test.h myRsaSign().
 9770
 9771    \return none No returns.
 9772
 9773    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9774    \param cb callback function to register for RSA signing.
 9775
 9776    _Example_
 9777    \code
 9778    none
 9779    \endcode
 9780
 9781    \sa wolfSSL_SetRsaSignCtx
 9782    \sa wolfSSL_GetRsaSignCtx
 9783*/
 9784void  wolfSSL_CTX_SetRsaSignCb(WOLFSSL_CTX* ctx, CallbackRsaSign cb);
 9785
 9786/*!
 9787    \brief Allows caller to set the Public Key RSA Signing Callback Context
 9788    to ctx.
 9789
 9790    \return none No Returns.
 9791
 9792    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9793    \param ctx pointer to the user context to be stored.
 9794
 9795    _Example_
 9796    \code
 9797    none
 9798    \endcode
 9799
 9800    \sa wolfSSL_CTX_SetRsaSignCb
 9801    \sa wolfSSL_GetRsaSignCtx
 9802*/
 9803void  wolfSSL_SetRsaSignCtx(WOLFSSL* ssl, void *ctx);
 9804
 9805/*!
 9806    \brief Allows caller to retrieve the Public Key RSA Signing Callback
 9807    Context previously stored with wolfSSL_SetRsaSignCtx().
 9808
 9809    \return pointer If successful the call will return a valid pointer to the
 9810    context.
 9811    \return NULL will be returned for a blank context.
 9812
 9813    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9814
 9815    _Example_
 9816    \code
 9817    none
 9818    \endcode
 9819
 9820    \sa wolfSSL_CTX_SetRsaSignCb
 9821    \sa wolfSSL_SetRsaSignCtx
 9822*/
 9823void* wolfSSL_GetRsaSignCtx(WOLFSSL* ssl);
 9824
 9825/*!
 9826    \brief Allows caller to set the Public Key Callback for RSA Verification.
 9827    The callback should return the number of plaintext bytes for success or
 9828    < 0 for an error.  The ssl and ctx pointers are available for the user’s
 9829    convenience.  sig is the signature to verify and sigSz denotes the length
 9830    of the signature.  out should be set to the beginning of the verification
 9831    buffer after the decryption process and any padding.  keyDer is the RSA
 9832    Public key in ASN1 format and keySz is the length of the key in bytes.
 9833    An example callback can be found wolfssl/test.h myRsaVerify().
 9834
 9835    \return none No returns.
 9836
 9837    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9838    \param cb callback function to register for RSA verification.
 9839
 9840    \sa wolfSSL_SetRsaVerifyCtx
 9841    \sa wolfSSL_GetRsaVerifyCtx
 9842*/
 9843void  wolfSSL_CTX_SetRsaVerifyCb(WOLFSSL_CTX* ctx, CallbackRsaVerify cb);
 9844
 9845/*!
 9846    \brief Allows caller to set the Public Key RSA Verification Callback
 9847    Context to ctx.
 9848
 9849    \return none No returns.
 9850
 9851    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9852    \param ctx pointer to the user context to be stored.
 9853
 9854    _Example_
 9855    \code
 9856    none
 9857    \endcode
 9858
 9859    \sa wolfSSL_CTX_SetRsaVerifyCb
 9860    \sa wolfSSL_GetRsaVerifyCtx
 9861*/
 9862void  wolfSSL_SetRsaVerifyCtx(WOLFSSL* ssl, void *ctx);
 9863
 9864/*!
 9865    \brief Allows caller to retrieve the Public Key RSA Verification Callback
 9866    Context previously stored with wolfSSL_SetRsaVerifyCtx().
 9867
 9868    \return pointer If successful the call will return a valid pointer to
 9869    the context.
 9870    \return NULL will be returned for a blank context.
 9871
 9872    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9873
 9874    _Example_
 9875    \code
 9876    none
 9877    \endcode
 9878
 9879    \sa wolfSSL_CTX_SetRsaVerifyCb
 9880    \sa wolfSSL_SetRsaVerifyCtx
 9881*/
 9882void* wolfSSL_GetRsaVerifyCtx(WOLFSSL* ssl);
 9883
 9884/*!
 9885    \brief Allows caller to set the Public Key Callback for RSA Public
 9886    Encrypt.  The callback should return 0 for success or < 0 for an error.
 9887    The ssl and ctx pointers are available for the user’s convenience.
 9888    in is the input buffer to encrypt while inSz denotes the length of
 9889    the input.  out is the output buffer where the result of the encryption
 9890    should be stored.  outSz is an input/output variable that specifies
 9891    the size of the output buffer upon invocation and the actual size of
 9892    the encryption should be stored there before returning.  keyDer is the
 9893    RSA Public key in ASN1 format and keySz is the length of the key in
 9894    bytes. An example callback can be found wolfssl/test.h myRsaEnc().
 9895
 9896    \return none No returns.
 9897
 9898    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9899    \param cb callback function to register for RSA public encrypt.
 9900
 9901    _Examples_
 9902    \code
 9903    none
 9904    \endcode
 9905
 9906    \sa wolfSSL_SetRsaEncCtx
 9907    \sa wolfSSL_GetRsaEncCtx
 9908*/
 9909void  wolfSSL_CTX_SetRsaEncCb(WOLFSSL_CTX* ctx, CallbackRsaEnc cb);
 9910
 9911/*!
 9912    \brief Allows caller to set the Public Key RSA Public Encrypt
 9913    Callback Context to ctx.
 9914
 9915    \return none No returns.
 9916
 9917    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9918    \param ctx pointer to the user context to be stored.
 9919
 9920    _Example_
 9921    \code
 9922    none
 9923    \endcode
 9924
 9925    \sa wolfSSL_CTX_SetRsaEncCb
 9926    \sa wolfSSL_GetRsaEncCtx
 9927*/
 9928void  wolfSSL_SetRsaEncCtx(WOLFSSL* ssl, void *ctx);
 9929
 9930/*!
 9931    \brief Allows caller to retrieve the Public Key RSA Public Encrypt
 9932    Callback Context previously stored with wolfSSL_SetRsaEncCtx().
 9933
 9934    \return pointer If successful the call will return a valid pointer
 9935    to the context.
 9936    \return NULL will be returned for a blank context.
 9937
 9938    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9939
 9940    _Example_
 9941    \code
 9942    none
 9943    \endcode
 9944
 9945    \sa wolfSSL_CTX_SetRsaEncCb
 9946    \sa wolfSSL_SetRsaEncCtx
 9947*/
 9948void* wolfSSL_GetRsaEncCtx(WOLFSSL* ssl);
 9949
 9950/*!
 9951    \brief Allows caller to set the Public Key Callback for RSA Private
 9952    Decrypt.  The callback should return the number of plaintext bytes
 9953    for success or < 0 for an error.  The ssl and ctx pointers are available
 9954    for the user’s convenience.  in is the input buffer to decrypt and inSz
 9955    denotes the length of the input.  out should be set to the beginning
 9956    of the decryption buffer after the decryption process and any padding.
 9957    keyDer is the RSA Private key in ASN1 format and keySz is the length
 9958    of the key in bytes.  An example callback can be found
 9959    wolfssl/test.h myRsaDec().
 9960
 9961    \return none No returns.
 9962
 9963    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
 9964    \param cb callback function to register for RSA private decrypt.
 9965
 9966    _Example_
 9967    \code
 9968    none
 9969    \endcode
 9970
 9971    \sa wolfSSL_SetRsaDecCtx
 9972    \sa wolfSSL_GetRsaDecCtx
 9973*/
 9974void  wolfSSL_CTX_SetRsaDecCb(WOLFSSL_CTX* ctx, CallbackRsaDec cb);
 9975
 9976/*!
 9977    \brief Allows caller to set the Public Key RSA Private Decrypt
 9978    Callback Context to ctx.
 9979
 9980    \return none No returns.
 9981
 9982    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
 9983    \param ctx pointer to the user context to be stored.
 9984
 9985    _Example_
 9986    \code
 9987    none
 9988    \endcode
 9989
 9990    \sa wolfSSL_CTX_SetRsaDecCb
 9991    \sa wolfSSL_GetRsaDecCtx
 9992*/
 9993void  wolfSSL_SetRsaDecCtx(WOLFSSL* ssl, void *ctx);
 9994
 9995/*!
 9996    \brief Allows caller to retrieve the Public Key RSA Private Decrypt
 9997    Callback Context previously stored with wolfSSL_SetRsaDecCtx().
 9998
 9999    \return pointer If successful the call will return a valid pointer
10000    to the context.
10001    \return NULL will be returned for a blank context.
10002
10003    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
10004
10005    _Example_
10006    \code
10007    none
10008    \endcode
10009
10010    \sa wolfSSL_CTX_SetRsaDecCb
10011    \sa wolfSSL_SetRsaDecCtx
10012*/
10013void* wolfSSL_GetRsaDecCtx(WOLFSSL* ssl);
10014
10015/*!
10016    \brief This function registers a callback with the SSL context
10017    (WOLFSSL_CTX) to be called when a new CA certificate is loaded
10018    into wolfSSL.  The callback is given a buffer with the DER-encoded
10019    certificate.
10020
10021    \return none No return.
10022
10023    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
10024    \param cb function to be registered as the CA callback for the
10025    wolfSSL context, ctx. The signature of this function must follow that
10026    as shown above in the Synopsis section.
10027
10028    _Example_
10029    \code
10030    WOLFSSL_CTX* ctx = 0;
10031
10032    // CA callback prototype
10033    int MyCACallback(unsigned char *der, int sz, int type);
10034
10035    // Register the custom CA callback with the SSL context
10036    wolfSSL_CTX_SetCACb(ctx, MyCACallback);
10037
10038    int MyCACallback(unsigned char* der, int sz, int type)
10039    {
10040    	// custom CA callback function, DER-encoded cert
10041        // located in “der” of size “sz” with type “type”
10042    }
10043    \endcode
10044
10045    \sa wolfSSL_CTX_load_verify_locations
10046*/
10047void wolfSSL_CTX_SetCACb(WOLFSSL_CTX* ctx, CallbackCACache cb);
10048
10049/*!
10050    \ingroup CertManager
10051    \brief Allocates and initializes a new Certificate Manager context.
10052    This context may be used independent of SSL needs.  It may be used to
10053    load certificates, verify certificates, and check the revocation status.
10054
10055    \return WOLFSSL_CERT_MANAGER If successful the call will return a valid
10056    WOLFSSL_CERT_MANAGER pointer.
10057    \return NULL will be returned for an error state.
10058
10059    \param heap pointer to a heap hint for memory allocation.
10060
10061    \sa wolfSSL_CertManagerFree
10062*/
10063WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew_ex(void* heap);
10064
10065/*!
10066    \ingroup CertManager
10067    \brief Allocates and initializes a new Certificate Manager context.
10068    This context may be used independent of SSL needs.  It may be used to
10069    load certificates, verify certificates, and check the revocation status.
10070
10071    \return WOLFSSL_CERT_MANAGER If successful the call will return a
10072    valid WOLFSSL_CERT_MANAGER pointer.
10073    \return NULL will be returned for an error state.
10074
10075    \param none No parameters.
10076
10077    _Example_
10078    \code
10079    #import <wolfssl/ssl.h>
10080
10081    WOLFSSL_CERT_MANAGER* cm;
10082    cm = wolfSSL_CertManagerNew();
10083    if (cm == NULL) {
10084	// error creating new cert manager
10085    }
10086    \endcode
10087
10088    \sa wolfSSL_CertManagerFree
10089*/
10090WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew(void);
10091
10092/*!
10093    \ingroup CertManager
10094    \brief Frees all resources associated with the Certificate Manager
10095    context.  Call this when you no longer need to use the Certificate Manager.
10096
10097    \return none
10098
10099    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10100    wolfSSL_CertManagerNew().
10101
10102    _Example_
10103    \code
10104    #include <wolfssl/ssl.h>
10105
10106    WOLFSSL_CERT_MANAGER* cm;
10107    ...
10108    wolfSSL_CertManagerFree(cm);
10109    \endcode
10110
10111    \sa wolfSSL_CertManagerNew
10112*/
10113void wolfSSL_CertManagerFree(WOLFSSL_CERT_MANAGER* cm);
10114
10115/*!
10116    \ingroup CertManager
10117    \brief Specifies the locations for CA certificate loading into the
10118    manager context.  The PEM certificate CAfile may contain several
10119    trusted CA certificates.  If CApath is not NULL it specifies a
10120    directory containing CA certificates in PEM format.
10121
10122    \return SSL_SUCCESS If successful the call will return.
10123    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
10124    \return SSL_BAD_FILE will be returned if the file doesn’t exist,
10125    can’t be read, or is corrupted.
10126    \return MEMORY_E will be returned if an out of memory condition occurs.
10127    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
10128    \return BAD_FUNC_ARG is the error that will be returned if a
10129    pointer is not provided.
10130    \return SSL_FATAL_ERROR - will be returned upon failure.
10131
10132    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created
10133    using wolfSSL_CertManagerNew().
10134    \param file pointer to the name of the file containing CA
10135    certificates to load.
10136    \param path pointer to the name of a directory path containing CA c
10137    ertificates to load.  The NULL pointer may be used if no
10138    certificate directory is desired.
10139
10140    _Example_
10141    \code
10142    #include <wolfssl/ssl.h>
10143
10144    int ret = 0;
10145    WOLFSSL_CERT_MANAGER* cm;
10146    ...
10147    ret = wolfSSL_CertManagerLoadCA(cm, “path/to/cert-file.pem”, 0);
10148    if (ret != SSL_SUCCESS) {
10149	// error loading CA certs into cert manager
10150    }
10151    \endcode
10152
10153    \sa wolfSSL_CertManagerVerify
10154*/
10155int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER* cm, const char* f,
10156                                                                 const char* d);
10157
10158/*!
10159    \ingroup CertManager
10160    \brief Loads the CA Buffer by calling wolfSSL_CTX_load_verify_buffer and
10161    returning that result using a temporary cm so as not to lose the information
10162    in the cm passed into the function.
10163
10164    \return SSL_FATAL_ERROR is returned if the WOLFSSL_CERT_MANAGER struct is
10165    NULL or if wolfSSL_CTX_new() returns NULL.
10166    \return SSL_SUCCESS is returned for a successful execution.
10167
10168    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10169    wolfSSL_CertManagerNew().
10170    \param in buffer for cert information.
10171    \param sz length of the buffer.
10172    \param format certificate format, either PEM or DER.
10173
10174    _Example_
10175    \code
10176    WOLFSSL_CERT_MANAGER* cm = (WOLFSSL_CERT_MANAGER*)vp;
10177    …
10178    const unsigned char* in;
10179    long sz;
10180    int format;
10181    …
10182    if(wolfSSL_CertManagerLoadCABuffer(vp, sz, format) != SSL_SUCCESS){
10183	    Error returned. Failure case code block.
10184    }
10185    \endcode
10186
10187    \sa wolfSSL_CTX_load_verify_buffer
10188    \sa ProcessChainBuffer
10189    \sa ProcessBuffer
10190    \sa cm_pick_method
10191*/
10192int wolfSSL_CertManagerLoadCABuffer(WOLFSSL_CERT_MANAGER* cm,
10193                                  const unsigned char* buff, long sz,
10194                                  int format);
10195
10196/*!
10197    \ingroup CertManager
10198    \brief This function unloads the CA signer list.
10199
10200    \return SSL_SUCCESS returned on successful execution of the function.
10201    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
10202    \return BAD_MUTEX_E returned if there was a mutex error.
10203
10204    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure,
10205    created using wolfSSL_CertManagerNew().
10206
10207    _Example_
10208    \code
10209    #include <wolfssl/ssl.h>
10210
10211    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
10212    WOLFSSL_CERT_MANAGER* cm = wolfSSL_CTX_GetCertManager(ctx);
10213    ...
10214    if(wolfSSL_CertManagerUnloadCAs(cm) != SSL_SUCCESS){
10215        Failure case.
10216    }
10217    \endcode
10218
10219    \sa UnlockMutex
10220*/
10221int wolfSSL_CertManagerUnloadCAs(WOLFSSL_CERT_MANAGER* cm);
10222
10223/*!
10224    \ingroup CertManager
10225    \brief This function unloads intermediate certificates add to the CA
10226    signer list.
10227
10228    \return SSL_SUCCESS returned on successful execution of the function.
10229    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
10230    \return BAD_MUTEX_E returned if there was a mutex error.
10231
10232    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure,
10233    created using wolfSSL_CertManagerNew().
10234
10235    _Example_
10236    \code
10237    #include <wolfssl/ssl.h>
10238
10239    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
10240    WOLFSSL_CERT_MANAGER* cm = wolfSSL_CTX_GetCertManager(ctx);
10241    ...
10242    if(wolfSSL_CertManagerUnloadIntermediateCerts(cm) != SSL_SUCCESS){
10243    	Failure case.
10244    }
10245    \endcode
10246
10247    \sa UnlockMutex
10248*/
10249int wolfSSL_CertManagerUnloadIntermediateCerts(WOLFSSL_CERT_MANAGER* cm);
10250
10251/*!
10252    \ingroup CertManager
10253    \brief The function will free the Trusted Peer linked list and unlocks
10254    the trusted peer list.
10255
10256    \return SSL_SUCCESS if the function completed normally.
10257    \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL.
10258    \return BAD_MUTEX_E mutex  error if tpLock, a member of the
10259    WOLFSSL_CERT_MANAGER struct, is 0 (nill).
10260
10261    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10262    wolfSSL_CertManagerNew().
10263
10264    _Example_
10265    \code
10266    #include <wolfssl/ssl.h>
10267
10268    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(Protocol define);
10269    WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
10270    ...
10271    if(wolfSSL_CertManagerUnload_trust_peers(cm) != SSL_SUCCESS){
10272	    The function did not execute successfully.
10273    }
10274    \endcode
10275
10276    \sa UnLockMutex
10277*/
10278int wolfSSL_CertManagerUnload_trust_peers(WOLFSSL_CERT_MANAGER* cm);
10279
10280/*!
10281    \ingroup CertManager
10282    \brief Specifies the certificate to verify with the Certificate Manager
10283    context.  The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.
10284
10285    \return SSL_SUCCESS If successful.
10286    \return ASN_SIG_CONFIRM_E will be returned if the signature could not be
10287    verified.
10288    \return ASN_SIG_OID_E will be returned if the signature type is not
10289    supported.
10290    \return CRL_CERT_REVOKED is an error that is returned if this certificate
10291    has been revoked.
10292    \return CRL_MISSING is an error that is returned if a current issuer CRL is
10293    not available.
10294    \return ASN_BEFORE_DATE_E will be returned if the current date is before the
10295    before date.
10296    \return ASN_AFTER_DATE_E will be returned if the current date is after the
10297    after date.
10298    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
10299    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be
10300    read, or is corrupted.
10301    \return MEMORY_E will be returned if an out of memory condition occurs.
10302    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
10303    \return BAD_FUNC_ARG is the error that will be returned if a pointer is
10304    not provided.
10305
10306    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10307    wolfSSL_CertManagerNew().
10308    \param fname pointer to the name of the file containing the certificates
10309    to verify.
10310    \param format format of the certificate to verify - either
10311    SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
10312
10313    _Example_
10314    \code
10315    int ret = 0;
10316    WOLFSSL_CERT_MANAGER* cm;
10317    ...
10318
10319    ret = wolfSSL_CertManagerVerify(cm, “path/to/cert-file.pem”,
10320    SSL_FILETYPE_PEM);
10321    if (ret != SSL_SUCCESS) {
10322	    error verifying certificate
10323    }
10324    \endcode
10325
10326    \sa wolfSSL_CertManagerLoadCA
10327    \sa wolfSSL_CertManagerVerifyBuffer
10328*/
10329int wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANAGER* cm, const char* f,
10330                                                                    int format);
10331
10332/*!
10333    \ingroup CertManager
10334    \brief Specifies the certificate buffer to verify with the Certificate
10335    Manager context.  The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.
10336
10337    \return SSL_SUCCESS If successful.
10338    \return ASN_SIG_CONFIRM_E will be returned if the signature could not
10339    be verified.
10340    \return ASN_SIG_OID_E will be returned if the signature type is not
10341    supported.
10342    \return CRL_CERT_REVOKED is an error that is returned if this certificate
10343    has been revoked.
10344    \return CRL_MISSING is an error that is returned if a current issuer CRL
10345    is not available.
10346    \return ASN_BEFORE_DATE_E will be returned if the current date is before
10347    the before date.
10348    \return ASN_AFTER_DATE_E will be returned if the current date is after
10349    the after date.
10350    \return SSL_BAD_FILETYPE will be returned if the file is the wrong format.
10351    \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t
10352    be read, or is corrupted.
10353    \return MEMORY_E will be returned if an out of memory condition occurs.
10354    \return ASN_INPUT_E will be returned if Base16 decoding fails on the file.
10355    \return BAD_FUNC_ARG is the error that will be returned if a pointer
10356    is not provided.
10357
10358    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10359    wolfSSL_CertManagerNew().
10360    \param buff buffer containing the certificates to verify.
10361    \param sz size of the buffer, buf.
10362    \param format format of the certificate to verify, located in buf - either
10363    SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
10364
10365    _Example_
10366    \code
10367    #include <wolfssl/ssl.h>
10368
10369    int ret = 0;
10370    int sz = 0;
10371    WOLFSSL_CERT_MANAGER* cm;
10372    byte certBuff[...];
10373    ...
10374
10375    ret = wolfSSL_CertManagerVerifyBuffer(cm, certBuff, sz, SSL_FILETYPE_PEM);
10376    if (ret != SSL_SUCCESS) {
10377    	error verifying certificate
10378    }
10379
10380    \endcode
10381
10382    \sa wolfSSL_CertManagerLoadCA
10383    \sa wolfSSL_CertManagerVerify
10384*/
10385int wolfSSL_CertManagerVerifyBuffer(WOLFSSL_CERT_MANAGER* cm,
10386                                const unsigned char* buff, long sz, int format);
10387
10388/*!
10389    \ingroup CertManager
10390    \brief The function sets the verifyCallback function in the Certificate
10391    Manager. If present, it will be called for each cert loaded. If there is
10392    a verification error, the verify callback can be used to over-ride the
10393    error.
10394
10395    \return none No return.
10396
10397    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10398    wolfSSL_CertManagerNew().
10399    \param verify_callback a VerifyCallback function pointer to the callback
10400    routine
10401
10402    _Example_
10403    \code
10404    #include <wolfssl/ssl.h>
10405
10406    int myVerify(int preverify, WOLFSSL_X509_STORE_CTX* store)
10407    { // do custom verification of certificate }
10408
10409    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(Protocol define);
10410    WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
10411    ...
10412    wolfSSL_CertManagerSetVerify(cm, myVerify);
10413
10414    \endcode
10415
10416    \sa wolfSSL_CertManagerVerify
10417*/
10418void wolfSSL_CertManagerSetVerify(WOLFSSL_CERT_MANAGER* cm,
10419        VerifyCallback verify_callback);
10420
10421/*!
10422    \brief Check CRL if the option is enabled and compares the cert to the
10423    CRL list.
10424
10425    \return SSL_SUCCESS returns if the function returned as expected. If
10426    the crlEnabled member of the WOLFSSL_CERT_MANAGER struct is turned on.
10427    \return MEMORY_E returns if the allocated memory failed.
10428    \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL.
10429
10430    \param cm a pointer to a WOLFSSL_CERT_MANAGER struct.
10431    \param der pointer to a DER formatted certificate.
10432    \param sz size of the certificate.
10433
10434    _Example_
10435    \code
10436    WOLFSSL_CERT_MANAGER* cm;
10437    byte* der;
10438    int sz; // size of der
10439    ...
10440    if(wolfSSL_CertManagerCheckCRL(cm, der, sz) != SSL_SUCCESS){
10441    	// Error returned. Deal with failure case.
10442    }
10443    \endcode
10444
10445    \sa CheckCertCRL
10446    \sa ParseCertRelative
10447    \sa wolfSSL_CertManagerSetCRL_CB
10448    \sa InitDecodedCert
10449*/
10450int wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER* cm,
10451                                const unsigned char* der, int sz);
10452
10453/*!
10454    \ingroup CertManager
10455    \brief Turns on Certificate Revocation List checking when verifying
10456    certificates with the Certificate Manager.  By default, CRL checking
10457    is off.  options include WOLFSSL_CRL_CHECKALL which performs CRL
10458    checking on each certificate in the chain versus the Leaf certificate
10459    only which is the default.
10460
10461    \return SSL_SUCCESS If successful the call will return.
10462    \return NOT_COMPILED_IN will be returned if wolfSSL was not built with
10463    CRL enabled.
10464    \return MEMORY_E will be returned if an out of memory condition occurs.
10465    \return BAD_FUNC_ARG is the error that will be returned if a pointer
10466    is not provided.
10467    \return SSL_FAILURE will be returned if the CRL context cannot be
10468    initialized properly.
10469
10470    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10471    wolfSSL_CertManagerNew().
10472    \param options options to use when enabling the Certification Manager, cm.
10473
10474    _Example_
10475    \code
10476    #include <wolfssl/ssl.h>
10477
10478    int ret = 0;
10479    WOLFSSL_CERT_MANAGER* cm;
10480    ...
10481
10482    ret = wolfSSL_CertManagerEnableCRL(cm, 0);
10483    if (ret != SSL_SUCCESS) {
10484    	error enabling cert manager
10485    }
10486
10487    ...
10488    \endcode
10489
10490    \sa wolfSSL_CertManagerDisableCRL
10491*/
10492int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER* cm,
10493                                                                   int options);
10494
10495/*!
10496    \ingroup CertManager
10497    \brief Turns off Certificate Revocation List checking when verifying
10498    certificates with the Certificate Manager.  By default, CRL checking is
10499    off.  You can use this function to temporarily or permanently disable CRL
10500    checking with this Certificate Manager context that previously had CRL
10501    checking enabled.
10502
10503    \return SSL_SUCCESS If successful the call will return.
10504    \return BAD_FUNC_ARG is the error that will be returned if a function
10505    pointer is not provided.
10506
10507    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10508    wolfSSL_CertManagerNew().
10509
10510    _Example_
10511    \code
10512    #include <wolfssl/ssl.h>
10513
10514    int ret = 0;
10515    WOLFSSL_CERT_MANAGER* cm;
10516    ...
10517    ret = wolfSSL_CertManagerDisableCRL(cm);
10518    if (ret != SSL_SUCCESS) {
10519    	error disabling cert manager
10520    }
10521    ...
10522    \endcode
10523
10524    \sa wolfSSL_CertManagerEnableCRL
10525*/
10526int wolfSSL_CertManagerDisableCRL(WOLFSSL_CERT_MANAGER* cm);
10527
10528/*!
10529    \ingroup CertManager
10530    \brief Error checks and passes through to LoadCRL() in order to load the
10531    cert into the CRL for revocation checking. An updated CRL can be loaded by
10532    first calling wolfSSL_CertManagerFreeCRL, then loading the new CRL.
10533
10534    \return SSL_SUCCESS if there is no error in wolfSSL_CertManagerLoadCRL and
10535    if LoadCRL returns successfully.
10536    \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER struct is NULL.
10537    \return SSL_FATAL_ERROR if wolfSSL_CertManagerEnableCRL returns anything
10538    other than SSL_SUCCESS.
10539    \return BAD_PATH_ERROR if the path is NULL.
10540    \return MEMORY_E if LoadCRL fails to allocate heap memory.
10541
10542    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10543    wolfSSL_CertManagerNew().
10544    \param path a constant char pointer holding the CRL path.
10545    \param type type of certificate to be loaded.
10546    \param monitor requests monitoring in LoadCRL().
10547
10548    _Example_
10549    \code
10550    #include <wolfssl/ssl.h>
10551
10552    int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type,
10553    int monitor);
10554    …
10555    wolfSSL_CertManagerLoadCRL(SSL_CM(ssl), path, type, monitor);
10556    \endcode
10557
10558    \sa wolfSSL_CertManagerEnableCRL
10559    \sa wolfSSL_LoadCRL
10560    \sa wolfSSL_CertManagerFreeCRL
10561*/
10562int wolfSSL_CertManagerLoadCRL(WOLFSSL_CERT_MANAGER* cm,
10563                               const char* path, int type, int monitor);
10564
10565/*!
10566    \ingroup CertManager
10567    \brief The function loads the CRL file by calling BufferLoadCRL.
10568
10569    \return SSL_SUCCESS returned if the function completed without errors.
10570    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
10571    \return SSL_FATAL_ERROR returned if there is an error associated
10572    with the WOLFSSL_CERT_MANAGER.
10573
10574    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure.
10575    \param buff a constant byte type and is the buffer.
10576    \param sz a long int representing the size of the buffer.
10577    \param type a long integer that holds the certificate type.
10578
10579    _Example_
10580    \code
10581    #include <wolfssl/ssl.h>
10582
10583    WOLFSSL_CERT_MANAGER* cm;
10584    const unsigned char* buff;
10585    long sz; size of buffer
10586    int type;  cert type
10587    ...
10588    int ret = wolfSSL_CertManagerLoadCRLBuffer(cm, buff, sz, type);
10589    if(ret == SSL_SUCCESS){
10590	return ret;
10591    } else {
10592    	Failure case.
10593    }
10594    \endcode
10595
10596    \sa BufferLoadCRL
10597    \sa wolfSSL_CertManagerEnableCRL
10598*/
10599int wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER* cm,
10600                                     const unsigned char* buff, long sz,
10601                                     int type);
10602
10603/*!
10604    \ingroup CertManager
10605    \brief This function sets the CRL Certificate Manager callback. If
10606    HAVE_CRL is defined and a matching CRL record is not found then the
10607    cbMissingCRL is called (set via wolfSSL_CertManagerSetCRL_Cb). This
10608    allows you to externally retrieve the CRL and load it.
10609
10610    \return SSL_SUCCESS returned upon successful execution of the function and
10611    subroutines.
10612    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.
10613
10614    \param cm the WOLFSSL_CERT_MANAGER structure holding the information for
10615    the certificate.
10616    \param cb a function pointer to (*CbMissingCRL) that is set to the
10617    cbMissingCRL member of the WOLFSSL_CERT_MANAGER.
10618
10619    _Example_
10620    \code
10621    #include <wolfssl/ssl.h>
10622
10623    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
10624    WOLFSSL* ssl = wolfSSL_new(ctx);
10625    …
10626    void cb(const char* url){
10627	    Function body.
10628    }
10629    …
10630    CbMissingCRL cb = CbMissingCRL;
10631    …
10632    if(ctx){
10633        return wolfSSL_CertManagerSetCRL_Cb(SSL_CM(ssl), cb);
10634    }
10635    \endcode
10636
10637    \sa CbMissingCRL
10638    \sa wolfSSL_SetCRL_Cb
10639*/
10640int wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER* cm,
10641                                 CbMissingCRL cb);
10642
10643/*!
10644    \ingroup CertManager
10645    \brief This function sets the CRL Update callback. If
10646    HAVE_CRL and HAVE_CRL_UPDATE_CB is defined , and an entry with the same
10647    issuer and a lower CRL number exists when a CRL is added, then the
10648    CbUpdateCRL is called with the details of the existing entry and the
10649    new one replacing it.
10650
10651    \return SSL_SUCCESS returned upon successful execution of the function and
10652    subroutines.
10653    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.
10654
10655    \param cm the WOLFSSL_CERT_MANAGER structure holding the information for
10656    the certificate.
10657    \param cb a function pointer to (*CbUpdateCRL) that is set to the
10658    cbUpdateCRL member of the WOLFSSL_CERT_MANAGER.
10659    Signature requirement:
10660	void (*CbUpdateCRL)(CrlInfo *old, CrlInfo *new);
10661
10662    _Example_
10663    \code
10664    #include <wolfssl/ssl.h>
10665
10666    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
10667    WOLFSSL* ssl = wolfSSL_new(ctx);
10668    …
10669    void cb(CrlInfo *old, CrlInfo *new){
10670	    Function body.
10671    }
10672    …
10673    CbUpdateCRL cb = CbUpdateCRL;
10674    …
10675    if(ctx){
10676        return wolfSSL_CertManagerSetCRLUpdate_Cb(SSL_CM(ssl), cb);
10677    }
10678    \endcode
10679
10680    \sa CbUpdateCRL
10681*/
10682int wolfSSL_CertManagerSetCRLUpdate_Cb(WOLFSSL_CERT_MANAGER* cm,
10683                                       CbUpdateCRL cb);
10684
10685/*!
10686    \ingroup CertManager
10687    \brief This function yields a structure with parsed CRL information from
10688    an encoded CRL buffer.
10689
10690    \return SSL_SUCCESS returned upon successful execution of the function and
10691    subroutines.
10692    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.
10693
10694    \param cm   the WOLFSSL_CERT_MANAGER structure..
10695    \param info pointer to caller managed CrlInfo structure that will receive
10696                the CRL information.
10697    \param buff input buffer containing encoded CRL.
10698    \param sz   the length in bytes of the input CRL data in buff.
10699    \param type WOLFSSL_FILETYPE_PEM or WOLFSSL_FILETYPE_DER
10700
10701    _Example_
10702    \code
10703    #include <wolfssl/ssl.h>
10704
10705    CrlInfo info;
10706    WOLFSSL_CERT_MANAGER* cm = NULL;
10707
10708    cm = wolfSSL_CertManagerNew();
10709
10710    // Read crl data from file into buffer
10711
10712    wolfSSL_CertManagerGetCRLInfo(cm, &info, crlData, crlDataLen,
10713                                  WOLFSSL_FILETYPE_PEM);
10714    \endcode
10715
10716    \sa CbUpdateCRL
10717    \sa wolfSSL_SetCRL_Cb
10718*/
10719int wolfSSL_CertManagerGetCRLInfo(WOLFSSL_CERT_MANAGER* cm, CrlInfo* info,
10720    const byte* buff, long sz, int type)
10721
10722/*!
10723    \ingroup CertManager
10724    \brief This function frees the CRL stored in the Cert Manager. An
10725    application can update the CRL by calling wolfSSL_CertManagerFreeCRL
10726    and then loading the new CRL.
10727
10728    \return SSL_SUCCESS returned upon successful execution of the function and
10729    subroutines.
10730    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL.
10731
10732    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10733    wolfSSL_CertManagerNew().
10734
10735    _Example_
10736    \code
10737    #include <wolfssl/ssl.h>
10738
10739    const char* crl1     = "./certs/crl/crl.pem";
10740    WOLFSSL_CERT_MANAGER* cm = NULL;
10741
10742    cm = wolfSSL_CertManagerNew();
10743    wolfSSL_CertManagerLoadCRL(cm, crl1, WOLFSSL_FILETYPE_PEM, 0);
10744    …
10745    wolfSSL_CertManagerFreeCRL(cm);
10746    \endcode
10747
10748    \sa wolfSSL_CertManagerLoadCRL
10749*/
10750int wolfSSL_CertManagerFreeCRL(WOLFSSL_CERT_MANAGER* cm);
10751
10752/*!
10753    \ingroup CertManager
10754    \brief The function enables the WOLFSSL_CERT_MANAGER’s member, ocspEnabled
10755    to signify that the OCSP check option is enabled.
10756
10757    \return SSL_SUCCESS returned on successful execution of the function. The
10758    ocspEnabled member of the WOLFSSL_CERT_MANAGER is enabled.
10759    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is
10760    NULL or if an argument value that is not allowed is passed to a subroutine.
10761    \return MEMORY_E returned if there is an error allocating memory within
10762    this function or a subroutine.
10763
10764    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10765    wolfSSL_CertManagerNew().
10766    \param der a byte pointer to the certificate.
10767    \param sz an int type representing the size of the DER cert.
10768
10769    _Example_
10770    \code
10771    #import <wolfssl/ssl.h>
10772
10773    WOLFSSL* ssl = wolfSSL_new(ctx);
10774    byte* der;
10775    int sz; size of der
10776    ...
10777    if(wolfSSL_CertManagerCheckOCSP(cm, der, sz) != SSL_SUCCESS){
10778	 Failure case.
10779    }
10780    \endcode
10781
10782    \sa ParseCertRelative
10783    \sa CheckCertOCSP
10784*/
10785int wolfSSL_CertManagerCheckOCSP(WOLFSSL_CERT_MANAGER* cm,
10786                                const unsigned char* der, int sz);
10787
10788/*!
10789    \ingroup CertManager
10790    \brief Turns on OCSP if it’s turned off and if compiled with the
10791    set option available.
10792
10793    \return SSL_SUCCESS returned if the function call is successful.
10794    \return BAD_FUNC_ARG if cm struct is NULL.
10795    \return MEMORY_E if WOLFSSL_OCSP struct value is NULL.
10796    \return SSL_FAILURE initialization of WOLFSSL_OCSP struct fails
10797    to initialize.
10798    \return NOT_COMPILED_IN build not compiled with correct feature enabled.
10799
10800    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using
10801    wolfSSL_CertManagerNew().
10802    \param options used to set values in WOLFSSL_CERT_MANAGER struct.
10803
10804    _Example_
10805    \code
10806    #include <wolfssl/ssl.h>
10807
10808    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method);
10809    WOLFSSL* ssl = wolfSSL_new(ctx);
10810    WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
10811    int options;
10812    …
10813    if(wolfSSL_CertManagerEnableOCSP(SSL_CM(ssl), options) != SSL_SUCCESS){
10814	    Failure case.
10815    }
10816    \endcode
10817
10818    \sa wolfSSL_CertManagerNew
10819*/
10820int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER* cm,
10821                                                                   int options);
10822
10823/*!
10824    \ingroup CertManager
10825    \brief Disables OCSP certificate revocation.
10826
10827    \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled the
10828    crlEnabled member of the WOLFSSL_CERT_MANAGER structure.
10829    \return BAD_FUNC_ARG the WOLFSSL structure was NULL.
10830
10831    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure.
10832
10833    _Example_
10834    \code
10835    #include <wolfssl/ssl.h>
10836
10837    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(method);
10838    WOLFSSL* ssl = wolfSSL_new(ctx);
10839    ...
10840    if(wolfSSL_CertManagerDisableOCSP(ssl) != SSL_SUCCESS){
10841	    Fail case.
10842    }
10843    \endcode
10844
10845    \sa wolfSSL_DisableCRL
10846*/
10847int wolfSSL_CertManagerDisableOCSP(WOLFSSL_CERT_MANAGER* cm);
10848
10849/*!
10850    \ingroup CertManager
10851    \brief The function copies the url to the ocspOverrideURL member of the
10852    WOLFSSL_CERT_MANAGER structure.
10853
10854    \return SSL_SUCCESS the function was able to execute as expected.
10855    \return BAD_FUNC_ARG the WOLFSSL_CERT_MANAGER struct is NULL.
10856    \return MEMEORY_E Memory was not able to be allocated for the
10857    ocspOverrideURL member of the certificate manager.
10858
10859    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
10860
10861    _Example_
10862    \code
10863    #include <wolfssl/ssl.h>
10864    WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew();
10865    const char* url;
10866    …
10867    int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url)
10868    …
10869    if(wolfSSL_CertManagerSetOCSPOverrideURL(SSL_CM(ssl), url) != SSL_SUCCESS){
10870	    Failure case.
10871    }
10872    \endcode
10873
10874    \sa ocspOverrideURL
10875    \sa wolfSSL_SetOCSP_OverrideURL
10876*/
10877int wolfSSL_CertManagerSetOCSPOverrideURL(WOLFSSL_CERT_MANAGER* cm,
10878                                          const char* url);
10879
10880/*!
10881    \ingroup CertManager
10882    \brief The function sets the OCSP callback in the WOLFSSL_CERT_MANAGER.
10883
10884    \return SSL_SUCCESS returned on successful execution. The arguments are
10885    saved in the WOLFSSL_CERT_MANAGER structure.
10886    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL.
10887
10888    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure.
10889    \param ioCb a function pointer of type CbOCSPIO.
10890    \param respFreeCb - a function pointer of type CbOCSPRespFree.
10891    \param ioCbCtx - a void pointer variable to the I/O callback user
10892    registered context.
10893
10894    _Example_
10895    \code
10896    #include <wolfssl/ssl.h>
10897
10898    wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb,
10899    CbOCSPRespFree respFreeCb, void* ioCbCtx){
10900    …
10901    return wolfSSL_CertManagerSetOCSP_Cb(SSL_CM(ssl), ioCb, respFreeCb, ioCbCtx);
10902    \endcode
10903
10904    \sa wolfSSL_CertManagerSetOCSPOverrideURL
10905    \sa wolfSSL_CertManagerCheckOCSP
10906    \sa wolfSSL_CertManagerEnableOCSPStapling
10907    \sa wolfSSL_EnableOCSP
10908    \sa wolfSSL_DisableOCSP
10909    \sa wolfSSL_SetOCSP_Cb
10910*/
10911int wolfSSL_CertManagerSetOCSP_Cb(WOLFSSL_CERT_MANAGER* cm,
10912                                  CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
10913                                  void* ioCbCtx);
10914
10915/*!
10916    \ingroup CertManager
10917    \brief This function turns on OCSP stapling if it is not turned on as well
10918    as set the options.
10919
10920    \return SSL_SUCCESS returned if there were no errors and the function
10921    executed successfully.
10922    \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is
10923    NULL or otherwise if there was a unpermitted argument value passed to
10924    a subroutine.
10925    \return MEMORY_E returned if there was an issue allocating memory.
10926    \return SSL_FAILURE returned if the initialization of the OCSP
10927    structure failed.
10928    \return NOT_COMPILED_IN returned if wolfSSL was not compiled with
10929    HAVE_CERTIFICATE_STATUS_REQUEST option.
10930
10931    \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, a member of the
10932    WOLFSSL_CTX structure.
10933
10934    _Example_
10935    \code
10936    int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX* ctx){
10937    …
10938    return wolfSSL_CertManagerEnableOCSPStapling(ctx->cm);
10939    \endcode
10940
10941    \sa wolfSSL_CTX_EnableOCSPStapling
10942*/
10943int wolfSSL_CertManagerEnableOCSPStapling(
10944                                                      WOLFSSL_CERT_MANAGER* cm);
10945
10946/*!
10947    \brief Enables CRL certificate revocation.
10948
10949    \return SSL_SUCCESS the function and subroutines returned with no errors.
10950    \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
10951    \return MEMORY_E returned if the allocation of memory failed.
10952    \return SSL_FAILURE returned if the InitCRL function does not return
10953    successfully.
10954    \return NOT_COMPILED_IN HAVE_CRL was not enabled during the compiling.
10955
10956    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
10957    \param options an integer that is used to determine the setting of
10958    crlCheckAll member of the WOLFSSL_CERT_MANAGER structure.
10959
10960    _Example_
10961    \code
10962    WOLFSSL* ssl = wolfSSL_new(ctx);
10963    …
10964    if (wolfSSL_EnableCRL(ssl, WOLFSSL_CRL_CHECKALL) != SSL_SUCCESS){
10965	    // Failure case. SSL_SUCCESS was not returned by this function or
10966    a subroutine
10967    }
10968    \endcode
10969
10970    \sa wolfSSL_CertManagerEnableCRL
10971    \sa InitCRL
10972*/
10973int wolfSSL_EnableCRL(WOLFSSL* ssl, int options);
10974
10975/*!
10976    \brief Disables CRL certificate revocation.
10977
10978    \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled
10979    the crlEnabled member of the WOLFSSL_CERT_MANAGER structure.
10980    \return BAD_FUNC_ARG the WOLFSSL structure was NULL.
10981
10982    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
10983
10984    _Example_
10985    \code
10986    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
10987    WOLFSSL* ssl = wolfSSL_new(ctx);
10988    ...
10989    if(wolfSSL_DisableCRL(ssl) != SSL_SUCCESS){
10990    	// Failure case
10991    }
10992    \endcode
10993
10994    \sa wolfSSL_CertManagerDisableCRL
10995    \sa wolfSSL_CertManagerDisableOCSP
10996*/
10997int wolfSSL_DisableCRL(WOLFSSL* ssl);
10998
10999/*!
11000    \brief A wrapper function that ends up calling LoadCRL to load the
11001    certificate for revocation checking.
11002
11003    \return WOLFSSL_SUCCESS returned if the function and all of the
11004    subroutines executed without error.
11005    \return SSL_FATAL_ERROR returned if one of the subroutines does not
11006    return successfully.
11007    \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER or the WOLFSSL
11008    structure are NULL.
11009
11010    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11011    \param path a constant character pointer that holds the path to the
11012    crl file.
11013    \param type an integer representing the type of certificate.
11014    \param monitor an integer variable used to verify the monitor path if
11015    requested.
11016
11017    _Example_
11018    \code
11019    WOLFSSL* ssl = wolfSSL_new(ctx);
11020    const char* crlPemDir;
11021    …
11022    if(wolfSSL_LoadCRL(ssl, crlPemDir, SSL_FILETYPE_PEM, 0) != SSL_SUCCESS){
11023    	// Failure case. Did not return SSL_SUCCESS.
11024    }
11025    \endcode
11026
11027    \sa wolfSSL_CertManagerLoadCRL
11028    \sa wolfSSL_CertManagerEnableCRL
11029    \sa LoadCRL
11030*/
11031int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type, int monitor);
11032
11033/*!
11034    \brief Sets the CRL callback in the WOLFSSL_CERT_MANAGER structure.
11035
11036    \return SSL_SUCCESS returned if the function or subroutine executes
11037    without error. The cbMissingCRL member of the WOLFSSL_CERT_MANAGER is set.
11038    \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER
11039    structure is NULL.
11040
11041    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11042    \param cb a function pointer to CbMissingCRL.
11043
11044    _Example_
11045    \code
11046    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
11047    WOLFSSL* ssl = wolfSSL_new(ctx);
11048    …
11049    void cb(const char* url) // required signature
11050    {
11051    	// Function body
11052    }
11053    …
11054    int crlCb = wolfSSL_SetCRL_Cb(ssl, cb);
11055    if(crlCb != SSL_SUCCESS){
11056    	// The callback was not set properly
11057    }
11058    \endcode
11059
11060    \sa CbMissingCRL
11061    \sa wolfSSL_CertManagerSetCRL_Cb
11062*/
11063int wolfSSL_SetCRL_Cb(WOLFSSL* ssl, CbMissingCRL cb);
11064
11065/*!
11066    \brief This function enables OCSP certificate verification. The value of
11067    options if formed by or’ing one or more of the following options:
11068    WOLFSSL_OCSP_URL_OVERRIDE - use the override URL instead of the URL in
11069     certificates. The override URL is specified using the
11070     wolfSSL_CTX_SetOCSP_OverrideURL() function.
11071    WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on
11072    WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests
11073
11074    \return SSL_SUCCESS returned if the function and subroutines executes
11075    without errors.
11076    \return BAD_FUNC_ARG returned if an argument in this function or any
11077    subroutine receives an invalid argument value.
11078    \return MEMORY_E returned if there was an error allocating memory for
11079    a structure or other variable.
11080    \return NOT_COMPILED_IN returned if wolfSSL was not compiled with the
11081    HAVE_OCSP option.
11082
11083    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11084    \param options an integer type passed to wolfSSL_CertMangerENableOCSP()
11085    used for settings check.
11086
11087    _Example_
11088    \code
11089    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
11090    WOLFSSL* ssl = wolfSSL_new(ctx);
11091    int options; // initialize to option constant
11092    …
11093    int ret = wolfSSL_EnableOCSP(ssl, options);
11094    if(ret != SSL_SUCCESS){
11095    	// OCSP is not enabled
11096    }
11097    \endcode
11098
11099    \sa wolfSSL_CertManagerEnableOCSP
11100*/
11101int wolfSSL_EnableOCSP(WOLFSSL* ssl, int options);
11102
11103/*!
11104    \brief Disables the OCSP certificate revocation option.
11105
11106    \return SSL_SUCCESS returned if the function and its subroutine return with
11107    no errors. The ocspEnabled member of the WOLFSSL_CERT_MANAGER structure was
11108    successfully set.
11109    \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
11110
11111    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11112
11113    _Example_
11114    \code
11115    WOLFSSL* ssl = wolfSSL_new(ctx);
11116    …
11117    if(wolfSSL_DisableOCSP(ssl) != SSL_SUCCESS){
11118	    // Returned with an error. Failure case in this block.
11119    }
11120    \endcode
11121
11122    \sa wolfSSL_CertManagerDisableOCSP
11123*/
11124int wolfSSL_DisableOCSP(WOLFSSL* ssl);
11125
11126/*!
11127    \brief This function sets the ocspOverrideURL member in the
11128    WOLFSSL_CERT_MANAGER structure.
11129
11130    \return SSL_SUCCESS returned on successful execution of the function.
11131    \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if a
11132    unpermitted argument was passed to a subroutine.
11133    \return MEMORY_E returned if there was an error allocating memory in the
11134    subroutine.
11135
11136    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11137    \param url a constant char pointer to the url that will be stored in the
11138    ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure.
11139
11140    _Example_
11141    \code
11142    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
11143    WOLFSSL* ssl = wolfSSL_new(ctx);
11144    char url[URLSZ];
11145    ...
11146    if(wolfSSL_SetOCSP_OverrideURL(ssl, url)){
11147    	// The override url is set to the new value
11148    }
11149    \endcode
11150
11151    \sa wolfSSL_CertManagerSetOCSPOverrideURL
11152*/
11153int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url);
11154
11155/*!
11156    \brief This function sets the OCSP callback in the
11157    WOLFSSL_CERT_MANAGER structure.
11158
11159    \return SSL_SUCCESS returned if the function executes without error.
11160    The ocspIOCb, ocspRespFreeCb, and ocspIOCtx members of the CM are set.
11161    \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER
11162    structures are NULL.
11163
11164    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11165    \param ioCb a function pointer to type CbOCSPIO.
11166    \param respFreeCb a function pointer to type CbOCSPRespFree which is the
11167    call to free the response memory.
11168    \param ioCbCtx a void pointer that will be held in the ocspIOCtx member
11169    of the CM.
11170
11171    _Example_
11172    \code
11173    WOLFSSL* ssl = wolfSSL_new(ctx);
11174    …
11175    int OCSPIO_CB(void* , const char*, int , unsigned char* , int,
11176    unsigned char**){  // must have this signature
11177    // Function Body
11178    }
11179    …
11180    void OCSPRespFree_CB(void* , unsigned char* ){ // must have this signature
11181    	// function body
11182    }
11183    …
11184    void* ioCbCtx;
11185    CbOCSPRespFree CB_OCSPRespFree;
11186
11187    if(wolfSSL_SetOCSP_Cb(ssl, OCSPIO_CB( pass args ), CB_OCSPRespFree,
11188				ioCbCtx) != SSL_SUCCESS){
11189	    // Callback not set
11190    }
11191    \endcode
11192
11193    \sa wolfSSL_CertManagerSetOCSP_Cb
11194    \sa CbOCSPIO
11195    \sa CbOCSPRespFree
11196*/
11197int wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
11198                       void* ioCbCtx);
11199
11200/*!
11201    \brief Enables CRL certificate verification through the CTX.
11202
11203    \return SSL_SUCCESS returned if this function and it’s subroutines
11204    execute without errors.
11205    \return BAD_FUNC_ARG returned if the CTX struct is NULL or there
11206    was otherwise an invalid argument passed in a subroutine.
11207    \return MEMORY_E returned if there was an error allocating
11208    memory during execution of the function.
11209    \return SSL_FAILURE returned if the crl member of the
11210    WOLFSSL_CERT_MANAGER fails to initialize correctly.
11211    \return NOT_COMPILED_IN wolfSSL was not compiled with the HAVE_CRL option.
11212
11213    \param ctx a pointer to a WOLFSSL_CTX structure, created using
11214    wolfSSL_CTX_new().
11215    \param options option flags for enabling CRL.
11216
11217    _Example_
11218    \code
11219    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
11220    WOLFSSL* ssl = wolfSSL_new(ctx);
11221    ...
11222    if(wolfSSL_CTX_EnableCRL(ssl->ctx, options) != SSL_SUCCESS){
11223    	// The function failed
11224    }
11225    \endcode
11226
11227    \sa wolfSSL_CertManagerEnableCRL
11228    \sa InitCRL
11229    \sa wolfSSL_CTX_DisableCRL
11230*/
11231int wolfSSL_CTX_EnableCRL(WOLFSSL_CTX* ctx, int options);
11232
11233/*!
11234    \brief This function disables CRL verification in the CTX structure.
11235
11236    \return SSL_SUCCESS returned if the function executes without error.
11237    The crlEnabled member of the WOLFSSL_CERT_MANAGER struct is set to 0.
11238    \return BAD_FUNC_ARG returned if either the CTX struct or the CM
11239    struct has a NULL value.
11240
11241    \param ctx a pointer to a WOLFSSL_CTX structure, created using
11242    wolfSSL_CTX_new().
11243
11244    _Example_
11245    \code
11246    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
11247    WOLFSSL* ssl = wolfSSL_new(ctx);
11248    ...
11249    if(wolfSSL_CTX_DisableCRL(ssl->ctx) != SSL_SUCCESS){
11250    	// Failure case.
11251    }
11252    \endcode
11253
11254    \sa wolfSSL_CertManagerDisableCRL
11255*/
11256int wolfSSL_CTX_DisableCRL(WOLFSSL_CTX* ctx);
11257
11258/*!
11259    \brief This function loads CRL into the WOLFSSL_CTX structure through
11260    wolfSSL_CertManagerLoadCRL().
11261
11262    \return SSL_SUCCESS - returned if the function and its subroutines
11263    execute without error.
11264    \return BAD_FUNC_ARG - returned if this function or any subroutines
11265    are passed NULL structures.
11266    \return BAD_PATH_ERROR - returned if the path variable opens as NULL.
11267    \return MEMORY_E - returned if an allocation of memory failed.
11268
11269    \param ctx a pointer to a WOLFSSL_CTX structure, created using
11270    wolfSSL_CTX_new().
11271    \param path the path to the certificate.
11272    \param type an integer variable holding the type of certificate.
11273    \param monitor an integer variable used to determine if the monitor
11274    path is requested.
11275
11276    _Example_
11277    \code
11278    WOLFSSL_CTX* ctx;
11279    const char* path;
11280    …
11281    return wolfSSL_CTX_LoadCRL(ctx, path, SSL_FILETYPE_PEM, 0);
11282    \endcode
11283
11284    \sa wolfSSL_CertManagerLoadCRL
11285    \sa LoadCRL
11286*/
11287int wolfSSL_CTX_LoadCRL(WOLFSSL_CTX* ctx, const char* path, int type, int monitor);
11288
11289/*!
11290    \brief This function will set the callback argument to the cbMissingCRL
11291    member of the WOLFSSL_CERT_MANAGER structure by calling
11292    wolfSSL_CertManagerSetCRL_Cb.
11293
11294    \return SSL_SUCCESS returned for a successful execution. The
11295    WOLFSSL_CERT_MANAGER structure’s member cbMssingCRL was successfully
11296    set to cb.
11297    \return BAD_FUNC_ARG returned if WOLFSSL_CTX or WOLFSSL_CERT_MANAGER
11298    are NULL.
11299
11300    \param ctx a pointer to a WOLFSSL_CTX structure, created with
11301    wolfSSL_CTX_new().
11302    \param cb a pointer to a callback function of type CbMissingCRL.
11303    Signature requirement:
11304	void (*CbMissingCRL)(const char* url);
11305
11306    _Example_
11307    \code
11308    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
11309    …
11310    void cb(const char* url) // Required signature
11311    {
11312    	// Function body
11313    }
11314    …
11315    if (wolfSSL_CTX_SetCRL_Cb(ctx, cb) != SSL_SUCCESS){
11316    	// Failure case, cb was not set correctly.
11317    }
11318    \endcode
11319
11320    \sa wolfSSL_CertManagerSetCRL_Cb
11321    \sa CbMissingCRL
11322*/
11323int wolfSSL_CTX_SetCRL_Cb(WOLFSSL_CTX* ctx, CbMissingCRL cb);
11324
11325/*!
11326    \brief This function sets options to configure behavior of OCSP
11327    functionality in wolfSSL.  The value of options if formed by or’ing
11328    one or more of the following options:
11329    WOLFSSL_OCSP_URL_OVERRIDE - use the override URL instead of the URL in
11330     certificates. The override URL is specified using the
11331     wolfSSL_CTX_SetOCSP_OverrideURL() function.
11332    WOLFSSL_OCSP_CHECKALL - Set all OCSP checks on
11333    WOLFSSL_OCSP_NO_NONCE - Set nonce option for creating OCSP requests
11334
11335    This function only sets the OCSP options when wolfSSL has been compiled with
11336    OCSP support (--enable-ocsp, #define HAVE_OCSP).
11337
11338    \return SSL_SUCCESS is returned upon success.
11339    \return SSL_FAILURE is returned upon failure.
11340    \return NOT_COMPILED_IN is returned when this function has been called,
11341    but OCSP support was not enabled when wolfSSL was compiled.
11342
11343    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
11344    \param options value used to set the OCSP options.
11345
11346    _Example_
11347    \code
11348    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
11349    int options; // initialize to option constant
11350    …
11351    int ret = wolfSSL_CTX_EnableOCSP(ctx, options);
11352    if(ret != SSL_SUCCESS){
11353        // OCSP is not enabled
11354    }
11355    \endcode
11356
11357    \sa wolfSSL_CertManagerEnableOCSP
11358    \sa wolfSSL_EnableOCSP
11359*/
11360int wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX* ctx, int options);
11361
11362/*!
11363    \brief This function disables OCSP certificate revocation checking by
11364    affecting the ocspEnabled member of the WOLFSSL_CERT_MANAGER structure.
11365
11366    \return SSL_SUCCESS returned if the function executes without error.
11367    The ocspEnabled member of the CM has been disabled.
11368    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL.
11369
11370    \param ctx a pointer to a WOLFSSL_CTX structure, created using
11371    wolfSSL_CTX_new().
11372
11373    _Example_
11374    \code
11375    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
11376    WOLFSSL* ssl = wolfSSL_new(ctx);
11377    ...
11378    if(!wolfSSL_CTX_DisableOCSP(ssl->ctx)){
11379    	// OCSP is not disabled
11380    }
11381    \endcode
11382
11383    \sa wolfSSL_DisableOCSP
11384    \sa wolfSSL_CertManagerDisableOCSP
11385*/
11386int wolfSSL_CTX_DisableOCSP(WOLFSSL_CTX* ctx);
11387
11388/*!
11389    \brief This function manually sets the URL for OCSP to use. By default,
11390    OCSP will use the URL found in the individual certificate unless the
11391    WOLFSSL_OCSP_URL_OVERRIDE option is set using the wolfSSL_CTX_EnableOCSP.
11392
11393    \return SSL_SUCCESS is returned upon success.
11394    \return SSL_FAILURE is returned upon failure.
11395    \return NOT_COMPILED_IN is returned when this function has been called,
11396    but OCSP support was not enabled when wolfSSL was compiled.
11397
11398    \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
11399    \param url pointer to the OCSP URL for wolfSSL to use.
11400
11401    _Example_
11402    \code
11403    WOLFSSL_CTX* ctx = 0;
11404    ...
11405    wolfSSL_CTX_OCSP_set_override_url(ctx, “custom-url-here”);
11406    \endcode
11407
11408    \sa wolfSSL_CTX_OCSP_set_options
11409*/
11410int wolfSSL_CTX_SetOCSP_OverrideURL(WOLFSSL_CTX* ctx, const char* url);
11411
11412/*!
11413    \brief Sets the callback for the OCSP in the WOLFSSL_CTX structure.
11414
11415    \return SSL_SUCCESS returned if the function executed successfully. The
11416    ocspIOCb, ocspRespFreeCb, and ocspIOCtx members in the CM were
11417    successfully set.
11418    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX or
11419    WOLFSSL_CERT_MANAGER structure is NULL.
11420
11421    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11422    \param ioCb a CbOCSPIO type that is a function pointer.
11423    \param respFreeCb a CbOCSPRespFree type that is a function pointer.
11424    \param ioCbCtx a void pointer that will be held in the WOLFSSL_CERT_MANAGER.
11425
11426    _Example_
11427    \code
11428    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
11429    …
11430    CbOCSPIO ocspIOCb;
11431    CbOCSPRespFree ocspRespFreeCb;
11432    …
11433    void* ioCbCtx;
11434
11435    int isSetOCSP = wolfSSL_CTX_SetOCSP_Cb(ctx, ocspIOCb,
11436    ocspRespFreeCb, ioCbCtx);
11437
11438    if(isSetOCSP != SSL_SUCCESS){
11439    	// The function did not return successfully.
11440    }
11441    \endcode
11442
11443    \sa wolfSSL_CertManagerSetOCSP_Cb
11444    \sa CbOCSPIO
11445    \sa CbOCSPRespFree
11446*/
11447int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX* ctx,
11448                           CbOCSPIO ioCb, CbOCSPRespFree respFreeCb,
11449                           void* ioCbCtx);
11450
11451/*!
11452    \brief This function enables OCSP stapling by calling
11453    wolfSSL_CertManagerEnableOCSPStapling().
11454
11455    \return SSL_SUCCESS returned if there were no errors and the function
11456    executed successfully.
11457    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or
11458    otherwise if there was a unpermitted argument value passed to a subroutine.
11459    \return MEMORY_E returned if there was an issue allocating memory.
11460    \return SSL_FAILURE returned if the initialization of the OCSP
11461    structure failed.
11462    \return NOT_COMPILED_IN returned if wolfSSL was not compiled with
11463    HAVE_CERTIFICATE_STATUS_REQUEST option.
11464
11465    \param ctx a pointer to a WOLFSSL_CTX structure, created using
11466    wolfSSL_CTX_new().
11467
11468    _Example_
11469    \code
11470    WOLFSSL* ssl = WOLFSSL_new();
11471    ssl->method.version; // set to desired protocol
11472    ...
11473    if(!wolfSSL_CTX_EnableOCSPStapling(ssl->ctx)){
11474    	// OCSP stapling is not enabled
11475    }
11476    \endcode
11477
11478    \sa wolfSSL_CertManagerEnableOCSPStapling
11479    \sa InitOCSP
11480*/
11481int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX* ctx);
11482
11483/*!
11484    \ingroup CertsKeys
11485
11486    \brief Normally, at the end of the SSL handshake, wolfSSL frees
11487    temporary arrays.  Calling this function before the handshake begins
11488    will prevent wolfSSL from freeing temporary arrays.  Temporary arrays
11489    may be needed for things such as wolfSSL_get_keys() or PSK hints.
11490    When the user is done with temporary arrays, either wolfSSL_FreeArrays()
11491    may be called to free the resources immediately, or alternatively the
11492    resources will be freed when the associated SSL object is freed.
11493
11494    \return none No return.
11495
11496    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11497
11498    _Example_
11499    \code
11500    WOLFSSL* ssl;
11501    ...
11502    wolfSSL_KeepArrays(ssl);
11503    \endcode
11504
11505    \sa wolfSSL_FreeArrays
11506*/
11507void wolfSSL_KeepArrays(WOLFSSL* ssl);
11508
11509/*!
11510    \ingroup CertsKeys
11511
11512    \brief Normally, at the end of the SSL handshake, wolfSSL frees temporary
11513    arrays.  If wolfSSL_KeepArrays() has been called before the handshake,
11514    wolfSSL will not free temporary arrays.  This function explicitly frees
11515    temporary arrays and should be called when the user is done with temporary
11516    arrays and does not want to wait for the SSL object to be freed to free
11517    these resources.
11518
11519    \return none No return.
11520
11521    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11522
11523    _Example_
11524    \code
11525    WOLFSSL* ssl;
11526    ...
11527    wolfSSL_FreeArrays(ssl);
11528    \endcode
11529
11530    \sa wolfSSL_KeepArrays
11531*/
11532void wolfSSL_FreeArrays(WOLFSSL* ssl);
11533
11534/*!
11535    \brief This function enables the use of Server Name Indication in the SSL
11536    object passed in the 'ssl' parameter. It means that the SNI extension will
11537    be sent on ClientHello by wolfSSL client and wolfSSL server will respond
11538    ClientHello + SNI with either ServerHello + blank SNI or alert fatal in
11539    case of SNI mismatch.
11540
11541    \return WOLFSSL_SUCCESS upon success.
11542    \return BAD_FUNC_ARG is the error that will be returned in one of these
11543    cases: ssl is NULL, data is NULL, type is a unknown value. (see below)
11544    \return MEMORY_E is the error returned when there is not enough memory.
11545
11546    \param ssl pointer to a SSL object, created with wolfSSL_new().
11547    \param type indicates which type of server name is been passed in data.
11548    The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
11549    \param data pointer to the server name data.
11550    \param size size of the server name data.
11551
11552    _Example_
11553    \code
11554    int ret = 0;
11555    WOLFSSL_CTX* ctx = 0;
11556    WOLFSSL* ssl = 0;
11557    ctx = wolfSSL_CTX_new(method);
11558    if (ctx == NULL) {
11559        // context creation failed
11560    }
11561    ssl = wolfSSL_new(ctx);
11562    if (ssl == NULL) {
11563        // ssl creation failed
11564    }
11565    ret = wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, "www.yassl.com",
11566        strlen("www.yassl.com"));
11567    if (ret != WOLFSSL_SUCCESS) {
11568        // sni usage failed
11569    }
11570    \endcode
11571
11572    \sa wolfSSL_new
11573    \sa wolfSSL_CTX_UseSNI
11574*/
11575int wolfSSL_UseSNI(WOLFSSL* ssl, unsigned char type,
11576                                         const void* data, unsigned short size);
11577
11578/*!
11579    \brief This function enables the use of Server Name Indication for SSL
11580    objects created from the SSL context passed in the 'ctx' parameter. It
11581    means that the SNI extension will be sent on ClientHello by wolfSSL
11582    clients and wolfSSL servers will respond ClientHello + SNI with either
11583    ServerHello + blank SNI or alert fatal in case of SNI mismatch.
11584
11585    \return WOLFSSL_SUCCESS upon success.
11586    \return BAD_FUNC_ARG is the error that will be returned in one of these
11587    cases: ctx is NULL, data is NULL, type is a unknown value. (see below)
11588    \return MEMORY_E is the error returned when there is not enough memory.
11589
11590    \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
11591    \param type indicates which type of server name is been passed in data.
11592    The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
11593    \param data pointer to the server name data.
11594    \param size size of the server name data.
11595
11596    _Example_
11597    \code
11598    int ret = 0;
11599    WOLFSSL_CTX* ctx = 0;
11600    ctx = wolfSSL_CTX_new(method);
11601    if (ctx == NULL) {
11602        // context creation failed
11603    }
11604    ret = wolfSSL_CTX_UseSNI(ctx, WOLFSSL_SNI_HOST_NAME, "www.yassl.com",
11605        strlen("www.yassl.com"));
11606    if (ret != WOLFSSL_SUCCESS) {
11607        // sni usage failed
11608    }
11609    \endcode
11610
11611    \sa wolfSSL_CTX_new
11612    \sa wolfSSL_UseSNI
11613*/
11614int wolfSSL_CTX_UseSNI(WOLFSSL_CTX* ctx, unsigned char type,
11615                                         const void* data, unsigned short size);
11616
11617/*!
11618    \brief This function is called on the server side to configure the
11619    behavior of the SSL session using Server Name Indication in the SSL
11620    object passed in the 'ssl' parameter. The options are explained below.
11621
11622    \return none No returns.
11623
11624    \param ssl pointer to a SSL object, created with wolfSSL_new().
11625    \param type indicates which type of server name is been passed in data.
11626    The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
11627    \param options a bitwise semaphore with the chosen options. The available
11628    options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01,
11629    WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort the
11630    handshake by sending a fatal-level unrecognized_name(112) alert if the
11631    hostname provided by the client mismatch with the servers.
11632    \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the server
11633    will not send a SNI response instead of aborting the session.
11634    \param WOLFSSL_SNI_ANSWER_ON_MISMATCH - With this option set, the server
11635    will send a SNI response as if the host names match instead of aborting
11636    the session.
11637
11638    _Example_
11639    \code
11640    int ret = 0;
11641    WOLFSSL_CTX* ctx = 0;
11642    WOLFSSL* ssl = 0;
11643    ctx = wolfSSL_CTX_new(method);
11644    if (ctx == NULL) {
11645        // context creation failed
11646    }
11647    ssl = wolfSSL_new(ctx);
11648    if (ssl == NULL) {
11649        // ssl creation failed
11650    }
11651    ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));
11652    if (ret != WOLFSSL_SUCCESS) {
11653        // sni usage failed
11654    }
11655    wolfSSL_SNI_SetOptions(ssl, WOLFSSL_SNI_HOST_NAME,
11656        WOLFSSL_SNI_CONTINUE_ON_MISMATCH);
11657    \endcode
11658
11659    \sa wolfSSL_new
11660    \sa wolfSSL_UseSNI
11661    \sa wolfSSL_CTX_SNI_SetOptions
11662*/
11663void wolfSSL_SNI_SetOptions(WOLFSSL* ssl, unsigned char type,
11664                                                         unsigned char options);
11665
11666/*!
11667    \brief This function is called on the server side to configure the behavior
11668    of the SSL sessions using Server Name Indication for SSL objects created
11669    from the SSL context passed in the 'ctx' parameter. The options are
11670    explained below.
11671
11672    \return none No returns.
11673
11674    \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
11675    \param type indicates which type of server name is been passed in data.
11676    The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
11677    \param options a bitwise semaphore with the chosen options. The available
11678    options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01,
11679    WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort
11680    the handshake by sending a fatal-level unrecognized_name(112) alert if the
11681    hostname provided by the client mismatch with the servers.
11682    \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the
11683    server will not send a SNI response instead of aborting the session.
11684    \param WOLFSSL_SNI_ANSWER_ON_MISMATCH With this option set, the server
11685    will send a SNI response as if the host names match instead of aborting
11686    the session.
11687
11688    _Example_
11689    \code
11690    int ret = 0;
11691    WOLFSSL_CTX* ctx = 0;
11692    ctx = wolfSSL_CTX_new(method);
11693    if (ctx == NULL) {
11694       // context creation failed
11695    }
11696    ret = wolfSSL_CTX_UseSNI(ctx, 0, "www.yassl.com", strlen("www.yassl.com"));
11697    if (ret != WOLFSSL_SUCCESS) {
11698        // sni usage failed
11699    }
11700    wolfSSL_CTX_SNI_SetOptions(ctx, WOLFSSL_SNI_HOST_NAME,
11701    WOLFSSL_SNI_CONTINUE_ON_MISMATCH);
11702    \endcode
11703
11704    \sa wolfSSL_CTX_new
11705    \sa wolfSSL_CTX_UseSNI
11706    \sa wolfSSL_SNI_SetOptions
11707*/
11708void wolfSSL_CTX_SNI_SetOptions(WOLFSSL_CTX* ctx,
11709                                     unsigned char type, unsigned char options);
11710
11711/*!
11712    \brief This function is called on the server side to retrieve the Server
11713    Name Indication provided by the client from the Client Hello message sent
11714    by the client to start a session. It does not requires context or session
11715    setup to retrieve the SNI.
11716
11717    \return WOLFSSL_SUCCESS upon success.
11718    \return BAD_FUNC_ARG is the error that will be returned in one of this
11719    cases: buffer is NULL, bufferSz <= 0, sni is NULL, inOutSz is NULL or <= 0
11720    \return BUFFER_ERROR is the error returned when there is a malformed
11721    Client Hello message.
11722    \return INCOMPLETE_DATA is the error returned when there is not enough
11723    data to complete the extraction.
11724
11725    \param buffer pointer to the data provided by the client (Client Hello).
11726    \param bufferSz size of the Client Hello message.
11727    \param type indicates which type of server name is been retrieved
11728    from the buffer. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
11729    \param sni pointer to where the output is going to be stored.
11730    \param inOutSz pointer to the output size, this value will be updated
11731    to MIN("SNI's length", inOutSz).
11732
11733    _Example_
11734    \code
11735    unsigned char buffer[1024] = {0};
11736    unsigned char result[32]   = {0};
11737    int           length       = 32;
11738    // read Client Hello to buffer...
11739    ret = wolfSSL_SNI_GetFromBuffer(buffer, sizeof(buffer), 0, result, &length));
11740    if (ret != WOLFSSL_SUCCESS) {
11741        // sni retrieve failed
11742    }
11743    \endcode
11744
11745    \sa wolfSSL_UseSNI
11746    \sa wolfSSL_CTX_UseSNI
11747    \sa wolfSSL_SNI_GetRequest
11748*/
11749int wolfSSL_SNI_GetFromBuffer(
11750                 const unsigned char* clientHello, unsigned int helloSz,
11751                 unsigned char type, unsigned char* sni, unsigned int* inOutSz);
11752
11753/*!
11754    \ingroup IO
11755
11756    \brief This function gets the status of an SNI object.
11757
11758    \return value This function returns the byte value of the SNI struct’s
11759    status member if the SNI is not NULL.
11760    \return 0 if the SNI object is NULL.
11761
11762    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11763    \param type the SNI type.
11764
11765    _Example_
11766    \code
11767    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
11768    WOLFSSL* ssl = wolfSSL_new(ctx);
11769    …
11770    #define AssertIntEQ(x, y) AssertInt(x, y, ==, !=)
11771    …
11772    Byte type = WOLFSSL_SNI_HOST_NAME;
11773    char* request = (char*)&type;
11774    AssertIntEQ(WOLFSSL_SNI_NO_MATCH, wolfSSL_SNI_Status(ssl, type));
11775    …
11776    \endcode
11777
11778    \sa TLSX_SNI_Status
11779    \sa TLSX_SNI_find
11780    \sa TLSX_Find
11781*/
11782unsigned char wolfSSL_SNI_Status(WOLFSSL* ssl, unsigned char type);
11783
11784/*!
11785    \brief This function is called on the server side to retrieve the
11786    Server Name Indication provided by the client in a SSL session.
11787
11788    \return size the size of the provided SNI data.
11789
11790    \param ssl pointer to a SSL object, created with wolfSSL_new().
11791    \param type indicates which type of server name is been retrieved in
11792    data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 };
11793    \param data pointer to the data provided by the client.
11794
11795    _Example_
11796    \code
11797    int ret = 0;
11798    WOLFSSL_CTX* ctx = 0;
11799    WOLFSSL* ssl = 0;
11800    ctx = wolfSSL_CTX_new(method);
11801    if (ctx == NULL) {
11802        // context creation failed
11803    }
11804    ssl = wolfSSL_new(ctx);
11805    if (ssl == NULL) {
11806        // ssl creation failed
11807    }
11808    ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com"));
11809    if (ret != WOLFSSL_SUCCESS) {
11810        // sni usage failed
11811    }
11812    if (wolfSSL_accept(ssl) == SSL_SUCCESS) {
11813        void *data = NULL;
11814        unsigned short size = wolfSSL_SNI_GetRequest(ssl, 0, &data);
11815    }
11816    \endcode
11817
11818    \sa wolfSSL_UseSNI
11819    \sa wolfSSL_CTX_UseSNI
11820*/
11821unsigned short wolfSSL_SNI_GetRequest(WOLFSSL *ssl,
11822                                               unsigned char type, void** data);
11823
11824/*!
11825    \ingroup Setup
11826
11827    \brief Setup ALPN use for a wolfSSL session.
11828
11829    \return WOLFSSL_SUCCESS: upon success.
11830    \return BAD_FUNC_ARG Returned if ssl or protocol_name_list
11831    is null or protocol_name_listSz is too large or options
11832    contain something not supported.
11833    \return MEMORY_ERROR Error allocating memory for protocol list.
11834    \return SSL_FAILURE upon failure.
11835
11836    \param ssl The wolfSSL session to use.
11837    \param protocol_name_list List of protocol names to use.
11838    Comma delimited string is required.
11839    \param protocol_name_listSz Size of the list of protocol names.
11840    \param options WOLFSSL_ALPN_CONTINUE_ON_MISMATCH or
11841    WOLFSSL_ALPN_FAILED_ON_MISMATCH.
11842
11843    _Example_
11844    \code
11845    wolfSSL_Init();
11846    WOLFSSL_CTX* ctx;
11847    WOLFSSL* ssl;
11848    WOLFSSL_METHOD method = // Some wolfSSL method
11849    ctx = wolfSSL_CTX_new(method);
11850    ssl = wolfSSL_new(ctx);
11851
11852    char alpn_list[] = {};
11853
11854    if (wolfSSL_UseALPN(ssl, alpn_list, sizeof(alpn_list),
11855        WOLFSSL_APN_FAILED_ON_MISMATCH) != WOLFSSL_SUCCESS)
11856    {
11857       // Error setting session ticket
11858    }
11859    \endcode
11860
11861    \sa TLSX_UseALPN
11862*/
11863int wolfSSL_UseALPN(WOLFSSL* ssl, char *protocol_name_list,
11864                                unsigned int protocol_name_listSz,
11865                                unsigned char options);
11866
11867/*!
11868    \ingroup TLS
11869
11870    \brief This function gets the protocol name set by the server.
11871
11872    \return SSL_SUCCESS returned on successful execution where no
11873    errors were thrown.
11874    \return SSL_FATAL_ERROR returned if the extension was not found or
11875    if there was no protocol match with peer. There will also be an
11876    error thrown if there is more than one protocol name accepted.
11877    \return SSL_ALPN_NOT_FOUND returned signifying that no protocol
11878    match with peer was found.
11879    \return BAD_FUNC_ARG returned if there was a NULL argument passed
11880    into the function.
11881
11882    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11883    \param protocol_name a pointer to a char that represents the protocol
11884    name and will be held in the ALPN structure.
11885    \param size a word16 type that represents the size of the protocol_name.
11886
11887    _Example_
11888    \code
11889    WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method );
11890    WOLFSSL* ssl = WOLFSSL_new(ctx);
11891    ...
11892    int err;
11893    char* protocol_name = NULL;
11894    Word16 protocol_nameSz = 0;
11895    err = wolfSSL_ALPN_GetProtocol(ssl, &protocol_name, &protocol_nameSz);
11896
11897    if(err == SSL_SUCCESS){
11898	    // Sent ALPN protocol
11899    }
11900    \endcode
11901
11902    \sa TLSX_ALPN_GetRequest
11903    \sa TLSX_Find
11904*/
11905int wolfSSL_ALPN_GetProtocol(WOLFSSL* ssl, char **protocol_name,
11906                                         unsigned short *size);
11907
11908/*!
11909    \ingroup TLS
11910
11911    \brief This function copies the alpn_client_list data from the SSL
11912    object to the buffer.
11913
11914    \return SSL_SUCCESS returned if the function executed without error. The
11915    alpn_client_list member of the SSL object has been copied to the
11916    list parameter.
11917    \return BAD_FUNC_ARG returned if the list or listSz parameter is NULL.
11918    \return BUFFER_ERROR returned if there will be a problem with the
11919    list buffer (either it’s NULL or the size is 0).
11920    \return MEMORY_ERROR returned if there was a problem dynamically
11921    allocating memory.
11922
11923    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
11924    \param list a pointer to the buffer. The data from the SSL object will
11925    be copied into it.
11926    \param listSz the buffer size.
11927
11928    _Example_
11929    \code
11930    #import <wolfssl/ssl.h>
11931
11932    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method);
11933    WOLFSSL* ssl = wolfSSL_new(ctx);
11934    …
11935    #ifdef HAVE_ALPN
11936    char* list = NULL;
11937    word16 listSz = 0;
11938    …
11939    err = wolfSSL_ALPN_GetPeerProtocol(ssl, &list, &listSz);
11940
11941    if(err == SSL_SUCCESS){
11942	    List of protocols names sent by client
11943    }
11944    \endcode
11945
11946    \sa wolfSSL_UseALPN
11947*/
11948int wolfSSL_ALPN_GetPeerProtocol(WOLFSSL* ssl, char **list,
11949                                             unsigned short *listSz);
11950
11951/*!
11952    \brief This function is called on the client side to enable the use of
11953    Maximum Fragment Length in the SSL object passed in the 'ssl' parameter.
11954    It means that the Maximum Fragment Length extension will be sent on
11955    ClientHello by wolfSSL clients.
11956
11957    \return SSL_SUCCESS upon success.
11958    \return BAD_FUNC_ARG is the error that will be returned in one of
11959    these cases: ssl is NULL, mfl is out of range.
11960    \return MEMORY_E is the error returned when there is not enough memory.
11961
11962    \param ssl pointer to a SSL object, created with wolfSSL_new().
11963    \param mfl indicates which is the Maximum Fragment Length requested for the
11964    session. The available options are: enum { WOLFSSL_MFL_2_9  = 1, 512 bytes
11965    WOLFSSL_MFL_2_10 = 2, 1024 bytes WOLFSSL_MFL_2_11 = 3, 2048 bytes
11966    WOLFSSL_MFL_2_12 = 4, 4096 bytes WOLFSSL_MFL_2_13 = 5, 8192
11967    bytes wolfSSL ONLY!!! };
11968
11969    _Example_
11970    \code
11971    int ret = 0;
11972    WOLFSSL_CTX* ctx = 0;
11973    WOLFSSL* ssl = 0;
11974    ctx = wolfSSL_CTX_new(method);
11975    if (ctx == NULL) {
11976        // context creation failed
11977    }
11978    ssl = wolfSSL_new(ctx);
11979    if (ssl == NULL) {
11980        // ssl creation failed
11981    }
11982    ret = wolfSSL_UseMaxFragment(ssl, WOLFSSL_MFL_2_11);
11983    if (ret != 0) {
11984        // max fragment usage failed
11985    }
11986    \endcode
11987
11988    \sa wolfSSL_new
11989    \sa wolfSSL_CTX_UseMaxFragment
11990*/
11991int wolfSSL_UseMaxFragment(WOLFSSL* ssl, unsigned char mfl);
11992
11993/*!
11994    \brief This function is called on the client side to enable the use
11995    of Maximum Fragment Length for SSL objects created from the SSL context
11996    passed in the 'ctx' parameter. It means that the Maximum Fragment Length
11997    extension will be sent on ClientHello by wolfSSL clients.
11998
11999    \return SSL_SUCCESS upon success.
12000    \return BAD_FUNC_ARG is the error that will be returned in one of
12001    these cases: ctx is NULL, mfl is out of range.
12002    \return MEMORY_E is the error returned when there is not enough memory.
12003
12004    \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
12005    \param mfl indicates which is the Maximum Fragment Length requested
12006    for the session. The available options are:
12007    enum { WOLFSSL_MFL_2_9  = 1 512 bytes, WOLFSSL_MFL_2_10 = 2 1024 bytes,
12008           WOLFSSL_MFL_2_11 = 3 2048 bytes WOLFSSL_MFL_2_12 = 4 4096 bytes,
12009           WOLFSSL_MFL_2_13 = 5 8192 bytes wolfSSL ONLY!!!,
12010           WOLFSSL_MFL_2_13 = 6  256 bytes wolfSSL ONLY!!!
12011    };
12012
12013    _Example_
12014    \code
12015    int ret = 0;
12016    WOLFSSL_CTX* ctx = 0;
12017    ctx = wolfSSL_CTX_new(method);
12018    if (ctx == NULL) {
12019        // context creation failed
12020    }
12021    ret = wolfSSL_CTX_UseMaxFragment(ctx, WOLFSSL_MFL_2_11);
12022    if (ret != 0) {
12023        // max fragment usage failed
12024    }
12025    \endcode
12026
12027    \sa wolfSSL_CTX_new
12028    \sa wolfSSL_UseMaxFragment
12029*/
12030int wolfSSL_CTX_UseMaxFragment(WOLFSSL_CTX* ctx, unsigned char mfl);
12031
12032/*!
12033    \brief This function is called on the client side to enable the use of
12034    Truncated HMAC in the SSL object passed in the 'ssl' parameter. It
12035    means that the Truncated HMAC extension will be sent on ClientHello
12036    by wolfSSL clients.
12037
12038    \return SSL_SUCCESS upon success.
12039    \return BAD_FUNC_ARG is the error that will be returned in one of
12040    these cases: ssl is NULL
12041    \return MEMORY_E is the error returned when there is not enough memory.
12042
12043    \param ssl pointer to a SSL object, created with wolfSSL_new()
12044
12045    _Example_
12046    \code
12047    int ret = 0;
12048    WOLFSSL_CTX* ctx = 0;
12049    WOLFSSL* ssl = 0;
12050    ctx = wolfSSL_CTX_new(method);
12051    if (ctx == NULL) {
12052        // context creation failed
12053    }
12054    ssl = wolfSSL_new(ctx);
12055    if (ssl == NULL) {
12056        // ssl creation failed
12057    }
12058    ret = wolfSSL_UseTruncatedHMAC(ssl);
12059    if (ret != 0) {
12060        // truncated HMAC usage failed
12061    }
12062    \endcode
12063
12064    \sa wolfSSL_new
12065    \sa wolfSSL_CTX_UseMaxFragment
12066*/
12067int wolfSSL_UseTruncatedHMAC(WOLFSSL* ssl);
12068
12069/*!
12070    \brief This function is called on the client side to enable the use of
12071    Truncated HMAC for SSL objects created from the SSL context passed in
12072    the 'ctx' parameter. It means that the Truncated HMAC extension will
12073    be sent on ClientHello by wolfSSL clients.
12074
12075    \return SSL_SUCCESS upon success.
12076    \return BAD_FUNC_ARG is the error that will be returned in one of
12077    these cases: ctx is NULL
12078    \return MEMORY_E is the error returned when there is not enough memory.
12079
12080    \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
12081
12082    _Example_
12083    \code
12084    int ret = 0;
12085    WOLFSSL_CTX* ctx = 0;
12086    ctx = wolfSSL_CTX_new(method);
12087    if (ctx == NULL) {
12088        // context creation failed
12089    }
12090    ret = wolfSSL_CTX_UseTruncatedHMAC(ctx);
12091    if (ret != 0) {
12092        // truncated HMAC usage failed
12093    }
12094    \endcode
12095
12096    \sa wolfSSL_CTX_new
12097    \sa wolfSSL_UseMaxFragment
12098*/
12099int wolfSSL_CTX_UseTruncatedHMAC(WOLFSSL_CTX* ctx);
12100
12101/*!
12102    \brief Stapling eliminates the need to contact the CA. Stapling
12103    lowers the cost of certificate revocation check presented in OCSP.
12104
12105    \return SSL_SUCCESS returned if TLSX_UseCertificateStatusRequest
12106    executes without error.
12107    \return MEMORY_E returned if there is an error with the allocation
12108    of memory.
12109    \return BAD_FUNC_ARG returned if there is an argument that has a
12110    NULL or otherwise unacceptable value passed into the function.
12111
12112    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12113    \param status_type a byte type that is passed through to
12114    TLSX_UseCertificateStatusRequest() and stored in the
12115    CertificateStatusRequest structure.
12116    \param options a byte type that is passed through to
12117    TLSX_UseCertificateStatusRequest() and stored in the
12118    CertificateStatusRequest structure.
12119
12120    _Example_
12121    \code
12122    WOLFSSL* ssl = wolfSSL_new(ctx);
12123    …
12124    if (wolfSSL_UseOCSPStapling(ssl, WOLFSSL_CSR2_OCSP,
12125    WOLFSSL_CSR2_OCSP_USE_NONCE) != SSL_SUCCESS){
12126	    // Failed case.
12127    }
12128    \endcode
12129
12130    \sa TLSX_UseCertificateStatusRequest
12131    \sa wolfSSL_CTX_UseOCSPStapling
12132*/
12133int wolfSSL_UseOCSPStapling(WOLFSSL* ssl,
12134                              unsigned char status_type, unsigned char options);
12135
12136/*!
12137    \brief This function requests the certificate status during the handshake.
12138
12139    \return SSL_SUCCESS returned if the function and subroutines execute
12140    without error.
12141    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or
12142    otherwise if a unpermitted value is passed to a subroutine.
12143    \return MEMORY_E returned if the function or subroutine failed to properly
12144    allocate memory.
12145
12146    \param ctx a pointer to a WOLFSSL_CTX structure,
12147    created using wolfSSL_CTX_new().
12148    \param status_type a byte type that is passed through to
12149    TLSX_UseCertificateStatusRequest() and stored in the
12150    CertificateStatusRequest structure.
12151    \param options a byte type that is passed through to
12152    TLSX_UseCertificateStatusRequest() and stored in the
12153    CertificateStatusRequest structure.
12154
12155    _Example_
12156    \code
12157    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
12158    WOLFSSL* ssl = wolfSSL_new(ctx);
12159    byte statusRequest = 0; // Initialize status request
12160    …
12161    switch(statusRequest){
12162    	case WOLFSSL_CSR_OCSP:
12163    		if(wolfSSL_CTX_UseOCSPStapling(ssl->ctx, WOLFSSL_CSR_OCSP,
12164    WOLF_CSR_OCSP_USE_NONCE) != SSL_SUCCESS){
12165    // UseCertificateStatusRequest failed
12166    }
12167    // Continue switch cases
12168    \endcode
12169
12170    \sa wolfSSL_UseOCSPStaplingV2
12171    \sa wolfSSL_UseOCSPStapling
12172    \sa TLSX_UseCertificateStatusRequest
12173*/
12174int wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX* ctx,
12175                              unsigned char status_type, unsigned char options);
12176
12177/*!
12178    \brief The function sets the status type and options for OCSP.
12179
12180    \return SSL_SUCCESS - returned if the function and subroutines
12181    executed without error.
12182    \return MEMORY_E - returned if there was an allocation of memory error.
12183    \return BAD_FUNC_ARG - returned if a NULL or otherwise unaccepted
12184    argument was passed to the function or a subroutine.
12185
12186    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12187    \param status_type a byte type that loads the OCSP status type.
12188    \param options a byte type that holds the OCSP options, set in
12189    wolfSSL_SNI_SetOptions() and wolfSSL_CTX_SNI_SetOptions().
12190
12191    _Example_
12192    \code
12193    WOLFSSL* ssl = wolfSSL_new(ctx);
12194    ...
12195    if (wolfSSL_UseOCSPStaplingV2(ssl, WOLFSSL_CSR2_OCSP_MULTI, 0) != SSL_SUCCESS){
12196    	// Did not execute properly. Failure case code block.
12197    }
12198    \endcode
12199
12200    \sa TLSX_UseCertificatStatusRequestV2
12201    \sa wolfSSL_SNI_SetOptions
12202    \sa wolfSSL_CTX_SNI_SetOptions
12203*/
12204int wolfSSL_UseOCSPStaplingV2(WOLFSSL* ssl,
12205                              unsigned char status_type, unsigned char options);
12206
12207/*!
12208    \brief Creates and initializes the certificate status request
12209    for OCSP Stapling.
12210
12211    \return SSL_SUCCESS if the function and subroutines executed without error.
12212    \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or if
12213    the side variable is not client side.
12214    \return MEMORY_E returned if the allocation of memory failed.
12215
12216    \param ctx a pointer to a WOLFSSL_CTX structure, created using
12217    wolfSSL_CTX_new().
12218    \param status_type a byte type that is located in the
12219    CertificatStatusRequest structure and must be either WOLFSSL_CSR2_OCSP
12220    or WOLFSSL_CSR2_OCSP_MULTI.
12221    \param options a byte type that will be held in
12222    CertificateStatusRequestItemV2 struct.
12223
12224    _Example_
12225    \code
12226    WOLFSSL_CTX* ctx  = wolfSSL_CTX_new( protocol method );
12227    byte status_type;
12228    byte options;
12229    ...
12230    if(wolfSSL_CTX_UseOCSPStaplingV2(ctx, status_type, options); != SSL_SUCCESS){
12231    	// Failure case.
12232    }
12233    \endcode
12234
12235    \sa TLSX_UseCertificateStatusRequestV2
12236    \sa wc_RNG_GenerateBlock
12237    \sa TLSX_Push
12238*/
12239int wolfSSL_CTX_UseOCSPStaplingV2(WOLFSSL_CTX* ctx,
12240                              unsigned char status_type, unsigned char options);
12241
12242/*!
12243    \brief This function is called on the client side to enable the use of
12244    Supported Elliptic Curves Extension in the SSL object passed in the 'ssl'
12245    parameter. It means that the supported curves enabled will be sent on
12246    ClientHello by wolfSSL clients. This function can be called more than
12247    one time to enable multiple curves.
12248
12249    \return SSL_SUCCESS upon success.
12250    \return BAD_FUNC_ARG is the error that will be returned in one of these
12251    cases: ssl is NULL, name is a unknown value. (see below)
12252    \return MEMORY_E is the error returned when there is not enough memory.
12253
12254    \param ssl pointer to a SSL object, created with wolfSSL_new().
12255    \param name indicates which curve will be supported for the session. The
12256    available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10,
12257    WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15,
12258    WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18,
12259    WOLFSSL_ECC_SECP521R1 = 0x19 };
12260
12261    _Example_
12262    \code
12263    int ret = 0;
12264    WOLFSSL_CTX* ctx = 0;
12265    WOLFSSL* ssl = 0;
12266    ctx = wolfSSL_CTX_new(method);
12267    if (ctx == NULL) {
12268        // context creation failed
12269    }
12270    ssl = wolfSSL_new(ctx);
12271    if (ssl == NULL) {
12272        // ssl creation failed
12273    }
12274    ret = wolfSSL_UseSupportedCurve(ssl, WOLFSSL_ECC_SECP256R1);
12275    if (ret != 0) {
12276        // Elliptic Curve Extension usage failed
12277    }
12278    \endcode
12279
12280    \sa wolfSSL_CTX_new
12281    \sa wolfSSL_CTX_UseSupportedCurve
12282*/
12283int wolfSSL_UseSupportedCurve(WOLFSSL* ssl, word16 name);
12284
12285/*!
12286    \brief This function is called on the client side to enable the use of
12287    Supported Elliptic Curves Extension for SSL objects created from the SSL
12288    context passed in the 'ctx' parameter. It means that the supported curves
12289    enabled will be sent on ClientHello by wolfSSL clients. This function can
12290    be called more than one time to enable multiple curves.
12291
12292    \return SSL_SUCCESS upon success.
12293    \return BAD_FUNC_ARG is the error that will be returned in one of these
12294    cases: ctx is NULL, name is a unknown value. (see below)
12295    \return MEMORY_E is the error returned when there is not enough memory.
12296
12297    \param ctx pointer to a SSL context, created with wolfSSL_CTX_new().
12298    \param name indicates which curve will be supported for the session.
12299    The available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10,
12300    WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15,
12301    WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18,
12302    WOLFSSL_ECC_SECP521R1 = 0x19 };
12303
12304    _Example_
12305    \code
12306    int ret = 0;
12307    WOLFSSL_CTX* ctx = 0;
12308    ctx = wolfSSL_CTX_new(method);
12309    if (ctx == NULL) {
12310        // context creation failed
12311    }
12312    ret = wolfSSL_CTX_UseSupportedCurve(ctx, WOLFSSL_ECC_SECP256R1);
12313    if (ret != 0) {
12314        // Elliptic Curve Extension usage failed
12315    }
12316    \endcode
12317
12318    \sa wolfSSL_CTX_new
12319    \sa wolfSSL_UseSupportedCurve
12320*/
12321int wolfSSL_CTX_UseSupportedCurve(WOLFSSL_CTX* ctx,
12322                                                           word16 name);
12323
12324/*!
12325    \ingroup IO
12326
12327    \brief This function forces secure renegotiation for the supplied
12328    WOLFSSL structure.  This is not recommended.
12329
12330    \return SSL_SUCCESS Successfully set secure renegotiation.
12331    \return BAD_FUNC_ARG Returns error if ssl is null.
12332    \return MEMORY_E Returns error if unable to allocate memory for secure
12333    renegotiation.
12334
12335    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12336
12337    _Example_
12338    \code
12339    wolfSSL_Init();
12340    WOLFSSL_CTX* ctx;
12341    WOLFSSL* ssl;
12342    WOLFSSL_METHOD method = // Some wolfSSL method
12343    ctx = wolfSSL_CTX_new(method);
12344    ssl = wolfSSL_new(ctx);
12345
12346    if(wolfSSL_UseSecureRenegotiation(ssl) != SSL_SUCCESS)
12347    {
12348        // Error setting secure renegotiation
12349    }
12350    \endcode
12351
12352    \sa TLSX_Find
12353    \sa TLSX_UseSecureRenegotiation
12354*/
12355int wolfSSL_UseSecureRenegotiation(WOLFSSL* ssl);
12356
12357/*!
12358    \ingroup IO
12359
12360    \brief This function executes a secure renegotiation handshake; this is user
12361    forced as wolfSSL discourages this functionality.
12362
12363    \return SSL_SUCCESS returned if the function executed without error.
12364    \return BAD_FUNC_ARG returned if the WOLFSSL structure was NULL or otherwise
12365    if an unacceptable argument was passed in a subroutine.
12366    \return SECURE_RENEGOTIATION_E returned if there was an error with
12367    renegotiating the handshake.
12368    \return SSL_FATAL_ERROR returned if there was an error with the
12369    server or client configuration and the renegotiation could
12370    not be completed. See wolfSSL_negotiate().
12371
12372    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12373
12374    _Example_
12375    \code
12376    WOLFSSL* ssl = wolfSSL_new(ctx);
12377    ...
12378    if(wolfSSL_Rehandshake(ssl) != SSL_SUCCESS){
12379	    // There was an error and the rehandshake is not successful.
12380    }
12381    \endcode
12382
12383    \sa wolfSSL_negotiate
12384    \sa wc_InitSha512
12385    \sa wc_InitSha384
12386    \sa wc_InitSha256
12387    \sa wc_InitSha
12388    \sa wc_InitMd5
12389*/
12390int wolfSSL_Rehandshake(WOLFSSL* ssl);
12391
12392/*!
12393    \ingroup IO
12394
12395    \brief Force provided WOLFSSL structure to use session ticket. The
12396    constant HAVE_SESSION_TICKET should be defined and the constant
12397    NO_WOLFSSL_CLIENT should not be defined to use this function.
12398
12399    \return SSL_SUCCESS Successfully set use session ticket.
12400    \return BAD_FUNC_ARG Returned if ssl is null.
12401    \return MEMORY_E Error allocating memory for setting session ticket.
12402
12403    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12404
12405    _Example_
12406    \code
12407    wolfSSL_Init();
12408    WOLFSSL_CTX* ctx;
12409    WOLFSSL* ssl;
12410    WOLFSSL_METHOD method = // Some wolfSSL method
12411    ctx = wolfSSL_CTX_new(method);
12412    ssl = wolfSSL_new(ctx);
12413
12414    if(wolfSSL_UseSessionTicket(ssl) != SSL_SUCCESS)
12415    {
12416        // Error setting session ticket
12417    }
12418    \endcode
12419
12420    \sa TLSX_UseSessionTicket
12421*/
12422int wolfSSL_UseSessionTicket(WOLFSSL* ssl);
12423
12424/*!
12425    \ingroup Setup
12426
12427    \brief This function sets wolfSSL context to use a session ticket.
12428
12429    \return SSL_SUCCESS Function executed successfully.
12430    \return BAD_FUNC_ARG Returned if ctx is null.
12431    \return MEMORY_E Error allocating memory in internal function.
12432
12433    \param ctx The WOLFSSL_CTX structure to use.
12434
12435    _Example_
12436    \code
12437    wolfSSL_Init();
12438    WOLFSSL_CTX* ctx;
12439    WOLFSSL_METHOD method = // Some wolfSSL method ;
12440    ctx = wolfSSL_CTX_new(method);
12441
12442    if(wolfSSL_CTX_UseSessionTicket(ctx) != SSL_SUCCESS)
12443    {
12444        // Error setting session ticket
12445    }
12446    \endcode
12447
12448    \sa TLSX_UseSessionTicket
12449*/
12450int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx);
12451
12452/*!
12453    \ingroup IO
12454
12455    \brief This function copies the ticket member of the Session structure to
12456    the buffer. If buf is NULL and bufSz is non-NULL, bufSz will be set to the
12457    ticket length.
12458
12459    \return SSL_SUCCESS returned if the function executed without error.
12460    \return BAD_FUNC_ARG returned if ssl or bufSz is NULL, or if bufSz
12461    is non-NULL and buf is NULL
12462
12463
12464    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12465    \param buf a byte pointer representing the memory buffer.
12466    \param bufSz a word32 pointer representing the buffer size.
12467
12468    _Example_
12469    \code
12470    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
12471    WOLFSSL* ssl = wolfSSL_new(ctx);
12472    byte* buf;
12473    word32 bufSz;  // Initialize with buf size
12474    …
12475    if(wolfSSL_get_SessionTicket(ssl, buf, bufSz) <= 0){
12476	    // Nothing was written to the buffer
12477    } else {
12478	    // the buffer holds the content from ssl->session->ticket
12479    }
12480    \endcode
12481
12482    \sa wolfSSL_UseSessionTicket
12483    \sa wolfSSL_set_SessionTicket
12484*/
12485int wolfSSL_get_SessionTicket(WOLFSSL* ssl, unsigned char* buf, word32* bufSz);
12486
12487/*!
12488    \ingroup IO
12489
12490    \brief This function sets the ticket member of the WOLFSSL_SESSION
12491    structure within the WOLFSSL struct. The buffer passed into the function
12492    is copied to memory.
12493
12494    \return SSL_SUCCESS returned on successful execution of the function.
12495    The function returned without errors.
12496    \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. This will
12497    also be thrown if the buf argument is NULL but the bufSz argument
12498    is not zero.
12499
12500    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12501    \param buf a byte pointer that gets loaded into the ticket member
12502    of the session structure.
12503    \param bufSz a word32 type that represents the size of the buffer.
12504
12505    _Example_
12506    \code
12507    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
12508    WOLFSSL* ssl = wolfSSL_new(ctx);
12509    byte* buffer; // File to load
12510    word32 bufSz;
12511    ...
12512    if(wolfSSL_KeepArrays(ssl, buffer, bufSz) != SSL_SUCCESS){
12513    	// There was an error loading the buffer to memory.
12514    }
12515    \endcode
12516
12517    \sa wolfSSL_set_SessionTicket_cb
12518*/
12519int wolfSSL_set_SessionTicket(WOLFSSL* ssl, const unsigned char* buf,
12520                              word32 bufSz);
12521
12522/*!
12523    \brief This function sets the session ticket callback. The type
12524    CallbackSessionTicket is a function pointer with the signature of:
12525    int (*CallbackSessionTicket)(WOLFSSL*, const unsigned char*, int, void*)
12526
12527    \return SSL_SUCCESS returned if the function executed without error.
12528    \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL.
12529
12530    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12531    \param cb a function pointer to the type CallbackSessionTicket.
12532    \param ctx a void pointer to the session_ticket_ctx member of the
12533    WOLFSSL structure.
12534
12535    _Example_
12536    \code
12537    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
12538    WOLFSSL* ssl = wolfSSL_new(ctx);
12539    …
12540    int sessionTicketCB(WOLFSSL* ssl, const unsigned char* ticket, int ticketSz,
12541				void* ctx){ … }
12542    wolfSSL_set_SessionTicket_cb(ssl, sessionTicketCB, (void*)”initial session”);
12543    \endcode
12544
12545    \sa wolfSSL_get_SessionTicket
12546    \sa CallbackSessionTicket
12547    \sa sessionTicketCB
12548*/
12549int wolfSSL_set_SessionTicket_cb(WOLFSSL* ssl,
12550                                 CallbackSessionTicket cb, void* ctx);
12551
12552/*!
12553    \brief This function sends a session ticket to the client after a TLS v1.3
12554    handhsake has been established.
12555
12556    \return WOLFSSL_SUCCESS returned if a new session ticket was sent.
12557    \return BAD_FUNC_ARG returned if WOLFSSL structure is NULL, or not using
12558    TLS v1.3.
12559    \return SIDE_ERROR returned if not a server.
12560    \return NOT_READY_ERROR returned if the handshake has not completed.
12561    \return WOLFSSL_FATAL_ERROR returned if creating or sending message fails.
12562
12563    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12564
12565    _Example_
12566    \code
12567    int ret;
12568    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
12569    WOLFSSL* ssl = wolfSSL_new(ctx);
12570    …
12571    ret = wolfSSL_send_SessionTicket(ssl);
12572    if (ret != WOLFSSL_SUCCESS) {
12573        // New session ticket not sent.
12574    }
12575    \endcode
12576
12577    \sa wolfSSL_get_SessionTicket
12578    \sa CallbackSessionTicket
12579    \sa sessionTicketCB
12580 */
12581int wolfSSL_send_SessionTicket(WOLFSSL* ssl);
12582
12583/*!
12584    \brief This function sets the session ticket key encrypt callback function
12585    for a server to support session tickets as specified in RFC 5077.
12586
12587    \return SSL_SUCCESS will be returned upon successfully setting the session.
12588    \return BAD_FUNC_ARG will be returned on failure. This is caused by passing
12589    invalid arguments to the function.
12590
12591    \param ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().
12592    \param cb user callback function to encrypt/decrypt session tickets
12593    \param ssl(Callback) pointer to the WOLFSSL object, created with
12594    wolfSSL_new()
12595    \param key_name(Callback) unique key name for this ticket context, should
12596    be randomly generated
12597    \param iv(Callback) unique IV for this ticket, up to 128 bits, should
12598    be randomly generated
12599    \param mac(Callback) up to 256 bit mac for this ticket
12600    \param enc(Callback) if this encrypt parameter is true the user should fill
12601    in key_name, iv, mac, and encrypt the ticket in-place of length inLen and
12602    set the resulting output length in *outLen.  Returning WOLFSSL_TICKET_RET_OK
12603    tells wolfSSL that the encryption was successful. If this encrypt parameter
12604    is false, the user should perform a decrypt of the ticket in-place of length
12605    inLen using key_name, iv, and mac. The resulting decrypt length should be
12606    set in *outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL to proceed
12607    using the decrypted ticket. Returning WOLFSSL_TICKET_RET_CREATE tells
12608    wolfSSL to use the decrypted ticket but also to generate a new one to
12609    send to the client, helpful if recently rolled keys and don’t want to
12610    force a full handshake.  Returning WOLFSSL_TICKET_RET_REJECT tells
12611    wolfSSL to reject this ticket, perform a full handshake, and create
12612    a new standard session ID for normal session resumption. Returning
12613    WOLFSSL_TICKET_RET_FATAL tells wolfSSL to end the connection
12614    attempt with a fatal error.
12615    \param ticket(Callback) the input/output buffer for the encrypted ticket.
12616    See the enc parameter
12617    \param inLen(Callback) the input length of the ticket parameter
12618    \param outLen(Callback) the resulting output length of the ticket parameter.
12619    When entering the callback outLen will indicate the maximum size available
12620    in the ticket buffer.
12621    \param userCtx(Callback) the user context set with
12622    wolfSSL_CTX_set_TicketEncCtx()
12623
12624    _Example_
12625    \code
12626    See wolfssl/test.h myTicketEncCb() used by the example
12627    server and example echoserver.
12628    \endcode
12629
12630    \sa wolfSSL_CTX_set_TicketHint
12631    \sa wolfSSL_CTX_set_TicketEncCtx
12632*/
12633int wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX* ctx,
12634                                            SessionTicketEncCb cb);
12635
12636/*!
12637    \brief This function sets the session ticket hint relayed to the client.
12638    For server side use.
12639
12640    \return SSL_SUCCESS will be returned upon successfully setting the session.
12641    \return BAD_FUNC_ARG will be returned on failure.  This is caused by passing
12642    invalid arguments to the function.
12643
12644    \param ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new().
12645    \param hint number of seconds the ticket might be valid for.  Hint to client.
12646
12647    _Example_
12648    \code
12649    none
12650    \endcode
12651
12652    \sa wolfSSL_CTX_set_TicketEncCb
12653*/
12654int wolfSSL_CTX_set_TicketHint(WOLFSSL_CTX* ctx, int hint);
12655
12656/*!
12657    \brief This function sets the session ticket encrypt user context for the
12658    callback.  For server side use.
12659
12660    \return SSL_SUCCESS will be returned upon successfully setting the session.
12661    \return BAD_FUNC_ARG will be returned on failure.  This is caused by
12662    passing invalid arguments to the function.
12663
12664    \param ctx pointer to the WOLFSSL_CTX object, created
12665    with wolfSSL_CTX_new().
12666    \param userCtx the user context for the callback
12667
12668    _Example_
12669    \code
12670    none
12671    \endcode
12672
12673    \sa wolfSSL_CTX_set_TicketEncCb
12674*/
12675int wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX* ctx, void* userCtx);
12676
12677/*!
12678    \brief This function gets the session ticket encrypt user context for the
12679    callback.  For server side use.
12680
12681    \return userCtx will be returned upon successfully getting the session.
12682    \return NULL will be returned on failure.  This is caused by
12683    passing invalid arguments to the function, or when the user context has
12684    not been set.
12685
12686    \param ctx pointer to the WOLFSSL_CTX object, created
12687    with wolfSSL_CTX_new().
12688
12689    _Example_
12690    \code
12691    none
12692    \endcode
12693
12694    \sa wolfSSL_CTX_set_TicketEncCtx
12695*/
12696void* wolfSSL_CTX_get_TicketEncCtx(WOLFSSL_CTX* ctx);
12697
12698/*!
12699    \brief This function sets the handshake done callback. The hsDoneCb and
12700    hsDoneCtx members of the WOLFSSL structure are set in this function.
12701
12702    \return SSL_SUCCESS returned if the function executed without an error.
12703    The hsDoneCb and hsDoneCtx members of the WOLFSSL struct are set.
12704    \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL.
12705
12706    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
12707    \param cb a function pointer of type HandShakeDoneCb with the signature of
12708    the form: int (*HandShakeDoneCb)(WOLFSSL*, void*);
12709    \param user_ctx a void pointer to the user registered context.
12710
12711    _Example_
12712    \code
12713    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
12714    WOLFSSL* ssl = wolfSSL_new(ctx);
12715    …
12716    int myHsDoneCb(WOLFSSL* ssl, void* user_ctx){
12717        // callback function
12718    }
12719    …
12720    wolfSSL_SetHsDoneCb(ssl, myHsDoneCb, NULL);
12721    \endcode
12722
12723    \sa HandShakeDoneCb
12724*/
12725int wolfSSL_SetHsDoneCb(WOLFSSL* ssl, HandShakeDoneCb cb, void* user_ctx);
12726
12727/*!
12728    \ingroup IO
12729
12730    \brief This function prints the statistics from the session.
12731
12732    \return SSL_SUCCESS returned if the function and subroutines return without
12733    error. The session stats have been successfully retrieved and printed.
12734    \return BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats()
12735    was passed an unacceptable argument.
12736    \return BAD_MUTEX_E returned if there was a mutex error in the subroutine.
12737
12738    \param none No parameters.
12739
12740    _Example_
12741    \code
12742    // You will need to have a session object to retrieve stats from.
12743    if(wolfSSL_PrintSessionStats(void) != SSL_SUCCESS	){
12744        // Did not print session stats
12745    }
12746
12747    \endcode
12748
12749    \sa wolfSSL_get_session_stats
12750*/
12751int wolfSSL_PrintSessionStats(void);
12752
12753/*!
12754    \ingroup IO
12755
12756    \brief This function gets the statistics for the session.
12757
12758    \return SSL_SUCCESS returned if the function and subroutines return without
12759    error. The session stats have been successfully retrieved and printed.
12760    \return BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats()
12761    was passed an unacceptable argument.
12762    \return BAD_MUTEX_E returned if there was a mutex error in the subroutine.
12763
12764    \param active a word32 pointer representing the total current sessions.
12765    \param total a word32 pointer representing the total sessions.
12766    \param peak a word32 pointer representing the peak sessions.
12767    \param maxSessions a word32 pointer representing the maximum sessions.
12768
12769    _Example_
12770    \code
12771    int wolfSSL_PrintSessionStats(void){
12772    …
12773    ret = wolfSSL_get_session_stats(&totalSessionsNow,
12774    &totalSessionsSeen, &peak, &maxSessions);
12775    …
12776    return ret;
12777    \endcode
12778
12779    \sa wolfSSL_PrintSessionStats
12780*/
12781int wolfSSL_get_session_stats(unsigned int* active,
12782                                          unsigned int* total,
12783                                          unsigned int* peak,
12784                                          unsigned int* maxSessions);
12785
12786/*!
12787    \ingroup TLS
12788
12789    \brief This function copies the values of cr and sr then passes through to
12790    wc_PRF (pseudo random function) and returns that value.
12791
12792    \return 0 on success
12793    \return BUFFER_E returned if there will be an error
12794    with the size of the buffer.
12795    \return MEMORY_E returned if a subroutine failed
12796    to allocate dynamic memory.
12797
12798    \param ms the master secret held in the Arrays structure.
12799    \param msLen the length of the master secret.
12800    \param pms the pre-master secret held in the Arrays structure.
12801    \param pmsLen the length of the pre-master secret.
12802    \param cr the client random.
12803    \param sr the server random.
12804    \param tls1_2 signifies that the version is at least tls version 1.2.
12805    \param hash_type signifies the hash type.
12806
12807    _Example_
12808    \code
12809    WOLFSSL* ssl;
12810
12811    called in MakeTlsMasterSecret and retrieves the necessary
12812    information as follows:
12813
12814    int MakeTlsMasterSecret(WOLFSSL* ssl){
12815	int ret;
12816	ret = wolfSSL_makeTlsMasterSecret(ssl->arrays->masterSecret, SECRET_LEN,
12817    ssl->arrays->preMasterSecret, ssl->arrays->preMasterSz,
12818    ssl->arrays->clientRandom, ssl->arrays->serverRandom,
12819    IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);
12820    …
12821    return ret;
12822
12823    }
12824    \endcode
12825
12826    \sa wc_PRF
12827    \sa MakeTlsMasterSecret
12828*/
12829
12830int wolfSSL_MakeTlsMasterSecret(unsigned char* ms, word32 msLen,
12831                               const unsigned char* pms, word32 pmsLen,
12832                               const unsigned char* cr, const unsigned char* sr,
12833                               int tls1_2, int hash_type);
12834
12835/*!
12836    \ingroup CertsKeys
12837
12838    \brief An external facing wrapper to derive TLS Keys.
12839
12840    \return 0 returned on success.
12841    \return BUFFER_E returned if the sum of labLen and
12842    seedLen (computes total size) exceeds the maximum size.
12843    \return MEMORY_E returned if the allocation of memory failed.
12844
12845    \param key_data a byte pointer that is allocateded in DeriveTlsKeys
12846    and passed through to wc_PRF to hold the final hash.
12847    \param keyLen a word32 type that is derived in DeriveTlsKeys
12848    from the WOLFSSL structure’s specs member.
12849    \param ms a constant pointer type holding the master secret
12850    held in the arrays structure within the WOLFSSL structure.
12851    \param msLen a word32 type that holds the length of the
12852    master secret in an enumerated define, SECRET_LEN.
12853    \param sr a constant byte pointer to the serverRandom
12854    member of the arrays structure within the WOLFSSL structure.
12855    \param cr a constant byte pointer to the clientRandom
12856    member of the arrays structure within the WOLFSSL structure.
12857    \param tls1_2 an integer type returned from IsAtLeastTLSv1_2().
12858    \param hash_type an integer type held in the WOLFSSL structure.
12859
12860    _Example_
12861    \code
12862    int DeriveTlsKeys(WOLFSSL* ssl){
12863    int ret;
12864    …
12865    ret = wolfSSL_DeriveTlsKeys(key_data, length, ssl->arrays->masterSecret,
12866    SECRET_LEN, ssl->arrays->clientRandom,
12867    IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm);
12868    …
12869    }
12870    \endcode
12871
12872    \sa wc_PRF
12873    \sa DeriveTlsKeys
12874    \sa IsAtLeastTLSv1_2
12875*/
12876
12877int wolfSSL_DeriveTlsKeys(unsigned char* key_data, word32 keyLen,
12878                               const unsigned char* ms, word32 msLen,
12879                               const unsigned char* sr, const unsigned char* cr,
12880                               int tls1_2, int hash_type);
12881
12882/*!
12883    \brief wolfSSL_connect_ex() is an extension that allows
12884    a HandShake Callback to be set. This can be useful in
12885    embedded systems for debugging support when a debugger isn’t
12886    available and sniffing is impractical. The HandShake Callback
12887    will be called whether or not a handshake error occurred.
12888    No dynamic memory is used since the maximum number of SSL
12889    packets is known.  Packet names can be accessed through packetNames[].
12890    The connect extension also allows a Timeout Callback to be set along
12891    with a timeout value.  This is useful if the user doesn’t want
12892    to wait for the TCP stack to timeout. This extension can be called
12893    with either, both, or neither callbacks.
12894
12895    \return SSL_SUCCESS upon success.
12896    \return GETTIME_ERROR will be returned if gettimeofday()
12897    encountered an error.
12898    \return SETITIMER_ERROR will be returned if setitimer()
12899    encountered an error.
12900    \return SIGACT_ERROR will be returned if sigaction() encountered an error.
12901    \return SSL_FATAL_ERROR will be returned if the underlying SSL_connect()
12902    call encountered an error.
12903
12904    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
12905    \param hsCb HandShake Callback function pointer.
12906    \param toCb Timeout Callback function pointer.
12907    \param timeout timeout value to use with the Timeout Callback.
12908
12909    _Example_
12910    \code
12911    none
12912    \endcode
12913
12914    \sa wolfSSL_accept_ex
12915*/
12916int wolfSSL_connect_ex(WOLFSSL* ssl, HandShakeCallBack hsCb,
12917                       TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout);
12918
12919/*!
12920    \brief wolfSSL_accept_ex() is an extension that allows a HandShake Callback
12921    to be set. This can be useful in embedded systems for debugging support
12922    when a debugger isn’t available and sniffing is impractical. The HandShake
12923    Callback will be called whether or not a handshake error occurred.
12924    No dynamic memory is used since the maximum number of SSL packets is known.
12925    Packet names can be accessed through packetNames[]. The connect extension
12926    also allows a Timeout Callback to be set along with a timeout value.
12927    This is useful if the user doesn’t want to wait for the TCP stack to timeout.
12928    This extension can be called with either, both, or neither callbacks.
12929
12930    \return SSL_SUCCESS upon success.
12931    \return GETTIME_ERROR will be returned if gettimeofday()
12932    encountered an error.
12933    \return SETITIMER_ERROR will be returned if setitimer()
12934    encountered an error.
12935    \return SIGACT_ERROR will be returned if sigaction() encountered an error.
12936    \return SSL_FATAL_ERROR will be returned if the underlying
12937    SSL_accept() call encountered an error.
12938
12939    \param ssl pointer to a WOLFSSL structure, created using wolfSSL_new().
12940    \param hsCb HandShake Callback function pointer.
12941    \param toCb Timeout Callback function pointer.
12942    \param timeout timeout value to use with the Timeout Callback.
12943
12944    _Example_
12945    \code
12946    none
12947    \endcode
12948
12949    \sa wolfSSL_connect_ex
12950*/
12951int wolfSSL_accept_ex(WOLFSSL* ssl, HandShakeCallBack hsCb,
12952                      TimeoutCallBack toCb, WOLFSSL_TIMEVAL timeout);
12953
12954/*!
12955    \ingroup IO
12956
12957    \brief This is used to set the internal file pointer for a BIO.
12958
12959    \return SSL_SUCCESS On successfully setting file pointer.
12960    \return SSL_FAILURE If an error case was encountered.
12961
12962    \param bio WOLFSSL_BIO structure to set pair.
12963    \param fp file pointer to set in bio.
12964    \param c close file behavior flag.
12965
12966    _Example_
12967    \code
12968    WOLFSSL_BIO* bio;
12969    XFILE fp;
12970    int ret;
12971    bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
12972    ret  = wolfSSL_BIO_set_fp(bio, fp, BIO_CLOSE);
12973    // check ret value
12974    \endcode
12975
12976    \sa wolfSSL_BIO_new
12977    \sa wolfSSL_BIO_s_mem
12978    \sa wolfSSL_BIO_get_fp
12979    \sa wolfSSL_BIO_free
12980*/
12981long wolfSSL_BIO_set_fp(WOLFSSL_BIO *bio, XFILE fp, int c);
12982
12983/*!
12984    \ingroup IO
12985
12986    \brief This is used to get the internal file pointer for a BIO.
12987
12988    \return SSL_SUCCESS On successfully getting file pointer.
12989    \return SSL_FAILURE If an error case was encountered.
12990
12991    \param bio WOLFSSL_BIO structure to set pair.
12992    \param fp file pointer to set in bio.
12993
12994    _Example_
12995    \code
12996    WOLFSSL_BIO* bio;
12997    XFILE fp;
12998    int ret;
12999    bio  = wolfSSL_BIO_new(wolfSSL_BIO_s_file());
13000    ret  = wolfSSL_BIO_get_fp(bio, &fp);
13001    // check ret value
13002    \endcode
13003
13004    \sa wolfSSL_BIO_new
13005    \sa wolfSSL_BIO_s_mem
13006    \sa wolfSSL_BIO_set_fp
13007    \sa wolfSSL_BIO_free
13008*/
13009long wolfSSL_BIO_get_fp(WOLFSSL_BIO *bio, XFILE* fp);
13010
13011/*!
13012    \ingroup Setup
13013
13014    \brief This function checks that the private key is a match
13015    with the certificate being used.
13016
13017    \return SSL_SUCCESS On successfully match.
13018    \return SSL_FAILURE If an error case was encountered.
13019    \return <0 All error cases other than SSL_FAILURE are negative values.
13020
13021    \param ssl WOLFSSL structure to check.
13022
13023    _Example_
13024    \code
13025    WOLFSSL* ssl;
13026    int ret;
13027    // create and set up ssl
13028    ret  = wolfSSL_check_private_key(ssl);
13029    // check ret value
13030    \endcode
13031
13032    \sa wolfSSL_new
13033    \sa wolfSSL_free
13034*/
13035int wolfSSL_check_private_key(const WOLFSSL* ssl);
13036
13037/*!
13038    \ingroup CertsKeys
13039
13040    \brief This function looks for and returns the extension index
13041    matching the passed in NID value.
13042
13043    \return >= 0 If successful the extension index is returned.
13044    \return -1 If extension is not found or error is encountered.
13045
13046    \param x certificate to get parse through for extension.
13047    \param nid extension OID to be found.
13048    \param lastpos start search from extension after lastpos.
13049                   Set to -1 initially.
13050
13051    _Example_
13052    \code
13053    const WOLFSSL_X509* x509;
13054    int lastPos = -1;
13055    int idx;
13056
13057    idx = wolfSSL_X509_get_ext_by_NID(x509, NID_basic_constraints, lastPos);
13058    \endcode
13059
13060*/
13061int wolfSSL_X509_get_ext_by_NID(const WOLFSSL_X509 *x, int nid, int lastpos);
13062
13063/*!
13064    \ingroup CertsKeys
13065
13066    \brief This function looks for and returns the extension
13067    matching the passed in NID value.
13068
13069    \return pointer If successful a STACK_OF(WOLFSSL_ASN1_OBJECT)
13070    pointer is returned.
13071    \return NULL If extension is not found or error is encountered.
13072
13073    \param x509 certificate to get parse through for extension.
13074    \param nid extension OID to be found.
13075    \param c if not NULL is set to -2 for multiple extensions found -1
13076    if not found, 0 if found and not critical and 1 if found and critical.
13077    \param idx if NULL return first extension matched otherwise if not
13078    stored in x509 start at idx.
13079
13080    _Example_
13081    \code
13082    const WOLFSSL_X509* x509;
13083    int c;
13084    int idx = 0;
13085    STACK_OF(WOLFSSL_ASN1_OBJECT)* sk;
13086
13087    sk = wolfSSL_X509_get_ext_d2i(x509, NID_basic_constraints, &c, &idx);
13088    //check sk for NULL and then use it. sk needs freed after done.
13089    \endcode
13090
13091    \sa wolfSSL_sk_ASN1_OBJECT_free
13092*/
13093void* wolfSSL_X509_get_ext_d2i(const WOLFSSL_X509* x509,
13094                                                     int nid, int* c, int* idx);
13095
13096/*!
13097    \ingroup CertsKeys
13098
13099    \brief This function returns the hash of the DER certificate.
13100
13101    \return SSL_SUCCESS On successfully creating a hash.
13102    \return SSL_FAILURE Returned on bad input or unsuccessful hash.
13103
13104    \param x509 certificate to get the hash of.
13105    \param digest the hash algorithm to use.
13106    \param buf buffer to hold hash.
13107    \param len length of buffer.
13108
13109    _Example_
13110    \code
13111    WOLFSSL_X509* x509;
13112    unsigned char buffer[64];
13113    unsigned int bufferSz;
13114    int ret;
13115
13116    ret = wolfSSL_X509_digest(x509, wolfSSL_EVP_sha256(), buffer, &bufferSz);
13117    //check ret value
13118    \endcode
13119
13120    \sa none
13121*/
13122int wolfSSL_X509_digest(const WOLFSSL_X509* x509,
13123        const WOLFSSL_EVP_MD* digest, unsigned char* buf, unsigned int* len);
13124
13125/*!
13126    \ingroup Setup
13127
13128    \brief his is used to set the certificate for WOLFSSL structure to use
13129    during a handshake.
13130
13131    \return SSL_SUCCESS On successful setting argument.
13132    \return SSL_FAILURE If a NULL argument passed in.
13133
13134    \param ssl WOLFSSL structure to set certificate in.
13135    \param x509 certificate to use.
13136
13137    _Example_
13138    \code WOLFSSL* ssl;
13139    WOLFSSL_X509* x509
13140    int ret;
13141    // create ssl object and x509
13142    ret  = wolfSSL_use_certificate(ssl, x509);
13143    // check ret value
13144    \endcode
13145
13146    \sa wolfSSL_new
13147    \sa wolfSSL_free
13148*/
13149int wolfSSL_use_certificate(WOLFSSL* ssl, WOLFSSL_X509* x509);
13150
13151/*!
13152    \ingroup Setup
13153
13154    \brief This is used to set the certificate for WOLFSSL structure
13155    to use during a handshake. A DER formatted buffer is expected.
13156
13157    \return SSL_SUCCESS On successful setting argument.
13158    \return SSL_FAILURE If a NULL argument passed in.
13159
13160    \param ssl WOLFSSL structure to set certificate in.
13161    \param der DER certificate to use.
13162    \param derSz size of the DER buffer passed in.
13163
13164    _Example_
13165    \code
13166    WOLFSSL* ssl;
13167    unsigned char* der;
13168    int derSz;
13169    int ret;
13170    // create ssl object and set DER variables
13171    ret  = wolfSSL_use_certificate_ASN1(ssl, der, derSz);
13172    // check ret value
13173    \endcode
13174
13175    \sa wolfSSL_new
13176    \sa wolfSSL_free
13177*/
13178int wolfSSL_use_certificate_ASN1(WOLFSSL* ssl, const unsigned char* der,
13179                                 int derSz);
13180
13181/*!
13182    \ingroup CertsKeys
13183
13184    \brief This is used to set the private key for the WOLFSSL structure.
13185
13186    \return SSL_SUCCESS On successful setting argument.
13187    \return SSL_FAILURE If a NULL ssl passed in. All error
13188    cases will be negative values.
13189
13190    \param ssl WOLFSSL structure to set argument in.
13191    \param pkey private key to use.
13192
13193    _Example_
13194    \code
13195    WOLFSSL* ssl;
13196    WOLFSSL_EVP_PKEY* pkey;
13197    int ret;
13198    // create ssl object and set up private key
13199    ret  = wolfSSL_use_PrivateKey(ssl, pkey);
13200    // check ret value
13201    \endcode
13202
13203    \sa wolfSSL_new
13204    \sa wolfSSL_free
13205*/
13206int wolfSSL_use_PrivateKey(WOLFSSL* ssl, WOLFSSL_EVP_PKEY* pkey);
13207
13208/*!
13209    \ingroup CertsKeys
13210
13211    \brief This is used to set the private key for the WOLFSSL
13212    structure. A DER formatted key buffer is expected.
13213
13214    \return SSL_SUCCESS On successful setting parsing and
13215    setting the private key.
13216    \return SSL_FAILURE If an NULL ssl passed in. All error cases
13217    will be negative values.
13218
13219    \param pri type of private key.
13220    \param ssl WOLFSSL structure to set argument in.
13221    \param der buffer holding DER key.
13222    \param derSz size of der buffer.
13223
13224    _Example_
13225    \code
13226    WOLFSSL* ssl;
13227    unsigned char* pkey;
13228    long pkeySz;
13229    int ret;
13230    // create ssl object and set up private key
13231    ret  = wolfSSL_use_PrivateKey_ASN1(1, ssl, pkey, pkeySz);
13232    // check ret value
13233    \endcode
13234
13235    \sa wolfSSL_new
13236    \sa wolfSSL_free
13237    \sa wolfSSL_use_PrivateKey
13238*/
13239int wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL* ssl,
13240                        const unsigned char* der, long derSz);
13241
13242/*!
13243    \ingroup CertsKeys
13244
13245    \brief This is used to set the private key for the WOLFSSL
13246    structure. A DER formatted RSA key buffer is expected.
13247
13248    \return SSL_SUCCESS On successful setting parsing and setting
13249    the private key.
13250    \return SSL_FAILURE If an NULL ssl passed in. All error cases
13251    will be negative values.
13252
13253    \param ssl WOLFSSL structure to set argument in.
13254    \param der buffer holding DER key.
13255    \param derSz size of der buffer.
13256
13257    _Example_
13258    \code
13259    WOLFSSL* ssl;
13260    unsigned char* pkey;
13261    long pkeySz;
13262    int ret;
13263    // create ssl object and set up RSA private key
13264    ret  = wolfSSL_use_RSAPrivateKey_ASN1(ssl, pkey, pkeySz);
13265    // check ret value
13266    \endcode
13267
13268    \sa wolfSSL_new
13269    \sa wolfSSL_free
13270    \sa wolfSSL_use_PrivateKey
13271*/
13272int wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL* ssl, unsigned char* der,
13273                                                                long derSz);
13274
13275/*!
13276    \ingroup CertsKeys
13277
13278    \brief This function duplicates the parameters in dsa to a
13279    newly created WOLFSSL_DH structure.
13280
13281    \return WOLFSSL_DH If duplicated returns WOLFSSL_DH structure
13282    \return NULL upon failure
13283
13284    \param dsa WOLFSSL_DSA structure to duplicate.
13285
13286    _Example_
13287    \code
13288    WOLFSSL_DH* dh;
13289    WOLFSSL_DSA* dsa;
13290    // set up dsa
13291    dh = wolfSSL_DSA_dup_DH(dsa);
13292
13293    // check dh is not null
13294    \endcode
13295
13296    \sa none
13297*/
13298WOLFSSL_DH *wolfSSL_DSA_dup_DH(const WOLFSSL_DSA *r);
13299
13300/*!
13301    \ingroup Setup
13302
13303    \brief This is used to get the master key after completing a handshake.
13304
13305    \return >0 On successfully getting data returns a value greater than 0
13306    \return 0  If no random data buffer or an error state returns 0
13307    \return max If outSz passed in is 0 then the maximum buffer
13308    size needed is returned
13309
13310    \param ses WOLFSSL_SESSION structure to get master secret buffer from.
13311    \param out buffer to hold data.
13312    \param outSz size of out buffer passed in. (if 0 function will
13313    return max buffer size needed)
13314
13315    _Example_
13316    \code
13317    WOLFSSL_SESSION ssl;
13318    unsigned char* buffer;
13319    size_t bufferSz;
13320    size_t ret;
13321    // complete handshake and get session structure
13322    bufferSz  = wolfSSL_SESSION_get_master_secret(ses, NULL, 0);
13323    buffer = malloc(bufferSz);
13324    ret  = wolfSSL_SESSION_get_master_secret(ses, buffer, bufferSz);
13325    // check ret value
13326    \endcode
13327
13328    \sa wolfSSL_new
13329    \sa wolfSSL_free
13330*/
13331int wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION* ses,
13332        unsigned char* out, int outSz);
13333
13334/*!
13335    \ingroup Setup
13336
13337    \brief This is used to get the master secret key length.
13338
13339    \return size Returns master secret key size.
13340
13341    \param ses WOLFSSL_SESSION structure to get master secret buffer from.
13342
13343    _Example_
13344    \code
13345    WOLFSSL_SESSION ssl;
13346    unsigned char* buffer;
13347    size_t bufferSz;
13348    size_t ret;
13349    // complete handshake and get session structure
13350    bufferSz  = wolfSSL_SESSION_get_master_secret_length(ses);
13351    buffer = malloc(bufferSz);
13352    // check ret value
13353    \endcode
13354
13355    \sa wolfSSL_new
13356    \sa wolfSSL_free
13357*/
13358int wolfSSL_SESSION_get_master_key_length(const WOLFSSL_SESSION* ses);
13359
13360/*!
13361    \ingroup Setup
13362
13363    \brief This is a setter function for the WOLFSSL_X509_STORE
13364    structure in ctx.
13365
13366    \return none No return.
13367
13368    \param ctx pointer to the WOLFSSL_CTX structure for setting
13369    cert store pointer.
13370    \param str pointer to the WOLFSSL_X509_STORE to set in ctx.
13371
13372    _Example_
13373    \code
13374    WOLFSSL_CTX ctx;
13375    WOLFSSL_X509_STORE* st;
13376    // setup ctx and st
13377    st = wolfSSL_CTX_set_cert_store(ctx, st);
13378    //use st
13379    \endcode
13380
13381    \sa wolfSSL_CTX_new
13382    \sa wolfSSL_CTX_free
13383*/
13384void wolfSSL_CTX_set_cert_store(WOLFSSL_CTX* ctx,
13385                                                       WOLFSSL_X509_STORE* str);
13386
13387/*!
13388    \ingroup CertsKeys
13389
13390    \brief This function get the DER buffer from bio and converts it
13391    to a WOLFSSL_X509 structure.
13392
13393    \return pointer returns a WOLFSSL_X509 structure pointer on success.
13394    \return Null returns NULL on failure
13395
13396    \param bio pointer to the WOLFSSL_BIO structure that has the DER
13397    certificate buffer.
13398    \param x509 pointer that get set to new WOLFSSL_X509 structure created.
13399
13400    _Example_
13401    \code
13402    WOLFSSL_BIO* bio;
13403    WOLFSSL_X509* x509;
13404    // load DER into bio
13405    x509 = wolfSSL_d2i_X509_bio(bio, NULL);
13406    Or
13407    wolfSSL_d2i_X509_bio(bio, &x509);
13408    // use x509 returned (check for NULL)
13409    \endcode
13410
13411    \sa none
13412*/
13413WOLFSSL_X509* wolfSSL_d2i_X509_bio(WOLFSSL_BIO* bio, WOLFSSL_X509** x509);
13414
13415/*!
13416    \ingroup Setup
13417
13418    \brief This is a getter function for the WOLFSSL_X509_STORE
13419    structure in ctx.
13420
13421    \return WOLFSSL_X509_STORE* On successfully getting the pointer.
13422    \return NULL Returned if NULL arguments are passed in.
13423
13424    \param ctx pointer to the WOLFSSL_CTX structure for getting cert
13425    store pointer.
13426
13427    _Example_
13428    \code
13429    WOLFSSL_CTX ctx;
13430    WOLFSSL_X509_STORE* st;
13431    // setup ctx
13432    st = wolfSSL_CTX_get_cert_store(ctx);
13433    //use st
13434    \endcode
13435
13436    \sa wolfSSL_CTX_new
13437    \sa wolfSSL_CTX_free
13438    \sa wolfSSL_CTX_set_cert_store
13439*/
13440WOLFSSL_X509_STORE* wolfSSL_CTX_get_cert_store(WOLFSSL_CTX* ctx);
13441
13442/*!
13443    \ingroup IO
13444
13445    \brief Gets the number of pending bytes to read. If BIO type is BIO_BIO
13446    then is the number to read from pair. If BIO contains an SSL object then
13447    is pending data from SSL object (wolfSSL_pending(ssl)). If is BIO_MEMORY
13448    type then returns the size of memory buffer.
13449
13450    \return >=0 number of pending bytes.
13451
13452    \param bio pointer to the WOLFSSL_BIO structure that has already
13453    been created.
13454
13455    _Example_
13456    \code
13457    WOLFSSL_BIO* bio;
13458    int pending;
13459    bio = wolfSSL_BIO_new();
13460    …
13461    pending = wolfSSL_BIO_ctrl_pending(bio);
13462    \endcode
13463
13464    \sa wolfSSL_BIO_make_bio_pair
13465    \sa wolfSSL_BIO_new
13466*/
13467size_t wolfSSL_BIO_ctrl_pending(WOLFSSL_BIO *b);
13468
13469/*!
13470    \ingroup Setup
13471
13472    \brief This is used to get the random data sent by the server
13473    during the handshake.
13474
13475    \return >0 On successfully getting data returns a value greater than 0
13476    \return 0  If no random data buffer or an error state returns 0
13477    \return max If outSz passed in is 0 then the maximum buffer size
13478    needed is returned
13479
13480    \param ssl WOLFSSL structure to get clients random data buffer from.
13481    \param out buffer to hold random data.
13482    \param outSz size of out buffer passed in. (if 0 function will return max
13483    buffer size needed)
13484
13485    _Example_
13486    \code
13487    WOLFSSL ssl;
13488    unsigned char* buffer;
13489    size_t bufferSz;
13490    size_t ret;
13491    bufferSz  = wolfSSL_get_server_random(ssl, NULL, 0);
13492    buffer = malloc(bufferSz);
13493    ret  = wolfSSL_get_server_random(ssl, buffer, bufferSz);
13494    // check ret value
13495    \endcode
13496
13497    \sa wolfSSL_new
13498    \sa wolfSSL_free
13499*/
13500size_t wolfSSL_get_server_random(const WOLFSSL *ssl,
13501                                             unsigned char *out, size_t outlen);
13502
13503/*!
13504    \ingroup Setup
13505
13506    \brief This is used to get the random data sent by the client during
13507    the handshake.
13508
13509    \return >0 On successfully getting data returns a value greater than 0
13510    \return 0 If no random data buffer or an error state returns 0
13511    \return max If outSz passed in is 0 then the maximum buffer size needed
13512    is returned
13513
13514    \param ssl WOLFSSL structure to get clients random data buffer from.
13515    \param out buffer to hold random data.
13516    \param outSz size of out buffer passed in. (if 0 function will return max
13517    buffer size needed)
13518
13519    _Example_
13520    \code
13521    WOLFSSL ssl;
13522    unsigned char* buffer;
13523    size_t bufferSz;
13524    size_t ret;
13525    bufferSz  = wolfSSL_get_client_random(ssl, NULL, 0);
13526    buffer = malloc(bufferSz);
13527    ret  = wolfSSL_get_client_random(ssl, buffer, bufferSz);
13528    // check ret value
13529    \endcode
13530
13531    \sa wolfSSL_new
13532    \sa wolfSSL_free
13533*/
13534size_t wolfSSL_get_client_random(const WOLFSSL* ssl,
13535                                              unsigned char* out, size_t outSz);
13536
13537/*!
13538    \ingroup Setup
13539
13540    \brief This is a getter function for the password callback set in ctx.
13541
13542    \return func On success returns the callback function.
13543    \return NULL If ctx is NULL then NULL is returned.
13544
13545    \param ctx WOLFSSL_CTX structure to get call back from.
13546
13547    _Example_
13548    \code
13549    WOLFSSL_CTX* ctx;
13550    wc_pem_password_cb cb;
13551    // setup ctx
13552    cb = wolfSSL_CTX_get_default_passwd_cb(ctx);
13553    //use cb
13554    \endcode
13555
13556    \sa wolfSSL_CTX_new
13557    \sa wolfSSL_CTX_free
13558*/
13559wc_pem_password_cb* wolfSSL_CTX_get_default_passwd_cb(WOLFSSL_CTX*
13560                                                                  ctx);
13561
13562/*!
13563    \ingroup Setup
13564
13565    \brief This is a getter function for the password callback user
13566    data set in ctx.
13567
13568    \return pointer On success returns the user data pointer.
13569    \return NULL If ctx is NULL then NULL is returned.
13570
13571    \param ctx WOLFSSL_CTX structure to get user data from.
13572
13573    _Example_
13574    \code
13575    WOLFSSL_CTX* ctx;
13576    void* data;
13577    // setup ctx
13578    data = wolfSSL_CTX_get_default_passwd_cb(ctx);
13579    //use data
13580    \endcode
13581
13582    \sa wolfSSL_CTX_new
13583    \sa wolfSSL_CTX_free
13584*/
13585void *wolfSSL_CTX_get_default_passwd_cb_userdata(WOLFSSL_CTX *ctx);
13586
13587/*!
13588    \ingroup CertsKeys
13589
13590    \brief This function behaves the same as wolfSSL_PEM_read_bio_X509.
13591    AUX signifies containing extra information such as trusted/rejected use
13592    cases and friendly name for human readability.
13593
13594    \return WOLFSSL_X509 on successfully parsing the PEM buffer a WOLFSSL_X509
13595    structure is returned.
13596    \return Null if failed to parse PEM buffer.
13597
13598    \param bp WOLFSSL_BIO structure to get PEM buffer from.
13599    \param x if setting WOLFSSL_X509 by function side effect.
13600    \param cb password callback.
13601    \param u NULL terminated user password.
13602
13603    _Example_
13604    \code
13605    WOLFSSL_BIO* bio;
13606    WOLFSSL_X509* x509;
13607    // setup bio
13608    X509 = wolfSSL_PEM_read_bio_X509_AUX(bio, NULL, NULL, NULL);
13609    //check x509 is not null and then use it
13610    \endcode
13611
13612    \sa wolfSSL_PEM_read_bio_X509
13613*/
13614WOLFSSL_X509 *wolfSSL_PEM_read_bio_X509_AUX
13615        (WOLFSSL_BIO *bp, WOLFSSL_X509 **x, wc_pem_password_cb *cb, void *u);
13616
13617/*!
13618    \ingroup CertsKeys
13619
13620    \brief Initializes the WOLFSSL_CTX structure’s dh member with the
13621    Diffie-Hellman parameters.
13622
13623    \return SSL_SUCCESS returned if the function executed successfully.
13624    \return BAD_FUNC_ARG returned if the ctx or dh structures are NULL.
13625    \return SSL_FATAL_ERROR returned if there was an error setting a
13626    structure value.
13627    \return MEMORY_E returned if their was a failure to allocate memory.
13628
13629    \param ctx a pointer to a WOLFSSL_CTX structure, created using
13630    wolfSSL_CTX_new().
13631    \param dh a pointer to a WOLFSSL_DH structure.
13632
13633    _Example_
13634    \code
13635    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
13636    WOLFSSL_DH* dh;
13637    …
13638    return wolfSSL_CTX_set_tmp_dh(ctx, dh);
13639    \endcode
13640
13641    \sa wolfSSL_BN_bn2bin
13642*/
13643long wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX* ctx, WOLFSSL_DH* dh);
13644
13645/*!
13646    \ingroup CertsKeys
13647
13648    \brief This function get the DSA parameters from a PEM buffer in bio.
13649
13650    \return WOLFSSL_DSA on successfully parsing the PEM buffer a WOLFSSL_DSA
13651    structure is created and returned.
13652    \return Null if failed to parse PEM buffer.
13653
13654    \param bio pointer to the WOLFSSL_BIO structure for getting PEM
13655    memory pointer.
13656    \param x pointer to be set to new WOLFSSL_DSA structure.
13657    \param cb password callback function.
13658    \param u null terminated password string.
13659
13660    _Example_
13661    \code
13662    WOLFSSL_BIO* bio;
13663    WOLFSSL_DSA* dsa;
13664    // setup bio
13665    dsa = wolfSSL_PEM_read_bio_DSAparams(bio, NULL, NULL, NULL);
13666
13667    // check dsa is not NULL and then use dsa
13668    \endcode
13669
13670    \sa none
13671*/
13672WOLFSSL_DSA *wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO *bp,
13673    WOLFSSL_DSA **x, wc_pem_password_cb *cb, void *u);
13674
13675/*!
13676    \ingroup Debug
13677
13678    \brief This function returns the absolute value of the last error from
13679    WOLFSSL_ERROR encountered.
13680
13681    \return error Returns absolute value of last error.
13682
13683    \param none No parameters.
13684
13685    _Example_
13686    \code
13687    unsigned long err;
13688    ...
13689    err = wolfSSL_ERR_peek_last_error();
13690    // inspect err value
13691    \endcode
13692
13693    \sa wolfSSL_ERR_print_errors_fp
13694*/
13695unsigned long wolfSSL_ERR_peek_last_error(void);
13696
13697/*!
13698    \ingroup CertsKeys
13699
13700    \brief This function gets the peer’s certificate chain.
13701
13702    \return pointer returns a pointer to the peer’s Certificate stack.
13703    \return NULL returned if no peer certificate.
13704
13705    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
13706
13707    _Example_
13708    \code
13709    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
13710    WOLFSSL* ssl = wolfSSL_new(ctx);
13711    ...
13712    wolfSSL_connect(ssl);
13713    STACK_OF(WOLFSSL_X509)* chain = wolfSSL_get_peer_cert_chain(ssl);
13714    ifchain){
13715	    // You have a pointer to the peer certificate chain
13716    }
13717    \endcode
13718
13719    \sa wolfSSL_X509_get_issuer_name
13720    \sa wolfSSL_X509_get_subject_name
13721    \sa wolfSSL_X509_get_isCA
13722*/
13723WOLF_STACK_OF(WOLFSSL_X509)* wolfSSL_get_peer_cert_chain(const WOLFSSL*);
13724
13725/*!
13726    \ingroup Setup
13727
13728    \brief This function resets option bits of WOLFSSL_CTX object.
13729
13730    \return option new option bits
13731
13732    \param ctx pointer to the SSL context.
13733
13734    _Example_
13735    \code
13736    WOLFSSL_CTX* ctx = 0;
13737    ...
13738    wolfSSL_CTX_clear_options(ctx, SSL_OP_NO_TLSv1);
13739    \endcode
13740
13741    \sa wolfSSL_CTX_new
13742    \sa wolfSSL_new
13743    \sa wolfSSL_free
13744*/
13745long wolfSSL_CTX_clear_options(WOLFSSL_CTX* ctx, long opt);
13746
13747/*!
13748    \ingroup IO
13749
13750    \brief This function sets the jObjectRef member of the WOLFSSL structure.
13751
13752    \return SSL_SUCCESS returned if jObjectRef is properly set to objPtr.
13753    \return SSL_FAILURE returned if the function did not properly execute and
13754    jObjectRef is not set.
13755
13756    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
13757    \param objPtr a void pointer that will be set to jObjectRef.
13758
13759    _Example_
13760    \code
13761    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
13762    WOLFSSL* ssl = WOLFSSL_new();
13763    void* objPtr = &obj;
13764    ...
13765    if(wolfSSL_set_jobject(ssl, objPtr)){
13766    	// The success case
13767    }
13768    \endcode
13769
13770    \sa wolfSSL_get_jobject
13771*/
13772int wolfSSL_set_jobject(WOLFSSL* ssl, void* objPtr);
13773
13774/*!
13775    \ingroup IO
13776
13777    \brief This function returns the jObjectRef member of the WOLFSSL structure.
13778
13779    \return value If the WOLFSSL struct is not NULL, the function returns the
13780    jObjectRef value.
13781    \return NULL returned if the WOLFSSL struct is NULL.
13782
13783    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
13784
13785    _Example_
13786    \code
13787    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
13788    WOLFSSL* ssl = wolfSSL(ctx);
13789    ...
13790    void* jobject = wolfSSL_get_jobject(ssl);
13791
13792    if(jobject != NULL){
13793    	// Success case
13794    }
13795    \endcode
13796
13797    \sa wolfSSL_set_jobject
13798*/
13799void* wolfSSL_get_jobject(WOLFSSL* ssl);
13800
13801/*!
13802    \ingroup Setup
13803
13804    \brief This function sets a callback in the ssl. The callback is to
13805    observe handshake messages. NULL value of cb resets the callback.
13806
13807    \return SSL_SUCCESS On success.
13808    \return SSL_FAILURE If an NULL ssl passed in.
13809
13810    \param ssl WOLFSSL structure to set callback argument.
13811
13812    _Example_
13813    \code
13814    static cb(int write_p, int version, int content_type,
13815    const void *buf, size_t len, WOLFSSL *ssl, void *arg)
13816    …
13817    WOLFSSL* ssl;
13818    ret  = wolfSSL_set_msg_callback(ssl, cb);
13819    // check ret
13820    \endcode
13821
13822    \sa wolfSSL_set_msg_callback_arg
13823*/
13824int wolfSSL_set_msg_callback(WOLFSSL *ssl, SSL_Msg_Cb cb);
13825
13826/*!
13827    \ingroup Setup
13828
13829    \brief This function sets associated callback context value in the ssl.
13830    The value is handed over to the callback argument.
13831
13832    \return none No return.
13833
13834    \param ssl WOLFSSL structure to set callback argument.
13835
13836    _Example_
13837    \code
13838    static cb(int write_p, int version, int content_type,
13839    const void *buf, size_t len, WOLFSSL *ssl, void *arg)
13840    …
13841    WOLFSSL* ssl;
13842    ret  = wolfSSL_set_msg_callback(ssl, cb);
13843    // check ret
13844    wolfSSL_set_msg_callback(ssl, arg);
13845    \endcode
13846
13847    \sa wolfSSL_set_msg_callback
13848*/
13849int wolfSSL_set_msg_callback_arg(WOLFSSL *ssl, void* arg);
13850
13851/*!
13852    \ingroup CertsKeys
13853
13854    \brief This function returns the next, if any, altname from the peer certificate.
13855
13856    \return NULL if there is not a next altname.
13857    \return cert->altNamesNext->name from the WOLFSSL_X509 structure that is a
13858    string value from the altName list is returned if it exists.
13859
13860    \param cert a pointer to the wolfSSL_X509 structure.
13861
13862    _Example_
13863    \code
13864    WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL,
13865                                                        DYNAMIC_TYPE_X509);
13866    …
13867    int x509NextAltName = wolfSSL_X509_get_next_altname(x509);
13868    if(x509NextAltName == NULL){
13869            //There isn’t another alt name
13870    }
13871    \endcode
13872
13873    \sa wolfSSL_X509_get_issuer_name
13874    \sa wolfSSL_X509_get_subject_name
13875*/
13876char* wolfSSL_X509_get_next_altname(WOLFSSL_X509*);
13877
13878/*!
13879    \ingroup CertsKeys
13880
13881    \brief The function checks to see if x509 is NULL and if it’s not, it
13882    returns the notBefore member of the x509 struct.
13883
13884    \return pointer to struct with ASN1_TIME to the notBefore
13885        member of the x509 struct.
13886    \return NULL the function returns NULL if the x509 structure is NULL.
13887
13888    \param x509 a pointer to the WOLFSSL_X509 struct.
13889
13890    _Example_
13891    \code
13892    WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALLOC(sizeof(WOLFSSL_X509), NULL,
13893    DYNAMIC_TYPE_X509) ;
13894    …
13895    const WOLFSSL_ASN1_TIME* notAfter = wolfSSL_X509_get_notBefore(x509);
13896    if(notAfter == NULL){
13897            //The x509 object was NULL
13898    }
13899    \endcode
13900
13901    \sa wolfSSL_X509_get_notAfter
13902*/
13903WOLFSSL_ASN1_TIME* wolfSSL_X509_get_notBefore(WOLFSSL_X509*);
13904
13905/*!
13906    \ingroup IO
13907
13908    \brief This function is called on the client side and initiates an SSL/TLS
13909    handshake with a server.  When this function is called, the underlying
13910    communication channel has already been set up.
13911    wolfSSL_connect() works with both blocking and non-blocking I/O.  When the
13912    underlying I/O is non-blocking, wolfSSL_connect() will return when the
13913    underlying I/O could not satisfy the needs of wolfSSL_connect to continue
13914    the handshake.  In this case, a call to wolfSSL_get_error() will yield
13915    either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.  The calling process
13916    must then repeat the call to wolfSSL_connect() when the underlying I/O is
13917    ready and wolfSSL will pick up where it left off. When using a non-blocking
13918    socket, nothing needs to be done, but select() can be used to check for the
13919    required condition.
13920    If the underlying I/O is blocking, wolfSSL_connect() will only return once
13921    the handshake has been finished or an error occurred.
13922    wolfSSL takes a different approach to certificate verification than OpenSSL
13923    does.  The default policy for the client is to verify the server, this
13924    means that if you don't load CAs to verify the server you'll get a connect
13925    error, unable to verify (-155).  It you want to mimic OpenSSL behavior of
13926    having SSL_connect succeed even if verifying the server fails and reducing
13927    security you can do this by calling:
13928    SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new();
13929    Though it's not recommended.
13930
13931    \return SSL_SUCCESS If successful.
13932    \return SSL_FATAL_ERROR will be returned if an error occurred.  To get a
13933    more detailed error code, call wolfSSL_get_error().
13934
13935    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
13936
13937    _Example_
13938    \code
13939    int ret = 0;
13940    int err = 0;
13941    WOLFSSL* ssl;
13942    char buffer[80];
13943    ...
13944    ret = wolfSSL_connect(ssl);
13945    if (ret != SSL_SUCCESS) {
13946    err = wolfSSL_get_error(ssl, ret);
13947    printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
13948    }
13949    \endcode
13950
13951    \sa wolfSSL_get_error
13952    \sa wolfSSL_accept
13953*/
13954int  wolfSSL_connect(WOLFSSL* ssl);
13955
13956/*!
13957    \ingroup Setup
13958
13959    \brief This function is called on the server side to indicate that a
13960    HelloRetryRequest message must contain a Cookie and, in case of using
13961    protocol DTLS v1.3, that the handshake will always include a cookie
13962    exchange. Please note that when using protocol DTLS v1.3, the cookie
13963    exchange is enabled by default. The Cookie holds a hash of the current
13964    transcript so that another server process can handle the ClientHello in
13965    reply.  The secret is used when generating the integrity check on the Cookie
13966    data.
13967
13968    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
13969    \param [in] secret a pointer to a buffer holding the secret.
13970    Passing NULL indicates to generate a new random secret.
13971    \param [in] secretSz Size of the secret in bytes.
13972    Passing 0 indicates to use the default size: WC_SHA256_DIGEST_SIZE (or WC_SHA_DIGEST_SIZE when SHA-256 not available).
13973
13974    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
13975    \return SIDE_ERROR if called with a client.
13976    \return WOLFSSL_SUCCESS if successful.
13977    \return MEMORY_ERROR if allocating dynamic memory for storing secret failed.
13978    \return Another -ve value on internal error.
13979
13980    _Example_
13981    \code
13982    int ret;
13983    WOLFSSL* ssl;
13984    char secret[32];
13985    ...
13986    ret = wolfSSL__send_hrr_cookie(ssl, secret, sizeof(secret));
13987    if (ret != WOLFSSL_SUCCESS) {
13988        // failed to set use of Cookie and secret
13989    }
13990    \endcode
13991
13992    \sa wolfSSL_new
13993    \sa wolfSSL_disable_hrr_cookie
13994*/
13995int  wolfSSL_send_hrr_cookie(WOLFSSL* ssl,
13996    const unsigned char* secret, unsigned int secretSz);
13997
13998/*!
13999
14000    \ingroup Setup
14001
14002    \brief This function is called on the server side to indicate that a
14003    HelloRetryRequest message must NOT contain a Cookie and that, if using
14004    protocol DTLS v1.3, a cookie exchange will not be included in the
14005    handshake. Please note that not doing a cookie exchange when using protocol
14006    DTLS v1.3 can make the server susceptible to DoS/Amplification attacks.
14007
14008    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14009
14010    \return WOLFSSL_SUCCESS if successful
14011    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3
14012    \return SIDE_ERROR if invoked on client
14013
14014    \sa wolfSSL_send_hrr_cookie
14015*/
14016int wolfSSL_disable_hrr_cookie(WOLFSSL* ssl);
14017
14018/*!
14019    \ingroup Setup
14020
14021    \brief This function is called on the server to stop it from sending
14022    a resumption session ticket once the handshake is complete.
14023
14024    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
14025    with wolfSSL_CTX_new().
14026
14027    \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
14028    \return SIDE_ERROR if called with a client.
14029    \return 0 if successful.
14030
14031    _Example_
14032    \code
14033    int ret;
14034    WOLFSSL_CTX* ctx;
14035    ...
14036    ret = wolfSSL_CTX_no_ticket_TLSv13(ctx);
14037    if (ret != 0) {
14038        // failed to set no ticket
14039    }
14040    \endcode
14041
14042    \sa wolfSSL_no_ticket_TLSv13
14043*/
14044int  wolfSSL_CTX_no_ticket_TLSv13(WOLFSSL_CTX* ctx);
14045
14046/*!
14047    \ingroup Setup
14048
14049    \brief This function is called on the server to stop it from sending
14050    a resumption session ticket once the handshake is complete.
14051
14052    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14053
14054    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14055    \return SIDE_ERROR if called with a client.
14056    \return 0 if successful.
14057
14058    _Example_
14059    \code
14060    int ret;
14061    WOLFSSL* ssl;
14062    ...
14063    ret = wolfSSL_no_ticket_TLSv13(ssl);
14064    if (ret != 0) {
14065        // failed to set no ticket
14066    }
14067    \endcode
14068
14069    \sa wolfSSL_CTX_no_ticket_TLSv13
14070*/
14071int  wolfSSL_no_ticket_TLSv13(WOLFSSL* ssl);
14072
14073/*!
14074    \ingroup Setup
14075
14076    \brief This function is called on a TLS v1.3 wolfSSL context to disallow
14077    Diffie-Hellman (DH) style key exchanges when handshakes are using
14078    pre-shared keys for authentication.
14079
14080    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
14081    with wolfSSL_CTX_new().
14082
14083    \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
14084    \return 0 if successful.
14085
14086    _Example_
14087    \code
14088    int ret;
14089    WOLFSSL_CTX* ctx;
14090    ...
14091    ret = wolfSSL_CTX_no_dhe_psk(ctx);
14092    if (ret != 0) {
14093        // failed to set no DHE for PSK handshakes
14094    }
14095    \endcode
14096
14097    \sa wolfSSL_no_dhe_psk
14098*/
14099int  wolfSSL_CTX_no_dhe_psk(WOLFSSL_CTX* ctx);
14100
14101/*!
14102    \ingroup Setup
14103
14104    \brief This function is called on a TLS v1.3 client or server wolfSSL to
14105    disallow Diffie-Hellman (DH) style key exchanges when handshakes are using
14106    pre-shared keys for authentication.
14107
14108    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14109
14110    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14111    \return 0 if successful.
14112
14113    _Example_
14114    \code
14115    int ret;
14116    WOLFSSL* ssl;
14117    ...
14118    ret = wolfSSL_no_dhe_psk(ssl);
14119    if (ret != 0) {
14120        // failed to set no DHE for PSK handshakes
14121    }
14122    \endcode
14123
14124    \sa wolfSSL_CTX_no_dhe_psk
14125*/
14126int  wolfSSL_no_dhe_psk(WOLFSSL* ssl);
14127
14128/*!
14129    \ingroup IO
14130
14131    \brief This function is called on a TLS v1.3 client or server wolfSSL to
14132    force the rollover of keys. A KeyUpdate message is sent to the peer and
14133    new keys are calculated for encryption. The peer will send back a KeyUpdate
14134    message and the new decryption keys will then be calculated.
14135    This function can only be called after a handshake has been completed.
14136
14137    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14138
14139    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14140    \return WANT_WRITE if the writing is not ready.
14141    \return WOLFSSL_SUCCESS if successful.
14142
14143    _Example_
14144    \code
14145    int ret;
14146    WOLFSSL* ssl;
14147    ...
14148    ret = wolfSSL_update_keys(ssl);
14149    if (ret == WANT_WRITE) {
14150        // need to call again when I/O ready
14151    }
14152    else if (ret != WOLFSSL_SUCCESS) {
14153        // failed to send key update
14154    }
14155    \endcode
14156
14157    \sa wolfSSL_write
14158*/
14159int  wolfSSL_update_keys(WOLFSSL* ssl);
14160
14161/*!
14162    \ingroup IO
14163
14164    \brief This function is called on a TLS v1.3 client or server wolfSSL to
14165    determine whether a rollover of keys is in progress. When
14166    wolfSSL_update_keys() is called, a KeyUpdate message is sent and the
14167    encryption key is updated. The decryption key is updated when the response
14168    is received.
14169
14170    \param [in] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14171    \param [out] required   0 when no key update response required. 1 when no key update response required.
14172
14173    \return 0 on successful.
14174    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14175
14176    _Example_
14177    \code
14178    int ret;
14179    WOLFSSL* ssl;
14180    int required;
14181    ...
14182    ret = wolfSSL_key_update_response(ssl, &required);
14183    if (ret != 0) {
14184        // bad parameters
14185    }
14186    if (required) {
14187        // encrypt Key updated, awaiting response to change decrypt key
14188    }
14189    \endcode
14190
14191    \sa wolfSSL_update_keys
14192*/
14193int  wolfSSL_key_update_response(WOLFSSL* ssl, int* required);
14194
14195/*!
14196    \ingroup Setup
14197
14198    \brief This function is called on a TLS v1.3 client wolfSSL context to allow
14199    a client certificate to be sent post handshake upon request from server.
14200    This is useful when connecting to a web server that has some pages that
14201    require client authentication and others that don't.
14202
14203    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
14204    with wolfSSL_CTX_new().
14205
14206    \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
14207    \return SIDE_ERROR if called with a server.
14208    \return 0 if successful.
14209
14210    _Example_
14211    \code
14212    int ret;
14213    WOLFSSL_CTX* ctx;
14214    ...
14215    ret = wolfSSL_allow_post_handshake_auth(ctx);
14216    if (ret != 0) {
14217        // failed to allow post handshake authentication
14218    }
14219    \endcode
14220
14221    \sa wolfSSL_allow_post_handshake_auth
14222    \sa wolfSSL_request_certificate
14223*/
14224int  wolfSSL_CTX_allow_post_handshake_auth(WOLFSSL_CTX* ctx);
14225
14226/*!
14227    \ingroup Setup
14228
14229    \brief This function is called on a TLS v1.3 client wolfSSL to allow
14230    a client certificate to be sent post handshake upon request from server.
14231    A Post-Handshake Client Authentication extension is sent in the ClientHello.
14232    This is useful when connecting to a web server that has some pages that
14233    require client authentication and others that don't.
14234
14235    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14236
14237    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14238    \return SIDE_ERROR if called with a server.
14239    \return 0 if successful.
14240
14241    _Example_
14242    \code
14243    int ret;
14244    WOLFSSL* ssl;
14245    ...
14246    ret = wolfSSL_allow_post_handshake_auth(ssl);
14247    if (ret != 0) {
14248        // failed to allow post handshake authentication
14249    }
14250    \endcode
14251
14252    \sa wolfSSL_CTX_allow_post_handshake_auth
14253    \sa wolfSSL_request_certificate
14254*/
14255int  wolfSSL_allow_post_handshake_auth(WOLFSSL* ssl);
14256
14257/*!
14258    \ingroup IO
14259
14260    \brief This function requests a client certificate from the TLS v1.3 client.
14261    This is useful when a web server is serving some pages that require client
14262    authentication and others that don't.
14263    A maximum of 256 requests can be sent on a connection.
14264
14265    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14266
14267    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14268    \return WANT_WRITE if the writing is not ready.
14269    \return SIDE_ERROR if called with a client.
14270    \return NOT_READY_ERROR if called when the handshake is not finished.
14271    \return POST_HAND_AUTH_ERROR if posthandshake authentication is disallowed.
14272    \return MEMORY_E if dynamic memory allocation fails.
14273    \return WOLFSSL_SUCCESS if successful.
14274
14275    _Example_
14276    \code
14277    int ret;
14278    WOLFSSL* ssl;
14279    ...
14280    ret = wolfSSL_request_certificate(ssl);
14281    if (ret == WANT_WRITE) {
14282        // need to call again when I/O ready
14283    }
14284    else if (ret != WOLFSSL_SUCCESS) {
14285        // failed to request a client certificate
14286    }
14287    \endcode
14288
14289    \sa wolfSSL_allow_post_handshake_auth
14290    \sa wolfSSL_write
14291*/
14292int  wolfSSL_request_certificate(WOLFSSL* ssl);
14293
14294/*!
14295    \ingroup Setup
14296
14297    \brief This function sets the list of signature algorithms to allow on a
14298    wolfSSL context in order of preference. The list is a null-terminated text
14299    string and a colon-delimited list, where each element is of the form
14300    "<public-key>+<digest>" (for example "RSA-PSS+SHA256:ECDSA+SHA384"). The
14301    Edwards-curve algorithms "ED25519" and "ED448" are written without a digest
14302    suffix, since the hash is implied by the algorithm. The previous list
14303    stored in the context is replaced.
14304
14305    Recognized public-key tokens and digest tokens, together with the build
14306    options that must be enabled for each token to be accepted, are listed in
14307    the tables below.
14308
14309    Public-key tokens:
14310
14311    | Token             | Required build option                              |
14312    | ----------------- | -------------------------------------------------- |
14313    | RSA               | !NO_RSA                                            |
14314    | RSA-PSS  /  PSS   | !NO_RSA and WC_RSA_PSS                             |
14315    | ECDSA             | HAVE_ECC                                           |
14316    | ED25519           | HAVE_ED25519 (no digest suffix)                    |
14317    | ED448             | HAVE_ED448   (no digest suffix)                    |
14318    | DSA               | !NO_DSA                                            |
14319    | SM2               | WOLFSSL_SM2 and WOLFSSL_SM3 (digest is SM3)        |
14320
14321    Digest tokens:
14322
14323    | Token   | Required build option                                        |
14324    | ------- | ------------------------------------------------------------ |
14325    | SHA256  | !NO_SHA256                                                   |
14326    | SHA384  | WOLFSSL_SHA384                                               |
14327    | SHA512  | WOLFSSL_SHA512                                               |
14328    | SHA224  | WOLFSSL_SHA224                                               |
14329    | SM3     | WOLFSSL_SM3                                                  |
14330    | SHA1    | !NO_SHA, plus !NO_OLD_TLS or WOLFSSL_ALLOW_TLS_SHA1          |
14331
14332    Notes for TLS 1.3: per RFC 8446, RSA PKCS#1 v1.5, DSA, SHA-1, and SHA-224
14333    cannot be used as handshake signatures and will be filtered out at
14334    negotiation time even if listed. Specifying "RSA-PSS+SHAxxx" causes both
14335    the rsa_pss_rsae_shaxxx and rsa_pss_pss_shaxxx schemes to be added.
14336    Brainpool ECDSA signature schemes (RFC 8734) cannot be selected through
14337    this string interface; they are negotiated automatically when
14338    HAVE_ECC_BRAINPOOL is enabled.
14339
14340    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created with
14341    wolfSSL_CTX_new().
14342    \param [in] list a colon-delimited list of "<public-key>+<digest>"
14343    elements (or "ED25519" / "ED448" without a digest).
14344
14345    \return WOLFSSL_SUCCESS if successful.
14346    \return WOLFSSL_FAILURE if a pointer parameter is NULL, allocation of the
14347    suites structure fails, or any token in the list is not recognized or not
14348    supported by the current build.
14349
14350    _Example_
14351    \code
14352    int ret;
14353    WOLFSSL_CTX* ctx;
14354    const char* list = "RSA-PSS+SHA256:ECDSA+SHA384:ED25519";
14355    ...
14356    ret = wolfSSL_CTX_set1_sigalgs_list(ctx, list);
14357    if (ret != WOLFSSL_SUCCESS) {
14358        // failed to set signature algorithm list
14359    }
14360    \endcode
14361
14362    \sa wolfSSL_set1_sigalgs_list
14363    \sa wolfSSL_CTX_set1_groups_list
14364*/
14365int  wolfSSL_CTX_set1_sigalgs_list(WOLFSSL_CTX* ctx, const char* list);
14366
14367/*!
14368    \ingroup Setup
14369
14370    \brief This function sets the list of signature algorithms to allow on a
14371    wolfSSL session in order of preference. The list format and the set of
14372    recognized public-key and digest tokens are identical to those documented
14373    for wolfSSL_CTX_set1_sigalgs_list(); refer to that function for the full
14374    token tables and TLS 1.3 caveats. The previous list stored in the session
14375    is replaced.
14376
14377    \param [in,out] ssl a pointer to a WOLFSSL structure, created using
14378    wolfSSL_new().
14379    \param [in] list a colon-delimited list of "<public-key>+<digest>"
14380    elements (or "ED25519" / "ED448" without a digest).
14381
14382    \return WOLFSSL_SUCCESS if successful.
14383    \return WOLFSSL_FAILURE if a pointer parameter is NULL, allocation of the
14384    suites structure fails, or any token in the list is not recognized or not
14385    supported by the current build.
14386
14387    _Example_
14388    \code
14389    int ret;
14390    WOLFSSL* ssl;
14391    const char* list = "RSA-PSS+SHA256:ECDSA+SHA384:ED25519";
14392    ...
14393    ret = wolfSSL_set1_sigalgs_list(ssl, list);
14394    if (ret != WOLFSSL_SUCCESS) {
14395        // failed to set signature algorithm list
14396    }
14397    \endcode
14398
14399    \sa wolfSSL_CTX_set1_sigalgs_list
14400    \sa wolfSSL_set1_groups_list
14401*/
14402int  wolfSSL_set1_sigalgs_list(WOLFSSL* ssl, const char* list);
14403
14404/*!
14405    \ingroup Setup
14406
14407    \brief This function sets the list of key-exchange groups (named elliptic
14408    curves and KEMs) to allow on a wolfSSL context in order of preference. The
14409    list is a null-terminated, colon-delimited text string of group names, for
14410    example "P-384:P-256:X25519". Call this function to set the key-exchange
14411    parameters used with TLS v1.3 connections (the function is compiled in
14412    only when HAVE_ECC, WOLFSSL_TLS13, and HAVE_SUPPORTED_CURVES are defined).
14413
14414    Recognized group names and the build options each one requires are listed
14415    below. Names are matched case-sensitively against the table.
14416
14417    NIST / SEC curves (require HAVE_ECC):
14418
14419    | Name      | Curve / Group                                                |
14420    | --------- | ------------------------------------------------------------ |
14421    | P-160     | secp160r1                                                    |
14422    | P-160-2   | secp160r2                                                    |
14423    | P-192     | secp192r1 (prime192v1)                                       |
14424    | P-224     | secp224r1                                                    |
14425    | P-256     | secp256r1 (prime256v1) — also accepted as "prime256v1" / "secp256r1" |
14426    | P-384     | secp384r1 — also accepted as "secp384r1"                     |
14427    | P-521     | secp521r1 — also accepted as "secp521r1"                     |
14428    | K-160     | secp160k1                                                    |
14429    | K-192     | secp192k1                                                    |
14430    | K-224     | secp224k1                                                    |
14431    | K-256     | secp256k1                                                    |
14432
14433    Brainpool curves (require HAVE_ECC plus WOLFSSL_CUSTOM_CURVES and
14434    HAVE_ECC_BRAINPOOL — typically enabled by --enable-ecccustcurves=all):
14435
14436    | Name  | Curve              |
14437    | ----- | ------------------ |
14438    | B-256 | brainpoolP256r1    |
14439    | B-384 | brainpoolP384r1    |
14440    | B-512 | brainpoolP512r1    |
14441
14442    Edwards / Montgomery curves:
14443
14444    | Name   | Required build option |
14445    | ------ | --------------------- |
14446    | X25519 | HAVE_CURVE25519       |
14447    | X448   | HAVE_CURVE448         |
14448
14449    SM2 (requires WOLFSSL_SM2):
14450
14451    | Name      | Group           |
14452    | --------- | --------------- |
14453    | SM2       | sm2p256v1       |
14454    | sm2p256v1 | sm2p256v1 (alias) |
14455
14456    ML-KEM (post-quantum) groups (require WOLFSSL_HAVE_MLKEM and
14457    !WOLFSSL_NO_ML_KEM):
14458
14459    | Name        |
14460    | ----------- |
14461    | ML_KEM_512  |
14462    | ML_KEM_768  |
14463    | ML_KEM_1024 |
14464
14465    ML-KEM hybrid groups additionally require HAVE_ECC together with either
14466    WOLFSSL_WC_MLKEM or HAVE_LIBOQS, and WOLFSSL_PQC_HYBRIDS (or
14467    WOLFSSL_EXTRA_PQC_HYBRIDS for the "extra" set):
14468
14469    | Name                | Hybrid flag set            |
14470    | ------------------- | -------------------------- |
14471    | SecP256r1MLKEM768   | WOLFSSL_PQC_HYBRIDS        |
14472    | SecP384r1MLKEM1024  | WOLFSSL_PQC_HYBRIDS        |
14473    | X25519MLKEM768      | WOLFSSL_PQC_HYBRIDS        |
14474    | SecP256r1MLKEM512   | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14475    | SecP384r1MLKEM768   | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14476    | SecP521r1MLKEM1024  | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14477    | X25519MLKEM512      | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14478    | X448MLKEM768        | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14479
14480    Legacy Kyber groups (require WOLFSSL_MLKEM_KYBER; hybrids additionally
14481    require HAVE_ECC together with WOLFSSL_WC_MLKEM or HAVE_LIBOQS):
14482
14483    | Name                  |
14484    | --------------------- |
14485    | KYBER_LEVEL1          |
14486    | KYBER_LEVEL3          |
14487    | KYBER_LEVEL5          |
14488    | P256_KYBER_LEVEL1     |
14489    | P256_KYBER_LEVEL3     |
14490    | P384_KYBER_LEVEL3     |
14491    | P521_KYBER_LEVEL5     |
14492    | X25519_KYBER_LEVEL1   |
14493    | X25519_KYBER_LEVEL3   |
14494    | X448_KYBER_LEVEL3     |
14495
14496    In addition to the names above, when HAVE_FIPS and HAVE_SELFTEST are not
14497    defined, any curve name registered with wolfCrypt (looked up via
14498    wc_ecc_get_curve_idx_from_name(), e.g. "brainpoolP256r1") is also
14499    accepted.
14500
14501    The order of the names in the list is preserved and used as the local
14502    preference order for KeyShare selection in TLS 1.3.
14503
14504    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
14505    with wolfSSL_CTX_new().
14506    \param [in] list a string that is a colon-delimited list of key-exchange
14507    group names.
14508
14509    \return WOLFSSL_FAILURE if pointer parameters are NULL, there are more than
14510    WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not
14511    using TLS v1.3.
14512    \return WOLFSSL_SUCCESS if successful.
14513
14514    _Example_
14515    \code
14516    int ret;
14517    WOLFSSL_CTX* ctx;
14518    const char* list = "P-384:P-256";
14519    ...
14520    ret = wolfSSL_CTX_set1_groups_list(ctx, list);
14521    if (ret != WOLFSSL_SUCCESS) {
14522        // failed to set group list
14523    }
14524    \endcode
14525
14526    \sa wolfSSL_set1_groups_list
14527    \sa wolfSSL_CTX_set_groups
14528    \sa wolfSSL_set_groups
14529    \sa wolfSSL_UseKeyShare
14530    \sa wolfSSL_preferred_group
14531*/
14532int  wolfSSL_CTX_set1_groups_list(WOLFSSL_CTX *ctx, const char *list);
14533
14534/*!
14535    \ingroup Setup
14536
14537    \brief This function sets the list of key-exchange groups (named elliptic
14538    curves and KEMs) to allow on a wolfSSL session in order of preference. The
14539    list format and the set of recognized group names are identical to those
14540    documented for wolfSSL_CTX_set1_groups_list(); refer to that function for
14541    the full token tables and required build options.
14542
14543    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14544    \param [in] list a string that is a colon separated list of key exchange
14545    groups.
14546
14547    \return WOLFSSL_FAILURE if pointer parameters are NULL, there are more than
14548    WOLFSSL_MAX_GROUP_COUNT groups, a group name is not recognized or not
14549    using TLS v1.3.
14550    \return WOLFSSL_SUCCESS if successful.
14551
14552    _Example_
14553    \code
14554    int ret;
14555    WOLFSSL* ssl;
14556    const char* list = "P-384:P-256";
14557    ...
14558    ret = wolfSSL_CTX_set1_groups_list(ssl, list);
14559    if (ret != WOLFSSL_SUCCESS) {
14560        // failed to set group list
14561    }
14562    \endcode
14563
14564    \sa wolfSSL_CTX_set1_groups_list
14565    \sa wolfSSL_CTX_set_groups
14566    \sa wolfSSL_set_groups
14567    \sa wolfSSL_UseKeyShare
14568    \sa wolfSSL_preferred_group
14569*/
14570int  wolfSSL_set1_groups_list(WOLFSSL *ssl, const char *list);
14571
14572/*!
14573    \ingroup TLS
14574
14575    \brief This function returns the key exchange group the client prefers to
14576    use in the TLS v1.3 handshake.
14577    Call this function to after a handshake is complete to determine which
14578    group the server prefers so that this information can be used in future
14579    connections to pre-generate a key pair for key exchange.
14580
14581    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14582
14583    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14584    \return SIDE_ERROR if called with a server.
14585    \return NOT_READY_ERROR if called before handshake is complete.
14586    \return Group identifier if successful.
14587
14588    _Example_
14589    \code
14590    int ret;
14591    int group;
14592    WOLFSSL* ssl;
14593    ...
14594    ret = wolfSSL_CTX_set1_groups_list(ssl)
14595    if (ret < 0) {
14596        // failed to get group
14597    }
14598    group = ret;
14599    \endcode
14600
14601    \sa wolfSSL_UseKeyShare
14602    \sa wolfSSL_CTX_set_groups
14603    \sa wolfSSL_set_groups
14604    \sa wolfSSL_CTX_set1_groups_list
14605    \sa wolfSSL_set1_groups_list
14606*/
14607int  wolfSSL_preferred_group(WOLFSSL* ssl);
14608
14609/*!
14610    \ingroup Setup
14611
14612    \brief This function sets the list of key-exchange groups (named elliptic
14613    curves and KEMs) to allow on a wolfSSL context in order of preference. The
14614    list is an array of named-group identifiers (see the table below) and
14615    \p count is the number of identifiers in the array. Use this function to
14616    set the key-exchange parameters used by TLS v1.3 connections; the order
14617    of the array becomes the local KeyShare preference order.
14618
14619    Recognized identifiers and the build options each one requires are listed
14620    below. The identifiers are defined in the anonymous enum in
14621    \<wolfssl/ssl.h\>.
14622
14623    NIST / SEC curves (require HAVE_ECC):
14624
14625    | Identifier                | Curve / Group                        |
14626    | ------------------------- | ------------------------------------ |
14627    | WOLFSSL_ECC_SECP160K1     | secp160k1                            |
14628    | WOLFSSL_ECC_SECP160R1     | secp160r1                            |
14629    | WOLFSSL_ECC_SECP160R2     | secp160r2                            |
14630    | WOLFSSL_ECC_SECP192K1     | secp192k1                            |
14631    | WOLFSSL_ECC_SECP192R1     | secp192r1 (prime192v1)               |
14632    | WOLFSSL_ECC_SECP224K1     | secp224k1                            |
14633    | WOLFSSL_ECC_SECP224R1     | secp224r1                            |
14634    | WOLFSSL_ECC_SECP256K1     | secp256k1                            |
14635    | WOLFSSL_ECC_SECP256R1     | secp256r1 (prime256v1)               |
14636    | WOLFSSL_ECC_SECP384R1     | secp384r1                            |
14637    | WOLFSSL_ECC_SECP521R1     | secp521r1                            |
14638
14639    Brainpool curves (require HAVE_ECC plus WOLFSSL_CUSTOM_CURVES and
14640    HAVE_ECC_BRAINPOOL — typically enabled by --enable-ecccustcurves=all):
14641
14642    | Identifier                          | Curve            | Notes |
14643    | ----------------------------------- | ---------------- | ----- |
14644    | WOLFSSL_ECC_BRAINPOOLP256R1         | brainpoolP256r1  | TLS 1.2 group ID 26 |
14645    | WOLFSSL_ECC_BRAINPOOLP384R1         | brainpoolP384r1  | TLS 1.2 group ID 27 |
14646    | WOLFSSL_ECC_BRAINPOOLP512R1         | brainpoolP512r1  | TLS 1.2 group ID 28 |
14647    | WOLFSSL_ECC_BRAINPOOLP256R1TLS13    | brainpoolP256r1  | RFC 8734 TLS 1.3 ID |
14648    | WOLFSSL_ECC_BRAINPOOLP384R1TLS13    | brainpoolP384r1  | RFC 8734 TLS 1.3 ID |
14649    | WOLFSSL_ECC_BRAINPOOLP512R1TLS13    | brainpoolP512r1  | RFC 8734 TLS 1.3 ID |
14650
14651    Edwards / Montgomery curves:
14652
14653    | Identifier        | Required build option |
14654    | ----------------- | --------------------- |
14655    | WOLFSSL_ECC_X25519| HAVE_CURVE25519       |
14656    | WOLFSSL_ECC_X448  | HAVE_CURVE448         |
14657
14658    SM2 (requires WOLFSSL_SM2):
14659
14660    | Identifier             | Group     |
14661    | ---------------------- | --------- |
14662    | WOLFSSL_ECC_SM2P256V1  | sm2p256v1 |
14663
14664    Finite-field DH (RFC 7919) groups (require HAVE_FFDHE and the matching
14665    HAVE_FFDHE_NNNN macro for each size):
14666
14667    | Identifier         | Group       |
14668    | ------------------ | ----------- |
14669    | WOLFSSL_FFDHE_2048 | ffdhe2048   |
14670    | WOLFSSL_FFDHE_3072 | ffdhe3072   |
14671    | WOLFSSL_FFDHE_4096 | ffdhe4096   |
14672    | WOLFSSL_FFDHE_6144 | ffdhe6144   |
14673    | WOLFSSL_FFDHE_8192 | ffdhe8192   |
14674
14675    ML-KEM (post-quantum) groups (require HAVE_PQC, WOLFSSL_HAVE_MLKEM and
14676    !WOLFSSL_NO_ML_KEM):
14677
14678    | Identifier         |
14679    | ------------------ |
14680    | WOLFSSL_ML_KEM_512 |
14681    | WOLFSSL_ML_KEM_768 |
14682    | WOLFSSL_ML_KEM_1024|
14683
14684    ML-KEM hybrid groups additionally require HAVE_ECC together with either
14685    WOLFSSL_WC_MLKEM or HAVE_LIBOQS, and WOLFSSL_PQC_HYBRIDS (or
14686    WOLFSSL_EXTRA_PQC_HYBRIDS for the "extra" set):
14687
14688    | Identifier                       | Hybrid flag set            |
14689    | -------------------------------- | -------------------------- |
14690    | WOLFSSL_SECP256R1MLKEM768        | WOLFSSL_PQC_HYBRIDS        |
14691    | WOLFSSL_X25519MLKEM768           | WOLFSSL_PQC_HYBRIDS        |
14692    | WOLFSSL_SECP384R1MLKEM1024       | WOLFSSL_PQC_HYBRIDS        |
14693    | WOLFSSL_SECP256R1MLKEM512        | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14694    | WOLFSSL_SECP384R1MLKEM768        | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14695    | WOLFSSL_SECP521R1MLKEM1024       | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14696    | WOLFSSL_X25519MLKEM512           | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14697    | WOLFSSL_X448MLKEM768             | WOLFSSL_EXTRA_PQC_HYBRIDS  |
14698
14699    Legacy Kyber groups (require HAVE_PQC and WOLFSSL_MLKEM_KYBER; hybrids
14700    additionally require HAVE_ECC together with WOLFSSL_WC_MLKEM or
14701    HAVE_LIBOQS):
14702
14703    | Identifier                  |
14704    | --------------------------- |
14705    | WOLFSSL_KYBER_LEVEL1        |
14706    | WOLFSSL_KYBER_LEVEL3        |
14707    | WOLFSSL_KYBER_LEVEL5        |
14708    | WOLFSSL_P256_KYBER_LEVEL1   |
14709    | WOLFSSL_P256_KYBER_LEVEL3   |
14710    | WOLFSSL_P384_KYBER_LEVEL3   |
14711    | WOLFSSL_P521_KYBER_LEVEL5   |
14712    | WOLFSSL_X25519_KYBER_LEVEL1 |
14713    | WOLFSSL_X25519_KYBER_LEVEL3 |
14714    | WOLFSSL_X448_KYBER_LEVEL3   |
14715
14716    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
14717    with wolfSSL_CTX_new().
14718    \param [in] groups a list of key-exchange groups by identifier.
14719    \param [in] count the number of identifiers in \p groups (must not exceed
14720    WOLFSSL_MAX_GROUP_COUNT).
14721
14722    \return BAD_FUNC_ARG if a pointer parameter is NULL, \p count exceeds
14723    WOLFSSL_MAX_GROUP_COUNT, or the underlying method is not a TLS method.
14724    \return WOLFSSL_SUCCESS if successful.
14725
14726    _Example_
14727    \code
14728    int ret;
14729    WOLFSSL_CTX* ctx;
14730    int groups[] = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
14731    int count = sizeof(groups) / sizeof(groups[0]);
14732    ...
14733    ret = wolfSSL_CTX_set_groups(ctx, groups, count);
14734    if (ret != WOLFSSL_SUCCESS) {
14735        // failed to set group list
14736    }
14737    \endcode
14738
14739    \sa wolfSSL_set_groups
14740    \sa wolfSSL_UseKeyShare
14741    \sa wolfSSL_CTX_set1_groups_list
14742    \sa wolfSSL_set1_groups_list
14743    \sa wolfSSL_preferred_group
14744*/
14745int  wolfSSL_CTX_set_groups(WOLFSSL_CTX* ctx, int* groups,
14746    int count);
14747
14748/*!
14749    \ingroup Setup
14750
14751    \brief This function sets the list of key-exchange groups (named elliptic
14752    curves and KEMs) to allow on a wolfSSL session in order of preference. The
14753    array format and the set of recognized identifiers are identical to those
14754    documented for wolfSSL_CTX_set_groups(); refer to that function for the
14755    full identifier table and required build options.
14756
14757    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14758    \param [in] groups a list of key-exchange groups by identifier.
14759    \param [in] count the number of identifiers in \p groups (must not exceed
14760    WOLFSSL_MAX_GROUP_COUNT).
14761
14762    \return BAD_FUNC_ARG if a pointer parameter is NULL, \p count exceeds
14763    WOLFSSL_MAX_GROUP_COUNT, any of the identifiers are unrecognized, or the
14764    underlying method is not a TLS method.
14765    \return WOLFSSL_SUCCESS if successful.
14766
14767    _Example_
14768    \code
14769    int ret;
14770    WOLFSSL* ssl;
14771    int groups[] = { WOLFSSL_ECC_X25519, WOLFSSL_ECC_SECP256R1 };
14772    int count = sizeof(groups) / sizeof(groups[0]);
14773    ...
14774    ret = wolfSSL_set_groups(ssl, groups, count);
14775    if (ret != WOLFSSL_SUCCESS) {
14776        // failed to set group list
14777    }
14778    \endcode
14779
14780    \sa wolfSSL_CTX_set_groups
14781    \sa wolfSSL_UseKeyShare
14782    \sa wolfSSL_CTX_set1_groups_list
14783    \sa wolfSSL_set1_groups_list
14784    \sa wolfSSL_preferred_group
14785*/
14786int  wolfSSL_set_groups(WOLFSSL* ssl, int* groups, int count);
14787
14788/*!
14789    \ingroup IO
14790
14791    \brief This function is called on the client side and initiates a
14792    TLS v1.3 handshake with a server.  When this function is called, the
14793    underlying communication channel has already been set up.
14794    wolfSSL_connect() works with both blocking and non-blocking I/O.
14795    When the underlying I/O is non-blocking, wolfSSL_connect() will return
14796    when the underlying I/O could not satisfy the needs of wolfSSL_connect
14797    to continue the handshake.  In this case, a call to wolfSSL_get_error()
14798    will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The
14799    calling process must then repeat the call to wolfSSL_connect() when
14800    the underlying I/O is ready and wolfSSL will pick up where it left off.
14801    When using a non-blocking socket, nothing needs to be done, but select()
14802    can be used to check for the required condition. If the underlying I/O is
14803    blocking, wolfSSL_connect() will only return once the handshake has been
14804    finished or an error occurred. wolfSSL takes a different approach to
14805    certificate verification than OpenSSL does.  The default policy for the
14806    client is to verify the server, this means that if you don't load CAs to
14807    verify the server you'll get a connect error, unable to verify (-155). It
14808    you want to mimic OpenSSL behavior of having SSL_connect succeed even if
14809    verifying the server fails and reducing security you can do this by
14810    calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling
14811    SSL_new();  Though it's not recommended.
14812
14813    \return SSL_SUCCESS upon success.
14814    \return SSL_FATAL_ERROR will be returned if an error occurred.  To get a
14815    more detailed error code, call wolfSSL_get_error().
14816
14817    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14818
14819    _Example_
14820    \code
14821    int ret = 0;
14822    int err = 0;
14823    WOLFSSL* ssl;
14824    char buffer[80];
14825    ...
14826
14827    ret = wolfSSL_connect_TLSv13(ssl);
14828    if (ret != SSL_SUCCESS) {
14829        err = wolfSSL_get_error(ssl, ret);
14830        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
14831    }
14832    \endcode
14833
14834    \sa wolfSSL_get_error
14835    \sa wolfSSL_connect
14836    \sa wolfSSL_accept_TLSv13
14837    \sa wolfSSL_accept
14838*/
14839int  wolfSSL_connect_TLSv13(WOLFSSL* ssl);
14840
14841/*!
14842    \ingroup IO
14843
14844    \brief This function is called on the server side and waits for a SSL/TLS
14845    client to initiate the SSL/TLS handshake.  When this function is called,
14846    the underlying communication channel has already been set up.
14847    wolfSSL_accept() works with both blocking and non-blocking I/O.
14848    When the underlying I/O is non-blocking, wolfSSL_accept() will return
14849    when the underlying I/O could not satisfy the needs of wolfSSL_accept
14850    to continue the handshake.  In this case, a call to wolfSSL_get_error()
14851    will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.
14852    The calling process must then repeat the call to wolfSSL_accept when
14853    data is available to read and wolfSSL will pick up where it left off.
14854    When using a non-blocking socket, nothing needs to be done, but select()
14855    can be used to check for the required condition. If the underlying I/O
14856    is blocking, wolfSSL_accept() will only return once the handshake has
14857    been finished or an error occurred.
14858    Call this function when expecting a TLS v1.3 connection though older
14859    version ClientHello messages are supported.
14860
14861    \return SSL_SUCCESS upon success.
14862    \return SSL_FATAL_ERROR will be returned if an error occurred. To get a
14863    more detailed error code, call wolfSSL_get_error().
14864
14865    \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14866
14867    _Example_
14868    \code
14869    int ret = 0;
14870    int err = 0;
14871    WOLFSSL* ssl;
14872    char buffer[80];
14873    ...
14874
14875    ret = wolfSSL_accept_TLSv13(ssl);
14876    if (ret != SSL_SUCCESS) {
14877        err = wolfSSL_get_error(ssl, ret);
14878        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
14879    }
14880    \endcode
14881
14882    \sa wolfSSL_get_error
14883    \sa wolfSSL_connect_TLSv13
14884    \sa wolfSSL_connect
14885    \sa wolfSSL_accept_TLSv13
14886    \sa wolfSSL_accept
14887*/
14888wolfSSL_accept_TLSv13(WOLFSSL* ssl);
14889
14890/*!
14891    \ingroup Setup
14892
14893    \brief This function sets the maximum amount of early data that a
14894    TLS v1.3 client or server is willing to exchange using the wolfSSL context.
14895    Call this function to limit the amount of early data to process to mitigate
14896    replay attacks. Early data is protected by keys derived from those of the
14897    connection that the session ticket was sent and therefore will be the same
14898    every time a session ticket is used in resumption.
14899    The value is included in the session ticket for resumption.
14900    A server value of zero indicates no early data is to be sent by client using
14901    session tickets. A client value of zero indicates that the client will
14902    not send any early data.
14903    The default value is zero: per RFC 8446 Appendix E.5, TLS implementations
14904    "MUST NOT enable 0-RTT (either sending or accepting) unless specifically
14905    requested by the application." Servers must call this function (or the
14906    per-SSL equivalent) with a non-zero value to opt in.
14907    It is recommended that the number of early data bytes be kept as low as
14908    practically possible in the application.
14909
14910    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
14911    with wolfSSL_CTX_new().
14912    \param [in] sz the amount of early data to accept in bytes.
14913
14914    \return BAD_FUNC_ARG if ctx is NULL or not using TLS v1.3.
14915    \return 0 if successful.
14916
14917    _Example_
14918    \code
14919    int ret;
14920    WOLFSSL_CTX* ctx;
14921    ...
14922    ret = wolfSSL_CTX_set_max_early_data(ctx, 128);
14923    if (ret != WOLFSSL_SUCCESS) {
14924        // failed to set group list
14925    }
14926    \endcode
14927
14928    \sa wolfSSL_set_max_early_data
14929    \sa wolfSSL_write_early_data
14930    \sa wolfSSL_read_early_data
14931*/
14932int  wolfSSL_CTX_set_max_early_data(WOLFSSL_CTX* ctx,
14933    unsigned int sz);
14934
14935/*!
14936    \ingroup Setup
14937
14938    \brief This function sets the maximum amount of early data that a
14939    TLS v1.3 client or server is willing to exchange.
14940    Call this function to limit the amount of early data to process to mitigate
14941    replay attacks. Early data is protected by keys derived from those of the
14942    connection that the session ticket was sent and therefore will be the same
14943    every time a session ticket is used in resumption.
14944    The value is included in the session ticket for resumption.
14945    A server value of zero indicates no early data is to be sent by client using
14946    session tickets. A client value of zero indicates that the client will
14947    not send any early data.
14948    It is recommended that the number of early data bytes be kept as low as
14949    practically possible in the application.
14950
14951    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14952    \param [in] sz the amount of early data to accept from client in bytes.
14953
14954    \return BAD_FUNC_ARG if ssl is NULL or not using TLS v1.3.
14955    \return 0 if successful.
14956
14957    _Example_
14958    \code
14959    int ret;
14960    WOLFSSL* ssl;
14961    ...
14962    ret = wolfSSL_set_max_early_data(ssl, 128);
14963    if (ret != WOLFSSL_SUCCESS) {
14964        // failed to set group list
14965    }
14966    \endcode
14967
14968    \sa wolfSSL_CTX_set_max_early_data
14969    \sa wolfSSL_write_early_data
14970    \sa wolfSSL_read_early_data
14971*/
14972int  wolfSSL_set_max_early_data(WOLFSSL* ssl, unsigned int sz);
14973
14974/*!
14975    \ingroup IO
14976
14977    \brief This function writes early data to the server on resumption.
14978    Call this function before wolfSSL_connect() or wolfSSL_connect_TLSv13().
14979    This function is only used with clients.
14980
14981    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
14982    \param [in] data the buffer holding the early data to write to server.
14983    \param [in] sz the amount of early data to write in bytes.
14984    \param [out] outSz the amount of early data written in bytes.
14985
14986    \return BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or
14987    not using TLSv1.3.
14988    \return SIDE_ERROR if called with a server.
14989    \return BAD_STATE_E if invoked without a valid session or without a valid
14990    PSK cb
14991    \return WOLFSSL_FATAL_ERROR if the connection is not made.
14992    \return the amount of early data written in bytes if successful.
14993
14994    _Example_
14995    \code
14996    int ret = 0;
14997    int err = 0;
14998    WOLFSSL* ssl;
14999    byte earlyData[] = { early data };
15000    int outSz;
15001    char buffer[80];
15002    ...
15003
15004    ret = wolfSSL_write_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
15005    if (ret < 0) {
15006        err = wolfSSL_get_error(ssl, ret);
15007        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
15008        goto err_label;
15009    }
15010    if (outSz < sizeof(earlyData)) {
15011        // not all early data was sent
15012    }
15013    ret = wolfSSL_connect_TLSv13(ssl);
15014    if (ret != SSL_SUCCESS) {
15015        err = wolfSSL_get_error(ssl, ret);
15016        printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
15017    }
15018    \endcode
15019
15020    \sa wolfSSL_read_early_data
15021    \sa wolfSSL_connect
15022    \sa wolfSSL_connect_TLSv13
15023*/
15024int  wolfSSL_write_early_data(WOLFSSL* ssl, const void* data,
15025    int sz, int* outSz);
15026
15027/*!
15028    \ingroup IO
15029
15030    \brief This function reads any early data from a client on resumption.
15031    Call this function instead of wolfSSL_accept() or wolfSSL_accept_TLSv13()
15032    to accept a client and read any early data in the handshake. The function
15033    should be invoked until wolfSSL_is_init_finished() returns true. Early data
15034    may be sent by the client in multiple messages. If there is no early data
15035    then the handshake will be processed as normal. This function is only used
15036    with servers.
15037
15038    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
15039    \param [out] data a buffer to hold the early data read from client.
15040    \param [in] sz size of the buffer in bytes.
15041    \param [out] outSz number of bytes of early data read.
15042
15043    \return BAD_FUNC_ARG if a pointer parameter is NULL, sz is less than 0 or
15044    not using TLSv1.3.
15045    \return SIDE_ERROR if called with a client.
15046    \return WOLFSSL_FATAL_ERROR if accepting a connection fails.
15047    \return Number of early data bytes read (may be zero).
15048
15049    _Example_
15050    \code
15051    int ret = 0;
15052    int err = 0;
15053    WOLFSSL* ssl;
15054    byte earlyData[128];
15055    int outSz;
15056    char buffer[80];
15057    ...
15058
15059    do {
15060        ret = wolfSSL_read_early_data(ssl, earlyData, sizeof(earlyData), &outSz);
15061        if (ret < 0) {
15062            err = wolfSSL_get_error(ssl, ret);
15063            printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer));
15064        }
15065        if (outSz > 0) {
15066            // early data available
15067        }
15068    } while (!wolfSSL_is_init_finished(ssl));
15069    \endcode
15070
15071    \sa wolfSSL_write_early_data
15072    \sa wolfSSL_accept
15073    \sa wolfSSL_accept_TLSv13
15074*/
15075int  wolfSSL_read_early_data(WOLFSSL* ssl, void* data, int sz,
15076    int* outSz);
15077
15078/*!
15079    \ingroup IO
15080
15081    \brief This function is called to inject data into the WOLFSSL object. This
15082    is useful when data needs to be read from a single place and demultiplexed
15083    into multiple connections. The caller should then call wolfSSL_read() to
15084    extract the plaintext data from the WOLFSSL object.
15085
15086    \param [in] ssl a pointer to a WOLFSSL structure, created using
15087                    wolfSSL_new().
15088    \param [in] data data to inject into the ssl object.
15089    \param [in] sz number of bytes of data to inject.
15090
15091    \return BAD_FUNC_ARG if any pointer parameter is NULL or sz <= 0
15092    \return APP_DATA_READY if there is application data left to read
15093    \return MEMORY_E if allocation fails
15094    \return WOLFSSL_SUCCESS on success
15095
15096    _Example_
15097    \code
15098    byte buf[2000]
15099    sz = recv(fd, buf, sizeof(buf), 0);
15100    if (sz <= 0)
15101        // error
15102    if (wolfSSL_inject(ssl, buf, sz) != WOLFSSL_SUCCESS)
15103        // error
15104    sz = wolfSSL_read(ssl, buf, sizeof(buf);
15105    \endcode
15106
15107    \sa wolfSSL_read
15108*/
15109int wolfSSL_inject(WOLFSSL* ssl, const void* data, int sz);
15110
15111/*!
15112    \ingroup Setup
15113
15114    \brief This function sets the Pre-Shared Key (PSK) client side callback
15115    for TLS v1.3 connections.
15116    The callback is used to find a PSK identity and return its key and
15117    the name of the cipher to use for the handshake.
15118    The function sets the client_psk_tls13_cb member of the
15119    WOLFSSL_CTX structure.
15120
15121    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
15122    with wolfSSL_CTX_new().
15123    \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client.
15124
15125    _Example_
15126    \code
15127    WOLFSSL_CTX* ctx;
15128    ...
15129    wolfSSL_CTX_set_psk_client_tls13_callback(ctx, my_psk_client_tls13_cb);
15130    \endcode
15131
15132    \sa wolfSSL_set_psk_client_tls13_callback
15133    \sa wolfSSL_CTX_set_psk_server_tls13_callback
15134    \sa wolfSSL_set_psk_server_tls13_callback
15135*/
15136void wolfSSL_CTX_set_psk_client_tls13_callback(WOLFSSL_CTX* ctx,
15137    wc_psk_client_tls13_callback cb);
15138
15139/*!
15140    \ingroup Setup
15141
15142    \brief This function sets the Pre-Shared Key (PSK) client side callback
15143    for TLS v1.3 connections.
15144    The callback is used to find a PSK identity and return its key and
15145    the name of the cipher to use for the handshake.
15146    The function sets the client_psk_tls13_cb member of the options field in
15147    WOLFSSL structure.
15148
15149    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
15150    \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 client.
15151
15152    _Example_
15153    \code
15154    WOLFSSL* ssl;
15155    ...
15156    wolfSSL_set_psk_client_tls13_callback(ssl, my_psk_client_tls13_cb);
15157    \endcode
15158
15159    \sa wolfSSL_CTX_set_psk_client_tls13_callback
15160    \sa wolfSSL_CTX_set_psk_server_tls13_callback
15161    \sa wolfSSL_set_psk_server_tls13_callback
15162*/
15163void wolfSSL_set_psk_client_tls13_callback(WOLFSSL* ssl,
15164    wc_psk_client_tls13_callback cb);
15165
15166/*!
15167    \ingroup Setup
15168
15169    \brief This function sets the Pre-Shared Key (PSK) server side callback
15170    for TLS v1.3 connections.
15171    The callback is used to find a PSK identity and return its key and
15172    the name of the cipher to use for the handshake.
15173    The function sets the server_psk_tls13_cb member of the
15174    WOLFSSL_CTX structure.
15175
15176    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created
15177    with wolfSSL_CTX_new().
15178    \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server.
15179
15180    _Example_
15181    \code
15182    WOLFSSL_CTX* ctx;
15183    ...
15184    wolfSSL_CTX_set_psk_server_tls13_callback(ctx, my_psk_client_tls13_cb);
15185    \endcode
15186
15187    \sa wolfSSL_CTX_set_psk_client_tls13_callback
15188    \sa wolfSSL_set_psk_client_tls13_callback
15189    \sa wolfSSL_set_psk_server_tls13_callback
15190*/
15191void wolfSSL_CTX_set_psk_server_tls13_callback(WOLFSSL_CTX* ctx,
15192    wc_psk_server_tls13_callback cb);
15193
15194/*!
15195    \ingroup Setup
15196
15197    \brief This function sets the Pre-Shared Key (PSK) server side callback
15198    for TLS v1.3 connections.
15199    The callback is used to find a PSK identity and return its key and
15200    the name of the cipher to use for the handshake.
15201    The function sets the server_psk_tls13_cb member of the options field in
15202    WOLFSSL structure.
15203
15204    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
15205    \param [in] cb a Pre-Shared Key (PSK) callback for a TLS 1.3 server.
15206
15207    _Example_
15208    \code
15209    WOLFSSL* ssl;
15210    ...
15211    wolfSSL_set_psk_server_tls13_callback(ssl, my_psk_server_tls13_cb);
15212    \endcode
15213
15214    \sa wolfSSL_CTX_set_psk_client_tls13_callback
15215    \sa wolfSSL_set_psk_client_tls13_callback
15216    \sa wolfSSL_CTX_set_psk_server_tls13_callback
15217*/
15218void wolfSSL_set_psk_server_tls13_callback(WOLFSSL* ssl,
15219    wc_psk_server_tls13_callback cb);
15220
15221/*!
15222    \ingroup Setup
15223
15224    \brief Enable or disable TLS 1.3 certificate authentication with external
15225    PSK (RFC8773bis) on a context.
15226
15227    When enabled, wolfSSL advertises and accepts the
15228    `tls_cert_with_extern_psk` extension for TLS 1.3 handshakes using external
15229    PSKs. Any non-zero \p state value enables the feature and zero disables it.
15230
15231    Availability:
15232      - Built with `--enable-tls13 --enable-psk --enable-cert-with-extern-psk`
15233      - Or with `WOLFSSL_TLS13` and `WOLFSSL_CERT_WITH_EXTERN_PSK` defined
15234
15235    \param [in,out] ctx a pointer to a WOLFSSL_CTX structure, created with
15236                        wolfSSL_CTX_new().
15237    \param [in] state 0 to disable, non-zero to enable.
15238
15239    \return WOLFSSL_SUCCESS on success.
15240    \return WOLFSSL_FAILURE when \p ctx is NULL.
15241
15242    _Example_
15243    \code
15244    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfTLSv1_3_client_method());
15245    if (wolfSSL_CTX_set_cert_with_extern_psk(ctx, 1) != WOLFSSL_SUCCESS) {
15246        /* handle error */
15247    }
15248    \endcode
15249
15250    \sa wolfSSL_set_cert_with_extern_psk
15251    \sa wolfSSL_CTX_set_psk_client_tls13_callback
15252    \sa wolfSSL_CTX_set_psk_server_tls13_callback
15253*/
15254int wolfSSL_CTX_set_cert_with_extern_psk(WOLFSSL_CTX* ctx, int state);
15255
15256/*!
15257    \ingroup Setup
15258
15259    \brief Enable or disable TLS 1.3 certificate authentication with external
15260    PSK (RFC8773bis) on a connection.
15261
15262    This call applies to a single WOLFSSL object. Any non-zero \p state value
15263    enables the feature and zero disables it.
15264
15265    Availability:
15266      - Built with `--enable-tls13 --enable-psk --enable-cert-with-extern-psk`
15267      - Or with `WOLFSSL_TLS13` and `WOLFSSL_CERT_WITH_EXTERN_PSK` defined
15268
15269    \param [in,out] ssl a pointer to a WOLFSSL structure, created using
15270                        wolfSSL_new().
15271    \param [in] state 0 to disable, non-zero to enable.
15272
15273    \return WOLFSSL_SUCCESS on success.
15274    \return WOLFSSL_FAILURE when \p ssl is NULL.
15275
15276    _Example_
15277    \code
15278    WOLFSSL* ssl = wolfSSL_new(ctx);
15279    if (wolfSSL_set_cert_with_extern_psk(ssl, 1) != WOLFSSL_SUCCESS) {
15280        /* handle error */
15281    }
15282    \endcode
15283
15284    \sa wolfSSL_CTX_set_cert_with_extern_psk
15285    \sa wolfSSL_set_psk_client_tls13_callback
15286    \sa wolfSSL_set_psk_server_tls13_callback
15287*/
15288int wolfSSL_set_cert_with_extern_psk(WOLFSSL* ssl, int state);
15289
15290/*!
15291    \ingroup Setup
15292
15293    \brief This function creates a key share entry from the group including
15294    generating a key pair.
15295    The KeyShare extension contains all the generated public keys for key
15296    exchange. If this function is called, then only the groups specified will
15297    be included.
15298    Call this function when a preferred group has been previously established
15299    for the server.
15300
15301    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
15302    \param [in] group a key exchange group identifier.
15303
15304    \return BAD_FUNC_ARG if ssl is NULL.
15305    \return MEMORY_E when dynamic memory allocation fails.
15306    \return WOLFSSL_SUCCESS if successful.
15307
15308    _Example_
15309    \code
15310    int ret;
15311    WOLFSSL* ssl;
15312    ...
15313    ret = wolfSSL_UseKeyShare(ssl, WOLFSSL_ECC_X25519);
15314    if (ret != WOLFSSL_SUCCESS) {
15315        // failed to set key share
15316    }
15317    \endcode
15318
15319    \sa wolfSSL_preferred_group
15320    \sa wolfSSL_CTX_set1_groups_list
15321    \sa wolfSSL_set1_groups_list
15322    \sa wolfSSL_CTX_set_groups
15323    \sa wolfSSL_set_groups
15324    \sa wolfSSL_NoKeyShares
15325*/
15326int wolfSSL_UseKeyShare(WOLFSSL* ssl, word16 group);
15327
15328/*!
15329    \ingroup Setup
15330
15331    \brief This function is called to ensure no key shares are sent in the
15332    ClientHello. This will force the server to respond with a HelloRetryRequest
15333    if a key exchange is required in the handshake.
15334    Call this function when the expected key exchange group is not known and
15335    to avoid the generation of keys unnecessarily.
15336    Note that an extra round-trip will be required to complete the handshake
15337    when a key exchange is required.
15338
15339    \param [in,out] ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
15340
15341    \return BAD_FUNC_ARG if ssl is NULL.
15342    \return SIDE_ERROR if called with a server.
15343    \return WOLFSSL_SUCCESS if successful.
15344
15345    _Example_
15346    \code
15347    int ret;
15348    WOLFSSL* ssl;
15349    ...
15350    ret = wolfSSL_NoKeyShares(ssl);
15351    if (ret != WOLFSSL_SUCCESS) {
15352        // failed to set no key shares
15353    }
15354    \endcode
15355
15356    \sa wolfSSL_UseKeyShare
15357*/
15358int wolfSSL_NoKeyShares(WOLFSSL* ssl);
15359
15360/*!
15361    \ingroup Setup
15362
15363    \brief This function is used to indicate
15364    that the application is a server and will only support the TLS 1.3
15365    protocol. This function allocates memory for and initializes a new
15366    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
15367    with wolfSSL_CTX_new().
15368
15369    \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.
15370
15371    \return If successful, the call will return a pointer to the newly
15372    created WOLFSSL_METHOD structure.
15373    \return FAIL If memory allocation fails when calling XMALLOC, the failure
15374    value of the underlying malloc() implementation will be returned
15375    (typically NULL with errno will be set to ENOMEM).
15376
15377    _Example_
15378    \code
15379    #include <wolfssl/ssl.h>
15380
15381    WOLFSSL_METHOD* method;
15382    WOLFSSL_CTX* ctx;
15383
15384    method = wolfTLSv1_3_server_method_ex(NULL);
15385    if (method == NULL) {
15386        // unable to get method
15387    }
15388
15389    ctx = wolfSSL_CTX_new(method);
15390    ...
15391    \endcode
15392
15393    \sa wolfSSLv3_server_method
15394    \sa wolfTLSv1_server_method
15395    \sa wolfTLSv1_1_server_method
15396    \sa wolfTLSv1_2_server_method
15397    \sa wolfTLSv1_3_server_method
15398    \sa wolfDTLSv1_server_method
15399    \sa wolfSSLv23_server_method
15400    \sa wolfSSL_CTX_new
15401*/
15402WOLFSSL_METHOD *wolfTLSv1_3_server_method_ex(void* heap);
15403
15404/*!
15405    \ingroup Setup
15406
15407    \brief This function is used to indicate
15408    that the application is a client and will only support the TLS 1.3
15409    protocol. This function allocates memory for and initializes a new
15410    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
15411    with wolfSSL_CTX_new().
15412
15413    \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.
15414
15415    \return If successful, the call will return a pointer to the newly
15416    created WOLFSSL_METHOD structure.
15417    \return FAIL If memory allocation fails when calling XMALLOC, the failure
15418    value of the underlying malloc() implementation will be returned
15419    (typically NULL with errno will be set to ENOMEM).
15420
15421    _Example_
15422    \code
15423    #include <wolfssl/ssl.h>
15424
15425    WOLFSSL_METHOD* method;
15426    WOLFSSL_CTX* ctx;
15427
15428    method = wolfTLSv1_3_client_method_ex(NULL);
15429    if (method == NULL) {
15430        // unable to get method
15431    }
15432
15433    ctx = wolfSSL_CTX_new(method);
15434    ...
15435    \endcode
15436
15437    \sa wolfSSLv3_client_method
15438    \sa wolfTLSv1_client_method
15439    \sa wolfTLSv1_1_client_method
15440    \sa wolfTLSv1_2_client_method
15441    \sa wolfTLSv1_3_client_method
15442    \sa wolfDTLSv1_client_method
15443    \sa wolfSSLv23_client_method
15444    \sa wolfSSL_CTX_new
15445*/
15446WOLFSSL_METHOD *wolfTLSv1_3_client_method_ex(void* heap);
15447
15448/*!
15449    \ingroup Setup
15450
15451    \brief This function is used to indicate
15452    that the application is a server and will only support the TLS 1.3
15453    protocol. This function allocates memory for and initializes a new
15454    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
15455    with wolfSSL_CTX_new().
15456
15457    \return If successful, the call will return a pointer to the newly
15458    created WOLFSSL_METHOD structure.
15459    \return FAIL If memory allocation fails when calling XMALLOC, the failure
15460    value of the underlying malloc() implementation will be returned
15461    (typically NULL with errno will be set to ENOMEM).
15462
15463    _Example_
15464    \code
15465    #include <wolfssl/ssl.h>
15466
15467    WOLFSSL_METHOD* method;
15468    WOLFSSL_CTX* ctx;
15469
15470    method = wolfTLSv1_3_server_method();
15471    if (method == NULL) {
15472        // unable to get method
15473    }
15474
15475    ctx = wolfSSL_CTX_new(method);
15476    ...
15477    \endcode
15478
15479    \sa wolfSSLv3_server_method
15480    \sa wolfTLSv1_server_method
15481    \sa wolfTLSv1_1_server_method
15482    \sa wolfTLSv1_2_server_method
15483    \sa wolfTLSv1_3_server_method_ex
15484    \sa wolfDTLSv1_server_method
15485    \sa wolfSSLv23_server_method
15486    \sa wolfSSL_CTX_new
15487*/
15488WOLFSSL_METHOD *wolfTLSv1_3_server_method(void);
15489
15490/*!
15491    \ingroup Setup
15492
15493    \brief This function is used to indicate
15494    that the application is a client and will only support the TLS 1.3
15495    protocol. This function allocates memory for and initializes a new
15496    wolfSSL_METHOD structure to be used when creating the SSL/TLS context
15497    with wolfSSL_CTX_new().
15498
15499    \return If successful, the call will return a pointer to the newly
15500    created WOLFSSL_METHOD structure.
15501    \return FAIL If memory allocation fails when calling XMALLOC, the failure
15502    value of the underlying malloc() implementation will be returned
15503    (typically NULL with errno will be set to ENOMEM).
15504
15505    _Example_
15506    \code
15507    #include <wolfssl/ssl.h>
15508
15509    WOLFSSL_METHOD* method;
15510    WOLFSSL_CTX* ctx;
15511
15512    method = wolfTLSv1_3_client_method();
15513    if (method == NULL) {
15514        // unable to get method
15515    }
15516
15517    ctx = wolfSSL_CTX_new(method);
15518    ...
15519    \endcode
15520
15521    \sa wolfSSLv3_client_method
15522    \sa wolfTLSv1_client_method
15523    \sa wolfTLSv1_1_client_method
15524    \sa wolfTLSv1_2_client_method
15525    \sa wolfTLSv1_3_client_method_ex
15526    \sa wolfDTLSv1_client_method
15527    \sa wolfSSLv23_client_method
15528    \sa wolfSSL_CTX_new
15529*/
15530WOLFSSL_METHOD *wolfTLSv1_3_client_method(void);
15531
15532/*!
15533    \ingroup Setup
15534
15535    \brief This function returns a WOLFSSL_METHOD similar to
15536    wolfTLSv1_3_client_method except that it is not determined
15537    which side yet (server/client).
15538
15539    \param [in] heap a pointer to a buffer that the static memory allocator will use during dynamic memory allocation.
15540
15541    \return WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD
15542    pointer
15543    \return NULL Null if memory allocation error or failure to create method
15544
15545    _Example_
15546    \code
15547    WOLFSSL* ctx;
15548    ctx  = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL));
15549    // check ret value
15550    \endcode
15551
15552    \sa wolfSSL_new
15553    \sa wolfSSL_free
15554*/
15555WOLFSSL_METHOD *wolfTLSv1_3_method_ex(void* heap);
15556
15557/*!
15558    \ingroup Setup
15559
15560    \brief This function returns a WOLFSSL_METHOD similar to
15561    wolfTLSv1_3_client_method except that it is not determined
15562    which side yet (server/client).
15563
15564    \return WOLFSSL_METHOD On successful creations returns a WOLFSSL_METHOD
15565    pointer
15566    \return NULL Null if memory allocation error or failure to create method
15567
15568    _Example_
15569    \code
15570    WOLFSSL* ctx;
15571    ctx  = wolfSSL_CTX_new(wolfTLSv1_3_method());
15572    // check ret value
15573    \endcode
15574
15575    \sa wolfSSL_new
15576    \sa wolfSSL_free
15577*/
15578WOLFSSL_METHOD *wolfTLSv1_3_method(void);
15579
15580/*!
15581 \ingroup SSL
15582 \brief This function sets a fixed / static ephemeral key for testing only
15583 \return 0 Key loaded successfully
15584 \param ctx A WOLFSSL_CTX context pointer
15585 \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
15586 \param key key file path (if keySz == 0) or actual key buffer (PEM or ASN.1)
15587 \param keySz key size (should be 0 for "key" arg is file path)
15588 \param format WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM
15589 \sa wolfSSL_CTX_get_ephemeral_key
15590 */
15591int wolfSSL_CTX_set_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo, const char* key, unsigned int keySz, int format);
15592
15593/*!
15594 \ingroup SSL
15595 \brief This function sets a fixed / static ephemeral key for testing only
15596 \return 0 Key loaded successfully
15597 \param ssl A WOLFSSL object pointer
15598 \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
15599 \param key key file path (if keySz == 0) or actual key buffer (PEM or ASN.1)
15600 \param keySz key size (should be 0 for "key" arg is file path)
15601 \param format WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM
15602 \sa wolfSSL_get_ephemeral_key
15603 */
15604int wolfSSL_set_ephemeral_key(WOLFSSL* ssl, int keyAlgo, const char* key, unsigned int keySz, int format);
15605
15606/*!
15607 \ingroup SSL
15608 \brief This function returns pointer to loaded key as ASN.1/DER
15609 \return 0 Key returned successfully
15610 \param ctx A WOLFSSL_CTX context pointer
15611 \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
15612 \param key key buffer pointer
15613 \param keySz key size pointer
15614 \sa wolfSSL_CTX_set_ephemeral_key
15615 */
15616int wolfSSL_CTX_get_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo,
15617    const unsigned char** key, unsigned int* keySz);
15618
15619/*!
15620 \ingroup SSL
15621 \brief This function returns pointer to loaded key as ASN.1/DER
15622 \return 0 Key returned successfully
15623 \param ssl A WOLFSSL object pointer
15624 \param keyAlgo enum wc_PkType like WC_PK_TYPE_DH and WC_PK_TYPE_ECDH
15625 \param key key buffer pointer
15626 \param keySz key size pointer
15627 \sa wolfSSL_set_ephemeral_key
15628 */
15629int wolfSSL_get_ephemeral_key(WOLFSSL* ssl, int keyAlgo,
15630    const unsigned char** key, unsigned int* keySz);
15631
15632/*!
15633 \ingroup SSL
15634 \brief Sign a message with the chosen message digest, padding, and RSA key
15635 \return WOLFSSL_SUCCESS on success and c on error
15636 \param type      Hash NID
15637 \param m         Message to sign. Most likely this will be the digest of
15638                  the message to sign
15639 \param mLen      Length of message to sign
15640 \param sigRet    Output buffer
15641 \param sigLen    On Input: length of sigRet buffer
15642                  On Output: length of data written to sigRet
15643 \param rsa       RSA key used to sign the input
15644 \param flag      1: Output the signature
15645                  0: Output the value that the unpadded signature should be
15646                     compared to. Note: for RSA_PKCS1_PSS_PADDING the
15647                     wc_RsaPSS_CheckPadding_ex function should be used to check
15648                     the output of a *Verify* function.
15649 \param padding   Padding to use. Only RSA_PKCS1_PSS_PADDING and
15650                  RSA_PKCS1_PADDING are currently supported for signing.
15651 */
15652int wolfSSL_RSA_sign_generic_padding(int hashAlg, const unsigned char* hash,
15653                               unsigned int hLen, unsigned char* sigRet,
15654                               unsigned int* sigLen, WOLFSSL_RSA* rsa,
15655                               int flag, int padding);
15656/*!
15657
15658\brief checks if DTLSv1.3 stack has some messages sent but not yet acknowledged
15659 by the other peer
15660
15661 \return 1 if there are pending messages, 0 otherwise
15662 \param ssl A WOLFSSL object pointer
15663*/
15664int wolfSSL_dtls13_has_pending_msg(WOLFSSL *ssl);
15665
15666/*!
15667    \ingroup SSL
15668    \brief Get the maximum size of Early Data from a session.
15669
15670    \param [in] s  the WOLFSSL_SESSION instance.
15671
15672    \return the value of max_early_data that was configured in the WOLFSSL* the session
15673    was derived from.
15674
15675    \sa wolfSSL_set_max_early_data
15676    \sa wolfSSL_write_early_data
15677    \sa wolfSSL_read_early_data
15678 */
15679unsigned int wolfSSL_SESSION_get_max_early_data(const WOLFSSL_SESSION *s);
15680
15681/*!
15682    \ingroup SSL
15683    \brief Get a new index for external data. This entry applies also for the
15684           following API:
15685           - wolfSSL_CTX_get_ex_new_index
15686           - wolfSSL_get_ex_new_index
15687           - wolfSSL_SESSION_get_ex_new_index
15688           - wolfSSL_X509_get_ex_new_index
15689
15690    \param [in] class_index Identifier for the object class the external data
15691                 index applies to. Ignored by wolfSSL.
15692    \param [in] argl Optional long argument passed through for compatibility.
15693                 Ignored by wolfSSL.
15694    \param [in] argp Optional pointer argument passed through for compatibility.
15695                 Ignored by wolfSSL.
15696    \param [in] new_func Pointer to an external data constructor callback.
15697                 Ignored by wolfSSL.
15698    \param [in] dup_func Pointer to an external data duplicate callback.
15699                 Ignored by wolfSSL.
15700    \param [in] free_func Pointer to an external data destructor callback.
15701                 Ignored by wolfSSL.
15702
15703    \return The new index value to be used with the external data API for this
15704            object class.
15705*/
15706int wolfSSL_CRYPTO_get_ex_new_index(int class_index, long argl, void *argp,
15707                                    WOLFSSL_CRYPTO_EX_new* new_func,
15708                                    WOLFSSL_CRYPTO_EX_dup* dup_func,
15709                                    WOLFSSL_CRYPTO_EX_free* free_func);
15710
15711/*!
15712 \ingroup Setup
15713 \brief  In case this function is called in a client side, set certificate types
15714 that can be sent to its peer. In case called in a server side,
15715 set certificate types that can be acceptable from its peer. Put cert types in the
15716 buffer with prioritised order. To reset the settings to default, pass NULL
15717 for the buffer or pass zero for len. By default, certificate type is only X509.
15718 In case both side intend to send or accept "Raw public key" cert,
15719 WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
15720
15721 \return WOLFSSL_SUCCESS if cert types set successfully
15722 \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
15723  cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
15724  a duplicate value is found in buf.
15725
15726 \param ctx  WOLFSSL_CTX object pointer
15727 \param buf  A buffer where certificate types are stored
15728 \param len  buf size in bytes (same as number of certificate types included)
15729    _Example_
15730 \code
15731  int ret;
15732  WOLFSSL_CTX* ctx;
15733  char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
15734  int len = sizeof(buf)/sizeof(char);
15735  ...
15736
15737  ret = wolfSSL_CTX_set_client_cert_type(ctx, buf, len);
15738 \endcode
15739 \sa wolfSSL_set_client_cert_type
15740 \sa wolfSSL_CTX_set_server_cert_type
15741 \sa wolfSSL_set_server_cert_type
15742 \sa wolfSSL_get_negotiated_client_cert_type
15743 \sa wolfSSL_get_negotiated_server_cert_type
15744 */
15745int wolfSSL_CTX_set_client_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);
15746
15747/*!
15748 \ingroup Setup
15749 \brief  In case this function is called in a server side, set certificate types
15750 that can be sent to its peer. In case called in a client side,
15751 set certificate types that can be acceptable from its peer. Put cert types in the
15752 buffer with prioritised order. To reset the settings to default, pass NULL
15753 for the buffer or pass zero for len. By default, certificate type is only X509.
15754 In case both side intend to send or accept "Raw public key" cert,
15755 WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
15756
15757 \return WOLFSSL_SUCCESS if cert types set successfully
15758 \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
15759  cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
15760  a duplicate value is found in buf.
15761
15762 \param ctx  WOLFSSL_CTX object pointer
15763 \param buf  A buffer where certificate types are stored
15764 \param len  buf size in bytes (same as number of certificate types included)
15765    _Example_
15766 \code
15767  int ret;
15768  WOLFSSL_CTX* ctx;
15769  char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
15770  int len = sizeof(buf)/sizeof(char);
15771  ...
15772
15773  ret = wolfSSL_CTX_set_server_cert_type(ctx, buf, len);
15774 \endcode
15775 \sa wolfSSL_set_client_cert_type
15776 \sa wolfSSL_CTX_set_client_cert_type
15777 \sa wolfSSL_set_server_cert_type
15778 \sa wolfSSL_get_negotiated_client_cert_type
15779 \sa wolfSSL_get_negotiated_server_cert_type
15780 */
15781int wolfSSL_CTX_set_server_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);
15782
15783/*!
15784 \ingroup Setup
15785 \brief  In case this function is called in a client side, set certificate types
15786 that can be sent to its peer. In case called in a server side,
15787 set certificate types that can be acceptable from its peer. Put cert types in the
15788 buffer with prioritised order. To reset the settings to default, pass NULL
15789 for the buffer or pass zero for len. By default, certificate type is only X509.
15790 In case both side intend to send or accept "Raw public key" cert,
15791 WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
15792
15793 \return WOLFSSL_SUCCESS if cert types set successfully
15794 \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
15795  cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
15796  a duplicate value is found in buf.
15797
15798 \param ssl  WOLFSSL object pointer
15799 \param buf  A buffer where certificate types are stored
15800 \param len  buf size in bytes (same as number of certificate types included)
15801    _Example_
15802 \code
15803  int ret;
15804  WOLFSSL* ssl;
15805  char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
15806  int len = sizeof(buf)/sizeof(char);
15807  ...
15808
15809  ret = wolfSSL_set_client_cert_type(ssl, buf, len);
15810 \endcode
15811 \sa wolfSSL_CTX_set_client_cert_type
15812 \sa wolfSSL_CTX_set_server_cert_type
15813 \sa wolfSSL_set_server_cert_type
15814 \sa wolfSSL_get_negotiated_client_cert_type
15815 \sa wolfSSL_get_negotiated_server_cert_type
15816 */
15817int wolfSSL_set_client_cert_type(WOLFSSL* ssl, const char* buf, int len);
15818
15819/*!
15820 \ingroup Setup
15821 \brief  In case this function is called in a server side, set certificate types
15822 that can be sent to its peer. In case called in a client side,
15823 set certificate types that can be acceptable from its peer. Put cert types in the
15824 buffer with prioritised order. To reset the settings to default, pass NULL
15825 for the buffer or pass zero for len. By default, certificate type is only X509.
15826 In case both side intend to send or accept "Raw public key" cert,
15827 WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
15828
15829 \return WOLFSSL_SUCCESS if cert types set successfully
15830 \return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
15831  cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
15832  a duplicate value is found in buf.
15833
15834 \param ctx  WOLFSSL_CTX object pointer
15835 \param buf  A buffer where certificate types are stored
15836 \param len  buf size in bytes (same as number of certificate types included)
15837    _Example_
15838 \code
15839  int ret;
15840  WOLFSSL* ssl;
15841  char buf[] = {WOLFSSL_CERT_TYPE_RPK, WOLFSSL_CERT_TYPE_X509};
15842  int len = sizeof(buf)/sizeof(char);
15843  ...
15844
15845  ret = wolfSSL_set_server_cert_type(ssl, buf, len);
15846 \endcode
15847 \sa wolfSSL_set_client_cert_type
15848 \sa wolfSSL_CTX_set_server_cert_type
15849 \sa wolfSSL_set_server_cert_type
15850 \sa wolfSSL_get_negotiated_client_cert_type
15851 \sa wolfSSL_get_negotiated_server_cert_type
15852 */
15853int wolfSSL_set_server_cert_type(WOLFSSL* ssl, const char* buf, int len);
15854
15855/*!
15856    \ingroup Setup
15857
15858    \brief Enables handshake message grouping for the given WOLFSSL_CTX context.
15859
15860    This function turns on handshake message grouping for all SSL objects created from the specified context.
15861
15862    \return WOLFSSL_SUCCESS on success.
15863    \return BAD_FUNC_ARG if ctx is NULL.
15864
15865    \param ctx Pointer to the WOLFSSL_CTX structure.
15866
15867    _Example_
15868    \code
15869    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method());
15870    wolfSSL_CTX_set_group_messages(ctx);
15871    \endcode
15872
15873    \sa wolfSSL_CTX_clear_group_messages
15874    \sa wolfSSL_set_group_messages
15875    \sa wolfSSL_clear_group_messages
15876*/
15877int wolfSSL_CTX_set_group_messages(WOLFSSL_CTX* ctx);
15878
15879/*!
15880    \ingroup Setup
15881
15882    \brief Disables handshake message grouping for the given WOLFSSL_CTX context.
15883
15884    This function turns off handshake message grouping for all SSL objects created from the specified context.
15885
15886    \return WOLFSSL_SUCCESS on success.
15887    \return BAD_FUNC_ARG if ctx is NULL.
15888
15889    \param ctx Pointer to the WOLFSSL_CTX structure.
15890
15891    _Example_
15892    \code
15893    WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method());
15894    wolfSSL_CTX_clear_group_messages(ctx);
15895    \endcode
15896
15897    \sa wolfSSL_CTX_set_group_messages
15898    \sa wolfSSL_set_group_messages
15899    \sa wolfSSL_clear_group_messages
15900*/
15901int wolfSSL_CTX_clear_group_messages(WOLFSSL_CTX* ctx);
15902
15903/*!
15904    \ingroup Setup
15905
15906    \brief Enables handshake message grouping for the given WOLFSSL object.
15907
15908    This function turns on handshake message grouping for the specified SSL object.
15909
15910    \return WOLFSSL_SUCCESS on success.
15911    \return BAD_FUNC_ARG if ssl is NULL.
15912
15913    \param ssl Pointer to the WOLFSSL structure.
15914
15915    _Example_
15916    \code
15917    WOLFSSL* ssl = wolfSSL_new(ctx);
15918    wolfSSL_set_group_messages(ssl);
15919    \endcode
15920
15921    \sa wolfSSL_clear_group_messages
15922    \sa wolfSSL_CTX_set_group_messages
15923    \sa wolfSSL_CTX_clear_group_messages
15924*/
15925int wolfSSL_set_group_messages(WOLFSSL* ssl);
15926
15927/*!
15928    \ingroup Setup
15929
15930    \brief Disables handshake message grouping for the given WOLFSSL object.
15931
15932    This function turns off handshake message grouping for the specified SSL object.
15933
15934    \return WOLFSSL_SUCCESS on success.
15935    \return BAD_FUNC_ARG if ssl is NULL.
15936
15937    \param ssl Pointer to the WOLFSSL structure.
15938
15939    _Example_
15940    \code
15941    WOLFSSL* ssl = wolfSSL_new(ctx);
15942    wolfSSL_clear_group_messages(ssl);
15943    \endcode
15944
15945    \sa wolfSSL_set_group_messages
15946    \sa wolfSSL_CTX_set_group_messages
15947    \sa wolfSSL_CTX_clear_group_messages
15948*/
15949int wolfSSL_clear_group_messages(WOLFSSL* ssl);
15950
15951/*!
15952 \ingroup SSL
15953 \brief  This function returns the result of the client certificate type
15954 negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as
15955  a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
15956  returned as the certificate type.
15957
15958 \return WOLFSSL_SUCCESS if a negotiated certificate type could be got
15959 \return BAD_FUNC_ARG if NULL was passed for ctx or tp
15960 \param ssl  WOLFSSL object pointer
15961 \param tp  A buffer where a certificate type is to be returned. One of three
15962 certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
15963 WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN.
15964
15965    _Example_
15966 \code
15967  int ret;
15968  WOLFSSL* ssl;
15969  int tp;
15970  ...
15971
15972  ret = wolfSSL_get_negotiated_client_cert_type(ssl, &tp);
15973 \endcode
15974 \sa wolfSSL_set_client_cert_type
15975 \sa wolfSSL_CTX_set_client_cert_type
15976 \sa wolfSSL_set_server_cert_type
15977 \sa wolfSSL_CTX_set_server_cert_type
15978 \sa wolfSSL_get_negotiated_server_cert_type
15979 */
15980int wolfSSL_get_negotiated_client_cert_type(WOLFSSL* ssl, int* tp);
15981
15982/*!
15983 \ingroup SSL
15984 \brief  This function returns the result of the server certificate type
15985 negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as
15986  a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
15987  returned as the certificate type.
15988
15989 \return WOLFSSL_SUCCESS if a negotiated certificate type could be got
15990 \return BAD_FUNC_ARG if NULL was passed for ctx or tp
15991 \param ssl  WOLFSSL object pointer
15992 \param tp  A buffer where a certificate type is to be returned. One of three
15993 certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
15994 WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN.
15995    _Example_
15996 \code
15997  int ret;
15998  WOLFSSL* ssl;
15999  int tp;
16000　...
16001
16002  ret = wolfSSL_get_negotiated_server_cert_type(ssl, &tp);
16003 \endcode
16004 \sa wolfSSL_set_client_cert_type
16005 \sa wolfSSL_CTX_set_client_cert_type
16006 \sa wolfSSL_set_server_cert_type
16007 \sa wolfSSL_CTX_set_server_cert_type
16008 \sa wolfSSL_get_negotiated_client_cert_type
16009 */
16010int wolfSSL_get_negotiated_server_cert_type(WOLFSSL* ssl, int* tp);
16011
16012/*!
16013
16014\brief Enable use of ConnectionID extensions for the SSL object. See RFC 9146
16015and RFC 9147
16016
16017 \return WOLFSSL_SUCCESS on success, error code otherwise
16018
16019 \param ssl A WOLFSSL object pointer
16020
16021 \sa wolfSSL_dtls_cid_is_enabled
16022 \sa wolfSSL_dtls_cid_set
16023 \sa wolfSSL_dtls_cid_get_rx_size
16024 \sa wolfSSL_dtls_cid_get_rx
16025 \sa wolfSSL_dtls_cid_get_tx_size
16026 \sa wolfSSL_dtls_cid_get_tx
16027*/
16028int wolfSSL_dtls_cid_use(WOLFSSL* ssl);
16029
16030/*!
16031
16032\brief If invoked after the handshake is complete it checks if ConnectionID was
16033successfully negotiated for the SSL object. See RFC 9146 and RFC 9147
16034
16035 \return 1 if ConnectionID was correctly negotiated, 0 otherwise
16036
16037 \param ssl A WOLFSSL object pointer
16038
16039 \sa wolfSSL_dtls_cid_use
16040 \sa wolfSSL_dtls_cid_set
16041 \sa wolfSSL_dtls_cid_get_rx_size
16042 \sa wolfSSL_dtls_cid_get_rx
16043 \sa wolfSSL_dtls_cid_get_tx_size
16044 \sa wolfSSL_dtls_cid_get_tx
16045*/
16046int wolfSSL_dtls_cid_is_enabled(WOLFSSL* ssl);
16047
16048/*!
16049
16050\brief Set the ConnectionID used by the other peer to send records in this
16051connection. See RFC 9146 and RFC 9147. The ConnectionID must be at maximum
16052DTLS_CID_MAX_SIZE, that is an tunable compile time define, and it can't
16053never be bigger than 255 bytes.
16054
16055 \return WOLFSSL_SUCCESS if ConnectionID was correctly set, error code otherwise
16056
16057 \param ssl A WOLFSSL object pointern
16058 \param cid the ConnectionID to be used
16059 \param size of the ConnectionID provided
16060
16061 \sa wolfSSL_dtls_cid_use
16062 \sa wolfSSL_dtls_cid_is_enabled
16063 \sa wolfSSL_dtls_cid_get_rx_size
16064 \sa wolfSSL_dtls_cid_get_rx
16065 \sa wolfSSL_dtls_cid_get_tx_size
16066 \sa wolfSSL_dtls_cid_get_tx
16067*/
16068int wolfSSL_dtls_cid_set(WOLFSSL* ssl, unsigned char* cid,
16069    unsigned int size);
16070
16071/*!
16072
16073\brief Get the size of the ConnectionID used by the other peer to send records
16074in this connection. See RFC 9146 and RFC 9147. The size is stored in the
16075parameter size.
16076
16077 \return WOLFSSL_SUCCESS if ConnectionID was correctly negotiated, error code
16078 otherwise
16079
16080 \param ssl A WOLFSSL object pointern
16081 \param size a pointer to an unsigned int where the size will be stored
16082
16083 \sa wolfSSL_dtls_cid_use
16084 \sa wolfSSL_dtls_cid_is_enabled
16085 \sa wolfSSL_dtls_cid_set
16086 \sa wolfSSL_dtls_cid_get_rx
16087 \sa wolfSSL_dtls_cid_get_tx_size
16088 \sa wolfSSL_dtls_cid_get_tx
16089*/
16090int wolfSSL_dtls_cid_get_rx_size(WOLFSSL* ssl,
16091    unsigned int* size);
16092
16093/*!
16094
16095\brief Copy the ConnectionID used by the other peer to send records in this
16096connection into the buffer pointed by the parameter buffer. See RFC 9146 and RFC
160979147. The available space in the buffer need to be provided in bufferSz.
16098
16099 \return WOLFSSL_SUCCESS if ConnectionID was correctly copied, error code
16100 otherwise
16101
16102 \param ssl A WOLFSSL object pointern
16103 \param buffer A buffer where the ConnectionID will be copied
16104 \param bufferSz available space in buffer
16105
16106 \sa wolfSSL_dtls_cid_get0_rx
16107 \sa wolfSSL_dtls_cid_use
16108 \sa wolfSSL_dtls_cid_is_enabled
16109 \sa wolfSSL_dtls_cid_set
16110 \sa wolfSSL_dtls_cid_get_rx_size
16111 \sa wolfSSL_dtls_cid_get_tx_size
16112 \sa wolfSSL_dtls_cid_get_tx
16113*/
16114int wolfSSL_dtls_cid_get_rx(WOLFSSL* ssl, unsigned char* buffer,
16115    unsigned int bufferSz);
16116
16117/*!
16118
16119\brief Get the ConnectionID used by the other peer. See RFC 9146 and RFC
161209147.
16121
16122 \return WOLFSSL_SUCCESS if ConnectionID was correctly set in cid.
16123
16124 \param ssl A WOLFSSL object pointern
16125 \param cid Pointer that will be set to the internal memory that holds the CID
16126
16127 \sa wolfSSL_dtls_cid_get_rx
16128 \sa wolfSSL_dtls_cid_use
16129 \sa wolfSSL_dtls_cid_is_enabled
16130 \sa wolfSSL_dtls_cid_set
16131 \sa wolfSSL_dtls_cid_get_rx_size
16132 \sa wolfSSL_dtls_cid_get_tx_size
16133 \sa wolfSSL_dtls_cid_get_tx
16134*/
16135int wolfSSL_dtls_cid_get0_rx(WOLFSSL* ssl, unsigned char** cid);
16136
16137/*!
16138
16139\brief Get the size of the ConnectionID used to send records in this
16140connection. See RFC 9146 and RFC 9147. The size is stored in the parameter size.
16141
16142 \return WOLFSSL_SUCCESS if ConnectionID size was correctly stored, error
16143 code otherwise
16144
16145 \param ssl A WOLFSSL object pointern
16146 \param size a pointer to an unsigned int where the size will be stored
16147
16148 \sa wolfSSL_dtls_cid_use
16149 \sa wolfSSL_dtls_cid_is_enabled
16150 \sa wolfSSL_dtls_cid_set
16151 \sa wolfSSL_dtls_cid_get_rx_size
16152 \sa wolfSSL_dtls_cid_get_rx
16153 \sa wolfSSL_dtls_cid_get_tx
16154*/
16155int wolfSSL_dtls_cid_get_tx_size(WOLFSSL* ssl, unsigned int* size);
16156
16157/*!
16158
16159\brief Copy the ConnectionID used when sending records in this connection into
16160the buffer pointer by the parameter buffer. See RFC 9146 and RFC 9147. The
16161available size need to be provided in bufferSz.
16162
16163 \return WOLFSSL_SUCCESS if ConnectionID was correctly copied, error code
16164 otherwise
16165
16166 \param ssl A WOLFSSL object pointern
16167 \param buffer A buffer where the ConnectionID will be copied
16168 \param bufferSz available space in buffer
16169
16170 \sa wolfSSL_dtls_cid_get0_tx
16171 \sa wolfSSL_dtls_cid_use
16172 \sa wolfSSL_dtls_cid_is_enabled
16173 \sa wolfSSL_dtls_cid_set
16174 \sa wolfSSL_dtls_cid_get_rx_size
16175 \sa wolfSSL_dtls_cid_get_rx
16176 \sa wolfSSL_dtls_cid_get_tx_size
16177*/
16178int wolfSSL_dtls_cid_get_tx(WOLFSSL* ssl, unsigned char* buffer,
16179    unsigned int bufferSz);
16180
16181/*!
16182
16183\brief Get the ConnectionID used when sending records in this connection. See
16184RFC 9146 and RFC 9147.
16185
16186 \return WOLFSSL_SUCCESS if ConnectionID was correctly retrieved, error code
16187 otherwise
16188
16189 \param ssl A WOLFSSL object pointern
16190 \param cid Pointer that will be set to the internal memory that holds the CID
16191
16192 \sa wolfSSL_dtls_cid_get_tx
16193 \sa wolfSSL_dtls_cid_use
16194 \sa wolfSSL_dtls_cid_is_enabled
16195 \sa wolfSSL_dtls_cid_set
16196 \sa wolfSSL_dtls_cid_get_rx_size
16197 \sa wolfSSL_dtls_cid_get_rx
16198 \sa wolfSSL_dtls_cid_get_tx_size
16199*/
16200int wolfSSL_dtls_cid_get0_tx(WOLFSSL* ssl, unsigned char** cid);
16201
16202/*!
16203
16204\brief Extract the ConnectionID from a record datagram/message. See
16205RFC 9146 and RFC 9147.
16206
16207 \param msg buffer holding the datagram read from the network
16208 \param msgSz size of msg in bytes
16209 \param cid pointer to the start of the CID inside the msg buffer
16210 \param cidSz the expected size of the CID. The record layer does not have a CID
16211 size field so we have to know beforehand the size of the CID. It is recommended
16212 to use a constant CID for all connections.
16213
16214 \sa wolfSSL_dtls_cid_get_tx
16215 \sa wolfSSL_dtls_cid_use
16216 \sa wolfSSL_dtls_cid_is_enabled
16217 \sa wolfSSL_dtls_cid_set
16218 \sa wolfSSL_dtls_cid_get_rx_size
16219 \sa wolfSSL_dtls_cid_get_rx
16220 \sa wolfSSL_dtls_cid_get_tx_size
16221*/
16222const unsigned char* wolfSSL_dtls_cid_parse(const unsigned char* msg,
16223        unsigned int msgSz, unsigned int cidSz);
16224
16225/*!
16226    \ingroup TLS
16227    \brief On the server, this sets a list of CA names to be sent to clients in
16228    certificate requests as a hint for which CA's are supported by the server.
16229
16230    On the client, this function has no effect.
16231
16232    \param [in] ctx Pointer to the wolfSSL context
16233    \param [in] names List of names to be set
16234
16235    \sa wolfSSL_set_client_CA_list
16236    \sa wolfSSL_CTX_get_client_CA_list
16237    \sa wolfSSL_get_client_CA_list
16238    \sa wolfSSL_CTX_set0_CA_list
16239    \sa wolfSSL_set0_CA_list
16240    \sa wolfSSL_CTX_get0_CA_list
16241    \sa wolfSSL_get0_CA_list
16242    \sa wolfSSL_get0_peer_CA_list
16243*/
16244void wolfSSL_CTX_set_client_CA_list(WOLFSSL_CTX* ctx,
16245                                    WOLF_STACK_OF(WOLFSSL_X509_NAME)* names);
16246
16247/*!
16248    \ingroup TLS
16249    \brief This retrieves the list previously set via
16250     wolfSSL_CTX_set_client_CA_list, or NULL if no list has been set.
16251
16252    \param [in] ctx Pointer to the wolfSSL context
16253    \return A stack of WOLFSSL_X509_NAMEs containing the CA names
16254
16255    \sa wolfSSL_set_client_CA_list
16256    \sa wolfSSL_CTX_set_client_CA_list
16257    \sa wolfSSL_get_client_CA_list
16258    \sa wolfSSL_CTX_set0_CA_list
16259    \sa wolfSSL_set0_CA_list
16260    \sa wolfSSL_CTX_get0_CA_list
16261    \sa wolfSSL_get0_CA_list
16262    \sa wolfSSL_get0_peer_CA_list
16263*/
16264WOLFSSL_STACK *wolfSSL_CTX_get_client_CA_list(
16265        const WOLFSSL_CTX *ctx);
16266
16267/*!
16268    \ingroup TLS
16269    \brief Same as wolfSSL_CTX_set_client_CA_list, but specific to a session.
16270    If a CA list is set on both the context and the session, the list on the
16271    session is used.
16272
16273    \param [in] ssl Pointer to the WOLFSSL object
16274    \param [in] names List of names to be set.
16275
16276    \sa wolfSSL_CTX_set_client_CA_list
16277    \sa wolfSSL_CTX_get_client_CA_list
16278    \sa wolfSSL_get_client_CA_list
16279    \sa wolfSSL_CTX_set0_CA_list
16280    \sa wolfSSL_set0_CA_list
16281    \sa wolfSSL_CTX_get0_CA_list
16282    \sa wolfSSL_get0_CA_list
16283    \sa wolfSSL_get0_peer_CA_list
16284*/
16285void wolfSSL_set_client_CA_list(WOLFSSL* ssl,
16286                                    WOLF_STACK_OF(WOLFSSL_X509_NAME)* names);
16287
16288/*!
16289    \ingroup TLS
16290    \brief On the server, this retrieves the list previously set via
16291    wolfSSL_set_client_CA_list. If none was set, returns the list previously
16292    set via wolfSSL_CTX_set_client_CA_list. If no list at all was set, returns
16293    NULL.
16294
16295    On the client, this retrieves the list that was received from the server,
16296    or NULL if none was received. wolfSSL_CTX_set_cert_cb can be used to
16297    register a callback to dynamically load certificates when a certificate
16298    request is received from the server.
16299
16300    \param [in] ssl Pointer to the WOLFSSL object
16301    \return A stack of WOLFSSL_X509_NAMEs containing the CA names
16302
16303    \sa wolfSSL_CTX_set_cert_cb
16304    \sa wolfSSL_CTX_set_client_CA_list
16305    \sa wolfSSL_CTX_get_client_CA_list
16306    \sa wolfSSL_get_client_CA_list
16307    \sa wolfSSL_CTX_set0_CA_list
16308    \sa wolfSSL_set0_CA_list
16309    \sa wolfSSL_CTX_get0_CA_list
16310    \sa wolfSSL_get0_CA_list
16311    \sa wolfSSL_get0_peer_CA_list
16312*/
16313WOLFSSL_STACK* wolfSSL_get_client_CA_list(
16314            const WOLFSSL* ssl);
16315
16316/*!
16317    \ingroup TLS
16318    \brief This function sets a list of CA names to be sent to the peer as a
16319    hint for which CA's are supported for its authentication.
16320
16321    In TLS >= 1.3, this is supported in both directions between the client and
16322    the server. On the server, the CA names will be sent as part of a
16323    CertificateRequest, making this function an equivalent of *_set_client_CA_list;
16324    on the client, these are sent as part of ClientHello.
16325
16326    In TLS < 1.3, sending CA names from the client to the server is not
16327    supported, therefore this function is equivalent to
16328    wolfSSL_CTX_set_client_CA_list.
16329
16330    Note that the lists set via *_set_client_CA_list and *_set0_CA_list are
16331    separate internally, i.e. calling *_get_client_CA_list will not retrieve a
16332    list set via *_set0_CA_list and vice versa. If both are set, the server will
16333    ignore *_set0_CA_list when sending CA names to the client.
16334
16335    \param [in] ctx Pointer to the wolfSSL context
16336    \param [in] names List of names to be set
16337
16338    \sa wolfSSL_CTX_set_client_CA_list
16339    \sa wolfSSL_set_client_CA_list
16340    \sa wolfSSL_CTX_get_client_CA_list
16341    \sa wolfSSL_get_client_CA_list
16342    \sa wolfSSL_set0_CA_list
16343    \sa wolfSSL_CTX_get0_CA_list
16344    \sa wolfSSL_get0_CA_list
16345    \sa wolfSSL_get0_peer_CA_list
16346*/
16347void wolfSSL_CTX_set0_CA_list(WOLFSSL_CTX *ctx,
16348        WOLF_STACK_OF(WOLFSSL_X509_NAME)* names);
16349
16350/*!
16351    \ingroup TLS
16352    \brief This retrieves the list previously set via
16353    wolfSSL_CTX_set0_CA_list, or NULL if no list has been set.
16354
16355    \param [in] ctx Pointer to the wolfSSL context
16356    \return A stack of WOLFSSL_X509_NAMEs containing the CA names
16357
16358    \sa wolfSSL_CTX_set_client_CA_list
16359    \sa wolfSSL_set_client_CA_list
16360    \sa wolfSSL_CTX_get_client_CA_list
16361    \sa wolfSSL_get_client_CA_list
16362    \sa wolfSSL_CTX_set0_CA_list
16363    \sa wolfSSL_set0_CA_list
16364    \sa wolfSSL_get0_CA_list
16365    \sa wolfSSL_get0_peer_CA_list
16366*/
16367WOLFSSL_STACK *wolfSSL_CTX_get0_CA_list(
16368        const WOLFSSL_CTX *ctx);
16369
16370/*!
16371    \ingroup TLS
16372    \brief Same as wolfSSL_CTX_set0_CA_list, but specific to a session.
16373    If a CA list is set on both the context and the session, the list on the
16374    session is used.
16375
16376    \param [in] ssl Pointer to the WOLFSSL object
16377    \param [in] names List of names to be set.
16378
16379    \sa wolfSSL_CTX_set_client_CA_list
16380    \sa wolfSSL_set_client_CA_list
16381    \sa wolfSSL_CTX_get_client_CA_list
16382    \sa wolfSSL_get_client_CA_list
16383    \sa wolfSSL_CTX_set0_CA_list
16384    \sa wolfSSL_CTX_get0_CA_list
16385    \sa wolfSSL_get0_CA_list
16386    \sa wolfSSL_get0_peer_CA_list
16387*/
16388void wolfSSL_set0_CA_list(WOLFSSL *ssl,
16389        WOLF_STACK_OF(WOLFSSL_X509_NAME) *names);
16390
16391/*!
16392    \ingroup TLS
16393    \brief This retrieves the list previously set via wolfSSL_set0_CA_list. If
16394    none was set, returns the list previously set via
16395    wolfSSL_CTX_set0_CA_list. If no list at all was set, returns NULL.
16396
16397    \param [in] ssl Pointer to the WOLFSSL object
16398    \return A stack of WOLFSSL_X509_NAMEs containing the CA names
16399
16400    \sa wolfSSL_CTX_set_client_CA_list
16401    \sa wolfSSL_set_client_CA_list
16402    \sa wolfSSL_CTX_get_client_CA_list
16403    \sa wolfSSL_get_client_CA_list
16404    \sa wolfSSL_CTX_set0_CA_list
16405    \sa wolfSSL_set0_CA_list
16406    \sa wolfSSL_CTX_get0_CA_list
16407    \sa wolfSSL_get0_peer_CA_list
16408*/
16409WOLFSSL_STACK *wolfSSL_get0_CA_list(
16410        const WOLFSSL *ssl);
16411
16412/*!
16413    \ingroup TLS
16414    \brief This returns the CA list received from the peer.
16415
16416    On the client, this is the list sent by the server in a CertificateRequest,
16417    and this function is equivalent to wolfSSL_get_client_CA_list.
16418
16419    On the server, this is the list sent by the client in the ClientHello message
16420    in TLS >= 1.3; in TLS < 1.3, the function always returns NULL on the server
16421    side.
16422
16423    wolfSSL_CTX_set_cert_cb can be used to register a callback to dynamically
16424    load certificates when a CA list is received from the peer.
16425
16426    \param [in] ssl Pointer to the WOLFSSL object
16427    \return A stack of WOLFSSL_X509_NAMEs containing the CA names
16428
16429    \sa wolfSSL_CTX_set_cert_cb
16430    \sa wolfSSL_CTX_set_client_CA_list
16431    \sa wolfSSL_set_client_CA_list
16432    \sa wolfSSL_CTX_get_client_CA_list
16433    \sa wolfSSL_get_client_CA_list
16434    \sa wolfSSL_CTX_set0_CA_list
16435    \sa wolfSSL_set0_CA_list
16436    \sa wolfSSL_CTX_get0_CA_list
16437    \sa wolfSSL_get0_CA_list
16438*/
16439WOLFSSL_STACK *wolfSSL_get0_peer_CA_list(const WOLFSSL *ssl);
16440
16441/*!
16442    \ingroup TLS
16443    \brief This function sets a callback that will be called whenever a
16444    certificate is about to be used, to allow the application to inspect, set
16445    or clear any certificates, for example to react to a CA list sent from the
16446    peer.
16447
16448    \param [in] ctx Pointer to the wolfSSL context
16449    \param [in] cb Function pointer to the callback
16450    \param [in] arg Pointer that will be passed to the callback
16451
16452    \sa wolfSSL_get0_peer_CA_list
16453    \sa wolfSSL_get_client_CA_list
16454*/
16455void wolfSSL_CTX_set_cert_cb(WOLFSSL_CTX* ctx,
16456    int (*cb)(WOLFSSL *, void *), void *arg);
16457
16458/*!
16459    \ingroup TLS
16460
16461    \brief This function returns the raw list of ciphersuites and signature
16462    algorithms offered by the client. The lists are only stored and returned
16463    inside a callback setup with wolfSSL_CTX_set_cert_cb(). This is useful to
16464    be able to dynamically load certificates and keys based on the available
16465    ciphersuites and signature algorithms.
16466
16467    \param [in] ssl The WOLFSSL object to extract the lists from.
16468    \param [out] suites Raw and unfiltered list of client ciphersuites.
16469                        May be NULL if no suites are available.
16470    \param [out] suiteSz Size of suites in bytes.
16471    \param [out] hashSigAlgo Raw and unfiltered list of client signature
16472                        algorithms. May be NULL if not provided.
16473    \param [out] hashSigAlgoSz Size of hashSigAlgo in bytes.
16474    \return WOLFSSL_SUCCESS when suites available
16475    \return WOLFSSL_FAILURE when suites not available
16476
16477    _Example_
16478    \code
16479    int certCB(WOLFSSL* ssl, void* arg)
16480    {
16481        const byte* suites = NULL;
16482        word16 suiteSz = 0;
16483        const byte* hashSigAlgo = NULL;
16484        word16 hashSigAlgoSz = 0;
16485
16486        wolfSSL_get_client_suites_sigalgs(ssl, &suites, &suiteSz, &hashSigAlgo,
16487                &hashSigAlgoSz);
16488
16489        // Choose certificate to load based on ciphersuites and sigalgs
16490    }
16491
16492    WOLFSSL* ctx;
16493    ctx  = wolfSSL_CTX_new(wolfTLSv1_3_method_ex(NULL));
16494    wolfSSL_CTX_set_cert_cb(ctx, certCB, NULL);
16495    \endcode
16496
16497    \sa wolfSSL_get_ciphersuite_info
16498    \sa wolfSSL_get_sigalg_info
16499*/
16500int wolfSSL_get_client_suites_sigalgs(const WOLFSSL* ssl,
16501        const byte** suites, word16* suiteSz,
16502        const byte** hashSigAlgo, word16* hashSigAlgoSz);
16503
16504/*!
16505    \ingroup TLS
16506
16507    \brief This returns information about the ciphersuite directly from the
16508    raw ciphersuite bytes.
16509
16510    \param [in] first First byte of the ciphersuite
16511    \param [in] second Second byte of the ciphersuite
16512
16513    \return WOLFSSL_CIPHERSUITE_INFO A struct containing information about the
16514    type of authentication used in the ciphersuite.
16515
16516    _Example_
16517    \code
16518    WOLFSSL_CIPHERSUITE_INFO info =
16519            wolfSSL_get_ciphersuite_info(suites[0], suites[1]);
16520    if (info.rsaAuth)
16521        haveRSA = 1;
16522    else if (info.eccAuth)
16523        haveECC = 1;
16524    \endcode
16525
16526    \sa wolfSSL_get_client_suites_sigalgs
16527    \sa wolfSSL_get_sigalg_info
16528*/
16529WOLFSSL_CIPHERSUITE_INFO wolfSSL_get_ciphersuite_info(byte first,
16530        byte second);
16531
16532/*!
16533    \ingroup TLS
16534
16535    \brief This returns information about the hash and signature algorithm
16536    directly from the raw ciphersuite bytes.
16537
16538    \param [in] first First byte of the hash and signature algorithm
16539    \param [in] second Second byte of the hash and signature algorithm
16540    \param [out] hashAlgo The enum wc_HashType of the MAC algorithm
16541    \param [out] sigAlgo The enum Key_Sum of the authentication algorithm
16542
16543    \return 0            when info was correctly set
16544    \return BAD_FUNC_ARG when either input parameters are NULL or the bytes
16545                         are not a recognized sigalg suite
16546
16547    _Example_
16548    \code
16549    enum wc_HashType hashAlgo;
16550    enum Key_Sum sigAlgo;
16551
16552    wolfSSL_get_sigalg_info(hashSigAlgo[idx+0], hashSigAlgo[idx+1],
16553            &hashAlgo, &sigAlgo);
16554
16555    if (sigAlgo == RSAk || sigAlgo == RSAPSSk)
16556        haveRSA = 1;
16557    else if (sigAlgo == ECDSAk)
16558        haveECC = 1;
16559    \endcode
16560
16561    \sa wolfSSL_get_client_suites_sigalgs
16562    \sa wolfSSL_get_ciphersuite_info
16563*/
16564int wolfSSL_get_sigalg_info(byte first, byte second,
16565        int* hashAlgo, int* sigAlgo);
16566
16567/*!
16568    \brief This function will set the password callback in the provided CTX.
16569    This callback is used when loading an encrypted cert or key which requires
16570    a password.
16571
16572    \param ctx a pointer to a WOLFSSL_CTX structure, created with
16573    wolfSSL_CTX_new().
16574    \param cb a function pointer to (*wc_pem_password_cb) that is set to the
16575    passwd_cb member of the WOLFSSL_CTX.
16576
16577    _Example_
16578    \code
16579    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
16580    int PasswordCallBack(char* passwd, int sz, int rw, void* userdata) {
16581
16582    }
16583    …
16584    wolfSSL_CTX_set_default_passwd_cb(ctx, PasswordCallBack);
16585    \endcode
16586
16587    \sa wolfSSL_CTX_set_default_passwd_cb_userdata
16588*/
16589void wolfSSL_CTX_set_default_passwd_cb(WOLFSSL_CTX* ctx,
16590                                        wc_pem_password_cb* cb);
16591
16592/*!
16593    \brief This function will set the userdata argument to the passwd_userdata
16594    member of the WOLFSSL_CTX structure.
16595    This member is passed into the CTX's password callback when called.
16596
16597    \param ctx a pointer to a WOLFSSL_CTX structure, created with
16598    wolfSSL_CTX_new().
16599    \param userdata a pointer to userdata which is passed into the
16600    password callback.
16601
16602    _Example_
16603    \code
16604    WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
16605    int data;
16606    …
16607    wolfSSL_CTX_set_default_passwd_cb_userdata(ctx, (void*)&data);
16608    \endcode
16609
16610    \sa wolfSSL_CTX_set_default_passwd_cb
16611*/
16612void wolfSSL_CTX_set_default_passwd_cb_userdata(WOLFSSL_CTX* ctx,
16613                                                   void* userdata);
16614
16615/*!
16616    \ingroup Setup
16617
16618    \brief Gets the state of the secure renegotiation (SCR) check requirement.
16619
16620    This function returns whether the client requires the server to acknowledge
16621    the secure renegotiation extension and enable secure renegotiation when
16622    sending it from the client. When enabled, the client will generate a fatal
16623    handshake_failure alert if the server does not acknowledge the extension
16624    in the ServerHello message, as required by RFC 9325.
16625
16626    \return 1 if the SCR check is enabled.
16627    \return 0 if the SCR check is disabled.
16628    \return BAD_FUNC_ARG if ssl is NULL.
16629
16630    \param ssl Pointer to the WOLFSSL structure, created with wolfSSL_new().
16631
16632    _Example_
16633    \code
16634    WOLFSSL* ssl;
16635    int enabled;
16636
16637    ssl = wolfSSL_new(ctx);
16638    enabled = wolfSSL_get_scr_check_enabled(ssl);
16639    if (enabled) {
16640        // SCR check is enabled
16641    }
16642    \endcode
16643
16644    \sa wolfSSL_set_scr_check_enabled
16645*/
16646int wolfSSL_get_scr_check_enabled(const WOLFSSL* ssl);
16647
16648/*!
16649    \ingroup Setup
16650
16651    \brief Sets the state of the secure renegotiation (SCR) check requirement.
16652
16653    This function enables or disables the requirement for the server to
16654    acknowledge the secure renegotiation extension and enable secure
16655    renegotiation when sending it from the client. When enabled, the client
16656    will generate a fatal handshake_failure alert if the server does not
16657    acknowledge the extension in the ServerHello message, as required by
16658    RFC 9325.
16659
16660    \return WOLFSSL_SUCCESS on success.
16661    \return BAD_FUNC_ARG if ssl is NULL.
16662
16663    \param ssl Pointer to the WOLFSSL structure, created with wolfSSL_new().
16664    \param enabled Non-zero to enable the SCR check, zero to disable it.
16665
16666    _Example_
16667    \code
16668    WOLFSSL* ssl;
16669    int ret;
16670
16671    ssl = wolfSSL_new(ctx);
16672    ret = wolfSSL_set_scr_check_enabled(ssl, 1);
16673    if (ret != WOLFSSL_SUCCESS) {
16674        // Error setting SCR check
16675    }
16676    \endcode
16677
16678    \sa wolfSSL_get_scr_check_enabled
16679*/
16680int wolfSSL_set_scr_check_enabled(WOLFSSL* ssl, byte enabled);