In a cryptographic setting, naive equality checking is dangerous. This class is the timing safe way of doing equality checking. The recommended method of defining equality checking for cryptographically sensitive data is as follows.

1. Define an instance of Equality.
2. Make use of the above instance to define Eq instance as follows.

 data SomeSensitiveType = ...

 instance Equality SomeSensitiveType where
          eq a b = ...

 instance Eq SomeSensitiveType where
      (==) a b = a === b

Check whether two values are equal using the timing safe eq function. Use this function when defining the Eq instance for a Sensitive data type.

The result of a comparison. This is an opaque type and the monoid instance essentially takes AND of two comparisons in a timing safe way.

Timing independent equality checks for vector of values. Do not use this to check the equality of two general vectors in a timing independent manner (use eqVector instead) because:

1. They do not work for vectors of unequal lengths,
2. They do not work for empty vectors.

The use case is for defining equality of data types which have fixed size vector quantities in it. Like for example

 import Data.Vector.Unboxed
 newtype Sha1 = Sha1 (Vector (BE Word32))

 instance Eq Sha1 where
    (==) (Sha1 g) (Sha1 h) = oftenCorrectEqVector g h

Timing independent equality checks for vectors. If you know that the vectors are not empty and of equal length, you may use the slightly faster oftenCorrectEqVector

This class is the starting point of an endian agnostic interface to basic cryptographic data types. Endianness only matters when we first load the data from the buffer or when we finally write the data out. Any multi-byte type that are meant to be serialised should define and instance of this class. The load and store should takes care of the appropriate endian conversion.

Little endian version of the word type w

Big endian version of the word type w

Convert to the little endian variant.

Convert to the big endian variants.

Store the given value at an offset from the crypto pointer. The offset is given in type safe units.

Store the given value as the n-th element of the array pointed by the crypto pointer.

Load from a given offset. The offset is given in type safe units.

Load the n-th value of an array pointed by the crypto pointer.

The pointer type used by all cryptographic library.

In cryptographic settings, we need to measure pointer offsets and buffer sizes in different units. To avoid errors due to unit conversions, we distinguish between different length units at the type level. This type class capturing such types, i.e. types that stand of length units.

Type safe lengths/offsets in units of bytes.

Type safe lengths/offsets in units of bits.

A type whose only purpose in this universe is to provide alignment safe pointers.

Express the length units in bits.

Function similar to bytesQuotRem but works with bits instead.

A length unit u is usually a multiple of bytes. The function bytesQuotRem is like quotRem: the value byteQuotRem bytes is a tuple (x,r), where x is bytes expressed in the unit u with r being the reminder.

Function similar to bitsQuotRem but returns only the quotient.

Function similar to bytesQuotRem but returns only the quotient.

Express length unit src in terms of length unit dest rounding upwards.

Express length unit src in terms of length unit dest rounding downwards.

The expression allocaBuffer l action allocates a local buffer of length l and passes it on to the IO action action. No explicit freeing of the memory is required as the memory is allocated locally and freed once the action finishes. It is better to use this function than allocaBytes as it does type safe scaling. This function also ensure that the allocated buffer is word aligned.

This function allocates a chunk of secure memory of a given size and runs the action. The memory (1) exists for the duration of the action (2) will not be swapped during that time and (3) will be wiped clean and deallocated when the action terminates either directly or indirectly via errors. While this is mostly secure, there can be strange situations in multi-threaded application where the memory is not wiped out. For example if you run a crypto-sensitive action inside a child thread and the main thread gets exists, then the child thread is killed (due to the demonic nature of haskell threads) immediately and might not give it chance to wipe the memory clean. This is a problem inherent to how the bracket combinator works inside a child thread.

TODO: File this insecurity in the wiki.

Creates a memory of given size. It is better to use over mallocBytes as it uses typesafe length.

A version of hGetBuf which works for any type safe length units.

Similar to sizeOf but returns the length in type safe units.

Sets the given number of Bytes to the specified value.

Move between pointers.

Copy between pointers.

Tuples that encode their length in their types. For tuples, we call the length its dimension

Function that returns the dimension of the tuple. The dimension is calculated without inspecting the tuple and hence the term dimension (undefined :: Tuple 5 Int) will evaluate to 5.

Computes the initial fragment of a tuple. No length needs to be given as it is infered from the types.

Construct a tuple out of the list. This function is unsafe and will result in run time error if the list is not of the correct dimension.

This class captures all types that have some sort of description attached to it.