From 1f8f4b5405430fec064e1c30f7c374a73523267f Mon Sep 17 00:00:00 2001
From: Stephen Paul Weber <singpolyma@singpolyma.net>
Date: Mon, 8 Aug 2011 23:31:14 -0500
Subject: haddock

---
 Data/OpenPGP.hs        |  9 ++++++++-
 Data/OpenPGP/Crypto.hs | 19 +++++++++++++++----
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/Data/OpenPGP.hs b/Data/OpenPGP.hs
index c285127..0ce9991 100644
--- a/Data/OpenPGP.hs
+++ b/Data/OpenPGP.hs
@@ -1,3 +1,8 @@
+-- | Main implementation of the OpenPGP message format <http://tools.ietf.org/html/rfc4880>
+--
+-- The recommended way to import this module is:
+--
+-- > import qualified Data.OpenPGP as OpenPGP
 module Data.OpenPGP (Message(..), Packet(..), SignatureSubpacket(..), HashAlgorithm(..), KeyAlgorithm(..), CompressionAlgorithm(..), MPI(..), fingerprint_material, signatures_and_data, signature_issuer) where
 
 import Control.Monad
@@ -384,7 +389,7 @@ parse_packet 13 =
 -- Fail nicely for unimplemented packets
 parse_packet x = fail $ "Unimplemented OpenPGP packet tag " ++ (show x) ++ "."
 
--- Helper method for fingerprints and such
+-- | Helper method for fingerprints and such
 fingerprint_material :: Packet -> [LZ.ByteString]
 fingerprint_material (PublicKeyPacket {version = 4,
                       timestamp = timestamp,
@@ -482,6 +487,7 @@ instance Binary Message where
 			(Message tail) <- get :: Get Message
 			return (Message (next_packet:tail))
 
+-- | Extract all signature and data packets from a 'Message'
 signatures_and_data :: Message -> ([Packet], [Packet])
 signatures_and_data (Message ((CompressedDataPacket {message = m}):_)) =
 	signatures_and_data m
@@ -535,6 +541,7 @@ instance Binary SignatureSubpacket where
 		packet <- getLazyByteString len
 		return $ runGet (parse_signature_subpacket tag) packet
 
+-- | Find the keyid that issued a SignaturePacket
 signature_issuer :: Packet -> Maybe String
 signature_issuer (SignaturePacket {hashed_subpackets = hashed,
                                    unhashed_subpackets = unhashed}) =
diff --git a/Data/OpenPGP/Crypto.hs b/Data/OpenPGP/Crypto.hs
index e2151fc..fee1d55 100644
--- a/Data/OpenPGP/Crypto.hs
+++ b/Data/OpenPGP/Crypto.hs
@@ -1,3 +1,9 @@
+-- | This is a wrapper around <http://hackage.haskell.org/package/Crypto>
+-- that currently does fingerprint generation and signature verification.
+--
+-- The recommended way to import this module is:
+--
+-- > import qualified Data.OpenPGP.Crypto as OpenPGP
 module Data.OpenPGP.Crypto (verify, fingerprint) where
 
 import Data.Word
@@ -15,7 +21,8 @@ import qualified Data.Digest.SHA512 as SHA512
 import qualified Data.OpenPGP as OpenPGP
 import qualified Data.BaseConvert as BaseConvert
 
--- http://tools.ietf.org/html/rfc4880#section-12.2
+-- | Generate a key fingerprint from a PublicKeyPacket or SecretKeyPacket
+-- <http://tools.ietf.org/html/rfc4880#section-12.2>
 fingerprint :: OpenPGP.Packet -> String
 fingerprint p | OpenPGP.version p == 4 =
 	BaseConvert.toString 16 $ SHA1.toInteger $ SHA1.hash $
@@ -66,8 +73,12 @@ emsa_pkcs1_v1_5_encode m emLen algo =
 	[0, 1] ++ replicate (emLen - length t - 3) 0xff ++ [0] ++ t
 	where t = emsa_pkcs1_v1_5_hash_padding algo ++ hash algo m
 
-verify :: OpenPGP.Message -> OpenPGP.Message -> Int -> Bool
-verify keys packet sigidx =
+-- | Verify a message signature.  Only supports RSA keys for now.
+verify :: OpenPGP.Message    -- ^ Keys that may have made the signature
+          -> OpenPGP.Message -- ^ Message containing data and signature packet
+          -> Int             -- ^ Index of signature to verify (0th, 1st, etc)
+          -> Bool
+verify keys message sigidx =
 	encoded == RSA.encrypt (n, e) raw_sig
 	where
 	raw_sig = LZ.unpack $ LZ.drop 2 $ encode (OpenPGP.signature sig)
@@ -79,4 +90,4 @@ verify keys packet sigidx =
 	Just issuer = OpenPGP.signature_issuer sig
 	sig = sigs !! sigidx
 	(sigs, (OpenPGP.LiteralDataPacket {OpenPGP.content = dta}):_) =
-		OpenPGP.signatures_and_data packet
+		OpenPGP.signatures_and_data message
-- 
cgit v1.2.3