Welcome to botan

Hackage: botan-bindings Hackage: botan-low Hackage: botan Build Haddocks

botan is a set of Haskell bindings for the Botan cryptography library.

Botan's goal is to be the best option for cryptography in C++ by offering the tools necessary to implement a range of practical systems, such as TLS protocol, X.509 certificates, modern AEAD ciphers, PKCS#11 and TPM hardware support, password hashing, and post quantum crypto schemes.

Acknowledgements

This project has received support from the Haskell Foundation, and was made possible through funding provided by Mercury.

Navigation

Introduction

This project has the goal of providing a set of safe and performant bindings to the Botan C++ cryptography library via its C FFI (Foreign Function Interface). It does this by providing 3 libraries at varying levels of complexity and abstraction:

• botan-bindings contains raw bindings with buffers and pointers, and is otherwise an almost a 1:1 translation of the C FFI into Haskell
• botan-low contains low-level bindings with imperative IO and exceptions, and safely wraps buffers and pointers into bytestrings and autoreleased objects
• botan contains high-level bindings with strong types and idiomatic Haskell, and provides algebraic data types and convenience functions

We suggest using the highest-level library possible, unless you wish to build your own abstraction over the Botan C++ library. The highest-level stable library is currently: botan-low

Installation

This library requires Botan 3 to be installed in order to work. See Building the Library in the handbook for more details.

Unix package

~~Botan is available already in nearly all packaging systems so you can probably install it through your distribution / system package manager.~~

At current, Botan 2 is readily available, but Botan 3 is not yet available as a prebuilt linux package. Please see 'Building from source'.

MacOS package

Botan is available through the Homebrew package manager:

From source

Botan can be built from source, for additional configuration options and customization.

Windows from source

Prebuilt botan is not available for windows, and it must be built from source. The process is similar to building from source in Unix or MacOS.

Usage

You will need to add botan as a package dependency in order to use it.

After you have added botan as a dependency, you can begin importing modules and using them in your code.

import Botan.Low.Hash

main = do
    hash <- hashInit "SHA-256"
    digest <- hashUpdateFinalize hash "Fee fi fo fum!"
    print digest

Tutorials

Resources

There are several resources for this project that might be helpful:

• Devlog for project status and updates.
• GitHub for Haskell source code, issues, and pull requests.
• Proposal Haskell Foundation funding proposal submission thread.

As well, there are resources for the original Botan C++ library:

• Botan Crypto and TLS for Modern C++
• Botan C++ Github for original Botan C++ source code, issues, and pull requests.
• Botan Handbook for documentation on the original library
• Botan FFI for documentation on the Botan C FFI
• Issue FFI APIs for X.509 are insufficient

License

This project is licensed under the BSD 3-Clause License and is free, open-source software.

Contributing

There are several ways to contribute to the development of this project, and we are happy to receive any bug reports, fixes, documentation, and any other improvements to this project.

Reporting Bugs

See a bug?

1. Describe the issue
2. Write down the steps required to reproduce the issue
3. Report the issue by opening a ticket!

Assist in Development

Want to help?

1. Fork or clone the repo, and create a new branch:

git checkout https://github.com/haskellfoundation/botan -b some_new_branch

1. Make your changes, and test them
2. Submit a pull request with a comprehensive description of the changes

Donations

This is free, open-source software. If you'd like to support the continued development of this project and future projects like this, or just to say thanks, you can donate directly using the following link(s):

ko-fi