raaz-0.0.2: The raaz cryptographic library.

Safe HaskellNone
LanguageHaskell98

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 where Source

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

Minimal complete definition

Nothing

Methods

toByteString :: a -> ByteString Source

Convert stuff to bytestring

fromByteString :: ByteString -> Maybe a Source

Try parsing back a value. Returns nothing on failure.

unsafeFromByteString :: ByteString -> a Source

Unsafe version of fromByteString

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

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 Source

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

decodeFormat :: fmt -> ByteString Source

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 Source

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

Format Base16 Source 
Format Base64 Source 

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

Encode in a given format.

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

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

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

Translate from one format to another.

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

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.

fromBase16 :: Encodable a => String -> a Source

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 Source

Base16 variant of show.

Other binary formats.

data Base64 Source

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