Repository files navigation

cryptlib is a security toolkit focused on long-term stability and reliabilitythat implements a wide range of protocols including S/MIME and PGP/OpenPGPsecure messaging, SSL/TLS and SSH secure sessions, a full range of CA servicessuch as CMP, SCEP, RTCS, OCSP, SCVP and TSP, and secure authenticationprotocols like EAP-TLS, EAP-TTLS, and PEAP.

cryptlib's primary goal is stability and reliability, consisting of a highlymature code base with a 30-year history and an API that's been stable for thelast 20 years - you should be able to take 20-year-old code, recompile itagainst the current code base, and it'll still work (you'll just get thelatest algorithms and crypto mechanisms). This emphasis on long-termstability means that what you deploy today will still be fine in 10-20 years -there's no need to roll out patches every two weeks to deal with bugs andsecurity vulnerabilities.

cryptlib provides a strong emphasis on safe, reliable operation. Main memorysections are statically allocated (only variable-sized items like certificatesuse dynamic allocation, and even this is done in a FIFO manner where storagecan be drawn from a static memory block if required), allowing the memoryfootprint to be determined in advance. All cryptovariables and algorithmshave extensive protection through self-testing, pairwise consistency checks oncrypto operations, and checksumming of cryptovariables to preventmodifications, either indirectly (faults) or deliberately (glitch attacks).All parameters are range-checked and bounds-checked, all loops and arrayaccesses are statically-bounded, pointers and critical variables are protectedagainst data corruption and faults, and critical code sections involvingcrypto operations have control flow integrity protections to prevent glitches.

cryptlib's development has been driven by user feedback over its 30-yearlifetime, evolving to maximise ease-of-use and minimise the need to ploughthrough the manual or online forums for every task, augmented by acomprehensive 400-page manual with extensive ready-to-use code samples formost tasks. Requests or bug reports result in a fix and test suite and/ordocumentation update to resolve the issue for the future.

The code base is highly tuneable and configurable to allow use in constrainedenvironments, minimising code size and memory footprints. The emphasis is onproviding a high-level API that makes it easy to get things right, providingfully functional interfaces rather than stub APIs that need to be crafted intoa working system. cryptlib's cross-platform nature means that you can developin your preferred environment (Windows, Unix, Mac OS) and then deploy the samecode to the target embedded or RTOS environment, bypassing the need to doextensive development directly on the embedded hardware.

Alongside the security services, cryptlib provides a sophisticated key storageinterface that allows the use of a wide range of key database types rangingfrom PKCS #11 devices, PKCS #15 key files, and PGP/OpenPGP key rings throughto commercial-grade RDBMS' and LDAP directories, as well as interfacing tocryptographic hardware like PKCS #11 tokens and crypto accelerators, TPMs, andfully custom crypto hardware via plugin modules.

cryptlib is written in C, with language bindings for C / C++, C# / .NET,Delphi, Java, Python, and Visual Basic (VB).

Although cryptlib runs on the usual suspects (every Unix variant includingAIX, Digital Unix, DGUX, FreeBSD/NetBSD/OpenBSD, HP-UX, IRIX, Linux, MP-RAS,OSF/1, QNX, Solaris, Ultrix, and UTS4), Windows, Mac OS, and lesser-knownsystems like IBM MVS, Tandem, and VM/CMS, it's also targeted at embedded,RTOS, and even bare-metal use, including AMX, ARINC653, ChorusOS, CMSIS, CMX,eCos, embOS, FreeRTOS/OpenRTOS, uITRON, MGOS, MQX, Nucleus, OSEK, PalmOS,Quadros, RiotOS, RTEMS, SMX, Telit, ThreadX, TI kernel, T-Kernel, uC/OS II,VDK, VxWorks, XMK, and Zephyr OS.

cryptlib is provided in source code form and optionally as precompiled DLLsfor Windows. To build it from source, you can load the project file intoVisual Studio to build for Windows, or for non-Windows environments eithermake ormake shared depending on whether you want the static or sharedlibrary. When you're done,make install will set things up for usesystemwide. More details are given in themanual, withan overview in thecryptlib architecture document.

