M2Crypto.RSA: Add PEP-484 type hints in comments.

1 files changed, 51 insertions, 70 deletions

diff --git a/M2Crypto/RSA.py b/M2Crypto/RSA.py
index a18c420..383b835 100644
--- a/M2Crypto/RSA.py
+++ b/M2Crypto/RSA.py
@@ -7,6 +7,8 @@ Copyright (c) 1999-2004 Ng Pheng Siong. All rights reserved."""
 import sys
 
 from M2Crypto import BIO, m2, util
+if util.py27plus:
+    from typing import Any, AnyStr, Callable, Dict, List, IO, Optional, Tuple  # noqa
 
 
 class RSAError(Exception):
@@ -28,18 +30,25 @@ class RSA:
     m2_rsa_free = m2.rsa_free
 
     def __init__(self, rsa, _pyfree=0):
+        # type: (bytes, int) -> None
+        """
+        @param rsa: binary representation of OpenSSL RSA type
+        """
         assert m2.rsa_type_check(rsa), "'rsa' type error"
         self.rsa = rsa
         self._pyfree = _pyfree
 
     def __del__(self):
+        # type: () -> None
         if getattr(self, '_pyfree', 0):
             self.m2_rsa_free(self.rsa)
 
     def __len__(self):
+        # type: () -> int
         return m2.rsa_size(self.rsa) << 3
 
     def __getattr__(self, name):
+        # type: (str) -> bytes
         if name == 'e':
             return m2.rsa_get_e(self.rsa)
         elif name == 'n':
@@ -48,39 +57,40 @@ class RSA:
             raise AttributeError
 
     def pub(self):
+        # type: () -> Tuple[bytes, bytes]
         assert self.check_key(), 'key is not initialised'
         return m2.rsa_get_e(self.rsa), m2.rsa_get_n(self.rsa)
 
     def public_encrypt(self, data, padding):
+        # type: (bytes, int) -> bytes
         assert self.check_key(), 'key is not initialised'
         return m2.rsa_public_encrypt(self.rsa, data, padding)
 
     def public_decrypt(self, data, padding):
+        # type: (bytes, int) -> bytes
         assert self.check_key(), 'key is not initialised'
         return m2.rsa_public_decrypt(self.rsa, data, padding)
 
     def private_encrypt(self, data, padding):
+        # type: (bytes, int) -> bytes
         assert self.check_key(), 'key is not initialised'
         return m2.rsa_private_encrypt(self.rsa, data, padding)
 
     def private_decrypt(self, data, padding):
+        # type: (bytes, int) -> bytes
         assert self.check_key(), 'key is not initialised'
         return m2.rsa_private_decrypt(self.rsa, data, padding)
 
     def save_key_bio(self, bio, cipher='aes_128_cbc',
                      callback=util.passphrase_callback):
+        # type: (BIO.BIO, Optional[str], Callable) -> int
         """
         Save the key pair to an M2Crypto.BIO.BIO object in PEM format.
 
-        @type bio: M2Crypto.BIO.BIO
         @param bio: M2Crypto.BIO.BIO object to save key to.
-
-        @type cipher: string
         @param cipher: Symmetric cipher to protect the key. The default
         cipher is 'aes_128_cbc'. If cipher is None, then the key is saved
         in the clear.
-
-        @type callback: Python callable
         @param callback: A Python callable object that is invoked
         to acquire a passphrase with which to protect the key.
         The default is util.passphrase_callback.
@@ -97,18 +107,16 @@ class RSA:
 
     def save_key(self, file, cipher='aes_128_cbc',
                  callback=util.passphrase_callback):
+        # type: (AnyStr, Optional[str], Callable) -> int
         """
         Save the key pair to a file in PEM format.
 
-        @type file: string
         @param file: Name of file to save key to.
 
-        @type cipher: string
         @param cipher: Symmetric cipher to protect the key. The default
         cipher is 'aes_128_cbc'. If cipher is None, then the key is saved
         in the clear.
 
-        @type callback: Python callable
         @param callback: A Python callable object that is invoked
         to acquire a passphrase with which to protect the key.
         The default is util.passphrase_callback.
@@ -119,6 +127,7 @@ class RSA:
     save_pem = save_key
 
     def as_pem(self, cipher='aes_128_cbc', callback=util.passphrase_callback):
+        # type: (Optional[str], Callable) -> bytes
         """
         Returns the key(pair) as a string in PEM format.
         """
@@ -127,57 +136,60 @@ class RSA:
         return bio.read()
 
     def save_key_der_bio(self, bio):
+        # type: (BIO.BIO) -> int
         """
         Save the key pair to an M2Crypto.BIO.BIO object in DER format.
 
-        @type bio: M2Crypto.BIO.BIO
         @param bio: M2Crypto.BIO.BIO object to save key to.
         """
         return m2.rsa_write_key_der(self.rsa, bio._ptr())
 
     def save_key_der(self, file):
+        # type: (AnyStr) -> int
         """
         Save the key pair to a file in DER format.
 
