From 55330cc47562d6b5010fcc4ec25175191788a9e4 Mon Sep 17 00:00:00 2001 From: Stephen Paul Weber Date: Sat, 29 Dec 2012 15:39:48 -0500 Subject: More documentation --- Data/OpenPGP.hs | 52 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 13 deletions(-) (limited to 'Data') diff --git a/Data/OpenPGP.hs b/Data/OpenPGP.hs index a3b7b62..4d049dd 100644 --- a/Data/OpenPGP.hs +++ b/Data/OpenPGP.hs @@ -175,6 +175,7 @@ data Packet = key_algorithm::KeyAlgorithm, encrypted_data::B.ByteString } | + -- ^ SignaturePacket { version::Word8, signature_type::Word8, @@ -186,6 +187,7 @@ data Packet = signature::[MPI], trailer::B.ByteString } | + -- ^ OnePassSignaturePacket { version::Word8, signature_type::Word8, @@ -194,6 +196,7 @@ data Packet = key_id::String, nested::Word8 } | + -- ^ PublicKeyPacket { version::Word8, timestamp::Word32, @@ -202,39 +205,45 @@ data Packet = is_subkey::Bool, v3_days_of_validity::Maybe Word16 } | + -- ^ (also subkey) SecretKeyPacket { version::Word8, timestamp::Word32, key_algorithm::KeyAlgorithm, key::[(Char,MPI)], - s2k_useage::Word8, -- determines if the Maybes are Just or Nothing + s2k_useage::Word8, -- ^ determines if the 'Maybe's are 'Just' or 'Nothing' symmetric_type::Maybe Word8, s2k_type::Maybe Word8, s2k_hash_algorithm::Maybe HashAlgorithm, s2k_salt::Maybe Word64, s2k_count::Maybe Word32, encrypted_data::B.ByteString, - private_hash::Maybe B.ByteString, -- the hash may be in the encrypted data + private_hash::Maybe B.ByteString, -- ^ the hash may be in the encrypted data is_subkey::Bool } | + -- ^ (also subkey) CompressedDataPacket { compression_algorithm::CompressionAlgorithm, message::Message } | - MarkerPacket | + -- ^ + MarkerPacket | -- ^ LiteralDataPacket { format::Char, filename::String, timestamp::Word32, content::B.ByteString } | - TrustPacket B.ByteString | - UserIDPacket String | + -- ^ + TrustPacket B.ByteString | -- ^ + UserIDPacket String | -- ^ EncryptedDataPacket { - version::Word8, -- 0 for old-skool no-MDC (tag 9) + version::Word8, encrypted_data::B.ByteString } | - ModificationDetectionCodePacket B.ByteString | + -- ^ + -- or when version is 0 + ModificationDetectionCodePacket B.ByteString | -- ^ UnsupportedPacket Word8 B.ByteString deriving (Show, Read, Eq) @@ -830,7 +839,7 @@ instance BINARY_CLASS RevocationCode where put = put . enum_to_word8 get = fmap enum_from_word8 get --- A message is encoded as a list that takes the entire file +-- | A message is encoded as a list that takes the entire file newtype Message = Message [Packet] deriving (Show, Read, Eq) instance BINARY_CLASS Message where put (Message xs) = mapM_ put xs @@ -846,6 +855,7 @@ signatures_and_data (Message lst) = isDta (LiteralDataPacket {}) = True isDta _ = False +-- | newtype MPI = MPI Integer deriving (Show, Read, Eq, Ord) instance BINARY_CLASS MPI where put (MPI i) @@ -879,15 +889,15 @@ listUntilEnd = do rest <- listUntilEnd return (next:rest) --- http://tools.ietf.org/html/rfc4880#section-5.2.3.1 +-- | data SignatureSubpacket = SignatureCreationTimePacket Word32 | - SignatureExpirationTimePacket Word32 | -- seconds after CreationTime + SignatureExpirationTimePacket Word32 | -- ^ seconds after CreationTime ExportableCertificationPacket Bool | TrustSignaturePacket {depth::Word8, trust::Word8} | RegularExpressionPacket String | RevocablePacket Bool | - KeyExpirationTimePacket Word32 | -- seconds after key CreationTime + KeyExpirationTimePacket Word32 | -- ^ seconds after key CreationTime PreferredSymmetricAlgorithmsPacket [SymmetricAlgorithm] | RevocationKeyPacket { sensitive::Bool, @@ -1160,7 +1170,12 @@ signature_issuer (SignaturePacket {hashed_subpackets = hashed, isIssuer _ = False signature_issuer _ = Nothing -find_key :: (Packet -> String) -> Message -> String -> Maybe Packet +-- | Find a key with the given Fingerprint/KeyID +find_key :: + (Packet -> String) -- ^ Extract Fingerprint/KeyID from packet + -> Message -- ^ List of packets (some of which are keys) + -> String -- ^ Fingerprint/KeyID to search for + -> Maybe Packet find_key fpr (Message (x@(PublicKeyPacket {}):xs)) keyid = find_key' fpr x xs keyid find_key fpr (Message (x@(SecretKeyPacket {}):xs)) keyid = @@ -1177,7 +1192,18 @@ find_key' fpr x xs keyid thisid = reverse $ take (length keyid) (reverse (fpr x)) -- | SignaturePacket smart constructor -signaturePacket :: Word8 -> Word8 -> KeyAlgorithm -> HashAlgorithm -> [SignatureSubpacket] -> [SignatureSubpacket] -> Word16 -> [MPI] -> Packet +-- +-- +signaturePacket :: + Word8 -- ^ Signature version (probably 4) + -> Word8 -- ^ Signature type + -> KeyAlgorithm + -> HashAlgorithm + -> [SignatureSubpacket] -- ^ Hashed subpackets (these get signed) + -> [SignatureSubpacket] -- ^ Unhashed subpackets (these do not get signed) + -> Word16 -- ^ Left 16 bits of the signed hash value + -> [MPI] -- ^ The raw MPIs of the signature + -> Packet signaturePacket version signature_type key_algorithm hash_algorithm hashed_subpackets unhashed_subpackets hash_head signature = let p = SignaturePacket { version = version, -- cgit v1.2.3