cryptlib has a comprehensiveusermanual containingmany code samples that you can copy directly into your application, so thefollowing is just a brief overview of how to use it. To create an S/MIMEsigned message:

CRYPT_ENVELOPE cryptEnvelope;int bytesCopied;/* Create the S/MIME envelope */cryptCreateEnvelope( &cryptEnvelope, CRYPT_FORMAT_SMIME );/* Add the signing key */cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_SIGNATURE, sigKeyContext );/* Push in the data and pop out the signed data */cryptPushData( cryptEnvelope, data, dataLength, &bytesCopied );cryptFlushData( cryptEnvelope );cryptPopData( cryptEnvelope, processedData, processedDataBufsize, &bytesCopied );cryptDestroyEnvelope( cryptEnvelope );

To encrypt instead of signing, change the second function call to:

/* Add the certificate of the message recipient */cryptSetAttribute( cryptEnvelope, CRYPT_ENVINFO_PUBLICKEY, certificate );

That's all that's necessary (you can copy this code directly into yourapplication to S/MIME-enable it). To do the same for PGP/OpenPGP, just changethe CRYPT_FORMAT_SMIME specifier to CRYPT_FORMAT_PGP.

To create an SSL/TLS session:

CRYPT_SESSION cryptSession;/* Create the TLS session */cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_TLS );/* Add the server name and activate the session */cryptSetAttributeString( cryptSession, CRYPT_SESSINFO_SERVER_NAME, serverName, serverNameLength );cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

The corresponding SSL/TLS server is:

CRYPT_SESSION cryptSession;/* Create the TLS server session */cryptCreateSession( &cryptSession, cryptUser, CRYPT_SESSION_TLS_SERVER );/* Add the server key/certificate and activate the session */cryptSetAttribute( cryptSession, CRYPT_SESSINFO_PRIVATEKEY, privateKey );cryptSetAttribute( cryptSession, CRYPT_SESSINFO_ACTIVE, 1 );

That's all that's necessary (you can copy this code directly into yourapplication to TLS-enable it). As with the S/MIME to PGP switch, to changethis from SSL/TLS to SSH, just change the CRYPT_SESSION_TLS specifier toCRYPT_SESSION_SSH.

All contributions are welcome, however because we carefully vet any code thatgoes into cryptlib to maintain the stability and reliability guarantees (seethe principles in theoverview) we'll probably rewrite it, addunit tests and documentation, and so on rather than taking it as is.

To request new features or ask a question, please use theDiscussionforum. For bug reports,see theIssues section. Toprivately report an issue such as a vulnerability, see theSecuritysection.

cryptlib contains contributions from various open-source developers, see theacknowledgements section of themanual fordetails.

cryptlib is dual-licensed:

• Under the historicSleepycat License. This is anOpen Source Initiative-approved license that allowsuse under standard GPL copyleft terms.

• Optionallyclosed-source use for anyonerequiring commercial support.

cryptlib supports theOpenSSL Mission and Values.

When you're working with crypto code, you may also want to consider:

OpenSSL, a robust, commercial-grade,full-featured Open Source Toolkit for the TLS (formerly SSL), DTLS and QUICprotocols.

BouncyCastle, FIPS-certified open-sourcecryptographic APIs for Java and C#.

cryptlib acknowledges the following SAST and runtime tools, which are used tocheck the cryptlib code base.

AFL/AFLplusplus - Code fuzzing tool.

Clang Static Analyzer - Source codeanalysis tool that finds bugs in C, C++, and Objective-C programs.

Coverity Scan - Static source code analysis toolfor a variety of languages.

Cppcheck - Static analysis tool for C/C++code.

Infer - Infer static analyzer.

libfuzzer - In-process,coverage-guided, evolutionary fuzzing engine.

PREfast - Code analysis tool for VisualStudio.

PVS-Studio - Staticanalyzer for C, C++, C#, and Java code.

valgrind - Dynamic code analysis tool.