Raaz: A secure cryptographic library
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
- Pervasive use of types for better safety.
- Default choice of primitives and implementations are safe.
- 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.
- Strong emphasis on API design with through documentation.
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.
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 hacking see our github repository.
For discussion see our google groups mailing list.
Hangout on irc.freenode.net (channel: #haskell-raaz).
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.
Interfacemodule, one for each primitive that raaz supports. For example, the
Blake2b.Interfaceprovides 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.Implementationfor this to work.
raaz:implementationprovides the needed
Implementationmodules and by listing both
build-dependsthe implementation modules needed by
raaz:prim-indefare 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
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.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
MyCustom.Blake2b.Implementation (exposed from
Overriding the Entropy source.
The raaz library expects entropy to be supplied through and interface
captured by the signature
Entropy exposed by the
component. We can override the entropy source by using the following
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
Raaz (राज़) stands for secret in Hindi.
Copyright 2012 Piyush P Kurur
The library is licensed under
- Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0
- BSD 3-Clause license https://opensource.org/licenses/BSD-3-Clause
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.