Raaz.Core.Encode

Encoding of binary data.

Often one wants to represent cryptographic hashes, secret keys or just binary data into various enocoding formats like base64, hexadecimal etc. This module gives a generic interface for all such operations. There are two main classes that capture the essence of encoding.

Format

Each encoding supported by this module is an instance of this class. For printing and for easy inclusion in source code appropriate instances of Show and IsString is provided for these types.

Encodable

Instances of this class are those that can be encoded into any of the available formats. Actual encoding and decoding of elements of this class can be done by the combinators encode and decode

The raaz library exposes many instances of Format which are all some form of encoding of binary data.

class Encodable a where

The type class Encodable captures all the types that can be encoded into a stream of bytes. By making a type say Foo an instance of the Encodable class, we get for free methods to encode it in any of the supported formats (i.e. instances of the class Format).

Minimum complete definition for this class is toByteString and fromByteString. Instances of EndianStore have default definitions for both these functions and hence a trivial instance declaration is sufficient for such types.

 instance Encodable Foo

Methods

toByteString :: a -> ByteString

Convert stuff to bytestring

fromByteString :: ByteString -> Maybe a

Try parsing back a value. Returns nothing on failure.

unsafeFromByteString :: ByteString -> a

Unsafe version of fromByteString

Instances

Encodable ByteString

Encodable Base16

Encodable Base64

Encodable Write

Encodable SHA1

Encodable SHA224

Encodable SHA256

Encodable SHA384

Encodable SHA512

Encodable IV

Encodable KEY256

Encodable KEY192

Encodable KEY128

Encodable a => Encodable (BITS a)

Encodable a => Encodable (BYTES a)

Encodable (BE Word32)

Encodable (BE Word64)

Encodable (LE Word32)

Encodable (LE Word64)

Encodable h => Encodable (HMAC h)

class (IsString fmt, Show fmt, Encodable fmt) => Format fmt where

A binary format is a representation of binary data often in printable form. We distinguish between various binary formats at the type level and each supported format corresponds to an instance of the the class Format. The encodeByteString and decodeFormat are required to satisfy the laws

 decodeFormat . encodeByteString = id

For type safety, the formats themselves are opaque types and hence it is not possible to obtain the underlying binary data directly. We require binary formats to be instances of the class Encodable, with the combinators toByteString and fromByteString of the Encodable class performing the actual encoding and decoding.

Instances of Format are required to be instances of Show and so that the encoded format can be easily printed. They are also required to be instances of IsString so that they can be easily represented in Haskell source using the OverloadedStrings extension. However, be careful when using this due to the fact that invalid encodings can lead to runtime errors.

Methods

encodeByteString :: ByteString -> fmt

Encode binary data into the format. The return type gurantees that any binary data can indeed be encoded into a format.

decodeFormat :: fmt -> ByteString

Decode the format to its associated binary representation. Notice that this function always succeeds: we assume that elements of the type fmt are valid encodings and hence the return type is ByteString instead of Maybe ByteString.

Instances

Format ByteString

Bytestring itself is an encoding format (namely binary format).

Format Base16

Format Base64

encode :: (Encodable a, Format fmt) => a -> fmt

Encode in a given format.

decode :: (Format fmt, Encodable a) => fmt -> Maybe a

Decode from a given format. It results in Nothing if there is a parse error.

translate :: (Format fmt1, Format fmt2) => fmt1 -> fmt2

Translate from one format to another.

unsafeDecode :: (Format fmt, Encodable a) => fmt -> a

The unsafe version of decode.

The base 16 encoding format

data Base16

The type corresponding to base-16 or hexadecimal encoding. The Base16 encoding has a special place in this library: most cryptographic types use Base16 encoding for their Show and IsString instance. The combinators fromBase16 and showBase16 are exposed mainly to make these definitions easy.

Instances

Eq Base16

Show Base16

IsString Base16

Monoid Base16

Format Base16

Encodable Base16

fromBase16 :: Encodable a => String -> a

Base16 variant of fromString. Useful in definition of IsString instances as well as in cases where the default IsString instance does not parse from a base16 encoding.

showBase16 :: Encodable a => a -> String

Base16 variant of show.

Other binary formats.

data Base64

The type corresponding to the standard padded base-64 binary encoding.

Instances

Eq Base64

Show Base64

IsString Base64

Monoid Base64

Format Base64

Encodable Base64