raaz-0.1.1: The raaz cryptographic library.

Safe Haskell | None
Language | Haskell2010

Raaz.Core.Encode

Contents

- Encoding of binary data.
  - The base 16 encoding format
  - Other binary formats.

Synopsis

- class Encodable a where
- class (IsString fmt, Show fmt, Encodable fmt) => Format fmt where
- encode :: (Encodable a, Format fmt) => a -> fmt
- decode :: (Format fmt, Encodable a) => fmt -> Maybe a
- translate :: (Format fmt1, Format fmt2) => fmt1 -> fmt2
- unsafeDecode :: (Format fmt, Encodable a) => fmt -> a
- data Base16
- fromBase16 :: Encodable a => String -> a
- showBase16 :: Encodable a => a -> String
- data Base64

# 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 # |
Methods toByteString :: ByteString -> ByteString Source # fromByteString :: ByteString -> Maybe ByteString Source # unsafeFromByteString :: ByteString -> ByteString Source #
Encodable Base64 Source # |
Methods toByteString :: Base64 -> ByteString Source # fromByteString :: ByteString -> Maybe Base64 Source # unsafeFromByteString :: ByteString -> Base64 Source #
Encodable Base16 Source # |
Methods toByteString :: Base16 -> ByteString Source # fromByteString :: ByteString -> Maybe Base16 Source # unsafeFromByteString :: ByteString -> Base16 Source #
Encodable SHA1 Source # |
Methods toByteString :: SHA1 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA1 Source # unsafeFromByteString :: ByteString -> SHA1 Source #
Encodable SHA224 Source # |
Methods toByteString :: SHA224 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA224 Source # unsafeFromByteString :: ByteString -> SHA224 Source #
Encodable SHA256 Source # |
Methods toByteString :: SHA256 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA256 Source # unsafeFromByteString :: ByteString -> SHA256 Source #
Encodable SHA384 Source # |
Methods toByteString :: SHA384 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA384 Source # unsafeFromByteString :: ByteString -> SHA384 Source #
Encodable SHA512 Source # |
Methods toByteString :: SHA512 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA512 Source # unsafeFromByteString :: ByteString -> SHA512 Source #
Encodable KEY Source # |
Methods toByteString :: KEY -> ByteString Source # fromByteString :: ByteString -> Maybe KEY Source # unsafeFromByteString :: ByteString -> KEY Source #
Encodable IV Source # |
Methods toByteString :: IV -> ByteString Source # fromByteString :: ByteString -> Maybe IV Source # unsafeFromByteString :: ByteString -> IV Source #
Encodable IV Source # |
Methods toByteString :: IV -> ByteString Source # fromByteString :: ByteString -> Maybe IV Source # unsafeFromByteString :: ByteString -> IV Source #
Encodable KEY256 Source # |
Methods toByteString :: KEY256 -> ByteString Source # fromByteString :: ByteString -> Maybe KEY256 Source # unsafeFromByteString :: ByteString -> KEY256 Source #
Encodable KEY192 Source # |
Methods toByteString :: KEY192 -> ByteString Source # fromByteString :: ByteString -> Maybe KEY192 Source # unsafeFromByteString :: ByteString -> KEY192 Source #
Encodable KEY128 Source # |
Methods toByteString :: KEY128 -> ByteString Source # fromByteString :: ByteString -> Maybe KEY128 Source # unsafeFromByteString :: ByteString -> KEY128 Source #
Encodable a => Encodable (BITS a) Source # |
Methods toByteString :: BITS a -> ByteString Source # fromByteString :: ByteString -> Maybe (BITS a) Source # unsafeFromByteString :: ByteString -> BITS a Source #
Encodable a => Encodable (BYTES a) Source # |
Methods toByteString :: BYTES a -> ByteString Source # fromByteString :: ByteString -> Maybe (BYTES a) Source # unsafeFromByteString :: ByteString -> BYTES a Source #
Encodable (BE Word32) Source # |
Methods toByteString :: BE Word32 -> ByteString Source # fromByteString :: ByteString -> Maybe (BE Word32) Source # unsafeFromByteString :: ByteString -> BE Word32 Source #
Encodable (BE Word64) Source # |
Methods toByteString :: BE Word64 -> ByteString Source # fromByteString :: ByteString -> Maybe (BE Word64) Source # unsafeFromByteString :: ByteString -> BE Word64 Source #
Encodable (LE Word32) Source # |
Methods toByteString :: LE Word32 -> ByteString Source # fromByteString :: ByteString -> Maybe (LE Word32) Source # unsafeFromByteString :: ByteString -> LE Word32 Source #
Encodable (LE Word64) Source # |
Methods toByteString :: LE Word64 -> ByteString Source # fromByteString :: ByteString -> Maybe (LE Word64) Source # unsafeFromByteString :: ByteString -> LE Word64 Source #
Encodable (WriteM IO) Source # |
Methods toByteString :: WriteM IO -> ByteString Source # fromByteString :: ByteString -> Maybe (WriteM IO) Source # unsafeFromByteString :: ByteString -> WriteM IO Source #
Encodable h => Encodable (HMAC h) Source # |
Methods toByteString :: HMAC h -> ByteString Source # fromByteString :: ByteString -> Maybe (HMAC h) Source # unsafeFromByteString :: ByteString -> 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`.

Instances

Format ByteString Source # | Bytestring itself is an encoding format (namely binary format).
Methods encodeByteString :: ByteString -> ByteString Source # decodeFormat :: ByteString -> ByteString Source #
Format Base64 Source # |
Methods encodeByteString :: ByteString -> Base64 Source # decodeFormat :: Base64 -> ByteString Source #
Format Base16 Source # |
Methods encodeByteString :: ByteString -> Base16 Source # decodeFormat :: Base16 -> ByteString 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.

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.

Instances

Eq Base16 Source # |
Methods (==) :: Base16 -> Base16 -> Bool # (/=) :: Base16 -> Base16 -> Bool #
Show Base16 Source # |
Methods showsPrec :: Int -> Base16 -> ShowS # show :: Base16 -> String # showList :: [Base16] -> ShowS #
IsString Base16 Source # |
Methods fromString :: String -> Base16 #
Monoid Base16 Source # |
Methods mempty :: Base16 # mappend :: Base16 -> Base16 -> Base16 # mconcat :: [Base16] -> Base16 #
Format Base16 Source # |
Methods encodeByteString :: ByteString -> Base16 Source # decodeFormat :: Base16 -> ByteString Source #
Encodable Base16 Source # |
Methods toByteString :: Base16 -> ByteString Source # fromByteString :: ByteString -> Maybe Base16 Source # unsafeFromByteString :: ByteString -> Base16 Source #

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.

Instances

Eq Base64 Source # |
Methods (==) :: Base64 -> Base64 -> Bool # (/=) :: Base64 -> Base64 -> Bool #
Show Base64 Source # |
Methods showsPrec :: Int -> Base64 -> ShowS # show :: Base64 -> String # showList :: [Base64] -> ShowS #
IsString Base64 Source # |
Methods fromString :: String -> Base64 #
Monoid Base64 Source # |
Methods mempty :: Base64 # mappend :: Base64 -> Base64 -> Base64 # mconcat :: [Base64] -> Base64 #
Format Base64 Source # |
Methods encodeByteString :: ByteString -> Base64 Source # decodeFormat :: Base64 -> ByteString Source #
Encodable Base64 Source # |
Methods toByteString :: Base64 -> ByteString Source # fromByteString :: ByteString -> Maybe Base64 Source # unsafeFromByteString :: ByteString -> Base64 Source #