Raaz.Core.Encode

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

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.

Laws for encoding

Note that not all byte strings can be valid encodings and fromByteString might fail and return Nothing on certain inputs. However, we require the minimum guarantee that fromByteString for actual encodings of elements, i.e. we require the instances to satisfy the law.

fromByteString . toByteString = Just

TODO: Write test cases for encoding laws.

Minimal complete definition

Nothing

Methods

toByteString :: a -> ByteString

Convert stuff to bytestring

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

fromByteString :: ByteString -> Maybe a

Try parsing back a value. Returns nothing on failure.

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

unsafeFromByteString :: ByteString -> a

Unsafe version of fromByteString

Instances

Encodable Word8

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: Word8 -> ByteString

fromByteString :: ByteString -> Maybe Word8

unsafeFromByteString :: ByteString -> Word8

Encodable ()

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: () -> ByteString

fromByteString :: ByteString -> Maybe ()

unsafeFromByteString :: ByteString -> ()

Encodable ByteString

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: ByteString -> ByteString

fromByteString :: ByteString -> Maybe ByteString

unsafeFromByteString :: ByteString -> ByteString

Encodable Base64

Defined in Raaz.Core.Encode.Base64

Methods

toByteString :: Base64 -> ByteString

fromByteString :: ByteString -> Maybe Base64

unsafeFromByteString :: ByteString -> Base64

Encodable Base16

Defined in Raaz.Core.Encode.Base16

Methods

toByteString :: Base16 -> ByteString

fromByteString :: ByteString -> Maybe Base16

unsafeFromByteString :: ByteString -> Base16

Encodable WriteTo

Defined in Raaz.Core.Transfer.Unsafe

Methods

toByteString :: WriteTo -> ByteString

fromByteString :: ByteString -> Maybe WriteTo

unsafeFromByteString :: ByteString -> WriteTo

Encodable S

Defined in Raaz.Primitive.Poly1305.Internal

Methods

toByteString :: S -> ByteString

fromByteString :: ByteString -> Maybe S

unsafeFromByteString :: ByteString -> S

Encodable R

Defined in Raaz.Primitive.Poly1305.Internal

Methods

toByteString :: R -> ByteString

fromByteString :: ByteString -> Maybe R

unsafeFromByteString :: ByteString -> R

Encodable Poly1305

Defined in Raaz.Primitive.Poly1305.Internal

Methods

toByteString :: Poly1305 -> ByteString

fromByteString :: ByteString -> Maybe Poly1305

unsafeFromByteString :: ByteString -> Poly1305

Encodable a => Encodable (BYTES a)

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: BYTES a -> ByteString

fromByteString :: ByteString -> Maybe (BYTES a)

unsafeFromByteString :: ByteString -> BYTES a

Encodable (BE Word32)

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: BE Word32 -> ByteString

fromByteString :: ByteString -> Maybe (BE Word32)

unsafeFromByteString :: ByteString -> BE Word32

Encodable (BE Word64)

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: BE Word64 -> ByteString

fromByteString :: ByteString -> Maybe (BE Word64)

unsafeFromByteString :: ByteString -> BE Word64

Encodable (LE Word32)

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: LE Word32 -> ByteString

fromByteString :: ByteString -> Maybe (LE Word32)

unsafeFromByteString :: ByteString -> LE Word32

Encodable (LE Word64)

Defined in Raaz.Core.Encode.Internal

Methods

toByteString :: LE Word64 -> ByteString

fromByteString :: ByteString -> Maybe (LE Word64)

unsafeFromByteString :: ByteString -> LE Word64

Encodable (Nounce XChaCha20)

Defined in Raaz.Primitive.ChaCha20.Internal

Methods

toByteString :: Nounce XChaCha20 -> ByteString

fromByteString :: ByteString -> Maybe (Nounce XChaCha20)

unsafeFromByteString :: ByteString -> Nounce XChaCha20

Encodable (Nounce ChaCha20)

Defined in Raaz.Primitive.ChaCha20.Internal

Methods

toByteString :: Nounce ChaCha20 -> ByteString

fromByteString :: ByteString -> Maybe (Nounce ChaCha20)

unsafeFromByteString :: ByteString -> Nounce ChaCha20

Encodable (Key XChaCha20)

Defined in Raaz.Primitive.ChaCha20.Internal

Methods

toByteString :: Key XChaCha20 -> ByteString

fromByteString :: ByteString -> Maybe (Key XChaCha20)

unsafeFromByteString :: ByteString -> Key XChaCha20

