11. SSL Tutorial - wolfSSL Manual

<!doctype html> <html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link rel="canonical" href="https://wolfssl.com/chapter11.html"> <link rel="icon" href="logo.png"> <meta name="generator" content="mkdocs-1.1.2, mkdocs-material-8.1.6"> <title>11. SSL Tutorial - wolfSSL Manual</title> <link rel="stylesheet" href="assets/stylesheets/main.cd566b2a.min.css"> <link rel="stylesheet" href="assets/stylesheets/palette.e6a45f82.min.css"> <meta name="theme-color" content="#4051b5"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700%7CRoboto+Mono&display=fallback"> <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style> <link rel="stylesheet" href="skin.css"> <script>__md_scope=new URL(".",location),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>  <script async src="https://www.googletagmanager.com/gtag/js?id=UA-64826966-1"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-64826966-1'); </script> </head> <body dir="ltr" data-md-color-scheme="" data-md-color-primary="indigo" data-md-color-accent="indigo"> <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off"> <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off"> <label class="md-overlay" for="__drawer"></label> <div data-md-component="skip"> <a href="#ssl-tutorial" class="md-skip"> Skip to content </a> </div> <div data-md-component="announce"> </div> <header class="md-header" data-md-component="header"> <nav class="md-header__inner md-grid" aria-label="Header"> <a href="." title="wolfSSL Manual" class="md-header__button md-logo" aria-label="wolfSSL Manual" data-md-component="logo"> <img src="logo.png" alt="logo"> </a> <label class="md-header__button md-icon" for="__drawer"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg> </label> <div class="md-header__title" data-md-component="header-title"> <div class="md-header__ellipsis"> <div class="md-header__topic"> <span class="md-ellipsis"> wolfSSL Manual </span> </div> <div class="md-header__topic" data-md-component="header-topic"> <span class="md-ellipsis"> 11. SSL Tutorial </span> </div> </div> </div> <div class="md-ellipsis-nav"> <a href="https://www.wolfssl.com/">Home</a> <a href="https://www.wolfssl.com/products/">Products</a> <a href="https://www.wolfssl.com/download/">Download</a> <a href="https://www.wolfssl.com/license/">License</a> <a href="https://www.wolfssl.com/docs/">Docs</a> <a href="https://www.wolfssl.com/contact/">Contact</a> </div> <label class="md-header__button md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg> </label> <div class="md-search" data-md-component="search" role="dialog"> <label class="md-search__overlay" for="__search"></label> <div class="md-search__inner" role="search"> <form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required> <label class="md-search__icon md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg> </label> <nav class="md-search__options" aria-label="Search"> <button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg> </button> </nav> </form> <div class="md-search__output"> <div class="md-search__scrollwrap" data-md-scrollfix> <div class="md-search-result" data-md-component="search-result"> <div class="md-search-result__meta"> Initializing search </div> <ol class="md-search-result__list"></ol> </div> </div> </div> </div> </div> </nav> </header> <div class="md-container" data-md-component="container"> <main class="md-main" data-md-component="main"> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0"> <label class="md-nav__title" for="__drawer"> <a href="." title="wolfSSL Manual" class="md-nav__button md-logo" aria-label="wolfSSL Manual" data-md-component="logo"> <img src="logo.png" alt="logo"> </a> wolfSSL Manual </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="index.html" class="md-nav__link"> 1. Introduction </a> </li> <li class="md-nav__item"> <a href="chapter02.html" class="md-nav__link"> 2. Building wolfSSL </a> </li> <li class="md-nav__item"> <a href="chapter03.html" class="md-nav__link"> 3. Getting Started </a> </li> <li class="md-nav__item"> <a href="chapter04.html" class="md-nav__link"> 4. Features </a> </li> <li class="md-nav__item"> <a href="chapter05.html" class="md-nav__link"> 5. Portability </a> </li> <li class="md-nav__item"> <a href="chapter06.html" class="md-nav__link"> 6. Callbacks </a> </li> <li class="md-nav__item"> <a href="chapter07.html" class="md-nav__link"> 7. Keys and Certificates </a> </li> <li class="md-nav__item"> <a href="chapter08.html" class="md-nav__link"> 8. Debugging </a> </li> <li class="md-nav__item"> <a href="chapter09.html" class="md-nav__link"> 9. Library Design </a> </li> <li class="md-nav__item"> <a href="chapter10.html" class="md-nav__link"> 10. wolfCrypt Usage Reference </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> 11. SSL Tutorial <span class="md-nav__icon md-icon"></span> </label> <a href="chapter11.html" class="md-nav__link md-nav__link--active"> 11. SSL Tutorial </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#introduction" class="md-nav__link"> Introduction </a> <nav class="md-nav" aria-label="Introduction"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#examples-used-in-this-tutorial" class="md-nav__link"> Examples Used in this Tutorial </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#quick-summary-of-ssltls" class="md-nav__link"> Quick Summary of SSL/TLS </a> </li> <li class="md-nav__item"> <a href="#getting-the-source-code" class="md-nav__link"> Getting the Source Code </a> </li> <li class="md-nav__item"> <a href="#base-example-modifications" class="md-nav__link"> Base Example Modifications </a> <nav class="md-nav" aria-label="Base Example Modifications"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#modifications-to-the-echoserver-tcpserv04c" class="md-nav__link"> Modifications to the echoserver (tcpserv04.c) </a> </li> <li class="md-nav__item"> <a href="#modifications-to-the-echoclient-tcpcli01c" class="md-nav__link"> Modifications to the echoclient (tcpcli01.c) </a> </li> <li class="md-nav__item"> <a href="#modifications-to-unph-header" class="md-nav__link"> Modifications to unp.h header </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#building-and-installing-wolfssl" class="md-nav__link"> Building and Installing wolfSSL </a> </li> <li class="md-nav__item"> <a href="#initial-compilation" class="md-nav__link"> Initial Compilation </a> </li> <li class="md-nav__item"> <a href="#libraries" class="md-nav__link"> Libraries </a> </li> <li class="md-nav__item"> <a href="#headers" class="md-nav__link"> Headers </a> </li> <li class="md-nav__item"> <a href="#startupshutdown" class="md-nav__link"> Startup/Shutdown </a> </li> <li class="md-nav__item"> <a href="#wolfssl_ctx-factory" class="md-nav__link"> WOLFSSL_CTX Factory </a> </li> <li class="md-nav__item"> <a href="#wolfssl-object" class="md-nav__link"> WOLFSSL Object </a> <nav class="md-nav" aria-label="WOLFSSL Object"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#echoclient" class="md-nav__link"> EchoClient </a> </li> <li class="md-nav__item"> <a href="#echoserver" class="md-nav__link"> EchoServer </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#sendingreceiving-data" class="md-nav__link"> Sending/Receiving Data </a> <nav class="md-nav" aria-label="Sending/Receiving Data"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#sending-with-echoclient" class="md-nav__link"> Sending with EchoClient </a> </li> <li class="md-nav__item"> <a href="#receiving-with-echoserver" class="md-nav__link"> Receiving with EchoServer </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#signal-handling" class="md-nav__link"> Signal Handling </a> <nav class="md-nav" aria-label="Signal Handling"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#echoclient-echoserver" class="md-nav__link"> Echoclient / Echoserver </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#certificates" class="md-nav__link"> Certificates </a> </li> <li class="md-nav__item"> <a href="#conclusion" class="md-nav__link"> Conclusion </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="chapter12.html" class="md-nav__link"> 12. Best Practices for Embedded Devices </a> </li> <li class="md-nav__item"> <a href="chapter13.html" class="md-nav__link"> 13. OpenSSL Compatibility </a> </li> <li class="md-nav__item"> <a href="chapter14.html" class="md-nav__link"> 14. Licensing </a> </li> <li class="md-nav__item"> <a href="chapter15.html" class="md-nav__link"> 15. Support and Consulting </a> </li> <li class="md-nav__item"> <a href="chapter16.html" class="md-nav__link"> 16. wolfSSL Updates </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_17" type="checkbox" id="__nav_17" > <label class="md-nav__link" for="__nav_17"> A. wolfSSL API Reference <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="A. wolfSSL API Reference" data-md-level="1"> <label class="md-nav__title" for="__nav_17"> <span class="md-nav__icon md-icon"></span> A. wolfSSL API Reference </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="group__CertManager.html" class="md-nav__link"> CertManager API </a> </li> <li class="md-nav__item"> <a href="group__Memory.html" class="md-nav__link"> Memory Handling </a> </li> <li class="md-nav__item"> <a href="group__openSSL.html" class="md-nav__link"> OpenSSL API </a> </li> <li class="md-nav__item"> <a href="group__CertsKeys.html" class="md-nav__link"> wolfSSL Certificates and Keys </a> </li> <li class="md-nav__item"> <a href="group__IO.html" class="md-nav__link"> wolfSSL Connection, Session, and I/O </a> </li> <li class="md-nav__item"> <a href="group__Setup.html" class="md-nav__link"> wolfSSL Context and Session Set Up </a> </li> <li class="md-nav__item"> <a href="group__Debug.html" class="md-nav__link"> wolfSSL Error Handling and Reporting </a> </li> <li class="md-nav__item"> <a href="group__TLS.html" class="md-nav__link"> wolfSSL Initialization/Shutdown </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_18" type="checkbox" id="__nav_18" > <label class="md-nav__link" for="__nav_18"> B. wolfCrypt API Reference <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="B. wolfCrypt API Reference" data-md-level="1"> <label class="md-nav__title" for="__nav_18"> <span class="md-nav__icon md-icon"></span> B. wolfCrypt API Reference </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="group__ASN.html" class="md-nav__link"> ASN.1 </a> </li> <li class="md-nav__item"> <a href="group__Base__Encoding.html" class="md-nav__link"> Base Encoding </a> </li> <li class="md-nav__item"> <a href="group__Compression.html" class="md-nav__link"> Compression </a> </li> <li class="md-nav__item"> <a href="group__Error.html" class="md-nav__link"> Error Reporting </a> </li> <li class="md-nav__item"> <a href="group__IoTSafe.html" class="md-nav__link"> IoT-Safe Module </a> </li> <li class="md-nav__item"> <a href="group__Keys.html" class="md-nav__link"> Key and Cert Conversion </a> </li> <li class="md-nav__item"> <a href="group__Logging.html" class="md-nav__link"> Logging </a> </li> <li class="md-nav__item"> <a href="group__Math.html" class="md-nav__link"> Math API </a> </li> <li class="md-nav__item"> <a href="group__Random.html" class="md-nav__link"> Random Number Generation </a> </li> <li class="md-nav__item"> <a href="group__Signature.html" class="md-nav__link"> Signature API </a> </li> <li class="md-nav__item"> <a href="group__wolfCrypt.html" class="md-nav__link"> wolfCrypt Init and Cleanup </a> </li> <li class="md-nav__item"> <a href="group__DES.html" class="md-nav__link"> Algorithms - 3DES </a> </li> <li class="md-nav__item"> <a href="group__AES.html" class="md-nav__link"> Algorithms - AES </a> </li> <li class="md-nav__item"> <a href="group__ARC4.html" class="md-nav__link"> Algorithms - ARC4 </a> </li> <li class="md-nav__item"> <a href="group__BLAKE2.html" class="md-nav__link"> Algorithms - BLAKE2 </a> </li> <li class="md-nav__item"> <a href="group__Camellia.html" class="md-nav__link"> Algorithms - Camellia </a> </li> <li class="md-nav__item"> <a href="group__ChaCha.html" class="md-nav__link"> Algorithms - ChaCha </a> </li> <li class="md-nav__item"> <a href="group__ChaCha20Poly1305.html" class="md-nav__link"> Algorithms - ChaCha20_Poly1305 </a> </li> <li class="md-nav__item"> <a href="group__CMAC.html" class="md-nav__link"> Algorithms - CMAC </a> </li> <li class="md-nav__item"> <a href="group__Crypto.html" class="md-nav__link"> Callbacks - CryptoCb </a> </li> <li class="md-nav__item"> <a href="group__Curve25519.html" class="md-nav__link"> Algorithms - Curve25519 </a> </li> <li class="md-nav__item"> <a href="group__Curve448.html" class="md-nav__link"> Algorithms - Curve448 </a> </li> <li class="md-nav__item"> <a href="group__DSA.html" class="md-nav__link"> Algorithms - DSA </a> </li> <li class="md-nav__item"> <a href="group__Diffie-Hellman.html" class="md-nav__link"> Algorithms - Diffie-Hellman </a> </li> <li class="md-nav__item"> <a href="group__ECC.html" class="md-nav__link"> Algorithms - ECC </a> </li> <li class="md-nav__item"> <a href="group__ED25519.html" class="md-nav__link"> Algorithms - ED25519 </a> </li> <li class="md-nav__item"> <a href="group__ED448.html" class="md-nav__link"> Algorithms - ED448 </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_18_28" type="checkbox" id="__nav_18_28" > <label class="md-nav__link" for="__nav_18_28"> ECCSI API Reference <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="ECCSI API Reference" data-md-level="2"> <label class="md-nav__title" for="__nav_18_28"> <span class="md-nav__icon md-icon"></span> ECCSI API Reference </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="group__ECCSI__Overview.html" class="md-nav__link"> Overview of ECCSI </a> </li> <li class="md-nav__item"> <a href="group__ECCSI__Setup.html" class="md-nav__link"> Setup ECCSI Key </a> </li> <li class="md-nav__item"> <a href="group__ECCSI__Operations.html" class="md-nav__link"> Operations for Signing and Verifying with ECCSI Key </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_18_29" type="checkbox" id="__nav_18_29" > <label class="md-nav__link" for="__nav_18_29"> SAKKE API Reference <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="SAKKE API Reference" data-md-level="2"> <label class="md-nav__title" for="__nav_18_29"> <span class="md-nav__icon md-icon"></span> SAKKE API Reference </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="group__SAKKE__Overview.html" class="md-nav__link"> Overview of SAKKE Key </a> </li> <li class="md-nav__item"> <a href="group__SAKKE__Setup.html" class="md-nav__link"> Setup SAKKE Key </a> </li> <li class="md-nav__item"> <a href="group__SAKKE__RSK.html" class="md-nav__link"> Operations on/with SAKKE RSK </a> </li> <li class="md-nav__item"> <a href="group__SAKKE__Operations.html" class="md-nav__link"> Operations using SAKKE Key </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="group__HMAC.html" class="md-nav__link"> Algorithms - HMAC </a> </li> <li class="md-nav__item"> <a href="group__MD2.html" class="md-nav__link"> Algorithms - MD2 </a> </li> <li class="md-nav__item"> <a href="group__MD4.html" class="md-nav__link"> Algorithms - MD4 </a> </li> <li class="md-nav__item"> <a href="group__MD5.html" class="md-nav__link"> Algorithms - MD5 </a> </li> <li class="md-nav__item"> <a href="group__Password.html" class="md-nav__link"> Algorithms - Password Based </a> </li> <li class="md-nav__item"> <a href="group__PKCS7.html" class="md-nav__link"> Algorithms - PKCS7 </a> </li> <li class="md-nav__item"> <a href="group__PKCS11.html" class="md-nav__link"> Algorithms - PKCS11 </a> </li> <li class="md-nav__item"> <a href="group__Poly1305.html" class="md-nav__link"> Algorithms - Poly1305 </a> </li> <li class="md-nav__item"> <a href="group__PSA.html" class="md-nav__link"> Algorithms - PSA </a> </li> <li class="md-nav__item"> <a href="group__RIPEMD.html" class="md-nav__link"> Algorithms - RIPEMD </a> </li> <li class="md-nav__item"> <a href="group__RSA.html" class="md-nav__link"> Algorithms - RSA </a> </li> <li class="md-nav__item"> <a href="group__SHA.html" class="md-nav__link"> Algorithms - SHA 128/224/256/384/512 </a> </li> <li class="md-nav__item"> <a href="group__SipHash.html" class="md-nav__link"> Algorithms - SipHash </a> </li> <li class="md-nav__item"> <a href="group__SRP.html" class="md-nav__link"> Algorithms - SRP </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_19" type="checkbox" id="__nav_19" > <label class="md-nav__link" for="__nav_19"> C. API Header Files <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="C. API Header Files" data-md-level="1"> <label class="md-nav__title" for="__nav_19"> <span class="md-nav__icon md-icon"></span> C. API Header Files </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="aes_8h.html" class="md-nav__link"> aes.h </a> </li> <li class="md-nav__item"> <a href="arc4_8h.html" class="md-nav__link"> arc4.h </a> </li> <li class="md-nav__item"> <a href="asn_8h.html" class="md-nav__link"> asn.h </a> </li> <li class="md-nav__item"> <a href="asn__public_8h.html" class="md-nav__link"> asn_public.h </a> </li> <li class="md-nav__item"> <a href="blake2_8h.html" class="md-nav__link"> blake2.h </a> </li> <li class="md-nav__item"> <a href="bn_8h.html" class="md-nav__link"> bn.h </a> </li> <li class="md-nav__item"> <a href="camellia_8h.html" class="md-nav__link"> camellia.h </a> </li> <li class="md-nav__item"> <a href="chacha20__poly1305_8h.html" class="md-nav__link"> chacha20_poly1305.h </a> </li> <li class="md-nav__item"> <a href="chacha_8h.html" class="md-nav__link"> chacha.h </a> </li> <li class="md-nav__item"> <a href="cmac_8h.html" class="md-nav__link"> cmac.h </a> </li> <li class="md-nav__item"> <a href="coding_8h.html" class="md-nav__link"> coding.h </a> </li> <li class="md-nav__item"> <a href="compress_8h.html" class="md-nav__link"> compress.h </a> </li> <li class="md-nav__item"> <a href="cryptocb_8h.html" class="md-nav__link"> cryptocb.h </a> </li> <li class="md-nav__item"> <a href="curve25519_8h.html" class="md-nav__link"> curve25519.h </a> </li> <li class="md-nav__item"> <a href="curve448_8h.html" class="md-nav__link"> curve448.h </a> </li> <li class="md-nav__item"> <a href="des3_8h.html" class="md-nav__link"> des3.h </a> </li> <li class="md-nav__item"> <a href="dh_8h.html" class="md-nav__link"> dh.h </a> </li> <li class="md-nav__item"> <a href="doxygen__groups_8h.html" class="md-nav__link"> doxygen_groups.h </a> </li> <li class="md-nav__item"> <a href="doxygen__pages_8h.html" class="md-nav__link"> doxygen_pages.h </a> </li> <li class="md-nav__item"> <a href="dsa_8h.html" class="md-nav__link"> dsa.h </a> </li> <li class="md-nav__item"> <a href="ecc_8h.html" class="md-nav__link"> ecc.h </a> </li> <li class="md-nav__item"> <a href="eccsi_8h.html" class="md-nav__link"> eccsi.h </a> </li> <li class="md-nav__item"> <a href="ed25519_8h.html" class="md-nav__link"> ed25519.h </a> </li> <li class="md-nav__item"> <a href="ed448_8h.html" class="md-nav__link"> ed448.h </a> </li> <li class="md-nav__item"> <a href="error-crypt_8h.html" class="md-nav__link"> error-crypt.h </a> </li> <li class="md-nav__item"> <a href="evp_8h.html" class="md-nav__link"> evp.h </a> </li> <li class="md-nav__item"> <a href="hash_8h.html" class="md-nav__link"> hash.h </a> </li> <li class="md-nav__item"> <a href="hmac_8h.html" class="md-nav__link"> hmac.h </a> </li> <li class="md-nav__item"> <a href="iotsafe_8h.html" class="md-nav__link"> iotsafe.h </a> </li> <li class="md-nav__item"> <a href="logging_8h.html" class="md-nav__link"> logging.h </a> </li> <li class="md-nav__item"> <a href="md2_8h.html" class="md-nav__link"> md2.h </a> </li> <li class="md-nav__item"> <a href="md4_8h.html" class="md-nav__link"> md4.h </a> </li> <li class="md-nav__item"> <a href="md5_8h.html" class="md-nav__link"> md5.h </a> </li> <li class="md-nav__item"> <a href="memory_8h.html" class="md-nav__link"> memory.h </a> </li> <li class="md-nav__item"> <a href="pem_8h.html" class="md-nav__link"> pem.h </a> </li> <li class="md-nav__item"> <a href="pkcs11_8h.html" class="md-nav__link"> pkcs11.h </a> </li> <li class="md-nav__item"> <a href="pkcs7_8h.html" class="md-nav__link"> pkcs7.h </a> </li> <li class="md-nav__item"> <a href="poly1305_8h.html" class="md-nav__link"> poly1305.h </a> </li> <li class="md-nav__item"> <a href="psa_8h.html" class="md-nav__link"> psa.h </a> </li> <li class="md-nav__item"> <a href="pwdbased_8h.html" class="md-nav__link"> pwdbased.h </a> </li> <li class="md-nav__item"> <a href="quic_8h.html" class="md-nav__link"> quic.h </a> </li> <li class="md-nav__item"> <a href="random_8h.html" class="md-nav__link"> random.h </a> </li> <li class="md-nav__item"> <a href="ripemd_8h.html" class="md-nav__link"> ripemd.h </a> </li> <li class="md-nav__item"> <a href="rsa_8h.html" class="md-nav__link"> rsa.h </a> </li> <li class="md-nav__item"> <a href="sakke_8h.html" class="md-nav__link"> sakke.h </a> </li> <li class="md-nav__item"> <a href="sha256_8h.html" class="md-nav__link"> sha256.h </a> </li> <li class="md-nav__item"> <a href="sha512_8h.html" class="md-nav__link"> sha512.h </a> </li> <li class="md-nav__item"> <a href="sha_8h.html" class="md-nav__link"> sha.h </a> </li> <li class="md-nav__item"> <a href="signature_8h.html" class="md-nav__link"> signature.h </a> </li> <li class="md-nav__item"> <a href="siphash_8h.html" class="md-nav__link"> siphash.h </a> </li> <li class="md-nav__item"> <a href="srp_8h.html" class="md-nav__link"> srp.h </a> </li> <li class="md-nav__item"> <a href="ssl_8h.html" class="md-nav__link"> ssl.h </a> </li> <li class="md-nav__item"> <a href="tfm_8h.html" class="md-nav__link"> tfm.h </a> </li> <li class="md-nav__item"> <a href="types_8h.html" class="md-nav__link"> types.h </a> </li> <li class="md-nav__item"> <a href="wc__encrypt_8h.html" class="md-nav__link"> wc_encrypt.h </a> </li> <li class="md-nav__item"> <a href="wc__port_8h.html" class="md-nav__link"> wc_port.h </a> </li> <li class="md-nav__item"> <a href="wolfio_8h.html" class="md-nav__link"> wolfio.h </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="appendix04.html" class="md-nav__link"> D. SSL/TLS Overview </a> </li> <li class="md-nav__item"> <a href="appendix05.html" class="md-nav__link"> E. RFCs, Specifications, and Reference </a> </li> <li class="md-nav__item"> <a href="appendix06.html" class="md-nav__link"> F. Error Codes </a> </li> <li class="md-nav__item"> <a href="appendix07.html" class="md-nav__link"> G. Experimenting with Post-Quantum Cryptography </a> </li> <li class="md-nav__item"> <a href="appendix08.html" class="md-nav__link"> H. wolfSSL Porting Guide </a> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#introduction" class="md-nav__link"> Introduction </a> <nav class="md-nav" aria-label="Introduction"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#examples-used-in-this-tutorial" class="md-nav__link"> Examples Used in this Tutorial </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#quick-summary-of-ssltls" class="md-nav__link"> Quick Summary of SSL/TLS </a> </li> <li class="md-nav__item"> <a href="#getting-the-source-code" class="md-nav__link"> Getting the Source Code </a> </li> <li class="md-nav__item"> <a href="#base-example-modifications" class="md-nav__link"> Base Example Modifications </a> <nav class="md-nav" aria-label="Base Example Modifications"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#modifications-to-the-echoserver-tcpserv04c" class="md-nav__link"> Modifications to the echoserver (tcpserv04.c) </a> </li> <li class="md-nav__item"> <a href="#modifications-to-the-echoclient-tcpcli01c" class="md-nav__link"> Modifications to the echoclient (tcpcli01.c) </a> </li> <li class="md-nav__item"> <a href="#modifications-to-unph-header" class="md-nav__link"> Modifications to unp.h header </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#building-and-installing-wolfssl" class="md-nav__link"> Building and Installing wolfSSL </a> </li> <li class="md-nav__item"> <a href="#initial-compilation" class="md-nav__link"> Initial Compilation </a> </li> <li class="md-nav__item"> <a href="#libraries" class="md-nav__link"> Libraries </a> </li> <li class="md-nav__item"> <a href="#headers" class="md-nav__link"> Headers </a> </li> <li class="md-nav__item"> <a href="#startupshutdown" class="md-nav__link"> Startup/Shutdown </a> </li> <li class="md-nav__item"> <a href="#wolfssl_ctx-factory" class="md-nav__link"> WOLFSSL_CTX Factory </a> </li> <li class="md-nav__item"> <a href="#wolfssl-object" class="md-nav__link"> WOLFSSL Object </a> <nav class="md-nav" aria-label="WOLFSSL Object"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#echoclient" class="md-nav__link"> EchoClient </a> </li> <li class="md-nav__item"> <a href="#echoserver" class="md-nav__link"> EchoServer </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#sendingreceiving-data" class="md-nav__link"> Sending/Receiving Data </a> <nav class="md-nav" aria-label="Sending/Receiving Data"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#sending-with-echoclient" class="md-nav__link"> Sending with EchoClient </a> </li> <li class="md-nav__item"> <a href="#receiving-with-echoserver" class="md-nav__link"> Receiving with EchoServer </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#signal-handling" class="md-nav__link"> Signal Handling </a> <nav class="md-nav" aria-label="Signal Handling"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#echoclient-echoserver" class="md-nav__link"> Echoclient / Echoserver </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#certificates" class="md-nav__link"> Certificates </a> </li> <li class="md-nav__item"> <a href="#conclusion" class="md-nav__link"> Conclusion </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <h1 id="ssl-tutorial">SSL Tutorial</h1> <h2 id="introduction">Introduction</h2> <p>The wolfSSL embedded SSL/TLS library can easily be integrated into your existing application or device to provide enhanced communication security through the addition of SSL and TLS. wolfSSL has been targeted at embedded and RTOS environments, and as such, offers a minimal footprint while maintaining excellent performance. Minimum build sizes for wolfSSL range between 20-100kB depending on the selected build options and platform being used.</p> <p>The goal of this tutorial is to walk through the integration of SSL and TLS into a simple application. Hopefully the process of going through this tutorial will also lead to a better understanding of SSL in general. This tutorial uses wolfSSL in conjunction with simple echoserver and echoclient examples to keep things as simple as possible while still demonstrating the general procedure of adding SSL support to an application. The echoserver and echoclient examples have been taken from the popular book titled <a href="http://www.unpbook.com/">Unix Network Programming, Volume 1, 3rd Edition</a> by Richard Stevens, Bill Fenner, and Andrew Rudoff.</p> <p>This tutorial assumes that the reader is comfortable with editing and compiling C code using the GNU GCC compiler as well as familiar with the concepts of public key encryption. Please note that access to the Unix Network Programming book is not required for this tutorial.</p> <h3 id="examples-used-in-this-tutorial">Examples Used in this Tutorial</h3> <ul> <li>echoclient - Figure 5.4, Page 124</li> <li>echoserver - Figure 5.12, Page 139</li> </ul> <h2 id="quick-summary-of-ssltls">Quick Summary of SSL/TLS</h2> <p><strong>TLS</strong> (Transport Layer Security) and <strong>SSL</strong> (Secure Sockets Layer) are cryptographic protocols that allow for secure communication across a number of different transport protocols. The primary transport protocol used is TCP/IP. The most recent version of SSL/TLS is TLS 1.3. wolfSSL supports SSL 3.0, TLS 1.0, 1.1, 1.2, 1.3 in addition to DTLS 1.0 and 1.2.</p> <p>SSL and TLS sit between the Transport and Application layers of the OSI model, where any number of protocols (including TCP/IP, Bluetooth, etc.) may act as the underlying transport medium. Application protocols are layered on top of SSL and can include protocols such as HTTP, FTP, and SMTP. A diagram of how SSL fits into the OSI model, as well as a simple diagram of the SSL handshake process can be found in Appendix A.</p> <h2 id="getting-the-source-code">Getting the Source Code</h2> <p>All of the source code used in this tutorial can be downloaded from the wolfSSL website, specifically from the following location. The download contains both the original and completed source code for both the echoserver and echoclient used in this tutorial. Specific contents are listed below the link.</p> <p><a href="https://www.wolfssl.com/documentation/ssl-tutorial-2.5.zip">https://www.wolfssl.com/documentation/ssl-tutorial-2.5.zip</a></p> <p>The downloaded ZIP file has the following structure:</p> <pre><code class="language-text">/finished_src /certs (Certificate files) /echoclient (Completed echoclient code) /echoserver (Completed echoserver code) /include (Modified unp.h) /lib (Library functions) /original_src /echoclient (Starting echoclient code) /echoserver (Starting echoserver code) /include (Modified unp.h) /lib (Library functions) README </code></pre> <h2 id="base-example-modifications">Base Example Modifications</h2> <p>This tutorial, and the source code that accompanies it, have been designed to be as portable as possible across platforms. Because of this, and because we want to focus on how to add SSL and TLS into an application, the base examples have been kept as simple as possible. Several modifications have been made to the examples taken from Unix Network Programming in order to either remove unnecessary complexity or increase the range of platforms supported. If you believe there is something we could do to increase the portability of this tutorial, please let us know at <a href="mailto:support@wolfssl.com">support@wolfssl.com</a>.</p> <p>The following is a list of modifications that were made to the original echoserver and echoclient examples found in the above listed book.</p> <h3 id="modifications-to-the-echoserver-tcpserv04c">Modifications to the echoserver (tcpserv04.c)</h3> <ul> <li>Removed call to the <code>fork()</code> function because <code>fork()</code> is not supported by Windows. The result of this is an echoserver which only accepts one client simultaneously. Along with this removal, Signal handling was removed.</li> <li>Moved <code>str_echo()</code> function from <code>str_echo.c</code> file into <code>tcpserv04.c</code> file</li> <li>Added a printf statement to view the client address and the port we have connected through:</li> </ul> <pre><code class="language-text"> printf("Connection from %s, port %d\n", inet_ntop(AF_INET, &cliaddr.sin_addr, buff, sizeof(buff)), ntohs(cliaddr.sin_port)); </code></pre> <ul> <li>Added a call to <code>setsockopt()</code> after creating the listening socket to eliminate the “Address already in use” bind error.</li> <li>Minor adjustments to clean up newer compiler warnings</li> </ul> <h3 id="modifications-to-the-echoclient-tcpcli01c">Modifications to the echoclient (tcpcli01.c)</h3> <ul> <li>Moved <code>str_cli()</code> function from <code>str_cli.c</code> file into <code>tcpcli01.c</code> file</li> <li>Minor adjustments to clean up newer compiler warnings</li> </ul> <h3 id="modifications-to-unph-header">Modifications to unp.h header</h3> <ul> <li>This header was simplified to contain only what is needed for this example.</li> </ul> <p>Please note that in these source code examples, certain functions will be capitalized. For example, <code>Fputs()</code> and <code>Writen()</code>. The authors of Unix Network Programming have written custom wrapper functions for normal functions in order to cleanly handle error checking. For a more thorough explanation of this, please see <strong>Section 1.4</strong> (page 11) in the <em>Unix Network Programming</em> book.</p> <h2 id="building-and-installing-wolfssl">Building and Installing wolfSSL</h2> <p>Before we begin, download the example code (<code>echoserver</code> and <code>echoclient</code>) from the <a href="chapter03.html#getting-the-source-code">Getting the Source Code</a> section, above. This section will explain how to download, configure, and install the wolfSSL embedded SSL/TLS library on your system.</p> <p>You will need to download and install the most recent version of wolfSSL from the wolfSSL <a href="https://www.wolfssl.com/download/">download page</a>.</p> <p>For a full list of available build options, see the <a href="https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html">Building wolfSSL</a> guide. wolfSSL was written with portability in mind, and should generally be easy to build on most systems. If you have difficulty building wolfSSL, please feel free to ask for support on the wolfSSL <a href="https://www.wolfssl.com/forums">product support forums</a>.</p> <p>When building wolfSSL on Linux, <em>BSD, OS X, Solaris, or other </em>nix like systems, you can use the autoconf system. For Windows-specific instructions, please refer to the <a href="chapter02.html#building-wolfssl">Building wolfSSL</a> section of the wolfSSL Manual. To configure and build wolfSSL, run the following two commands from the terminal. Any desired build options may be appended to <code>./configure</code> (ex: <code>./configure -–enable-opensslextra</code>):</p> <pre><code class="language-sh">./configure make </code></pre> <p>To install wolfSSL, run:</p> <pre><code class="language-sh">sudo make install </code></pre> <p>This will install wolfSSL headers into <code>/usr/local/include/wolfssl</code> and the wolfSSL libraries into <code>/usr/local/lib</code> on your system. To test the build, run the testsuite application from the wolfSSL root directory:</p> <pre><code class="language-sh">./testsuite/testsuite.test </code></pre> <p>A set of tests will be run on wolfCrypt and wolfSSL to verify it has been installed correctly. After a successful run of the testsuite application, you should see output similar to the following:</p> <pre><code class="language-text">------------------------------------------------------------------------------ wolfSSL version 5.7.0 ------------------------------------------------------------------------------ error test passed! MEMORY test passed! base64 test passed! asn test passed! RANDOM test passed! MD5 test passed! SHA test passed! SHA-224 test passed! SHA-256 test passed! SHA-384 test passed! SHA-512 test passed! SHA-512/224 test passed! SHA-512/256 test passed! SHA-3 test passed! Hash test passed! HMAC-MD5 test passed! HMAC-SHA test passed! HMAC-SHA224 test passed! HMAC-SHA256 test passed! HMAC-SHA384 test passed! HMAC-SHA512 test passed! HMAC-SHA3 test passed! HMAC-KDF test passed! PRF test passed! TLSv1.3 KDF test passed! GMAC test passed! Chacha test passed! POLY1305 test passed! ChaCha20-Poly1305 AEAD test passed! AES test passed! AES192 test passed! AES256 test passed! AES-GCM test passed! RSA test passed! DH test passed! PWDBASED test passed! ECC test passed! logging test passed! time test passed! mutex test passed! memcb test passed! Test complete Running simple test SSL version is TLSv1.2 SSL version is TLSv1.2 SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 SSL curve name is SECP256R1 SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 SSL curve name is SECP256R1 Client message: hello wolfssl! I hear you fa shizzle! Running TLS test sending server shutdown command: quit! client sent quit command: shutting down! ciphers = TLS13-AES128-GCM-SHA256:TLS13-AES256-GCM-SHA384:TLS13-CHACHA20-POLY1305-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305-OLD:ECDHE-ECDSA-CHACHA20-POLY1305-OLD:DHE-RSA-CHACHA20-POLY1305-OLD 33bc1a4570f4f1abccd5c48aace529b01a42ab51293954a297796e90d20970f0 input 33bc1a4570f4f1abccd5c48aace529b01a42ab51293954a297796e90d20970f0 /var/folders/dy/888x7r7d6dgcqw4840l32tpw0000gp/T//testsuite-output-9Ymbuv All tests passed! </code></pre> <p>Now that wolfSSL has been installed, we can begin modifying the example code to add SSL functionality. We will first begin by adding SSL to the echoclient and subsequently move on to the echoserver.</p> <h2 id="initial-compilation">Initial Compilation</h2> <p>To compile and run the example echoclient and echoserver code from the SSL Tutorial source bundle, you can use the included Makefiles. Change directory (cd) to either the echoclient or echoserver directory and run:</p> <pre><code class="language-sh">make </code></pre> <p>This will compile the example code and produce an executable named either echoserver or echoclient depending on which one is being built. The GCC command which is used in the Makefile can be seen below. If you want to build one of the examples without using the supplied Makefile, change directory to the example directory and replace <code>tcpcli01.c</code> (echoclient) or <code>tcpserv04.c</code> (echoserver) in the following command with correct source file for the example:</p> <pre><code class="language-sh">gcc -o echoserver ../lib/*.c tcpserv04.c -I ../include </code></pre> <p>This will compile the current example into an executable, creating either an “echoserver” or “echoclient” application. To run one of the examples after it has been compiled, change your current directory to the desired example directory and start the application. For example, to start the echoserver use:</p> <pre><code class="language-sh">./echoserver </code></pre> <p>You may open a second terminal window to test the echoclient on your local host and you will need to supply the IP address of the server when starting the application, which in our case will be 127.0.0.1. Change your current directory to the “echoclient” directory and run the following command. Note that the echoserver must already be running:</p> <pre><code class="language-sh">./echoclient 127.0.0.1 </code></pre> <p>Once you have both the echoserver and echoclient running, the echoserver should echo back any input that it receives from the echoclient. To exit either the echoserver or echoclient, use <em>Ctrl + C</em> to quit the application. Currently, the data being echoed back and forth between these two examples is being sent in the clear - easily allowing anyone with a little bit of skill to inject themselves in between the client and server and listen to your communication.</p> <h2 id="libraries">Libraries</h2> <p>The wolfSSL library, once compiled, is named <code>libwolfssl</code>, and unless otherwise configured the wolfSSL build and install process creates only a shared library under the following directory. Both shared and static libraries may be enabled or disabled by using the appropriate build options:</p> <pre><code class="language-sh">/usr/local/lib </code></pre> <p>The first step we need to do is link the wolfSSL library to our example applications. Modifying the GCC command (using the echoserver as an example), gives us the following new command. Since wolfSSL installs header files and libraries in standard locations, the compiler should be able to find them without explicit instructions (using <code>-l</code> or <code>-L</code>). Note that by using <code>-lwolfssl</code> the compiler will automatically choose the correct type of library (static or shared):</p> <pre><code class="language-sh">gcc -o echoserver ../lib/*.c tcpserv04.c -I ../include -lm -lwolfssl </code></pre> <h2 id="headers">Headers</h2> <p>The first thing we will need to do is include the wolfSSL native API header in both the client and the server. In the <code>tcpcli01.c</code> file for the client and the <code>tcpserv04.c</code> file for the server add the following line near the top:</p> <pre><code class="language-c">#include <wolfssl/ssl.h> </code></pre> <h2 id="startupshutdown">Startup/Shutdown</h2> <p>Before we can use wolfSSL in our code, we need to initialize the library and the <code>WOLFSSL_CTX</code>. wolfSSL is initialized by calling <a href="group__TLS.html#function-wolfssl_init"><code>wolfSSL_Init()</code></a>. This must be done first before anything else can be done with the library.</p> <h2 id="wolfssl_ctx-factory">WOLFSSL_CTX Factory</h2> <p>The <code>WOLFSSL_CTX</code> structure (wolfSSL Context) contains global values for each SSL connection, including certificate information. A single <code>WOLFSSL_CTX</code> can be used with any number of <code>WOLFSSL</code> objects created. This allows us to load certain information, such as a list of trusted CA certificates only once.</p> <p>To create a new <code>WOLFSSL_CTX</code>, use <a href="group__Setup.html#function-wolfssl_ctx_new"><code>wolfSSL_CTX_new()</code></a>. This function requires an argument which defines the SSL or TLS protocol for the client or server to use. There are several options for selecting the desired protocol. wolfSSL currently supports SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3, DTLS 1.0, DTLS 1.2, and DTLS 1.3. Each of these protocols have a corresponding function that can be used as an argument to <a href="group__Setup.html#function-wolfssl_ctx_new"><code>wolfSSL_CTX_new()</code></a>. The possible client and server protocol options are shown below. SSL 2.0 is not supported by wolfSSL because it has been insecure for several years.</p> <p>EchoClient:</p> <ul> <li><a href="group__Setup.html#function-wolfsslv3_client_method"><code>wolfSSLv3_client_method();</code></a> - SSL 3.0</li> <li><a href="group__Setup.html#function-wolftlsv1_client_method"><code>wolfTLSv1_client_method();</code></a> - TLS 1.0</li> <li><a href="group__Setup.html#function-wolftlsv1_1_client_method"><code>wolfTLSv1_1_client_method();</code></a> - TLS 1.1</li> <li><a href="group__Setup.html#function-wolftlsv1_2_client_method"><code>wolfTLSv1_2_client_method();</code></a> - TLS 1.2</li> <li><a href="group__Setup.html#function-wolftlsv1_3_client_method"><code>wolfTLSv1_3_client_method();</code></a> - TLS 1.3</li> <li><a href="group__Setup.html#function-wolfsslv23_client_method"><code>wolfSSLv23_client_method();</code></a> - Use highest version possible from SSL 3.0 - TLS 1.3</li> <li><a href="group__Setup.html#function-wolfdtlsv1_client_method"><code>wolfDTLSv1_client_method();</code></a> - DTLS 1.0</li> <li><a href="ssl_8h.html#function-wolfdtlsv1_2_client_method_ex"><code>wolfDTLSv1_2_client_method_ex();</code></a> - DTLS 1.2</li> <li><a href="ssl_8h.html#function-wolfdtlsv1_3_client_method_ex"><code>wolfDTLSv1_3_client_method_ex();</code></a> - DTLS 1.3</li> </ul> <p>EchoServer:</p> <ul> <li><a href="group__Setup.html#function-wolfsslv3_server_method"><code>wolfSSLv3_server_method();</code></a> - SSL 3.0</li> <li><a href="group__Setup.html#function-wolftlsv1_server_method"><code>wolfTLSv1_server_method();</code></a> - TLS 1.0</li> <li><a href="group__Setup.html#function-wolftlsv1_1_server_method"><code>wolfTLSv1_1_server_method();</code></a> - TLS 1.1</li> <li><a href="group__Setup.html#function-wolftlsv1_2_server_method"><code>wolfTLSv1_2_server_method();</code></a> - TLS 1.2</li> <li><a href="group__Setup.html#function-wolftlsv1_3_server_method"><code>wolfTLSv1_3_server_method();</code></a> - TLS 1.3</li> <li><a href="group__Setup.html#function-wolfsslv23_server_method"><code>wolfSSLv23_server_method();</code></a> - Allow clients to connect with TLS 1.0+</li> <li><a href="group__Setup.html#function-wolfdtlsv1_server_method"><code>wolfDTLSv1_server_method();</code></a> - DTLS 1.0</li> <li><a href="ssl_8h.html#function-wolfdtlsv1_2_server_method"><code>wolfDTLSv1_2_server_method();</code></a> - DTLS 1.2</li> <li><a href="ssl_8h.html#function-wolfdtlsv1_3_server_method"><code>wolfDTLSv1_3_server_method();</code></a> - DTLS 1.3</li> </ul> <p>We need to load our CA (Certificate Authority) certificate into the <code>WOLFSSL_CTX</code> so that the when the echoclient connects to the echoserver, it is able to verify the server’s identity. To load the CA certificates into the <code>WOLFSSL_CTX</code>, use <a href="group__CertsKeys.html#function-wolfssl_ctx_load_verify_locations"><code>wolfSSL_CTX_load_verify_locations()</code></a>. This function requires three arguments: a <code>WOLFSSL_CTX</code> pointer, a certificate file, and a path value. The path value points to a directory which should contain CA certificates in PEM format. When looking up certificates, wolfSSL will look at the certificate file value before looking in the path location. In this case, we don’t need to specify a certificate path because we will specify one CA file - as such we use the value 0 for the path argument. The <a href="group__CertsKeys.html#function-wolfssl_ctx_load_verify_locations"><code>wolfSSL_CTX_load_verify_locations</code></a> function returns either <code>SSL_SUCCESS</code> or <code>SSL_FAILURE</code>:</p> <pre><code class="language-c">wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX* ctx, const char* file, const char* path) </code></pre> <p>Putting these things together (library initialization, protocol selection, and CA certificate), we have the following. Here, we choose to use TLS 1.2:</p> <p>EchoClient:</p> <pre><code class="language-c"> WOLFSSL_CTX* ctx; wolfSSL_Init();/* Initialize wolfSSL */ /* Create the WOLFSSL_CTX */ if ( (ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method())) == NULL) { fprintf(stderr, "wolfSSL_CTX_new error.\n"); exit(EXIT_FAILURE); } /* Load CA certificates into WOLFSSL_CTX */ if (wolfSSL_CTX_load_verify_locations(ctx,"../certs/ca-cert.pem",0) != SSL_SUCCESS) { fprintf(stderr, "Error loading ../certs/ca-cert.pem, please check" "the file.\n"); exit(EXIT_FAILURE); } </code></pre> <p>Add the above code to <code>tcpcli01.c</code> in <code>main()</code> after the variable definitions and the check that the user has started the client with an IP address.</p> <p>EchoServer:</p> <p>When loading certificates into the <code>WOLFSSL_CTX</code>, the server certificate and key file should be loaded in addition to the CA certificate. This will allow the server to send the client its certificate for identification verification:</p> <pre><code class="language-c">WOLFSSL_CTX* ctx; wolfSSL_Init(); /* Initialize wolfSSL */ /* Create the WOLFSSL_CTX */ if ( (ctx = wolfSSL_CTX_new(wolfTLSv1_2_server_method())) == NULL) { fprintf(stderr, "wolfSSL_CTX_new error.\n"); exit(EXIT_FAILURE); } /* Load CA certificates into WOLFSSL_CTX */ if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", 0) != SSL_SUCCESS) { fprintf(stderr, "Error loading ../certs/ca-cert.pem, " "please check the file.\n"); exit(EXIT_FAILURE); } /* Load server certificates into WOLFSSL_CTX */ if (wolfSSL_CTX_use_certificate_file(ctx,"../certs/server-cert.pem", SSL_FILETYPE_PEM) != SSL_SUCCESS) { fprintf(stderr, "Error loading ../certs/server-cert.pem, please" "check the file.\n"); exit(EXIT_FAILURE); } /* Load keys */ if (wolfSSL_CTX_use_PrivateKey_file(ctx,"../certs/server-key.pem", SSL_FILETYPE_PEM) != SSL_SUCCESS) { fprintf(stderr, "Error loading ../certs/server-key.pem, please check" "the file.\n"); exit(EXIT_FAILURE); } </code></pre> <p>The code shown above should be added to the beginning of <code>tcpserv04.c</code> after the variable definitions in <code>main()</code>. A version of the finished code is included in the SSL tutorial ZIP file for reference.</p> <p>Now that wolfSSL and the <code>WOLFSSL_CTX</code> have been initialized, make sure that the <code>WOLFSSL_CTX</code> object and the wolfSSL library are freed when the application is completely done using SSL/TLS. In both the client and the server, the following two lines should be placed at the end of the <code>main()</code> function (in the client right before the call to <code>exit()</code>):</p> <pre><code class="language-c">wolfSSL_CTX_free(ctx); wolfSSL_Cleanup(); </code></pre> <h2 id="wolfssl-object">WOLFSSL Object</h2> <h3 id="echoclient">EchoClient</h3> <p>A WOLFSSL object needs to be created after each TCP Connect and the socket file descriptor needs to be associated with the session. In the echoclient example, we will do this after the call to <code>Connect()</code>, shown below:</p> <pre><code class="language-c">/* Connect to socket file descriptor */ Connect(sockfd, (SA *) &servaddr, sizeof(servaddr)); </code></pre> <p>Directly after connecting, create a new <code>WOLFSSL</code> object using the <a href="group__Setup.html#function-wolfssl_new"><code>wolfSSL_new()</code></a> function. This function returns a pointer to the <code>WOLFSSL</code> object if successful or <code>NULL</code> in the case of failure. We can then associate the socket file descriptor (<code>sockfd</code>) with the new <code>WOLFSSL</code> object (<code>ssl</code>):</p> <pre><code class="language-c">/* Create WOLFSSL object */ WOLFSSL* ssl; if( (ssl = wolfSSL_new(ctx)) == NULL) { fprintf(stderr, "wolfSSL_new error.\n"); exit(EXIT_FAILURE); } wolfSSL_set_fd(ssl, sockfd); </code></pre> <p>One thing to notice here is that we haven’t made a call to the <a href="group__IO.html#function-wolfssl_connect"><code>wolfSSL_connect()</code></a> function. <a href="group__IO.html#function-wolfssl_connect"><code>wolfSSL_connect()</code></a> initiates the SSL/TLS handshake with the server, and is called during <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read()</code></a> if it hadn't been called previously. In our case, we don’t explicitly call <a href="group__IO.html#function-wolfssl_connect"><code>wolfSSL_connect()</code></a>, as we let our first <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read()</code></a> do it for us.</p> <h3 id="echoserver">EchoServer</h3> <p>At the end of the for loop in the main method, insert the WOLFSSL object and associate the socket file descriptor (<code>connfd</code>) with the <code>WOLFSSL</code> object (<code>ssl</code>), just as with the client:</p> <pre><code class="language-c">/* Create WOLFSSL object */ WOLFSSL* ssl; if ( (ssl = wolfSSL_new(ctx)) == NULL) { fprintf(stderr, "wolfSSL_new error.\n"); exit(EXIT_FAILURE); } wolfSSL_set_fd(ssl, connfd); </code></pre> <p>Again, a WOLFSSL object needs to be created after each TCP Connect and the socket file descriptor needs to be associated with the session.</p> <h2 id="sendingreceiving-data">Sending/Receiving Data</h2> <h3 id="sending-with-echoclient">Sending with EchoClient</h3> <p>The next step is to begin sending data securely. Take note that in the echoclient example, the <code>main()</code> function hands off the sending and receiving work to <code>str_cli()</code>. The <code>str_cli()</code> function is where our function replacements will be made. First we need access to our <code>WOLFSSL</code> object in the <code>str_cli()</code> function, so we add another argument and pass the ssl variable to <code>str_cli()</code>. Because the <code>WOLFSSL</code> object is now going to be used inside of the <code>str_cli()</code> function, we remove the <code>sockfd</code> parameter. The new <code>str_cli()</code> function signature after this modification is shown below:</p> <pre><code class="language-c">void str_cli(FILE *fp, WOLFSSL* ssl) </code></pre> <p>In the <code>main()</code> function, the new argument (<code>ssl</code>) is passed to <code>str_cli()</code>:</p> <pre><code class="language-c">str_cli(stdin, ssl); </code></pre> <p>Inside the <code>str_cli()</code> function, <code>Writen()</code> and <code>Readline()</code> are replaced with calls to <a href="group__IO.html#function-wolfssl_write"><code>wolfSSL_write()</code></a> and <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read()</code></a> functions, and the <code>WOLFSSL</code> object (<code>ssl</code>) is used instead of the original file descriptor(<code>sockfd</code>). The new <code>str_cli()</code> function is shown below. Notice that we now need to check if our calls to <a href="group__IO.html#function-wolfssl_write"><code>wolfSSL_write</code></a> and <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read</code></a> were successful.</p> <p>The authors of the Unix Programming book wrote error checking into their <code>Writen()</code> function which we must make up for after it has been replaced. We add a new int variable, <code>n</code>, to monitor the return value of <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read</code></a> and before printing out the contents of the buffer, <code>recvline</code>, the end of our read data is marked with a <code>\0</code>:</p> <pre><code class="language-c">void str_cli(FILE *fp, WOLFSSL* ssl) { char sendline[MAXLINE], recvline[MAXLINE]; int n = 0; while (Fgets(sendline, MAXLINE, fp) != NULL) { if(wolfSSL_write(ssl, sendline, strlen(sendline)) != strlen(sendline)){ err_sys("wolfSSL_write failed"); } if ((n = wolfSSL_read(ssl, recvline, MAXLINE)) <= 0) err_quit("wolfSSL_read error"); recvline[n] = '\0'; Fputs(recvline, stdout); } } </code></pre> <p>The last thing to do is free the <code>WOLFSSL</code> object when we are completely done with it. In the <code>main()</code> function, right before the line to free the <code>WOLFSSL_CTX</code>, call to <a href="group__Setup.html#function-wolfssl_free"><code>wolfSSL_free()</code></a>:</p> <pre><code class="language-c">str_cli(stdin, ssl); wolfSSL_free(ssl); /* Free WOLFSSL object */ wolfSSL_CTX_free(ctx); /* Free WOLFSSL_CTX object */ wolfSSL_Cleanup(); /* Free wolfSSL */ </code></pre> <h3 id="receiving-with-echoserver">Receiving with EchoServer</h3> <p>The echo server makes a call to <code>str_echo()</code> to handle reading and writing (whereas the client made a call to <code>str_cli()</code>). As with the client, modify <code>str_echo()</code> by replacing the sockfd parameter with a <code>WOLFSSL</code> object (<code>ssl</code>) parameter in the function signature:</p> <pre><code class="language-c">void str_echo(WOLFSSL* ssl) </code></pre> <p>Replace the calls to <code>Read()</code> and <code>Writen()</code> with calls to the <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read()</code></a> and <a href="group__IO.html#function-wolfssl_write"><code>wolfSSL_write()</code></a> functions. The modified <code>str_echo()</code> function, including error checking of return values, is shown below. Note that the type of the variable <code>n</code> has been changed from <code>ssize_t</code> to <code>int</code> in order to accommodate for the change from <code>read()</code> to <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read()</code></a>:</p> <pre><code class="language-c">void str_echo(WOLFSSL* ssl) { int n; char buf[MAXLINE]; while ( (n = wolfSSL_read(ssl, buf, MAXLINE)) > 0) { if(wolfSSL_write(ssl, buf, n) != n) { err_sys("wolfSSL_write failed"); } } if( n < 0 ) printf("wolfSSL_read error = %d\n", wolfSSL_get_error(ssl,n)); else if( n == 0 ) printf("The peer has closed the connection.\n"); } </code></pre> <p>In <code>main()</code> call the <code>str_echo()</code> function at the end of the for loop (soon to be changed to a while loop). After this function, inside the loop, make calls to free the <code>WOLFSSL</code> object and close the connfd socket:</p> <pre><code class="language-c">str_echo(ssl); /* process the request */ wolfSSL_free(ssl); /* Free WOLFSSL object */ Close(connfd); </code></pre> <p>We will free the <code>ctx</code> and cleanup before the call to exit.</p> <h2 id="signal-handling">Signal Handling</h2> <h3 id="echoclient-echoserver">Echoclient / Echoserver</h3> <p>In the echoclient and echoserver, we will need to add a signal handler for when the user closes the app by using “Ctrl+C”. The echo server is continually running in a loop. Because of this, we need to provide a way to break that loop when the user presses “Ctrl+C”. To do this, the first thing we need to do is change our loop to a while loop which terminates when an exit variable (cleanup) is set to true.</p> <p>First, define a new static int variable called <code>cleanup</code> at the top of <code>tcpserv04.c</code> right after the <code>#include</code> statements:</p> <pre><code class="language-c">static int cleanup; /* To handle shutdown */ </code></pre> <p>Modify the echoserver loop by changing it from a for loop to a while loop:</p> <pre><code class="language-c">while(cleanup != 1) { /* echo server code here */ } </code></pre> <p>For the echoserver we need to disable the operating system from restarting calls which were being executed before the signal was handled after our handler has finished. By disabling these, the operating system will not restart calls to <code>accept()</code> after the signal has been handled. If we didn’t do this, we would have to wait for another client to connect and disconnect before the echoserver would clean up resources and exit. To define the signal handler and turn off <code>SA_RESTART</code>, first define act and oact structures in the echoserver’s <code>main()</code> function:</p> <pre><code class="language-c">struct sigaction act, oact; </code></pre> <p>Insert the following code after variable declarations, before the call to <a href="group__TLS.html#function-wolfssl_init"><code>wolfSSL_Init()</code></a> in the main function:</p> <pre><code class="language-c">/* Signal handling code */ struct sigaction act, oact; /* Declare the sigaction structs */ act.sa_handler = sig_handler; /* Tell act to use sig_handler */ sigemptyset(&act.sa_mask); /* Tells act to exclude all sa_mask * * signals during execution of * * sig_handler. */ act.sa_flags = 0; /* States that act has a special * * flag of 0 */ sigaction(SIGINT, &act, &oact); /* Tells the program to use (o)act * * on a signal or interrupt */ </code></pre> <p>The echoserver’s sig_handler function is shown below:</p> <pre><code class="language-c">void sig_handler(const int sig) { printf("\nSIGINT handled.\n"); cleanup = 1; return; } </code></pre> <p>That’s it - the echoclient and echoserver are now enabled with TLSv1.2!!</p> <p>What we did:</p> <ul> <li>Included the wolfSSL headers</li> <li>Initialized wolfSSL</li> <li>Created a <code>WOLFSSL_CTX</code> structure in which we chose what protocol we wanted to use</li> <li>Created a <code>WOLFSSL</code> object to use for sending and receiving data</li> <li>Replaced calls to <code>Writen()</code> and <code>Readline()</code> with <a href="group__IO.html#function-wolfssl_write"><code>wolfSSL_write()</code></a> and <a href="group__IO.html#function-wolfssl_read"><code>wolfSSL_read()</code></a></li> <li>Freed <code>WOLFSSL</code>, <code>WOLFSSL_CTX</code></li> <li>Made sure we handled client and server shutdown with signal handler</li> </ul> <p>There are many more aspects and methods to configure and control the behavior of your SSL connections. For more detailed information, please see additional wolfSSL documentation and resources.</p> <p>Once again, the completed source code can be found in the downloaded ZIP file at the top of this section.</p> <h2 id="certificates">Certificates</h2> <p>For testing purposes, you may use the certificates provided by wolfSSL. These can be found in the wolfSSL download, and specifically for this tutorial, they can be found in the <code>finished_src</code> folder.</p> <p>For production applications, you should obtain correct and legitimate certificates from a trusted certificate authority.</p> <h2 id="conclusion">Conclusion</h2> <p>This tutorial walked through the process of integrating the wolfSSL embedded SSL/TLS library into a simple client and server application. Although this example is simple, the same principles may be applied for adding SSL or TLS into your own application. The wolfSSL embedded SSL/TLS library provides all the features you would need in a compact and efficient package that has been optimized for both size and speed.</p> <p>Being dual licensed under GPLv2 and standard commercial licensing, you are free to download the wolfSSL source code directly from our website. Feel free to post to our support forums (<a href="https://www.wolfssl.com/forums">https://www.wolfssl.com/forums</a>) with any questions or comments you might have. If you would like more information about our products, please contact <a href="mailto:info@wolfssl.com">info@wolfssl.com</a>.</p> <p>We welcome any feedback you have on this SSL tutorial. If you believe it could be improved or enhanced in order to make it either more useful, easier to understand, or more portable, please let us know at <a href="mailto:support@wolfssl.com">support@wolfssl.com</a>.</p> </article> </div> </div> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer"> <a href="chapter10.html" class="md-footer__link md-footer__link--prev" aria-label="Previous: 10. wolfCrypt Usage Reference" rel="prev"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg> </div> <div class="md-footer__title"> <div class="md-ellipsis"> <span class="md-footer__direction"> Previous </span> 10. wolfCrypt Usage Reference </div> </div> </a> <a href="chapter12.html" class="md-footer__link md-footer__link--next" aria-label="Next: 12. Best Practices for Embedded Devices" rel="next"> <div class="md-footer__title"> <div class="md-ellipsis"> <span class="md-footer__direction"> Next </span> 12. Best Practices for Embedded Devices </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> Copyright © 2023 wolfSSL Inc. </div> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": ".", "features": [], "translations": {"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing", "select.version.title": "Select version"}, "search": "assets/javascripts/workers/search.22074ed6.min.js"}</script> <script src="assets/javascripts/bundle.1514a9a0.min.js"></script> <script src="search/main.js"></script> </body> </html>

CINXE.COM

11. SSL Tutorial - wolfSSL Manual