a portable, small, easy to use and fast c++14 library for cryptography.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

mbedcrypto

mbedcrypto is a portable, small, easy to use, feature rich and fast c++14 library for cryptography based on fantastic and clean mbedtlsnote note.

a sister project for Qt5 developers is available as qpolarssl, although mbedcrypto is newer and has more features with smaller footprint and can be configured to support QByteArray through the api.

for more information see wiki page.


features and highlights

  • small size: the mbedcrypto is less than 250KB in size (as single shared library and stripped under Linux and OS X) with all predefined algorithms. it can be easily embedded into your service or application.
  • easy to use: although cryptographynote is complex and complicated, mbedcrypto hides most of the complexities, tries to be easy to use and hard to misuse.
  • portable: needs an standard c++14 compiler and compliant stl, compiled and tested by:
    • g++ 5.x+ / 6+ under linux
    • clang 3.6+ under os x
    • mingw 5.x+ under msys2 (windows 8.1)
    • msvc 2015 community edition under windows 7
  • low dependency:
    • the mbedtlsnote as underlying cryptography engine, is the only mandatory dependency.
    • catch: only for unit testing.
    • cmake for building the library and the unit test app.
  • high+low level: both high level (c++ objects / exception) and low level (c pointer / error code) functions are available.
  • highly configurable: to add or remove the algorithms, simply change cmake build options. see build options
  • optional support for Qt5: optional support for Qt5's QByteArray is also available.

supported algorithms

following algorithms are included in mbedcrypto in default build (see wiki usage):

  • binary/text conversions: see wiki: samples

    • hex
    • base64
  • hashes (message digest): see wiki: samples

    • md5
    • sha1
    • sha224 / sha256
    • sha384 / sha512
    • hmac
    • optional hashes: ripemd160, md4, md2 (deprecated)
  • ciphers (symmetric): see wiki: samples

    • aes (128, 192, 256 bits) and aes-ni (hardware accelerated)
    • des and 3des (triple-des)
    • optional ciphers: blowfish, camellia and arc4
  • cipher block modes:

  • paddings:

    • pkcs7
    • one and zeros
    • zeros and length
    • zeros
  • random byte generator: see wiki samples

    • ctr_drbg counter mode deterministic random byte generator based on aes-256 NIST SP 800-90
  • pki (asymmetric): public key infrastructure, see wiki: rsa samples and wiki: ec samples

    • rsa
    • pem and der key formats (ASN.1)
    • optional pks: eckey elliptic curve, eckey_dh elliptic key Diffie–Hellman, ecdsa elliptic key digital signature algorithm, rsa_alt and rsassa_pss RSA standard signature algorithm, probabilistic signature scheme
    • optional rsa key generator
    • optional ec curves from well known domain parameters as NIST, Kolbitz, brainpool and Curve25519.

total number of supported algorithms:

  • hashes: 9
  • paddings: 5
  • ciphers: 47
  • pki: 6

see types.hpp

setup

bash

git clone the repository as you usually would. Then go to your terminal and execute the following command to download all dependencies (fetches master):

$mbedcrypto> ./update-dependencies.sh

git submodules

Alternatively, when using git clone, add the --recurse-submodules flag to the command. This way, the dependencies will be downloaded as well.

Dependencies are downloaded using Git's submodules. See the manual for more info.


build

Build the mbedcrypto library using CMake in your terminal:

$workspace/> mkdir mbedcrypto.build
$workspace/> cd mbedcrypto.build
$mbedcrypto.build/> cmake /path/to/mbedcrypto

# optionally to reconfigure the build option (or by cmake-gui .)
$mbedcrypto.build/> ccmake .

$mbedcrypto.build/> make -j

$mbedcrypto.build/> make install

build options

to trim the library size, only SHA/AES/RSA algorithms are included. you can add other algorithms by these cmake options:

