Cryptographic library for Haskell
Clone or download
piyush-kurur Merge reintroduced handwritten C implementations.
- Besides the verse implmentation we have the handwritten C
  implementations as well.

- The benchmark now covers all of them.
Latest commit 85a861a Nov 10, 2018
Permalink
Failed to load latest commit information.
benchmarks benchmarks: set encoding to utf8 for windows. Nov 10, 2018
core update the info command properly. Sep 26, 2018
implementation integrated the handwritten version of ChaCha20. Nov 7, 2018
indef expose the name of the csprg source. Sep 26, 2018
libverse @ 78f0aba update libverse to use the alternate version of sha2 Nov 4, 2018
liquid enable liquid haskell checks on Sha1 and Sha2 hashes. Jun 22, 2017
mans manpage: some cleanup in the writing. Dec 11, 2017
notes some more ideas to simplify the path to version 1. Mar 2, 2018
old-raaz/Raaz/Hash remove directory name clash on case-insensitive file systems Jun 7, 2018
raaz raaz-cmd: info now more informative. Sep 26, 2018
scripts simplified the liquid haskell driver script. Jul 20, 2018
tests better source dir for tests and benchmarks. Sep 20, 2018
wiki @ 326f94c update to the latest wiki version. Nov 3, 2018
.gitignore update gitignore. Jun 8, 2018
.gitmodules added the libverse submodule. Oct 21, 2018
.travis.yml less verbose build in travis. Nov 10, 2018
CHANGELOG.md CHANGELOG: mention libverse. Oct 31, 2018
CONTRIBUTORS CONTRIBUTORS: added full name of satvikc Sep 16, 2017
LICENSE back to one package. Sep 20, 2018
README.md readme: fixing typos and language usage. Nov 3, 2018
Releasing.md update the releasing note to include bumping of manpage version. Oct 11, 2017
Reviewing.md docs tweaks on reviewing and releasing. Sep 20, 2017
Setup.lhs moved to a simple build. Jan 26, 2016
appveyor.yml enable unicode in appveyor version. Nov 10, 2018
raaz.cabal integrated the handwritten version of ChaCha20. Nov 7, 2018

README.md

Raaz: A secure cryptographic library

Build Staus Build Windows In Progress Stackage LTS Stackage Nightly Hackage Hackage Dependencies

The Raaz cryptographic library is a collection of Haskell packages whose goal is to provide high level access to cryptographic operations. The type system of Haskell plays a crucial role in avoiding some of common bugs in cryptographic implementations. The library is intended to be used for standalone cryptographic applications as well as implementing network protocols. Besides, we put a lot of emphasis on better API design and good documentation which, we believe, makes the usage of the library secure.

Some of the features that are unique to raaz are the following

  1. Pervasive use of types for better safety.
  2. Default choice of primitives and implementations are safe.
  3. Mechanism to have multiple implementations for any given cryptographic primitives. An advanced user who has an indepth knowledge of the platform should be able to plugin the desired implementation
  4. Strong emphasis on API design with through documentation.

Building

Ensure that you have a ghc >= 8.2 and cabal version >= 2.2. These are necessary due to the crucial role played by backpack in the design. Having met these pre-requisites, the recommended approach towards building raaz using the following command.

cabal new-build

Backpack support is still work in progress for stack and it should be possible to use stack once this issue is resolved.

Hacking and Discussion

For details please refer to our wiki.

Releasing and reviewing.

The repository also contains the file Releasing.md which contains checklist for releasing a new version of the library. Any crypto library should undergo through review by multiple people. In the file Reviewing.md, we collect some common pitfalls to look for while reviewing the code. It is good to actively look for some of the problems suggested there but of course one should also look for other problems.

Backpack based pluggable implementations

NOTE: The interface that we describe now needs the ability for a single package (raaz in our case) to expose multiple components. This is still work in progress but is expected to be merged in soon (See https://github.com/haskell/cabal/issues/4206). Without this feature the interface described below cannot be used.

Certain cryptographic primitives can have better (both in terms of safety and performance) implementations that exploit specific hardware features. For example, if the underlying processor supports vector extensions like avx2, some primitives like chacha20 can be made up to 2x faster. Production quality cryptographic libraries are expected to provide implementations tuned for such specific hardware. In addition, it should be possible for users of esoteric platforms to override the default implementation with their own custom implementations. We use mixin-style modules provided by backpack to achieve this goal.

The raaz cryptographic library is organised as a single package containing multiple component. A user who only cares about the high level interface can just ignore these individual components and use only the top level library raaz much like any other package. For users who do care about changing the underlying implementation, having an overall picture of these components is helpful.

  1. The component raaz:core contains core types and utility functions. You would most likely need this component to begin with.

  2. The component raaz:indef exports a signature Implementation and a module Utils that depends on the signature. The Implementation signature captures the Haskell interface to the low level implementation of a cryptographic block primitive. To complement this indefinite package the component raaz:implementation provides implementations that can be "mixed-in" in place the signature Implementation. A user can select one such implementation from raaz:implementation, or can code up her own as long as it satisfies the Implementation signature.

  3. For each block primitive foo that is supported by raaz there is a component raaz:foo-indef, that captures the various implementations of the primitive foo. It reexports (a restricted version of) the signature Implementation and the module Utils as Foo.Implementation and Foo.Utils respectively. For example, raaz:chacha20-indef component captures low-level implementations of the ChaCha20 stream cipher and exposes them as the signature ChaCha20.Implementation and ChaCha20.Utils

  4. Any library bar that wants to use a primitive foo while giving the flexibility for the downstream user to plugin different implementations of foo should define an indefinite package bar:indef. The downstream user will then be able to mixin the appropriate implementation using the following in her cabal file

    
      build-depends: raaz:chacha20-indef
                   , bar:indef
                   , raaz:implementation
      mixin: bar:indef (Bar as Bar.Portable)
                requires (ChaCha20.Implementations as ChaCha20.Portable)
                  -- This makes use of the portable c implementation of
                  -- ChaCha20 from raaz:implementation
    

For an example of this usage check out the component raaz:hash-indef and its use in the main library.

About the name

The word Raaz (राज़) stands for secret in Hindi.