raaz-0.1.0: The raaz cryptographic library.

Safe HaskellNone
LanguageHaskell2010

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

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

toByteString :: EndianStore a => a -> ByteString Source #

Convert stuff to bytestring

fromByteString :: EndianStore a => ByteString -> Maybe a Source #

Try parsing back a value. Returns nothing on failure.

Instances

Encodable ByteString Source # 
Encodable Base64 Source # 
Encodable Base16 Source # 
Encodable SHA1 Source # 
Encodable SHA224 Source # 
Encodable SHA256 Source # 
Encodable SHA384 Source # 
Encodable SHA512 Source # 
Encodable KEY Source # 
Encodable IV Source # 
Encodable IV Source # 
Encodable KEY256 Source # 
Encodable KEY192 Source # 
Encodable KEY128 Source # 
Encodable a => Encodable (BITS a) Source # 
Encodable a => Encodable (BYTES a) Source # 
Encodable (BE Word32) Source # 
Encodable (BE Word64) Source # 
Encodable (LE Word32) Source # 
Encodable (LE Word64) Source # 
Encodable (WriteM IO) Source # 
Encodable h => Encodable (HMAC h) Source # 

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.

Minimal complete definition

encodeByteString, decodeFormat

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.

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.

The base16 encoding only produces valid hex characters. However, to aid easy presentation of long hexadecimal strings, a user can add add arbitrary amount of spaces, newlines and the character :. The decoding ignores these characters.

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. The base-64 encoding only produces valid base-64 characters. However, to aid easy presentation of long base-64 strings, a user can add add arbitrary amount of spaces and newlines. The decoding ignores these characters.