Encodable (Key ChaCha20)

Defined in Raaz.Primitive.ChaCha20.Internal

Methods

toByteString :: Key ChaCha20 -> ByteString

fromByteString :: ByteString -> Maybe (Key ChaCha20)

unsafeFromByteString :: ByteString -> Key ChaCha20

Encodable (Key (Keyed prim))

Defined in Raaz.Primitive.Keyed.Internal

Methods

toByteString :: Key (Keyed prim) -> ByteString

fromByteString :: ByteString -> Maybe (Key (Keyed prim))

unsafeFromByteString :: ByteString -> Key (Keyed prim)

Encodable prim => Encodable (Keyed prim)

Defined in Raaz.Primitive.Keyed.Internal

Methods

toByteString :: Keyed prim -> ByteString

fromByteString :: ByteString -> Maybe (Keyed prim)

unsafeFromByteString :: ByteString -> Keyed prim

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

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

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

decodeFormat :: fmt -> ByteString

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).

Defined in Raaz.Core.Encode.Internal

Methods

encodeByteString :: ByteString -> ByteString

decodeFormat :: ByteString -> ByteString

Format Base64

Defined in Raaz.Core.Encode.Base64

Methods

encodeByteString :: ByteString -> Base64

decodeFormat :: Base64 -> ByteString

Format Base16

Defined in Raaz.Core.Encode.Base16

Methods

encodeByteString :: ByteString -> Base16

decodeFormat :: Base16 -> ByteString

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

Encode in a given format.

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

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

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

Translate from one format to another.

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

The unsafe version of decode.

The base 16 encoding format

data Base16

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

Eq Base16

Defined in Raaz.Core.Encode.Base16

Methods

(==) :: Base16 -> Base16 -> Bool

(/=) :: Base16 -> Base16 -> Bool

Show Base16

Defined in Raaz.Core.Encode.Base16

Methods

showsPrec :: Int -> Base16 -> ShowS

show :: Base16 -> String

showList :: [Base16] -> ShowS

IsString Base16

Ignores spaces and : (colon).

Defined in Raaz.Core.Encode.Base16

Methods

fromString :: String -> Base16

Semigroup Base16

Defined in Raaz.Core.Encode.Base16

Methods

(<>) :: Base16 -> Base16 -> Base16

sconcat :: NonEmpty Base16 -> Base16

stimes :: Integral b => b -> Base16 -> Base16

Monoid Base16

Defined in Raaz.Core.Encode.Base16

Methods

mempty :: Base16

mappend :: Base16 -> Base16 -> Base16

mconcat :: [Base16] -> Base16

Format Base16

Defined in Raaz.Core.Encode.Base16

Methods

encodeByteString :: ByteString -> Base16

decodeFormat :: Base16 -> ByteString

Encodable Base16

Defined in Raaz.Core.Encode.Base16

Methods

toByteString :: Base16 -> ByteString

fromByteString :: ByteString -> Maybe Base16

unsafeFromByteString :: ByteString -> Base16

fromBase16 :: Encodable a => String -> a

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

Base16 variant of show.

Other binary formats.

data Base64

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

Instances

Eq Base64

Defined in Raaz.Core.Encode.Base64

Methods

(==) :: Base64 -> Base64 -> Bool

(/=) :: Base64 -> Base64 -> Bool

Show Base64

Defined in Raaz.Core.Encode.Base64

Methods

showsPrec :: Int -> Base64 -> ShowS

show :: Base64 -> String

showList :: [Base64] -> ShowS

IsString Base64

Ignores spaces and newlines.

Defined in Raaz.Core.Encode.Base64

Methods

fromString :: String -> Base64

Semigroup Base64

Defined in Raaz.Core.Encode.Base64

Methods

(<>) :: Base64 -> Base64 -> Base64

sconcat :: NonEmpty Base64 -> Base64

stimes :: Integral b => b -> Base64 -> Base64

Monoid Base64

Defined in Raaz.Core.Encode.Base64

Methods

mempty :: Base64

mappend :: Base64 -> Base64 -> Base64

mconcat :: [Base64] -> Base64

Format Base64

Defined in Raaz.Core.Encode.Base64

Methods

encodeByteString :: ByteString -> Base64

decodeFormat :: Base64 -> ByteString

Encodable Base64

Defined in Raaz.Core.Encode.Base64

Methods

toByteString :: Base64 -> ByteString

fromByteString :: ByteString -> Maybe Base64

unsafeFromByteString :: ByteString -> Base64