Raaz is a cryptographic library that provides an easy to use, type safe interface for cryptographic applications. Applications can get their cryptography wrong and this can have disastrous consequences. This can be due to the wrong choices of the underlying cryptographic primitives, or due to ignoring certain implementation details (reusing the key, nounce pair). To prevent this kind of issues, raaz, like other modern libraries, give a very high level interface with the library taking the responsibility of selecting sane primitives and their correct usages. The recommended usage there is to import the top level module and get going.

module Main where

import Raaz

In addition, raaz makes use of the type system of Haskell to give additional guarantees:

Type safety:

Instead of representing cryptographic data as plain strings, raaz uses distinct types for semantically distinct cryptographic data. If the user inadvertently compares a Sha512 digest with a Blake2b digest, the compiler will flag this as an error. Compare this with the situation in many libraries where both these are just 512-bit quantities.

Timing safe equality:

All cryptographically sensitive data have timing safe equality operation ==. The default comparison is therefore safe and we encourage its use. Compare this with many other libraries where one has to remember to use specific functions sanitised timing safe comparisons.

Locked memory:

The interface to locked memory is provided through the combinators withMemory and withSecureMemory. These combinators take any IO action that expects a memory element (captured by the class Memory) and runs it by providing such an element. The underlying memory buffer is zeroed at the end of the action. In addition, withSecureMeory ensures that the memory allocated for the memory element is locked (and hence not swapped out). This gives a relatively higher level interface for locked memory. A word of caution though. Interfaces that directly deal with memory elements should be considered low-level code and should better be left to advanced users. Furthermore certain usages, particularly those that involve reading pure values out of the memory element, are problematic and a lot of caution needs to be employed when using this interface.

The raaz library provides the following cryptographic operations.

Message Digest:

Compute a short summary of a message that can act as an integrity check for the message. A computationally bound adversary cannot create two distinct messages with the same digest. It does not ensure authentication.

Message Authentication:

In addition to integrity, we often want to ensure that a particular message has indeed come from a know peer (with whom we share a secret). Message authentication is for this purpose. It however, does not ensure privacy

Message Locking:

In addition to authentication, often we want to ensure that the message is private, i.e. no one other than the originator (with whom we share a secret) should be able to know the contents of our communication. Message lock (via authenticated encryption) is for this purpose.

Cryptographically secure random data:

We also have an interface to provide cryptographically secure bytes/data.

For detailed information on the api supported, please consult the documentation of the individual modules.

Many cryptographic types exposed from this library like hashes, message authentication, keys and nounces can be converted from/to their textual representation (via the Show, IsString instances) as well as binary representation (via their Encodable instance).

WARNING: textual/binary encoding are not type safe

A user of the raaz library should use the explicit data types instead of their encodings. There are a few security consequences of violating this principle

1. The IsString instance means that we represent values as string within program source (via OverloadedStrings). Do not do this unless it is to write unit tests as this can result in runtime bugs.
2. Timing safe comparison will get compromised if one compares the encodings (bytestring) instead of the types themselves