raaz-0.2.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.

Description

Encoding and decoding values to formats.

Synopsis

- class Encodable a where
  - toByteString :: a -> ByteString
  - fromByteString :: ByteString -> Maybe a
  - unsafeFromByteString :: ByteString -> a
- class (IsString fmt, Show fmt, Encodable fmt) => Format fmt where
  - encodeByteString :: ByteString -> fmt
  - decodeFormat :: fmt -> ByteString
- 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`:
  The class of all types that are encoding formats to binary data. They are all instances of `Show` and `IsString` for ease of printing and inclusion in source code.
`Encodable`:
  The class of all types that can be encoded into binary.

The combinators `encode` and `decode` allows encoding any instance of `Encodable` to any of the instances of `Format`.

## Sample code that makes use of Base16 encoding.

    theAnswer :: LE Word64
    theAnswer = 42

    main = do putStr "The answer to life, universe and everything is:"
              print answserInBase16
       where answerInBase16 :: Base16
             answerInBase16 = encode theAnswer

    checkAnswer :: Base16 -> Bool
    checkAnswer = maybe False (==theAnswer) . decode

    checkAnswerBS :: ByteString -> Bool
    checkAnswerBS = checkAnswer . fromString

In the above example, ``LE` Word64`, which captures 64-bit unsigned integers is an instance of Encode (but not Word64). The encode combinator then converts in into the type Base16 that is an instance of `Format`. The print then uses the `Show` instance of Base16 to print it as a sequence of hexadecimal characters. Similarly the decode combinator in `checkAnswer` decodes a base16 before comparing with the answer.

## Liberal `IsString` instances

Certain ascii printable formats like Base16 and Base64 have a more liberal `IsString` instance: they typically allow the use of spaces and newline in the input to the `fromString` function . This allows a more readable representation of these types when using the `OverloadedStrings` extension. See the documentation of the corresponding instance declarations to see what characters are ignored. However, all `Show` instance of formats are strict in the sense that they do not produce any such extraneous characters.

class Encodable a where Source #

The type class `Encodable` captures all the types that can be encoded into a stream of bytes. For a user defined type say `Foo`, defining an instance `Encodable` is all that is required to make use of `encode` and `decode` for any of the supported encoding 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.

    newtype Foo = Foo (LE Word64) deriving (Storable, EndianStore)

    instance EndianStore Foo where
      ...

    instance Encodable Foo

In particular, all the endian encoded versions of Haskell's word, i.e types like ``LE` Word32`, ``LE` Word64` etc, are instances of `Encodable`. Note that the corresponding plain type is not an instance of `Encodable` because encoding of say `Word32` without specifying whether the endianness is meaningless.

Minimal complete definition

Nothing

Methods

toByteString :: a -> ByteString Source #

Convert stuff to bytestring

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

fromByteString :: ByteString -> Maybe a Source #

Try parsing back a value. Returns nothing on failure.

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

unsafeFromByteString :: ByteString -> a Source #

Unsafe version of `fromByteString`

#### Instances

Instances details

Encodable Word8 Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: Word8 -> ByteString Source # fromByteString :: ByteString -> Maybe Word8 Source # unsafeFromByteString :: ByteString -> Word8 Source #
Encodable ByteString Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: ByteString -> ByteString Source # fromByteString :: ByteString -> Maybe ByteString Source # unsafeFromByteString :: ByteString -> ByteString Source #
Encodable Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods toByteString :: Base64 -> ByteString Source # fromByteString :: ByteString -> Maybe Base64 Source # unsafeFromByteString :: ByteString -> Base64 Source #
Encodable Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 Methods toByteString :: Base16 -> ByteString Source # fromByteString :: ByteString -> Maybe Base16 Source # unsafeFromByteString :: ByteString -> Base16 Source #
Encodable KEY Source # |
Instance details Defined in Raaz.Cipher.ChaCha20.Internal Methods toByteString :: KEY -> ByteString Source # fromByteString :: ByteString -> Maybe KEY Source # unsafeFromByteString :: ByteString -> KEY Source #
Encodable IV Source # |
Instance details Defined in Raaz.Cipher.ChaCha20.Internal Methods toByteString :: IV -> ByteString Source # fromByteString :: ByteString -> Maybe IV Source # unsafeFromByteString :: ByteString -> IV Source #
Encodable BLAKE2s Source # |
Instance details Defined in Raaz.Hash.Blake2.Internal Methods toByteString :: BLAKE2s -> ByteString Source # fromByteString :: ByteString -> Maybe BLAKE2s Source # unsafeFromByteString :: ByteString -> BLAKE2s Source #
Encodable BLAKE2b Source # |
Instance details Defined in Raaz.Hash.Blake2.Internal Methods toByteString :: BLAKE2b -> ByteString Source # fromByteString :: ByteString -> Maybe BLAKE2b Source # unsafeFromByteString :: ByteString -> BLAKE2b Source #
Encodable SHA1 Source # |
Instance details Defined in Raaz.Hash.Sha1.Internal Methods toByteString :: SHA1 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA1 Source # unsafeFromByteString :: ByteString -> SHA1 Source #
Encodable SHA224 Source # |
Instance details Defined in Raaz.Hash.Sha224.Internal Methods toByteString :: SHA224 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA224 Source # unsafeFromByteString :: ByteString -> SHA224 Source #
Encodable SHA256 Source # |
Instance details Defined in Raaz.Hash.Sha256.Internal Methods toByteString :: SHA256 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA256 Source # unsafeFromByteString :: ByteString -> SHA256 Source #
Encodable SHA384 Source # |
Instance details Defined in Raaz.Hash.Sha384.Internal Methods toByteString :: SHA384 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA384 Source # unsafeFromByteString :: ByteString -> SHA384 Source #
Encodable SHA512 Source # |
Instance details Defined in Raaz.Hash.Sha512.Internal Methods toByteString :: SHA512 -> ByteString Source # fromByteString :: ByteString -> Maybe SHA512 Source # unsafeFromByteString :: ByteString -> SHA512 Source #
Encodable IV Source # |
Instance details Defined in Raaz.Cipher.AES.Internal Methods toByteString :: IV -> ByteString Source # fromByteString :: ByteString -> Maybe IV Source # unsafeFromByteString :: ByteString -> IV Source #
Encodable KEY256 Source # |
Instance details Defined in Raaz.Cipher.AES.Internal Methods toByteString :: KEY256 -> ByteString Source # fromByteString :: ByteString -> Maybe KEY256 Source # unsafeFromByteString :: ByteString -> KEY256 Source #
Encodable KEY192 Source # |
Instance details Defined in Raaz.Cipher.AES.Internal Methods toByteString :: KEY192 -> ByteString Source # fromByteString :: ByteString -> Maybe KEY192 Source # unsafeFromByteString :: ByteString -> KEY192 Source #
Encodable KEY128 Source # |
Instance details Defined in Raaz.Cipher.AES.Internal Methods toByteString :: KEY128 -> ByteString Source # fromByteString :: ByteString -> Maybe KEY128 Source # unsafeFromByteString :: ByteString -> KEY128 Source #
Encodable a => Encodable (BITS a) Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: BITS a -> ByteString Source # fromByteString :: ByteString -> Maybe (BITS a) Source # unsafeFromByteString :: ByteString -> BITS a Source #
Encodable a => Encodable (BYTES a) Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: BYTES a -> ByteString Source # fromByteString :: ByteString -> Maybe (BYTES a) Source # unsafeFromByteString :: ByteString -> BYTES a Source #
Encodable (BE Word32) Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: BE Word32 -> ByteString Source # fromByteString :: ByteString -> Maybe (BE Word32) Source # unsafeFromByteString :: ByteString -> BE Word32 Source #
Encodable (BE Word64) Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: BE Word64 -> ByteString Source # fromByteString :: ByteString -> Maybe (BE Word64) Source # unsafeFromByteString :: ByteString -> BE Word64 Source #
Encodable (LE Word32) Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: LE Word32 -> ByteString Source # fromByteString :: ByteString -> Maybe (LE Word32) Source # unsafeFromByteString :: ByteString -> LE Word32 Source #
Encodable (LE Word64) Source # |
Instance details Defined in Raaz.Core.Encode.Internal Methods toByteString :: LE Word64 -> ByteString Source # fromByteString :: ByteString -> Maybe (LE Word64) Source # unsafeFromByteString :: ByteString -> LE Word64 Source #
Encodable (WriteM IO) Source # |
Instance details Defined in Raaz.Core.Transfer Methods toByteString :: WriteM IO -> ByteString Source # fromByteString :: ByteString -> Maybe (WriteM IO) Source # unsafeFromByteString :: ByteString -> WriteM IO Source #
Encodable h => Encodable (HMAC h) Source # |
Instance details Defined in Raaz.Hash.Internal.HMAC 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.

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

Instances details

Format ByteString Source # | Bytestring itself is an encoding format (namely binary format).
Instance details Defined in Raaz.Core.Encode.Internal Methods encodeByteString :: ByteString -> ByteString Source # decodeFormat :: ByteString -> ByteString Source #
Format Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods encodeByteString :: ByteString -> Base64 Source # decodeFormat :: Base64 -> ByteString Source #
Format Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 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.

#### Instances

Instances details

Eq Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 Methods (==) :: Base16 -> Base16 -> Bool Source # (/=) :: Base16 -> Base16 -> Bool Source #
Show Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 Methods showsPrec :: Int -> Base16 -> ShowS Source # show :: Base16 -> String Source # showList :: [Base16] -> ShowS Source #
IsString Base16 Source # | Ignores spaces and `:` (colon).
Instance details Defined in Raaz.Core.Encode.Base16 Methods fromString :: String -> Base16 Source #
Semigroup Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 Methods (<>) :: Base16 -> Base16 -> Base16 Source # sconcat :: NonEmpty Base16 -> Base16 Source # stimes :: Integral b => b -> Base16 -> Base16 Source #
Monoid Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 Methods mempty :: Base16 Source # mappend :: Base16 -> Base16 -> Base16 Source # mconcat :: [Base16] -> Base16 Source #
Format Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 Methods encodeByteString :: ByteString -> Base16 Source # decodeFormat :: Base16 -> ByteString Source #
Encodable Base16 Source # |
Instance details Defined in Raaz.Core.Encode.Base16 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.

#### Instances

Instances details

Eq Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods (==) :: Base64 -> Base64 -> Bool Source # (/=) :: Base64 -> Base64 -> Bool Source #
Show Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods showsPrec :: Int -> Base64 -> ShowS Source # show :: Base64 -> String Source # showList :: [Base64] -> ShowS Source #
IsString Base64 Source # | Ignores spaces and newlines.
Instance details Defined in Raaz.Core.Encode.Base64 Methods fromString :: String -> Base64 Source #
Semigroup Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods (<>) :: Base64 -> Base64 -> Base64 Source # sconcat :: NonEmpty Base64 -> Base64 Source # stimes :: Integral b => b -> Base64 -> Base64 Source #
Monoid Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods mempty :: Base64 Source # mappend :: Base64 -> Base64 -> Base64 Source # mconcat :: [Base64] -> Base64 Source #
Format Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods encodeByteString :: ByteString -> Base64 Source # decodeFormat :: Base64 -> ByteString Source #
Encodable Base64 Source # |
Instance details Defined in Raaz.Core.Encode.Base64 Methods toByteString :: Base64 -> ByteString Source # fromByteString :: ByteString -> Maybe Base64 Source # unsafeFromByteString :: ByteString -> Base64 Source #