Skip to content
Cryptographic library for Haskell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmarks cleanup benchmark directory Apr 12, 2019
core
implementation move entropy modules to the implementation component. Apr 27, 2019
indef expose implementation name and description from interfaces. May 12, 2019
libverse @ d6cd708
liquid hlint liquid haskell checks. Apr 12, 2019
mans update the man page of raaz the command. Feb 5, 2019
notes
old-raaz/Raaz/Hash
raaz
scripts simplified the liquid haskell driver script. Jul 20, 2018
tests more hlint suggestions from the travis builds. Apr 12, 2019
wiki @ 326f94c update to the latest wiki version. Nov 3, 2018
.gitignore
.gitmodules
.travis.yml travis: more efficient package installation. May 15, 2019
CHANGELOG.md
CONTRIBUTORS CONTRIBUTORS: added full name of satvikc Sep 16, 2017
LICENSE-APACHE-2.0
LICENSE-BSD3
README.md
Releasing.md
Reviewing.md
Setup.lhs
appveyor.yml
raaz.cabal

README.md

Raaz: A secure cryptographic library

Build Staus Build Windows Hackage Hackage Dependencies

Raaz is a cryptographic library in Haskell that provide a high level and safe access to a lot of cryptographic operations. The library can be used for standalone cryptographic applications as well as for implementing other network protocols. 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 in-depth 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.

One of the biggest safety feature of the raaz cryptographic library is that the implementations are fast and safe by default. However, there are some rare cases when the user might want to rework the internals of the raaz library. This could be for performance reasons --- certain cryptographic primitives can have better (both in terms of safety and performance) implementations that exploit specific hardware features --- or due to safety reasons -- the default entropy source might not be the best on certain virtualised system. While we do not recommend such tinkering in general, it is nonetheless possible to tweak each and every implementations of primitives or tweak the underlying entropy source using backpack style modules and signatures.

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. We assume some familiarity with the backpack system of mixin style modules for Haskell for the rest of this section.

The overall picture can be simplified as follows: Any primitive that raaz supports is exposed through its Interface module which in turn depends on an appropriate Implementation module. This dependency is satisfied by the mixin mechanism of backpack.

  1. The package raaz:prim-indef exposes an Interface module, one for each primitive that raaz supports. For example, the Blake2b.Interface provides access to blake2b hashing. However, this package cannot be used as such because it is a package with a hole. One needs to actually mixin a module with name Blake2b.Implementation for this to work.

  2. The component raaz:implementation provides the needed Implementation modules and by listing both raaz:prim-indef and raaz:implementation in the build-depends the implementation modules needed by raaz:prim-indef are satisfied by the default implementations from raaz:implementation. This is how the raaz library provides you with the interface.

   build-depends: raaz:prim-indef
                , raaz:implementation

Overiding the default implementation

The raaz:implementation often provide multiple implementation for the same primitives but for a particular primitives selects one as the default implementation. If we stick to the Blake2b example, raaz:implementation exposes Blake2b.CPortable and Blake2b.CHandWritten of which Blake2b.CPortable is made the default implementation by re-exporting it under the name Blake2b.Implementation. This means that when we add both raaz:prim-indef and the raaz:implementation to the build depends field, the demand for the module Blake2b.Implementation from the former component is satisfied by the Blakd2b.CPortable. We can selectively override this using the following cabal stanza.

build-depends: raaz:raaz-indef
             , raaz:implementation
mixins: raaz:raaz-indef requires (Blake2b.Implementation as Blake2b.CHandWritten)

You can also mix-in custom implementations (i.e implementations that are not exposed by raaz) using this technique.

build-depends: raaz:raaz-indef
             , raaz-implementation
             , my-custom-blake2

mixins: raaz:prim-indef requires (Blake2b.Implementation as MyCustom.Blake2b.Implementation)

The above stanza ensures all primitives except blake2b uses the default implementation from raaz:implementation but Blake2b alone uses MyCustom.Blake2b.Implementation (exposed from my-custom-blake2).

Overriding the Entropy source.

The raaz library expects entropy to be supplied through and interface captured by the signature Entropy exposed by the raaz:random-api component. We can override the entropy source by using the following cabal stanza

build-depends: raaz:raaz-indef
             , raaz:implementation
             , my-custom-blake2
			 , my-custom-entropy

mixins: raaz:raaz-indef requires (Blake2b.Implementation as MyCustom.Blake2b.Implementation,
                                  Entropy as MyCustom.Entropy)

About the name

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

Legal

Copyright 2012 Piyush P Kurur

The library is licensed under

You may not use this software except in compliance with one of the above Licenses (at your option).

SPDX-License-Identifier: (Apache-2.0 OR BSD-3-Clause)

Unless required by applicable law or agreed to in writing, software distributed under these Licenses is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. For the exact terms and conditions see the accompanying LICENSE file.

You can’t perform that action at this time.