From 5a2809a0f8f85956ed2bea2d0567414529c13a43 Mon Sep 17 00:00:00 2001
From: kinoru <xkinoru@gmail.com>
Date: Thu, 3 Dec 2015 18:00:23 +0000
Subject: [PATCH] [ChaChaPoly1305] fix type error of example code
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The example code had a type mismatch.

    Couldn't match expected type ‘State’
                with actual type ‘CryptoFailable State’
    In the second argument of ‘appendAAD’, namely ‘st1’
    In the second argument of ‘($)’, namely ‘appendAAD hdr st1’

This is due to the following part:

    let st1 = ChaChaPoly1305.initialize key nonce
        st2 = ChaChaPoly1305.finalizeAAD $ ChaChaPoly1305.appendAAD hdr st1

`initialize` returns `CryptoFailable State`, not `State`.

This commit fixes the type mismatch, changes the return type of the
example function to `CryptoFailable ByteString`, and makes the code
to be immediately copy-and-paste-able.
---
 Crypto/Cipher/ChaChaPoly1305.hs | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/Crypto/Cipher/ChaChaPoly1305.hs b/Crypto/Cipher/ChaChaPoly1305.hs
index ed8b99e..ae0121f 100644
--- a/Crypto/Cipher/ChaChaPoly1305.hs
+++ b/Crypto/Cipher/ChaChaPoly1305.hs
@@ -5,7 +5,8 @@
 -- Stability   : stable
 -- Portability : good
 --
--- A simple AEAD scheme using ChaCha20 and Poly1305. See RFC7539.
+-- A simple AEAD scheme using ChaCha20 and Poly1305. See
+-- <https://tools.ietf.org/html/rfc7539 RFC 7539>.
 --
 -- The State is not modified in place, so each function changing the State,
 -- returns a new State.
@@ -15,12 +16,24 @@
 --
 -- Once 'finalizeAAD' has been called, no further 'appendAAD' call should be make.
 --
--- > encrypt nonce key hdr inp =
--- >    let st1        = ChaChaPoly1305.initialize key nonce
--- >        st2        = ChaChaPoly1305.finalizeAAD $ ChaChaPoly1305.appendAAD hdr st1
--- >        (out, st3) = ChaChaPoly1305.encrypt inp st2
--- >        auth       = ChaChaPoly1305.finalize st3
--- >     in out `B.append` Data.ByteArray.convert auth
+-- >import Data.ByteString.Char8 as B
+-- >import Data.ByteArray
+-- >import Crypto.Error
+-- >import Crypto.Cipher.ChaChaPoly1305 as C
+-- >
+-- >encrypt
+-- >    :: ByteString -- nonce (12 random bytes)
+-- >    -> ByteString -- symmetric key
+-- >    -> ByteString -- optional associated data (won't be encrypted)
+-- >    -> ByteString -- input plaintext to be encrypted
+-- >    -> CryptoFailable ByteString -- ciphertext with a 128-bit tag attached
+-- >encrypt nonce key header plaintext = do
+-- >    st1 <- C.nonce12 nonce >>= C.initialize key
+-- >    let
+-- >        st2 = C.finalizeAAD $ C.appendAAD header st1
+-- >        (out, st3) = C.encrypt plaintext st2
+-- >        auth = C.finalize st3
+-- >    return $ out `B.append` Data.ByteArray.convert auth
 --
 module Crypto.Cipher.ChaChaPoly1305
     ( State