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.
- small size: the
mbedcrypto
is less than250KB
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 compliantstl
, compiled and tested by:g++ 5.x+ / 6+
underlinux
clang 3.6+
underos x
mingw 5.x+
undermsys2
(windows 8.1)msvc 2015
community edition underwindows 7
- low dependency:
- 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.
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) andaes-ni
(hardware accelerated)des
and3des
(triple-des)- optional ciphers:
blowfish
,camellia
andarc4
-
cipher block modes:
ecb
electronic codebookcbc
cipher block chainingctr
counter modegcm
Galois/counter andccm
(counter cbc-mac) modes. see authneticated encryption with additional data (AEAD)- optional block modes:
cfb
,stream
(forarc4
)
-
paddings:
pkcs7
- one and zeros
- zeros and length
- zeros
-
random byte generator: see wiki samples
ctr_drbg
counter mode deterministic random byte generator based onaes-256
NIST SP 800-90
-
pki (asymmetric): public key infrastructure, see wiki: rsa samples and wiki: ec samples
rsa
pem
andder
key formats (ASN.1)- optional pks:
eckey
elliptic curve,eckey_dh
elliptic key Diffie–Hellman,ecdsa
elliptic key digital signature algorithm,rsa_alt
andrsassa_pss
RSA standard signature algorithm, probabilistic signature scheme - optional
rsa
key generator - optional
ec curves
from well known domain parameters asNIST
,Kolbitz
,brainpool
andCurve25519
.
total number of supported algorithms:
- hashes: 9
- paddings: 5
- ciphers: 47
- pki: 6
see types.hpp
to setup all 3rdparty dependencies:
- ARMmbed/mbedtls
- catchorg/Catch2
run:
$mbedcrypto> ./setup.sh all
# optionally: $> ./setup.sh help
this script downloads the latest release files (master branch) of dependencies
into ./3rdparty/
directory.
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
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.
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)
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.
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.
- implementing an easy-to-use, lightweight and portable
c++
library for cryptography are the main purpose ofmbedcrypto
. - 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.
Distributed under the MIT license. Copyright (c) 2016, Amir Zamani.