From: W. Trevor King <wking@tremily.us>
Date: Fri, 20 Dec 2013 23:31:29 +0000 (-0800)
Subject: Describe packet stream ordering in PGPKey.__doc__
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=0d7501f68c23af2c637c748d4aacfdf547f7fdfd;p=gpg-migrate.git

Describe packet stream ordering in PGPKey.__doc__

Using quotes from RFC 4880, as noted in the docstring itself.
---

diff --git a/gpg-migrate.py b/gpg-migrate.py
index 30b80b4..9bc9ecc 100755
--- a/gpg-migrate.py
+++ b/gpg-migrate.py
@@ -656,6 +656,41 @@ def packets_from_bytes(data):
 
 
 class PGPKey (object):
+    """An OpenPGP key with public and private parts.
+
+    From RFC 4880 [1]:
+
+      OpenPGP users may transfer public keys.  The essential elements
+      of a transferable public key are as follows:
+
+      - One Public-Key packet
+      - Zero or more revocation signatures
+      - One or more User ID packets
+      - After each User ID packet, zero or more Signature packets
+        (certifications)
+      - Zero or more User Attribute packets
+      - After each User Attribute packet, zero or more Signature
+        packets (certifications)
+      - Zero or more Subkey packets
+      - After each Subkey packet, one Signature packet, plus
+        optionally a revocation
+
+    Secret keys have a similar packet stream [2]:
+
+      OpenPGP users may transfer secret keys.  The format of a
+      transferable secret key is the same as a transferable public key
+      except that secret-key and secret-subkey packets are used
+      instead of the public key and public-subkey packets.
+      Implementations SHOULD include self-signatures on any user IDs
+      and subkeys, as this allows for a complete public key to be
+      automatically extracted from the transferable secret key.
+      Implementations MAY choose to omit the self-signatures,
+      especially if a transferable public key accompanies the
+      transferable secret key.
+
+    [1]: http://tools.ietf.org/search/rfc4880#section-11.1
+    [2]: http://tools.ietf.org/search/rfc4880#section-11.2
+    """
     def __init__(self, fingerprint):
         self.fingerprint = fingerprint
         self.public_packets = None