-        @type file: str
         @param file: Filename to save key to
         """
         bio = BIO.openfile(file, 'wb')
         return self.save_key_der_bio(bio)
 
     def save_pub_key_bio(self, bio):
+        # type: (BIO.BIO) -> int
         """
         Save the public key to an M2Crypto.BIO.BIO object in PEM format.
 
-        @type bio: M2Crypto.BIO.BIO
         @param bio: M2Crypto.BIO.BIO object to save key to.
         """
         return m2.rsa_write_pub_key(self.rsa, bio._ptr())
 
     def save_pub_key(self, file):
+        # type: (AnyStr) -> int
         """
         Save the public key to a file in PEM format.
 
-        @type file: string
         @param file: Name of file to save key to.
         """
         bio = BIO.openfile(file, 'wb')
         return m2.rsa_write_pub_key(self.rsa, bio._ptr())
 
     def check_key(self):
+        # type: () -> int
+        """
+        @return: returns 1 if rsa is a valid RSA key, and 0 otherwise.
+                 -1 is returned if an error occurs while checking the key.
+                 If the key is invalid or an error occurred, the reason
+                 code can be obtained using ERR_get_error(3).
+        """
         return m2.rsa_check_key(self.rsa)
 
     def sign_rsassa_pss(self, digest, algo='sha1', salt_length=20):
+        # type: (bytes, str, int) -> bytes
         """
         Signs a digest with the private key using RSASSA-PSS
 
-        @type digest: str
         @param digest: A digest created by using the digest method
-
-        @type salt_length: int
         @param salt_length: The length of the salt to use
-
-        @type algo: str
         @param algo: The hash algorithm to use
         Legal values like 'sha1','sha224', 'sha256', 'ripemd160',
         and 'md5'.
@@ -194,21 +206,16 @@ class RSA:
         return self.private_encrypt(signature, m2.no_padding)
 
     def verify_rsassa_pss(self, data, signature, algo='sha1', salt_length=20):
+        # type: (bytes, bytes, str, int) -> int
         """
         Verifies the signature RSASSA-PSS
 
-        @type data: str
         @param data: Data that has been signed
-
-        @type signature: str
         @param signature: The signature signed with RSASSA-PSS
-
-        @type salt_length: int
         @param salt_length: The length of the salt that was used
-
-        @type algo: str
         @param algo: The hash algorithm to use
-
+        Legal values are for example 'sha1','sha224', 'sha256',
+        'ripemd160', and 'md5'.
         @return: 1 or 0, depending on whether the signature was
         verified or not.
         """
@@ -222,17 +229,14 @@ class RSA:
         return m2.rsa_verify_pkcs1_pss(self.rsa, data, plain_signature, hash(), salt_length)
 
     def sign(self, digest, algo='sha1'):
+        # type: (bytes, str) -> bytes
         """
         Signs a digest with the private key
 
-        @type digest: str
         @param digest: A digest created by using the digest method
-
-        @type algo: str
         @param algo: The method that created the digest.
         Legal values like 'sha1','sha224', 'sha256', 'ripemd160',
         and 'md5'.
-
         @return: a string which is the signature
         """
         digest_type = getattr(m2, 'NID_' + algo, None)
@@ -242,22 +246,17 @@ class RSA:
         return m2.rsa_sign(self.rsa, digest, digest_type)
 
     def verify(self, data, signature, algo='sha1'):
+        # type: (bytes, bytes, str) -> int
         """
         Verifies the signature with the public key
 
-        @type data: str
         @param data: Data that has been signed
-
-        @type signature: str
         @param signature: The signature signed with the private key
-
-        @type algo: str
         @param algo: The method use to create digest from the data
         before it was signed.  Legal values like 'sha1','sha224',
         'sha256', 'ripemd160', and 'md5'.
-
-        @return: True or False, depending on whether the signature was
-        verified.
+        @return: 1 or 0, depending on whether the signature was
+        verified or not.
         """
         digest_type = getattr(m2, 'NID_' + algo, None)
         if digest_type is None:
@@ -273,24 +272,29 @@ class RSA_pub(RSA):  # noqa
     """
 
     def __setattr__(self, name, value):
+        # type: (str, bytes) -> None
         if name in ['e', 'n']:
             raise RSAError('use factory function new_pub_key() to set (e, n)')
         else:
             self.__dict__[name] = value
 
     def private_encrypt(self, *argv):
+        # type: (*List[Any]) -> None
         raise RSAError('RSA_pub object has no private key')
 
     def private_decrypt(self, *argv):
+        # type: (*List[Any]) -> None
         raise RSAError('RSA_pub object has no private key')
 
     def save_key(self, file, *args, **kw):
+        # type: (AnyStr, *List[Any], **Dict[Any, Any]) -> int
         """
         Save public key to file.
         """
         return self.save_pub_key(file)
 
     def save_key_bio(self, bio, *args, **kw):
+        # type: (BIO.BIO, *List[Any], **Dict[Any, Any]) -> int
         """
         Save public key to BIO.
         """
@@ -301,14 +305,17 @@ class RSA_pub(RSA):  # noqa
     # save_key_der_bio
 
     def check_key(self):
+        # type: () -> int
         return m2.rsa_check_pub_key(self.rsa)
 
 
 def rsa_error():
+    # type: () -> None
     raise RSAError(m2.err_reason_error_string(m2.err_get_error()))
 
 
 def keygen_callback(p, n, out=sys.stdout):
+    # type: (int, Any, IO[str]) -> None
     """
     Default callback for gen_key().
     """
@@ -318,39 +325,29 @@ def keygen_callback(p, n, out=sys.stdout):
 
 
 def gen_key(bits, e, callback=keygen_callback):
+    # type: (int, int, Callable) -> RSA
     """
     Generate an RSA key pair.
 
