raaz-0.0.2: The raaz cryptographic library.

Safe HaskellNone

Raaz.Core.Encode

Contents

Synopsis

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 whereSource

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 -> ByteStringSource

Convert stuff to bytestring

fromByteString :: ByteString -> Maybe aSource

Try parsing back a value. Returns nothing on failure.

unsafeFromByteString :: ByteString -> aSource

Unsafe version of fromByteString

Instances

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

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 -> fmtSource

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

decodeFormat :: fmt -> ByteStringSource

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 -> fmtSource

Encode in a given format.

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

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

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

Translate from one format to another.

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

The unsafe version of decode.

The base 16 encoding format

data Base16 Source

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

fromBase16 :: Encodable a => String -> aSource

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 -> StringSource

Base16 variant of show.

Other binary formats.

data Base64 Source

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

Instances