From 80ed642f8502dc9f5091400a537a7efd25b0bc04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Ch=C3=A9ron?= Date: Tue, 22 Aug 2017 20:39:24 +0200 Subject: [PATCH 1/3] Add introduction to tutorial --- Crypto/Tutorial.hs | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/Crypto/Tutorial.hs b/Crypto/Tutorial.hs index 2e74fac..158fcc7 100644 --- a/Crypto/Tutorial.hs +++ b/Crypto/Tutorial.hs @@ -1,9 +1,31 @@ -- | Examples of how to use @cryptonite@. module Crypto.Tutorial - ( -- * Symmetric block ciphers + ( -- * API design + -- $api_design + + -- * Symmetric block ciphers -- $symmetric_block_ciphers ) where +-- $api_design +-- +-- APIs in cryptonite are often based on type classes from package +-- , notably +-- 'Data.ByteArray.ByteArrayAccess' and 'Data.ByteArray.ByteArray'. +-- Module "Data.ByteArray" provides many primitives that are useful to +-- work with cryptonite types. For example function 'Data.ByteArray.convert' +-- can transform one 'Data.ByteArray.ByteArrayAccess' concrete type like +-- 'Crypto.Hash.Digest' to a 'Data.ByteString.ByteString'. +-- +-- Algorithms and functions needing random bytes are based on type class +-- 'Crypto.Random.Types.MonadRandom'. Implementation 'IO' uses a system source +-- of entropy. It is also possible to use a 'Crypto.Random.Types.DRG' with +-- 'Crypto.Random.Types.MonadPseudoRandom' +-- +-- Error conditions are returned with data type 'Crypto.Error.CryptoFailable'. +-- Functions in module "Crypto.Error" can convert those values to runtime +-- exceptions, 'Maybe' or 'Either' values. + -- $symmetric_block_ciphers -- -- > {-# LANGUAGE OverloadedStrings #-} From 007f69c5572771693bc6cc313a5ee6c521e502e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Ch=C3=A9ron?= Date: Tue, 22 Aug 2017 20:39:27 +0200 Subject: [PATCH 2/3] Add Crypto.Hash examples to tutorial --- Crypto/Tutorial.hs | 61 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/Crypto/Tutorial.hs b/Crypto/Tutorial.hs index 158fcc7..bd1c9c5 100644 --- a/Crypto/Tutorial.hs +++ b/Crypto/Tutorial.hs @@ -3,6 +3,9 @@ module Crypto.Tutorial ( -- * API design -- $api_design + -- * Hash algorithms + -- $hash_algorithms + -- * Symmetric block ciphers -- $symmetric_block_ciphers ) where @@ -26,6 +29,64 @@ module Crypto.Tutorial -- Functions in module "Crypto.Error" can convert those values to runtime -- exceptions, 'Maybe' or 'Either' values. +-- $hash_algorithms +-- +-- Hashing a complete message: +-- +-- > import Crypto.Hash +-- > +-- > import Data.ByteString (ByteString) +-- > +-- > exampleHashWith :: ByteString -> IO () +-- > exampleHashWith msg = do +-- > putStrLn $ " sha1(" ++ show msg ++ ") = " ++ show (hashWith SHA1 msg) +-- > putStrLn $ "sha256(" ++ show msg ++ ") = " ++ show (hashWith SHA256 msg) +-- +-- Hashing incrementally, with intermediate context allocations: +-- +-- > {-# LANGUAGE OverloadedStrings #-} +-- > +-- > import Crypto.Hash +-- > +-- > import Data.ByteString (ByteString) +-- > +-- > exampleIncrWithAllocs :: IO () +-- > exampleIncrWithAllocs = do +-- > let ctx0 = hashInitWith SHA3_512 +-- > ctx1 = hashUpdate ctx0 ("The " :: ByteString) +-- > ctx2 = hashUpdate ctx1 ("quick " :: ByteString) +-- > ctx3 = hashUpdate ctx2 ("brown " :: ByteString) +-- > ctx4 = hashUpdate ctx3 ("fox " :: ByteString) +-- > ctx5 = hashUpdate ctx4 ("jumps " :: ByteString) +-- > ctx6 = hashUpdate ctx5 ("over " :: ByteString) +-- > ctx7 = hashUpdate ctx6 ("the " :: ByteString) +-- > ctx8 = hashUpdate ctx7 ("lazy " :: ByteString) +-- > ctx9 = hashUpdate ctx8 ("dog" :: ByteString) +-- > print (hashFinalize ctx9) +-- +-- Hashing incrementally, updating context in place: +-- +-- > {-# LANGUAGE OverloadedStrings #-} +-- > +-- > import Crypto.Hash.Algorithms +-- > import Crypto.Hash.IO +-- > +-- > import Data.ByteString (ByteString) +-- > +-- > exampleIncrInPlace :: IO () +-- > exampleIncrInPlace = do +-- > ctx <- hashMutableInitWith SHA3_512 +-- > hashMutableUpdate ctx ("The " :: ByteString) +-- > hashMutableUpdate ctx ("quick " :: ByteString) +-- > hashMutableUpdate ctx ("brown " :: ByteString) +-- > hashMutableUpdate ctx ("fox " :: ByteString) +-- > hashMutableUpdate ctx ("jumps " :: ByteString) +-- > hashMutableUpdate ctx ("over " :: ByteString) +-- > hashMutableUpdate ctx ("the " :: ByteString) +-- > hashMutableUpdate ctx ("lazy " :: ByteString) +-- > hashMutableUpdate ctx ("dog" :: ByteString) +-- > hashMutableFinalize ctx >>= print + -- $symmetric_block_ciphers -- -- > {-# LANGUAGE OverloadedStrings #-} From c6c715f465e345993fd456ce6e02f923a7530f0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Ch=C3=A9ron?= Date: Tue, 22 Aug 2017 20:39:29 +0200 Subject: [PATCH 3/3] Add note about Digest implementing ByteArrayAccess --- Crypto/Hash/Types.hs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Crypto/Hash/Types.hs b/Crypto/Hash/Types.hs index 9f088a5..ee594a1 100644 --- a/Crypto/Hash/Types.hs +++ b/Crypto/Hash/Types.hs @@ -62,6 +62,14 @@ newtype Context a = Context Bytes deriving (ByteArrayAccess,NFData) -- | Represent a digest for a given hash algorithm. +-- +-- This type is an instance of 'ByteArrayAccess' from package +-- . +-- Module "Data.ByteArray" provides many primitives to work with those values +-- including conversion to other types. +-- +-- Creating a digest from a bytearray is also possible with function +-- 'Crypto.Hash.digestFromByteString'. newtype Digest a = Digest (F.UArray Word8) deriving (Eq,Ord,ByteArrayAccess)