CURLOPT_SSL_CTX_FUNCTION.3: added example

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" *

.\" * This software is licensed as described in the file COPYING, which

.\" * you should have received as part of this distribution. The terms

This function will get called on all new connections made to a server, during

the SSL negotiation. The SSL_CTX pointer will be a new one every time.

To use this properly, a non-trivial amount of knowledge of your SSL library

is necessary. For example, you can use this function to call library-specific

To use this properly, a non-trivial amount of knowledge of your SSL library is

necessary. For example, you can use this function to call library-specific

callbacks to add additional validation code for certificates, and even to

change the actual URI of a HTTPS request (example used in the lib509 test

case).  See also the example section for a replacement of the key, certificate

and trust file settings.

change the actual URI of a HTTPS request.

.SH DEFAULT

NULL

.SH PROTOCOLS

All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.

.SH EXAMPLE

TODO

/* OpenSSL specific */

#include <openssl/ssl.h>

#include <curl/curl.h>

#include <stdio.h>

static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm)

{

  X509_STORE *store;

  X509 *cert=NULL;

  BIO *bio;

  char *mypem = /* example CA cert PEM - shortened */

    "-----BEGIN CERTIFICATE-----\n"

    "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\n"

    "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\n"

    "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\n"

    "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\n"

    "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\n"

    "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\n"

    "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\n"\

    "-----END CERTIFICATE-----\n";

  /* get a BIO */

  bio=BIO_new_mem_buf(mypem, -1);

  /* use it to read the PEM formatted certificate from memory into an X509

   * structure that SSL can use

   */

  PEM_read_bio_X509(bio, &cert, 0, NULL);

  if(cert == NULL)

    printf("PEM_read_bio_X509 failed...\n");

  /* get a pointer to the X509 certificate store (which may be empty!) */

  store=SSL_CTX_get_cert_store((SSL_CTX *)sslctx);

  /* add our certificate to this store */

  if(X509_STORE_add_cert(store, cert)==0)

    printf("error adding certificate\n");

  /* decrease reference counts */

  X509_free(cert);

  BIO_free(bio);

  /* all set to go */

  return CURLE_OK;

}

int main(void)

{

  CURL * ch;

  CURLcode rv;

  rv=curl_global_init(CURL_GLOBAL_ALL);

  ch=curl_easy_init();

  rv=curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM");

  rv=curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L);

  rv=curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/");

  /* Retrieve page using cacerts' certificate -> will succeed

   * load the certificate by installing a function doing the nescessary

   * "modifications" to the SSL CONTEXT just before link init

   */

  rv=curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);

  rv=curl_easy_perform(ch);

  if(rv==CURLE_OK)

    printf("*** transfer succeeded ***\n");

  else

    printf("*** transfer failed ***\n");

  curl_easy_cleanup(ch);

  curl_global_cleanup();

  return rv;

}

.SH AVAILABILITY

Added in 7.11.0 for OpenSSL. Added in 7.42.0 for wolfSSL/CyaSSL. Other SSL

backends not supported.