From f9797871aadeed125e01a3510e7c8222683f9529 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sun, 5 Jan 2014 10:16:22 +0000 Subject: examples: Added IMAP SSL and TLS examples --- docs/examples/Makefile.inc | 2 +- docs/examples/imap-ssl.c | 85 ++++++++++++++++++++++++++++++++++++++++++++++ docs/examples/imap-tls.c | 84 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 170 insertions(+), 1 deletion(-) create mode 100644 docs/examples/imap-ssl.c create mode 100644 docs/examples/imap-tls.c (limited to 'docs') diff --git a/docs/examples/Makefile.inc b/docs/examples/Makefile.inc index 5311c5b28..60e457c14 100644 --- a/docs/examples/Makefile.inc +++ b/docs/examples/Makefile.inc @@ -7,7 +7,7 @@ check_PROGRAMS = 10-at-a-time anyauthput cookie_interface debug fileupload \ smtp-multi smtp-send smtp-tls smtp-vrfy smtp-expn rtsp externalsocket \ resolve progressfunc pop3s pop3slist imap-list imap-fetch imap-store \ imap-append imap-examine imap-search imap-create imap-delete imap-copy \ - url2file sftpget ftpsget postinmemory + imap-ssl imap-tls url2file sftpget ftpsget postinmemory # These examples require external dependencies that may not be commonly # available on POSIX systems, so don't bother attempting to compile them here. diff --git a/docs/examples/imap-ssl.c b/docs/examples/imap-ssl.c new file mode 100644 index 000000000..e42ff3922 --- /dev/null +++ b/docs/examples/imap-ssl.c @@ -0,0 +1,85 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2014, Daniel Stenberg, , et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include +#include + +/* This is a simple example showing how to fetch mail using libcurl's IMAP + * capabilities. It builds on the imap-fetch.c example adding transport + * security to protect the authentication details from being snooped. + * + * Note that this example requires libcurl 7.30.0 or above. + */ + +int main(void) +{ + CURL *curl; + CURLcode res = CURLE_OK; + + curl = curl_easy_init(); + if(curl) { + /* Set username and password */ + curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); + + /* This will fetch message 1 from the user's inbox. Note the use of + * imaps:// rather than imap:// to request a SSL based connection. */ + curl_easy_setopt(curl, CURLOPT_URL, "imaps://imap.example.com/INBOX/;UID=1"); + + /* If you want to connect to a site who isn't using a certificate that is + * signed by one of the certs in the CA bundle you have, you can skip the + * verification of the server's certificate. This makes the connection + * A LOT LESS SECURE. + * + * If you have a CA cert for the server stored someplace else than in the + * default bundle, then the CURLOPT_CAPATH option might come handy for + * you. */ +#ifdef SKIP_PEER_VERIFICATION + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); +#endif + + /* If the site you're connecting to uses a different host name that what + * they have mentioned in their server certificate's commonName (or + * subjectAltName) fields, libcurl will refuse to connect. You can skip + * this check, but this will make the connection less secure. */ +#ifdef SKIP_HOSTNAME_VERFICATION + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); +#endif + + /* Since the traffic will be encrypted, it is very useful to turn on debug + * information within libcurl to see what is happening during the + * transfer */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* Perform the fetch */ + res = curl_easy_perform(curl); + + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* Always cleanup */ + curl_easy_cleanup(curl); + } + + return (int)res; +} diff --git a/docs/examples/imap-tls.c b/docs/examples/imap-tls.c new file mode 100644 index 000000000..c439864be --- /dev/null +++ b/docs/examples/imap-tls.c @@ -0,0 +1,84 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2014, Daniel Stenberg, , et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include +#include + +/* This is a simple example showing how to fetch mail using libcurl's IMAP + * capabilities. It builds on the imap-fetch.c example adding transport + * security to protect the authentication details from being snooped. + * + * Note that this example requires libcurl 7.30.0 or above. + */ + +int main(void) +{ + CURL *curl; + CURLcode res = CURLE_OK; + + curl = curl_easy_init(); + if(curl) { + /* Set username and password */ + curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); + + /* This will fetch message 1 from the user's inbox */ + curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1"); + + /* In this example, we'll start with a plain text connection, and upgrade + * to Transport Layer Security (TLS) using the STARTTLS command. Be careful + * of using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer + * will continue anyway - see the security discussion in the libcurl + * tutorial for more details. */ + curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); + + /* If your server doesn't have a valid certificate, then you can disable + * part of the Transport Layer Security protection by setting the + * CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0 (false). + * curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + * curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); + * That is, in general, a bad idea. It is still better than sending your + * authentication details in plain text though. + * Instead, you should get the issuer certificate (or the host certificate + * if the certificate is self-signed) and add it to the set of certificates + * that are known to libcurl using CURLOPT_CAINFO and/or CURLOPT_CAPATH. See + * docs/SSLCERTS for more information. */ + curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem"); + + /* Since the traffic will be encrypted, it is very useful to turn on debug + * information within libcurl to see what is happening during the + * transfer */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* Perform the fetch */ + res = curl_easy_perform(curl); + + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* Always cleanup */ + curl_easy_cleanup(curl); + } + + return (int)res; +} -- cgit v1.2.3