mbedtls.cr

Crystal language bindings to the mbed TLS lightweight TLS and cryptography library, based on the openssl.cr bindings.

In development, not yet stable.

Implemented:

• Message digests (hashing)
• HMAC authenticated digests
• CSPRNG (cryptographic random numbers)
• Symmetric encryption
• Asymmetric encryption
• X509 certificate utilities
• TLS connection wrapping

Disclaimer

Cryptography is hard. This library is not thoroughly tested; it might have flaws in it's bindings. As per the terms of the license, by using this you understand this is at your own risk.

Installation

You must install mbed TLS for your platform.

I test mbedtls.cr with mbed TLS 2.4.2. Other versions could work, but they are not tested. You can file a Pull Request on this Readme if you succeed in getting it to work with other versions. It won't work with mbed TLS versions before 2.0, or PolarSSL.

Please note: Versions of mbed TLS before 2.1 are under the GPL2 licence, and your distribution may bundle the GPL2 licensed version. If you need to redistribute the mbed TLS library with your project, consider downloading and building the Apache licensed version. The project is the same, it has Apache license headers and files replacing the GPL ones.

Installing mbed TLS

macOS:

brew install mbedtls

Ubuntu/Debian

brew install libmbedtls libmbedtls-dev

Fedora/CentOS

yum install mbedtls mbedtls-devel

Note: You need Fedora 22+ for a 2.x mbed version. CentOS and RHEL 6/7 users will need to use EPEL for suitable mbedtls packages.

Arch Linux

pacman -S mbedtls

Never use pacman -Sy when installing packages!

Using in your project or package

Add this to your application's shard.yml:

dependencies:
  mbedtls:
    github: ceph3us/mbedtls.cr

Usage

Full usage information is available in the documentation.

Message Digests (hashing)

require "mbedtls"

hash = MbedTLS::Digest::SHA256.new

# You can hash a whole string...
hash << "Hello, world"
puts %(The SHA256 hash of "Hello, world" is #{hash})

hash.reset

# ...or some concatenated strings...
hash << "Hello, " << "world"
puts %(The SHA256 hash of "Hello, world" is #{hash})

hash.reset

# ...or even a file!
hash.file("hello.txt")
puts "The SHA256 hash of the file hello.txt is #{hash}"

Development

If you have any suggestions or issues with the project, I'd be happy to listen to your concerns. Post a GitHub issue so we can discuss them.

Contributing

mbedtls.cr uses the GitLab flow for repositories. To contribute:

1. Fork it!
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Submit a new Pull Request with your changes.

If you do this a lot, consider the awesome Git Town which has lots of handy shortcuts for the GitLab flow and other Git workflows.

Contributors

• ceph3us Michael Holmes - creator, maintainer