Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CURLOPT_SSL_CTX_FUNCTION(3)curl_easy_setopt optionsCURLOPT_SSL_CTX_FUNCTION(3)

NAME
       CURLOPT_SSL_CTX_FUNCTION	 -  SSL	 context  callback  for	OpenSSL, wolf-
       SSL/CyaSSL or mbedTLS

SYNOPSIS
       #include	<curl/curl.h>

       CURLcode	ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *userptr);

       CURLcode	curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION,
				 ssl_ctx_callback);

DESCRIPTION
       This option only	works for libcurl powered by  OpenSSL,	wolfSSL/CyaSSL
       or mbedTLS. If libcurl was built	against	another	SSL library this func-
       tionality is absent.

       Pass a pointer to your callback function, which should match the	proto-
       type shown above.

       This  callback function gets called by libcurl just before the initial-
       ization of an SSL connection after having processed all other  SSL  re-
       lated options to	give a last chance to an application to	modify the be-
       haviour of the SSL initialization. The ssl_ctx parameter	is actually  a
       pointer to the SSL library's SSL_CTX for	OpenSSL	or wolfSSL/CyaSSL, and
       a pointer to mbedtls_ssl_config for mbedTLS. If an  error  is  returned
       from  the callback no attempt to	establish a connection is made and the
       perform operation will  return  the  callback's	error  code.  Set  the
       userptr argument	with the CURLOPT_SSL_CTX_DATA(3) option.

       This  function will get called on all new connections made to a server,
       during the SSL negotiation. The ssl_ctx will point to a newly  initial-
       ized  object  each time,	but note the pointer may be the	same as	from a
       prior call.

       To use this properly, a non-trivial amount of knowledge of your SSL li-
       brary  is necessary. For	example, you can use this function to call li-
       brary-specific callbacks	to add additional validation code for certifi-
       cates, and even to change the actual URI	of a HTTPS request.

DEFAULT
       NULL

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

EXAMPLE
       /* 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 necessary
	  * "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;
       }

AVAILABILITY
       Added  in 7.11.0	for OpenSSL. Added in 7.42.0 for wolfSSL/CyaSSL. Added
       in 7.54.0 for mbedTLS. Other SSL	backends not supported.

RETURN VALUE
       CURLE_OK	if supported; or an error such as:

       CURLE_NOT_BUILT_IN - Not	supported by the SSL backend

       CURLE_UNKNOWN_OPTION

SEE ALSO
       CURLOPT_SSL_CTX_DATA(3),	CURLOPT_SSL_VERIFYPEER(3),

libcurl	7.54.1			March 26, 2017	   CURLOPT_SSL_CTX_FUNCTION(3)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT | PROTOCOLS | EXAMPLE | AVAILABILITY | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CURLOPT_SSL_CTX_FUNCTION&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help