Consolidate key interface password handling and general overhaul

README.rst

@@ -83,9 +83,9 @@ text without prepended symbols is the output of a command.
 
     # If the key length is unspecified, it defaults to 3072 bits. A length of
     # less than 2048 bits raises an exception. A password may be supplied as an
-    # argument, otherwise a user prompt is presented.  If the password is an
-    # empty string, the private key is saved unencrypted.
-    >>> generate_and_write_rsa_keypair("rsa_key2")
+    # argument like above, or on the prompt. If no password is passed or
+    # entered the private key is saved unencrypted.
+    >>> generate_and_write_rsa_keypair("rsa_key2", prompt=True)
     Enter a password for the RSA key:
     Confirm:
 
@@ -134,18 +134,18 @@ Create and Import Ed25519 Keys
 
     # Continuing from the previous section . . .
 
-    # Generate and write an Ed25519 key pair.  The private key is saved
-    # encrypted.  A 'password' argument may be supplied, otherwise a prompt is
-    # presented.
-    >>> generate_and_write_ed25519_keypair('ed25519_key')
+    # Generate and write an Ed25519 key pair.  A password may be supplied as an
+    # argument, or on the prompt. If no password is passed or entered the
+    # private key is saved unencrypted.
+    >>> generate_and_write_ed25519_keypair('ed25519_key', prompt=True)
     Enter a password for the Ed25519 key:
     Confirm:
 
     # Import the Ed25519 public key just created . . .
     >>> public_ed25519_key = import_ed25519_publickey_from_file('ed25519_key.pub')
 
     # and its corresponding private key.
-    >>> private_ed25519_key = import_ed25519_privatekey_from_file('ed25519_key')
+    >>> private_ed25519_key = import_ed25519_privatekey_from_file('ed25519_key', prompt=True)
     Enter a password for the encrypted Ed25519 key:
 
 
@@ -156,12 +156,12 @@ Create and Import ECDSA Keys
 
     # continuing from the previous sections . . .
 
-    >>> generate_and_write_ecdsa_keypair('ecdsa_key')
+    >>> generate_and_write_ecdsa_keypair('ecdsa_key', prompt=True)
     Enter a password for the ECDSA key:
     Confirm:
 
     >>> public_ecdsa_key = import_ecdsa_publickey_from_file('ecdsa_key.pub')
-    >>> private_ecdsa_key = import_ecdsa_privatekey_from_file('ecdsa_key')
+    >>> private_ecdsa_key = import_ecdsa_privatekey_from_file('ecdsa_key', prompt=True)
     Enter a password for the encrypted ECDSA key:
 
 

securesystemslib/gpg/functions.py

@@ -232,43 +232,24 @@ def verify_signature(signature_object, pubkey_info, content):
 
 
 def export_pubkey(keyid, homedir=None):
-  """
-  <Purpose>
-    Calls gpg command line utility to export the gpg public key bundle
-    identified by the passed keyid from the gpg keyring at the passed homedir
-    in a securesystemslib-style format.
-
-    NOTE: The identified key is exported including the corresponding master
-    key and all subkeys.
-
-    The executed base export command is defined in
-    securesystemslib.gpg.constants.GPG_EXPORT_PUBKEY_COMMAND.
-
-  <Arguments>
-    keyid:
-            The GPG keyid in format: securesystemslib.formats.KEYID_SCHEMA
-
-    homedir: (optional)
-            Path to the gpg keyring. If not passed the default keyring is used.
-
-  <Exceptions>
-    ValueError:
-            if the keyid does not match the required format.
-
-    securesystemslib.exceptions.UnsupportedLibraryError:
-            If the gpg command is not available, or
-            the cryptography library is not installed.
+  """Exports a public key from a GnuPG keyring.
 
-    securesystemslib.gpg.execeptions.KeyNotFoundError:
-            if no key or subkey was found for that keyid.
+  Arguments:
+    keyid: An OpenPGP keyid in KEYID_SCHEMA format.
+    homedir (optional): A path to the GnuPG home directory. If not set the
+        default GnuPG home directory is used.
 
+  Raises:
+    ValueError: Keyid is not a string.
+    UnsupportedLibraryError: The gpg command or pyca/cryptography are not
+        available.
+    KeyNotFoundError: No key or subkey was found for that keyid.
 
-  <Side Effects>
-    None.
+  Side Effects:
+    Calls system gpg command in a subprocess.
 
-  <Returns>
-    The exported public key object in the format:
-    securesystemslib.formats.GPG_PUBKEY_SCHEMA.
+  Returns:
+    An OpenPGP public key object in GPG_PUBKEY_SCHEMA format.
 
   """
   if not HAVE_GPG: # pragma: no cover
@@ -302,7 +283,7 @@ def export_pubkey(keyid, homedir=None):
 
 
 def export_pubkeys(keyids, homedir=None):
-  """Export multiple public keys from a GnuPG keyring.
+  """Exports multiple public keys from a GnuPG keyring.
 
   Arguments:
     keyids: A list of OpenPGP keyids in KEYID_SCHEMA format.
@@ -311,11 +292,18 @@ def export_pubkeys(keyids, homedir=None):
 
   Raises:
     TypeError: Keyids is not iterable.
-    See 'export_pubkey' for other exceptions.
+    ValueError: A Keyid is not a string.
+    UnsupportedLibraryError: The gpg command or pyca/cryptography are not
+        available.
+    KeyNotFoundError: No key or subkey was found for that keyid.
+
+  Side Effects:
+    Calls system gpg command in a subprocess.
 
   Returns:
-    A dict with the OpenPGP keyids passed as the keyids argument for dict keys
-    and keys in GPG_PUBKEY_SCHEMA format for values.
+    A dict of OpenPGP public key objects in GPG_PUBKEY_SCHEMA format as values,
+    and their keyids as dict keys.
+
 
   """
   public_key_dict = {}