-    @type bits: int
     @param bits: Key length, in bits.
-
-    @type e: int
     @param e: The RSA public exponent.
-
-    @type callback: Python callable
     @param callback: A Python callable object that is invoked
     during key generation; its usual purpose is to provide visual
     feedback. The default callback is keygen_callback.
-
-    @rtype: M2Crypto.RSA.RSA
     @return: M2Crypto.RSA.RSA object.
     """
     return RSA(m2.rsa_generate_key(bits, e, callback), 1)
 
 
 def load_key(file, callback=util.passphrase_callback):
+    # type: (AnyStr, Callable) -> RSA
     """
     Load an RSA key pair from file.
 
-    @type file: string
     @param file: Name of file containing RSA public key in PEM format.
-
-    @type callback: Python callable
     @param callback: A Python callable object that is invoked
     to acquire a passphrase with which to unlock the key.
     The default is util.passphrase_callback.
-
-    @rtype: M2Crypto.RSA.RSA
     @return: M2Crypto.RSA.RSA object.
     """
     bio = BIO.openfile(file)
@@ -358,19 +355,15 @@ def load_key(file, callback=util.passphrase_callback):
 
 
 def load_key_bio(bio, callback=util.passphrase_callback):
+    # type: (BIO.BIO, Callable) -> RSA
     """
     Load an RSA key pair from an M2Crypto.BIO.BIO object.
 
-    @type bio: M2Crypto.BIO.BIO
     @param bio: M2Crypto.BIO.BIO object containing RSA key pair in PEM
     format.
-
-    @type callback: Python callable
     @param callback: A Python callable object that is invoked
     to acquire a passphrase with which to unlock the key.
     The default is util.passphrase_callback.
-
-    @rtype: M2Crypto.RSA.RSA
     @return: M2Crypto.RSA.RSA object.
     """
     rsa = m2.rsa_read_key(bio._ptr(), callback)
@@ -380,18 +373,14 @@ def load_key_bio(bio, callback=util.passphrase_callback):
 
 
 def load_key_string(string, callback=util.passphrase_callback):
+    # type: (AnyStr, Callable) -> RSA
     """
     Load an RSA key pair from a string.
 
-    @type string: string
     @param string: String containing RSA key pair in PEM format.
-
-    @type callback: Python callable
     @param callback: A Python callable object that is invoked
     to acquire a passphrase with which to unlock the key.
     The default is util.passphrase_callback.
-
-    @rtype: M2Crypto.RSA.RSA
     @return: M2Crypto.RSA.RSA object.
     """
     bio = BIO.MemoryBuffer(string)
@@ -399,13 +388,11 @@ def load_key_string(string, callback=util.passphrase_callback):
 
 
 def load_pub_key(file):
+    # type: (AnyStr) -> RSA_pub
     """
     Load an RSA public key from file.
 
-    @type file: string
     @param file: Name of file containing RSA public key in PEM format.
-
-    @rtype: M2Crypto.RSA.RSA_pub
     @return: M2Crypto.RSA.RSA_pub object.
     """
     bio = BIO.openfile(file)
@@ -413,14 +400,12 @@ def load_pub_key(file):
 
 
 def load_pub_key_bio(bio):
+    # type: (BIO.BIO) -> RSA_pub
     """
     Load an RSA public key from an M2Crypto.BIO.BIO object.
 
-    @type bio: M2Crypto.BIO.BIO
     @param bio: M2Crypto.BIO.BIO object containing RSA public key in PEM
     format.
-
-    @rtype: M2Crypto.RSA.RSA_pub
     @return: M2Crypto.RSA.RSA_pub object.
     """
     rsa = m2.rsa_read_pub_key(bio._ptr())
@@ -430,20 +415,16 @@ def load_pub_key_bio(bio):
 
 
 def new_pub_key(e_n):
+    # type: (Tuple[bytes, bytes]) -> RSA_pub
     """
     Instantiate an RSA_pub object from an (e, n) tuple.
 
-    @type e: string
     @param e: The RSA public exponent; it is a string in OpenSSL's MPINT
     format - 4-byte big-endian bit-count followed by the appropriate
     number of bits.
-
-    @type n: string
     @param n: The RSA composite of primes; it is a string in OpenSSL's MPINT
     format - 4-byte big-endian bit-count followed by the appropriate
     number of bits.
-
-    @rtype: M2Crypto.RSA.RSA_pub
     @return: M2Crypto.RSA.RSA_pub object.
     """
     (e, n) = e_n