options message
MBEDCRYPTO_MD2 enable md2 hash (insecure and deprecated)
MBEDCRYPTO_MD4 enable md4 hash
MBEDCRYPTO_RIPEMD160 enable ripemd160 hash
MBEDCRYPTO_CFB enable cfb (cipher feedback mode)
MBEDCRYPTO_CTR enable ctr (cipher counter mode)
MBEDCRYPTO_GCM enable gcm (Galois cipher mode, for aead cryptography)
MBEDCRYPTO_CCM enable ccm (counter cbc-mac cipher mode, for aead cryptography)
MBEDCRYPTO_DES enable des and triple-des cipher
MBEDCRYPTO_BLOWFISH enable blowfish cipher
MBEDCRYPTO_CAMELLIA enable camellia cipher
MBEDCRYPTO_ARC4 enable arc4 cipher (insecure)
MBEDCRYPTO_PK_EXPORT enable export keys in pem or der format
MBEDCRYPTO_RSA_KEYGEN enable rsa key generator
MBEDCRYPTO_EC enable eckey, eckey_dh and ecdsa algorithms
MBEDCRYPTO_Qt5 also adds adaptors around Qt5's QByteArray

please see CMakeLists.txt for the full list.


tests

samples and unit tests are available under tests/tdd folder.

#run the tests
$mbedcrypto.xbin64/> ./mbedcrypto-tests

possible output:

supports 6 hash algorithms: MD5 , SHA1 , SHA224 , SHA256 , SHA384 , SHA512 ,
supports 5 padding algorithms: PKCS7 , ONE_AND_ZEROS , ZEROS_AND_LEN , ZEROS ,
         NONE ,
supports 6 block modes: NONE , ECB , CBC , CTR , GCM , CCM ,
supports 21 cipher algorithms: AES-128-ECB , AES-192-ECB , AES-256-ECB ,
         AES-128-CBC , AES-192-CBC , AES-256-CBC , AES-128-CTR , AES-192-CTR ,
         AES-256-CTR , AES-128-GCM , AES-192-GCM , AES-256-GCM , DES-ECB ,
         DES-CBC , DES-EDE-ECB , DES-EDE-CBC , DES-EDE3-ECB , DES-EDE3-CBC ,
         AES-128-CCM , AES-192-CCM , AES-256-CCM ,
 this system supports AESNI (hardware accelerated AES)
 this build supports AEAD (authenticated encryption with additional data)
supports 4 pk (public key) algorithms: RSA , EC , EC_DH , ECDSA ,
 this build supports PK export (*.pem, *.der) facility
 this build supports RSA key generation
 this build supports EC (elliptic curve) key generation
supports 12 elliptic curves: SECP192R1 , SECP224R1 , SECP256R1 , SECP384R1 ,
         SECP521R1 , SECP192K1 , SECP224K1 , SECP256K1 , BP256R1 , BP384R1 ,
         BP512R1 , CURVE25519 ,

===============================================================================
All tests passed (952 assertions in 17 test cases)


notes

cryptography

cryptography is both complex and complicated, it requires a vast knowledge of mathematics, concepts, principles, algorithms, standards, conventions, continuous investigation of attacks, ...

As cryptography is mostly used to protect sensitive data, writing a library for it is a daunting task and difficult by any factor.

So instead of writing a library from scratch, mbedcrypto stands on the shoulders of giants, mbedtls is this case.

mbedtls

Although mbedtls is mostly a TLS/SSL library for embedded devices, it has already implemented the most famous and widely used cryptographic algorithms and actively developed and maintained.

Arguably mbedtls has cleaner code than openssl, it's easier to read, use and maintain, and it has been designed for efficiency and portability from scratch (for embedded devices), and has many advantages over openssl like as readability, size, compiling and setup, … to name a few.

disclaimer

  • implementing an easy-to-use, lightweight and portable c++ library for cryptography are the main purpose of mbedcrypto.
  • there are many more algorithms in cryptographic libraries, the focus of mbedcrypto is on the most important or widely used algorithms, tries to be simple and not to bloat your application.
  • as mentioned in notes, the cryptography can be divided into several areas of study and best practices, I'm not a guru nor a specialist in this field.

If you have any ideas, critiques, suggestions or whatever you want to call it, please open an issue. I'll be happy to hear from you what you'd see in this lib. I think about all suggestions, and I try to add those that make sense.

license

Distributed under the MIT license. Copyright (c) 2016, Amir Zamani.