Home

CyaSSL User Manual Table of Contents

1. char timeoutName MAX TIMEOUT NAME SZ 1 timeout Name int flags for future use int numberPackets actual of packets PacketInfo packets MAX PACKETS HANDSHAKE list of packets Timeval timeoutValue timer that caused it TimeoutInfo Again no dynamic memory is used for this structure since a maximum number of SSL packets is known for a handshake Timeval is just a typedef for struct timeval Packetinfo is defined like this 67 typedef struct packetInfo st char packetName MAX PACKETNAME SZ 1 SSL name Timeval timestamp when it occured xf unsigned char value MAX VALUE SZ PRL cs TEs here 47 unsigned char bufferValue otherwise here non 0 int valueSz sz of value or buffer PacketInfo Here dynamic memory may be used If the SSL packet can fit in va ue then that s where it s placed valueSz holds the length and bufferValue is 0 If the packet is too big for value only Certificate packets should cause this then the packet is placed in bufferValue valueSz still holds the size If memory is allocated for a Certificate packet then it is reclaimed after the callback returns The timeout is implemented using signals specifically SIGALRM and is thread safe Ifa previous alarm is set of type ITIMER_REAL then it is reset along with the correct handler afterwards The old timer will be time adjusted for any time CyaSSL spends proce
2. SSL v3 0 http tools ietf org id draft ietf tls ssl version3 00 txt TLS v1 0 http www ietf org rfc rfc2246 txt TLS v1 1 http www ietf org rfc rfc4346 txt TLS v1 2 http www ietf org rfc rfc5246 txt DTLS http tools ietf org html rfc4347 http crypto stanford edu nagendra papers dtls pdf IPv4 http en wikipedia org wiki IPv4 IPv6 http en wikipedia org wiki IPv6 B 2 Stream Ciphers Stream Cipher http en wikipedia org wiki Stream_cipher HC 128 http www ecrypt eu org stream p3ciphers hc hc128 p3 pdf RABBIT http cr yp to streamciphers rabbit desc pdf 311 RC4 ARC4 http tools ietf org id draft kaukonen cipher arcfour 03 txt http en wikipedia org wiki Rc4 B 3 Block Ciphers Block Cipher http en wikipedia org wiki Block_cipher AES http csrc nist gov publications fips fips197 fips 197 pdf http en wikipedia org wiki Advanced_ Encryption Standard AES GCM http www csrc nist gov groups S T toolkit BCM documents proposedmodes gcm gqcm revised spec pdf AES NI Intel Software Network DES 3DES http csrc nist gov publications fips fips46 3 fips46 3 pdf http en wikipedia org wiki Data_Encryption Standard B 4 Hashing Functions SHA http www itl nist gov fipspubs fip 180 1 htm http csrc nist gov publications fips fips180 2 fips 180 2 pdf http en wikipedia org wiki SHA_ hash_functions MD4 http tools ietf org html rfc1320 MD5 http t
3. holds the raw data from the key maybe from a file like RsaPublicKey der word32 idx 0 where to start reading into the buffer RsaPublickeyDecode publicKeyBuffer amp idx amp rsaPublicKey sizeof publicKeyBuffer byte in plain text to encrypt byte out 128 RNG rng InitRng amp rng word32 outLen RsaPublicEncrypt in sizeof in out sizeof out amp rsaPublickey amp rng Now out holds the cipher text from the plain text in RsaPublicEncrypt will return the length in bytes written to out or a negative number in case of an error RsaPublicEncrypt needs a RNG Random Number Generator for the padding used by the encryptor and it must be initialized before it can be used To make sure that the output buffer is large enough to pass you can first call RsaEncryptSize which will return the number of bytes that a successful call to RsaPublicEnrypt will write In the event of an error a negative return from RsaPublicEnrypt or 96 RsaPublicKeyDecode for that matter you can call CTaoCryptErrorString to get a string describing the error that occurred void CTaoCryptErrorString int error char buffer Make sure that buffer is at least MAX_ERROR_SZ bytes 80 Now to decrypt out RsaKey rsaPrivateKey byte privateKeyBuffer hold the raw data from the key maybe from a file like RsaPrivateKey der word32 idx 0
4. error loading certificate chain from buffer 141 See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_use_certificate_buffer CyaSSL_use_PrivateKey_buffer CyaSSL_use_certificate_chain_buffer CyaSSL_CTX_use_certificate_chain_file Synopsis int CyaSSL_CTX_use_certificate_chain_file CYASSL_CTX ctx const char file Description This function loads a chain of certificates into the SSL context CYASSL_CTX The file containing the certificate chain is provided by the file argument and must contain PEM formatted certificates This function will process up to MAX_CHAIN_DEPTH default 9 defined in internal h certificates plus the subject cert Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned If the function call fails possible causes might include The file is in the wrong format or the wrong format has been given using the format argument file doesn t exist can t be read or is corrupted an out of memory condition occurs Parameters ctx a pointer to a CYASSL_CTX structure created using CyaSSL_CTX_new file a pointer to the name of the file containing the chain of certificates to be loaded into the CyaSSL SSL context Certificates must be in PEM format Example int ret 0 142 CYASSL CTX ctx ret CyaSSL CTX use certif
5. 303 ssl creation failed ret CyaSSL UseTruncatedHMAC ssl Lf ret t 0 4 truncated HMAC usage failed See Also CyaSSL_new CyaSSL_CTX_UseMaxFragment CyaSSL_CTX_UseSupportedCurve Synopsis include lt cyassl ssl h gt int CVaSSL_CTX_UseSupportedCurve CYASSL_CTX ctx unsigned short name Description This function is called on the client side to enable the use of Supported Elliptic Curves Extension for SSL objects created from the SSL context passed in the ctx parameter It means that the supported curves enabled will be sent on ClientHello by CyaSSL clients This function can be called more than one time to enable multiple curves Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned in one of these cases ctx is NULL name is a unknown value see below MEMORY E is the error returned when there is not enough memory Parameters ctx pointer to a SSL context created with CyaSSL_CTX_new name indicates which curve will be supported for the session The available options 304 are enum CYASSL_ECC_SECP160R1 0x10 CYASSL_ECC_SECP192R1 0x13 CYASSL_ECC_SECP224R1 0x15 CYASSL_ECC_SECP256R1 0x17 CYASSL_ECC_SECP384R1 0x18 CYASSL_ECC_SECP521R1 0x19 Example int ret 0 CYASSL CTX ctx 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ret CyaSSL CTX UseSupp
6. output contains the derived key passwd holds the user password of length pLen salt holds the salt input of length sLen iterations is the number of iterations to perform kLen is the desired derived key length and hashType is the hash to use which can be MD5 SHA1 or SHA2 If you are using configure to build cyassl the way enable this functionality is to use the option enable pwdbased A full example can be found in ctaocrypt src test c More information can be found on PKCS 5 PBKDF1 and PBKDF2 from the following specifications PKCS 5 PBKDF1 PBKDF2 http tools ietf org html rfc2898 4 3 7 2 PKCS 8 PKCS 8 is designed as the Private Key Information Syntax Standard which is used to store private key information including a private key for some public key algorithm and set of attributes The PKCS 8 standard has two versions which describe the syntax to store both encrypted private keys and non encrypted keys CyaSSL supports both non encrypted 54 and encrypted PKCS 8 Supported formats include PKCS 5 version 1 version 2 and PKCS 12 Types of encryption available include DES 3DES RC4 and AES PKCS 8 http tools ietf org html rfc5208 4 3 8 Forcing the Use of a Specific Cipher By default CyaSSL will pick the best highest security cipher suite that both sides of the connection can support To force a specific cipher such as 128 bit AES add something similar to SSL CTX set cipher lis
7. We have a few ideas about creating private keys for SSL enabled devices 1 Each device acting as a server should have a unique private key just like in the non embedded world 2 If the key can t be placed onto the device before delivery have it generated during setup 3 If the device lacks the power to generate it s own key during setup have the client setting up the device generate the key and send it to the device 4 Ifthe client lacks the ability to generate a private key have the client retrieve a unique private key over an SSL connection from the devices known website for example CyaSSL can be used in all of these steps to help ensure an embedded device has a secure unique private key Taking these steps will go a long ways towards securing the SSL connection itself 12 2 Digitally Signing and Authenticating with CyaSSL CyaSSL is a popular tool for digitally signing applications libraries or files prior to loading them on embedded devices Most desktop and server operating systems allow creation of this type of functionality through system libraries but stripped down embedded operating systems do not The reason that embedded RTOS environments do not include digital signature functionality is because it has historically not been a requirement for most embedded applications In today s world of connected devices and heightened security concerns digitally signing what is loaded onto your embedded or mobile devic
8. ctx CyaSSL CTX new method See Also CyaSSLv3_server_method CyaTLSv1_server_method CyaTLSv1_2 server_method CyaDTLSv1_server_method CyaSSLv23_server_method CyaSSL_CTX_new CyaTLSv1_2_client_method Synopsis CYASSL_METHOD CyaTLSv1_2_client_method void Description The CyaTLSv1_2_client_method function is used to indicate that the application is a client and will only support the TLS 1 2 protocol This function allocates memory for and initializes a new CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values 163 If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method CYASSL CTX ctx method CyaTLSv1 2 client _method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_client_method CyaTLSv1_client_method CyaTLSv1_1_client_method CyaDTLSv1_client_method CyaSSLv23_client_method CyaSSL_CTX_new CyaTLSv1_2_server_method Synopsis CYASSL_METHOD CyaTLSv1_2_server_method void Description The CyaTLSv1_2_server_method function is used to indicate that the application is a server and will only support the TLS 1 2 protocol This function allocates memo
9. RC4 SHA RC4 MD5 DES CBC3 SHA AES128 SHA AES256 SHA NULL SHA NULL SHA256 DHE RSA AES128 SHA DHE RSA AES256 SHA PSK AES128 CBC SHA256 PSK AES128 CBC SHA PSK AES256 CBC SHA PSK NULL SHA256 PSK NULL SHA HC128 MD5 HC128 SHA HC128 B2B256 AES128 B2B256 AES256 B2B256 RABBIT SHA NTRU RC4 SHA NTRU DES CBC3 SHA NTRU AES128 SHA NTRU AES256 SHA AES128 CCM 8 AES256 CCM 8 174 ECDHE ECDSA AES128 CCM 8 ECDHE ECDSA AES256 CCM 8 ECDHE RSA AES128 SHA ECDHE RSA AES256 SHA ECDHE ECDSA AES128 SHA ECDHE ECDSA AES256 SHA ECDHE RSA RC4 SHA ECDHE RSA DES CBC3 SHA ECDHE ECDSA RC4 SHA ECDHE ECDSA DES CBC3 SHA AES128 SHA256 AES256 SHA256 DHE RSA AES128 SHA256 DHE RSA AES256 SHA256 ECDH RSA AES128 SHA ECDH RSA AES256 SHA ECDH ECDSA AES128 SHA ECDH ECDSA AES256 SHA ECDH RSA RC4 SHA ECDH RSA DES CBC3 SHA ECDH ECDSA RC4 SHA ECDH ECDSA DES CBC3 SHA AES128 GCM SHA256 AES256 GCM SHA384 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 ECDH RSA AES128 GCM SHA256 ECDH RSA AES256 GCM SHA384 ECDH ECDSA AES128 GCM SHA256 ECDH ECDSA AES256 GCM SHA384 CAMELLIA128 SHA DHE RSA CAMELLIA128 SHA CAMELLIA256 SHA DHE RSA CAMELLIA256 SHA CAMELLIA128 SHA256 DHE RSA CAMELLIA128 SHA256 175 CAMELLIA256 SHA256 DHE RSA CAMELLIA256 SHA256 ECDHE RSA AES128 SHA256 ECDHE ECDSA AES128 SHA256 ECDH RSA AES128 SHA256 ECDH ECDSA AES128 SHA2
10. The CyaSSLv3_client_method function is used to indicate that the application is a client and will only support the SSL 3 0 protocol This function allocates memory for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Parameters This function has no parameters Example CYASSL METHOD method CYASSL CTX ctx method CyaSSLv3_ client _method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaTLSv1_client_method CyaTLSv1_1_client_method CyaTLSv1_2_client_method CyaDTLSv1_client_method CyaSSLv23_client_method CyaSSL_CTX_new CyaSSLv3_server_method 155 Synopsis include lt cyassl ssl h gt CYASSL_METHOD CyaSSLv3_server_method void Description The CyaSSLv3_server_method function is used to indicate that the application is a server and will only support the SSL 3 0 protocol This function allocates memory for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values If successful the call will return a pointer to the newly created CYASSL_MET
11. are located in cyassl ctaocrypt settings h and are commented out by default Each can be uncommented to enable support for the specific chip or stack referenced below 11 IPHONE can be defined if building for use with iOS THREADxX can be defined when building for use with the ThreadX RTOS www rtos com MICRIUM can be defined when building for Micrium s uC OS www micrium com MBED can be defined when building for the mbed prototyping platform www mbed org MICROCHIP_PIC32 can be defined when building for Microchip s PIC32 platform www microchip com MICROCHIP_TCPIP_V5 can be defined specifically version 5 of microchip tcp ip stack MICROCHIP_TCPIP can be defined for microchip tcp ip stack version 6 or later CYASSL_MICROCHIP_PIC32MZ can be defined for PIC32MZ hardware cryptography engine FREERTOS can be defined when building for FreeRTOS www freertos org If using LwIP define CYASSL_LWIP as well FREERTOS_WINSIM can be defined when building for the FreeRTOS windows simulator www freertos org EBSNET can be defined when using EBSnet products and RTIP CYASSL_LWIP can be defined when using CyaSSL with the LwIP TCP IP stack http savannah nongnu org projects lwip CYASSL_GAME_BUILD can be defined when building CyaSSL for a game console CYASSL_LSR can be define if building for LSR 12 FREESCALE _MQxX can be defined when building for Freescale MQX RTCS MFS www freescal
12. ret CyaSSL CTX set _timeout ctx 500 if ret SSL SUCCESS failed to set session timeout value See Also CyaSSL_flush_sessions CyaSSL_get_session CyaSSL_set_session CyaSSL_get_session ID CyaSSL_CTX_set_session_cache_mode CyaSSL_set_using_nonblock Synopsis include lt cyassl ssl h gt void CyaSSL_set_using_nonblock CYASSL ssl int nonblock Description This function informs the CYASSL object that the underlying I O is non blocking After an application creates a CYASSL object if it will be used with a non blocking socket call CyaSSL_set_using_nonblock on it This lets the CYASSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out Return Values 187 This function does not have a return value Parameters ssl pointer to the SSL session created with CyaSSL_new nonblock value used to set non blocking flag on CYASSL object Use 1 to specify non blocking otherwise 0 Example CYASSL ssl 0 CyaSSL_set_using nonblock ssl 1 See Also CyaSSL_get_using_nonblock CyaSSL_dtls_got_timeout CyaSSL_dtls_get_current_timeout CyaSSL_set_verify Synopsis include lt cyassl ssl h gt void CyaSSL_set_verify CYASSL ssl int mode VerifyCallback vc typedef int VerifyCallback int CYASSL_X509_STORE_CTX Description This function sets the verification method for remote peers and also allows a verify callback to be
13. ssl pointer to the SSL session created with CyaSSL_new Example CYASSL ssl 0 ret CyaSSL set _group_messages ssl if ret SSL SUCCESS failed to set handshake message grouping See Also CyaSSL_CTX_set_group_messages CyaSSL_new CyaSSL_CTX_set_group_messages Synopsis int CvaSSL_CTX_set_group_messages CYASSL_CTX ctx Description This function turns on grouping of handshake messages where possible Return Values SSL_SUCCESS will be returned upon success 182 BAD_FUNC_ARG will be returned if the input context is null Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new Example CYASSL_ CTX ctx 0 ret CyaSSL CTX set group messages ctx if ret SSL SUCCESS failed to set handshake message grouping See Also CyaSSL_set_group_messages CyaSSL_CTX_new CyaSSL_set_session Synopsis include lt cyassl ssl h gt int CyaSSL_set_session CYASSL ssl CYASSL_SESSION session Description This function sets the session to be used when the SSL object ssl is used to establish a SSL TLS connection For session resumption before calling CyaSSL_shutdown with your session object an application should save the session ID from the object with a call to CyaSSL_get_session which returns a pointer to the session Later the application should create anew CYASSL object and assign the saved session with CyaSSL_set_session At this p
14. where to start reading into the buffer RsaPrivateKeyDecode privateKeyBuffer amp idx amp rsaPrivateKey sizeof privateKeyBuffer byte plain 128 word32 plainSz RsaPrivateDecrypt out outLen plain sizeof plain amp rsaPrivateKey Now plain will hold plainSz bytes or an error code For complete examples of each type in CTaoCrypt please see the file ctaocrypt test test c Note that the RsaPrivateKeyDecode function only accepts keys in raw DER format 10 5 2 DH Diffie Hellman CTaoCrypt provides support for Diffie Hellman through the header cyassl ctaorypt dh h The Diffie Hellman key exchange algorithm allows two parties to establish a shared secret key Usage is usually similar to the following example where sideA and sideB designate the two parties In the following example dhPublicKey contains the Diffie Hellman public parameters signed by a Certificate Authority or self signed privA holds the generated private key for sideA pubA holds the generated public key for sideA and agreeA holds the mutual key that both sides have agreed on DhKey dhPublicKkey word32 idx 0 where to start reading into the 97 publickeyBuffer word32 pubASz pubBSz agreeASz byte tmp 1024 RNG rng byte privA 128 byte pubA 128 byte agreeA 128 InitDhKey dhPublickey byte publickeyBuffer holds the raw data from the public key parameters maybe from a fil
15. 10 1 1 MD4 NOTE MD4 is outdated and considered broken Please consider using a different hashing function if possible To use MD4 include the MD4 header cyassl ctaocrypt md4 h The structure to use is Md4 which is a typedef Before using the hash initialization must be done with the InitMd4 call Use Md4Update to update the hash and Md4Final to retrieve the final hash byte md4sum MD4 DIGEST SIZE byte buffer 1024 111 buffer with data to hash Md4 md4 InitMd4 amp md4 Md4Update amp md4 buffer sizeof buffer can be called again and again Md4Final amp md4 md4sum md4sum now contains the digest of the hashed data in buffer 10 1 2 MD5 86 To use MD5 include the MD5 header cyassl ctaocrypt md5 h The structure to use is Md5 which is a typedef Before using the hash initialization must be done with the InitMd5 call Use Md5Update to update the hash and Md5Final to retrieve the final hash byte mdSsum MD5 DIGEST SIZE byte buffer 1024 111 buffer with data to hash a r Md5 md5 InitMd5 amp md5 Md5Update amp md5 buffer sizeof buffer can be called again and again Md5Final amp md5 md5sum md5sum now contains the digest of the hashed data in buffer 10 1 3 SHA SHA 256 SHA 384 SHA 512 To use SHA include the SHA header cyass ctaocrypt sha h The str
16. 3 1 General Description CyaSSL is about 10 times smaller than yaSSL and up to 20 times smaller than OpenSSL when using the compile options described in Chapter 2 User benchmarking and feedback also reports dramatically better performance from CyaSSL vs OpenSSL in the vast majority of standard SSL operations For instructions on the build process please see Chapter 2 3 2 Testsuite The testsuite program is designed to test the ability of CyaSSL and its cryptography library CTaoCrypt to run on the system CyaSSL needs all examples and tests to be run from the CyaSSL home directory This is because it finds certs and keys from certs To run testsuite execute testsuite testsuite test or make test when using autoconf On nix or Windows the examples and testsuite will check to see if the current directory is the source directory and if so attempt to change to the CyaSSL home directory This should work in most setup cases if not just use the first method above and specify the full path 24 On a successful run you should see output like this with additional output for unit tests and cipher suite tests MD5 test passed MD4 test passed SHA test passed SHA 256 test passed HMAC MD5 test passed HMAC SHA test passed HMAC SHA256 test passed ARC4 test passed DES test passed DES3 test passed AES test passed RANDOM test passed RSA test passed DH test pas
17. A256 e eee oe 305_ ChaCha cipher suites TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA25 6 Table 4 CyaSSL Cipher Suites 4 3 3 Block and Stream Ciphers CyaSSL supports the AES DES 3DES and Camellia block ciphers and the RC4 RABBIT HC 128 and CHACHAZ20 stream ciphers AES DES 3DES RC4 and RABBIT are enabled by default Camellia HC 128 and ChaCha20 can be enabled 50 when building CyaSSL with the enable hc128 enable camellia and enable chacha build options respectively The default mode of AES is CBC mode To enable GCM or CCM mode with AES use the enable aesgcm and enable aesccm build options Please see the examples for usage and the CTaoCrypt Usage Reference Chapter 10 for specific usage information SSL uses RC4 as the default stream cipher It s a good one though it s getting a little old CyaSSL has added two ciphers from the eStream project into the code base RABBIT and HC 128 RABBIT is nearly twice as fast as RC4 and HC 128 is about 5 times as fast So if you ve ever decided not to use SSL because of speed concerns using CyaSSL s stream ciphers should lessen or eliminate that performance doubt Recently CyaSSL also added ChaCha20 While RC4 performs about 11 times faster then ChaCha RC4 is generally considered less secure than ChaCha ChaCha can put up very nice times of its own with added security as a tradeoff To see a comparison of cipher performance visit the CyaSSL Benchmark web page locat
18. Enable PSK Pre Shared Keys Enable error strings table Enable old TLS version lt 1 2 Ewen Enable MD5 enable md4 Disabled Enable MD4 enable webserver Disabled Enable a build compatible with the yaSSL Embedded Web Server enable pwdbased Disabled Enable PWDBASED enable hc128 Disabled Enable streaming cipher HC 128 CO ie eee enable renegotiation Disabled Enable Renegotiation Indication indication 16 enable fastmath Enabled Enable fast math ops on x86_64 enable fasthugemath Disabled Enable fast math huge code enable examples Enabled Enable examples enable mcapi Disabled Enable Microchip API enable jobserver no yes yes Enable up to make jobs yes enable one more than CPU count disable shared Disabled Disable the building of a shared CyaSSL library disable static Disabled Disable the building of a static CyaSSL library with ntru PATH Disabled Path to NTRU install default usr with libz PATH Disabled Optionally include libz for compression with cavium PATH Disabled Path to cavium software dir 2 5 1 Build Option Notes Debug enabling debug support allows easier debugging by compiling with debug information and defining the constant DEBUG_CYASSL which outputs messages to stderr To turn debug on at runtime call CyaSSL_Debugging_ON To turn debug logging off at runtime call CyaSSL_Debugging_OFF For more information see Chapter 8 Singl
19. Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted 151 MEMORY_E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer NO_PASSWORD will be returned if the key file is encrypted but no password is provided Parameters ctx a pointer to a CYASSL_CTX structure created using CyaSSL_CTX_new file a pointer to the name of the file containing the NTRU private key to be loaded into the CyaSSL SSL context Example int ret 0 CYASSL CTX ctx ret CyaSSL CTX use NTRUPrivateKey file ctx if ret SSL SUCCESS error loading NTRU private key See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_certificate_chain_buffer CyaSSL_use_certificate_buffer CyaSSL_use_PrivateKey_buffer CyaSSL_use_certificate_chain_buffer 152 ntru key raw CyaSSL_KeepArrays Synopsis include lt cyassl ssl h gt void CyaSSL_KeepArrays CYASSL ssl Description Normally at the end of the SSL handshake CyaSSL frees temporary arrays Calling this function before the handshake begins will prevent CyaSSL from freeing temporary arrays Temporary arrays may be needed for things such as Cya
20. TLS for both client and server The current supported version is DTLS 1 0 The TLS protocol was designed to provide a secure transport channel across a reliable medium such as TCP As application layer protocols began to be developed using 44 UDP transport such as SIP and various electronic gaming protocols a need arose for a way to provide communications security for applications which are delay sensitive This need lead to the creation of the DTLS protocol Many people believe the difference between TLS and DTLS is the same as TLS vs UDP This is incorrect UDP has the benefit of having no handshake no tear down and no delay in the middle if something gets lost compared with TCP DTLS on the other hand has an extended SSL handshake and tear down and must implement TCP like behavior for the handshake In essence DTLS reverses the benefits that are offered by UDP in exchange for a secure connection DTLS can be enabled when building CyaSSL by using the enable dtls build option 4 2 6 Lightweight Internet Protocol CyaSSL supports the lightweight internet protocol implementation out of the box To use this protocol all you need to do is define CYASSL_LWIP or navigate to the settings h file and uncomment the line define CYASSL LWIP The focus of IwIP is to reduce RAM usage while still providing a full TCP stack That focus makes IwlP great for use in embedded systems the same area where CyaSSL is an ideal match for
21. and EmbedReceive 5 1 3 Operating System Abstraction Layer The CyaSSL OS abstraction layer helps facilitate easier porting of CyaSSL to a user s operating system The cyassl ctaocrypt settings h file contains settings which end up triggering the OS layer OS specific defines are located in cyassl ctaocrypt types h for CTaoCrypt and cyassl internal h for CyaSSL 65 5 2 Supported Operating Systems One factor which defines CyaSSL is its ability to be easily ported to new platforms As such CyaSSL has support for a long list of operating systems out of the box Currently supported operating systems include Win32 64 Linux Mac OS X Solaris ThreadX VxWorks FreeBSD NetBSD OpenBSD embedded Linux WinCE Haiku OpenWRT iPhone iOS Android Nintendo Wii and Gamecube through DevkitPro QNX MontaVista OpenCL NonStop TRON ITRON UITRON Micrium s uC OS FreeRTOS SafeRTOS Freescale MQX Nucleus TinyOS HP UX TIRTOS 5 3 Supported Chipmakers CyaSSL has support for chipsets from chipmakers including ARM Intel ST STM32F2 F4 Motorola mbed Freescale Microchip PIC32 Texas Instruments and more Chapter 6 Callbacks 6 1 HandShake Callback CyaSSL has an extension that allows a HandShake Callback to be set for connect or accept This can be useful in embedded systems for debugging support when another debugger isn t available and sniffing is impractical To use CyaSSL HandShake Callbacks use the ext
22. 78 CTC SHA384wRSA CTC SHA384wECDSA CTC SHA512wRSA CTC SHA512wECDSA Now the user can initialize the subject information like this example from ctaocrypt test test c strncpy myCert subject country US CTC NAME SIZE strnepy myCert subject state OR CTC NAME SIZE strncpy myCert subject locality Portland CTC NAME SIZE strncpy myCert subject org yaSSL CTC NAME SIZE strncpy myCert subject unit Development CTC NAME SIZE strncpy myCert subject commonName www wolfssl com CTC_NAME SIZE strncpy myCert subject email info wolfssl com Then a self signed certificate can be generated using the variables genKey and rng from the above key generation example of course any valid RsaKey or RNG can be used byte derCert 4096 int certSz MakeSelfCert amp myCert derCert sizeof derCert amp key amp rng if certSz lt 0 certSz contains the error The buffer derCert now contains a DER format of the certificate If you need a PEM format of the certificate you can use the generic DerToPem function and specify the type to be CERT_TYPE like this byte pem int pemSz DerToPem derCert certSz pem sizeof pemCert CERT TYPE 7 if pemCertSz lt 0 pemCertSz contains error 79 Now the buffer pemCert holds the PEM format of the certificate If you wish to create a CA signed certificate then a couple of step
23. CyaSSL_use_certificate_chain_buffer CyaSSL_use_certificate_buffer Synopsis include lt cyassl ssl h gt int CyaSSL_use_certificate_buffer CYASSL ssl const unsigned char in long sz int format Description This function loads a certificate buffer into the CYASSL object It behaves like the non buffered version only differing in its ability to be called with a buffer as input instead of a file The buffer is provided by the in argument of size sz format specifies the format type of the buffer SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file Parameters ssl pointer to the SSL session created with CyaSSL_new 147 in buffer containing certificate to load sz size of the certificate located in buffer format format of the certificate to be loaded Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int buffSz int ret byte certBuff CYASSL ssl 0 ret CyaSSL_use certificate buffer ssl certBuff buffSz SSL FILETYPE PEM if ret SSL SUCCESS failed to load certificate from buf
24. DSA uses the SHA hash algorithm to generate a hash of a block of data then signs that hash using the signer s private key Standard usage is similar to the following We first declare our DSA key structure key initialize our initial message message to be signed and initialize our DSA key buffer dsaKeyBuffer DsakKey key byte message message data to sign holds the raw data from the DSA key maybe from a file like dsa512 der byte dsakeyBuffer We then declare our SHA structure sha random number generator rng array to store our SHA hash hash array to store our signature signature idx to mark where to start reading in our dsaKeyBuffer and an int answer to hold our return value after verification Sha sha RNG rng byte hash SHA DIGEST SIZE byte signature 40 word32 idx 0 int answer Set up and create the SHA hash For more information on CTaoCrypt s SHA algorithm see section 10 1 3 The SHA hash of message is stored in the variable hash InitSha amp sha ShaUpdate amp sha message sizeof message ShaFinal amp sha hash 99 Initialize the DSA key structure populate the structure key value and initialize the random number generator rng InitDsakey amp key DsaPrivateKeyDecode dsakeyBuffer G amp idx amp key sizeof dsaKeyBuffer InitRng amp rng The DsaSign function creates a signature signature
25. SSL functionality We will first begin by adding SSL to the echoclient and subsequently move on to the echoserver 11 6 Initial Compilation 11 6 Initial Compilation 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 make 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 tcpcli01 c echoclient or tcpserv04 c echoserver in the following command with correct source file for the example gcc o echoserver lib c tcpserve4 c I include 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 106 echoserver 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 di
26. the previous API function failed SSL_ERROR_NONE will be returned if ret gt 0 Parameters ssl pointer to the SSL object created with CyaSSL_new ret return value of the previous function that resulted in an error return code Example int err 0 CYASSL ssl char buffer 80 err CyaSSL_ get_error ssl 0 CyaSSL_ERR_error string err buffer printf err d s n err buffer See Also CyaSSL_ERR_error_string CyaSSL_ERR_error_string_n CyaSSL_ERR_print_errors_fp CyaSSL_load_error_strings CyaSSL_load_error_strings Synopsis include lt cyassl ssl h gt void CyaSSL_load_error_strings void Description This function is for OpenSSL compatibility SSL_load_error_string only and takes no 223 action Return Values This function has no return value Parameters This function takes no parameters Example CyaSSL load error strings See Also CyaSSL_get_error CyaSSL_ERR_error_string CyaSSL_ERR_error_string_n CyaSSL_ERR_print_errors_fp CyaSSL_load_error_strings CyaSSL_want_read Synopsis include lt cyassl ssl h gt int CyaSSL_want_read CYASSL ssl Description This function is similar to calling CyaSSL_get_error and getting SSL_ERROR_WANT_READ in return If the underlying error state is SSL_ERROR_WANT_READ this function will return 1 otherwise 0 Return Values 1 CyaSSL_get_error would return SSL_ERROR_WANT_READ the underlying I O has data a
27. 0 ret CyaSSL CTX _set_ session cache mode ctx SSL SESS CACHE OFF if ret SSL SUCCESS failed to turn SSL session caching off See Also CyaSSL_flush_sessions CyaSSL_get_session CyaSSL_set_session CyaSSL_get_sessionID CyaSSL_CTX_set_timeout CyaSSL_set_timeout Synopsis include lt cyassl ssl h gt int CyaSSL_set_timeout CYASSL ssl unsigned int to Description This function sets the SSL session timeout value in seconds Return Values 185 SSL_SUCCESS will be returned upon successfully setting the session BAD_FUNC_ARG will be returned if ssl is NULL Parameters ssl pointer to the SSL object created with CyaSSL_new to value in seconds used to set the SSL session timeout Example int ret 0 CYASSL ssl 0 ret CyaSSL_ set_timeout ssl 500 if ret SSL SUCCESS failed to set session timeout value See Also CyaSSL_get_session CyaSSL_set_session CyaSSL_CTX_set_timeout Synopsis int CyaSSL_CTX_set_timeout CYASSL_CTX ctx unsigned int to Description This function sets the timeout value for SSL sessions in seconds for the specified SSL context Return Values SSL_SUCCESS will be returned upon success 186 BAD_FUNC_ARG will be returned when the input context ctx is null Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new to session timeout value in seconds Example CYASSL_ CTX ctx 0
28. 1 Chapter 2 Building CyaSSL CyaSSL was written with portability in mind and should generally be easy to build on most systems If you have difficulty building CyaSSL please don t hesitate to seek support through our support forums http www wolfssl com forums or contact us directly at support wolfssl com This chapter explains how to build CyaSSL on Unix and Windows and provides guidance for building CyaSSL in a non standard environment You will find a getting started guide in Chapter 3 and an SSL tutorial in Chapter 11 When using the autoconf automake system to build CyaSSL CyaSSL uses a single Makefile to build all parts and examples of the library which is both simpler and faster than using Makefiles recursively 2 1 Getting CyaSSL Source Code The most recent version of CyaSSL can be downloaded from the wolfSSL website as a ZIP file http wolfssl com yaSSL download downloadForm php After downloading the ZIP file unzip the file using the unzip command To use native line endings enable the a modifier when using unzip From the unzip man page the a modifier functionality is described The a option causes files identified by zip as text files those with the t label in zipinfo listings rather than b to be automatically extracted as such converting line endings end of file characters and the character set itself as necessary For example Unix files use line feeds LF s fo
29. 9 A more complete walk through with example code is located in the SSL Tutorial in Chapter 11 If you want more information about the OpenSSL compatibility layer please see Chapter 13 1 Include the CyaSSL header include lt cyassl ssl h gt 2 Change all calls from read or recv to CyaSSL_read so 36 4 result read fd buffer bytes becomes result CyaSSL read ssl buffer bytes Change all calls from write or send to CyaSSL_write so result write fd buffer bytes becomes result CyaSSL write ssl buffer bytes You can manually call CyaSSL_connect but that s not even necessary the first call to CyaSSL_read or CyaSSL_write will initiate the CyaSSL_connect if it hasn t taken place yet Initialize CyaSSL and the CYASSL_CTX You can use one CYASSL_CTX no matter how many CYASSL objects you end up creating Basically you ll just need to load CA certificates to verify the server you are connecting to Basic initialization looks like CyaSSL Init CYASSL CTX ctx if ctx CyaSSL CTX new CyaTLSvl_ client method NULL fprintf stderr CyaSSL CTX new error n exit EXIT_FAILURE if CyaSSL CTX load verify locations ctx ca cert pem 0 SSL SUCCESS fprintf stderr Error loading ca cert pem please check the file n exit EXIT_FAILURE 37 6 Create the CYASSL object after each TCP
30. Abstraction Layers 5 1 1 C Standard Library Abstraction Layer CyaSSL can be built without the C standard library to provide a higher level of portability and flexibility to developers The user will have to map the functions they wish to use instead of the C standard ones 5 1 1 1 Memory Use Most C programs use malloc and free for dynamic memory allocation CyaSSL uses XMALLOC and XFREE instead By default these point to the C runtime versions By defining XMALLOC_USER the user can provide their own hooks Each memory function takes two additional arguments over the standard ones a heap hint and an allocation type The user is free to ignore these or use them in any way they like You can find the CyaSSL memory functions in cyassl ctaocrypt types h CyaSSL also provides the ability to register memory override functions at runtime instead of compile time cyassl ctaocrypt memory h is the header for this functionality and the user can call the following function to setup the memory functions int CyaSSL SetAllocators CyaSSL Malloc_ cb malloc function CyaSSL Free cb free function CyaSSL Realloc cb realloc function See the header cyassl ctaocrypt memory h for the callback prototypes and memory c for the implementation 5 1 1 2 string h CyaSSL uses several functions that behave like string h s memcpy memset and memcmp amongst others They are abstracted to XMEMCPY XMEMSET and XMEMCMP r
31. CRL checking is off options include CYASSL_CRL_CHECKALL which performs CRL checking on each certificate in the chain versus the Leaf certificate only which is the default Return Values If successful the call will return SSL_SUCCESS NOT_COMPILED_IN will be returned if CyaSSL was not built with CRL enabled MEMORY_E will be returned if an out of memory condition occurs BAD_FUNC_ARG is the error that will be returned if a pointer is not provided SSL_FAILURE will be returned if the CRL context cannot be initialized properly 270 Parameters cm a pointer toa CYASSL_CERT_MANAGER structure created using CyaSSL_CertManagerNew options options to use when enabling the Certification Manager cm Example int ret 0 CYASS L_ CERT MANAGER cm ret CyaSSL CertManagerEnableCRL cm 0 if ret SSL SUCCESS error enabling cert manager See Also CyaSSL_CertManagerDisableCRL CyaSSL_CertManagerFree Synopsis include lt cyassl ssl h gt void CyaSSL_CertManagerFree CYASSL_CERT_MANGER cm Description Frees all resources associated with the Certificate Manager context Call this when you no longer need to use the Certificate Manager Return Values No return value is used Parameters 271 cm a pointer toa CYASSL_CERT_MANAGER structure created using CyaSSL_CertManagerNew Example CYASSL_CERT_MANAGER cm CyaSSL_ CertManagerFree cm See Also CyaSSL_CertMana
32. CyaSSL_GetClientWriteKey Synopsis include lt cyassl ssl h gt const unsigned char CyaSSL_GetClientWriteKey CYASSL ssl Description Allows retrieval of the client write key from the handshake process Return Values If successful the call will return a valid pointer to the key The size of the key can be obtained from CyaSSL_GetKeySize NULL will be returned for an error state 231 Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetKeySize CyaSSL_GetClientWritelV CyaSSL_GetClientWritelV Synopsis include lt cyassl ssl h gt const unsigned char CyaSSL_GetClientWritelV CYASSL ssl Description Allows retrieval of the client write IV initialization vector from the handshake process Return Values If successful the call will return a valid pointer to the IV The size of the IV can be obtained from CyaSSL_GetCipherBlockSize NULL will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetCipherBlockSize CyaSSL_GetClientWriteKey CyaSSL_GetServerWriteKey Synopsis include lt cyassl ssl h gt const unsigned char CyaSSL_GetServerWriteKey CYASSL ssl 232 Description Allows retrieval of the server write key from the handshake process Return Values If successful the call will return a valid pointer to the key The size of the key can be obtained from
33. CyaSSL_recv will only be able to return the maximum buffer size which has been decrypted at the time of calling There may be additional not yet decrypted data waiting in the internal CyaSSL receive buffer which will be retrieved and decrypted with the next call to CyaSSL_recv If sz is larger than the number of bytes in the internal read buffer SSL_recv will return the bytes available in the internal read buffer If no bytes are buffered in the internal read buffer yet a call to CyaSSL_recv will trigger processing of the next record 253 Return Values gt 0 the number of bytes read upon success 0 will be returned upon failure This may be caused by a either a clean close notify alert shutdown or just that the peer closed the connection Call CyaSSL_get_error for the specific error code SSL_FATAL_ERROR will be returned upon failure when either an error occurred or when using non blocking sockets the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_recv again Use CyaSSL_get_error to get a specific error code Parameters ssl pointer to the SSL session created with CyaSSL_new data buffer where CyaSSL_recv will place data read sz number of bytes to read into data flags the recv flags to use for the underlying recv operation Example CYASSL ssl 0 char reply 1024 int flags input CyaSSL_ recv ssl reply sizeof re
34. This function returns a pointer to the current session CYASSL_SESSION used in ssl The CYASSL_SESSION pointed to contains all the necessary information required to perform a session resumption and reestablish the connection without a new handshake For session resumption before calling CyaSSL_shutdown with your session object an application should save the session ID from the object with a call to CyaSSL_get_session which returns a pointer to the session Later the application should create a new CYASSL object and assign the saved session with CyaSSL_set_session At this point the application may call CyaSSL_connect and CyaSSL will try to resume the session The CyaSSL server code allows session resumption by default Return Values If successful the call will return a pointer to the the current SSL session object NULL will be returned if ssl is NULL the SSL session cache is disabled CyaSSL doesn t have the Session ID available or mutex functions fail Parameters ssl pointer to the SSL session created with CyaSSL_new Example CYASSL ssl 0 CYASSL_SESSION session 0 245 session CyaSSL_ get _session ssl if session NULL failed to get session pointer See Also CyaSSL_set_session CyaSSL_get_using_nonblock Synopsis include lt cyassl ssl h gt int CyaSSL_get_using_nonblock CYASSL ssl Description This function allows the application to determine if CyaSSL is using non
35. This should reduce memory use by nearly 3 kB NO_TLS turns off TLS We don t recommend turning off TLS SMALL_SESSION_CACHE can be defined to limit the size of the SSL session cache used by CyaSSL This will reduce the default session cache from 33 sessions to 6 sessions and save approximately 2 5 kB 2 4 2 Enabling Features Disabled by Default CYASSL_CERT_GEN turns on CyaSSL s certificate generation functionality See chapter 7 for more information CYASSL_DER_LOAD allows loading DER formatted CA certs into the CyaSSL context CYASSL_CTX using the function CyaSSL_CTX_der_load_verify_locations CYASSL_DTLS turns on the use of DTLS or datagram TLS This isn t widely supported or used so it is off by default CYASSL_KEY_GEN turns on CyaSSL s RSA key generation functionality See chapter 7 for more information CYASSL_RIPEMD enables RIPEMD 160 support CYASSL_SHA384 enables SHA 384 support CYASSL_SHA512 enables SHA 512 support DEBUG_CYASSL builds in the ability to debug For more information regarding debugging CyaSSL see Chapter 8 It is off by default HAVE_AESCCM enables AES CCM support HAVE_AESGCM enables AES GCM support HAVE_CAMELLIA enables Camellia support HAVE_CHACHA enables ChaCha20 support HAVE_POLY1305 enables Poly1305 support HAVE_CRL enables Certificate Revocation List CRL support HAVE_ECC enables Elliptical Curve Cryptography ECC support HAVE_LIBZ is an extension that can allow for compr
36. aesni enable poly1305 enable camellia enable md2 enable nullcipher enable ripemd enable blake2 enable sha512 enable sessioncerts Disabled Enable extra OpenSSL API compatibility increases the size Disabled Enable testing of IPv6 CyaSSL proper is IP neutral Disabled Enable SSL Bump build Disabled Enable Lean PSK build Disabled Enable a big session cache Disabled Enable a huge session cache Disabled Enable small session cache Disabled Enable CyaSSL sniffer support Disabled Enable AES GCM support Disabled Enable AES CCM support Disabled Enable CyaSSL Intel AES NI support Disabled Enable CyaSSL RIPEMD 160 support Disabled Enable CyaSSL BLAKE2 support Disabled Enable CyaSSL SHA 512 support Disabled Enable session cert storing 14 enable keygen enable certgen enable certreq enable sep enable hkdf enable dsa enable ecc enable fpecc enable eccencrypt enable psk enable errorstrings enable oldtls enable stacksize enable memory enable rsa enable dh enable asn enable aes enable coding enable des3 enable arc4 enable md5 Disabled Disabled Disabled Disabled Disabled Disabled Disabled Disabled 15 Enable key generation Enable cert generation Enable cert request generation Enable SEP extensions Enable HKDF HMAC KDF Enable DSA Enable ECC Enable Fixed Point cache ECC Enable ECC encrypt
37. already been set up CyaSSL_accept works with both blocking and non blocking I O When the underlying I O is non blocking CyaSSL_accept will return when the underlying I O could not satisfy the needs of of CyaSSL_accept to continue the handshake In this case a call to CyaSSL_get_error will yield either SSL_LERROR_WANT_READ or SSL_ERROR_WANT_WRITE The calling process must then repeat the call to CyaSSL_accept when data is available to read and CyaSSL will pick up where it left off When using a non blocking socket nothing needs to be done but select can be used to check for the required condition If the underlying I O is blocking CyaSSL_accept will only return once the handshake has been finished or an error occurred Return Values If successful the call will return SSL_SUCCESS SSL_FATAL_ERROR will be returned if an error occurred To get a more detailed error code call CyaSSL_get_error 240 Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new Example int ret 0 int err 0 CYASSL ssl char buffer 80 ret CyaSSL_accept ssl if ret SSL SUCCESS err CyaSSL_ get_error ssl ret printf error d s n err CyaSSL_ ERR error string err buffer See Also CyaSSL_get_error CyaSSL_connect CyaSSL_connect Synopsis include lt cyassl ssl h gt int CyaSSL_connect CYASSL ssl Description This function is called on the client sid
38. blocking I O If CyaSSL is using non blocking I O this function will return 1 otherwise 0 After an application creates a CYASSL object if it will be used with a non blocking socket call CyaSSL_set_using_nonblock on it This lets the CYASSL object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out Return Values 0 underlying I O is blocking 1 underlying I O is non blocking Parameters ssl pointer to the SSL session created with CyaSSL_new Example int ret 0 CYASSL ssl 0 246 ret CyaSSL_ get_using nonblock ssl if ret 1 underlying I O is non blocking See Also CyaSSL_set_session CyaSSL_flush_sessions Synopsis include lt cyassl ssl h gt void CyaSSL_flush_sessions CYASSL_CTX ctx long tm Description This function flushes session from the session cache which have expired The time tm is used for the time comparison Note that CyaSSL currently uses a static table for sessions so no flushing is needed As such this function is currently just a stub This function provides OpenSSL compatibility SSL_flush_sessions when CyaSSL is compiled with the OpenSSL compatibility layer Return Values This function does not have a return value Parameters ctx a pointer to a CYASSL_CTX structure created using CyaSSL_CTX_new tm time used in session expiration comparison Example CYASSL CTX ssl CyaSSL_ flu
39. client method ff TLS 1 0 CyaTLSv1_1_client_method TLS 1 1 CyaTLSvl_ 2 client _method TLS 1 2 CyaSSLv23_ client _method Use highest version possible from SSiv3 TLS 1 2 108 CyaDTLSv1l_ client method DILS 1 0 CyaDTLSv1 2 client _method DTLS 1 2 EchoServer CyaSSLv3_ server methods SSLv3 CyaTLSvl_ server method TLSv1 CyaTLSvl_1 server _method TLSv1 1 CyaTLSvl_ 2 server _method TLSv1 2 Allow clients to connect with SSLv3 or TLSvl1t CyaDTLSv1 server method DTS CyaDTLSv1_2 server method DTLS 1 2 CyaSSLv23_ server method We need to load our CA Certificate Authority certificate into the CYASSL_CTX 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 CYASSL_CTX use CyaSSL_CTX_load_verify_locations This function requires three arguments a CYASSL_CTX 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 CyaSSL 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 CyaSSL_CTX_load_verify_locations function returns either SSL_SUCCESS or SSL_FAILURE CyaSSL_
40. does not have a return value Parameters ssl pointer to a SSL object created with CyaSSL_new type indicates which type of server name is been passed in data The known types are enum CYASSL_SNI_HOST_NAME 0 options a bitwise semaphore with the chosen options The available options are enum CYASSL_SNI_CONTINUE_ON_MISMATCH 0x01 CYASSL_SNI_ANSWER_ON_MISMATCH 0x02 Normally the server will abort the handshake by sending a fatal level 294 unrecognized_name 112 alert if the hostname provided by the client mismatch with the servers CYASSL_SNI_CONTINUE_ON_MISMATCH With this option set the server will not send a SNI response instead of aborting the session CYASSL_SNI_LANSWER_ON_MISMATCH With this option set the server will send a SNI response as if the host names match instead of aborting the session Example int ret 0 CYASSL CTX ctx 0 CYASSL ssl 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ssl CyaSSL_new ctx if ssl NULL ssl creation failed ret CyaSSL_ UseSNI ssl 0 www yassl com strilen www yassl com if ret 0 sni usage failed CyaSSL_SNI_ SetOptions ssl CYASSL SNI HOST NAME CYASSL_SNI_CONTINUE_ON_ MISMATCH See Also CyaSSL_new CyaSSL_UseSNI CyaSSL_CTX_SNI_SetOptions CyaSSL_SNI_GetRequest 295 Synopsis include lt cyassl ssl h gt unsigned short CyaSSL_SN
41. ecc_key byte output word32 inLen Example define FOURK BUF 4096 byte der FOURK BUF ecCUkey userB EccKeyToDer amp userB der FOURK BUF Chapter 8 Debugging 8 1 Debugging and Logging CyaSSL has support for debugging through log messages in environments where debugging is limited To turn logging on use the function CyaSSL_Debugging_ON and to turn it off use CyaSSL_Deubgging_OFF In a normal build release mode these functions will have no effect In a debug build define DEBUG_CYASSL to ensure these functions are turned on As of CyaSSL 2 0 logging callback functions may be registered at runtime to provide more flexibility with how logging is done The logging callback can be registered with the following function int CyaSSL SetLoggingCb CyaSSL Logging cb log function typedef void CyaSSL Logging cb const int logLevel const char const logMessage 81 The log levels can be found in cyassl ctaocrypt logging h and the implementation is located in logging c By default CyaSSL logs to stderr with fprintf 8 2 Error Codes CyaSSL tries to provide informative error messages in order to help with debugging Each CyaSSL_read and CyaSSL_write call will return the number of bytes written upon success 0 upon connection closure and 1 for an error just like read and write In the event of an error you can use two calls to get more information about the error The function C
42. if you specify command line arguments for the client example then a client certificate isn t loaded and the CyaSSL_connect will fail unless client cert 29 check is disabled using the d option The server will report an error 245 peer didn t send cert Like the example client the server can be used with several command line arguments as well examples server server help server 2 8 0 NOTE All files relative to CyaSSL home dir Help print this usage p lt num gt Port to listen on not 0 default 11111 vy lt num gt SSL version 0 3 SSLv3 0 TLS1 2 3 default 3 1 lt str gt Cipher list c lt file gt Certificate file default certs server cert pem k lt file gt Key file default certs server key pem A lt file gt Certificate Authority file default certs client cert pem d Disable client cert check b Bind to any interface instead of localhost only s Use pre Shared keys t Track CyaSSL memory use u Use UDP DTLS add v 2 for DTLSv1 default v 3 for DTLSv1 2 f Fewer packets group messages N Use Non blocking sockets S lt str gt Use Host Name Indication 3 5 EchoServer Example The echoserver example sits in an endless loop waiting for an unlimited number of client connections Whatever the client sends the echoserver echos back Client authentication isn t performed so the example client can be used against the echoserver in all 3 modes Fo
43. is the input buffer to encrypt while encSz is the size of the input An example callback can be found cyassl test h myMacEncryptCb 205 Return Values NA See Also CyaSSL_SetMacEncryptCtx CyaSSL_GetMacEncryptCtx CyaSSL_SetMacEncryptCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetMacEncryptCtx CYASSL void ctx Description Allows caller to set the Atomic User Record Processing Mac Encrypt Callback Context to ctx Return Values NA See Also CyaSSL_CTX_SetMacEncryptCb CyaSSL_GetMacEncryptCtx CyaSSL_GetMacEncryptCtx Synopsis include lt cyassl ssl h gt void CyaSSL_GetMacEncryptCtx CYASSL Description Allows caller to retrieve the Atomic User Record Processing Mac Encrypt Callback Context previously stored with CyaSSL_SetMacEncryptCtx Return Values 206 If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetMacEncryptCb CyaSSL_SetMacEncryptCtx CyaSSL_CTX_SetDecryptVerifyCb Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetDecryptVerifyCb CYASSL_CTX CallbackDecryptVerify typedef int CallbackDecryptVerify CYASSL ssl unsigned char decOut const unsigned char decin unsigned int decSz int content int verify unsigned int padSz void ctx Description Allows caller to set the Atomic User Record Processing Decrypt Verify Callback The callback should retu
44. of the original file descriptor sockfd The new str_cli function is shown below Notice that we now need to check if our calls to CyaSSL_write and CyaSSL_read were successful The authors of the Unix Programming book wrote error checking into their Writen function which we must make up for after it has been replaced We add a new int variable n to monitor the return value of CyaSSL_read and before printing out the contents of the buffer recvline the end of our read data is marked with a 0 void str_cli FILE fp CYASSL ssl charsendline MAXLINE recvline MAXLINE 113 while Fgets sendline MAXLINE fp NULL if CyaSSL_write ssl sendline strlen sendline strlen sendline err_sys CyaSSL_write failed if n CyaSSL_read ssl recvline MAXLINE lt err_quit CyaSSL_read error recvline n Fputs recvline stdout The last thing to do is free the CYASSL object when we are completely done with it In the main function right before the line to free the CYASSL_CTX call to CyaSSL_free str_cli stdin ssl CyaSSL_free ssl Free CYASSL object CyaSSL_CTX_free ctx Free CYASSL_CTX object CyaSSL_Cleanup Free CyaSSL EchoServer The echo server makes a call to str_echo to handle reading and writing whereas the client made a call to str_cli As with the client modify str_echo by replacing the sockfd parameter with an CY
45. packets PacketInfo packets MAX PACKETS HANDSHAKE list of packets Timeval timeoutValue timer that caused it TimeoutInfo typedef struct packetInfo st char packetName MAX PACKETNAME SZ 1 SSL name x Timeval timestamp when it occured RY unsigned char value MAX VALUE SZ if fits it s here if unsigned char bufferValue otherwise here non 0 a int valueSz sz of value or buffer ef PacketInfo 202 Description CyaSSL_accept_ex is an extension that allows a HandShake Callback to be set This can be useful in embedded systems for debugging support when a debugger isn t available and sniffing is impractical The HandShake Callback will be called whether or not a handshake error occurred No dynamic memory is used since the maximum number of SSL packets is known Packet names can be accessed through packetNamesjJ The connect extension also allows a Timeout Callback to be set along with a timeout value This is useful if the user doesn t want to wait for the TCP stack to timeout This extension can be called with either both or neither callbacks Return Values If successful the call will return SSL_SUCCESS GETTIME_ERROR will be returned if gettimeofday encountered an error SETITIMER_ERROR will be returned if setitimer encountered an error SIGACT_ERROR will be returned if sigaction encountered an error SSL_FATAL_ERROR will be returned
46. passed HA 256 test passed AC MD5 test passed HA test passed AC SHA256 test passed RC4 test passed ES D a n ES test passed ES3 test passed Yo O tmi g u n ES test passed RANDOM test passed RSA test passed DH test passed PWDBASED test passed OPENSSL test passed peer s cert info issuer C US ST 0regon L Portland O yaSSL OU Programming CN www yassl com emailAddre ss info yassl com subject C US ST Oregon L Portland O yaSSL OU Programming CN www yassl com emailAddre ss info yassl com serial number 87 4a 75 be 91 66 d8 3d SSL version is TLSv1 2 peer s cert info issuer C US ST Montana L Bozeman 0 Sawtooth OU Consulting CN www yassl com emailAdd ress info yassl com subject C US ST Montana L Bozeman O yaSSL OU Support CN www yassl com emailAddress i nfo yassl com SSL cipher suite is TLS DHE RSA WITH AES 256 CBC SHA256 105 serial number 02 SSL version is TLSv1 2 SSL cipher suite is TLS DHE RSA WITH AES 256 CBC SHA256 Client message hello cyassl Server response I hear you fa shizzle sending server shutdown command quit client sent quit command shutting down 9al04af3d164e37c0dabe3316f7bc35b9be5fd771la09ealcda478d4057 f0b06e input 9al04af3d164e37c0dabe3316f7bc35b9be5fd771a09ealcda478d4057 f0b06e tmp output All tests passed Now that CyaSSL has been installed we can begin modifying the example code to add
47. registered with the SSL session The verify callback will be called only when a verification failure has occurred If no verify callback is desired the NULL pointer can be used for verify_callback The verification mode of peer certificates is a logically OR d list of flags The possible flag values include 188 SSL_VERIFY_NONE Client mode the client will not verify the certificate received from the server and the handshake will continue as normal Server mode the server will not send a certificate request to the client As such client verification will not be enabled SSL_VERIFY_PEER Client mode the client will verify the certificate received from the server during the handshake This is turned on by default in CyaSSL therefore using this option has no effect Server mode the server will send a certificate request to the client and verify the client certificate received SSL_VERIFY_FAIL_IF_NO PEER_CERT Client mode no effect when used on the client side Server mode the verification will fail on the server side if the client fails to send a certificate when requested to do so when using SSL_VERIFY_PEER on the SSL server Return Values This function has no return value Parameters ssl pointer to the SSL session created with CyaSSL_new mode session timeout value in seconds verify_callback callback to be called when verification fails If no callback is desired the NULL pointer can be used for ve
48. size_t size custom realloc function See Also NA 17 11 Certificate Manager The functions in this section are part of the CyaSSL Certificate Manager The Certificate Manager allows applications to load and verify certificates external to the SSL TLS connection CyaSSL_CertManagerDisableCRL Synopsis include lt cyassl ssl h gt int CyaSSL_CertManagerDisableCRL CYASSL_CERT_MANGER cm Description Turns off Certificate Revocation List checking when verifying certificates with the Certificate Manager By default CRL checking is off You can use this function to temporarily or permanently disable CRL checking with this Certificate Manager context that previously had CRL checking enabled Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided Parameters cm a pointer to a CYASSL_CERT_MANAGER structure created using CyaSSL_CertManagerNew 269 Example int ret 0 CYASSL_CERT MANAGER cm ret CyaSSL CertManagerDisableCRL cm if ret SSL SUCCESS error disabling cert manager See Also CyaSSL_CertManagerEnableCRL CyaSSL_CertManagerEnableCRL Synopsis include lt cyassl ssl h gt int CyaSSL_CertManagerEnableCRL CYASSL_CERT_MANGER cm int options Description Turns on Certificate Revocation List checking when verifying certificates with the Certificate Manager By default
49. specific error code Parameters ssl pointer to the SSL session created with CyaSSL_new data buffer where CyaSSL_peek will place data read sz number of bytes to read into data Example CYASSL ssl 0 char reply 1024 input CyaSSL peek ssl reply sizeof reply if input gt 0 input number of bytes returned into buffer reply See Also CyaSSL_read CyaSSL_pending Synopsis include lt cyassl ssl h gt int CyaSSL_pending CYASSL ssl Description This function returns the number of bytes which are buffered and available in the SSL object to be read by CyaSSL_read Return Values 250 This function returns the number of bytes pending Parameters ssl pointer to the SSL session created with CyaSSL_new Example int pending 0 CYASSL ssl 0 pending CyaSSL_ pending ssl printf There are Sd bytes buffered and available for reading pending See Also CyaSSL_recv CyaSSL_read CyaSSL_peek CyaSSL_read Synopsis include lt cyassl ssl h gt int CyaSSL_read CYASSL ssl void data int sz Description This function reads sz bytes from the SSL session ssl internal read buffer into the buffer data The bytes read are removed from the internal receive buffer If necessary CyaSSL_read will negotiate an SSL TLS session if the handshake has not already been performed yet by CyaSSL_connect or CyaSSL_accept The SSL TLS protocol
50. specific protocol version method is used on either side then only that version will be negotiated or an error will be returned For example a client that uses TLSv1 and tries to connect to a SSLv3 only server will fail likewise connecting to a TLSv1 1 will fail as well To resolve this issue a client that uses the CyaSSLv23_client_method function will use the highest protocol version supported by the server and downgrade to SSLv3 if needed In this case the client will be able to connect to a server running SSLv3 TLSv1 2 The only version it can t connect to is SSLv2 which has been insecure for years Similarly a server using the CyaSSLv23_server_method function can handle clients supporting protocol versions from SSLv3 TLSv1 2 A CyaSSL server can t accept a connection from SSLv2 because no security is provided 4 2 4 IPv6 Support If you are an adopter of IPv6 and want to use an embedded SSL implementation then you may have been wondering if CyaSSL supports IPv6 The answer is yes we do support CyaSSL running on top of IPv6 CyaSSL was designed as IP neutral and will work with both IPv4 and IPv6 but the current test applications default to IPv4 so as to apply to a broader number of systems To change the test applications to IPv6 use the enable ipv6 option while building CyaSSL Further information on IPv6 can be found here http en wikipedia org wiki IPv6 4 2 5 DTLS CyaSSL has support for DTLS Datagram
51. uses SSL records which have a maximum size of 16kB the max record size can be controlled by the MAX_RECORD_SIZE define in lt cyassl_root gt cyassl internal h As such CyaSSL needs to read an entire SSL record internally before it is able to process and decrypt the record Because of this a call to CyaSSL_read will only be able to return the maximum buffer size which has been 251 decrypted at the time of calling There may be additional not yet decrypted data waiting in the internal CyaSSL receive buffer which will be retrieved and decrypted with the next call to CyaSSL_read If sz is larger than the number of bytes in the internal read buffer SSL_read will return the bytes available in the internal read buffer If no bytes are buffered in the internal read buffer yet a call to CyaSSL_read will trigger processing of the next record Return Values gt 0 the number of bytes read upon success 0 will be returned upon failure This may be caused by a either a clean close notify alert shutdown or just that the peer closed the connection Call CyaSSL_get_error for the specific error code SSL_FATAL_ERROR will be returned upon failure when either an error occurred or when using non blocking sockets the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_read again Use CyaSSL_get_error to get a specific error code Parameters ssl pointer to the SSL session cre
52. value If it has been too long this will return a failure 262 Return Values SSL_SUCCESS will be returned upon success SSL_FATAL_ERROR will be returned if there have been too many retransmissions timeouts without getting a response from the peer NOT_COMPILED_IN will be returned if CyaSSL was not compiled with DTLS support Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new Example See the following files for usage examples lt cyassl_root gt examples client client c lt cyassl_root gt examples server server c See Also CyaSSL_dtls_get_current_timeout CyaSSL_dtls_get_peer CyaSSL_dtls_set_peer CyaSSL_dtls CyaSSL_dtls_set_peer Synopsis include lt cyassl ssl h gt int CyaSSL_dtls_set_peer CYASSL ssl void peer unsigned int peerSz Description This function sets the DTLS peer peer sockaddr_in with size of peerSz Return Values SSL_SUCCESS will be returned upon success 263 SSL_FAILURE will be returned upon failure SSL_NOT_IMPLEMENTED will be returned if CyaSSL was not compiled with DTLS support Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new peer pointer to peer s sockaddr_in structure peerSz size of the sockaddr_in structure pointed to by peer Example int ret 0 CYASSL ssl sockaddr in addr ret CyaSSL dtls_set_peer ssl amp addr sizeof addr if ret SSL SUCCESS failed to set DTLS peer S
53. version only differing in its ability to be called with a buffer as input instead of a file The buffer is provided by the in argument of size sz format specifies the format type of the buffer SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file NO_PASSWORD will be returned if the key file is encrypted but no password is provided Parameters ssl pointer to the SSL session created with CyaSSL_new in buffer containing private key to load sz size of the private key located in buffer format format of the private key to be loaded Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int buffSz int ret byte keyBuff CYASSL ssl 0 ret CyaSSL_use PrivateKey buffer ssl keyBuff buffSz SSL FILETYPE PEM if ret SSL SUCCESS failed to load private key from buffer 146 See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_CTX_use_certificate_chain_buffer CyaSSL_use_certificate_buffer
54. 0 00 68 b6 SSL version is TLSv1 2 SSL cipher suite is SSL RSA WITH RC4 128 SHA SSL connect ok sending GET Server response HTTP 1 0 302 Found Cache Control private Content Type text html charset UTF 8 Location http www google com Content Length 218 Date Mon 01 Oct 2012 21 17 18 GMT Server GFE 2 0 This tells the client to connect to gmail google com on the HTTPS port of 443 and sends a generic GET The d option tells the client not to verify the server The rest is the initial output from the server that fits into the read buffer If no command line arguments are given then the client attempts to connect to the localhost on the CyaSSL default port of 11111 It also loads the client certificate in case the server wants to perform client authentication The client is able to benchmark a connection when using the b lt num gt argument When used the client attempts to connect to the specified server port the argument number of times and gives the average time in milliseconds that it took to perform SSL_connect For example examples client client b 100 SSL _ connect avg took 0 653 milliseconds 28 If you d like to change the default host from localhost or the default port from 11111 you can change these settings in cyassl test h The variables yassIIP and yassIPort control these settings Re build all of the examples including testsuite when changing these settings other
55. 07 11 8 Headers The first thing we will need to do is include the CyaSSL native API header in both the client and the server In the tcpcli01 c file for the client and the tcpserv04 c file for the server add the following line near the top include lt cyassl ssl h gt 11 9 Startup Shutdown Before we can use CyaSSL in our code we need to initialize the library and the CYASSL_CTX CyaSSL is initialized by calling CyaSSL_Init This must be done first before anything else can be done with the library The CYASSL_CTX structure CyaSSL Context contains global values for each SSL connection including certificate information A single CYASSL_CTX can be used with any number of CYASSL objects created This allows us to load certain information such as a list of trusted CA certificates only once To create anew CYASSL_CTX use CyaSSL_CTX_new 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 CyaSSL currently supports SSL 3 0 TLS 1 0 TLS 1 1 TLS 1 2 DTLS 1 0 and DTLS 1 2 Each of these protocols have a corresponding function that can be used as an argument to CyaSSL_CTX_new The possible client and server protocol options are shown below SSL 2 0 is not supported by CyaSSL because it has been insecure for several years EchoClient CyaSSLv3_client_method ff SSL 220 CyaTLSvl_
56. 1_2_client_method CyaDTLSv1_client_method CyaSSLv23_client_method CyaSSL_CTX_new CyaTLSv1_server_method Synopsis CYASSL_METHOD CyaTLSv1_server_method void Description The CyaTLSv1_server_method function is used to indicate that the application is a server and will only support the TLS 1 0 protocol This function allocates memory for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values 160 If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method CYASSL CTX ctx method CyaTLSvl_ server method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_server_method CyaTLSv1_1_server_method CyaTLSv1_2 server_method CyaDTLSv1_server_method CyaSSLv23_server_method CyaSSL_CTX_new CyaTLSv1_1_client_method Synopsis CYASSL_METHOD CyaTLSv1_1_client_method void Description The CyaTLSv1_1_client_method function is used to indicate that the application is a client and will only support the TLS 1 0 protocol This function allocates memory for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_C
57. 56 ECDHE ECDSA AES256 SHA384 ECDH RSA AES256 SHA384 ECDH ECDSA AES256 SHA384 Return Values SSL_SUCCESS will be returned upon successful function completion otherwise SSL_FAILURE will be returned on failure Parameters ssl pointer to the SSL session created with CyaSSL_new list null terminated text string and a colon delimited list of cipher suites to use with the specified SSL session Example int ret 0 CYASSL ssl 0 ret CyaSSL set cipher list ssl DHE RSA AES256 SHA256 DHE RSA AES128 SHA256 AES256 SHA256 if ret SSL SUCCESS failed to set cipher suite list See Also CyaSSL_CTX_set_cipher_list CyaSSL_new CyaSSL_CTX_set_cipher_list Synopsis 176 int CyaSSL_CTX_set_cipher_list CYASSL_CTX ctx const char list Description This function sets cipher suite list for a given CYASSL_CTX This cipher suite list becomes the default list for any new SSL sessions CYASSL created using this context The ciphers in the list should be sorted in order of preference from highest to lowest Each call to CyaSSL_CTX_set_cipher_list resets the cipher suite list for the specific SSL context to the provided list each time the function is called The cipher suite list list is a null terminated text string and a colon delimited list For example one value for list may be DHE RSA AES256 SHA256 DHE RSA AES128 SHA256 AES256 SHA256 Valid cipher values are the full
58. 8 CyaSSL_CTX_SetEccSignCb Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetEccSignCb CYASSL_CTX CallbackEccSign typedef int CallbackEccSign CYASSL ssl const unsigned char in unsigned int inSz unsigned char out unsigned int outSz const unsigned char keyDer unsigned int keySz void ctx Description Allows caller to set the Public Key Callback for ECC Signing The callback should return O for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience in is the input buffer to sign while inSz denotes the length of the input out is the output buffer where the result of the signature should be stored outSz is an input output variable that specifies the size of the output buffer upon invocation and the actual size of the signature should be stored there before returning keyDer is the ECC Private key in ASN1 format and keySz is the length of the key in bytes An example callback can be found cyassl test h myEccSign Return Values NA See Also CyaSSL_SetEccSignCtx CyaSSL_GetEccSignCtx CyaSSL_SetEccSignCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetEccSignCtx CYASSL void ctx Description Allows caller to set the Public Key Ecc Signing Callback Context to ctx 209 Return Values NA See Also CyaSSL_CTX_SetEccSignCb CyaSSL_GetEccSignCtx CyaSSL_GetEccSignCtx Synopsis include lt cyassl ssl h gt void CyaSSL
59. A AES128 SHA256 ECDH RSA AES128 SHA256 ECDH ECDSA AES 128 SHA256 ECDHE ECDSA AES256 SHA384 ECDH RSA AES256 SHA384 ECDH ECDSA AES256 SHA384 Return Values SSL_SUCCESS will be returned upon successful function completion otherwise SSL_FAILURE will be returned on failure Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new list null terminated text string and a colon delimited list of cipher suites to use with the specified SSL context Example CYASSL_ CTX ctx 0 ret CyaSSL CTX set cipher list ctx DHE RSA AES256 SHA256 DHE RSA AES128 SHA256 AES256 SHA256 if ret SSL SUCCESS failed to set cipher suite list See Also CyaSSL_set_cipher_list CyaSSL_CTX_new 179 CyaSSL_set_compression Synopsis include lt cyassl ssl h gt int CyaSSL_set_compression CYASSL ssl Description Turns on the ability to use compression for the SSL connection Both sides must have compression turned on otherwise compression will not be used The zlib library performs the actual data compression To compile into the library use with libz for the configure system and define HAVE_LIBZ otherwise Keep in mind that while compressing data before sending decreases the actual size of the messages being sent and received the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks Retur
60. AES CBC CTR GCM CCM 8 Camellia DES 3DES ARC4 RABBIT HC 128 ChaCha20 Public Key Options 5 public key options RSA DSS DH EDH NTRU Password based Key Derivation 3 password based key derivation HMAC PBKDF2 PKCS 5 options ECC Support ECDH ECDSA ECDHE ECDSA ECDH RSA ECDHE RSA RSA Key Generation Fast run time key generation support Client Authentication Support Provides ability to do mutual authentication between client and server using certificates to verify clients PSK Pre Shared Keys Support Helpful for embedded devices lacking resources to do public key operations Avoid RSA operations in limited environments Simple API Easy to learn and use zlib Compression Support Highly configurable compression support PEM and DER certificate support No need to reconfigure certificates or keys X 509 v3 Signed Certificate Generation Generate your own certificates Certificate Manager Verify certs check CRL outside of SSL usage 41 Intel AES NI Support STM32F2 F4 Hardware Crypto Support Cavium NITROX Support Sniffer SSL Inspection Support Abstraction Layers Callbacks C Standard Library Custom I O Memory hooks Logging callbacks User Atomic Record Layer Processing Public Key RSA ECC callbacks IPv4 and IPv6 support PKCS 8 PKCS 5 12 formats MySQL Integration Supported Web Servers yaSSLEWS GoAhead Mongoose Lighttpd Super fast chip level AES encryption
61. ASN_UNKNOWN_OID_E ASN_DATE_SZ_E ASN_BEFORE_DATE_E ASN_AFTER_DATE_E ASN_SIG_OID_E ASN_TIME_E ASN_INPUT_E ASN_SIG_CONFIRM_E ASN_SIG_HASH_E ASN_SIG_KEY_E ASN_DH_KEY_E ASN_NTRU_KEY_E ASN_CRIT_EXT_E ECC_BAD_ARG_E ASN_ECC_KEY_E ECC_CURVE_OID_E BAD_FUNC_ARG NOT_COMPILED_IN UNICODE_SIZE_E NO_ PASSWORD ALT_NAME_E 318 C 3 Common Error Codes and their Solution There are several error codes that commonly happen when getting an application up and running with CyaSSL 319 ASN_NO_SIGNER_E 188 This error occurs when using a certificate and the signing CA certificate was not loaded This can be seen using the CyaSSL example server or client against another client or server for example connecting to Google using the CyaSSL example client examples client client g h www google com p 443 This fails with error 188 because Google s CA certificate wasn t loaded with the A command line option WANT_READ 323 The WANT_READ error happens often when using non blocking sockets and isn t actually an error when using non blocking sockets but it is passed up to the caller as an error When a call to receive data from the I O callback would block as there isn t data currently available to receive the I O callback returns WANT_READ The caller should wait and try receiving again later This is usually seen from calls to CyaSSL_read CyaSSL_negotiate CyaSSL_accept and CyaSSL_connect The example cl
62. ASSL object ssl parameter in the function signature void str_echo CYASSL ssl Replace the calls to read and Writen with calls to the CyaSSL_read and CyaSSL_write functions The modified str_echo function including error checking of return values is shown below Note that the type of the variable n has been changed from ssize_t to int in order to accommodate for the change from read to CyaSSL_read 114 void str_echo CYASSL ssl intn charbuf MAXLINE while n CyaSSL_read ssl buf MAXLINE gt if CyaSSL_write ssl buf n n err_sys CyaSSL_write failed if n lt printf CyaSSL_read error d n CyaSSL_get_error ssl n else if n printf The peer has closed the connection n Call the str_echo 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 CYASSL object and close the connfd socket str_echo ssl process the request CyaSSL_free ssl Free CYASSL object Close connfd We will free the ctx and cleanup before the call to exit 11 12 Signal Handling Echoclient In order for CyaSSL resources to be released we make a call for the user to break in order to close the client This is done in the str_cli function directly after the while loop The program exit gracefully after the user types break in the command line while the c
63. ASSL_CTX CallbackRsaEnc typedef int CallbackRsaEnc CYASSL ssl const unsigned char in unsigned int inSz unsigned char out unsigned int outSz const unsigned char keyDer unsigned int keySz void ctx Description Allows caller to set the Public Key Callback for RSA Public Encrypt The callback should return O for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience in is the input buffer to encrypt while inSz denotes the length of the input out is the output buffer where the result of the encryption should be stored outSz is an input output variable that specifies the size of the output buffer upon invocation and the actual size of the encryption should be stored there before returning keyDer is the RSA Public key in ASN1 format and keySz is the length of the key in bytes An example callback can be found cyassl test h myRsaEnc Return Values NA See Also CyaSSL_SetRsaEncCtx CyaSSL_GetRsaEncCtx CyaSSL_SetRsaEncCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetRsaEncCtx CYASSL void ctx Description Allows caller to set the Public Key RSA Public Encrypt Callback Context to ctx 216 Return Values NA See Also CyaSSL_CTX_SetRsaEncCb CyaSSL_GetRsaEncCtx CyaSSL_GetRsaEncCtx Synopsis include lt cyassl ssl h gt void CyaSSL_GetRsaEncCtx CYASSL Description Allows caller to retrieve the Public Key RSA Public Encrypt C
64. ASSL_SERVER_END or 234 CYASSL_CLIENT_END depending on the side of CYASSL object BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetClientWriteKey CyaSSL_GetServerWriteKey CyaSSL_IsTLSv1_1 Synopsis include lt cyassl ssl h gt int CyaSSL_IsTLSV1_1 CYASSL ssl Description Allows caller to determine if the negotiated protocol version is at least TLS version 1 1 or greater Return Values If successful the call will return 1 for true or 0 for false BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetSide CyaSSL_GetBulkCipher Synopsis 235 include lt cyassl ssl h gt int CyaSSL_GetBulkCipher CYASSL ssl Description Allows caller to determine the negotiated bulk cipher algorithm from the handshake Return Values If successful the call will return one of the following cyassl_cipher_null cyassl_des cyassl_triple_des cyassl_aes cyassl _aes_gcm cyassl_aes_ccm cyassl_camellia cyass _hc128 cyassl _ rabbit BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetCipherBlockSize CyaSSL_GetKeySize CyaSSL_GetCipherBlockSize Synopsis include lt cyassl ssl h gt int CyaSSL_GetCipherBlockSize CYASSL ss
65. Accelerate crypto on STM32 processors Accelerate crypto and SSL using Cavium NITROX Decode SSL encrypted packets Providing more flexibility and portability to developers Compatible with current and upcoming protocols Private Key Encryption Wide distribution and testing Multiple lightweight embedded web server options CyaSSL is also used in the yaSSL Embedded Web Server Table 1 CyaSSL Features 4 1 2 AEAD Suites CyaSSL supports AEAD suites including AES GCM AES CCM and CHACHA POLY1305 The big difference between these AEAD suites and others is that they authenticate the encrypted data This helps with mitigating man in the middle attacks that result in having data tampered with AEAD suites use a combination of a block cipher or more recently also a stream cipher algorithm combined with a tag produced by a keyed hash algorithm Combining these two algorithms is handled by the CyaSSL encrypt and decrypt process which makes it easier for users All that is needed for using a specific AEAD suite is simply enabling the algorithms that are used in a supported suite 4 2 Protocol Support CyaSSL supports SSL 3 0 TLS 1 0 1 1 and 1 2 and DTLS 1 0 and 1 2 You can easily select a protocol to use by using one of the following functions as shown for either the client or server CyaSSL does not support SSL 2 0 as it has been insecure for several years The client and server functions below change slightly when u
66. CTX_load_verify_locations CYASSL_CTX ctx const char file const char path Putting these things together library initialization protocol selection and CA certificate we have the following Here we choose to use TLS 1 2 EchoClient CYASSL_CTX ctx CyaSSL_Init Initialize CyaSSL Create the CYASSL_CTX if ctx CyaSSL_CTX_new CyaTLSv1_2_client_method NULL 109 fprintf stderr CyaSSL_CTX_new error n exit EXIT_FAILURE Load CA certificates into CYASSL_CTX if CyaSSL_CTX_load_verify_locations ctx certs ca cert pem SSL_SUCCESS fprintf stderr Error loading certs ca cert pem please check the file n exit EXIT_FAILURE EchoServer When loading certificates into the CYASSL_CTX 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 CYASSL_CTX ctx CyaSSL_Init Initialize CyaSSL Create the CYASSL_CTX if ctx CyaSSL_CTX_new CyaTLSv1_2_server_method NULL fprintf stderr CyaSSL_CTX_new error n exit EXIT_FAILURE Load server certificates into CYASSL_CTX CyaSSL_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 CyaSSL_CTX_us
67. CYASSL object ssl Create CYASSL object CYASSL ssl if ssl CyaSSL new ctx NULL fprintf stderr CyaSSL new error n exit EXIT FAILURE CyaSSL_ set fd ssl sockfd 112 One thing to notice here is we haven t made a call to the CyaSSL_connect function CyaSSL_connect initiates the SSL TLS handshake with the server and is called during CyaSSL_read if it hasn t been called previously In our case we don t explicitly call CyaSSL_connect as we let our first CyaSSL_read do it for us 11 11 Sending Receiving Data EchoClient The next step is to begin sending data securely Take note that in the echoclient example the main function hands off the sending and receiving work to str_cli The str_cli function is where our function replacements will be made First we need access to our CYASSL object in the str_cli function so we add another argument and pass the ssl variable to str_cli Because the CYASSL object is now going to be used inside of the str_cli function we remove the sockfd parameter The new str_cli function signature after this modification is shown below void str_cli FILE fp CYASSL ssl In the main function the new argument ssl is passed to str_cli str_cli stdin ssl Inside the str_cli function Writen and Readline are replaced with calls to CyaSSL_write and CyaSSL_read functions and the CYASSL object ssl is used instead
68. CyaSSL User Manual September 11 2014 Version 3 2 0 Table of Contents Chapter 1 Introduction Chapter 2 Building CyaSSL 2 1 Getting CyaSSL Source Code 2 2 Building on nix 2 3 Building on Windows 2 4 Building in a Non Standard Environment 2 5 Build Options configure Options 2 6 Cross Compiling Chapter 3 Getting Started 3 1 General Description 3 2 Testsuite 3 3 Client Example 3 4 Server Example 3 5 EchoServer Example 3 6 EchoClient Example 3 7 Benchmark 3 8 Changing a Client Application to Use CyaSSL 3 9 Changing a Server Application to Use CyaSSL Chapter 4 Features 4 1 Features Overview 4 2 Protocol Support 4 3 Cipher Support 4 4 Hardware Accelerated Crypto 4 5 SSL Inspection 4 6 Compression 4 7 Pre Shared Keys 4 8 Client Authentication 4 9 Server Name Indication SNI 4 10 Handshake Modifications 4 11 Truncated HMAC Chapter 5 Portability 5 1 Abstraction Layers 5 2 5 3 Chapter 6 6 1 6 2 Chapter 7 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 Chapter 8 8 1 8 2 Chapter 9 9 1 9 2 9 3 9 4 9 5 9 6 Chapter 10 10 1 10 2 10 3 10 4 10 5 Chapter 11 Chapter 12 Chapter 13 Chapter 14 Chapter 15 Chapter 16 Chapter 17 Supported Operating Systems Supported Chipmakers Callbacks Handshake Callback Timeout Callback Keys and Certificates Supported Formats and Sizes Certificate Loading Certificate Chain Verification Domain Name Check for Server Certificates No File System an
69. CyaSSL_GetKeySize NULL will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetKeySize CyaSSL_GetServerWritelV CyaSSL_GetServerWritelV Synopsis include lt cyassl ssl h gt const unsigned char CyaSSL_GetServerWritelV CYASSL ssl Description Allows retrieval of the server write IV initialization vector from the handshake process Return Values If successful the call will return a valid pointer to the IV The size of the IV can be obtained from CyaSSL_GetCipherBlockSize NULL will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also 233 CyaSSL_GetCipherBlockSize CyaSSL_GetClientWriteKey CyaSSL_GetKeySize Synopsis include lt cyassl ssl h gt int CyaSSL_GetKeySize CYASSL ssl Description Allows retrieval of the key size from the handshake process Return Values If successful the call will return the key size in bytes BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetClientWriteKey CyaSSL_GetServerWriteKey CyaSSL_GetSide Synopsis include lt cyassl ssl h gt int CyaSSL_GetSide CYASSL ssl Description Allows retrieval of the side of this CYASSL connection Return Values If successful the call will return either CY
70. CyaSSL_SetEccVerifyCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetEccVerifyCtx CYASSL void ctx Description Allows caller to set the Public Key Ecc Verification Callback Context to ctx Return Values NA See Also CyaSSL_CTX_SetEccVerifyCb CyaSSL_GetEccVerifyCtx CyaSSL_GetEccVerifyCtx 211 Synopsis include lt cyassl ssl h gt void CyaSSL_GetEccVerifyCtx CYASSL Description Allows caller to retrieve the Public Key Ecc Verification Callback Context previously stored with CyaSSL_SetEccVerifyCtx Return Values If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetEccVerifyCb CyaSSL_SetEccVerifyCtx CyaSSL_CTX_SetRsaSignCb Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetEccRsaCb CYASSL_CTX CallbackRsaSign typedef int CallbackRsaSign CYASSL ssl const unsigned char in unsigned int inSz unsigned char out unsigned int outSz const unsigned char keyDer unsigned int keySz void ctx Description Allows caller to set the Public Key Callback for RSA Signing The callback should return O for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience in is the input buffer to sign while inSz denotes the length of the input out is the output buffer where the result of the signature should be stored outSz is an input output variabl
71. EAD or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_send again Use CyaSSL_get_error to get a specific error code Parameters 255 ssl pointer to the SSL session created with CyaSSL_new data data buffer to send to peer sz size in bytes of data to be sent to peer flags the send flags to use for the underlying send operation Example CYASSL ssl 0 char msg 64 hello cyass1 int msgSz int strlen msg int flags input CyaSSL_send ssl msg msgSz flags if input msgSz CyaSSL_send failed See Also CyaSSL_write CyaSSL_read CyaSSL_recv CyaSSL_write Synopsis include lt cyassl ssl h gt int CyaSSL_write CYASSL ssl const void data int sz Description This function writes sz bytes from the buffer data to the SSL connection ssl If necessary CyaSSL_write will negotiate an SSL TLS session if the handshake has not already been performed yet by CyaSSL_connect or CyaSSL_accept CyaSSL_write works with both blocking and non blocking I O When the underlying I O is non blocking CyaSSL_write will return when the underlying I O could not satisfy 256 the needs of of CyaSSL_write to continue In this case a call to CyaSSL_get_error will yield either SSL_LERROR_WANT_READ or SSL_ERROR_WANT_WRITE The calling process must then repeat the call to CyaSSL_write when the underlying I O is ready If th
72. E_E will be returned if the current date is after the after date SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file BAD_FUNC_ARG is the error that will be returned if a pointer is not provided Parameters cm a pointer to a CYASSL_CERT_MANAGER structure created using CyaSSL_CertManagerNew cert pointer to the name of the file containing the certificates to verify format format of the certificate to verify either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int ret 0 CYASSL_CERT MANAGER cm ret CyaSSL CertManagerVerify cm path to cert file pem SSL FILETYPE PEM if ret SSL SUCCESS error verifying certificate See Also CyaSSL_CertManagerLoadCA CyaSSL_CertManagerVerifyBuffer CyaSSL_CertManagerVerifyBuffer 275 Synopsis include lt cyassl ssl h gt int CyaSSL_CertManagerVerify CYASSL_CERT_MANGER cm const unsigned char buff int sz int format Description Specifies the certificate buffer to verify with the Certificate Manager context The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 Return Values If successful the call will return SSL_SUCCESS ASN_SIG_CONFIRM_E will be returned if the signature coul
73. G is the error that will be returned in one of these cases ctx is NULL data is NULL type is a unknown value see below MEMORY E is the error returned when there is not enough memory 289 Parameters ctx pointer to a SSL context created with CyaSSL_CTX_new type indicates which type of server name is been passed in data The known types are enum CYASSL_SNI_HOST_NAME 0 data pointer to the server name data size size of the server name data Example int ret 0 CYASSL CTX ctx 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ret CyaSSL_CTX_UseSNI ctx CYASSL_SNI_HOST_NAME strlen www yassl com if ret 0 sni usage failed See Also CyaSSL_CTX_new CyaSSL_UseSNI CyaSSL_UseSNI Synopsis include lt cyassl ssl h gt 290 www yassl com int CvaSSL_UseSNI CYASSL ssl unsigned char type const void data unsigned short size Description This function enables the use of Server Name Indication in the SSL object passed in the ssl parameter It means that the SNI extension will be sent on ClientHello by CyaSSL client and CyaSSL server will respond ClientHello SNI with either ServerHello blank SNI or alert fatal in case of SNI mismatch Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned in one of these cases ssl is NULL data is NULL type
74. HMAC extension will be sent on ClientHello by CyaSSL clients Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned in one of these cases ctx is NULL MEMORY_E is the error returned when there is not enough memory Parameters ctx pointer to a SSL context created with CyaSSL_CTX_new Example int ret 0 CYASSL_ CTX ctx 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ret CyaSSL CTX UseTruncatedHMAC ctx if ret 0 truncated HMAC usage failed See Also CyaSSL_CTX_new 302 CyaSSL_UseMaxFragment CyaSSL_UseTruncatedHMAC Synopsis include lt cyassl ssl h gt int CyaSSL_UseTruncatedHMAC CYASSL ssl Description This function is called on the client side to enable the use of Truncated HMAC in the SSL object passed in the ssl parameter It means that the Truncated HMAC extension will be sent on ClientHello by CyaSSL clients Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned in one of these cases ssl is NULL MEMORY_E is the error returned when there is not enough memory Parameters ssl pointer to a SSL object created with CyaSSL_new Example int ret 0 CYASSL CTX ctx 0 CYASSL ssl 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ssl CyaSSL_new ctx if ssl NULL
75. HOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Parameters This function has no parameters Example CYASSL METHOD method CYASSL CTX ctx method CyaSSLv3 server method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaTLSv1_server_method CyaTLSv1_1_server_method CyaTLSv1_2_ server_method CyaDTLSv1_server_method 156 CyaSSLv23_server_method CyaSSL_CTX_new CyaSSLv23_client_method Synopsis include lt cyassl ssl h gt CYASSL_METHOD CyaSSLv23_client_method void Description The CyaSSLv23_client_method function is used to indicate that the application is a client and will support the highest protocol version supported by the server between SSL 3 0 TLS 1 2 This function allocates memory for and initializes a new CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Both CyaSSL clients and servers have robust version downgrade capability Ifa specific protocol version method is used on either side then only that version will be negotiated or an error will be returned For example a client that uses TLSv1 and tries to connect to a SSLv3 only server will fail likewise connecting to a TLSv1 1 will fail as well To resolve this issue a client that uses the CyaSSLv23_client_
76. I_GetRequest CYASSL ssl unsigned char type void data Description This function is called on the server side to retrieve the Server Name Indication provided by the client in a SSL session Return Values The size of the provided SNI data Parameters ssl pointer to a SSL object created with CyaSSL_new type indicates which type of server name is been retrieved in data The known types are enum CYASSL_SNI_HOST_NAME 0 data pointer to the data provided by the client Example int ret 0 CYASSL CTX ctx 0 CYASSL ssl 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ssl CyaSSL_new ctx if ssl NULL ssl creation failed 296 ret CyaSSL UseSNI ssl 0 www yassl com strilen www yassl com if ret 0 sni usage failed if CyaSSL accept ssl SSL SUCCESS void data NULL unsigned short size CyaSSL SNI GetRequest ssl 0 amp data See Also CyaSSL_UseSNI CyaSSL_CTX_UseSNI CyaSSL_SNI_GetFromBuffer Synopsis include lt cyassl ssl h gt CYASSL_API int CyaSSL_SNI_GetFromBuffer const unsigned char clientHello unsigned int helloSz unsigned char type unsigned char sni unsigned int inOutSz Description This function is called on the server side to retrieve the Server Name Indication provided by the client from the Client Hello message sent by the client to start a session It does not requires con
77. It behaves like the non buffered version only differing in its ability to be called with a buffer as input instead of a file The buffer is provided by the in argument of size sz format specifies the format type of the buffer SSL_FILETYPE_ASN1ior SSL_FILETYPE_PEM Please see the 136 examples for proper usage Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file NO_PASSWORD will be returned if the key file is encrypted but no password is provided Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new in the input buffer containing the private key to be loaded sz the size of the input buffer format the format of the private key located in the input buffer in Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int ret 0 int sz 0 CYASSL CTX ctx byte keyBuff ret CyaSSL CTX_use PrivateKey buffer ctx keyBuff sz SSL FILETYPE PEM if ret SSL SUCCESS error loading private key from buffer 137 See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_CTX_use_certificat
78. L API and crypto tests make test Further details about expected output of the testsuite program can be found in Section 3 2 If you want to build only the CyaSSL library and not the additional items examples testsuite benchmark app etc you can run the following command from the CyaSSL root directory make src libcyassl la 2 3 Building on Windows VS 2008 Solutions are included for Visual Studio 2008 in the root directory of the install For use with Visual Studio 2010 and later the existing project files should be able to be converted during the import process To test each build choose Build All from the Visual Studio menu and then run the testsuite program To edit build options in the Visual Studio project select your desired project cyassl echoclient echoserver etc and browse to the Properties panel Cygwin If using Cygwin or other toolsets for Windows that provides nix like commands and functionality please follow the instructions in section 2 2 above for Building on nix If building CyaSSL for Windows on a Windows development machine we recommend using the included Visual Studio project files to build CyaSSL 2 4 Building in a non standard environment While not officially supported we try to help users wishing to build CyaSSL in a non standard environment particularly with embedded and cross compilation systems Below are some notes on getting started with this 1 The source
79. L object ssl Create CYASSL object CYASSL ssl if ssl CyaSSL_new ctx NULL fprintf stderr CyaSSL_new error n exit EXIT_FAILURE CyaSSL_set_fd ssl sockfd 111 One thing to notice here is we haven t made a call to the CyaSSL_connect function CyaSSL_connect initiates the SSL TLS handshake with the server and is called during CyaSSL_read if it hasn t been called previously In our case we don t explicitly call CyaSSL_connect as we let our first CyaSSL_read do it for us EchoServer At the end of the for loop in the main method insert the CYASSL object and associate the socket file descriptor connfd with the CYASSL object ssl just as with the client Create CYASSL object CYASSL ssl if ssl CyaSSL_new ctx NULL fprintf stderr CyaSSL_new error n exit EXIT_FAILURE CyaSSL_set_fd ssl connfd A CYASSL 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 Connect shown below Connect to socket file descriptor Connect sockfd SA amp servaddr sizeof servaddr Create a new CYASSL object using the CyaSSL_new function This function returns a pointer to the CYASSL object if successful or NULL in the case of failure We can then associate the socket file descriptor Sockfd with the new
80. L_connect or CyaSSL_accept The SSL TLS protocol uses SSL records which have a maximum size of 16kB the max record size can be controlled by the MAX_RECORD_ SIZE define in lt cyassl_root gt cyassl internal h As such CyaSSL needs to read an entire SSL record internally before it is able to process and decrypt the record Because of this a call to CyaSSL_peek will only be able to return the maximum buffer size which has been decrypted at the time of calling There may be additional not yet decrypted data waiting in the internal CyaSSL receive buffer which will be retrieved and decrypted with the next call to CyaSSL_peek CyaSSL_read If sz is larger than the number of bytes in the internal read buffer SSL_peek will return the bytes available in the internal read buffer If no bytes are buffered in the internal read buffer yet a call to CyaSSL_peek will trigger processing of the next record Return Values gt 0 the number of bytes read upon success 0 will be returned upon failure This may be caused by a either a clean close notify alert shutdown or just that the peer closed the connection Call CyaSSL_get_error for the specific error code 249 SSL_FATAL_ERROR will be returned upon failure when either an error occurred or when using non blocking sockets the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_peek again Use CyaSSL_get_error to get a
81. New Synopsis include lt cyassl ssl h gt CYASSL_CERT_MANAGER CyaSSL_CertManagerNew void Description Allocates and initializes a new Certificate Manager context This context be used independent of SSL needs It may be used to load certificates verify certificates and check the revocation status Return Values If successful the call will return a valid CYASSL_CERT_MANAGER pointer NULL will be returned for an error state 273 Parameters There are no parameters for this function Example CYASSL_CERT_MANAGER cm cm CyaSSL CertManagerNew if cm NULL error creating new cert manager See Also CyaSSL_CertManagerFree CyaSSL_CertManagerVerify Synopsis include lt cyassl ssl h gt int CyaSSL_CertManagerVerify CYASSL_CERT_MANGER cm const char cert int format Description Specifies the certificate to verify with the Certificate Manager context The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 Return Values If successful the call will return SSL_SUCCESS ASN_SIG_CONFIRM_E will be returned if the signature could not be verified ASN_SIG_OID_E will be returned if the signature type is not supported CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked CRL_MISSING is an error that is returned if a current issuer CRL is not available ASN_BEFORE_DATE_E will be returned if the current date is before the before date 274 ASN_AFTER_DAT
82. READ NOT_READY_ERROR PMS_VERSION_ERROR VERSION_ERROR WANT_WRITE BUFFER_ERROR VERIFY_CERT_ERROR VERIFY_SIGN_ERROR CLIENT_ID_ERROR SERVER_HINT_ERROR PSK_KEY_ERROR ZLIB_INIT_ERROR ZLIB_COMPRESS_ERROR ZLIB_DECOMPRESS_ERROR GETTIME_ERROR GETITIMER_ERROR SIGACT_ERROR SETITIMER_ERROR 314 LENGTH_ERROR PEER_KEY_ERROR ZERO_RETURN SIDE_ERROR NO_PEER_CERT NTRU_KEY_ERROR NTRU_DRBG_ERROR NTRU_ENCRYPT_ERROR NTRU_DECRYPT_ERROR ECC_CURVETYPE_ERROR ECC_CURVE_ERROR ECC_PEERKEY_ERROR ECC_MAKEKEY_ERROR ECC_EXPORT_ERROR ECC_SHARED_ERROR NOT_CA_ERROR BAD_PATH_ERROR BAD_CERT_MANAGER_ERROR OCSP_CERT_REVOKED CRL_CERT_REVOKED CRL_MISSING MONITOR_RUNNING_E THREAD_CREATE_E OCSP_NEED_URL OCSP_CERT_UNKNOWN OCSP_LOOKUP_FAIL MAX_CHAIN_ERROR COOKIE_ERROR 315 C 2 CTaoCrypt Error Codes CTaoCrypt error codes can be found in cyassl ctaocrypt error h Error Code Enum Error Error Description Code OPEN_RAN_E opening random device error READ _RAN_E reading random device error 316 WINCRYPT_E CRYPTGEN_E RAN_BLOCK_E BAD_MUTEX_E MP_INIT_E MP_READ_E MP_EXPTMOD_E MP_TO_E MP_SUB_E MP_ADD_E MP_MUL_E MP_MULMOD_E MP_MOD_E MP_INVMOD_E MP_CMP_E MP_ZERO_E MEMORY_E RSA_WRONG_TYPE_E RSA_BUFFER_E BUFFER_E ALGO_ID_E PUBLIC_KEY_E DATE_E SUBJECT_E ISSUER_E CA_TRUE_E EXTENSIONS E ASN_PARSE_E 317 ASN_VERSION_E ASN_GETINT_E ASN_RSA_KEY_E ASN_OBJECT_ID_E ASN_TAG_NULL_E ASN_EXPECT_0_E ASN_BITSTR_E
83. ROR will be returned if an error occurred To get a more detailed error code call CyaSSL_get_error Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new Example int ret 0 int err 0 CYASSL ssl char buffer 80 ret CyaSSL_ connect ssl if ret SSL SUCCESS err CyaSSL get_error ssl ret printf error d s n err CyaSSL_ ERR error string err buffer See Also CyaSSL_get_error 242 CyaSSL_accept CyaSSL_connect_cert Synopsis include lt cyassl ssl h gt int CyaSSL_connect_cert CYASSL ssl Description This function is called on the client side and initiates an SSL TLS handshake with a server only long enough to get the peer s certificate chain When this function is called the underlying communication channel has already been set up CyaSSL_connect_cert works with both blocking and non blocking I O When the underlying I O is non blocking CyaSSL_connect_cert will return when the underlying I O could not satisfy the needs of of CyaSSL_connect_cert to continue the handshake In this case a call to CyaSSL_get_error will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE The calling process must then repeat the call to CyaSSL_connect_cert when the underlying I O is ready and CyaSSL will pick up where it left off When using a non blocking socket nothing needs to be done but select can be used to check for the required condi
84. Receive CYASSL ssl char buf int sz void ctx custom EmbedReceive function See Also CyaSSL_SetlOSend CyaSSL_SetlOReadCtx CyaSSL_SetlOWriteCtx CyaSSL_SetlOSend Synopsis void CyaSSL_SetlOSend CYASSL_CTX ctx CallbacklOSend CBlIOSend typedef int CallbacklOSend char buf int sz void ctx Description This function registers a send callback for CyaSSL to write output data By default CyaSSL uses EmbedSend as the callback which uses the system s TCP send function The user can register a function to send output to memory some other network module or to anywhere Please see the EmbedSend function in src io c as a guide for how the function should work and for error codes In particular 1O_ERR_WANT_WRITE should be returned for non blocking send when the action cannot be taken yet Return Values No return values are used for this function Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new 197 callback function to be registered as the send callback for the CyaSSL context ctx The signature of this function must follow that as shown above in the Synopsis section Example CYASSL_ CTX ctx 0 Receive callback prototype int MyEmbedSend CYASSL ssl char buf int sz void ctx Register the custom receive callback with CyaSSL CyaSSL SetIOSend ctx MyEmbedSend int MyEmbedSend CYASSL ssl char buf int sz void ctx cus
85. S protocol level Example CYASSL_ CTX ctx 0 CYASSL METHOD method fo method CyaSSLv3 client_method if method NULL 169 unable to get method ctx CyaSSL CTX new method if ctx NULL context creation failed See Also CyaSSL_new CyaSSL_CTX_free Synopsis void CyaSSL_CTX_free CYASSL_CTX ctx Description This function frees an allocated CYASSL_CTX object This function decrements the CTX reference count and only frees the context when the reference count has reached 0 Return Values No return values are used for this function Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new Example CYASSL_ CTX ctx 0 CyaSSL CTX _ free ctx See Also CyaSSL_CTX_new CyaSSL_new CyaSSL_free CyaSSL_SetVersion 170 Synopsis include lt cyassl ssl h gt int CyaSSL_SetVersion CYASSL ssl int version Description This function sets the SSL TLS protocol version for the specified SSL session CYASSL object using the version as specified by version This will override the protocol setting for the SSL session ssl originally defined and set by the SSL context CyaSSL_CTX_new method type Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG will be returned if the input SSL object is NULL or an incorrect protocol version is given for version Parameters ssl a pointer to a CYASSL structure c
86. SSL Init if ret SSL SUCCESS failed to initialize CyaSSL library See Also CyaSSL_Cleanup CyaSSL_library_init Synopsis include lt cyassl ssl h gt int CyaSSL_library_init void Description This function is done internally in CyaSSL_CTX_new This function is a wrapper around CyaSSL_Init and exists for OpenSSL compatibility SSL_library_init when CyaSSL has been compiled with OpenSSL compatibility layer CyaSSL_Init is the more typically used CyaSSL initialization function Return Values If successful the call will return SSL_SUCCESS SSL_FATAL_ERROR is returned upon failure Parameters This function takes no parameters 130 Example int ret 0 ret CyaSSL library init if ret SSL SUCCESS failed to initialize CyaSSL See Also CyaSSL_Init CyaSSL_Cleanup CyaSSL_Cleanup Synopsis include lt cyassl ssl h gt void CyaSSL_Cleanup void Description Un initializes the CyaSSL library from further use Doesn t have to be called though it will free any resources used by the library Return Values No return value for this function Parameters There are no parameters for this function Example CyaSSL Cleanup See Also CyaSSL_Init CyaSSL_shutdown 131 Synopsis include lt cyassl ssl h gt int CyaSSL_shutdown CYASSL ssl Description This function shuts down an active SSL TLS connection using the SSL session ssl This func
87. SSL TLS needs 4 3 Cipher Support 4 3 1 Cipher Suite Strength and Choosing Proper Key Sizes To see what ciphers are currently being used you can call the method CyaSSL_get_ciphers This function will return the currently enabled cipher suites Cipher suites come in a variety of strengths Because they are made up of several different types of algorithms authentication encryption and message authentication code MAC the strength of each varies with the chosen key sizes There can be many methods of grading the strength of a cipher suite the specific method used seems to vary between different projects and companies an can include 45 things such as symmetric and public key algorithm key sizes type of algorithm performance and known weaknesses NIST National Institute of Standards and Technology makes recommendations on choosing an acceptable cipher suite by providing comparable algorithm strengths for varying key sizes of each The strength of a cryptographic algorithm depends on the algorithm and the key size used The NIST Special Publication SP800 57 states that two algorithms are considered to be of comparable strength as follows two algorithms are considered to be of comparable strength for the given key sizes X and Y if the amount of work needed to break the algorithms or determine the keys with the given key sizes is approximately the same using a given resource The security strength of an algor
88. SSL download and specifically for this tutorial they can be found in the finished_src folder 117 For production applications you should obtain correct and legitimate certificates from a trusted certificate authority 11 14 Conclusion This tutorial walked through the process of integrating the CyaSSL embedded SSL 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 CyaSSL embedded SSL library provides all the features you would need in a compact and efficient package that has been optimized for both size and speed Being dual licensed under GPLv2 and standard commercial licensing you are free to download the CyaSSL source code directly from our website Feel free to post to our support forums www wolfssl com forums with any questions or comments you might have If you would like more information about our products please contact info yassl com 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 support wolfssl com 118 Chapter 12 Best Practices for Embedded Devices 12 1 Creating Private Keys Embedding a private key into firmware allows anyone to extract the key and turns an otherwise secure connection into something nothing more secure than TCP
89. SSL_get_keys or PSK hints When the user is done with temporary arrays either CyaSSL_FreeArrays may be called to free the resources immediately or alternatively the resources will be freed when the associated SSL object is freed Return Values This function has no return value Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new Example CYASSL ssl E E saul See Also CyaSSL_FreeArrays CyaSSL_FreeArrays Synopsis include lt cyassl ssl h gt void CyaSSL_FreeArrays CYASSL ssl 153 Description Normally at the end of the SSL handshake CyaSSL frees temporary arrays If CyaSSL_KeepArrays has been called before the handshake CyaSSL will not free temporary arrays This function explicitly frees temporary arrays and should be called when the user is done with temporary arrays and does not want to wait for the SSL object to be freed to free these resources Return Values This function has no return value Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new Example CYASSL ssl CyaSSL FreeArrays ssl See Also CyaSSL_KeepArrays 17 3 Context and Session Setup The functions in this section have to do with creating and setting up SSL TLS context objects CYASSL_CTX and SSL TLS session objects CYASSL CyaSSLv3_client_method Synopsis include lt cyassl ssl h gt CYASSL_METHOD CyaSSLv3_client_method void Description 154
90. TX_new Return Values 161 If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method CYASSL CTX ctx method CyaTLSv1 1 client _method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_client_method CyaTLSv1_client_method CyaTLSv1_2_client_method CyaDTLSv1_client_method CyaSSLv23_client_method CyaSSL_CTX_new CyaTLSv1_1_server_method Synopsis CYASSL_METHOD CyaTLSv1_1_server_method void Description The CyaTLSv1_1_server_method function is used to indicate that the application is a server and will only support the TLS 1 1 protocol This function allocates memory for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values 162 If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method CYASSL CTX ctx method CyaTLSvl_1 server _method if method NULL unable to get method
91. T_NAME 0 options a bitwise semaphore with the chosen options The available options are enum CYASSL_SNI_CONTINUE_ON_MISMATCH 0x01 CYASSL_SNI_ANSWER_ON_MISMATCH 0x02 Normally the server will abort the handshake by sending a fatal level unrecognized_name 112 alert if the hostname provided by the client mismatch with the servers CYASSL_SNI_CONTINUE_ON_MISMATCH With this option set the server will not send a SNI response instead of aborting the session CYASSL_SNI_LANSWER_ON_MISMATCH With this option set the server will send a SNI response as if the host names match instead of aborting the session Example int ret 0 CYASSL_ CTX ctx 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ret CyaSSL CTX _UseSNI ctx 0 www yassl com strlen www yassl com if ret 0 sni usage failed CyaSSL_CTX_SNI_ SetOptions ctx CYASSL_ SNI_ HOST NAME CYASSL_ SNI CONTINUE ON MISMATCH 293 See Also CyaSSL_CTX_new CyaSSL_CTX_UseSNI CyaSSL_SNI_SetOptions CyaSSL_SNI_SetOptions Synopsis include lt cyassl ssl h gt void CyaSSL_SNI_ SetOptions CYASSL ssl unsigned char type unsigned char options Description This function is called on the server side to configure the behavior of the SSL session using Server Name Indication in the SSL object passed in the ssl parameter The options are explained below Return Values This function
92. TimeoutCallBack TimeoutlInfo typedef struct timeval Timeval typedef struct handShakeInfo st char cipherName MAX CIPHERNAME SZ 1 negotiated name char 199 packetNames MAX PACKETS HANDSHAKE MAX PACKETNAME SZ 1 SSL packet names int numberPackets actual of packets int negotiationError cipher parameter err HandShakelInfo typedef struct timeoutInfo st char timeoutName MAX TIMEOUT NAME SZ 1 timeout Name int flags for future use int numberPackets actual of packets PacketInfo packets MAX PACKETS HANDSHAKE list of packets Timeval timeoutValue timer that caused it TimeoutInfo typedef struct packetInfo st char packetName MAX PACKETNAME SZ 1 SSL name xy Timeval timestamp when it occured unsigned char value MAX VALUE SZ if fits it s here unsigned char bufferValue otherwise here non 0 a int valueSz sz of value or buffer ny PacketInfo Description CyaSSL_connect_ex is an extension that allows a HandShake Callback to be set This can be useful in embedded systems for debugging support when a debugger isn t 200 available and sniffing is impractical The HandShake Callback will be called whether or not a handshake error occurred No dynamic memory is used since the maximum number of SSL packets is known Packet names can be accessed t
93. YASSL CTX ctx method CyaDTLSv1_client_method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_client_method CyaTLSv1_client_method CyaTLSv1_1_client_method CyaTLSv1_2_client_method CyaSSLv23_client_method CyaSSL_CTX_new CyaDTLSv1_server_method Synopsis include lt cyassl ssl h gt CYASSL_METHOD CyaDTLSv1_server_method void Description The CyaDTLSv1_server_method function is used to indicate that the application is a server and will only support the DTLS 1 0 protocol This function allocates memory for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new 166 Return Values If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method CYASSL CTX ctx method CyaDTLSvl_ server method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_server_method CyaTLSv1_server_method CyaTLSv1_1_server_method CyaTLSv1_2_ server_method CyaSSLv23_server_method CyaSSL_CTX_new CyaSSL_new Synopsis include lt cyassl ssl h gt CYASSL CyaSSL_new CYASSL_CTX ctx Description This functio
94. _GetEccSignCtx CYASSL Description Allows caller to retrieve the Public Key Ecc Signing Callback Context previously stored with CyaSSL_SetEccSignCtx Return Values If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetEccSignCb CyaSSL_SetEccSignCtx CyaSSL_CTX_SetEccVerifyCb Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetEccVerifyCb CYASSL_CTX CallbackEccVerify typedef int CallbackEccVerify CYASSL ssl const unsigned char sig unsigned int sigSz const unsigned char hash unsigned int hashSz 210 const unsigned char keyDer unsigned int keySz int result void ctx Description Allows caller to set the Public Key Callback for ECC Verification The callback should return O for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience sig is the signature to verify and sigSz denotes the length of the signature hash is an input buffer containing the digest of the message and hashSz denotes the length in bytes of the hash result is an output variable where the result of the verification should be stored 1 for success and 0 for failure keyDer is the ECC Private key in ASN1 format and keySz is the length of the key in bytes An example callback can be found cyassl test h myEccVerify Return Values NA See Also CyaSSL_SetEccVerifyCtx CyaSSL_GetEccVerifyCtx
95. _WITH_NULL_SHA TLS_PSK_WITH AES 256 _CBC_SHA TLS _PSK_WITH AES 128 CBC_SHA256 TLS_PSK_WITH AES 128 CBC_SHA TLS_PSK_WITH_NULL_SHA256 TLS_PSK_WITH_NULL_SHA SSL_RSA_WITH_RC4_128 SHA SSL_RSA_WITH_RC4_128 MD5 SSL_RSA_WITH_3DES_EDE_CBC_SHA Copyright 2014 wolfSSL Inc All rights reserved 48 TLS_ECDHE_RSA_WITH AES 256 CBC_SHA TLS _ECDHE_ RSA WITH AES 128 CBC_SHA TLS _ECDHE_ ECDSA _WITH_AES 256 CBC_SHA TLS_ECDHE ECDSA WITH AES 128 CBC_SHA TLS_ECDHE_RSA_WITH_RC4_128 SHA TLS_ECDHE_ ECDSA _WITH_RC4_128 SHA TLS _ECDHE_RSA_WITH_3DES EDE_CBC_SHA TLS_ECDHE_ ECDSA _WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_ AES 128 CBC_SHA256 TLS_ECDHE_ ECDSA _WITH_AES 128 CBC_SHA256 TLS ECDHE_RSA WITH AES 256 CBC_SHA384 TLS _ECDHE_ ECDSA _WITH_AES 256 CBC_SHA384 ECC cipher suites TLS_ECDH_RSA_WITH_AES 256 CBC_SHA TLS _ECDH_RSA_WITH_AES 128 CBC_SHA TLS _ECDH ECDSA _WITH_AES 256 CBC_SHA TLS _ECDH ECDSA _WITH_ AES 128 CBC_SHA TLS_ECDH_RSA_WITH_RC4_128 SHA TLS_ECDH ECDSA _WITH_RC4_128 SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS _ECDH ECDSA_WITH_3DES_EDE _CBC_SHA TLS _ECDH_RSA_WITH_AES 128 CBC_SHA256 TLS_ECDH ECDSA _WITH_ AES 128 CBC_SHA256 TLS _ECDH_RSA_WITH_AES 256 CBC_SHA384 TLS _ECDH ECDSA _WITH_ AES 256 CBC_SHA384 Static ECDH cipher suites TLS_RSA_WITH_HC_128 CBC_MD5 TLS_RSA_WITH_HC_ 128 CBC_SHA TLS_RSA_WITH_RABBIT_CBC_SHA CyaSSL extension eSTREAM cipher suites TLS_NTRU_RSA_WITH_RC4_128 SHA TLS _NTRU_RSA_WITH_3DES EDE_CBC_SHA CyaSSL extens
96. aDecCb CyaSSL_GetRsaDecCtx CyaSSL_GetRsaDecCtx 218 Synopsis include lt cyassl ssl h gt void CyaSSL_GetRsaDecCtx CYASSL Description Allows caller to retrieve the Public Key RSA Private Decrypt Callback Context previously stored with CyaSSL_SetRsaDecCtx Return Values If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetRsaDecCb CyaSSL_SetRsaDecCtx 17 5 Error Handling and Debugging The functions in this section have to do with printing and handling errors as well as enabling and disabling debugging in CyaSSL CyaSSL_ERR_error_string Synopsis include lt cyassl ssl h gt char CyaSSL_ERR_error_string unsigned long errNumber char data Description This function converts an error code returned by CyaSSL_get_error into a more human readable error string errNumber is the error code returned by CyaSSL_get_error and data is the storage buffer which the error string will be placed In The maximum length of data is 80 characters by default as defined by 219 MAX_ERROR_SZ is cyassl ctaocrypt error h Return Values On successful completion this function returns the same string as is returned in data Upon failure this function returns a string with the appropriate failure reason Parameters errNumber error code returned by CyaSSL_get_error data output buffer containing human readable erro
97. age and speeds up public key operations If you are having trouble building on 32 bit platform with fastmath disable shared libraries so that PIC isn t hogging a register also see notes in the README configure enable fastmath disable shared make clean make Note doing a make clean is good practice with CyaSSL when switching configure options By default fastmath tries to use assembly optimizations if possible If assembly optimizations don t work you can still use fastmath without them by adding TFM_NO_ASM to CFLAGS when building CyaSSL configure enable fastmath CFLAGS DTFM NO ASM Using fasthugemath can try to push fastmath even more for users who are not running on embedded platforms configure enable fasthugemath With the default CyaSSL build we have tried to find a good balance between memory usage and performance If you are more concerned about one of the two please refer back to Chapter 2 for additional CyaSSL configuration options Bulk Transfers CyaSSL by default uses 128 byte I O buffers since about 80 of SSL traffic falls within this size and to limit dynamic memory use It can be configured to use 16K buffers the maximum SSL size if bulk transfers are required 35 3 7 3 Benchmarking on Embedded Systems There are several build options available to make building the benchmark application on an embedded system easier These include BENCH_EMBEDDED enabling this define w
98. ake2bFinal to retrieve the final hash byte digest 64 byte input 64 fill input with data to hash Blake2b b2b InitBlake2b amp b2b 64 vo lake2bUpdate amp b2b input sizeof input lake2bFinal amp b2b digest 64 vo The second parameter to InitBlake2b should be the final digest size digest now contains the digest of the hashed data in buffer Example usage can be found in the CTaoCrypt test application ctaocrypt test test c inside the blake2b_test function 10 1 5 RIPEMD 160 To use RIPEMD 160 include the header cyassl ctaocrypt ripemd h The structure to use is RipeMd which is a typedef Before using the hash initialization must be done with the InitRipeMd call Use RipeMdUpdate to update the hash and RipeMdFinal to retrieve the final hash 88 byte ripeMdSum RIPEMD DIGEST SIZE byte buffer 1024 111 buffer with data to hash RipeMd ripemd InitRipeMd amp ripemd RipeMdUpdate amp ripemd buffer sizeof buffer can be called again and again RipeMdFinal amp ripemd ripeMdSum ripeMdSum now contains the digest of the hashed data in buffer 10 2 Keyed Hash Functions 10 2 1 HMAC CTaoCrypt currently provides HMAC for message digest needs The structure Hmac is found in the header cyassl ctaocrypt hmac h HMAC initialization is done with HmacSetKey 5 different types are supported wit
99. akes porting into software that uses writev easier Return Values gt 0 the number of bytes written upon success 0 will be returned upon failure Call CyaSSL_get_error for the specific error code MEMORY_ERROR will be returned if a memory error was encountered SSL_FATAL_ERROR will be returned upon failure when either an error occurred or when using non blocking sockets the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_write again Use CyaSSL_get_error to get a specific error code Parameters ssl pointer to the SSL session created with CyaSSL_new iov array of I O vectors to write iovent number of vectors in iov array 258 Example CYASSL ssl 0 char bufA hello n char bufB hello world n int iovent struct iovec iov 2 iov 0 iov_base buffA iov 0 iov_len strlen buffA iov 1 iov_base buffB iov 1 iov_len strlen buffB iovent 2 ret CyaSSL writev ssl iov iovent wrote ret bytes or error if lt 0 See Also CyaSSL_write 17 9 DTLS Specific The functions in this section are specific to using DTLS with CyaSSL CyaSSL_dtls Synopsis include lt cyassl ssl h gt int CyaSSL_dtls CYASSL ssl Description This function is used to determine if the SSL session has been configured to use DTLS Return Values If the SSL session ssl has been con
100. allback Context previously stored with CyaSSL_SetRsaEncCtx Return Values If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetRsaEncCb CyaSSL_SetRsaEncCtx CyaSSL_CTX_SetRsaDecCb Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetRsaDecCb CYASSL_CTX CallbackRsaDec typedef int CallbackRsaDec CYASSL ssl unsigned char in unsigned int inSz unsigned char out const unsigned char keyDer unsigned int keySz 217 void ctx Description Allows caller to set the Public Key Callback for RSA Private Decrypt The callback should return the number of plaintext bytes for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience in is the input buffer to decrypt and inSz denotes the length of the input out should be set to the beginning of the decryption buffer after the decryption process and any padding keyDer is the RSA Private key in ASN1 format and keySz is the length of the key in bytes An example callback can be found cyassl test h myRsaDec Return Values NA See Also CyaSSL_SetRsaDecCtx CyaSSL_GetRsaDecCtx CyaSSL_SetRsaDecCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetRsaDecCtx CYASSL void ctx Description Allows caller to set the Public Key RSA Private Decrypt Callback Context to ctx Return Values NA See Also CyaSSL_CTX_SetRs
101. allback for RSA Verification The callback should return the number of plaintext bytes for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience sig is the signature to verify and sigSz denotes the length of the signature out should be set to the beginning of the verification buffer after the decryption process and any padding keyDer is the RSA Public key in ASN1 format and keySz is the length of the key in bytes An example callback can be found cyassl test h myRsaVerify Return Values NA See Also CyaSSL_SetRsaVerifyCtx CyaSSL_GetRsaVerifyCtx 214 CyaSSL_SetRsaVerifyCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetRsaVerifyCtx CYASSL void ctx Description Allows caller to set the Public Key RSA Verification Callback Context to ctx Return Values NA See Also CyaSSL_CTX_SetRsaVerifyCb CyaSSL_GetRsaVerifyCtx CyaSSL_GetRsaVerifyCtx Synopsis include lt cyassl ssl h gt void CyaSSL_GetRsaVerifyCtx CYASSL Description Allows caller to retrieve the Public Key RSA Verification Callback Context previously stored with CyaSSL_SetRsaVerifyCtx Return Values If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetRsaVerifyCb CyaSSL_SetRsaVerifyCtx CyaSSL_CTX_SetRsaEncCb 215 Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetRsaEncCb CY
102. alled Poly1305 pmac byte key 32 fill key with keying material byte buffer 2048 fill buffer with data to digest byte pmacDigest 16 Ww Poly1305SetKey amp pmac key sizeof key 05Update amp pmac buffer sizeof buffer 05Final amp pmac pmacDigest 09 Poly Ww Polyl pmacDigest now contains the digest of the hashed data in buffer 10 3 Block Ciphers 10 3 1 AES CTaoCrypt provides support for AES with key sizes of 16 bytes 128 bits 24 bytes 192 bits or 32 bytes 256 bits Supported AES modes include CBC CTR GCM and CCM 8 90 CBC mode is supported for both encryption and decryption and is provided through the AesSetKey AesCbcEncrypt and AesCbcDecrypt functions Please include the header cyassl ctaocrypt aes h to use AES AES has a block size of 16 bytes and the IV should also be 16 bytes Function usage is usually as follows Aes enc Aes dec const byte key some 24 byte key const byte iv some 16 byte iv byte plain 32 an increment of 16 fill with data byte cipher 32 encrypt AesSetKey amp enc key sizeof key iv AES ENCRYPTION f plain AesCbcEncrypt amp enc cipher plain sizeot cipher now contains the cipher text from the plain text decrypt AesSetKey amp dec key sizeof key iv AES DECRYPTION AesCbcDecrypt amp dec plain cipher sizeof cip
103. ameter It means that the Maximum Fragment Length extension will be sent on ClientHello by CyaSSL clients Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned in one of these cases ssl is NULL mfl is out of range MEMORY_E is the error returned when there is not enough memory Parameters 300 ssl pointer to a SSL object created with CyaSSL_new mfl indicates witch is the Maximum Fragment Length requested for the session The available options are enum CYASSL_MFL_2 9 1 512 bytes CYASSL_MFL_2 10 2 1024 bytes CYASSL_MFL_2 11 3 2048 bytes CYASSL_MFL_2 12 4 4096 bytes CYASSL_MFL_2_13 5 8192 bytes CyaSSL ONLY Example int ret 0 CYASSL_ CTX ctx 0 CYASSL ssl 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ssl CyaSSL_new ctx if ssl NULL ssl creation failed ret CyaSSL UseMaxFragment ssl CYASSL MFL 2 11 if ret 0 max fragment usage failed See Also CyaSSL_new CyaSSL_CTX_UseMaxFragment CyaSSL_CTX_UseTruncatedHMAC 301 Synopsis include lt cyassl ssl h gt int CvaSSL_CTX_UseTruncatedHMAC CYASSL_CTX ctx Description This function is called on the client side to enable the use of Truncated HMAC for SSL objects created from the SSL context passed in the ctx parameter It means that the Truncated
104. and header files need to remain in the same directory structure as they are in the CyaSSL download package 2 Some build systems will want to explicitly know where the CyaSSL header files are located so you may need to specify that They are located in the lt cyassl_root gt cyassl directory Typically you can add the lt cyassl_root gt directory to your include path to resolve header problems 3 CyaSSL defaults to a little endian system unless the configure process detects big endian Since users building in a non standard environment aren t using the configure process BIG_ENDIAN_ORDER will need to be defined if using a big endian system 4 CyaSSL benefits speed wise from having a 64 bit type available The configure process determines if long Or long long is 64 bits and if so sets up a define So if sizeof long is 8 bytes on your system define SIZEOF_LONG 8 If it isn t but sizeof long long is 8 bytes then define SZZEOF_LONG_LONG 8 5 Try to build the library and let us know if you run into any problems If you need help contact us at info wolfssl com 6 Some defines that can modify the build are listed in the following sub sections below For more verbose descriptions of many options please see section 2 5 1 Build Option Notes 2 4 1 Removing Features The following defines can be used to remove features from CyaSSL This can be helpful if you are trying to reduce the overall library footprint size In addit
105. and is an update to TLS 1 0 The major changes are e The Implicit Initialization Vector IV is replaced with an explicit IV to protect 310 against Cipher block chaining CBC attacks e Handling of padded errors is changed to use the bad_record_mac alert rather than the decryption_failed alert to protect against CBC attacks e IANA registries are defined for protocol parameters e Premature closes no longer cause a session to be non resumable TLS 1 2 This protocol was defined in RFC 5246 in August of 2008 Based on TLS 1 1 TLS 1 2 contains improved flexibility The major differences include e The MD5 SHA 1 combination in the pseudorandom function PRF was replaced with cipher suite specified PRFs e The MDS5 SHA 1 combination in the digitally signed element was replaced with a single hash Signed elements include a field explicitly specifying the hash algorithm used e There was substantial cleanup to the client s and server s ability to specify which hash and signature algorithms they will accept Addition of support for authenticated encryption with additional data modes TLS Extensions definition and AES Cipher Suites were merged in Tighter checking of EncryptedPreMasterSecret version numbers Many of the requirements were tightened Verify_data length depends on the cipher suite Description of Bleichenbacher Dlima attack defenses cleaned up Appendix B RFCs Specifications and Reference B 1 Protocols
106. and much more all provided under a very easy to use license model The points below outline several of the main differences between CyaSSL and OpenSSL 1 With a 20 100 kB build size CyaSSL is up to 20 times smaller than OpenSSL CyaSSL is a better choice for resource constrained environments where every byte matters 2 CyaSSL is up to date with the most current standards of TLS 1 2 with DTLS The yaSSL team is dedicated to continually keeping CyaSSL up to date with current 121 standards CyaSSL offers the best current ciphers and standards available today including ciphers for streaming media support In addition the recently introduced NTRU cipher allows speed increases of 20 200x over standard RSA CyaSSL is dual licensed under both the GPLv2 as well as a commercial license where OpenSSL is available only under their unique license from multiple sources CyaSSL is backed by an outstanding company who cares about its users and about their security and who actively works to improve and expand CyaSSL The yaSSL team is based in Bozeman MT Portland OR and Seattle WA and is always willing to help CyaSSL is the leading SSL library for real time mobile and embedded systems by virtue of its breadth of platform support and successful implementations on embedded environments Chances are we ve already been ported to your environment If not let us know and we ll be glad to help CyaSSL offers several ab
107. are used for this function Parameters ssl pointer to the SSL session created with CyaSSL_new flags value of the I O read flags for the specified SSL session ssl Example CYASSL ssl 0 Manually setting recv flags to 0 CyaSSL_ SetIOReadFlags ssl 0 194 See Also CyaSSL_SetlORecv CyaSSL_SetlOSend CyaSSL_SetlOReadCtx CyaSSL_SetlOWriteFlags Synopsis void CyaSSL_SetlOWriteFlags CYASSL ssl int flags Description This function sets the flags for the send callback to use for the given SSL session The send callback could be either the default CyaSSL EmbedSend callback or a custom callback specified by the user see CyaSSL_SetlOSend The default flag value is set internally by CyaSSL to the value of 0 The default CyaSSL send callback uses the send function to send data from the socket From the send man page The flags parameter may include one or more of the following define MSG_OOB 0x1 process out of band data define MSG_DONTROUTE 0x4 bypass routing use direct interface The flag MSG_OOB is used to send out of band data on sockets that support this notion e g SOCK_STREAM the underlying protocol must also support out of band data MSG_DONTROUTE is usually used only by diagnostic or routing programs Return Values No return values are used for this function Parameters ssl pointer to the SSL session created with CyaSSL_new flags value of the I O
108. ated with CyaSSL_new data buffer where CyaSSL_read will place data read sz number of bytes to read into data Example CYASSL ssl 0 char reply 1024 input CyaSSL_ read ssl reply sizeof reply if input gt 0 input number of bytes returned into buffer reply 252 See CyaSSL examples client server echoclient echoserver for more complete examples of CyaSSL_read See Also CyaSSL_recv CyaSSL_write CyaSSL_peek CyaSSL_pending CyaSSL_recv Synopsis include lt cyassl ssl h gt int CyaSSL_recv CYASSL ssl void data int sz int flags Description This function reads sz bytes from the SSL session ssl internal read buffer into the buffer data using the specified flags for the underlying recv operation The bytes read are removed from the internal receive buffer This function is identical to CyaSSL_read except that it allows the application to set the recv flags for the underlying read operation If necessary CyaSSL_recv will negotiate an SSL TLS session if the handshake has not already been performed yet by CyaSSL_connect or CyaSSL_accept The SSL TLS protocol uses SSL records which have a maximum size of 16kB the max record size can be controlled by the MAX_RECORD_SIZE define in lt cyassl_root gt cyassl internal h As such CyaSSL needs to read an entire SSL record internally before it is able to process and decrypt the record Because of this a call to
109. ation typedef struct Cert int version x509 version byte serial CTC SERIAL SLZE serial number int sigType signature algo type CertName issuer issuer info int daysValid validity days int selfSigned self signed flag CertName subject subject info int isCA is this going to be a CA TT Cert Where CertName looks like typedef st char count ch ch ch ch ch ch ch ch ch ch ch ch ch ch es ar ar ak ar ar ar ar ar ar ak ar ar ar ar truct CertName try CTC NAME SIZE countryEnc state CTC_NAME SIZE stateEnc locality CTC_NAME SIZE localityEnc sur CTC_NAME SIZE surEnc org CTC_NAME SIZE orgEnc unit CTC NAME SIZE unitEnc commonName CTC NAME SIZE commonNameEnc email CTC NAME SIZE email has to be last CertName Before filling in the subject information an initialization function needs to be called like this Cer Init t myCert tCert amp myCert InitCert sets defaults for some of the variables including setting the version to 3 0x02 the serial number to 0 randPomly generated the sigType to CTC_SHAWRSA the daysValid to 500 and selfSigned to 1 TRUE Supported signature types include QAaaqgaaqgaaQqaadadaadan TC SHAwDSA TC_MD2wRSA TC_MDSwRSA TC_SHAwWRSA TC_SHAWECDSA TC_SHA256wRSA TC_SHA256wECDSA
110. basically allowing 200 new sessions per minute or so hugecache enabling the huge session cache will increase the session cache size to 65 791 sessions This option is for servers that are under heavy load over 13 000 new sessions per minute are possible or over 200 new sessions per second smallcache enabling the small session cache will cause CyaSSL to only store 6 sessions This may be useful for embedded clients or systems where the default of nearly 3kB is too much RAM This define uses less than 500 bytes of RAM savesession enabling this option will allow an application to persist Save and restore the CyaSSL session cache to from memory buffers 19 savecert enabling this option will allow an application to persist save and restore the CyaSSL certificate cache to from memory buffers atomicuser enabling this option will turn on User Atomic Record Layer Processing callbacks This will allow the application to register its own MAC encrypt and decrypt verify callbacks pkcallbacks enabling this option will turn on Public Key callbacks allowing the application to register its own ECC sign verify and RSA sign verify and encrypt decrypt callbacks sniffer enabling sniffer SSL inspection support will allow the collection of SSL traffic packets as well as the ability to decrypt those packets with the correct key file aesgcm enabling AES GCM will add these cipher suites to CyaSSL CyaSSL offers four different implem
111. callback can also be found in my_psk_server_cb in cyassl test h CyaSSL supports identities and hints up to 128 octets and pre shared keys up to 64 octets 4 8 Client Authentication Client authentication is a feature which enables the server to authenticate clients by requesting that the clients send a certificate to the server for authentication when they connect Client authentication requires an X 509 client certificate from a CA or self signed if generated by you or someone other than a CA By default CyaSSL validates all certificates that it receives this includes both client and server To set up client authentication the server must load the list of trusted CA certificates to be used to verify the client certificate against CyaSSL CTX load verify locations ctx caCert 0 To turn on client verification and control its behavior the CyaSSL_CTX_set_verify function is used In the following example SSL_VERIFY_PEER turns on a certificate request from the server to the client SSL_VERIFY_FAIL_IF_NO_PEER_CERT 59 instructs the server to fail if the client does not present a certificate to validate on the server side Other options to CyaSSL_CTX_set_verify include SSL_VERIFY_NONE and SSL_VERIFY_CLIENT_ONCE CyaSSL CTX set _verify ctx SSL VERIFY PEER SSL_ VERIFY FAIL IF NO PEER CERT 0 An example of client authentication can be found in the example server server c included in the CyaSSL download examp
112. cate common name hash public key and key type etc If B is valid then it is used to verify C Following this model as long as root cert A has been loaded as a trusted root into the CyaSSL server the server certificate chain will still be able to be verified if the server sends A gt B gt C or B gt C If the server just sends C and not the intermediate certificate the chain will not be able to be verified unless the CyaSSL client has already loaded B as a trusted root 7 4 Domain Name Check for Server Certificates CyaSSL has an extension on the client that automatically checks the domain of the server certificate In OpenSSL mode nearly a dozen function calls are needed to perform this CyaSSL checks that the date of the certificate is in range verifies the signature and additionally verifies the domain if you call CyaSSL_ check domain name CYASSL ssl const char dn before calling CyaSSL_connect CyaSSL will match the X509 issuer name of peer s server certificate against dn the expected domain name If the names match CyaSSL_connect will proceed normally however if there is a name mismatch CyaSSL_connect will return a fatal error and CyaSSL_get_error will return DOMAIN_NAME_MISMATCH Checking the domain name of the certificate is an important step that verifies the server is actually who it claims to be This extension is intended to ease the burden of performing the check 7 5 No File System and u
113. cer and cannot be viewed with a text editor 7 2 Certificate Loading Certificates are normally loaded using the file system although loading from memory buffers is supported as well see section 7 5 7 2 1 Loading CA Certificates CA certificate files can be loaded using the CyaSSL_CTX_load_verify_locations function int CyaSSL_ CTX load verify locations CYASSL CTX ctx const char CAfile const char CApath CA loading can also parse multiple CA certificates per file using the above function by passing in a CAfile in PEM format with as many certs as possible This makes initialization easier and is useful when a client needs to load several root CAs at startup This makes CyaSSL easier to port into tools that expect to be able to use a single file for CAs 7 2 2 Loading Client or Server Certificates Loading single client or server certificates can be done with the CyaSSL_CTX_use_certificate_file function If this function is used with a certificate chain only the actual or bottom certificate will be sent int CyaSSL_ CTX_use_ certificate file CYASSL CTX ctx const char CAfile int type CAfile is the CA certificate file and type is the format of the certificate such as SSL_FILETYPE_PEM The server and client can send certificate chains using the CyaSSL_CTX_use_certificate_chain_file function The certificate chain file must be in 72 PEM format and must be sorted starting with the subject
114. ch SetKey also takes an IV an initialization vector that is the same size as the key size Usage is usually like the following Des3 enc Des3 dec const byte key some 24 byte key const byte iv some 24 byte iv byte plain 24 an increment of 8 fill with data byte cipher 24 encrypt D s3 5 tKey amp enc key iv DES ENCRYPTION Des3 CbhcEncrypt amp enc cipher plain sizeof plain cipher now contains the cipher text from the plain text decrypt Des3 SetKey amp dec key iv DES DECRYPTION Des3 CbcDecrypt amp dec plain cipher sizeof cipher plain now contains the original plaintext from the cipher text 10 3 3 Camellia CTaoCrypt provides support for the Camellia block cipher To use Camellia include the header cyassl ctaocrypt camellia h The structure you can use is called Camellia Initialization is done through CamelliaSetKey CBC encryption decryption is provided through CamelliaCbcEnrypt and CamelliaCbcDecrypt while direct encryption decryption is provided through CamelliaEncryptDirect and CamelliaDecryptDirect 92 For usage examples please see the camellia_test function in lt cyassl_root gt ctaocrypt test test c 10 4 Stream Ciphers 10 4 1 ARC4 The most common stream cipher used on the Internet is ARC4 CTaoCrypt supports it through the header cyassl ctaocrypt arc4 h Usage is simpler than block ciphers beca
115. code after variable declarations before the call to CyaSSL_Init in the main function Define a signal handler for when the user closes the program with Ctrl C Also turn off SA RESTART so that the OS doesn t restart the call to accept after the signal is handled 116 act sa_handler sig handler sigemptyset amp act sa_mask act sa_flags sigaction SIGINT amp act amp oact The echoserver s sig_handler function is shown below void sig handler const int sig printf nSIGINT handled n cleanup 1 return That s it the echoclient and echoserver are now enabled with TLSv1 2 What we did e Included the CyaSSL headers e Initialized CyaSSL e Created a CYASSL_CTX structure in which we chose what protocol we wanted to use e Created a CYASSL object to use for sending and receiving data e Replaced calls to Writen and Readline with CyaSSL_write and CyaSSL_read e Freed CYASSL CYASSL_CTX e Made sure we handled exiting client and the Ctrl C signal for the server There are many more aspects and methods to configure and control the behavior of your SSL connections For more detailed information please see additional CyaSSL documentation and resources Once again the completed source code can be found in the downloaded ZIP file at the top of the page 11 13 Certificates For testing purposes you may use the certificates provided by CyaSSL These can be found in the Cya
116. connect and associate the file descriptor with the session after connecting to socket fd CYASSL ssl if ssl CyaSSL new ctx NULL fprintf stderr CyaSSL new error n exit EXIT FAI LURE CyaSSL_set_fd ssl fd 7 Error checking Each CyaSSL_read and CyaSSL_write call will return the number of bytes written upon success 0 upon connection closure and 1 for an error just like read and write In the event of an error you can use two calls to get more information about the error char errorString 80 int err CyaSSL get _error ssl 0 CyaSSL_ERR_ error string err errorString If you are using non blocking sockets you can test for errno EAGAIN EWOULDBLOCK or more correctly you can test the specific error code returned by CyaSSL_get_error for SSL_LERROR_WANT_READ or SSL_ERROR_WANT_WRITE 8 Cleanup After each CYASSL object is done being used you can free it up by calling CyaSSL free ssl When you are completely done using SSL TLS altogether you can free the CYASSL_CTX object by calling CyaSSL CTX free ctx CyaSSL Cleanup For an example of a client application using CyaSSL see the client example located in the lt cyassl_root gt examples client c file 38 3 9 Changing a Server Application to Use CyaSSL This section will explain the basic steps needed to add CyaSSL to a server application using the CyaSSL native API For a client explanation please
117. ction are part of CyaSSL s OpenSSL Compatibility Layer These functions are only available when CyaSSL has been compiled with the OPENSSL_EXTRA define CyaSSL_X509_get_serial_number Synopsis include lt cyassl ssl h gt int CyaSSL_X509_get_serial_number CYASSL_X509 x509 unsigned char in int inOutSz 277 Description Retrieves the peer s certificate serial number The serial number buffer in should be at least 32 bytes long and be provided as the inOutSz argument as input After calling the function inOutSz will hold the actual length in bytes written to the in buffer Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG will be returned if a bad function argument was encountered See Also SSL_get_peer_certificate CyaSSL_get_sessionID Synopsis include lt cyassl ssl h gt const unsigned char CyaSSL_get_sessionID const CYASSL_SESSION session Description Retrieves the session s ID The session ID is always 32 bytes long Return Values The session ID See Also SSL_get_session CyaSSL_get_peer_chain Synopsis include lt cyassl ssl h gt X509_ CHAIN CyaSSL_get_peer_chain CYASSL ssl Description 278 Retrieves the peer s certificate chain Return Values If successful the call will return the peer s certificate chain 0 will be returned if an invalid CYASSL pointer is passed to the function See Also CyaSSL_get_chain_count CyaSSL_get_chain_len
118. d Using Certificates Serial Number Retrieval RSA Key Generation Certificate Generation Convert raw ECC key Debugging Debugging and Logging Error Codes Library Design Library Headers Startup and Exit Structure Usage Thread Safety Input and Output Buffers Secure Renegotiation CTaoCrypt Usage Reference Hash Functions Keyed Hash Functions Block Ciphers Stream Ciphers Public Key Cryptography SSL Tutorial Best Practices for Embedded Devices OpenSSL Compatibility Licensing Support and Consulting CyaSSL Updates CyaSSL API Reference Appendix A SSL TLS Overview Appendix B RFCs Specifications and Reference Appendix C Error Codes Chapter 1 Introduction This manual is written as a technical guide to the CyaSSL embedded SSL library It will explain how to build and get started with CyaSSL provide an overview of build options features portability enhancements support and much more Why Choose CyaSSL There are many reasons to choose CyaSSL as your embedded SSL solution Some of the top reasons include size typical footprint sizes range from 20 100 kB support for the newest standards SSL 3 0 TLS 1 0 TLS 1 1 TLS 1 2 DTLS 1 0 and DTLS 1 2 current and progressive cipher support including stream ciphers multi platform royalty free and an OpenSSL compatibility API to ease porting into existing applications which have previously used the OpenSSL package For a complete feature list see Section 4
119. d not be verified ASN_SIG_OID_E will be returned if the signature type is not supported CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked CRL_MISSING is an error that is returned if a current issuer CRL is not available ASN_BEFORE_DATE_E will be returned if the current date is before the before date ASN_AFTER_DATE_E will be returned if the current date is after the after date SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY_E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file BAD_FUNC_ARG is the error that will be returned if a pointer is not provided Parameters cm a pointer toa CYASSL_CERT_MANAGER structure created using CyaSSL_CertManagerNew 276 buff buffer containing the certificates to verify sz size of the buffer buf format format of the certificate to verify located in buf either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int ret 0 int sz 0 CYASSL_CERT MANAGER cm byte certBuff ret CyaSSL CertManagerVerifyBuffer cm certBuff sz SSL FILETYPE PEM if ret SSL SUCCESS error verifying certificate See Also CyaSSL_CertManagerLoadCA CyaSSL_CertManagerVerify 17 12 OpenSSL Compatibility Layer The functions in this se
120. d porting to embedded systems with no filesystem USE_CERT_BUFFERS_2048 enables 2048 bit test certificate and key buffers located in lt cyassl_root gt cyassl certs_test h Helpful when testing on and porting to embedded systems with no filesystem 2 4 4 Reducing Memory Usage TFM_TIMING_RESISTANT can be defined when using fast math USE_FAST_MATH on systems with a small stack size This will get rid of the large static arrays CYASSL_SMALL_STACK can be used for devices which have a small stack size This increases the use of dynamic memory in ctaocrypt src integer c but can lead to slower performance 2 4 5 Increasing Performance CYASSL_AESNI enables use of AES accelerated operations which are built into some Intel chipsets When using this define the aes_asm s file must be added to the CyaSSL build sources USE_FAST_MATH switches the big integer library to a faster one that uses assembly if possible fastmath will speed up public key operations like RSA DH and DSA The big integer library is generally the most portable and generally easiest to get going with but the negatives to the normal big integer library are that it is slower and it uses a lot of dynamic memory Because the stack memory usage can be larger when using fastmath we recommend defining TFM_TIMING_ RESISTANT as well when using this option 2 4 6 Stack or Chip Specific Defines CyaSSL can be built for a variety of platforms and TCP IP stacks The following defines
121. d using it by calling CyaSSL_set_compression While compressing data before sending decreases the actual size of the messages being sent and received the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks 2 6 Cross Compiling Many users on embedded platforms cross compile CyaSSL for their environment The easiest way to cross compile the library is to use the configure system It will generate a Makefile which can then be used to build CyaSSL When cross compiling you ll need to specify the host to configure such as configure host arm linux You may also need to specify the compiler linker etc that you want to use configure host arm linux CC arm linux gcc AR arm linux ar RANLIB arm linux There is a bug in the configure system which you might see when cross compiling and detecting user overriding malloc If you get an undefined reference to rpl_malloc and or rpl_realloc please add the following to your configure line ac cv func malloc 0 nonnull yes ac _ cv func realloc_ 0 nonnull yes 23 After correctly configuring CyaSSL for cross compilation you should be able to follow standard autoconf practices for building and installing the library make sudo make install If you have any additional tips or feedback about cross compiling CyaSSL please let us know at info wolfssl com Chapter 3 Getting Started
122. derBuffer Example int derSz byte derBuf derSz CyaSSL PemCertToDer cert pem derBuf sizeof derBuf See Also SSL_get_peer_certificate CyaSSL_CTX_use_RSAPrivateKey_file Synopsis include lt cyassl ssl h gt int CvaSSL_CTX_use_RSAPrivateKey_file CYASSL_CTX ctx const char file int format Description This function loads the private RSA key used in the SSL connection into the SSL context CYASSL_CTX This function is only available when CyaSSL has been compiled with the OpenSSL compatibility layer enabled enable opensslExtra define OPENSSL_EXTRA and is identical to the more typically used CyaSSL_CTX_use_PrivateKey_file function The file argument contains a pointer to the RSA private key file in the format specified by format 282 Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned If the function call fails possible causes might include The input key file is in the wrong format or the wrong format has been given using the format argument file doesn t exist can t be read or is corrupted an out of memory condition occurs Parameters ctx a pointer to a CYASSL_CTX structure created using CyaSSL_CTX_new file a pointer to the name of the file containing the RSA private key to be loaded into the CyaSSL SSL context with format as specified by format format the encoding type of the RSA private key s
123. drew Rudoff 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 Examples Used in this Tutorial echoclient Figure 5 4 Page 124 echoserver Figure 5 12 Page 139 Unix Network Programming 101 Volume 1 3rd Edition www unpbook com 11 2 Quick Summary of SSL TLS TLS Transport Layer Security and SSL 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 2 CyaSSL supports SSL 3 0 TLS 1 0 1 1 and 1 2 in addition to DTLS 1 0 and 1 2 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 11 3 Getting the Source Code All of the source code used in this tutorial can be downloaded from the wolfSSL website specifically from the following location The download contai
124. e Threaded enabling single threaded mode turns off multi thread protection of the session cache Only enable single threaded mode if you know your application is single threaded or your application is multithreaded and only one thread at a time will be 17 accessing the library DTLS enabling DTLS support allows users of the library to also use the DTLS protocol in addition to TLS and SSL For more information see Chapter 4 OpenSSL Extra enabling OpenSSL Extra includes a larger set of OpenSSL compatibility functions The basic build will enable enough functions for most TLS SSL needs but if you re porting an application that uses 10s or 100s of OpenSSL calls enabling this will allow better support The CyaSSL OpenSSL compatibility layer is under active development so if there is a function missing which you need please contact us and we ll try to help For more information about the OpenSSL Compatibility Layer please see Chapter 13 IPV6 enabling IPV6 changes the test applications to use IPv6 instead of IPv4 CyaSSL proper is IP neutral either version can be used but currently the test applications are IP dependent IPv4 by default leanpsk Very small build using PSK and eliminating many features from the library Approximate build size for CyaSSL on an embedded system with this enabled is 21kB fastmath enabling fastmath will speed up public key operations like RSA DH and DSA By default CyaSSL uses the normal big i
125. e and initiates an SSL TLS handshake with a server When this function is called the underlying communication channel has already been set up CyaSSL_connect works with both blocking and non blocking I O When the underlying I O is non blocking CyaSSL_connect will return when the underlying I O could not satisfy the needs of of CyaSSL_connect to continue the handshake In this case a call to CyaSSL_get_error will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE The calling process must then repeat the call to CyaSSL_connect when the underlying I O is ready and CyaSSL will pick up where it left off When using a non blocking socket nothing needs to be done but select can 241 be used to check for the required condition If the underlying I O is blocking CyaSSL_connect will only return once the handshake has been finished or an error occurred CyaSSL takes a different approach to certificate verification than OpenSSL does The default policy for the client is to verify the server this means that if you don t load CAs to verify the server you ll get a connect error unable to verify 155 It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling SSL_CTX_set_verify ctx SSL_VERIFY_NONE 0 before calling SSL_new Though it s not recommended Return Values If successful the call will return SSL_SUCCESS SSL_FATAL_ER
126. e com This in turn defines FREESCALE _K70_RNGA to enable support for the Kinetis H W Random Number Generator Accelerator CYASSL_STM32F2 can be defined when building for STM32F2 This define also enables STM32F2 hardware crypto and hardware RNG support in CyaSSL http www st com internet mcu subclass 1520 jsp COMVERGE can be defined if using Comverge settings CYASSL_QL can be defined if using QL SEP settings CYASSL_EROAD can be defined building for EROAD CYASSL_IAR_ARM can be defined if build for IAR EWARM CYASSL_TIRTOS can be defined when building for TI RTOS 2 5 Build Options configure Options The following are options which may be appended to the configure script to customize how the CyaSSL library is built By default CyaSSL only builds in shared mode with static mode being disabled This speeds up build times by a factor of two Either mode can be explicitly disabled or enabled if desired Default Description Value enable debug Disabled Enable CyaSSL debugging support enable singlethreaded Disabled Enable single threaded mode no multi thread protections enable dtls Disabled Enable CyaSSL DTLS support 13 enable opensslextra enable ipv6 enable bump enable leanpsk enable bigcache enable hugecache enable smallcache enable savesession enable savecert enable atomicuser enable pkcallbacks enable sniffer enable aesgcm enable aesccm enable
127. e has become a top priority 119 Examples of embedded connected devices where this requirement was not found in years past include set top boxes DVR s POS systems both VoIP and mobile phones connected home and even automobile based computing systems Because CyaSSL supports the key embedded and real time operating systems encryption standards and authentication functionality it is a natural choice for embedded systems developers to use when adding digital signature functionality Generally the process for setting up code and file signing on an embedded device are as follows 1 The embedded systems developer will generate an RSA key pair 2 A server side script based tool is developed a The server side tool will create a hash of the code to be loaded on the device with SHA 256 for example b The hash is then digitally signed also called RSA private encrypt c A package is created that contains the code along with the digital signature 3 The package is loaded on the device along with a way to get the RSA public key The hash is re created on the device then digitally verified also called RSA public decrypt against the existing digital signature Benefits to enabling digital signatures on your device include 1 Easily enable a secure method for allowing third parties to load files to your device 2 Ensure against malicious files finding their way on to your device Digitally secure firmware updates 4 Ensure against fir
128. e input txt issue examples echoclient echoclient input txt If you want the result to be written out to a file you can specify the output file name as an additional command line argument The following command will echo the contents of file input txt and write the result from the server to output txt examples echoclient echoclient input txt output txt The testsuite program does just that but hashes the input and output files to make sure that the client and server were getting sending the correct and expected results 31 3 7 Benchmark Many users are curious about how the CyaSSL embedded SSL library will perform on a specific hardware device or in a specific environment Because of the wide variety of different platforms and compilers used today in embedded enterprise and cloud based environments it is hard to give generic performance calculations across the board To help CyaSSL users and customers in determining SSL performance for CyaSSL CTaoCrypt a benchmark application is provided which is bundled with CyaSSL CyaSSL uses the CTaoCrypt cryptography library for all crypto operations by default Because the underlying crypto is a very performance critical aspect of SSL TLS our benchmark application runs performance tests on CTaoCrypt s algorithms The benchmark utility located in ctaocrypt benchmark may be used to benchmark the cryptographic functionality of CTaoCrypt Typical output may look like the following in th
129. e like dh1024 der DhKeyDecode tmp amp idx amp dhPublicKey publicKeyBuffer InitRng amp rng Initialize random number generator DhGenerateKeyPair will generate a public and private DH key based on the initial public parameters in dhPublicKey DhGenerateKeyPair amp dhPublickey amp rng privA amp privASz pubA amp pubASz After sideB sends their public key pubB to sideA sideA can then generate the mutually agreed key agreeA using the DhAgree function DhAgree amp dhPublickey agreeA amp agreeASz privA privASz pubB pubBSz Now agreeA holds sideA s mutually generated key of size agreeASz bytes The same process will have been done on sideB For a complete example of Diffie Hellman in CTaoCrypt see the file ctaocrypt test test c 10 5 3 EDH Ephemeral Diffie Hellman A CyaSSL server can do Ephemeral Diffie Hellman No build changes are needed to add this feature though an application will have to register the ephemeral group parameters on the server side to enable the EDH cipher suites A new API can be used to do this 98 int CyaSSL SetTmpDH CYASSL ssl unsigned char p int pSz unsigned char g int gSz The example server and echoserver use this function from SetDH 10 5 4 DSA Digital Signature Algorithm CTaoCrypt provides support for DSA and DSS through the header cyassl ctaocrypt dsa h DSA allows for the creation of a digital signature based on a given data hash
130. e same SSL pointer is not supported CyaSSL could take a more aggressive constrictive stance and lock out other users when a function is entered that cannot be shared but this level of granularity seems counter intuitive All users even single threaded ones will pay for the locking and multi thread ones won t be able to re enter the library even if they aren t sharing objects across threads This penalty seems much too high and CyaSSL leaves the responsibility of synchronizing shared objects in the hands of the user 2 Besides sharing CYASSL pointers users must also take care to completely initialize an CYASSL_CTX before passing the structure to CyaSSL_new The same CYASSL_CTX can create multiple CYASSL structs but the CYASSL_CTX is only read during CyaSSL_new creation and any future or simultaneous changes to the CYASSL_CTX will not be reflected once the CYASSL object is created Again multiple threads should synchronize writing access to a CYASSL_CTX and it is advised that a single thread initialize the CYASSL_CTX to avoid the synchronization and update problem described above 9 5 Input and Output Buffers CyaSSL now uses dynamic buffers for input and output They default to 0 bytes and are controlled by the RECORD_SIZE define in cyassl internal h If an input record is 84 received that is greater in size than the static buffer then a dynamic buffer is temporarily used to handle the request and then freed You can set
131. e that specifies the size of the output buffer upon invocation and the actual size of the signature should be stored there before returning keyDer is 212 the RSA Private key in ASN1 format and keySz is the length of the key in bytes An example callback can be found cyassl test h myRsaSign Return Values NA See Also CyaSSL_SetRsaSignCtx CyaSSL_GetRsaSignCtx CyaSSL_SetRsaSignCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetRsaSignCtx CYASSL void ctx Description Allows caller to set the Public Key RSA Signing Callback Context to ctx Return Values NA See Also CyaSSL_CTX_SetRsaSignCb CyaSSL_GetRsaSignCtx CyaSSL_GetRsaSignCtx Synopsis include lt cyassl ssl h gt void CyaSSL_GetRsaSignCtx CYASSL Description Allows caller to retrieve the Public Key RSA Signing Callback Context previously stored with CyaSSL_SetRsaSignCtx 213 Return Values If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetRsaSignCb CyaSSL_SetRsaSignCtx CyaSSL_CTX_SetRsaVerifyCb Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetRsaVerifyCb CYASSL_CTX CallbackRsaVerify typedef int CallbackRsaVerify CYASSL ssl unsigned char sig unsigned int sigSz unsigned char out const unsigned char keyDer unsigned int keySz void ctx Description Allows caller to set the Public Key C
132. e the client connect try examples client client A certs server ecc pem where A is the CA certificate to use to verify the server 4 3 7 PKCS Support PKCS Public Key Cryptography Standards refers to a group of standards created and published by RSA Security Inc CyaSSL has support for PKCS 5 PKCS 8 and PBKD from PKCS 12 4 3 7 1 PKCS 5 PBKDF1 PBKDF2 PKCS 12 PKCS 5 is a password based key derivation method which combines a password a 53 salt and an iteration count to generate a password based key CyaSSL supports both PBKDF1 and PBKDF2 key derivation functions A key derivation function produces a derived key from a base key and other parameters such as the salt and iteration count as explained above PBKDF1 applies a hash function MD5 SHA etc to derive keys where the derived key length is bounded by the length of the hash function output With PBKDF2 a psudorandom function is applied such as HMAC SHA 1 to derive the keys In the case of PBKDF2 the derived key length is unbounded CyaSSL also supports the PBKDF function from PKCS 12 in addition to PBKDF1 and PBKDF2 The function prototypes look like this int PBKDF2 byte output const byte passwd int plLen const byte salt int sLen int iterations int kLen int hashType int PKCS12 PBKDF byte output const byte passwd int plen const byte salt int sLen int iterations int kLen int hashType int purpose
133. e underlying I O is blocking CyaSSL_write will only return once the buffer data of size sz has been completely written or an error occurred Return Values gt 0 the number of bytes written upon success 0 will be returned upon failure Call CyaSSL_get_error for the specific error code SSL_FATAL_ERROR will be returned upon failure when either an error occurred or when using non blocking sockets the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and the application needs to call CyaSSL_write again Use CyaSSL_get_error to get a specific error code Parameters ssl pointer to the SSL session created with CyaSSL_new data data buffer which will be sent to peer sz size in bytes of data to send to the peer data Example CYASSL ssl 0 char msg 64 hello cyass1 int msgSz int strlen msg int flags int ret ret CyaSSL write ssl msg msgSz if ret lt 0 CyaSSL_ write failed call CyaSSL_ get _error See CyaSSL examples client server echoclient echoserver for more more detailed 257 examples of CyaSSL_write See Also CyaSSL_send CyaSSL_read CyaSSL_recv CyaSSL_writev Synopsis include lt cyassl ssl h gt int CyaSSL_writev CYASSL ssl const struct iovec iov int iovcnt Description Simulates writev semantics but doesn t actually do block at a time because of SSL_write behavior and because front adds may be small M
134. e_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 The code shown above should be added to the beginning of tcpcli01 c and tcpserv04 c 110 after the variable definitions and then check that the user has started the client with an IP address A version of the finished code is included in the SSL tutorial ZIP file for reference Now that CyaSSL and the CYASSL_CTX have been initialized make sure that the CYASSL_CTX object and the CyaSSL 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 main function right before the call to exit CyaSSL_CTX_free ctx CyaSSL_Cleanup 11 10 CYASSL Object EchoClient A CYASSL 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 Connect shown below Connect to socket file descriptor Connect sockfd SA amp servaddr sizeof servaddr Directly after connecting create a new CYASSL object using the CyaSSL_new function This function returns a pointer to the CYASSL object if successful or NULL in the case of failure We can then associate the socket file descriptor sockfd with the new CYASS
135. e_chain_buffer CyaSSL_use_certificate_buffer CyaSSL_use_PrivateKey_buffer CyaSSL_use_certificate_chain_buffer CyaSSL_CTX_use_PrivateKey_file Synopsis int CvaSSL_CTX_use_PrivateKey_file CYASSL_CTX ctx const char file int format Description This function loads a private key file into the SSL context CYASSL_CTX The file is provided by the file argument The format argument specifies the format type of the file SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned If the function call fails possible causes might include The file is in the wrong format or the wrong format has been given using the format argument The file doesn t exist can t be read or is corrupted An out of memory condition occurs Base16 decoding fails on the file The key file is encrypted but no password is provided Example int ret 0 CYASSL_CTX ctx ret CyaSSL CTX use PrivateKey file ctx server key pem 138 SSL FILETYPE PEM if ret SSL SUCCESS error loading key file See Also CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_use_PrivateKey_file CyaSSL_use_PrivateKey_buffer CyaSSL_CTX_use_certificate_buffer Synopsis int CVaSSL_CTX_use_certificate_buffer CYASSL_CTX ctx const unsigned char in long sz int format Description This functi
136. ect sockfd const sockaddr amp servaddr sizeof servaddr Once a connection is established the client may read and write to the server Instead of using the TCP functions send and receive CyaSSL and yaSSL use the SSL functions SSL_write and SSL_read Here is a simple example from the client demo char msg hello yassl int wrote SSL write ssl msg sizeof msg char reply 1024 int read SSL read ssl reply sizeof reply reply read 0 printf Server response s n reply The server connects in the same way except that is uses SSL_accept instead of SSL_connect analogous to the TCP API See the server example for a complete server demo program 13 5 x509 Certificates Both the server and client can provide CyaSSL with certificates in either PEM or DER Typical usage is like this SSL_CTX_use certificate file ctx certs cert pem SSL FILETYPE PEM SSL CTX use PrivateKey file ctx certs key der SSL _ FILETYPE ASN1 124 A key file can also be presented to the Context in either format SSL_FILETYPE_PEM signifies the file is PEM formatted while SSL_FILETYPE_ASN1 declares the file to be in DER format To verify that the key file is appropriate for use with the certificate the following function can be used SSL CTX check private key ctx 125 Chapter 14 Licensing 14 1 Open Source The founders and employees of wolfSSL believe i
137. ed here http wolfssl com yaSSL benchmarks cyassl html 4 3 3 1 What s the Difference Have you ever wondered what the difference was between a block cipher and a stream cipher A block cipher has to be encrypted in chunks that are the block size for the cipher For example AES has block size of 16 bytes So if you re encrypting a bunch of small 2 or 3 byte chunks back and forth over 80 of the data is useless padding decreasing the speed of the encryption decryption process and needlessly wasting network bandwidth to boot Basically block ciphers are designed for large chunks of data have block sizes requiring padding and use a fixed unvarying transformation Stream ciphers work well for large or small chunks of data They are suitable for smaller data sizes because no block size is required If speed is a concern stream ciphers are your answer because they use a simpler transformation that typically involves an xor d keystream So if you need to stream media encrypt various data sizes including small ones or have a need for a fast cipher then stream ciphers are your best bet 4 3 4 Hashing Functions CyaSSL supports several different hashing functions including MD2 MD4 MD5 SHA 1 SHA 2 SHA 256 SHA 384 SHA 512 SHA 3 BLAKE2 and RIPEMD 160 51 Detailed usage of these functions can be found in the CTaoCrypt Usage Reference Section 10 1 4 3 5 Public Key Options CyaSSL supports the RSA DSA DSS DH and NTRU p
138. ee Also CyaSSL_dtls_get_current_timeout CyaSSL_dtls_get_peer CyaSSL_dtls_got_timeout CyaSSL_dtls 17 10 Memory Abstraction Layer The functions in this section are used when an application sets its own memory handling functions by using the CyaSSL memory abstraction layer CyaSSL_Malloc 264 Synopsis include lt cyassl ctaocrypt memory h gt void CyaSSL_Malloc size_t size Description This function is similar to malloc but calls the memory allocation function which CyaSSL has been configured to use By default CyaSSL uses malloc This can be changed using the CyaSSL memory abstraction layer see CyaSSL_SetAllocators Return Values If successful this function returns a pointer to allocated memory If there is an error NULL will be returned Specific return values may be dependent on the underlying memory allocation function being used if not using the default malloc Parameters size number of bytes to allocate Example char buffer buffer char CyaSSL Malloc 20 if buffer NULL failed to allocate memory See Also CyaSSL_Free CyaSSL_Realloc CyaSSL_SetAllocators CyaSSL_Realloc Synopsis include lt cyassl ctaocrypt memory h gt void CyaSSL_Realloc void ptr size_t size 265 Description This function is similar to realloc but calls the memory re allocation function which CyaSSL has been configured to use By default CyaSSL uses realloc This can be chan
139. ended functions CyaSSL_connect_ex and CyaSSL_accept_ex int CyaSSL_ connect _ex CYASSL HandShakeCallBack TimeoutCallBack Timeval int CyaSSL_ accept _ex CYASSL HandShakeCallBack TimeoutCallBack Timeval HandShakeCallBack is defined as typedef int HandShakeCallBack HandShakeInfo 66 HandShakelnfo is defined in cyassl callbacks h which should be added to a non standard build typedef struct handShakeInfo st char cipherName MAX CIPHERNAME SZ 1 negotiated name char packetNames MAX PACKETS HANDSHAKE MAX PACKETNAME SZ 1 SSL packet names int numberPackets actual of packets int negotiationError cipher parameter err HandShakelInfo No dynamic memory is used since the maximum number of SSL packets in a handshake exchange is known Packet names can be accessed through packetNames idx up to numberPackets The callback will be called whether or not a handshake error occured Example usage is also in the client example 6 2 Timeout Callback The same extensions used with CyaSSL Handshake Callbacks can be used for CyaSSL Timeout Callbacks as well These extensions can be called with either both or neither callbacks Handshake and or Timeout TimeoutCallback is defined as typedef int TimeoutCallBack TimeoutInfo Where Timeoutlinfo looks like typedef struct timeoutInfo st
140. entations of AES GCM balancing speed versus memory consumption If available CyaSSL will use 64 bit or 32 bit math For embedded applications there is a speedy 8 bit version that uses RAM based lookup tables 8KB per session which is speed comparable to the 64 bit version and a slower 8 bit version that doesn t take up any additional RAM The enable aesgcm configure option may be modified with the options word32 table or small i e enable aesgcm table aesccm enabling AES GCM will enable Counter with CBC MAC Mode with 8 byte authentication CCM 8 for AES aesni enabling AES NI support will allow AES instructions to be called directly from the chip when using an AES NI supported chip This provides speed increases for AES functions See Chapter 4 for more details regarding AES NI poly1305 enabling this option will add Poly1305 support to wolfCrypt and CyaSSL camellia enabling this option will add Camellia CBC support to wolfCrypt and CyaSSL chacha enabling this option will add ChaCha support to wolfCrypt and CyaSSL md2 enabling this option adds support for the MD2 algorithm to CyaSSL MD2 is disabled by default due to known security vulnerabilities 20 ripemd enabling this option adds support for the RIPEMD 160 algorithm to CyaSSL sha512 enabling this option adds support for the SHA 512 hash algorithm This algorithm needs the word64 type to be available which is why it is disabled by default S
141. es several steps some of which are optional depending on what options the SSL client and server have been configured with Below in Figure 2 you will find a simplified diagram of the SSL handshake process Copyright 2014 wolfSSL Inc All rights reserved 308 iiiw L Client Hello Cryptographic Info SSL version supported ciphers etc 3 2 Server Hello Verify server cert check crypto parameters Cipher Suite Server Certificate Server Key Exchange public key Client Certificate Request Server Hello Done Certificate Verify Client Certificate Verify client cert if required e Change Cipher Spec Client Finished Change Cipher Spec Server Finished Exchange Messages Encrypted ET cnenkeyexcnane o E sag raoe Meares Ene Figure 2 SSL Handshake Diagram A 3 Differences between SSL and TLS Protocol Versions SSL Secure Socket Layer and TLS Transport Security Layer are both cryptographic protocols which provide secure communication over networks These two protocols and the several version of each are in widespread use today in applications ranging from web browsing to e mail to instant messaging and VolP Each protocol and the 309 underlying versions of each are slightly different from the other Below you will find both an explanation of and the major differences between the different SSL and TLS protocol versions For specific details about each protocol please
142. espectively And by default they point to the C standard library versions Defining XSTRING_USER allows the user to provide their own hooks in types h For example by default XMEMCPY is define XMEMCPY d s 1 memcpy d s 1 63 After defining XSTRING_USER you could do define XMEMCPY d s 1 my memcpy d s 1 Or if you prefer to avoid macros external void my memcpy void d const void s size t n to set CyaSSL s abstraction layer to point to your version my_memcpy 5 1 1 3 math h CyaSSL uses two functions that behave like math h s pow and og They are only required by Diffie Hellman so if you exclude DH from the build then you don t have to provide your own They are abstracted to XPOW and XLOG and found in ctaocrypt src dh c 5 1 1 4 File System Use By default CyaSSL uses the system s file system for the purpose of loading keys and certificates This can be turned off by defining NO_FILESYSTEM see item V If instead you d like to use a file system but not the system one you can use the XFILE layer in ssl c to point the file system calls to the ones you d like to use See the example provided by the MICRIUM define 5 1 2 Custom Input Output Abstraction Layer CyaSSL provides a custom I O abstraction layer for those who wish to have higher control over I O of their SSL connection or run SSL on top of a different transport medium other than TCP IP The user will
143. ession with format as specified by format format the encoding type of the certificate specified by file Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1 Example int ret 0 CYASSL ssl ret CyaSSL_ use certificate file ssl client cert pem 284 SSL_FILETYPE PEM if ret SSL SUCCESS error loading cert file See Also CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_certificate_file CyaSSL_use_certificate_buffer CyaSSL_use_PrivateKey_file Synopsis include lt cyassl ssl h gt int CyaSSL_use_PrivateKey_file CYASSL ssl const char file int format Description This function loads a private key file into the SSL session CYASSL structure The key file is provided by the file argument The format argument specifies the format type of the file SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned If the function call fails possible causes might include The file is in the wrong format or the wrong format has been given using the format argument The file doesn t exist can t be read or is corrupted An out of memory condition occurs Base16 decoding fails on the file The key file is encrypted but no password is provided Parameters ssl a pointer to a CYASSL structure created with CyaSSL_new file a pointer to the name of the
144. ession of data over the connection It is off by default and normally shouldn t be used see the note below under configure notes libz HAVE_OCSP enables Online Certificate Status Protocol OCSP support OPENSSL_EXTRA builds even more OpenSSL compatibility into the library and enables the CyaSSL OpenSSL compatibility layer to ease porting CyaSSL into existing applications which had been designed to work with OpenSSL It is off by default TEST_IPV6 turns on testing of IPv6 in the test applications CyaSSL proper is IP neutral but the testing applications use IPv4 by default 2 4 3 Customizing or Porting CyaSSL CYASSL_CALLBACKS is an extension that allows debugging callbacks through the use of signals in an environment without a debugger it is off by default It can also be used to set up a timer with blocking sockets Please see Chapter 6 for more information CYASSL_USER_IO allows the user to remove automatic setting of the default I O functions EmbedSend and EmbedReceive Used for custom I O abstraction layer see section 5 1 for more details NO_FILESYSTEM is used if stdio isn t available to load certificates and key files This enables the use of buffer extensions to be used instead of the file ones NO_INLINE disables the automatic inlining of small heavily used functions Turning this on will slow down CyaSSL and actually make it bigger since these are small functions usually much smaller than function call setup return Y
145. evelopment cycle testcert when this option is enabled it exposes part of the ASN certificate API that is usually not exposed This can be useful for testing purposes as seen in the CTaoCrypt test application ctaocrypt test test c examples this option is enabled by default When enabled the CyaSSL example applications will be built client server echoclient echoserver gcc hardening enabling this option will add extra compiler security checks jobserver enabling this option allows make on computers with multiple processors to 22 build several files in parallel which can significantly reduce build times Users have the ability to pass different arguments to this command yes no If yes is used the configure script will tell make to use one more than the CPU count for the number of jobs no obviously disables this feature Optionally the user can pass in the number of jobs as well disable shared disabling the shared library build will exclude a CyaSSL shared library from being built By default only a shared library is built in order to save time and space disable static disabling the static library build will exclude a CyaSSL static library from being built This options is enabled by default A static library can be built by using the enable static build option libz enabling libz will allow compression support in CyaSSL from the libz library Think twice about including this option an
146. fer See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_CTX_use_certificate_chain_buffer CyaSSL_use_PrivateKey_buffer CyaSSL_use_certificate_chain_buffer CyaSSL_use_certificate_chain_buffer Synopsis include lt cyassl ssl h gt int CyaSSL_use_certificate_chain_buffer CYASSL ssl const unsigned char in long sz Description This function loads a certificate chain buffer into the CYASSL object It behaves like the non buffered version only differing in its ability to be called with a buffer as input instead 148 of a file The buffer is provided by the in argument of size sz The buffer must be in PEM format and start with the subject s certificate ending with the root certificate Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY_E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer Parameters ssl pointer to the SSL session created with CyaSSL_new in buffer containing certificate to load sz size of the certificate loca
147. figured to use DTLS this function will return 1 otherwise 0 259 Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new Example int ret 0 CYASSL ssl ret CyaSSL_ dtls ssl if ret SSL session has been configured to use DTLS See Also CyaSSL_dtls_get_current_timeout CyaSSL_dtls_get_peer CyaSSL_dtls_got_timeout CyaSSL_dtls_set_peer CyaSSL_dtls_get_current_timeout Synopsis include lt cyassl ssl h gt CyaSSL_dtls_get_current_timeout CYASSL ssl Description This function returns the current timeout value in seconds for the CYASSL object When using non blocking sockets something in the user code needs to decide when to check for available recv data and how long it has been waiting The value returned by this function indicates how long the application should wait Return Values The current DTLS timeout value in seconds or NOT_COMPILED_IN if CyaSSL was not built with DTLS support Parameters 260 ssl a pointer to a CYASSL structure created using CyaSSL_new Example int timeout 0 CYASSL ssl timeout CyaSSL_ get _dtls_ current timeout ssl printf DTLS timeout sec d n timeout See Also CyaSSL_dtls CyaSSL_dtls_get_peer CyaSSL_dtls_got_timeout CyaSSL_dtls_set_peer CyaSSL_dtls_get_peer Synopsis include lt cyassl ssl h gt int CyaSSL_dtls_get_peer CYASSL ssl void peer unsigned int peerSz Description Th
148. file containing the key file to be loaded into the 285 CyaSSL SSL session with format as specified by format format the encoding type of the key specified by file Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1 Example int ret 0 CYASSL ssl ret CyaSSL_ use PrivateKey file ssl server key pem SSL FILETYPE PEM if ret SSL SUCCESS error loading key file See Also CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_PrivateKey_file CyaSSL_use_PrivateKey_buffer CyaSSL_use_certificate_chain_file Synopsis include lt cyassl ssl h gt int CyaSSL_use_certificate_chain_file CYASSL ssl const char file Description This function loads a chain of certificates into the SSL session CYASSL structure The file containing the certificate chain is provided by the file argument and must contain PEM formatted certificates This function will process up to MAX_CHAIN_DEPTH default 9 defined in internal h certificates plus the subject certificate Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be 286 returned If the function call fails possible causes might include The file is in the wrong format or the wrong format has been given using the format argument file doesn t exist can t be read or is corrupted an out of memory condition occurs Parameters ssl a pointer to a CYASSL struc
149. function CyaSSL_Realloc_cb realloc_function typedef void CyaSSL_Malloc_cb size_t size typedef void CyaSSL_Free_cb void ptr typedef void CyaSSL_Realloc_cb void ptr size_t size Description This function registers the allocation functions used by CyaSSL By default if the system supports it malloc free and realloc are used Using this function allows the user 267 at runtime to install their own memory handlers Return Values If successful this function will return 0 BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided Parameters malloc_function memory allocation function for CyaSSL to use Function signature must match CyaSSL_Malloc_cb prototype above free_function memory free function for CyaSSL to use Function signature must match CyaSSL_Free_cb prototype above realloc_function memory re allocation function for CyaSSL to use Function signature must match CyaSSL_Realloc_cb prototype above Example int ret 0 Memory function prototypes void MyMalloc size t size void MyFree void ptr void MyRealloc void ptr size t size Register custom memory functions with CyaSSL ret CyaSSL SetAllocators MyMalloc MyFree MyRealloc if ret 0 failed to set memory functions void MyMalloc size t size custom malloc function void MyFree void ptr custom free function 268 void MyRealloc void ptr
150. ged using the CyaSSL memory abstraction layer see CyaSSL_SetAllocators Return Values If successful this function returns a pointer to re allocated memory This may be the same pointer as ptr or a new pointer location If there is an error NULL will be returned Specific return values may be dependent on the underlying memory re allocation function being used if not using the default realloc Parameters ptr pointer to the previously allocated memory to be reallocated size number of bytes to allocate Example char buffer buffer char CyaSSL Realloc 30 if buffer NULL failed to re allocate memory See Also CyaSSL_Free CyaSSL_Malloc CyaSSL_SetAllocators CyaSSL_Free Synopsis include lt cyassl ctaocrypt memory h gt void CyaSSL_Free void ptr Description This function is similar to free but calls the memory free function which CyaSSL has 266 been configured to use By default CyaSSL uses free This can be changed using the CyaSSL memory abstraction layer see CyaSSL_SetAllocators Return Values This function does not have a return value Parameters ptr pointer to the memory to be freed Example char buffer CyaSSL_ Free buffer See Also CyaSSL_Alloc CyaSSL_Realloc CyaSSL_SetAllocators CyaSSL_SetAllocators Synopsis include lt cyassl ctaocrypt memory h gt int CyaSSL_SetAllocators CyaSSL_Malloc_cb malloc_function CyaSSL_Free_cb free_
151. gerNew CyaSSL_CertManagerLoadCA Synopsis include lt cyassl ssl h gt int CyaSSL_CertManagerLoadCA CYASSL_CERT_MANGER cm const char CAfile const char CApath Description Specifies the locations for CA certificate loading into the manager context The PEM certificate CAfile may contain several trusted CA certificates If CApath is not NULL it specifies a directory containing CA certificates in PEM format Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file BAD_FUNC_ARG is the error that will be returned if a pointer is not provided Parameters 272 cm a pointer to a CYASSL_CERT_MANAGER structure created using CyaSSL_CertManagerNew CAfile pointer to the name of the file containing CA certificates to load CApath pointer to the name of a directory path containing CA certificates to load The NULL pointer may be used if no certificate directory is desired Example int ret 0 CYASSL_ CERT MANAGER cm ret CyaSSL CertManagerLoadCA cm path to cert file pem 0 if ret SSL SUCCESS error loading CA certs into cert manager See Also CyaSSL_CertManagerVerify CyaSSL_CertManager
152. gramming language as a primary interface but also supports several other host languages including Java PHP Perl and Python through a SWIG interface If you have interest in hosting CyaSSL in another programming language that is not currently supported please contact us This chapter covers some of the features of CyaSSL in more depth including Stream Ciphers AES NI IPv6 support SSL Inspection Sniffer support and more 4 1 Features Overview The following table lists features included in the most recent release of CyaSSL SSL version 3 and TLS versions 1 1 1 and 1 2 Support for the most up to date standards client and server with backwards compatibility DTLS 1 0 1 2 support client and server Streaming Multimedia Minimum footprint size of 20 100 kB Small build size for use in resource depending on build options and operating constrained environments environment Runtime memory usage between 1 36 kB Minimal dynamic memory use perfect depending on I O buffer sizes public key for embedded systems or scalable algorithm and key size enterprise servers OpenSSL Compatibility Layer Standard API and ease of migration from Copyright 2014 wolfSSL Inc All rights reserved 40 OCSP and CRL support Used to confirm certificate validity Multiple Hash Functions MD2 MD4 MD5 SHA 1 SHA 2 SHA 256 SHA 384 SHA 512 BLAKE2b RIPEMD 160 Poly1305 Block and Stream Ciphers 4 block ciphers 4 stream ciphers
153. gth CyaSSL_get_chain_cert CyaSSL_get_chain_cert_pem CyaSSL_get_chain_count Synopsis include lt cyassl ssl h gt int CyaSSL_get_chain_count CYASSL_X509_CHAIN chain Description Retrieves the peer s certificate chain count Return Values If successful the call will return the peer s certificate chain count 0 will be returned if an invalid chain pointer is passed to the function See Also CyaSSL_get_peer_chain CyaSSL_get_chain_length CyaSSL_get_chain_cert CyaSSL_get_chain_cert_pem CyaSSL_get_chain_length Synopsis include lt cyassl ssl h gt 279 int CyaSSL_get_chain_length CYASSL_X509_CHAIN chain int idx Description Retrieves the peer s ASN1 DER certificate length in bytes at index idx Return Values If successful the call will return the peer s certificate length in bytes by index 0 will be returned if an invalid chain pointer is passed to the function See Also CyaSSL_get_peer_chain CyaSSL_get_chain_count CyaSSL_get_chain_cert CyaSSL_get_chain_cert_pem CyaSSL_get_chain_cert Synopsis include lt cyassl ssl h gt unsigned char CyaSSL_get_chain_cert CYASSL_X509_CHAIN chain int idx Description Retrieves the peer s ASN1 DER certificate at index idx Return Values If successful the call will return the peer s certificate by index 0 will be returned if an invalid chain pointer is passed to the function See Also CyaSSL_get_peer_chain CyaSSL_get_chain_count C
154. h HMAC MD5 SHA SHA 256 SHA 384 and SHA 512 Here s an example with SHA 256 Hmac hmac byte key 24 fill key with keying material byte buffer 2048 fill buffer with data to digest byte hmacDigest SHA256 DIGEST SIZE HmacSetKey amp hmac SHA256 key sizeof key HmacUpdate amp hmac buffer sizeof buffer HmacFinal amp hmac hmacDigest hmacDigest now contains the digest of the hashed data in buffer 10 2 2 GMAC CTaoCrypt also provides GMAC for message digest needs The structure Gmac is found in the header cyassl ctaocrypt aes h as it is an application AES GCM GMAC initialization is done with GmacSetKey 89 Gmac gmac byte key 16 fill key with keying material byte iv 12 ill iv with an initialization vector byte buffer 2048 fill buffer with data to digest byte gmacDigest 16 GmacSetKey amp gmac key sizeof key GmacUpdate amp gmac iv sizeof iv buffer sizeof buffer gmacDigest sizeof gmacDigest gmacDigest now contains the digest of the hashed data in buffer 10 2 3 Poly1305 CTaoCrypt also provides Poly1305 for message digest needs The structure Poly1305 is found in the header cyassl ctaocrypt poly1305 h Poly1305 initialization is done with Poly1305SetKey The process of setting a key in Poly1305 should be done again with a new key when next using Poly1305 after Poly1305Final has been c
155. he Source Code section above This section will explain how to download configure and install the CyaSSL embedded SSL library on your system You will need to download and install the most recent version of CyaSSL from the wolfSSL download page For a full list of available build options see the Building CyaSSL guide CyaSSL was written with portability in mind and should generally be easy to build on most systems If you have difficulty building CyaSSL please feel free to ask for support on the wolfSSL product support forums When building CyaSSL on Linux BSD OS X Solaris or other nix like systems you can use the autoconf system For windows specific instructions please refer to the Building CyaSSL section of the CyaSSL Manual To configure and build CyaSSL run the following two commands from the terminal Any desired build options may be appended to configure ex configure enable opensslextra configure make 104 To install CyaSSL run sudo make install This will install CyaSSL headers into usr local include cyassl and the CyaSSL libraries into usr local lib on your system To test the build run the testsuite application from the CyaSSL root directory testsuite testsuite test A set of tests will be run on CTaoCrypt and CyaSSL to verify it has been installed correctly After a successful run of the testsuite application you should see output similar to the following MD5 test passed HA test
156. her plain now contains the original plaintext from the cipher text CTaoCrypt also supports CTR Counter GCM Galois Counter and CCM 8 Counter with CBC MAC modes of operation for AES When using these modes like CBC include the cyassl ctaocrypt aes h header CTR mode is available for encryption through the AesCtrEncrypt function GCM mode is available for both encryption and decryption through the AesGcmSetKey AesGcmEncrypt and AesGcmDecrypt functions For a usage example see the aesgcm_test function in lt cyassl_root gt ctaocrypt test test c CCM 8 mode is supported for both encryption and decryption through the AesCcmSetKey AesCcmEncrypt and AesCcmDecrypt functions For a usage example see the aesccm_test function in lt cyassl_root gt ctaocrypt test test c 10 3 2 DES and 3DES 91 CTaoCrypt provides support for DES and 3DES Des3 since 3 is an invalid leading C identifier To use these include the header cyassl ctaocrypt des h The structures you can use are Des and Des3 Initialization is done through Des_SetKey or Des3_SetKey CBC encryption decryption is provided through Des_CbcEnrypt Des_CbcDecrypt and Des3_CbcEncrypt Des3_CbcDecrypt Des has a key size of 8 bytes 24 for 3DES and the block size is 8 bytes so only pass increments of 8 bytes to encrypt decrypt functions If your data isn t in a block size increment you ll need to add padding to make sure it is Ea
157. hrough packetNames J The connect extension also allows a Timeout Callback to be set along with a timeout value This is useful if the user doesn t want to wait for the TCP stack to timeout This extension can be called with either both or neither callbacks Return Values If successful the call will return SSL_SUCCESS GETTIME_ERROR will be returned if gettimeofday encountered an error SETITIMER_ERROR will be returned if setitimer encountered an error SIGACT_ERROR will be returned if sigaction encountered an error SSL_FATAL_ERROR will be returned if the underlying SSL_connect call encountered an error See Also CyaSSL_accept_ex CyaSSL_accept_ex Synopsis include lt cyassl ssl h gt int CyaSSL_accept_ex CYASSL ssl HandShakeCallBack hsCb TimeoutCallBack toCb Timeval timeout typedef int HandShakeCallBack HandShakelnfo typedef int TimeoutCallBack TimeoutInfo typedef struct timeval Timeval 201 typedef struct handShakelInfo st char cipherName MAX CIPHERNAME SZ 1 negotiated name char packetNames MAX PACKETS HANDSHAKE MAX PACKETNAME SZ 1 SSL packet names int numberPackets actual of packets int negotiationError cipher parameter err HandShakelInfo typedef struct timeoutInfo st char timeoutName MAX TIMEOUT NAME SZ 1 timeout Name int flags for future use int numberPackets actual of
158. icate chain file ctx cert chain pem if ret SSL SUCCESS error loading cert file See Also CyaSSL_CTX_use_certificate_file CyaSSL_CTX_use_certificate_buffer CyaSSL_use_certificate_file CyaSSL_use_certificate_buffer CyaSSL_CTX_use_certificate_file Synopsis int CyaSSL_CTX_use_certificate_file CYASSL_CTX ctx const char file int format Description This function loads a certificate file into the SSL context CYASSL_CTX The file is provided by the file argument The format argument specifies the format type of the file either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned If the function call fails possible causes might include The file is in the wrong format or the wrong format has been given using the format argument file doesn t exist can t be read or is corrupted an out of memory condition occurs Base16 decoding fails on the file Parameters 143 ctx a pointer toa CYASSL_CTX structure created using CyaSSL_CTX_new file a pointer to the name of the file containing the certificate to be loaded into the CyaSSL SSL context format format of the certificates pointed to by file Possible options are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int ret 0 CYASSL CTX ctx ret CyaSSL CTX use certificate file ct
159. ient and server will indicate the WANT_READ incidents when debugging is enabled 320
160. if the underlying SSL_accept call encountered an error See Also CyaSSL_connect_ex CyaSSL_SetLoggingCb Synopsis include lt cyassl ctaocrypt logging h gt int CyaSSL_SetLoggingCb CyaSSL_Logging_cb log_function typedef void CyaSSL_Logging_cb const int logLevel const char const logMessage Description This function registers a logging callback that will be used to handle the CyaSSL log 203 message By default if the system supports it fprintf to stderr is used but by using this function anything can be done by the user Return Values If successful this function will return 0 BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided Parameters log_function function to register as a logging callback Function signature must follow the above prototype Example int ret 0 Logging callback prototype void MyLoggingCallback const int logLevel const char const logMessage Register the custom logging callback with CyaSSL ret CyaSSL SetLoggingCb myLogCallback if ret 0 failed to set logging callback void MyLoggingCallback const int logLevel const char const logMessage custom logging function See Also CyaSSL_Debugging ON CyaSSL_Debugging_OFF CyaSSL_SetTlsHmaclInner Synopsis include lt cyassl ssl h gt int CyaSSL_SetTlsHmaclnner CYASSL ssl byte inner word32 sz 204 int content i
161. iled ret CyaSSL UseSupportedCurve ssl CYASSL ECC _SECP256R1 if ret 0 Elliptic Curve Extension usage failed See Also CyaSSL_CTX_new CyaSSL_CTX_UseSupportedCurve Appendix A SSL TLS Overview A 1 General Architecture The CyaSSL embedded SSL library implements SSL 3 0 TLS 1 0 TLS 1 1 and TLS 1 2 protocols TLS 1 2 is currently the most secure and up to date version of the standard CyaSSL does not support SSL 2 0 due to the fact that it has been insecure for several years The TLS protocol in CyaSSL is implemented as defined in RFC 5246 http tools ietf org html ric5246 Two record layer protocols exist within SSL the message layer and the handshake layer Handshake messages are used to negotiate a common cipher suite create secrets and enable a secure connection The message layer encapsulates the handshake layer while also supporting alert processing and application data transfer A general diagram of how the SSL protocol fits into existing protocols can be seen in Figure 1 SSL sits in between the Transport and Application layers of the OSI model where any number of protocols including TCP IP Bluetooth etc may act as the transport medium Application protocols are layered on top of SSL such as HTTP FTP and SMTP 307 Protocols Secured by SSL TLS Application Layer Network Layer Figure 1 SSL Protocol Diagram A 2 SSL Handshake The SSL handshake involv
162. ill switch the benchmark application from using Megabytes to using Kilobytes therefore reducing the memory usage By default when using this define ciphers and algorithms will be benchmarked with 25kB Public key algorithms will only be benchmarked over 1 iteration as public key operations on some embedded processors can be fairly slow These can be adjusted in benchmark c by altering the variables numBlocks and times located inside the BENCH EMBEDDED define USE_CERT_BUFFERS_ 1024 enabling this define will switch the benchmark application from loading test keys and certificates from the file system and instead use 1024 bit key and certificate buffers located in lt cyassl_root gt cyassl certs_test h It is useful to use this define when an embedded platform has no filesystem used with NO_FILESYSTEM and a slow processor where 2048 bit public key operations may not be reasonable USE_CERT_BUFFERS_ 2048 enabling this define is similar to USE_CERT_BUFFERS_1024 except that 2048 bit key and certificate buffers are used instead of 1024 bit ones This define is useful when the processor is fast enough to do 2048 bit public key operations but when there is no filesystem available to load keys and certificates from files 3 8 Changing a Client Application to Use CyaSSL This section will explain the basic steps needed to add CyaSSL to a client application using the CyaSSL native API For a server explanation please see section 3
163. ion NTRU TLS_NTRU_RSA_WITH_ AES 128 CBC_SHA cipher suites TLS _NTRU_RSA_WITH_AES 256 _CBC_SHA TLS_DHE_RSA WITH AES 256 CBC_SHA256 TLS DHE RSA WITH AES 128 CBC_SHA256 TLS_RSA_WITH_ AES 256 CBC_SHA256 SHA 256 cipher suites TLS_RSA_WITH_AES 128 CBC_SHA256 TLS_RSA_WITH_NULL_SHA256 TLS_RSA_WITH_AES 128 GCM_SHA256 AES GCM cipher suites 49 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_128 GCM_SHA256 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES 128 GCM_SHA256 TLS_ECDHE_ ECDSA _WITH_AES 256 GCM SHA384 TLS_ECDH ECDSA_WITH_ AES 128 _GCM_SHA256 TLS_ECDH ECDSA_WITH_ AES 256 _GCM_SHA384__ ECC AES GCM cipher TLS _ECDHE_RSA_WITH_ AES 128 _GCM_SHA256 suites TLS _ECDHE_RSA_WITH AES 256 _GCM_SHA384 TLS_ECDH_RSA_WITH AES 128 GCM_SHA256 TLS _ECDH RSA _WITH_AES 256 GCM_SHA384 TLS_RSA_WITH_AES 128 CCM_8 SHA256 TLS_RSA_WITH_AES 256 CCM_8 SHA384 TLS _ECDHE_ ECDSA WITH_AES 128 CCM 8 TLS_ECDHE ECDSA _WITH_AES 256 CCM_8 TLS_PSK_WITH_ AES 128 CCM TLS_PSK_WITH_AES 256 CCM TLS _PSK_WITH_AES 128 CCM 8 TLS _PSK_WITH_AES 256 CCM 8 AES CCM cipher suites TLS_RSA_WITH_CAMELLIA_128 CBC_SHA TLS_RSA_WITH_CAMELLIA_256_CBC_SHA TLS RSA WITH CAMELLIA 128 CBC_SHA256 TLS RSA WITH CAMELLIA 256 _CBC_SHA256 ee TLS DHE RSA WITH CAMELLIA 128 CBC SHA Sallie ental Selb TLS DHE RSA WITH CAMELLIA 256 CBC SHA TLS DHE RSA WITH CAMELLIA 128 _CBC_SHA256 TLS DHE RSA WITH CAMELLIA 256 _CBC_SHA256 TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SH
164. ion to defining a NO_ lt feature name gt define you can also remove the respective source file as well from the build but not the header file NO_CYASSL_CLIENT removes calls specific to the client and is for a server only builds You should only use this if you want to remove a few calls for the sake of size NO_CYASSL_SERVER likewise removes calls specific to the server side NO_DES3 removes the use of DES3 encryptions DES3 is built in by default because some older servers still use it and it s required by SSL 3 0 NO_DH and NO_AES are the same as the two above they are widely used NO_DSA removes DSA since it s being phased out of popular use NO_ERROR_STRINGS disables error strings Error strings are located in src internal c for CyaSSL or ctaocrypt src asn c for CTaoCrypt NO_HMAC removes HMAC from the build NO_MD4 removes MD4 from the build MD4 is broken and shouldn t be used NO_MD5 removes MD5 from the build NO_SHA256 removes SHA 256 from the build NO_PSK turns off the use of the pre shared key extension It is built in by default NO_PWDBASED disables password based key derivation functions such as PBKDF1 PBKDF2 and PBKDF from PKCS 12 NO_RC4 removes the use of the ARC4 steam cipher from the build ARC4 is built in by default because it is still popular and widely used NO_RABBIT and NO_HC128 remove stream cipher extensions from the build NO_SESSION_CACHE can be defined when a session cache is not needed
165. is a unknown value see below MEMORY E is the error returned when there is not enough memory Parameters ssl pointer to a SSL object created with CyaSSL_new type indicates which type of server name is been passed in data The known types are enum CYASSL_SNI_HOST_NAME 0 data pointer to the server name data size size of the server name data Example int ret 0 CYASSL CTX ctx 0 CYASSL ssl 0 ctx CyaSSL CTX new method 291 if ctx NULL context creation failed ssl CyaSSL_new ctx if ssl NULL ssl creation failed ret CyaSSL UseSNI ssl CYASSL_ SNI HOST NAME www yassl com strlen www yassl com if ret 0 sni usage failed See Also CyaSSL_new CyaSSL_CTX_UseSNI CyaSSL_CTX_SNI_SetOptions Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SNI_ SetOptions CYASSL_CTX ctx unsigned char type unsigned char options Description This function is called on the server side to configure the behavior of the SSL sessions using Server Name Indication for SSL objects created from the SSL context passed in the ctx parameter The options are explained below Return Values This function does not have a return value Parameters ctx pointer to a SSL context created with CyaSSL_CTX_new 292 type indicates which type of server name is been passed in data The known types are enum CYASSL_SNI_HOS
166. is function gets the sockaddr_in of size peerSz of the current DTLS peer The function will compare peerSz to the actual DTLS peer size stored in the SSL session If the peer will fit into peer the peer s sockaddr_in will be copied into peer with peerSz set to the size of peer Return Values SSL_SUCCESS will be returned upon success SSL_FAILURE will be returned upon failure SSL_NOT_IMPLEMENTED will be returned if CyaSSL was not compiled with DTLS support 261 Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new peer pointer to memory location to store peer s sockaddr_in structure peerSz input output size As input the size of the allocated memory pointed to by peer As output the size of the actual sockaddr_in structure pointed to by peer Example int ret 0 CYASSL ssl sockaddr in addr ret CyaSSL dtls_get_peer ssl amp addr sizeof addr if ret SSL SUCCESS failed to get DTLS peer See Also CyaSSL_dtls_get_current_timeout CyaSSL_dtls_got_timeout CyaSSL_dtls_set_peer CyaSSL_dtls CyaSSL_dtls_got_timeout Synopsis include lt cyassl ssl h gt int CyaSSL_dtls_got_timeout CYASSL ssl Description When using non blocking sockets with DTLS this function should be called on the CYASSL object when the controlling code thinks the transmission has timed out It performs the actions needed to retry the last transmit including adjusting the timeout
167. is output several optional algorithms ciphers were enabled including HC 128 RABBIT ECC SHA 256 SHA 512 AES GCM AES CCM and Camellia ctaocrypt benchmark benchmark AES 5 megs took 0 034 seconds 145 05 MB s AES GCM 5 megs took 0 312 seconds 16 00 MB s AES CCM 5 megs took 0 064 seconds 77 72 MB s Camellia 5 megs took 0 045 seconds 110 50 MB s ARC4 5 megs took 0 016 seconds 322 31 MB s HC128 5 megs took 0 004 seconds 1226 69 MB s RABBIT 5 megs took 0 013 seconds 390 96 MB s 3DES 5 megs took 0 241 seconds 20 73 MB s MD5 5 megs took 0 011 seconds 442 84 MB s SHA 5 megs took 0 019 seconds 258 07 MB s SHA 256 5 megs took 0 044 seconds 113 92 MB s SHA 512 5 megs took 0 026 seconds 192 65 MB s RSA 2048 encryption took 0 88 milliseconds avg over 100 iterations RSA 2048 decryption took 4 98 milliseconds avg over 100 iterations DH 2048 key generation 1 27 milliseconds avg over 100 iterations DH 2048 key agreement 1 95 milliseconds avg over 100 32 iterations ECC 256 key generation 1 89 milliseconds avg over 5 iterations EC DHE key agreement 1 88 milliseconds avg over 5 iterations EC DSA sign time 1 90 milliseconds avg over 5 iterations This is especially useful for comparing the public key speed before and after changing the math
168. is section are informational They allow the application to gather some kind of information about the current status or setup of CyaSSL CyaSSL_GetObjectSize Synopsis include lt cyassl ssl h gt int CyaSSL_GetObjectSize void Description This function returns the size of the CYASSL object and will be dependent on build options and settings If SHOW_SIZES has been defined when building CyaSSL this function will also print the sizes of individual objects within the CYASSL object Suites Ciphers etc to stdout Return Values This function returns the size of the CYASSL object Parameters This function has no parameters Example int size 0 size CyaSSL_ GetObjectSize printf sizeof CYASSL d n size See Also CyaSSL_new CyaSSL_GetMacSecret Synopsis 230 include lt cyassl ssl h gt const unsigned char CyaSSL_GetMacSecret CYASSL ssl int verify Description Allows retrieval of the Hmac Mac secret from the handshake process The verify parameter specifies whether this is for verification of a peer message Return Values If successful the call will return a valid pointer to the secret The size of the secret can be obtained from CyaSSL_GetHmacSize NULL will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new verify specifies whether this is for verification of a peer message See Also CyaSSL_GetHmacSize
169. ithm for a given key size is traditionally described in terms of the amount of work it takes to try all keys for a symmetric algorithm with a key size of X that has no short cut attacks i e the most efficient attack is to try all possible keys The following two tables are based off of both Table 2 pg 64 and Table 4 pg 66 from NIST SP800 57 and shows comparable security strength between algorithms as well as a strength measurement based off of NIST s suggested algorithm security lifetimes using bits of security Note In the following table L is the size of the public key for finite field cryptography FFC N is the size of the private key for FFC k is considered the key size for integer factorization cryptography IFC and f is considered the key size for elliptic curve cryptography Bits of Symmetric Key FFC Key Size IFC Key Size ECC Key Size Security Algorithms DSA DH etc RSA etc ECDSA etc 2TDEA etc L 1024 k 1024 f 160 223 N 160 128 AES 128 etc L 3072 k 3072 f 256 383 N 256 AES 192 etc L 7680 k 7680 f 384 511 N 384 AES 256 etc L 15360 k 15360 f 512 N 512 46 Table 2 Relative Bit and Key Strengths Security good through 2010 Security good through 2030 Long Term Protection Secure for the foreseeable future Table 3 Bit Strength Descriptions Using this table as a guide to begin to classify a cipher suite we categorize i
170. l Description Allows caller to determine the negotiated cipher block size from the handshake 236 Return Values If successful the call will return the size in bytes of the cipher block size BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetBulkCipher CyaSSL_GetKeySize CyaSSL_GetAeadMacSize Synopsis include lt cyassl ssl h gt int CyaSSL_GetAeadMacSize CYASSL ssl Description Allows caller to determine the negotiated aead mac size from the handshake For cipher type CYASSL_AEAD_TYPE Return Values If successful the call will return the size in bytes of the aead mac size BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetBulkCipher CyaSSL_GetKeySize 237 CyaSSL_GetHmacSize Synopsis include lt cyassl ssl h gt int CyaSSL_GetHmacSize CYASSL ssl Description Allows caller to determine the negotiated h mac size from the handshake For cipher types except CYASSL_AEAD_TYPE Return Values If successful the call will return the size in bytes of the h mac size BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetBulkCipher CyaSSL_GetHmacType CyaSSL_GetHmacType Synopsis include l
171. les server server c 4 9 Server Name Indication SNI is useful when a server hosts multiple virtual servers at a single underlying network address It may be desirable for clients to provide the name of the server which it is contacting To enable SNI with CyaSSL you can simply do configure enable sni Using SNI on the client side requires an additional function call which should be one of the following functions CyaSSL_ CTX _UseSNI CyaSSL_ UseSNI CyaSSL_CTX_UseSNI is most recommended when the client contacts the same server multiple times Setting the SNI extension at the context level will enable the SNI usage in all SSL objects created from that same context from the moment of the call forward CyaSSL_UseSNl will enable SNI usage for one SSL object only so it is recommended to use this function when the server name changes between sessions On the server side one of the same function calls is required Since the CyaSSL server doesn t host multiple virtual servers the SNI usage is useful when the termination of the connection is desired in the case of SNI mismatch In this scenario CyaSSL_CTX_UseSNI will be more efficient as the server will set it only once per context creating all subsequent SSL objects with SNI from that same context 60 4 10 Handshake Modifications 4 10 1 Grouping Handshake Messages CyaSSL has the ability to group handshake messages if the user desires This can be do
172. library You can test the results using the normal math library configure the fastmath library configure enable fastmath and the fasthugemath library configure enable fasthugemath For more details and benchmark results please refer to the CyaSSL Benchmarks page http www wolfssl com yaSSL benchmarks cyassl html 3 7 1 Relative Performance Although the performance of individual ciphers and algorithms will depend on the host platform the following graph shows relative performance between CTaoCrypt s ciphers These tests were conducted on a Macbook Pro OS X 10 6 8 running a 2 2 GHz Intel Core i7 33 1200 1000 800 MB s S 400 200 fal E i a 3DES Comelia AES CBC RIPEMD ARC4 RABBIT MDS HC 128 If you want to use only a subset of ciphers you can customize which specific cipher suites and or ciphers CyaSSL uses when making an SSL TLS connection For example to force 128 bit AES add the following line after the call to CyaSSL_CTX_new SSL_CTX_new Cyassh CTX set cipher List ctx AES128 SHA 3 7 2 Benchmarking Notes 1 The processors native register size 32 vs 64 bit can make a big difference when doing 1000 bit public key operations 2 keygen enable keygen will allow you to also benchmark key generation speeds when running the benchmark utility Copyright 2014 wolfSSL Inc All rights reserved 34 fastmath enable fastmath reduces dynamic memory us
173. lient example found in examples client to test CyaSSL against any SSL server To see a list of available command line runtime options run the client with the help argument examples client client help client 2 8 0 NOTE All files relative h lt hos t gt p lt num gt v lt num lt str c lt fil cert pe k lt fil key pem A lt fil Cere pe b lt num 5 for DTL gt gt e gt m e gt e gt m gt Svl Help print this usage Host to connect to default Port to connect on not 0 SSL version 0 3 SSLv3 0 Cipher list Certificate file Key file Certificate Authority file Use pre Shared keys Track CyaSSL memory use Disable peer checks Send server HTTP GET Use UDP DTLS add v 2 for 2 26 LD AOE Oca default 11111 2243 V5 TLS default defaul default DTLSv1 default cert cert cert Benchmark lt num gt connections and print sta to CyaSSL home dir default 3 ts cl CS ts cl ient ient ts ca v 3 m Match domain name in cert N Use Non blocking sockets Hr Resume session f Fewer packets group messages Xx Disable client cert key loading To test against secure gmail try the following This is using CyaSSL compiled with the enable opensslExtra build option examples client client h gmail google com p 443 d g peer s cert inf
174. lient is running if strncmp sendline break 5 0 printf Sending server session close break n break 115 EchoServer Like the echoclient we will need to add a signal handler for when the user closes the echoserver 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 First define a new static int variable called cleanup at the top of tcpserv04 c right after the include statements static int cleanup To handle shutdown Modify the echoserver loop by changing it from a for loop to a while loop while cleanup 1 echo server code here 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 accept 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 SA_RESTART first define act and oact structures in the echoserver s main function struct sigaction act oact Insert the following
175. ll then in turn be passed back to the respective public key callback through the void ctx parameter Example callbacks can be found in cyassl test h under myEccSignCb myEccVerifyCb myRsaSignCb myRsaVerifyCb myRsaEncCb and myRsaDecCb Usage can be seen in the CyaSSL example client examples client client c when using the P command line option To use Atomic Record Layer callbacks CyaSSL needs to be compiled using the enable pkcallbacks configure option or by defining the HAVE_PK_CALLBACKS preprocessor flag Chapter 7 Keys and Certificates For an introduction to X 509 certificates as well as how they are used in SSL and TLS please see Appendix A 7 1 Supported Formats and Sizes CyaSSL has support for PEM and DER formats for certificates and keys as well as PKCS 8 private keys with PKCS 5 or PKCS 12 encryption PEM or Privacy Enhanced Mail is the most common format that certificates are issued in by certificate authorities PEM files are Base64 encoded ASCII files which can include multiple server certificates intermediate certificates and private keys and usually have a pem crt cer or key file extension Certificates inside PEM files are wrapped in the BEGIN CERTIFICATE and END CERTIFICATE statements 71 DER or Distinguished Encoding Rules is a binary format of a certificate DER file extensions can include der and
176. method function will use the highest protocol version supported by the server and downgrade to SSLv3 if needed In this case the client will be able to connect to a server running SSLv3 TLSv1 2 Return Values If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Parameters This function has no parameters 157 Example CYASSL METHOD method CYASSL CTX ctx method CyaSSLv23 client _method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_client_method CyaTLSv1_client_method CyaTLSv1_1_client_method CyaTLSv1_2_client_method CyaDTLSv1_client_method CyaSSL_CTX_new CyaSSLv23_server_method Synopsis include lt cyassl ssl h gt CYASSL_METHOD CyaSSLv23_server_method void Description The CyaSSLv23_server_method function is used to indicate that the application is a server and will support clients connecting with protocol version from SSL 3 0 TLS 1 2 This function allocates memory for and initializes a new CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fail
177. mware updates from unauthorized parties General information on code signing http en wikipedia org wiki Code_signing 120 Chapter 13 OpenSSL Compatibility 13 1 Compatibility with OpenSSL CyaSSL provides an OpenSSL compatibility header cyassl openssl ssl h in addition to the CyaSSL native API to ease the transition into using CyaSSL or to aid in porting an existing OpenSSL application over to CyaSSL For an overview of the OpenSSL Compatibility Layer please continue reading below To view the complete set of OpenSSL functions supported by CyaSSL please see the cyassl openssl ssl h file The OpenSSL Compatibility Layer maps a subset of the most commonly used OpenSSL commands to CyaSSL s native API functions This should allow for an easy replacement of OpenSSL by CyaSSL in your application or project without changing much code Our test beds for OpenSSL compatibility are stunnel and Lighttpd which means that we build both of them with CyaSSL as a way to test our OpenSSL compatibility API 13 2 Differences Between CyaSSL and OpenSSL Many people are curious how CyaSSL compares to OpenSSL and what benefits there are to using an SSL library that has been optimized to run on embedded platforms Obviously OpenSSL is free and presents no initial costs to begin using but we believe that CyaSSL will provide you with more flexibility an easier integration of SSL TLS into your existing platform current standards support
178. n Open Source Software As such the source code for CyaSSL is available for all to use modify test and enjoy under the GPL CyaSSL may be modified to the needs of the user as long as the user adheres to version two of the GPL License The GPLv2 license can be found on the gnu org website http www gnu org licenses old licenses gpl 2 0 html We do not reserve features As such everything available in the commercial version of CyaSSL is also available in the open source GPL version For more information on our licensing please see our website or contact info wolfssl com 14 2 Commercial Licensing Businesses and enterprises who wish to incorporate CyaSSL into proprietary appliances or other commercial software products for re distribution must license commercial versions Commercial licenses for CyaSSL and yaSSL are available for 5 000 USD per product Licenses are generally issued for one product and include unlimited distribution 14 3 Support Packages Support packages for CyaSSL are available on an annual basis directly from yaSSL With three different package options you can compare them side by side and choose the package that best fits your specific needs Please see our Support Packages page for more details http www wolfssl com yaSSL Support support_tiers php Chapter 15 Support and Consulting 15 1 How to Get Support 126 For general product support wolfSSL maintains an online forum for the wolfSSL prod
179. n SSL_SUCCESS SSL_FAILURE will be returned if ctx is NULL or if both file and path are NULL SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer BAD_PATH_ERROR will be returned if opendir fails when trying to open path Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new 135 file pointer to name of the file containing PEM formatted CA certificates path pointer to the name of a directory to load PEM formatted certificates from Example int ret 0 CYASSL CTX ctx ret CyaSSL CTX load _ verify locations ctx ca cert pem 0 if ret SSL SUCCESS error loading CA certs See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_certificate_file CyaSSL_CTX_use_PrivateKey_file CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_CTX_use _certificate_chain_file CyaSSL_use_certificate_file CyaSSL_use_PrivateKey_file CyaSSL_use_certificate_chain_file CyaSSL_CTX_use_PrivateKey_buffer Synopsis int CyVaSSL_CTX_use_PrivateKey_buffer CYASSL_CTX ctx const unsigned char in long sz int format Description This function loads a private key buffer into the SSL Context
180. n Values If successful the call will return SSL_SUCCESS NOT_COMPILED_IN will be returned if compression support wasn t built into the library Parameters ssl pointer to the SSL session created with CyaSSL_new Example int ret 0 CYASSL ssl 0 ret CyaSSL_ set_ compression ssl if ret SSL SUCCESS successfully enabled compression for SSL session See Also NA 180 CyaSSL_set_fd Synopsis include lt cyassl ssl h gt int CyaSSL_set_fd CYASSL ssl int fd Description This function assigns a file descriptor fd as the input output facility for the SSL connection Typically this will be a socket file descriptor Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned Parameters ssl pointer to the SSL session created with CyaSSL_new fd file descriptor to use with SSL TLS connection Example int sockfd CYASSL ssl 0 ret CyaSSL set _fd ssl sockfd if ret SSL SUCCESS failed to set SSL file descriptor See Also CyaSSL_SetlOSend CyaSSL_SetlORecv CyaSSL_SetlOReadCtx CyaSSL_SetlOWriteCtx CyaSSL_set_group_messages 181 Synopsis int CyaSSL_set_group_messages CYASSL ssl Description This function turns on grouping of handshake messages where possible Return Values SSL_SUCCESS will be returned upon success BAD_FUNC_ARG will be returned if the input context is null Parameters
181. n creates a new SSL session taking an already created SSL context as input 167 Return Values If successful the call will return a pointer to the newly created CYASSL structure Upon failure NULL will be returned Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new Example CYASSL ssl NULL CYASSL CTX ctx ll fo ctx CyaSSL CTX new method if ctx NULL context creation failed ssl CyaSSL_new ctx if ssl NULL SSL object creation failed See Also CyaSSL_CTX_new CyaSSL_free Synopsis include lt cyassl ssl h gt void CyaSSL_free CYASSL ssl Description This function frees an allocated CYASSL object Return Values No return values are used for this function Parameters 168 ssl pointer to the SSL object created with CyaSSL_new Example CYASSL ssl 0 CyaSSL free ssl See Also CyaSSL_CTX_new CyaSSL_new CyaSSL_CTX_free CyaSSL_CTX_new Synopsis CYASSL_CTX CyaSSL_CTX_new CYASSL_METHOD method Description This function creates a new SSL context taking a desired SSL TLS protocol method for input Return Values If successful the call will return a pointer to the newly created CYASSL_CTX Upon failure NULL will be returned Parameters method pointer to the desired CYASSL_METHOD to use for the SSL context This is created using one of the CyaSSLvXX_XXXX_method functions to specify SSL TLS DTL
182. n the client side Server mode the verification will fail on the server side if the client fails to send a certificate when requested to do so when using SSL_VERIFY_PEER on the SSL server Return Values This function has no return value Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new mode session timeout value in seconds verify_callback callback to be called when verification fails If no callback is desired the NULL pointer can be used for verify_callback Example CYASSL_ CTX ctx 0 CyaSSL_ CTX _set_verify ctx SSL VERIFY PEER SSL VERIFY FAIL IF NO PEER CERT 0 See Also CyaSSL_set_verify 17 4 Callbacks The functions in this section have to do with callbacks which the application is able to set in relation to CyaSSL 191 CyaSSL_SetlOReadCtx Synopsis void CyaSSL_SetlIOReadCtx CYASSL ssl void rctx Description This function registers a context for the SSL session s receive callback function By default CyaSSL sets the file descriptor passed to CyaSSL_set_fd as the context when CyaSSL is using the system s TCP library If you ve registered your own receive callback you may want to set a specific context for the session For example if you re using memory buffers the context may be a pointer to a structure describing where and how to access the memory buffers Return Values No return values are used for this fu
183. name values from the cipher_names array in src internal c RC4 SHA RC4 MD5 DES CBC3 SHA AES128 SHA AES256 SHA NULL SHA NULL SHA256 DHE RSA AES128 SHA DHE RSA AES256 SHA PSK AES128 CBC SHA256 PSK AES128 CBC SHA PSK AES256 CBC SHA PSK NULL SHA256 PSK NULL SHA HC128 MD5 HC128 SHA HC128 B2B256 AES128 B2B256 AES256 B2B256 RABBIT SHA NTRU RC4 SHA NTRU DES CBC3 SHA NTRU AES128 SHA 177 NTRU AES256 SHA AES128 CCM 8 AES256 CCM 8 ECDHE ECDSA AES128 CCM 8 ECDHE ECDSA AES256 CCM 8 ECDHE RSA AES128 SHA ECDHE RSA AES256 SHA ECDHE ECDSA AES128 SHA ECDHE ECDSA AES256 SHA ECDHE RSA RC4 SHA ECDHE RSA DES CBC3 SHA ECDHE ECDSA RC4 SHA ECDHE ECDSA DES CBC3 SHA AES128 SHA256 AES256 SHA256 DHE RSA AES128 SHA256 DHE RSA AES256 SHA256 ECDH RSA AES128 SHA ECDH RSA AES256 SHA ECDH ECDSA AES128 SHA ECDH ECDSA AES256 SHA ECDH RSA RC4 SHA ECDH RSA DES CBC3 SHA ECDH ECDSA RC4 SHA ECDH ECDSA DES CBC3 SHA AES128 GCM SHA256 AES256 GCM SHA384 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 ECDH RSA AES128 GCM SHA256 ECDH RSA AES256 GCM SHA384 ECDH ECDSA AES128 GCM SHA256 ECDH ECDSA AES256 GCM SHA384 CAMELLIA128 SHA DHE RSA CAMELLIA128 SHA CAMELLIA256 SHA 178 DHE RSA CAMELLIA256 SHA CAMELLIA128 SHA256 DHE RSA CAMELLIA128 SHA256 CAMELLIA256 SHA256 DHE RSA CAMELLIA256 SHA256 ECDHE RSA AES128 SHA256 ECDHE ECDS
184. nction Parameters ssl pointer to the SSL session created with CyaSSL_new rctx pointer to the context to be registered with the SSL session s ssl receive callback function Example int sockfd CYASSL ssl 0 Manually setting the socket fd as the receive CTX for example CyaSSL SetIOReadCtx ssl amp sockfd See Also CyaSSL_SetlORecv CyaSSL_SetlOSend CyaSSL_SetlOWriteCtx CyaSSL_SetlOWriteCtx 192 Synopsis void CyaSSL_SetlOWriteCtx CYASSL ssl void wctx Description This function registers a context for the SSL session s send callback function By default CyaSSL sets the file descriptor passed to CyaSSL_set_fd as the context when CyaSSL is using the system s TCP library If you ve registered your own send callback you may want to set a specific context for the session For example if you re using memory buffers the context may be a pointer to a structure describing where and how to access the memory buffers Return Values No return values are used for this function Parameters ssl pointer to the SSL session created with CyaSSL_new wctx pointer to the context to be registered with the SSL session s ssl send callback function Example int sockfd CYASSL ssl 0 Manually setting the socket fd as the send CTX for example CyaSSL SetIOSendCtx ssl amp sockfd See Also CyaSSL_SetlORecv CyaSSL_SetlOSend CyaSSL_SetlOReadCtx CyaSSL_SetlOReadFlags Sy
185. ne at the context level with CyaSSL CTX set group messages ctx or at the SSL object level with CyaSSL_ set group messages ssl 4 11 Truncated HMAC Currently defined TLS cipher suites use the HMAC to authenticate record layer communications In TLS the entire output of the hash function is used as the MAC tag However it may be desirable in constrained environments to save bandwidth by truncating the output of the hash function to 80 bits when forming MAC tags To enable the usage of Truncated HMAC at CyaSSL you can simply do configure enable truncatedhmac Using Truncated HMAC on the client side requires an additional function call which should be one of the following functions CyaSSL CTX UseTruncatedHMAC CyaSSL_ UseTruncatedHMAC CyaSSL_CTX_UseTruncatedHMAC is most recommended when the client would like to enable Truncated HMAC for all sessions Setting the Truncated HMAC extension at context level will enable it in all SSL objects created from that same context from the moment of the call forward 61 CyaSSL_UseTruncatedHMAC will enable it for one SSL object only so it s recommended to use this function when there is no need for Truncated HMAC on all sessions On the server side no call is required The server will automatically attend to the client s request for Truncated HMAC All TLS extensions can also be enabled with configure enable tlsx 62 Chapter 5 Portability 5 1
186. need to define 2 functions 1 The network Send function 2 The network Receive function These two functions are prototyped by CallbacklOSend and CallbacklORecv in ssl h CallbackIORecv char buf int CallbackIOSend char buf int typedef int sz void ctx cr ct cv CT typedef int sz void ctx 64 The user needs to register these functions per CYASSL_CTX with CyaSSL_SetlOSend and CyaSSL_SetlORecv For example in the default case CBlORecv and CBIOSend are registered at the bottom of io c void CyaSSL SetIORecv CYASSL CTX ctx CallbackIORecv CBIORecv ctx gt CBIORecv CBIORecv void CyaSSL SetIOSend CYASSL CTX ctx CallbackIOSend CBIOSend ctx gt CBIOSend CBIOSend The user can set a context per CYASSL object session with CyaSSL_SetlOWriteCtx and CyaSSL_SetlOReadCtx as demonstrated at the bottom of io c For example if the user is using memory buffers the context may be a pointer to a structure describing where and how to access the memory buffers The default case with no user overrides registers the socket as the context The CBlORecv and CBlOSend function pointers can be pointed to your custom I O functions The default Send and Receive functions EmbedSend and EmbedReceive located in io c can be used as templates and guides CYASSL_USER_I0O can be defined to remove the automatic setting of the default I O functions EmbedSend
187. noFilesystem this makes it easier to disable filesystem use This option defines NO_FILESYSTEM nolnline enabling this option disables function inlining in CyaSSL ecc enabling this option will build ECC support and cipher suites into CyaSSL 21 ocsp enabling this option adds OCSP Online Certificate Status Protocol support to CyaSSL crl enabling this option adds CRL Certificate Revocation List support to CyaSSL crl monitor enabling this option adds the ability to have CyaSSL actively monitor a specific CRL Certificate Revocation List directory ntru this turns on the ability for CyaSSL to use NTRU cipher suites NTRU is now available under the GPLv2 from Security Innovation The NTRU bundle may be downloaded from the Security Innovation GitHub repository available at https github com NTRUOpenSourceProject ntru crypto sni enabling this option will turn on the TLS Server Name Indication SNI extension maxfragment enabling this option will turn on the TLS Maximum Fragment Length extension truncatedhmac enabling this option will turn on the TLS Truncated HMAC extension supportedcurves enabling this option will turn on the TLS Supported ECC Curves extension tlsx enabling this option will turn on all TLS extensions currently supported by CyaSSL valgrind enabling this option will turn on valgrind when running the CyaSSL unit tests This can be useful for catching problems early on in the d
188. nopsis void CyaSSL_SetlIOReadFlags CYASSL ssl int flags 193 Description This function sets the flags for the receive callback to use for the given SSL session The receive callback could be either the default CyaSSL EmbedReceive callback or a custom callback specified by the user see CyaSSL_SetlORecv The default flag value is set internally by CyaSSL to the value of 0 The default CyaSSL receive callback uses the recv function to receive data from the socket From the recv man page The flags argument to a recv function is formed by or ing one or more of the values MSG _OOB process out of band data MSG PEEK peek at incoming message MSG_WAITALL wait for full request or error The MSG_OOB flag requests receipt of out of band data that would not be received in the normal data stream Some protocols place expedited data at the head of the normal data queue and thus this flag cannot be used with such protocols The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue Thus a subsequent receive call will return the same data The MSG_WAITALL flag requests that the operation block until the full request is satisfied However the call may still return less data than requested if a signal is caught an error or disconnect occurs or the next data to be received is of a different type than that returned Return Values No return values
189. ns both the original and completed source code for both the echoserver and echoclient used in this tutorial Specific contents are listed below the link http www wolfssl com documentation ssl tutorial 2 2 zip The downloaded ZIP file has the following structure include Common header file Modified from unp h in the book lib Common library functions finished srce echoclient The completed echoclient code echoserver The completed echoserver code original sre 102 echoclient The starting echoclient code echoserver The starting echoserver code CyaSSL_ SSL Tutorial pdf 11 4 Base Example Modifications 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 support wolfssl com The following is a list of modifications that were made to the original echoserver and echoclient examples found in the above listed book Modifications to the echoserver tcpserv04 c e Removed call to the Fo
190. ns when CyaSSL has been compiled with OCSP support enable ocsp define HAVE_OCSP Return Values SSL_SUCCESS is returned upon success SSL_FAILURE is returned upon failure NOT_COMPILED_IN is returned when this function has been called but OCSP support was not enabled when CyaSSL was compiled Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new options value used to set the OCSP options Example CYASSL_ CTX ctx 0 228 CyaSSL_CTX_OCSP_set_options ctx CYASSL OCSP_ ENABLE See Also CyaSSL_CTX_OCSP_set_override_url CyaSSL_CTX_SetOCSP_OverrideURL Synopsis int CyaSSL_CTX_SetOCSP_OverrideURL CYASSL_CTX ctx const char url Description This function manually sets the URL for OCSP to use By default OCSP will use the URL found in the individual certificate unless the CYASSL_OCSP_URL_OVERRIDE option is set using the CyaSSL_CTX_EnableOCSP Return Values SSL_SUCCESS is returned upon success SSL_FAILURE is returned upon failure NOT_COMPILED_IN is returned when this function has been called but OCSP support was not enabled when CyaSSL was compiled Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new url pointer to the OCSP URL for CyaSSL to use Example CYASSL_ CTX ctx 0 CyaSSL_CTX_OCSP_set_override url ctx custom url here See Also CyaSSL_CTX_OCSP_set_options 229 17 7 Informational The functions in th
191. nt verify Description Allows caller to set the Hmac Inner vector for message sending receiving The result is written to inner which should be at least CyaSSL_GetHmacSize bytes The size of the message is specified by sz content is the type of message and verify specifies whether this is a verification of a peer message Valid for cipher types excluding CYASSL_AEAD_TYPE Return Values If successful the call will return 1 BAD_FUNC_ARG will be returned for an error state See Also CyaSSL_GetBulkCipher CyaSSL_GetHmacType CyaSSL_CTX_SetMacEncryptCb Synopsis include lt cyassl ssl h gt void CyaSSL_CTX_SetMacEncryptCb CYASSL_CTX CallbackMacEncrypt typedef int CallbackMacEncrypt CYASSL ssl unsigned char macOut const unsigned char macin unsigned int maclnSz int macContent int macVerify unsigned char encOut const unsigned char enclin unsigned int encSz void ctx Description Allows caller to set the Atomic User Record Processing Mac Encrypt Callback The callback should return 0 for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience macOut is the output buffer where the result of the mac should be stored macln is the mac input buffer and macInSz notes the size of the buffer macContent and macVerify are needed for CyaSSL_SetTlsHmacinner and be passed along as is encOut is the output buffer where the result on the encryption should be stored enclin
192. nteger math library This is generally the most portable and generally easiest to get going with The negatives to the normal big integer library are that it is slower and it uses a lot of dynamic memory This option switches the big integer library to a faster one that uses assembly if possible Assembly inclusion is dependent on compiler and processor combinations Some combinations will need additional configure flags and some may not be possible Help with optimizing fastmath with new assembly routines is available on a consulting basis On ia32 for example all of the registers need to be available so high optimization and omitting the frame pointer needs to be taken care of CyaSSL will add O3 fomit frame pointer to GCC for non debug builds If you re using a different compiler you may need to add these manually to CFLAGS during configure OS X will also need mdynamic no pic added to CFLAGS In addition if you re building in shared mode for ia32 on OS X you ll need to pass options to LDFLAGS as well LDFLAGS W1 read_only relocs warning This gives warning for some symbols instead of errors 18 fastmath also changes the way dynamic and stack memory is used The normal math library uses dynamic memory for big integers fastmath uses fixed size buffers that hold 4096 bit integers by default allowing for 2048 bit by 2048 bit multiplications If you need 4096 bit by 4096 bit multiplications then change FP_MAX_BITS in cyassl ctaoc
193. o issuer C US 0O Google Inc CN Google Internet Authority subject C US ST California L Mountain View 0O Google Inc CN google com altname googleapis cn altname gstatic com altname g co altname goo gl altn 3 oO II cloud google com altn 3 0 Il google analytics com altn 3 oO II google analytics com altn urchin com 3 0 II altn surchin com 3 oO II altn 3 oO II x url google com altn 3 oO lI googlecommerce com altn 3 0 Il googlecommerce com altn android com 3 oO II android com google com tr google com vn altn altn 3 0 II altn 3 0 Il altn 3 oO II x google com co 2585858585388585 855885885885895358588585853885855353938 oO II altname google com ar altname google com mx altname google hu altname google co jp altname google com au altname google nl altname google pl altname google cl altname google de altname google it 27 altname google pt altname google fr altname google ca altname google co uk altname google es altname google co in altname google com br altname ytimg com altname youtu be altname youtube nocookie com altname youtube com altname youtube com altname google com altname google com serial number 40 98 6 53 00 00 0
194. oes not allow the loading of CA certificates from a given directory path Note that this function is only available when the CyaSSL library was compiled with CYASSL_DER_LOAD defined Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned upon failure Parameters ctx a pointer to a CYASSL_CTX structure created using CyaSSL_CTX_new file a pointer to the name of the file containing the CA certificates to be loaded into the 150 CyaSSL SSL context with format as specified by format format the encoding type of the certificates specified by file Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1 Example int ret 0 CYASSL CTX ctx ret CyaSSL CTX der load verify locations ctx ca cert der SSL_FILETYPE ASN1 if ret SSL SUCCESS error loading CA certs See Also CyaSSL_CTX_load_verify_locations CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_NTRUPrivateKey _file Synopsis include lt cyassl ssl h gt int CyaSSL_CTX_use_NTRUPrivateKey_file CYASSL_CTX ctx const char file Description This function loads an NTRU private key file into the CYASSL Context It behaves like the normal version only differing in its ability to accept an NTRU raw key file This function is needed since the format of the file is different than the normal key file buffer functions Please see the examples for proper usage
195. oint the application may call CyaSSL_connect and CyaSSL will try to resume the session The CyaSSL server code allows session resumption by default Return Values 183 SSL_SUCCESS will be returned upon successfully setting the session SSL_FAILURE will be returned on failure This could be caused by the session cache being disabled or if the session has timed out Parameters ssl pointer to the SSL object created with CyaSSL_new session pointer to the CYASSL_SESSION used to set the session for ssl Example int ret 0 CYASSL ssl 0 CYASSL_ SESSION session ret CyaSSL_ get_session ssl session if ret SSL SUCCESS failed to set the SSL session See Also CyaSSL_get_session CyaSSL_CTX_set_session_cache_mode Synopsis long CyaSSL_CTX_set_session_cache_mode CYASSL_CTX ctx long mode Description This function enables or disables SSL session caching Behavior depends on the value used for mode The following values for mode are available SSL_SESS_CACHE_OFF disable session caching Session caching is turned on by default SSL_SESS_CACHE NO AUTO CLEAR 184 Disable auto flushing of the session cache Auto flushing is turned on by default Return Values SSL_SUCCESS will be returned upon success Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new mode modifier used to change behavior of the session cache Example CYASSL CTX ctx
196. ome embedded system may not have this type available sessioncerts enabling this option adds support for the peer s certificate chain in the session cache through the CyaSSL_get_peer_chain CyaSSL_get_chain_count CyaSSL_get_chain_length CyaSSL_get_chain_cert CyaSSL_get_chain_cert_pem and CyaSSL_get_sessionID functions keygen enabling support for RSA key generation allows generating keys of varying lengths up to 4096 bits CyaSSL provides both DER and PEM formatting certgen enables support for self signed X 509 v3 certificate generation certreq enabling this option will add support for certificate request generation hc128 Though we really like the speed of the HC 128 steaming cipher it takes up some room in the cipher union for users who aren t using it To keep the default build small in as many aspects as we can we ve disabled this cipher by default In order to use this cipher or the corresponding cipher suite just turn it on no other action is required rabbit enabling this option adds support for the RABBIT stream cipher psk Pre Shared Key support is off by default since its not commonly used To enable this feature simply turn it on no other action is required poly1305 enabling this option adds support for Poly1305 to CTaocrypt and CyaSSL webServer this turns on functions required over the standard build that will allow full functionality for building with the yaSSL Embedded Web Server
197. on loads a certificate buffer into the CYASSL Context It behaves like the non buffered version only differing in its ability to be called with a buffer as input instead of a file The buffer is provided by the in argument of size sz format specifies the format type of the buffer SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new 139 in the input buffer containing the certificate to be loaded sz the size of the input buffer format the format of the certificate located in the input buffer in Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int ret 0 int sz 0 CYASSL CTX ctx byte certBuff ret CyaSSL CTX_use certificate buffer ctx certBuff sz SSL FILETYPE PEM if ret SSL SUCCESS error loading certificate from buffer See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_CTX_use_certificate_chain_buffer CyaSSL_use_certificate_b
198. ools ietf org html rfc1321 RIPEMD 160 http homes esat kuleuven be bosselae ripemd160 html B 5 Public Key Cryptography Diffie Hellman http en wikipedia org wiki Diffie Hellman_key exchange RSA http people csail mit edu rivest Rsapaper pdf http en wikipedia org wiki RSA DSA DSS http csrc nist gov publications fips fips186 3 fips 186 3 pdf NTRU http securityinnovation com cryptolab X 509 http www ietf org rfc rfc3279 txt ASN 1 http luca ntop org Teaching Appunti asn1 html http en wikipedia org wiki Abstract_Syntax_Notation One PSK http tools ietf org html rfc4279 B 6 Other PKCS 5 PBKDF1 PBKDF2 http tools ietf org html rfc2898 PKCS 8 http tools ietf org html rfc5208 PKCS 12 http www rsa com rsalabs node asp id 2138 Appendix C Error Codes C 1 CyaSSL Error Codes Copyright 2014 wolfSSL Inc All rights reserved 312 CyaSSL error codes can be found in cyassl ssl h For detailed descriptions of the following errors see the OpenSSL man page for SSL_get_error man SSL_get_error Error Code Enum Error Description SSL_ERROR_WANT_READ SSL_ERROR_WANT_WRITE SSL_ERROR_WANT_CONNECT SSL_ERROR_WANT_ACCEPT SSL_ERROR_SYSCALL Additional CyaSSL error codes can be found in cyassl error ssl h 313 FATAL_ERROR ENCRYPT_ERROR FREAD_ERROR NO_PEER_KEY NO_PRIVATE_KEY RSA_PRIVATE_ERROR NO_DH_PARAMS BUILD_MSG_ ERROR BAD_HELLO DOMAIN_NAME_MISMATCH WANT_
199. ors_fp FILE fp int err Description This function converts an error code returned by CyaSSL_get_error into a more human readable error string and prints that string to the output file fp err is the error code returned by CyaSSL_get_error and fp is the file which the error string will be 221 placed in Return Values This function has no return value Parameters fp output file for human readable error string to be written to e error code returned by CyaSSL_get_error Example int err 0 CYASSL ssl FILE fp err CyaSSL get_error ssl 0 CyaSSL ERR print_errors_fp fp err See Also CyaSSL_get_error CyaSSL_ERR_error_string CyaSSL_ERR_error_string_n CyaSSL_load_error_strings CyaSSL_get_error Synopsis include lt cyassl ssl h gt int CyaSSL_get_error CYASSL ssl int ret Description This function returns a unique error code describing why the previous API function call CyaSSL_connect CyaSSL_accept CyaSSL_read CyaSSL_write etc resulted in an error return code SSL_FAILURE The return value of the previous function is passed to CyaSSL_get_error through ret After CyaSSL_get_error is called and returns the unique error code 222 CyaSSL_ERR_error_string may be called to get a human readable error string See CyaSSL_ERR_error_string for more information Return Values On successful completion this function will return the unique error code describing why
200. ortedCurve ctx CYASSL ECC_SECP256R1 if ret 0 Elliptic Curve Extension usage failed See Also CyaSSL_CTX_new CyaSSL_UseSupportedCurve CyaSSL_UseSupportedCurve Synopsis include lt cyassl ssl h gt int CvaSSL_UseSupportedCurve CYASSL ssl unsigned short name Description This function is called on the client side to enable the use of Supported Elliptic Curves Extension in the SSL object passed in the ssl parameter It means that the supported 305 curves enabled will be sent on ClientHello by CyaSSL clients This function can be called more than one time to enable multiple curves Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned in one of these cases ssl is NULL name is a unknown value see below MEMORY_E is the error returned when there is not enough memory Parameters ssl pointer to a SSL object created with CyaSSL_new name indicates which curve will be supported for the session The available options are enum CYASSL_ECC_SECP160R1 0x10 CYASSL_ECC_SECP192R1 0x13 CYASSL_ECC_SECP224R1 0x15 CYASSL_ECC_SECP256R1 0x17 CYASSL_ECC_SECP384R1 0x18 CYASSL_ECC_SECP521R1 0x19 Example int ret 0 CYASSL_CTX ctx 0 CYASSL ssl 0 ctx CyaSSL CTX_ new method if ctx NULL context creation failed ssl CyaSSL_new ctx if ssl NULL 306 ssl creation fa
201. ory condition occurs Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new file a pointer to the name of the file containing the RSA private key to be loaded into the CyaSSL SSL session with format as specified by format format the encoding type of the RSA private key specified by file Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1 Example int ret 0 CYASSL ssl ret CyaSSL_ use RSAPrivateKey file ssl server key pem SSL FILETYPE PEM if ret SSL SUCCESS error loading private key file 288 See Also CyaSSL_CTX_use_RSAPrivateKey_file CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_PrivateKey_file CyaSSL_use_PrivateKey_buffer CyaSSL_use_PrivateKey_file 17 13 TLS Extensions The functions in this section are specific to supported TLS extensions CyaSSL_CTX_UseSNI Synopsis include lt cyassl ssl h gt int CyaSSL_CTX_UseSNI CYASSL_CTX ctx unsigned char type const void data unsigned short size Description This function enables the use of Server Name Indication for SSL objects created from the SSL context passed in the ctx parameter It means that the SNI extension will be sent on ClientHello by CyaSSL clients and CyaSSL servers will respond ClientHello SNI with either ServerHello blank SNI or alert fatal in case of SNI mismatch Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_AR
202. ou ll also need to add ctaocrypt src misc c to the list of compiled files if you re not using autoconf NO_DEV_RANDOM disables the use of the default dev random random number generator If defined the user needs to write an OS specific GenerateSeed function found in ctaocrypt src random c NO_MAIN_DRIVER is used in the normal build environment to determine whether a test application is called on its own or through the testsuite driver application You ll only need to use it with the test files test c client c server c echoclient c echoserver c and testsuite c NO_WRITEV disables simulation of writev semantics SINGLE_THREADED is a switch that turns off the use of mutexes CyaSSL currently only uses one for the session cache If your use of CyaSSL is always single threaded you can turn this on USER_TICKS allows the user to define their own clock tick function if time 0 is not wanted Custom function needs second accuracy but doesn t have to be correlated to EPOCH See LowResTimer function in cyassl_int c USER_TIME disables the use of time h structures in the case that the user wants or needs to use their own See ctaocrypt src asn c for implementation details 10 The user will need to define and or implement XTIME XGMTIME and XVALIDATE_DATE USE_CERT_BUFFERS_1024 enables 1024 bit test certificate and key buffers located in lt cyassl_root gt cyassl certs_test h Helpful when testing on an
203. parameters we ll work closely with you to make recommendations on how to implement CyaSSL into your application such that it provides you with optimal security If you would like to learn more about design consulting for building SSL into your application or device please contact info wolfss com for more information 128 Chapter 16 CyaSSL Updates 16 1 Product Release Information We regularly post update information on Twitter For additional release information you can keep track of our projects on Freshmeat follow us on Facebook or follow our daily blog CyaSSL on Freshmeat http freshmeat net projects cyassl wolfSSL on Twitter http twitter com wolfSSL wolfSSL on Facebook http www facebook com wolfSSL Daily Blog http wolfssl com yaSSL Blog Blog html Chapter 17 CyaSSL API Reference 17 1 Initialization Shutdown The functions in this section have to do with initializing the CyaSSL library and shutting it down freeing resources after it is no longer needed by the application CyaSSL_Init Synopsis include lt cyassl ssl h gt int CyaSSL_Init void Description Initializes the CyaSSL library for use Must be called once per application and before any other call to the library Return Values If successful the call will return SSL_SUCCESS 129 BAD_MUTEX_ERROR is an error that may be returned Parameters This function has no parameters Example int ret 0 ret Cya
204. pecified by file Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1 Example int ret 0 CYASSL_CTX ctx ret CyaSSL CTX use RSAPrivateKey file ctx server key pem SSL FILETYPE PEM if ret SSL SUCCESS error loading private key file See Also CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_PrivateKey_file CyaSSL_use_RSAPrivateKey_file CyaSSL_use_PrivateKey_buffer CyaSSL_use_PrivateKey_file 283 CyaSSL_use_certificate_file Synopsis include lt cyassl ssl h gt int CyaSSL_use_certificate_file CYASSL ssl const char file int format Description This function loads a certificate file into the SSL session CYASSL structure The certificate file is provided by the file argument The format argument specifies the format type of the file either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned If the function call fails possible causes might include The file is in the wrong format or the wrong format has been given using the format argument file doesn t exist can t be read or is corrupted an out of memory condition occurs Base16 decoding fails on the file Parameters ssl a pointer to a CYASSL structure created with CyaSSL_new file a pointer to the name of the file containing the certificate to be loaded into the CyaSSL SSL s
205. plications should call CyaSSL_I nit before using the library and call CyaSSL_Cleanup at program termination Currently these functions only initialize and free the shared mutex for the session cache in multi user mode but in the future they may do more so it s always a good idea to use them 9 3 Structure Usage In addition to header file location changes the release of CyaSSL 2 0 0 RC3 created a more visible distinction between the native CyaSSL API and the CyaSSL OpenSSL Compatibility Layer With this distinction the main SSL TLS structures used by the native CyaSSL API have changed names The new structures are as follows The previous names are still used when using the OpenSSL Compatibility Layer see Chapter 13 CYASSL previously SSL CYASSL CTX previously SSL CTX CYASSL METHOD previously SSL METHOD CYASSL SESSION previously SSL SESSION CYASSL_ X509 previously X509 83 CYASSL X509 NAME previously X509 NAME CYASSL_ X509 CHAIN previously X509 CHAIN 9 4 Thread Safety CyaSSL is thread safe by design Multiple threads can enter the library simultaneously without creating conflicts because CyaSSL avoids global data static data and the sharing of objects The user must still take care to avoid potential problems in two areas 1 A client may share an CYASSL object across multiple threads but access must be synchronized i e trying to read write at the same time from two different threads with th
206. ply flags if input gt 0 input number of bytes returned into buffer reply See Also CyaSSL_read CyaSSL_write CyaSSL_peek CyaSSL_pending 254 CyaSSL_send Synopsis include lt cyassl ssl h gt int CyaSSL_send CYASSL ssl const void data int sz int flags Description This function writes sz bytes from the buffer data to the SSL connection ssl using the specified flags for the underlying write operation If necessary CyaSSL_send will negotiate an SSL TLS session if the handshake has not already been performed yet by CyaSSL_connect or CyaSSL_accept CyaSSL_send works with both blocking and non blocking I O When the underlying I O is non blocking CyaSSL_send will return when the underlying I O could not satisfy the needs of of CyaSSL_send to continue In this case a call to CyaSSL_get_error will yield either SSL_LERROR_WANT_READ or SSL_ERROR_WANT_WRITE The calling process must then repeat the call to CyaSSL_send when the underlying I O is ready If the underlying I O is blocking CyaSSL_send will only return once the buffer data of size sz has been completely written or an error occurred Return Values gt 0 the number of bytes written upon success 0 will be returned upon failure Call CyaSSL_get_error for the specific error code SSL_FATAL_ERROR will be returned upon failure when either an error occurred or when using non blocking sockets the SSL_ERROR_WANT_R
207. r the functions in 4 2 should be modified by removing the Cya prefix For example the native CyaSSL API function CyaSSLv3 client _method Becomes SSLv3_client_method When an SSL connection is no longer needed the following calls free the structures created during initialization SSL CTX free ctx SSL free ssl SSL_CTX_free has the additional responsibility of freeing the associated SSL_METHOD Failing to use the XXX_free functions will result in a resource leak Using the system s free instead of the SSL ones results in undefined behavior Once an application has a valid SSL pointer from SSL_new the SSL handshake process can begin From the client s view SSL_connect will attempt to establish a secure connection SSL set _fd ssl sockfd SSL connect ssl 123 Before the SSL_connect can be issued the user must supply CyaSSL with a valid socket file descriptor sockfd in the example above sockfd is typically the result of the TCP function socket which is later established using TCP connect The following creates a valid client side socket descriptor for use with a local CyaSSL server on port 11111 error handling is omitted for simplicity int sockfd socket AF INET SOCK STREAM 0 sockaddr _in servaddr memset amp servaddr 0 sizeof servaddr servaddr sin family AF_INET servaddr sin port htons 11111 servaddr sin_ addr s addr inet_addr 127 0 0 1 conn
208. r end of line EOL and have no end of file EOF marker Apple Operating Systems use carriage returns CRs for EOLs and most PC operating systems use CR LF for EOLs and control Z for EOF In addition IBM mainframes and the Michigan Terminal System use EBCDIC rather than the more common ASCII character set and NT supports Unicode NOTE Beginning with the release of CyaSSL 2 0 0rc3 the directory structure of CyaSSL was changed as well as the standard install location These changes were made to make it easier for open source projects to integrate CyaSSL For more information on header and structure changes please see sections 9 1 and 9 3 2 2 Building on nix When building CyaSSL on Linux BSD OS X Solaris or other nix like systems use the autoconf system To build CyaSSL you only need to run two commands configure make You can append any number of build options to configure For a list of available build options please see Section 2 5 or run configure help from the command line to see a list of possible options to pass to the configure script To build CyaSSL run make To install CyaSSL run make install You may need superuser privileges to install in which case precede the command with sudo sudo make install To test the build run the testsuite program from the root CyaSSL source directory testsuite testsuite test Or use autoconf to run the testsuite as well as the standard CyaSS
209. r is required to make use of the assembly code References and further reading on AES NI ordered from general to specific are listed below For information about performance gains with AES NI please see the third link to the Intel Software Network page AES Wikipedia http en wikipedia org wiki Advanced_ Encryption Standar d AES NI Wikipedia http en wikipedia org wiki AES instruction set AES NI Intel Software http software intel com en us articles intel advanced Network page encryption standard instructions aes ni 4 4 2 STM32F2 CyaSSL is able to use the STM32F2 hardware based cryptography and random number generator through the STM32F2 Standard Peripheral Library For necessary defines see the CYASSL_STM32F2 define in settings h The CYASSL_STM32F2 define enables STM32F2 hardware crypto and RNG support by default The defines for enabling these individually are STM32F2_CRYPTO for hardware crypto support and STM32F2_RNG for hardware RNG support Documentation for the STM32F2 Standard Peripheral Library can be found in the following document http www st com internet com TECHNICAL RESOURCES TECHNICAL LITERATUR E USER_MANUAL DM00023896 pdf 4 4 3 Cavium NITROX CyaSSL has support for Cavium NITROX http Awww cavium com processor_security html To enable Cavium NITROX support when building CyaSSL use the following configure option 56 configure with cavium home user cavium softwa
210. r string matching errNumber Example int err 0 CYASSL ssl char buffer 80 err CyaSSL_ get_error ssl 0 CyaSSL_ERR_error string err buffer printf err d s n err buffer See Also CyaSSL_get_error CyaSSL_ERR_error_string_n CyaSSL_ERR_print_errors_fp CyaSSL_load_error_strings CyaSSL_ERR_error_string_n Synopsis include lt cyassl ssl h gt void CyaSSL_ERR_error_string_n unsigned long e char buf unsigned long len Description This function is a version of CyaSSL_ERR_error_string where len specifies the maximum number of characters that may be written to buf Like CyaSSL_ERR_error_string this function converts an error code returned from CyaSSL_get_error into a more human readable error string The human readable 220 string is placed in buf Return Values This function has no return value Parameters e error code returned by CyaSSL_get_error buff output buffer containing human readable error string matching e len maximum length in characters which may be written to buf Example int err 0 CYASSL ssl char buffer 80 err CyaSSL_get_error ssl 0 CyaSSL_ERR_error string n err buffer 80 printf err d s n err buffer See Also CyaSSL_get_error CyaSSL_ERR_error_string CyaSSL_ERR_print_errors_fp CyaSSL_load_error_strings CyaSSL_ERR_print_errors_fp Synopsis include lt cyassl ssl h gt void CyaSSL_ERR_print_err
211. r will be written to with at most inOutSz bytes on input After the call if successful return of 0 inOutSz will hold the actual number of bytes written to buffer A full example is included cyassl test h 7 7 RSA Key Generation CyaSSL supports RSA key generation of varying lengths up to 4096 bits Key generation is off by default but can be turned on during the configure process with enable keygen or by defining CYASSL_KEY_GEN in Windows or non standard environments Creating 75 a key is easy only requiring one function from rsa h int MakeRsaKkey Rsakey key int size long e RNG rng Where size is the length in bits and e is the public exponent using 65537 is usually a good choice for e The following from ctaocrypt test test c gives an example creating an RSA key of 1024 bits Rsakey genkey RNG rng int ret InitRng amp rng InitRsakey amp genKey 0 ret MakeRsakKey amp genkKey 1024 65537 amp rng if ret 0 ret contains error The RsaKey genKey can now be used like any other RsaKey If you need to export the key CyaSSL provides both DER and PEM formatting in asn h Always convert the key to DER format first and then if you need PEM use the generic DerToPem function like this byte der 4096 int derSz RsaKeyToDer amp genKey der sizeof der if derSz lt 0 derSz contains error The buffer der now holds a DER format of the key To conver
212. re Where the with cavium option is pointing to your licensed cavium software directory Since Cavium doesn t build a library CyaSSL pulls in the cavium_common o file which gives a libtool warning about the portability of this Also if you re using the github source tree you ll need to remove the Wredundant decls warning from the generated Makefile because the cavium headers don t conform to this warning Currently CyaSSL supports Cavium RNG AES 3DES RC4 HMAC and RSA directly at the crypto layer Support at the SSL level is partial and currently just does AES 3DES and RC4 RSA and HMAC are slower until the Cavium calls can be utilized in non blocking mode The example client turns on cavium support as does the crypto test and benchmark Please see the HAVE_CAVIUM define 4 5 SSL Inspection Sniffer Beginning with the CyaSSL 1 5 0 release CyaSSL has included a build option allowing it to be built with SSL Sniffer SSL Inspection functionality This means that you can collect SSL traffic packets and with the correct key file are able to decrypt them as well The ability to inspect SSL traffic can be useful for several reasons some of which include Analyzing Network Problems Detecting network misuse by internal and external users Monitoring network usage and data in motion Debugging client server communications To enable sniffer support build CyaSSL with the enable sniffer option on nix or use the veproj file
213. re Calling this function before CyaSSL_connect or CyaSSL_accept will add a domain name check to the list of checks to perform dn holds the domain name to check against the peer certificate when it s received Return Values If successful the call will return SSL_SUCCESS SSL_FAILURE will be returned if a memory error was encountered Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new dn domain name to check against the peer certificate when received Example int ret 0 CYASSL ssl char domain char www yassl com ret CyaSSL_ check domain_name ssl domain if ret SSL SUCCESS failed to enable domain name check See Also NA CyaSSL_set_cipher_list Synopsis include lt cyassl ssl h gt int CyaSSL_set_cipher_list CYASSL ssl const char list 173 Description This function sets cipher suite list for a given CYASSL object SSL session The ciphers in the list should be sorted in order of preference from highest to lowest Each call to CyaSSL_set_cipher_list resets the cipher suite list for the specific SSL session to the provided list each time the function is called The cipher suite list list is a null terminated text string and a colon delimited list For example one value for list may be DHE RSA AES256 SHA256 DHE RSA AES128 SHA256 AES256 SHA256 Valid cipher values are the full name values from the cipher_names array in src internal c
214. reated using CyaSSL_new version SSL TLS protocol version Possible values include CYASSL_SSLV3 CYASSL_TLSV1 CYASSL_TLSV1_1 CYASSL_TLSV1_ 2 Example int ret 0 CYASSL ssl ret CyaSSL SetVersion ssl CYASSL TLSV1 if ret SSL SUCCESS failed to set SSL session protocol version See Also CyaSSL_CTX_new 171 CyaSSL_use_old_poly Synopsis include lt cyassl ssl h gt int CyaSSL_use_old_poly CYASSL ssl int flag Description Since there is some differences between the first release and newer versions of chacha poly AEAD construction we have added an option to communicate with servers clients using the older version By default CyaSSL uses the new version Return Values If successful the call will return 0 Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new flag whether or not to use the older version of setting up the information for poly1305 Passing a flag value of one indicates yes use the old poly AEAD to switch back to using the new version pass a flag value of 0 Example int ret 0 CYASSL ssl ret CyaSSL_use old poly ssl 1 if ret 13 0 failed to set poly1305 AEAD version CyaSSL_check_domain_name Synopsis include lt cyassl ssl h gt int CyaSSL_check_domain_name CYASSL ssl const char dn 172 Description CyaSSL by default checks the peer certificate for a valid date range and a verified signatu
215. rectory to the echoclient directory and run the following command Note that the echoserver must already be running echoclient 127 0 0 1 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 Ctrl C 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 11 7 Libraries The CyaSSL library once compiled is named libcyassl and unless otherwise configured the CyaSSL 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 usr local lib The first step we need to do is link the CyaSSL library to our example applications Modifying the GCC command using the echoserver as an example gives us the following new command Since CyaSSL installs header files and libraries in standard locations the compiler should be able to find them without explicit instructions using l or L Note that by using lcyassl the compiler will automatically choose the correct type of library static or shared gcc o echoserver lib c tcpserv 4 c I include lm lcyassl 1
216. reference the RFC specification mentioned SSL 3 0 This protocol was released in 1996 but began with the creation of SSL 1 0 developed by Netscape Version 1 0 wasn t released and version 2 0 had a number of security flaws thus leading to the release of SSL 3 0 Some major improvements of SSL 3 0 over SSL 2 0 are e Separation of the transport of data from the message layer e Use of a full 128 bits of keying material even when using the Export cipher e Ability of the client and server to send chains of certificates thus allowing organizations to use certificate hierarchy which is more than two certificates deep e Implementing a generalized key exchange protocol allowing Diffie Hellman and Fortezza key exchanges as well as non RSA certificates e Allowing for record compression and decompression e Ability to fall back to SSL 2 0 when a 2 0 client is encountered TLS 1 0 This protocol was first defined in RFC 2246 in January of 1999 This was an upgrade from SSL 3 0 and the differences were not dramatic but they are significant enough that SSL 3 0 and TLS 1 0 don t interoperate Some of the major differences between SSL 3 0 and TLS 1 0 are e Key derivation functions are different e MACs are different SSL 3 0 uses a modification of an early HMAC while TLS 1 0 uses HMAC e The Finished messages are different e TLS has more alerts e TLS requires DSS DH support TLS 1 1 This protocol was defined in RFC 4346 in April of 2006
217. rify_callback Example 189 CYASSL ssl 0 CyaSSL_set_verify ssl SSL VERIFY PEER SSL VERIFY FAIL IF NO PEER CERT 0 See Also CyaSSL_CTX_set_verify CyaSSL_CTX_set_verify Synopsis void CyaSSL_CTX_set_verify CYASSL_CTX ctx int mode VerifyCallback vc typedef int VerifyCallback int CYASSL_X509_STORE_CTX Description This function sets the verification method for remote peers and also allows a verify callback to be registered with the SSL context The verify callback will be called only when a verification failure has occurred If no verify callback is desired the NULL pointer can be used for verify_callback The verification mode of peer certificates is a logically OR d list of flags The possible flag values include SSL_VERIFY_NONE Client mode the client will not verify the certificate received from the server and the handshake will continue as normal Server mode the server will not send a certificate request to the client As such client verification will not be enabled SSL_VERIFY_PEER Client mode the client will verify the certificate received from the server during the handshake This is turned on by default in CyaSSL therefore using this option has no effect Server mode the server will send a certificate request to the client and verify the 190 client certificate received SSL_VERIFY_FAIL_IF_NO PEER_CERT Client mode no effect when used o
218. rk function because fork 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 e Moved str_echo function from str_echo c file into tcpserv04 c file e Added a printf statement to view the client address and the port we have connected through printf Connection from s port d n inet_ntop AF_INET amp cliaddr sin_addr buff sizeof buff ntohs cliaddr sin_port e Added a call to setsockopt after creating the listening socket to eliminate the Address already in use bind error Minor adjustments to clean up newer compiler warnings 103 Modifications to the echoclient tcpcli01 c e Moved str_cli function from str_cli c file into tcpcli01 c file e Minor adjustments to clean up newer compiler warnings Modifications to unp h header e This header was simplified to contain only what is needed for this example Please note that in these source code examples certain functions will be capitalized For example Fputs and Writen 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 Section 1 4 page 11 in the Unix Network Programming book 11 5 Building and Installing CyaSSL Before we begin download the example code echoserver and echoclient from the Getting t
219. rn 0 for success or lt 0 for an error The ssl and ctx pointers are available for the users convenience decOut is the output buffer where the result of the decryption should be stored decin is the encrypted input buffer and decInSz notes the size of the buffer content and verify are needed for CyaSSL_SetTlsHmaclInner and be passed along as is padSz is an output variable that should be set with the total value of the padding That is the mac size plus any padding and pad bytes An example callback can be found cyassl test h myDecryptVerifyCb Return Values NA See Also CyaSSL_SetMacEncryptCtx CyaSSL_GetMacEncryptCtx 207 CyaSSL_SetDecryptVerifyCtx Synopsis include lt cyassl ssl h gt void CyaSSL_SetDecryptVerifyCtx CYASSL void ctx Description Allows caller to set the Atomic User Record Processing Decrypt Verify Callback Context to ctx Return Values NA See Also CyaSSL_CTX_SetDecryptVerifyCb CyaSSL_GetDecryptVerifyCtx CyaSSL_GetDecryptVerifyCtx Synopsis include lt cyassl ssl h gt void CyaSSL_GetDecryptVerifyCtx CYASSL Description Allows caller to retrieve the Atomic User Record Processing Decrypt Verify Callback Context previously stored with CyaSSL_SetDecryptVerifyCtx Return Values If successful the call will return a valid pointer to the context NULL will be returned for a blank context See Also CyaSSL_CTX_SetDecryptVerifyCb CyaSSL_SetDecryptVerifyCtx 20
220. ry for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values 164 If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method CYASSL CTX ctx method CyaTLSvl_ 2 server method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_server_method CyaTLSv1_server_method CyaTLSv1_1_server_method CyaDTLSv1_server_method CyaSSLv23_server_method CyaSSL_CTX_new CyaDTLSv1_client_method Synopsis CYASSL_METHOD CyaDTLSv1_client_method void Description The CyaDTLSv1_client_method function is used to indicate that the application is a client and will only support the DTLS 1 0 protocol This function allocates memory for and initializes anew CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values 165 If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method C
221. rypt tfm h As FP_MAX_BITS is increased this will also increase the runtime stack usage since the buffers used in the public key operations will now be larger A couple of functions in the library use several temporary big integers meaning the stack can get relatively large This should only come into play on embedded systems or in threaded environments where the stack size is set to a low value If stack corruption occurs with fastmath during public key operations in those environments increase the stack size to accommodate the stack usage If you are enabling fastmath without using the autoconf system you ll need to define USE_FAST_MATH and add tfm c to the CyaSSL build instead of integer c Since the stack memory can be large when using fastmath we recommend defining TFM_TIMING_RESISTANT when using the fastmath library This will get rid of large static arrays fasthugemath enabling fasthugemath includes support for the fastmath library and greatly increases the code size by unrolling loops for popular key sizes during public key operations Try using the benchmark utility before and after using fasthugemath to see if the slight speedup is worth the increased code size bigcache enabling the big session cache will increase the session cache from 33 sessions to 20 027 sessions The default session cache size of 33 is adequate for TLS clients and embedded servers The big session cache is suitable for servers that aren t under heavy load
222. s are required After filling in the subject information as before you ll need to set the issuer information from the CA certificate This can be done with Set ssuer like this ret SetIssuer amp myCert ca cert pem if ret lt 0 ret contains error Then you ll need to perform the two step process of creating the certificate and then signing it MakeSelfCert does these both in one step You ll need the private keys from both the issuer caKey and the subject key Please see the example in test c for complete usage byte derCert 4096 int certSz MakeCert amp myCert derCert sizeof derCert amp key NULL amp rng if certSz lt 0 certSz contains the error certSz SignCert myCert bodySz myCert sigType derCert sizeof derCert amp caKey NULL amp rng if certSz lt 0 certSz contains the error The buffer derCert now contains a DER format of the CA signed certificate If you need a PEM format of the certificate please see the self signed example above Note that MakeCert and SignCert provide function parameters for either an RSA or ECC key to be used The above example uses an RSA key and passes NULL for the ECC key parameter 80 7 9 Convert to raw ECC key With our recently added support for raw ECC key import comes the ability to convert an ecc key from PEM to DER Use the following with the specified arguments to accomplish this EccKeyToDer
223. s certificate the actual client or server cert followed by any intermediate certificates and ending optionally at the root top CA The example server examples server server c uses this functionality int CyaSSL CTX_use_ certificate chain _file CYASSL CTX ctx const char file 7 2 3 Loading Private Keys Server private keys can be loaded using the CyaSSL_CTX_use_PrivateKey_file function int CyaSSL_ CTX_use PrivateKey file CYASSL CTX ctx const char keyFile int type keyFile is the private key file and type is the format of the private key i e SSL_FILETYPE_PEM 7 3 Certificate Chain Verification CyaSSL requires that only the top or root certificate in a chain to be loaded as a trusted certificate in order to verify a certificate chain This means that if you have a certificate chain A gt B gt C where C is signed by B and B is signed by A CyaSSL only requires that certificate A be loaded as a trusted certificate in order to verify the entire chain A gt B gt C For example if a server certificate chain looks like So ornoa The CyaSSL client should already have at least the root cert A loaded as a trusted root When the client receives the server cert chain it uses the signature of A to verify 73 B and if B has not been previously loaded into CyaSSL as a trusted root B gets stored in CyaSSL s internal cert chain CyaSSL just stores what is necessary to verify a certifi
224. s into CyaSSL CyaSSL_CTX_load_verify_buffer Synopsis int CyaSSL_CTX_load_verify_buffer CYASSL_CTX ctx const unsigned char in long sz int format Description This function loads a CA certificate buffer into the CYASSL Context It behaves like the non buffered version only differing in its ability to be called with a buffer as input instead of a file The buffer is provided by the in argument of size sz format specifies the format type of the buffer SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM More than one CA certificate may be loaded per buffer as long as the format is in PEM Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file 133 BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new in pointer to the CA certificate buffer sz size of the input CA certificate buffer in format format of the buffer certificate either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM Example int ret 0 int sz 0 CYASSL CTX ctx byte certBuff ret CyaSSL CTX load verify buffer c
225. s on Windows You will need to have pcap installed on nix or WinPcap on Windows There are five main sniffer functions which can be found in sniffer h They are listed below with a short description of each ssl_SetPrivateKey Sets the private key for a specific server and port ss _DecodePacket Passes in a TCP IP packet for decoding ssl_Trace Enables Disables debug tracing to the traceFile ssl _InitSniffer Initialize the overall sniffer ssl_FreeSniffer Free the overall sniffer 57 To look at CyaSSL s sniffer support and see a complete example please see the snifftest app in the ssSniffer sslSnifferTest folder from the CyaSSL download Keep in mind that because the encryption keys are setup in the SSL Handshake the handshake needs to be decoded by the sniffer in order for future application data to be decoded For example if you are using snifftest with the CyaSSL example echoserver and echoclient the snifftest application must be started before the handshake begins between the server and client 4 6 Compression CyaSSL supports data compression with the zlib library The configure build system detects the presence of this library but if you re building in some other way define the constant HAVE_LIBZ and include the path to zlib h for your includes Compression is off by default for a given cipher To turn it on use the function CyaSSL_set_compression before SSL connecting or accepting Both the client and
226. s when calling XMALLOC the failure value of the underlying 158 malloc implementation will be returned typically NULL with errno will be set to ENOMEM Parameters This function has no parameters Example CYASSL METHOD method CYASSL CTX ctx method CyaSSLv23 server method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_server_method CyaTLSv1_server_method CyaTLSv1_1_server_method CyaTLSv1_2_ server_method CyaDTLSv1_server_method CyaSSL_CTX_new CyaTLSv1_client_method Synopsis CYASSL_METHOD CyaTLSv1_client_method void Description The CyaTLSv1_client_method function is used to indicate that the application is a client and will only support the TLS 1 0 protocol This function allocates memory for and initializes a new CYASSL_METHOD structure to be used when creating the SSL TLS context with CyaSSL_CTX_new Return Values 159 If successful the call will return a pointer to the newly created CYASSL_METHOD structure If memory allocation fails when calling XMALLOC the failure value of the underlying malloc implementation will be returned typically NULL with errno will be set to ENOMEM Example CYASSL METHOD method CYASSL CTX ctx method CyaTLSvl_ client _method if method NULL unable to get method ctx CyaSSL CTX new method See Also CyaSSLv3_client_method CyaTLSv1_1_client_method CyaTLSv
227. se enable debug or define DEBUG_CYASSL Return Values If successful this function will return 0 NOT_COMPILED_IN is the error that will be returned if logging isn t enabled for this build Parameters This function has no parameters Example 226 CyaSSL_ Debugging ON See Also CyaSSL_Debugging_OFF CyaSSL_SetLoggingCb CyaSSL_Debugging_OFF Synopsis include lt cyassl ssl h gt void CyaSSL_Debugging_OFF void Description This function turns off runtime logging messages If they re already off no action is taken Return Values No return values are returned by this function Parameters This function has no parameters Example CyaSSL_ Debugging OFF See Also CyaSSL_Debugging ON CyaSSL_SetLoggingCb 17 6 OCSP and CRL The functions in this section have to do with using OCSP Online Certificate Status Protocol and CRL Certificate Revocation List with CyaSSL 227 CyaSSL_CTX_EnableOCSP Synopsis long CyaSSL_CTX_EnableOCSP CYASSL_CTX ctx int options Description This function sets options to configure behavior of OCSP functionality in CyaSSL The value of options if formed by or ing one or more of the following options CYASSL_OCSP_ENABLE enable OCSP lookups CYASSL_OCSP_URL_OVERRIDE use the override URL instead of the URL in certificates The override URL is specified using the CyaSSL_CTX_SetOCSP_OverrideURL function This function only sets the OCSP optio
228. sed DSA test passed PWDBASED test passed OPENSSL test passed peer s cert info issuer C US ST Oregon L Portland O wolfSSL OU Programming CN www wolfs sl com emailAddress info yassl com subject C US ST Oregon L Portland O wolfSSL OU Programming CN www wolfs sl com emailAddress info yassl com serial number 87 4a 75 be 91 66 d8 3d SSL version is TLSv1 2 SSL cipher suite is TLS DHE RSA WITH AES 256 CBC SHA256 peer s cert info issuer C US ST Montana L Bozeman O Sawtooth OU Consulting CN www yassl com emailAddress info yassl com subject C US ST Montana L Bozeman O wolfSSL OU Support CN www wolfssl c om emailAddress info wolfssl com serial number 02 SSL version is TLSv1 2 SSL cipher suite is TLS DHE RSA WITH AES 256 CBC SHA256 25 Client message hello cyassl Server response I hear you fa shizzle sending server shutdown command quit client sent quit command shutting down 6cd8940c5e7229F9357cc15b202b593befbbc8e 6cd8940c5e7229 F9357cc15b202b593befbbc8e All tests passed a input a output This indicates that everything is configured and built correctly If any of the tests fail make sure the build system was set up correctly Likely culprits include having the wrong endianness or not properly setting the 64 bit type If you ve set anything to the non default settings try removing those rebuilding CyaSSL and then re testing 3 3 Client Example You can use the c
229. see section 3 8 A more complete walk through with example code is located in the SSL Tutorial in Chapter 11 1 2 Follow the instructions above for a client except change the client method call in step 5 to a server one so CyaSSL_ CTX new CyaTLSvils _client method becomes CyaSSL CTX new CyaTLSvl_ server method or even CyaSSL CTX new CyaSSLv23 server method To allow SSLv3 and TLSv1 clients to connect to the server Add the server s certificate and key file to the initialization in step 5 above if CyaSSL CTX use certificate file ctx server cert pem SSL FILETYPE PEM SSL SUCCESS fprintf stderr Error loading server cert pem please check the file n exit EXIT_FAILURE _ r if CyaSSL CTX use PrivateKey file ctx server key pem SSL FILETYPE PEM SSL SUCCESS fprintf stderr Error loading server key pem please check the file n exit EXIT_FAILURE lt r 39 It is possible to load certificates and keys from buffers as well if there is no filesystem available In this case see the CyaSSL_CTX_use_certificate_buffer and CyaSSL_CTX_use_PrivateKey_buffer API documentation for more information For an example of a server application using CyaSSL see the server example located in the lt cyassl_root gt examples server c file Chapter 4 Features CyaSSL supports the C pro
230. send flags for the specified SSL session ssl Example 195 CYASSL ssl 0 Manually setting send flags to 0 CyaSSL_ SetIOSendFlags ssl 0 See Also CyaSSL_SetlORecv CyaSSL_SetlOSend CyaSSL_SetlOReadCtx CyaSSL_SetlORecv Synopsis void CyaSSL_SetlORecv CYASSL_CTX ctx CallbacklORecv CBIORecv typedef int CallbacklORecv char buf int sz void ctx Description This function registers a receive callback for CyaSSL to get input data By default CyaSSL uses EmbedReceive as the callback which uses the system s TCP recv function The user can register a function to get input from memory some other network module or from anywhere Please see the EmbedReceive function in src io c as a guide for how the function should work and for error codes In particular 1O_ERR_WANT_READ should be returned for non blocking receive when no data is ready Return Values No return values are used for this function Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new callback function to be registered as the receive callback for the CyaSSL context ctx The signature of this function must follow that as shown above in the Synopsis section Example 196 CYASSL_ CTX ctx 0 Receive callback prototype int MyEmbedReceive CYASSL ssl char buf int sz void ctx Register the custom receive callback with CyaSSL CyaSSL_SetIORecv ctx MyEmbedReceive int MyEmbed
231. server must have compression turned on in order for compression to be used Keep in mind that while compressing data before sending decreases the actual size of the messages being sent and received the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks 4 7 Pre Shared Keys CyaSSL has support for two ciphers with pre shared keys TLS_PSK_WITH_AES 256 CBC_SHA TLS_PSK_WITH_AES 128 CBC_SHA256 TLS_PSK_WITH_AES 128 CBC_SHA TLS_PSK_WITH_NULL_SHA256 TLS_PSK_WITH_NULL_SHA TLS_PSK_WITH_AES 128 CCM TLS_PSK_WITH_AES 256 CCM TLS_PSK_WITH_AES 128 CCM_8 TLS_PSK_WITH_AES 256 CCM_8 58 These suites are automatically built into CyaSSL though they can be turned off at build time with the constant NO_PSK To only use these ciphers at runtime use the function CyaSSL_CTX_set_cipher_list with the desired ciphersuite On the client use the function CyaSSL_CTX_set_psk_client_callback to setup the callback The client example in lt CyaSSL_Home gt examples client client c gives example usage for setting up the client identity and key though the actual callback is implemented in cyassl test h On the server side two additional calls are required CyaSSL_CTX_set_psk_server_callback CyaSSL_CTX_use_psk_identity_hint The server stores it s identity hint to help the client with the 2nd call in our server example that s cyassl server An example server psk
232. sh _sessions ctx time 0 247 See Also CyaSSL_get_session CyaSSL_set_session CyaSSL_negotiate Synopsis include lt cyassl ssl h gt int CyaSSL_negotiate CYASSL ssl Description Performs the actual connect or accept based on the side of the SSL method If called from the client side then an CyaSSL_connect is done while a CyaSSL_accept is performed if called from the server side Return Values SSL_SUCCESS will be returned if successful Note older versions will return 0 SSL_FATAL_ERROR will be returned if the underlying call resulted in an error Use CyaSSL_get_error to get a specific error code Parameters ssl pointer to the SSL session created with CyaSSL_new Example int ret SSL FATAL ERROR CYASSL ssl 0 ret CyaSSL negotiate ssl if ret SSL FATAL ERROR SSL establishment failed int error code CyaSSL_ get_error ssl See Also SSL_connect 248 SSL_accept CyaSSL_peek Synopsis include lt cyassl ssl h gt int CyaSSL_peek CYASSL ssl void data int sz Description This function copies sz bytes from the SSL session ssl internal read buffer into the buffer data This function is identical to CyaSSL_read except that the data in the internal SSL session receive buffer is not removed or modified If necessary like CyaSSL_read CyaSSL_peek will negotiate an SSL TLS session if the handshake has not already been performed yet by CyaSS
233. sing Certificates Normally a file system is used to load private keys certificates and CAs Since CyaSSL is sometimes used in environments without a full file system an extension to use memory buffers instead is provided To use the extension define the constant NO_FILESYSTEM and the following functions will be made available int CyaSSL CTX load verify buffer CYASSL CTX const unsigned char 74 long int int CyaSSL_ CTX_use_ certificate buffer CYASSL CTX const unsigned char long int int CyaSSL CTX_use PrivateKey buffer CYASSL CTX const unsigned char long int int CyaSSL CTX use certificate chain buffer CYASSL CTX const unsigned char long Use these functions exactly like their counterparts that are named file instead of buffer And instead of providing a filename provide a memory buffer 7 5 1 Test Certificate and Key Buffers CyaSSL has come bundled with test certificate and key files in the past Now it also comes bundled with test certificate and key buffers for use in environments with no filesystem available These buffers are available in certs_test h when defining either USE_CERT_BUFFERS_1024 or USE_CERT_BUFFERS_2048 7 6 Serial Number Retrieval The serial number of an X 509 certificate can be extracted from CyaSSL using the following function The serial number can be of any length int CyaSSL_X509 get_serial number CYASSL X509 x509 unsigned char buffer int inOutSz buffe
234. sing the OpenSSL compatibility layer For the OpenSSL compatible functions please see Chapter 13 4 2 1 Server Functions CyaDTLSv1 server method void 7 7 DTLS 1 20 CyaDTLSvl_ 2_server method void I DERS A2 CyaSSLv3_ server _method void ff SST 340 CyaTLSvl_ server method void TLS 1 0 CyaTLSv1_1_ server method void PA TLS Let CyaTLSv1 2 server method void AI TbS L2 CyaSSLv23 server method void Use highest possible version from SSLv3 TLS 1 2 CyaSSL supports robust server downgrade with the CyaSSLv23_server_method function See section 4 2 3 for a details 4 2 2 Client Functions CyaDTLSvl1_client_method void DTLS 1 0 CyaDTLSv1_2 client method void Tif DENS I2 CyasSsSLv3_client_method void ff SSI 30 CyaTLSvl1l_ client method void TLS 1 0 CyaTLSv1 1 client method void TLS 1 1 CyaTLSv1 2 client_method void TLS 1 2 CyaSSLv23 client method void Use highest possible version from SSLv3 TLS 1 2 CyaSSL supports robust client downgrade with the CyaSSLv23_client_method function See section 4 2 3 for a details For details on how to use these functions please see the Getting Started Chapter For a comparison between SSL 3 0 TLS 1 0 1 1 1 2 and DTLS please see Appendix A 43 4 2 3 Robust Client and Server Downgrade Both CyaSSL clients and servers have robust version downgrade capability If a
235. sizeof cipher plain now contains the original plaintext from the cipher text 10 4 3 HC 128 Another stream cipher in current use is HC 128 which is even faster than RABBIT about 5 times faster than ARC4 To use it with CTaoCrypt please include the header cyassl ctaocrypt nc128 h HC 128 also uses 16 bytes keys 128 bits but uses 16 bytes vs 128 bits unlike RABBIT HC128 enc HC128 dec const byte key some key 16 bytes const byte iv some iv 16 bytes byte plain 37 no size restriction fill with data byte cipher 37 encrypt Hcl28 SetKey amp enc key iv iv can be a NULL pointer Hc128 Process amp enc cipher plain sizeof plain cipher now contains the cipher text from the plain text 94 decrypt Hc128 SetKey amp dec key iv Hc128 Process amp dec plain cipher sizeof cipher plain now contains the original plaintext from the cipher text 10 4 4 ChaCha yet to be released will be included in next release ChaCha with 20 rounds is slightly faster than ARC4 while maintaining a high level of security To use it with CTaoCrypt please include the header cyassl ctaocrypt chacha h ChaCha typically uses 32 byte keys 256 bit but can also use 16 byte keys 128 bits CHACHA enc CHACHA dec const byte key some key 32 bytes const byte iv some iv 12 bytes byte plain 37 no si
236. ssing If an existing timer is shorter than the passed timer the existing timer value is used It is still reset afterwards An existing timer that expires will be reset if has an interval associated with it The callback will only be issued if a timeout occurs See the client example for usage 6 3 User Atomic Record Layer Processing CyaSSL provides Atomic Record Processing callbacks for users who wish to have more control over MAC encrypt and decrypt verify functionality during the SSL TLS connection The user will need to define 2 functions 1 MAC encrypt callback function 2 Decrypt verify callback function These two functions are prototyped by CallbackMacEncrypt and CallbackDecryptVerify in ssl h typedef int CallbackMacEncrypt CYASSL ssl unsigned char macOut const unsigned char macIn unsigned int macInSz 68 int macContent int macVerify unsigned char encOut const unsigned char encIn unsigned int encSz VOLd CX typedef int CallbackDecryptVerify CYASSL ssl unsigned char decOut const unsigned char decIn unsigned int decSz int content int verify unsigned int padSz void ctx The user needs to write and register these functions per CyaSSL context CYASSL_CTX with CyaSSL_CTX_SetMacEncryptCb and CyaSSL_CTX_SetDecryptVerifyCb The user can set a context per CYASSL object session with CyaSSL_SetMacEncryptCtx and CyaSSL_SetDecryptVerifyCtx This context may be a poin
237. straction layers to make integrating SSL into your environment and platform as easy as possible With an OS layer a custom I O layer and a C Standard Library abstraction layer integration has never been so easy yaSSL offers several support packages for CyaSSL Available directly through phone email or the yaSSL product support forums your questions are answered quickly and accurately to help you make progress on your project as quickly as possible 13 3 Supported OpenSSL Structures SSL_METHOD holds SSL version information and is either a client or server method Same as CYASSL_METHOD in the native CyaSSL API SSL_CTX holds context information including certificates Same as CYASSL_CTX in the native CyaSSL API SSL holds session information for a secure connection Same as CYASSL in the native 122 CyaSSL API 13 4 Supported OpenSSL Functions The three structures shown above are usually initialized in the following way SSL METHOD method SSLv3_ client _method SSL CTX ctx SSL CTX new method SSL ssl SSL new ctx This establishes a client side SSL version 3 method creates a context based on the method and initializes the SSL session with the context A server side program is no different except that the SSL_METHOD is created using SSLv3_server_method or one of the available functions For a list of supported functions please see section 4 2 When using the OpenSSL Compatibility laye
238. t based on the strength of the symmetric encryption algorithm In doing this a rough grade classification can be devised to classify each cipher suite based on bits of security only taking into account symmetric key size LOW bits of security smaller than 128 bits MEDIUM bits of security equal to 128 bits HIGH bits of security larger than 128 bits Outside of the symmetric encryption algorithm strength the strength of a cipher suite will depend greatly on the key sizes of the key exchange and authentication algorithm keys The strength is only as good as the cipher suite s weakest link Following the above grading methodology and only basing it on symmetric encryption algorithm strength CyaSSL 2 0 0 currently supports a total of 0 LOW strength cipher suites 12 MEDIUM strength cipher suites and 8 HIGH strength cipher suites as listed below The following strength classification could change depending on the chosen key sizes of the other algorithms involved For a reference on hash function security strength see Table 3 pg 64 of NIST SP800 57 In some cases you will see ciphers referenced as EXPORT ciphers These ciphers originated from the time period in US history as late as 1992 when it was illegal to export software with strong encryption from the United States Strong encryption was classified as Munitions by the US Government under the same category as Nuclear Weapons Tanks and Ballistic Missiles Beca
239. t ctx AES128 SHA after the call to SSL_CTX_new so that you have ctx SSL CTX new method SSL CTX set cipher list ctx AES126 SHA 4 4 Hardware Accelerated Crypto CyaSSL is able to take advantage of several hardware accelerated or assisted crypto functionalities in various processors and chips The following sections explain which technologies CyaSSL supports out of the box 4 4 1 Intel AES NI AES is a key encryption standard used by governments worldwide which CyaSSL has always supported Intel has released a new set of instructions that is a faster way to implement AES CyaSSL is the first SSL library to fully support the new instruction set for production environments Essentially Intel has added AES instructions at the chip level that perform the computational intensive parts of the AES algorithm boosting performance For a list of Intel s chips that currently have support for AES NI you can look here http ark intel com search advanced s t amp AES Tech true We have added the functionality to CyaSSL to allow it to call the instructions directly from the chip instead of running the algorithm in software This means that when you re 55 running CyaSSL on a chipset that supports AES NI you can run your AES crypto 5 10 times faster If you are running on an AES NI supported chipset enable AES NI with the enable aesni build option To build CyaSSL with AES NI GCC 4 4 3 or late
240. t cyassl ssl h gt int CvaSSL_GetHmacType CYASSL ssl Description Allows caller to determine the negotiated h mac type from the handshake For cipher types except CYASSL_AEAD_TYPE Return Values If successful the call will return one of the following MD5 238 SHA SHA256 SHA384 BAD_FUNC_ARG or SSL_FATAL_ERROR will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetBulkCipher CyaSSL_GetHmacSize CyaSSL_GetCipherType Synopsis include lt cyassl ssl h gt int CyaSSL_GetCipherType CYASSL ssl Description Allows caller to determine the negotiated cipher type from the handshake Return Values If successful the call will return one of the following CYASSL_BLOCK_TYPE CYASSL_STREAM_TYPE CYASSL_AEAD_TYPE BAD_FUNC_ARG will be returned for an error state Parameters ssl a pointer to a CYASSL object created using CyaSSL_new See Also CyaSSL_GetBulkCipher 239 CyaSSL_GetHmacType 17 8 Connection Session and I O The functions in this section deal with setting up the SSL TLS connection managing SSL sessions and input output CyaSSL_accept Synopsis include lt cyassl ssl h gt int CyaSSL_accept CYASSL ssl Description This function is called on the server side and waits for an SSL client to initiate the SSL TLS handshake When this function is called the underlying communication channel has
241. t the DER buffer to PEM use the conversion function byte pem 4096 int pemSz DerToPem der derSz pem sizeof pem PRIVATEKEY TYPE if pemSz lt 0 pemSz contains error The last argument of DerToPem takes a type parameter usually either PRIVATEKEY_TYPE or CERT_TYPE Now the buffer pem holds the PEM format of the key 76 7 7 1 RSA Key Generation Notes Although an RSA private key contains the public key as well CyaSSL doesn t currently have the capability to generate a standalone RSA public key The private key can be used as both a private and public key by CyaSSL as used in test c The reasoning behind the lack of individual RSA public key generation in CyaSSL is that the private key and the public key in the form of a certificate is all that is typically needed for SSL A separate public key can be loaded into CyaSSL manually using the RsaPublickKeyDecode function if need be 7 8 Certificate Generation CyaSSL supports X 509 v3 certificate generation Certificate generation is off by default but can be turned on during the configure process with enable certgen or by defining CYASSL_CERT_GEN in Windows or non standard environments Before a certificate can be generated the user needs to provide information about the subject of the certificate This information is contained in a structure from cyassi ctaocrypt asn_public h named Cert for user to fill for certificate gener
242. ted in buffer Example int buffSz int ret byte certChainBuff CYASSL ssl 0 ret CyaSSL_use certificate chain buffer ssl certChainBuff buffSz if ret SSL SUCCESS failed to load certificate chain from buffer See Also CyaSSL_CTX_load_verify_buffer CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_PrivateKey_buffer 149 CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_CTX_use_certificate_chain_buffer CyaSSL_use_certificate_buffer CyaSSL_use_PrivateKey_buffer CyaSSL_CTX_der_load_verify_locations Synopsis include lt cyassl ssl h gt int CyaSSL_CTX_der_load_verify_locations CYASSL_CTX ctx const char file int format Description This function is similar to CyaSSL_CTX_load_verify_locations but allows the loading of DER formatted CA files into the SSL context CYASSL_CTX It may still be used to load PEM formatted CA files as well These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake The root certificate file provided by the file argument may be a single certificate or a file containing multiple certificates If multiple CA certs are included in the same file CyaSSL will load them in the same order they are presented in the file The format argument specifies the format which the certificates are in either SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 DER Unlike CyaSSL_CTX_load_verify_locations this function d
243. ter to any user specified context which will then in turn be passed back to the MAC encrypt and decrypt verify callbacks through the void ctx parameter 1 Example callbacks can be found in cyassl test h under myMacEncryptCb and myDecryptVerifyCb Usage can be seen in the CyaSSL example client examples client client c when using the U command line option To use Atomic Record Layer callbacks CyaSSL needs to be compiled using the enable atomicuser configure option or by defining the ATOMIC_USER preprocessor flag 6 4 Public Key Callbacks CyaSSL provides Public Key callbacks for users who wish to have more control over ECC sign verify functionality as well as RSA sign verify and encrypt decrypt functionality during the SSL TLS connection The user can optionally define 6 functions ECC sign callback ECC verify callback RSA sign callback RSA verify callback RSA encrypt callback RSA decrypt callback DOT E ee a 69 These two functions are prototyped by CallbackEccSign CallbackEccVerify CallbackRsaSign CallbackRsaVerify ssl h typedef int CallbackEccSign in unsigned int inSz unsigned int outSz unsigned int keySz typedef int CallbackRsaEnc and CallbackRsaDec in CYASSL ssl const unsigned char unsigned char out const unsigned char keyDer void ctx CallbackEccVerify CYASSL ssl const unsigned char sig const const int result
244. text or session setup to retrieve the SNI Return Values If successful the call will return SSL_SUCCESS If there is no SNI extension in the client hello the call will return 0 BAD_FUNC_ARG is the error that will be returned in one of this cases buffer is NULL bufferSz lt 0 sni is NULL jinOutSz is NULL or lt 0 BUFFER_ERROR is the error returned when there is a malformed Client Hello 297 message INCOMPLETE_DATA is the error returned when there is not enough data to complete the extraction Parameters buffer pointer to the data provided by the client Client Hello bufferSz size of the Client Hello message type indicates which type of server name is been retrieved from the buffer The known types are enum CYASSL_SNI_HOST_NAME 0 i sni pointer to where the output is going to be stored inOutSz pointer to the output size this value will be updated to MIN SNI s length inOutSz Example unsigned char buffer 1024 0 unsigned char result 32 0 int length 32 read Client Hello to buffer ret CyaSSL SNI_GetFromBuffer buffer sizeof buffer 0 result amp length if ret SSL SUCCESS sni retrieve failed See Also CyaSSL_UseSNI CyaSSL_CTX_UseSNI CyaSSL_SNI_GetRequest 298 CyaSSL_CTX_UseMaxFragment Synopsis include lt cyassl ssl h gt int CyaSSL_CTX_UseMaxFragment CYASSL_CTX ctx unsigned char mfl Description This f
245. the static buffer size up to the MAX_RECORD_ SIZE which is 216 or 16 384 If you prefer the previous way that CyaSSL operated with 16Kb static buffers that will never need dynamic memory you can still get that option by defining LARGE_STATIC_BUFFERS If dynamic buffers are used and the user requests a CyaSSL_write that is bigger than the buffer size then a dynamic block up to MAX_RECORD_ SIZE is used to send the data Users wishing to only send the data in chunks of at most RECORD_SIZE size can do this by defining STATIC_CHUNKS_ONLY This will cause CyaSSL to use I O buffers which grow up to RECORD_SIZE which is 128 bytes by default 9 6 Secure Renegotiation Several years back a vulnerability was discovered in SSL surrounding renegotiation CVE 2009 3555 In response to this vulnerability RFC 5746 secure renegotiation was created to mitigate the problem https tools ietf org html rfc5746 Support for renegotiation was left out of CyaSSL by design from the beginning This means that CyaSSL doesn t implement RFC 5746 and is not susceptible to the above vulnerability 85 Chapter 10 CTaoCrypt Usage Reference CTaoCrypt is the cryptography library primarily used by CyaSSL It is optimized for speed small footprint and portability CyaSSL interchange with other cryptography libraries as required Types used in the examples typedef unsigned char byte typedef unsigned int word32 10 1 Hash Functions
246. tion If the underlying I O is blocking CyaSSL_connect_cert will only return once the peer s certificate chain has been received Return Values If successful the call will return SSL_SUCCESS SSL_FAILURE will be returned if the SSL session parameter is NULL SSL_FATAL_ERROR will be returned if an error occurred To get a more detailed error code call CyaSSL_get_error Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new Example 243 int ret 0 int err 0 CYASSL ssl char buffer 80 ret CyaSSL_ connect _cert ssl if ret SSL SUCCESS err CyaSSL_ get_error ssl ret printf error d s n err CyaSSL_ ERR error string err buffer See Also CyaSSL_get_error CyaSSL_connect CyaSSL_accept CyaSSL_get_fd Synopsis include lt cyassl ssl h gt int CyaSSL_get_fd const CYASSL ssl Description This function returns the file descriptor fd used as the input output facility for the SSL connection Typically this will be a socket file descriptor Return Values If successful the call will return the SSL session file descriptor Parameters ssl pointer to the SSL session created with CyaSSL_new Example int sockfd CYASSL ssl 0 244 sockfd CyaSSL get _fd ssl See Also CyaSSL_set_fd CyaSSL_get_session Synopsis include lt cyassl ssl h gt CYASSL_SESSION CyaSSL_get_session CYASSL ssl Description
247. tion will try to send a close notify alert to the peer The calling application can choose to wait for the peer to send its close notify alert in response or just go ahead and shut down the underlying connection after directly calling CyaSSL_shutdown to save resources Either option is allowed by the TLS specification If the underlying connection will be used again in the future the complete two directional shutdown procedure must be performed to keep synchronization intact between the peers CyaSSL_shutdown works with both blocking and non blocking I O When the underlying I O is non blocking CyaSSL_shutdown will return an error if the underlying I O could not satisfy the needs of CyaSSL_send to continue In this case a call to CyaSSL_get_error will yield either SSL_LERROR_WANT_READ or SSL_ERROR_WANT_WRITE The calling process must then repeat the call to CyaSSL_send when the underlying I O is ready Return Values 0 will be returned upon success SSL_FATAL_ERROR will be returned upon failure Call CyaSSL_get_error for a more specific error code Parameters ssl pointer to the SSL session created with CyaSSL_new Example int ret 0 CYASSL ssl 0 132 ret CyaSSL_ shutdown ssl if ret 0 failed to shut down SSL connection See Also CyaSSL_free CyaSSL_CTX_free 17 2 Certificates and Keys The functions in this section have to do with loading certificates and key
248. to CyaSSL and both sides of the connection support NTRU then an NTRU cipher suite will be picked unless a user on one side has explicitly excluded them by stating to only use different cipher suites Using NTRU over RSA can provide a 20 200X speed improvement The improvement increases as the size of keys increases meaning a much larger speed benefit when using large keys 8192 bit versus smaller keys 1024 bit 52 4 3 6 ECC Support CyaSSL has support for Elliptic Curve Cryptography ECC including ECDH ECDSA ECDHE ECDSA ECDH RSA and ECDHE RSA CyaSSL s ECC implementation can be found in the lt cyassl_root gt cyassl ctaocrypt ecc h header file and the lt cyassl_root gt ctaocrypt src ecc c source file Supported cipher suites are shown in Table 4 above ECC is disabled by default but can be turned on when building CyaSSL with the HAVE _ECC define or by using the autoconf system configure enable ecc make make check When make check runs note the numerous cipher suites that CyaSSL checks Any of these cipher suites can be tested individually e g to tty ECDH ECDSA with AES256 SHA the example CyaSSL server can be started like this examples server server d 1 ECDH ECDSA AES256 SHA c certs server ecc pem k certs ecc key pem d disables client cert check while specifies the cipher suite list c is the certificate to use and k is the corresponding private key to use To hav
249. tom EmbedSend function See Also CyaSSL_SetlORecv CyaSSL_SetlOReadCtx CyaSSL_SetlOWriteCtx CyaSSL_CTX_SetCACb Synopsis void CyaSSL_CTX_SetCACb CYASSL_CTX ctx CallbackCACache cb typedef void CallbackCACache unsigned char der int sz int type Description This function registers a callback with the SSL context CYASSL_CTX to be called when a new CA certificate is loaded into CyaSSL The callback is given a buffer with the DER encoded certificate Return Values This function has no return value Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new 198 callback function to be registered as the CA callback for the CyaSSL context ctx The signature of this function must follow that as shown above in the Synopsis section Example CYASSL_ CTX ctx 0 CA callback prototype int MyCACallback unsigned char der int sz int type Register the custom CA callback with the SSL context CyaSSL_ CTX SetCACb ctx MyCACallback int MyCACallback unsigned char der int sz int type custom CA callback function DER encoded cert located in der of size sz with type type See Also CyaSSL_CTX_load_verify_locations CyaSSL_connect_ex Synopsis include lt cyassl ssl h gt int CyaSSL_connect_ex CYASSL ssl HandShakeCallBack hsCb TimeoutCallBack toCb Timeval timeout typedef int HandShakeCallBack HandShakelnfo typedef int
250. ture created using CyaSSL_new file a pointer to the name of the file containing the chain of certificates to be loaded into the CyaSSL SSL session Certificates must be in PEM format Example int ret 0 CYASSL ctx ret CyaSSL use certificate chain file ssl cert chain pem if ret SSL SUCCESS error loading cert file See Also CyaSSL_CTX_use_certificate_chain_file CyaSSL_CTX_use_certificate_chain_buffer CyaSSL_use_certificate_chain_buffer CyaSSL_use_RSAPrivateKey_file Synopsis include lt cyassl ssl h gt int CvaSSL_use_RSAPrivateKey_file CYASSL ssl const char file int format 287 Description This function loads the private RSA key used in the SSL connection into the SSL session CYASSL structure This function is only available when CyaSSL has been compiled with the OpenSSL compatibility layer enabled enable opensslExtra define OPENSSL_EXTRA and is identical to the more typically used CyaSSL_use_PrivateKey_file function The file argument contains a pointer to the RSA private key file in the format specified by format Return Values If successful the call will return SSL_SUCCESS otherwise SSL_FAILURE will be returned If the function call fails possible causes might include The input key file is in the wrong format or the wrong format has been given using the format argument file doesn t exist can t be read or is corrupted an out of mem
251. tx certBuff sz SSL FILETYPE PEM if ret SSL SUCCESS error loading CA certs from buffer See Also CyaSSL_CTX_load_verify_locations CyaSSL_CTX_use_certificate_buffer CyaSSL_CTX_use_PrivateKey_buffer CyaSSL_CTX_use_NTRUPrivateKey_file CyaSSL_CTX_use_certificate_chain_buffer CyaSSL_use_certificate_buffer CyaSSL_use_PrivateKey_buffer CyaSSL_use_certificate_chain_buffer CyaSSL_CTX_load_verify_locations 134 Synopsis int CyaSSL_CTX_load_verify_locations CYASSL_CTX ctx const char file const char path Description This function loads PEM formatted CA certificate files into the SSL context CYASSL_CTX These certificates will be treated as trusted root certificates and used to verify certs received from peers during the SSL handshake The root certificate file provided by the file argument may be a single certificate or a file containing multiple certificates If multiple CA certs are included in the same file CyaSSL will load them in the same order they are presented in the file The path argument is a pointer to the name of a directory that contains certificates of trusted root CAs If the value of file is not NULL path may be specified as NULL if not needed If path is specified and NO_CYASSL_DIR was not defined when building the library CyaSSL will load all CA certificates located in the given directory Please see the examples for proper usage Return Values If successful the call will retur
252. typedef int unsigned int sigSz unsigned char hash unsigned char keyDer void ctx CallbackRsaSign CYASSL ssl unsigned int hashSz unsigned int keySz const unsigned char in unsigned char out const unsigned char keyDer void ctx typedef int unsigned char sig unsigned char out unsigned int keySz typedef int in inSz outSz keySz unsigned int unsigned int unsigned int void ctx typedef int unsigned int inSz const unsigned char keyDer void ctx CallbackRsaEnc CYASSL ssl CallbackRsaDec CYASSL ssl unsigned char out unsigned int inSz unsigned int outSz unsigned int keySz CallbackRsaVerify CYASSL ssl unsigned int sigSz const unsigned char keyDer void ctx const unsigned char unsigned char out const unsigned char keyDer unsigned char in unsigned int keySz 70 The user needs to write and register these functions per CyaSSL context CYASSL_CTX with CyaSSL_CTX_SetEccSignCb CyaSSL_CTX_SetEccVerifyCb CyaSSL_CTX_SetRsaSignCb CyaSSL_CTX_SetRsaVerifyCb CyaSSL_CTX_SetRsaEncCb and CyaSSL_CTX_SetRsaDecCb The user can set a context per CYASSL object session with CyaSSL_SetEccSignCtx CyaSSL_SetEccVerifyCtx CyaSSL_SetRsaSignCtx CyaSSL_SetRsaVerifyCtx CyaSSL_SetRsaEncCtx and CyaSSL_SetRsaDecCtx These contexts may be pointers to any user specified context which wi
253. ublic key options with support for EDH Ephemeral Diffie Hellman on the CyaSSL server Detailed usage of these functions can be found in the CTaoCrypt Usage Reference section 10 5 CyaSSL has support for four cipher suites utilizing NTRU TLS_NTRU_RSA_WITH_3DES_EDE_CBC_SHA TLS_NTRU_RSA_WITH_RC4_128 SHA TLS_NTRU_RSA_WITH_AES_128 CBC_SHA TLS_NTRU_RSA_WITH_AES_256_CBC_SHA The strongest one AES 256 is the default If CyaSSL is enabled with NTRU and the NTRU package is available these cipher suites are built into the CyaSSL library A CyaSSL client will have these cipher suites available without any interaction needed by the user On the other hand a CyaSSL server application will need to load an NTRU private key and NTRU x509 certificate in order for those cipher suites to be available for use The example servers echoserver and server both use the define HAVE_NTRU which is turned on by enabling NTRU to specify whether or not to load NTRU keys and certificates The CyaSSL package comes with test keys and certificates in the lt cyassl_root gt certs directory ntru cert pem is the certificate and ntru key raw is the private key blob The CyaSSL NTRU cipher suites are given the highest preference order when the protocol picks a suite Their exact preference order is the reverse of the above listed suites i e AES 256 will be picked first and 3DES last before moving onto the standard cipher suites Basically if a user builds NTRU in
254. uct family Please post to the forums or contact wolfSSL directly with any questions yaSSL Forums hittp www wolfssl com forums Email Support support wolfss com For information regarding wolfSSL products questions regarding licensing or general comments please contact wolfSSL by emailing info wolfssl com For support packages please see Chapter 14 15 1 1 Bugs Reports and Support Issues If you are submitting a bug report or asking about a problem please include the following information with your submission CyaSSL version number Operating System version Compiler version The exact error you are seeing Adescription of how we can reproduce or try to replicate this problem O AOUN With the above information we will do our best to resolve your problems Without this information it is very hard to pinpoint the source of the problem wolfSSL values your feedback and makes it a top priority to get back to you as soon as possible 15 2 Consulting wolfSSL offers both on and off site consulting providing feature additions porting a Competitive Upgrade Program and design consulting 15 2 1 Feature Additions and Porting We can add additional features that you may need which are not currently offered in our products on a contract or co development basis We also offer porting services on our products to new host languages or new operating environments 15 2 2 Competitive Upgrade Program 127 We
255. ucture to use is Sha which is a typedef Before using the hash initialization must be done with the InitSha call Use ShaUpdate to update the hash and ShaFinal to retrieve the final hash byte shaSum SHA_ DIGEST SIZE byte buffer 1024 fill buffer with data to hash Sha sha InitSha amp sha ShaUpdate amp sha buffer sizeof buffer can be called again and again ShaFinal amp sha shaSum shaSum now contains the digest of the hashed data in buffer To use either SHA 256 SHA 384 or SHA 512 follow the same steps as shown above but use either the cyassl ctaocrypt sha256 h or cyassl ctaocrypt sha512 h for both SHA 384 and SHA 512 The SHA 256 SHA 384 and SHA 512 functions are named 87 similarly to the SHA functions For SHA 256 the functions InitSha256 Sha256Update and Sha256Final will be used with the structure Sha256 For SHA 384 the functions InitSha384 Sna384Update and Sha384Final will be used with the structure Sha384 For SHA 512 the functions InitSha512 Sha512Update and Sha512Final will be used with the structure Sha512 10 1 4 BLAKE2b To use BLAKE2b a SHA 3 finalist include the BLAKE2b header cyassl ctaocrypt blake2 h The structure to use is Blake2b which is a typedef Before using the hash initialization must be done with the InitBlake2b call Use Blake2bUpdate to update the hash and Bl
256. uffer CyaSSL_use_PrivateKey_buffer CyaSSL_use_certificate_chain_buffer CyaSSL_CTX_use_certificate_chain_buffer Synopsis int CyaSSL_CTX_use_certificate_chain_buffer CYASSL_CTX ctx const unsigned char in long sz Description This function loads a certificate chain buffer into the CYASSL Context It behaves like 140 the non buffered version only differing in its ability to be called with a buffer as input instead of a file The buffer is provided by the in argument of size sz The buffer must be in PEM format and start with the subject s certificate ending with the root certificate Please see the examples for proper usage Return Values If successful the call will return SSL_SUCCESS SSL_BAD_FILETYPE will be returned if the file is the wrong format SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY E will be returned if an out of memory condition occurs ASN_INPUT_E will be returned if Base16 decoding fails on the file BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer Parameters ctx pointer to the SSL context created with CyaSSL_CTX_new in the input buffer containing the PEM formatted certificate chain to be loaded sz the size of the input buffer Example int ret 0 int sz 0 CYASSL_CTX ctx byte certChainBuff ret CyaSSL CTX use certificate chain buffer ctx certChainBuff sz if ret SSL SUCCESS
257. unction is called on the client side to enable the use of Maximum Fragment Length for SSL objects created from the SSL context passed in the ctx parameter It means that the Maximum Fragment Length extension will be sent on ClientHello by CyaSSL clients Return Values If successful the call will return SSL_SUCCESS BAD_FUNC_ARG is the error that will be returned in one of these cases ctx is NULL mfl is out of range MEMORY_E is the error returned when there is not enough memory Parameters ctx pointer to a SSL context created with CyaSSL_CTX_new mfl indicates which is the Maximum Fragment Length requested for the session The available options are enum CYASSL_MFL_2_9 1 512 bytes CYASSL_MFL_2_10 2 1024 bytes CYASSL_MFL_2_11 3 2048 bytes CYASSL_MFL_2_12 4 4096 bytes CYASSL_MFL_2_13 5 8192 bytes CyaSSL ONLY i Example 299 int ret 0 CYASSL CTX ctx 0 ctx CyaSSL CTX new method if ctx NULL context creation failed ret CyaSSL CTX UseMaxFragment ctx CYASSL MFL 2 11 if ret 1 0y 4 max fragment usage failed See Also CyaSSL_CTX_new CyaSSL_UseMaxFragment CyaSSL_UseMaxFragment Synopsis include lt cyassl ssl h gt int CyaSSL_UseMaxFragment CYASSL ssl unsigned char mfl Description This function is called on the client side to enable the use of Maximum Fragment Length in the SSL object passed in the ssl par
258. ur special commands aren t echoed back and instruct the echoserver to take a different action 1 quit If the echoserver receives the string quit it will shutdown 2 break Ifthe echoserver receives the string break it will stop the current session but continue handling requests This is particularly useful for DTLS testing 30 3 printstats If the echoserver receives the string printstats it will print out statistics for the session cache 4 GET If the echoserver receives the string GET it will handle it as an http get and send back a simple page with the message greeting from CyaSSL This allows testing of various TLS SSL clients like Safari IE Firefox gnutls and the like against the echoserver example The output of the echoserver is echoed to stdout unless NO_MAIN_DRIVER is defined You can redirect output through the shell or through the first command line argument To create a file named output txt with the output from the echoserver run examples echoserver echoserver output txt 3 6 EchoClient Example The echoclient example can be run in interactive mode or batch mode with files To run in interactive mode and write 3 strings hello cyassl and quit results in examples echoclient echoclient hello hello cyassl cyassl quit sending server shutdown command quit To use an input file specify the filename on the command line as the first argument To echo the contents of the fil
259. use of this restriction software being exported included weakened ciphers mostly in smaller key sizes In the current day this restriction has been lifted and as such EXPORT ciphers are no longer a mandated 47 necessity 4 3 2 Supported Cipher Suites The following cipher suites are supported by CyaSSL A cipher suite is a combination of authentication encryption and message authentication code MAC algorithms which are used during the TLS or SSL handshake to negotiate security settings for a connection Each cipher suite defines a key exchange algorithm a bulk encryption algorithm and a message authentication code algorithm MAC The key exchange algorithm RSA DSS DH EDH determines how the client and server will authenticate during the handshake process The bulk encryption algorithm DES 3DES AES ARC4 RABBIT HC 128 including block ciphers and stream ciphers is used to encrypt the message stream The message authentication code MAC algorithm MD2 MD5 SHA 1 SHA 256 SHA 512 RIPEMD is a hash function used to create the message digest The table below matches up to the cipher suites and categories found in lt cyassl_root gt cyassl internal h If you are looking for a cipher suite which is not in the following list please contact us to discuss getting it added to CyaSSL TLS_DHE_RSA_WITH_AES 256 CBC_SHA TLS DHE RSA WITH AES 128 CBC_SHA TLS _RSA_WITH_AES 256 CBC_SHA TLS_RSA_WITH_AES 128 CBC_SHA TLS_RSA
260. use there is no block size and the key length can be any length The following is a typical usage of ARC4 Arc4 enc Arc4 dec const byte key some key any length byte plain 27 no size restriction fill with data byte cipher 27 encrypt Arc4SetKey amp enc key sizeof key Arc4Process amp enc cipher plain sizeof plain cipher now contains the cipher text from the plain text decrypt Arc4SetKey amp dec key sizeof key Arc4Process amp dec plain cipher sizeof cipher plain now contains the original plaintext from the cipher text 10 4 2 RABBIT A newer stream cipher gaining popularity is RABBIT This stream cipher can be used through CTaoCrypt by including the header cyass l ctaocrypt rabbit h RABBIT is very fast compared to ARC4 but has key constraints of 16 bytes 128 bits and an optional IV of 8 bytes 64 bits Otherwise usage is exactly like ARC4 Rabbit enc 93 Rabbit dec const byte key some key 16 bytes const byte iv some iv 8 bytes byte plain 27 no size restriction fill with data byte cipher 27 encrypt RabbitSetKey amp enc key iv iv can be a NULL pointer f plain RabbitProcess amp enc cipher plain sizeot cipher now contains the cipher text from the plain text decrypt RabbitSetKey amp dec key iv RabbitProcess amp dec plain cipher
261. using the DSA private key hash value and random number generator DsaSign hash signature amp key amp rng To verify the signature use DsaVerify If verification is successful answer will be equal to 1 Once finished free the DSA key structure using FreeDsaKey DsaVerify hash signature amp key amp S amp answer FreeDsakey amp key 100 Chapter 11 SSL Tutorial 11 1 Introduction The CyaSSL embedded SSL library can easily be integrated into your existing application or device to provide enhanced communication security through the addition of SSL and TLS CyaSSL has been targeted at embedded and RTOS environments and as such offers a minimal footprint while maintaining excellent performance Minimum build sizes for CyaSSL range between 20 100kB depending on the selected build options and platform being used 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 CyaSSL 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 Unix Network Programming Volume 1 3rd Edition by Richard Stevens Bill Fenner and An
262. vailable for reading 0 There is no SSL_ERROR_WANT_READ error state 224 Parameters ssl pointer to the SSL session created with CyaSSL_new Example Int Ket CYASSL ssl 0 ret CyaSSL want_read ssl if ret 1 underlying I O has data available for reading SSL ERROR WANT READ See Also CyaSSL_want_write CyaSSL_get_error CyaSSL_want_write Synopsis include lt cyassl ssl h gt int CyaSSL_want_write CYASSL ssl Description This function is similar to calling CyaSSL_get_error and getting SSL_ERROR_WANT_WRITE in return If the underlying error state is SSL_ERROR_WANT_WRITE this function will return 1 otherwise 0 Return Values 1 CyaSSL_get_error would return SSL_ERROR_WANT_WRITE the underlying I O needs data to be written in order for progress to be made in the underlying SSL connection 0 There is no SSL_ERROR_WANT_WRITE error state Parameters 220 ssl pointer to the SSL session created with CyaSSL_new Example int ret CYASSL ssl 0 ret CyaSSL want _write ssl if ret 1 underlying I O needs data to be written SSL ERROR WANT WRITE lt See Also CyaSSL_want_read CyaSSL_get_error CyaSSL_Debugging_ON Synopsis include lt cyassl ssl h gt int CyaSSL_Debugging_ON void Description If logging has been enabled at build time this function turns on logging at runtime To enable logging at build time u
263. will help you move from an outdated or expensive SSL library to CyaSSL with low cost and minimal disturbance to your code base Program Outline 1 You need to currently be using a commercial competitor to CyaSSL 2 You will receive up to one week of on site consulting to switch out your old SSL library for CyaSSL Travel expenses are not included 3 Normally up to one week is the right amount of time for us to make the replacement in your code and do initial testing Additional consulting on a replacement is available as needed 4 You will receive the standard CyaSSL royalty free license to ship with your product 5 The price is 10 000 The purpose of this program is to enable users who are currently spending too much on their embedded SSL implementation to move to CyaSSL with ease If you are interested in learning more then please contact us at info wolfssl com 15 2 3 Design Consulting If your application or framework needs to be secured with SSL TLS but you are uncertain about how the optimal design of a secured system would be structured we can help We offer design consulting for building SSL TLS security into devices using CyaSSL Our consultants can provide you with the following services 1 Assessment An evaluation of your current SSL TLS implementation We can give you advice on your current setup and how we think you could improve upon this by using CyaSSL 2 Design Looking at your system requirements and
264. wise the test programs won t be able to connect to each other By default the CyaSSL example client tries to connect to the specified server using TLS 1 2 The user is able to change the SSL TLS version which the client uses by using the v command line option The following values are available for this option v 0 SSL 3 0 v 1 TLS 1 0 v 2 TLS 1 1 v 3 TLS 1 2 A common error users see when using the example client is 155 err 155 ASN sig error confirm failure This is typically caused by the CyaSSL client not being able to verify the certificate of the server it is connecting to By default the CyaSSL client loads the yaSSL test CA certificate as a trusted root certificate This test CA certificate will not be able to verify an external server certificate which was signed by a different CA As such to solve this problem users either need to turn off verification of the peer Server using the d option examples client client h myhost com p 443 d Or load the correct CA certificate into the CyaSSL client using the A command line option examples client client h myhost com p 443 A serverCA pem 3 4 Server Example The server example demonstrates a simple SSL server that optionally performs client authentication Only one client connection is accepted and then the server quits The client example in normal mode no command line arguments will work just fine against the example server but
265. x client cert pem SSL FILETYPE PEM if ret SSL SUCCESS error loading cert file See Also CyaSSL_CTX_use_certificate_buffer CyaSSL_use_certificate_file CyaSSL_use_certificate_buffer CyaSSL_SetTmpDH Synopsis include lt cyassl ssl h gt int CyaSSL_SetTmpDH CYASSL ssl unsigned char p int pSz unsigned char g int gSz Description Server Diffie Hellman Ephemeral parameters setting This function sets up the group parameters to be used if the server negotiates a cipher suite that uses DHE Return Values 144 If successful the call will return SSL_SUCCESS MEMORY_ERROR will be returned if a memory error was encountered SIDE_ERROR will be returned if this function is called on an SSL client instead of an SSL server Parameters ssl a pointer to a CYASSL structure created using CyaSSL_new p Diffie Hellman prime number parameter pSz size of p g Diffie Hellman generator parameter gSz size of g Example CYASSL ssl static unsigned char p static unsigned char g CyaSSL_ SetTmpDH ssl p sizeof p g sizeof g See Also SSL_accept CyaSSL_use_PrivateKey_buffer Synopsis include lt cyassl ssl h gt int CyaSSL_use_PrivateKey_buffer CYASSL ssl const unsigned char in long sz int format Description This function loads a private key buffer into the CYASSL object It behaves like the non 145 buffered
266. yaSSL_get_chain_length CyaSSL_get_chain_cert_pem 280 CyaSSL_get_chain_cert_pem Synopsis include lt cyassl ssl h gt unsigned char CyaSSL_get_chain_cert_pem CYASSL_X509_CHAIN chain int idx Description Retrieves the peer s PEM certificate at index idx Return Values If successful the call will return the peer s certificate by index 0 will be returned if an invalid chain pointer is passed to the function See Also CyaSSL_get_peer_chain CyaSSL_get_chain_count CyaSSL_get_chain_length CyaSSL_get_chain_cert CyaSSL_PemCertToDer Synopsis include lt cyassl ssl h gt int CyaSSL_PemCertToDer const char fileName unsigned char derBuffer int derSz Description Loads the PEM certificate from fileName and converts it into DER format placing the result into derBuffer which is of size derSz Return Values If successful the call will return the number of bytes written to derBuffer SSL_BAD_FILE will be returned if the file doesn t exist can t be read or is corrupted MEMORY_E will be returned if an out of memory condition occurs 281 SSL_NO_PEM_HEADER will be returned if the PEM certificate header can t be found BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer Parameters filename pointer to the name of the PEM formatted certificate for conversion derBuffer the buffer for which the converted PEM certificate will be placed in DER format derSz size of
267. yaSSL_get_error will return the current error code It takes the current CYASSL object and CyaSSL_read or CyaSSL_write result value as an arguments and returns the corresponding error code int err CyaSSL_ get _error ssl result To get a more human readable error code description the CyaSSL_ERR_error_string function can be used It takes the return code from CyaSSL_get_error and a storage buffer as arguments and places the corresponding error description into the storage buffer errorString in the example below char errorString 80 CyaSSL_ERR_ error string err errorString If you are using non blocking sockets you can test for errno EAGAIN EWOULDBLOCK or more correctly you can test the specific error code for SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE For a list of CyaSSL and CTaoCrypt error codes please see Appendix C Error Codes Chapter 9 Library Design 9 1 Library Headers 82 With the release of CyaSSL 2 0 0 RC3 library header files are now located in the following locations CyaSSL cyassl CTaoCrypt cyassl ctaocrypt CyaSSL OpenSSL Compatibility Layer cyassl openssl When using the OpenSSL Compatibility layer see Chapter 13 the cyassl openssl ssl h header is required to be included include lt cyassl openssl ssl h gt When using only the CyaSSL native API only the cyassl ssl h header is required to be included finclude lt cyassl ssl h gt 9 2 Startup and Exit All ap
268. ze restriction fill with data byte cipher 37 encrypt Chacha _SetKey amp enc key keySz Chacha SetIV amp senc iv counter counter is the start block counter is usually set as 0 Chacha Process amp enc cipher plain sizeof plain cipher now contains the cipher text from the plain text decrypt Chacha_SetKey amp enc key keySz Chacha SetIV amp enc iv counter Chacha Process amp enc plain cipher sizeof cipher plain now contains the original plaintext from the cipher text Chacha_SetKey only needs to be set once but for each packet of information sent Chacha_SetlV must be called with a new iv nonce Counter is set as an argument to 95 allow for partially decrypting encrypting information by starting at a different block when performing the encrypt decrypt process but in most cases is set to 0 ChaCha should not be used without a mac algorithm ie Poly1305 hmac 10 5 Public Key Cryptography 10 5 1 RSA CTaoCrypt provides support for RSA through the header cyass l ctaocrypt rsa h There are two types of RSA keys public and private A public key allows anyone to encrypt something that only the holder of the private key can decrypt It also allows the private key holder to sign something and anyone with a public key can verify that only the private key holder actually signed it Usage is usually like the following Rsakey rsaPublicKkey byte publickKeyBuffer

CyaSSL User Manual Table of Contents

Contents

Download Pdf Manuals

Related Search

Related Contents