raaz: The raaz cryptographic library.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain]

Raaz is a cryptographic library for Haskell. The library is designed with a special emphasis on using the type system of Haskell to eliminate a large set of vulnerabilities like buffer overflows, timing attacks etc. It also strives to achieve this safety with no compromise on performance.


[Skip to ReadMe]

Properties

Versions0.0.1, 0.0.2, 0.1.0, 0.1.1, 0.2.0, 0.3.0
Change logCHANGELOG.md
Dependenciesbase (>=4.7 && <4.13), bytestring (>=0.9 && <0.11), cipher-indef, core, deepseq (>=1.1 && <1.5), hash-indef, implementation, mtl, optparse-applicative (>=0.13.0.0), raaz, random-indef, transformers, vector (>=0.7.1 && <0.13) [details]
LicenseBSD-3-Clause
AuthorPiyush P Kurur
Maintainerppk@cse.iitk.ac.in
CategoryCodec, Raaz
Home pagehttps://github.com/raaz-crypto/raaz
Bug trackerhttps://github.com/raaz-crypto/raaz/issues
Source repositoryhead: git clone https://github.com/raaz-crypto/raaz
Executablesraaz
UploadedSat Nov 3 09:03:35 UTC 2018 by PiyushKurur

Modules

[Index]

Flags

NameDescriptionDefaultType
linux-getrandom

Use the getrandom for system entropy instead of devurandom. Enabled by default but disable this when building for kernel < 3.17.

EnabledManual
native

Compile for native architecture. Often this enables a lot of platform specific optimisation which lead to better performance. Do not enable this when packaging though. Also tested only with gcc

DisabledManual
avx2

Support avx2 optimisations. Warning: enable only if you are sure of support.

DisabledManual

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainers' corner

For package maintainers and hackage trustees


Readme for raaz-0.3.0

[back to package description]

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

  1. 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.