diff options
| author | Matěj Cepl <mcepl@cepl.eu> | 2017-04-20 17:12:51 +0200 |
|---|---|---|
| committer | Matěj Cepl <mcepl@cepl.eu> | 2017-09-20 21:13:34 +0200 |
| commit | 82db77e1a9c1d03534a9c0b73d51801ba7257240 (patch) | |
| tree | d19e87bcb0d8128d3bc6396ee9406de9cd1e9012 | |
| parent | c0b300a5e4532b549f18b5526604219d717e2582 (diff) | |
| download | m2crypto-82db77e1a9c1d03534a9c0b73d51801ba7257240.tar.gz | |
Change JavaDoc parameters to the Sphinx convention.
| -rw-r--r-- | M2Crypto/ASN1.py | 4 | ||||
| -rw-r--r-- | M2Crypto/AuthCookie.py | 14 | ||||
| -rw-r--r-- | M2Crypto/BIO.py | 10 | ||||
| -rw-r--r-- | M2Crypto/BN.py | 14 | ||||
| -rw-r--r-- | M2Crypto/DSA.py | 119 | ||||
| -rw-r--r-- | M2Crypto/EC.py | 92 | ||||
| -rw-r--r-- | M2Crypto/EVP.py | 120 | ||||
| -rw-r--r-- | M2Crypto/Engine.py | 4 | ||||
| -rw-r--r-- | M2Crypto/RSA.py | 190 | ||||
| -rw-r--r-- | M2Crypto/SMIME.py | 2 | ||||
| -rw-r--r-- | M2Crypto/SSL/Checker.py | 6 | ||||
| -rw-r--r-- | M2Crypto/SSL/Cipher.py | 2 | ||||
| -rw-r--r-- | M2Crypto/SSL/Connection.py | 74 | ||||
| -rw-r--r-- | M2Crypto/SSL/Context.py | 80 | ||||
| -rw-r--r-- | M2Crypto/SSL/TwistedProtocolWrapper.py | 12 | ||||
| -rw-r--r-- | M2Crypto/X509.py | 310 | ||||
| -rw-r--r-- | M2Crypto/httpslib.py | 20 | ||||
| -rw-r--r-- | M2Crypto/m2urllib.py | 8 | ||||
| -rw-r--r-- | M2Crypto/m2urllib2.py | 3 | ||||
| -rw-r--r-- | doc/M2Crypto.rst | 8 | ||||
| -rw-r--r-- | doc/ZServerSSL-HOWTO.rst | 2 | ||||
| -rw-r--r-- | doc/conf.py | 2 | ||||
| -rw-r--r-- | doc/howto.ca.rst | 2 | ||||
| -rw-r--r-- | doc/howto.smime.rst | 2 | ||||
| -rw-r--r-- | doc/howto.ssl.rst | 2 | ||||
| -rw-r--r-- | setup.py | 10 |
26 files changed, 602 insertions, 510 deletions
diff --git a/M2Crypto/ASN1.py b/M2Crypto/ASN1.py index 778f3f6..018ec20 100644 --- a/M2Crypto/ASN1.py +++ b/M2Crypto/ASN1.py @@ -79,10 +79,10 @@ class ASN1_String: # noqa # type: (int) -> str """output an ASN1_STRING structure according to the set flags. - @param flags: determine the format of the output by using + :param flags: determine the format of the output by using predetermined constants, see ASN1_STRING_print_ex(3) manpage for their meaning. - @return: output an ASN1_STRING structure. + :return: output an ASN1_STRING structure. """ buf = BIO.MemoryBuffer() m2.asn1_string_print_ex(buf.bio_ptr(), self.asn1str, flags) diff --git a/M2Crypto/AuthCookie.py b/M2Crypto/AuthCookie.py index efadb46..b65b802 100644 --- a/M2Crypto/AuthCookie.py +++ b/M2Crypto/AuthCookie.py @@ -63,9 +63,9 @@ class AuthCookieJar: """ Make a cookie - @param expiry: expiration time (float in seconds) - @param data: cookie content - @return: AuthCookie object + :param expiry: expiration time (float in seconds) + :param data: cookie content + :return: AuthCookie object """ if not isinstance(expiry, (six.integer_types, float)): raise ValueError('Expiration time must be number, not "%s' % expiry) @@ -112,11 +112,11 @@ class AuthCookie: """ Create new authentication cookie - @param expiry: expiration time (in seconds) - @param data: cookie payload (as a string) - @param dough: expiry & data concatenated to URL compliant + :param expiry: expiration time (in seconds) + :param data: cookie payload (as a string) + :param dough: expiry & data concatenated to URL compliant string - @param mac: SHA1-based HMAC of dough and random key + :param mac: SHA1-based HMAC of dough and random key """ self._expiry = expiry self._data = data diff --git a/M2Crypto/BIO.py b/M2Crypto/BIO.py index c05e59b..3cd4230 100644 --- a/M2Crypto/BIO.py +++ b/M2Crypto/BIO.py @@ -98,7 +98,7 @@ class BIO(object): # type: (AnyStr) -> int """ - @return: either data written, or [0, -1] for nothing written, + :return: either data written, or [0, -1] for nothing written, -2 not implemented """ if not self.writeable(): @@ -115,7 +115,7 @@ class BIO(object): # type: () -> None """ - @return: 1 for success, and 0 or -1 for failure + :return: 1 for success, and 0 or -1 for failure """ m2.bio_flush(self.bio) @@ -123,7 +123,7 @@ class BIO(object): # type: () -> int """ Sets the bio to its initial state - @return: 1 for success, and 0 or -1 for failure + :return: 1 for success, and 0 or -1 for failure """ return m2.bio_reset(self.bio) @@ -228,7 +228,7 @@ class File(BIO): """ Object interface to BIO_s_pyfd - This class interfaces Python to OpenSSL functions that expect BIO *. For + This class interfaces Python to OpenSSL functions that expect BIO \*. For general file manipulation in Python, use Python's builtin file object. """ @@ -254,7 +254,7 @@ class File(BIO): # type: () -> int """ Sets the bio to its initial state - @return: 0 for success, and -1 for failure + :return: 0 for success, and -1 for failure """ return super(File, self).reset() diff --git a/M2Crypto/BN.py b/M2Crypto/BN.py index e131331..57a13a6 100644 --- a/M2Crypto/BN.py +++ b/M2Crypto/BN.py @@ -16,11 +16,11 @@ def rand(bits, top=-1, bottom=0): """ Generate cryptographically strong random number. - @param bits: Length of random number in bits. - @param top: If -1, the most significant bit can be 0. If 0, the most + :param bits: Length of random number in bits. + :param top: If -1, the most significant bit can be 0. If 0, the most significant bit is 1, and if 1, the two most significant bits will be 1. - @param bottom: If bottom is true, the number will be odd. + :param bottom: If bottom is true, the number will be odd. """ return m2.bn_rand(bits, top, bottom) @@ -30,8 +30,8 @@ def rand_range(range): """ Generate a random number in a range. - @param range: Upper limit for range. - @return: A random number in the range [0, range) + :param range: Upper limit for range. + :return: A random number in the range [0, range) """ return m2.bn_rand_range(range) @@ -42,8 +42,8 @@ def randfname(length): Return a random filename, which is simply a string where all the characters are from the set [a-zA-Z0-9]. - @param length: Length of filename to return. - @return: random filename string + :param length: Length of filename to return. + :return: random filename string """ import warnings warnings.warn( diff --git a/M2Crypto/DSA.py b/M2Crypto/DSA.py index ab2ea12..fd381e4 100644 --- a/M2Crypto/DSA.py +++ b/M2Crypto/DSA.py @@ -51,7 +51,7 @@ class DSA: # type: (bytes, int) -> None """ Use one of the factory functions to create an instance. - @param dsa: binary representation of OpenSSL DSA type + :param dsa: binary representation of OpenSSL DSA type """ assert m2.dsa_type_check(dsa), "'dsa' type error" self.dsa = dsa @@ -67,7 +67,7 @@ class DSA: """ Return the key length. - @return: the DSA key length in bits + :return: the DSA key length in bits """ assert m2.dsa_type_check(self.dsa), "'dsa' type error" return m2.dsa_keylen(self.dsa) @@ -77,9 +77,9 @@ class DSA: """ Return specified DSA parameters and key values. - @param name: name of variable to be returned. Must be + :param name: name of variable to be returned. Must be one of 'p', 'q', 'g', 'pub', 'priv'. - @return: value of specified variable (a "byte string") + :return: value of specified variable (a "byte string") """ if name in ['p', 'q', 'g', 'pub', 'priv']: method = getattr(m2, 'dsa_get_%s' % (name,)) @@ -102,14 +102,15 @@ class DSA: """ Set new parameters. - @param p: MPI binary representation ... format that consists of + :param p: MPI binary representation ... format that consists of the number's length in bytes represented as a 4-byte big-endian number, and the number itself in big-endian format, where the most significant bit signals a negative number (the representation of numbers with the MSB set is prefixed with null byte). - @param q: ditto - @param g: ditto + :param q: ditto + :param g: ditto + @warning: This does not change the private key, so it may be unsafe to use this method. It is better to use gen_params function to create a new DSA object. @@ -129,8 +130,8 @@ class DSA: """ Save the DSA parameters to a file. - @param filename: Save the DSA parameters to this file. - @return: 1 (true) if successful + :param filename: Save the DSA parameters to this file. + :return: 1 (true) if successful """ with BIO.openfile(filename, 'wb') as bio: ret = m2.dsa_write_params_bio(self.dsa, bio._ptr()) @@ -142,8 +143,8 @@ class DSA: """ Save DSA parameters to a BIO object. - @param bio: Save DSA parameters to this object. - @return: 1 (true) if successful + :param bio: Save DSA parameters to this object. + :return: 1 (true) if successful """ return m2.dsa_write_params_bio(self.dsa, bio._ptr()) @@ -153,10 +154,10 @@ class DSA: """ Save the DSA key pair to a file. - @param filename: Save the DSA key pair to this file. - @param cipher: name of symmetric key algorithm and mode + :param filename: Save the DSA key pair to this file. + :param cipher: name of symmetric key algorithm and mode to encrypt the private key. - @return: 1 (true) if successful + :return: 1 (true) if successful """ with BIO.openfile(filename, 'wb') as bio: ret = self.save_key_bio(bio, cipher, callback) @@ -169,10 +170,10 @@ class DSA: """ Save DSA key pair to a BIO object. - @param bio: Save DSA parameters to this object. - @param cipher: name of symmetric key algorithm and mode + :param bio: Save DSA parameters to this object. + :param cipher: name of symmetric key algorithm and mode to encrypt the private key. - @return: 1 (true) if successful + :return: 1 (true) if successful """ if cipher is None: return m2.dsa_write_key_bio_no_cipher(self.dsa, @@ -190,9 +191,9 @@ class DSA: """ Save the DSA public key (with parameters) to a file. - @param filename: Save DSA public key (with parameters) + :param filename: Save DSA public key (with parameters) to this file. - @return: 1 (true) if successful + :return: 1 (true) if successful """ with BIO.openfile(filename, 'wb') as bio: ret = self.save_pub_key_bio(bio) @@ -204,9 +205,9 @@ class DSA: """ Save DSA public key (with parameters) to a BIO object. - @param bio: Save DSA public key (with parameters) + :param bio: Save DSA public key (with parameters) to this object. - @return: 1 (true) if successful + :return: 1 (true) if successful """ return m2.dsa_write_pub_key_bio(self.dsa, bio._ptr()) @@ -215,9 +216,9 @@ class DSA: """ Sign the digest. - @param digest: SHA-1 hash of message (same as output + :param digest: SHA-1 hash of message (same as output from MessageDigest, a "byte string") - @return: DSA signature, a tuple of two values, r and s, + :return: DSA signature, a tuple of two values, r and s, both "byte strings". """ assert self.check_key(), 'key is not initialised' @@ -229,11 +230,11 @@ class DSA: Verify a newly calculated digest against the signature values r and s. - @param digest: SHA-1 hash of message (same as output + :param digest: SHA-1 hash of message (same as output from MessageDigest, a "byte string") - @param r: r value of the signature, a "byte string" - @param s: s value of the signature, a "byte string" - @return: 1 (true) if verify succeeded, 0 if failed + :param r: r value of the signature, a "byte string" + :param s: s value of the signature, a "byte string" + :return: 1 (true) if verify succeeded, 0 if failed """ assert self.check_key(), 'key is not initialised' return m2.dsa_verify(self.dsa, digest, r, s) @@ -250,7 +251,7 @@ class DSA: """ Check to be sure the DSA object has a valid private key. - @return: 1 (true) if a valid private key + :return: 1 (true) if a valid private key """ assert m2.dsa_type_check(self.dsa), "'dsa' type error" return m2.dsa_check_key(self.dsa) @@ -274,7 +275,7 @@ class DSA_pub(DSA): # noqa def check_key(self): # type: () -> int """ - @return: does DSA_pub contain a pub key? + :return: does DSA_pub contain a pub key? """ return m2.dsa_check_pub_key(self.dsa) @@ -292,12 +293,12 @@ def gen_params(bits, callback=util.genparam_callback): Factory function that generates DSA parameters and instantiates a DSA object from the output. - @param bits: The length of the prime to be generated. If + :param bits: The length of the prime to be generated. If 'bits' < 512, it is set to 512. - @param callback: A Python callback object that will be + :param callback: A Python callback object that will be invoked during parameter generation; it usual purpose is to provide visual feedback. - @return: instance of DSA. + :return: instance of DSA. """ dsa = m2.dsa_generate_parameters(bits, callback) if dsa is None: @@ -311,10 +312,10 @@ def set_params(p, q, g): Factory function that instantiates a DSA object with DSA parameters. - @param p: value of p, a "byte string" - @param q: value of q, a "byte string" - @param g: value of g, a "byte string" - @return: instance of DSA. + :param p: value of p, a "byte string" + :param q: value of q, a "byte string" + :param g: value of g, a "byte string" + :return: instance of DSA. """ dsa = m2.dsa_new() m2.dsa_set_pqg(dsa, p, q, g) @@ -327,12 +328,12 @@ def load_params(file, callback=util.passphrase_callback): Factory function that instantiates a DSA object with DSA parameters from a file. - @param file: Names the file (a path) that contains the PEM + :param file: Names the file (a path) that contains the PEM representation of the DSA parameters. - @param callback: A Python callback object that will be + :param callback: A Python callback object that will be invoked if the DSA parameters file is passphrase-protected. - @return: instance of DSA. + :return: instance of DSA. """ with BIO.openfile(file) as bio: ret = load_params_bio(bio, callback) @@ -346,12 +347,12 @@ def load_params_bio(bio, callback=util.passphrase_callback): Factory function that instantiates a DSA object with DSA parameters from a M2Crypto.BIO object. - @param bio: Contains the PEM representation of the DSA + :param bio: Contains the PEM representation of the DSA parameters. - @param callback: A Python callback object that will be + :param callback: A Python callback object that will be invoked if the DSA parameters file is passphrase-protected. - @return: instance of DSA. + :return: instance of DSA. """ dsa = m2.dsa_read_params(bio._ptr(), callback) if dsa is None: @@ -365,12 +366,12 @@ def load_key(file, callback=util.passphrase_callback): Factory function that instantiates a DSA object from a PEM encoded DSA key pair. - @param file: Names the file (a path) that contains the PEM + :param file: Names the file (a path) that contains the PEM representation of the DSA key pair. - @param callback: A Python callback object that will be + :param callback: A Python callback object that will be invoked if the DSA key pair is passphrase-protected. - @return: instance of DSA. + :return: instance of DSA. """ with BIO.openfile(file) as bio: ret = load_key_bio(bio, callback) @@ -384,12 +385,12 @@ def load_key_bio(bio, callback=util.passphrase_callback): Factory function that instantiates a DSA object from a PEM encoded DSA key pair. - @param bio: Contains the PEM representation of the DSA + :param bio: Contains the PEM representation of the DSA key pair. - @param callback: A Python callback object that will be + :param callback: A Python callback object that will be invoked if the DSA key pair is passphrase-protected. - @return: instance of DSA. + :return: instance of DSA. """ dsa = m2.dsa_read_key(bio._ptr(), callback) if not dsa: @@ -403,11 +404,11 @@ def pub_key_from_params(p, q, g, pub): Factory function that instantiates a DSA_pub object using the parameters and public key specified. - @param p: value of p - @param q: value of q - @param g: value of g - @param pub: value of the public key - @return: instance of DSA_pub. + :param p: value of p + :param q: value of q + :param g: value of g + :param pub: value of the public key + :return: instance of DSA_pub. """ dsa = m2.dsa_new() m2.dsa_set_pqg(dsa, p, q, g) @@ -422,12 +423,12 @@ def load_pub_key(file, callback=util.passphrase_callback): a DSA public key contained in PEM file. The PEM file must contain the parameters in addition to the public key. - @param file: Names the file (a path) that contains the PEM + :param file: Names the file (a path) that contains the PEM representation of the DSA public key. - @param callback: A Python callback object that will be + :param callback: A Python callback object that will be invoked should the DSA public key be passphrase-protected. - @return: instance of DSA_pub. + :return: instance of DSA_pub. """ with BIO.openfile(file) as bio: ret = load_pub_key_bio(bio, callback) @@ -442,12 +443,12 @@ def load_pub_key_bio(bio, callback=util.passphrase_callback): a DSA public key contained in PEM format. The PEM must contain the parameters in addition to the public key. - @param bio: Contains the PEM representation of the DSA + :param bio: Contains the PEM representation of the DSA public key (with params). - @param callback: A Python callback object that will be + :param callback: A Python callback object that will be invoked should the DSA public key be passphrase-protected. - @return: instance of DSA_pub. + :return: instance of DSA_pub. """ dsapub = m2.dsa_read_pub_key(bio._ptr(), callback) if not dsapub: diff --git a/M2Crypto/EC.py b/M2Crypto/EC.py index b295d06..51517a5 100644 --- a/M2Crypto/EC.py +++ b/M2Crypto/EC.py @@ -156,8 +156,10 @@ class EC: # type: () -> int """ Generates the key pair from its parameters. Use:: + keypair = EC.gen_params(curve) keypair.gen_key() + to create an EC key pair. """ assert m2.ec_key_type_check(self.ec), "'ec' type error" @@ -212,15 +214,16 @@ class EC: """ Save the key pair to an M2Crypto.BIO.BIO object in PEM format. - @param bio: M2Crypto.BIO.BIO object to save key to. + :param bio: M2Crypto.BIO.BIO object to save key to. - @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. + :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. - @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. + :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. """ if cipher is None: return m2.ec_key_write_bio_no_cipher(self.ec, bio._ptr(), callback) @@ -236,15 +239,16 @@ class EC: """ Save the key pair to a file in PEM format. - @param file: Name of filename to save key to. + :param file: Name of filename to save key to. - @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. + :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. - @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. + :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. """ with BIO.openfile(file, 'wb') as bio: return self.save_key_bio(bio, cipher, callback) @@ -254,7 +258,7 @@ class EC: """ Save the public key to an M2Crypto.BIO.BIO object in PEM format. - @param bio: M2Crypto.BIO.BIO object to save key to. + :param bio: M2Crypto.BIO.BIO object to save key to. """ return m2.ec_key_write_pubkey(self.ec, bio._ptr()) @@ -263,7 +267,7 @@ class EC: """ Save the public key to a filename in PEM format. - @param file: Name of filename to save key to. + :param file: Name of filename to save key to. """ with BIO.openfile(file, 'wb') as bio: return m2.ec_key_write_pubkey(self.ec, bio._ptr()) @@ -328,7 +332,7 @@ def gen_params(curve): Factory function that generates EC parameters and instantiates a EC object from the output. - @param curve: This is the OpenSSL nid of the curve to use. + :param curve: This is the OpenSSL nid of the curve to use. """ assert curve in [x['NID'] for x in m2.ec_get_builtin_curves()], \ 'Elliptic curve %s is not available on this system.' % \ @@ -341,30 +345,28 @@ def load_key(file, callback=util.passphrase_callback): """ Factory function that instantiates a EC object. - @param file: Names the filename that contains the PEM representation - of the EC key pair. + :param file: Names the filename that contains the PEM representation + of the EC key pair. - @param callback: Python callback object that will be invoked - if the EC key pair is passphrase-protected. + :param callback: Python callback object that will be invoked + if the EC key pair is passphrase-protected. """ with BIO.openfile(file) as bio: return load_key_bio(bio, callback) def load_key_string(string, callback=util.passphrase_callback): + # type: (str, Callable) -> EC """ Load an EC key pair from a string. - @type string: string - @param string: String containing EC key pair in PEM format. + :param string: String containing EC 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. + :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.EC.EC - @return: M2Crypto.EC.EC object. + :return: M2Crypto.EC.EC object. """ with BIO.MemoryBuffer(string) as bio: return load_key_bio(bio, callback) @@ -375,11 +377,11 @@ def load_key_bio(bio, callback=util.passphrase_callback): """ Factory function that instantiates a EC object. - @param bio: M2Crypto.BIO object that contains the PEM - representation of the EC key pair. + :param bio: M2Crypto.BIO object that contains the PEM + representation of the EC key pair. - @param callback: Python callback object that will be invoked - if the EC key pair is passphrase-protected. + :param callback: Python callback object that will be invoked + if the EC key pair is passphrase-protected. """ return EC(m2.ec_key_read_bio(bio._ptr(), callback), 1) @@ -389,27 +391,27 @@ def load_pub_key(file): """ Load an EC public key from filename. - @param file: Name of filename containing EC public key in PEM format. + :param file: Name of filename containing EC public key in PEM + format. - @return: M2Crypto.EC.EC_pub object. + :return: M2Crypto.EC.EC_pub object. """ with BIO.openfile(file) as bio: return load_pub_key_bio(bio) def load_key_string_pubkey(string, callback=util.passphrase_callback): + # type: (str, Callable) -> PKey """ Load an M2Crypto.EC.PKey from a public key as a string. - @type string: string - @param string: String containing the key in PEM format. + :param string: String containing the key in PEM format. - @type callback: Python callable - @param callback: A Python callable object that is invoked - to acquire a passphrase with which to protect the key. + :param callback: A Python callable object that is invoked + to acquire a passphrase with which to protect the + key. - @rtype: M2Crypto.EC.PKey - @return: M2Crypto.EC.PKey object. + :return: M2Crypto.EC.PKey object. """ with BIO.MemoryBuffer(string) as bio: return load_key_bio_pubkey(bio, callback) @@ -420,10 +422,10 @@ def load_pub_key_bio(bio): """ Load an EC public key from an M2Crypto.BIO.BIO object. - @param bio: M2Crypto.BIO.BIO object containing EC public key in PEM - format. + :param bio: M2Crypto.BIO.BIO object containing EC public key in PEM + format. - @return: M2Crypto.EC.EC_pub object. + :return: M2Crypto.EC.EC_pub object. """ ec = m2.ec_key_read_pubkey(bio._ptr()) if ec is None: diff --git a/M2Crypto/EVP.py b/M2Crypto/EVP.py index 4fd4633..effba9e 100644 --- a/M2Crypto/EVP.py +++ b/M2Crypto/EVP.py @@ -24,11 +24,11 @@ def pbkdf2(password, salt, iter, keylen): """ Derive a key from password using PBKDF2 algorithm specified in RFC 2898. - @param password: Derive the key from this password. - @param salt: Salt. - @param iter: Number of iterations to perform. - @param keylen: Length of key to produce. - @return: Key. + :param password: Derive the key from this password. + :param salt: Salt. + :param iter: Number of iterations to perform. + :param keylen: Length of key to produce. + :return: Key. """ return m2.pkcs5_pbkdf2_hmac_sha1(password, salt, iter, keylen) @@ -63,7 +63,7 @@ class MessageDigest: """ Add data to be digested. - @return: -1 for Python error, 1 for success, 0 for OpenSSL failure. + :return: -1 for Python error, 1 for success, 0 for OpenSSL failure. """ return m2.digest_update(self.ctx, data) @@ -198,7 +198,7 @@ class PKey: """ Reset internal message digest context. - @param md: The message digest algorithm. + :param md: The message digest algorithm. """ self._set_context(md) @@ -214,7 +214,7 @@ class PKey: """ Feed data to signing operation. - @param data: Data to be signed. + :param data: Data to be signed. """ m2.sign_update(self.ctx, data) @@ -223,7 +223,7 @@ class PKey: """ Return signature. - @return: The signature. + :return: The signature. """ return m2.sign_final(self.ctx, self.pkey) @@ -243,8 +243,8 @@ class PKey: """ Feed data to verification operation. - @param data: Data to be verified. - @return: -1 on Python error, 1 for success, 0 for OpenSSL error + :param data: Data to be verified. + :return: -1 on Python error, 1 for success, 0 for OpenSSL error """ return m2.verify_update(self.ctx, data) @@ -253,8 +253,8 @@ class PKey: """ Return result of verification. - @param sign: Signature to use for verification - @return: Result of verification: 1 for success, 0 for failure, -1 on + :param sign: Signature to use for verification + :return: Result of verification: 1 for success, 0 for failure, -1 on other error. """ return m2.verify_final(self.ctx, sign, self.pkey) @@ -264,13 +264,13 @@ class PKey: """ Assign the RSA key pair to self. - @param rsa: M2Crypto.RSA.RSA object to be assigned to self. + :param rsa: M2Crypto.RSA.RSA object to be assigned to self. - @param capture: If true (default), this PKey object will own the RSA + :param capture: If true (default), this PKey object will own the RSA object, meaning that once the PKey object gets deleted it is no longer safe to use the RSA object. - @return: Return 1 for success and 0 for failure. + :return: Return 1 for success and 0 for failure. """ if capture: ret = m2.pkey_assign_rsa(self.pkey, rsa.rsa) @@ -299,15 +299,16 @@ class PKey: """ Save the key pair to a file in PEM format. - @param file: Name of file to save key to. + :param file: Name of file to save key to. - @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. + :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. - @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. + :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. """ with BIO.openfile(file, 'wb') as bio: return self.save_key_bio(bio, cipher, callback) @@ -318,15 +319,16 @@ class PKey: """ Save the key pair to the M2Crypto.BIO object 'bio' in PEM format. - @param bio: M2Crypto.BIO object to save key to. + :param bio: M2Crypto.BIO object to save key to. - @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. + :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. - @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. + :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. """ if cipher is None: return m2.pkey_write_pem_no_cipher(self.pkey, bio._ptr(), callback) @@ -341,13 +343,14 @@ class PKey: """ Return key in PEM format in a 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. + :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. - @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. + :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. """ bio = BIO.MemoryBuffer() self.save_key_bio(bio, cipher, callback) @@ -382,12 +385,13 @@ def load_key(file, callback=util.passphrase_callback): """ Load an M2Crypto.EVP.PKey from file. - @param file: Name of file containing the key in PEM format. + :param file: Name of file containing the key in PEM format. - @param callback: A Python callable object that is invoked - to acquire a passphrase with which to protect the key. + :param callback: A Python callable object that is invoked + to acquire a passphrase with which to protect the + key. - @return: M2Crypto.EVP.PKey object. + :return: M2Crypto.EVP.PKey object. """ bio = m2.bio_new_file(file, 'r') if bio is None: @@ -404,12 +408,13 @@ def load_key_bio(bio, callback=util.passphrase_callback): """ Load an M2Crypto.EVP.PKey from an M2Crypto.BIO object. - @param bio: M2Crypto.BIO object containing the key in PEM format. + :param bio: M2Crypto.BIO object containing the key in PEM format. - @param callback: A Python callable object that is invoked - to acquire a passphrase with which to protect the key. + :param callback: A Python callable object that is invoked + to acquire a passphrase with which to protect the + key. - @return: M2Crypto.EVP.PKey object. + :return: M2Crypto.EVP.PKey object. """ cptr = m2.pkey_read_pem(bio._ptr(), callback) if cptr is None: @@ -422,12 +427,13 @@ def load_key_bio_pubkey(bio, callback=util.passphrase_callback): """ Load an M2Crypto.EVP.PKey from a public key as a M2Crypto.BIO object. - @param bio: M2Crypto.BIO object containing the key in PEM format. + :param bio: M2Crypto.BIO object containing the key in PEM format. - @param callback: A Python callable object that is invoked - to acquire a passphrase with which to protect the key. + :param callback: A Python callable object that is invoked + to acquire a passphrase with which to protect the + key. - @return: M2Crypto.EVP.PKey object. + :return: M2Crypto.EVP.PKey object. """ cptr = m2.pkey_read_pem_pubkey(bio._ptr(), callback) if cptr is None: @@ -440,12 +446,13 @@ def load_key_string(string, callback=util.passphrase_callback): """ Load an M2Crypto.EVP.PKey from a string. - @param string: String containing the key in PEM format. + :param string: String containing the key in PEM format. - @param callback: A Python callable object that is invoked - to acquire a passphrase with which to protect the key. + :param callback: A Python callable object that is invoked + to acquire a passphrase with which to protect the + key. - @return: M2Crypto.EVP.PKey object. + :return: M2Crypto.EVP.PKey object. """ bio = BIO.MemoryBuffer(string) return load_key_bio(bio, callback) @@ -456,12 +463,13 @@ def load_key_string_pubkey(string, callback=util.passphrase_callback): """ Load an M2Crypto.EVP.PKey from a public key as a string. - @param string: String containing the key in PEM format. + :param string: String containing the key in PEM format. - @param callback: A Python callable object that is invoked - to acquire a passphrase with which to protect the key. + :param callback: A Python callable object that is invoked + to acquire a passphrase with which to protect the + key. - @return: M2Crypto.EVP.PKey object. + :return: M2Crypto.EVP.PKey object. """ bio = BIO.MemoryBuffer(string) return load_key_bio_pubkey(bio, callback) diff --git a/M2Crypto/Engine.py b/M2Crypto/Engine.py index 3518cc4..8878568 100644 --- a/M2Crypto/Engine.py +++ b/M2Crypto/Engine.py @@ -43,7 +43,7 @@ class Engine: # type: () -> int """Obtain a functional reference to the engine. - @return: 0 on error, non-zero on success.""" + :return: 0 on error, non-zero on success.""" return m2.engine_init(self._ptr) def finish(self): @@ -72,7 +72,7 @@ class Engine: """ Use this engine as default for methods specified in argument - @param methods: Possible values are bitwise OR of m2.ENGINE_METHOD_* + :param methods: Possible values are bitwise OR of m2.ENGINE_METHOD_* """ return m2.engine_set_default(self._ptr, methods) diff --git a/M2Crypto/RSA.py b/M2Crypto/RSA.py index c7d2709..e313432 100644 --- a/M2Crypto/RSA.py +++ b/M2Crypto/RSA.py @@ -32,7 +32,7 @@ class RSA: def __init__(self, rsa, _pyfree=0): # type: (bytes, int) -> None """ - @param rsa: binary representation of OpenSSL RSA type + :param rsa: binary representation of OpenSSL RSA type """ assert m2.rsa_type_check(rsa), "'rsa' type error" self.rsa = rsa @@ -87,13 +87,16 @@ class RSA: """ Save the key pair to an M2Crypto.BIO.BIO object in PEM format. - @param bio: M2Crypto.BIO.BIO object to save key to. - @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. - @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. + :param bio: M2Crypto.BIO.BIO object to save key to. + + :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. + + :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. """ if cipher is None: return m2.rsa_write_key_no_cipher(self.rsa, bio._ptr(), callback) @@ -111,15 +114,16 @@ class RSA: """ Save the key pair to a file in PEM format. - @param file: Name of file to save key to. + :param file: Name of file to save key to. - @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. + :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. - @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. + :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. """ with BIO.openfile(file, 'wb') as bio: return self.save_key_bio(bio, cipher, callback) @@ -140,7 +144,7 @@ class RSA: """ Save the key pair to an M2Crypto.BIO.BIO object in DER format. - @param bio: M2Crypto.BIO.BIO object to save key to. + :param bio: M2Crypto.BIO.BIO object to save key to. """ return m2.rsa_write_key_der(self.rsa, bio._ptr()) @@ -149,7 +153,7 @@ class RSA: """ Save the key pair to a file in DER format. - @param file: Filename to save key to + :param file: Filename to save key to """ with BIO.openfile(file, 'wb') as bio: return self.save_key_der_bio(bio) @@ -159,7 +163,7 @@ class RSA: """ Save the public key to an M2Crypto.BIO.BIO object in PEM format. - @param bio: M2Crypto.BIO.BIO object to save key to. + :param bio: M2Crypto.BIO.BIO object to save key to. """ return m2.rsa_write_pub_key(self.rsa, bio._ptr()) @@ -168,7 +172,7 @@ class RSA: """ Save the public key to a file in PEM format. - @param file: Name of file to save key to. + :param file: Name of file to save key to. """ with BIO.openfile(file, 'wb') as bio: return m2.rsa_write_pub_key(self.rsa, bio._ptr()) @@ -176,7 +180,8 @@ class RSA: def check_key(self): # type: () -> int """ - @return: returns 1 if rsa is a valid RSA key, and 0 otherwise. + + :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). @@ -188,13 +193,15 @@ class RSA: """ Signs a digest with the private key using RSASSA-PSS - @param digest: A digest created by using the digest method - @param salt_length: The length of the salt to use - @param algo: The hash algorithm to use - Legal values like 'sha1','sha224', 'sha256', 'ripemd160', - and 'md5'. + :param digest: A digest created by using the digest method + + :param salt_length: The length of the salt to use - @return: a string which is the signature + :param algo: The hash algorithm to use + Legal values like 'sha1','sha224', 'sha256', + 'ripemd160', and 'md5'. + + :return: a string which is the signature """ hash = getattr(m2, algo, None) @@ -210,14 +217,18 @@ class RSA: """ Verifies the signature RSASSA-PSS - @param data: Data that has been signed - @param signature: The signature signed with RSASSA-PSS - @param salt_length: The length of the salt that was used - @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. + :param data: Data that has been signed + + :param signature: The signature signed with RSASSA-PSS + + :param salt_length: The length of the salt that was used + + :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. """ hash = getattr(m2, algo, None) @@ -233,11 +244,13 @@ class RSA: """ Signs a digest with the private key - @param digest: A digest created by using the digest method - @param algo: The method that created the digest. - Legal values like 'sha1','sha224', 'sha256', 'ripemd160', - and 'md5'. - @return: a string which is the signature + :param digest: A digest created by using the digest method + + :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) if digest_type is None: @@ -250,13 +263,16 @@ class RSA: """ Verifies the signature with the public key - @param data: Data that has been signed - @param signature: The signature signed with the private key - @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: 1 or 0, depending on whether the signature was - verified or not. + :param data: Data that has been signed + + :param signature: The signature signed with the private key + + :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: 1 or 0, depending on whether the signature was + verified or not. """ digest_type = getattr(m2, 'NID_' + algo, None) if digest_type is None: @@ -329,12 +345,16 @@ def gen_key(bits, e, callback=keygen_callback): """ Generate an RSA key pair. - @param bits: Key length, in bits. - @param e: The RSA public exponent. - @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. - @return: M2Crypto.RSA.RSA object. + :param bits: Key length, in bits. + + :param e: The RSA public exponent. + + :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. + + :return: M2Crypto.RSA.RSA object. """ return RSA(m2.rsa_generate_key(bits, e, callback), 1) @@ -344,11 +364,13 @@ def load_key(file, callback=util.passphrase_callback): """ Load an RSA key pair from file. - @param file: Name of file containing RSA public key in PEM format. - @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. - @return: M2Crypto.RSA.RSA object. + :param file: Name of file containing RSA public key in PEM format. + + :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. + + :return: M2Crypto.RSA.RSA object. """ with BIO.openfile(file) as bio: return load_key_bio(bio, callback) @@ -359,12 +381,14 @@ def load_key_bio(bio, callback=util.passphrase_callback): """ Load an RSA key pair from an M2Crypto.BIO.BIO object. - @param bio: M2Crypto.BIO.BIO object containing RSA key pair in PEM - format. - @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. - @return: M2Crypto.RSA.RSA object. + :param bio: M2Crypto.BIO.BIO object containing RSA key pair in PEM + format. + + :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. + + :return: M2Crypto.RSA.RSA object. """ rsa = m2.rsa_read_key(bio._ptr(), callback) if rsa is None: @@ -377,11 +401,13 @@ def load_key_string(string, callback=util.passphrase_callback): """ Load an RSA key pair from a string. - @param string: String containing RSA key pair in PEM format. - @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. - @return: M2Crypto.RSA.RSA object. + :param string: String containing RSA key pair in PEM format. + + :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. + + :return: M2Crypto.RSA.RSA object. """ bio = BIO.MemoryBuffer(string) return load_key_bio(bio, callback) @@ -392,8 +418,9 @@ def load_pub_key(file): """ Load an RSA public key from file. - @param file: Name of file containing RSA public key in PEM format. - @return: M2Crypto.RSA.RSA_pub object. + :param file: Name of file containing RSA public key in PEM format. + + :return: M2Crypto.RSA.RSA_pub object. """ with BIO.openfile(file) as bio: return load_pub_key_bio(bio) @@ -404,9 +431,10 @@ def load_pub_key_bio(bio): """ Load an RSA public key from an M2Crypto.BIO.BIO object. - @param bio: M2Crypto.BIO.BIO object containing RSA public key in PEM - format. - @return: M2Crypto.RSA.RSA_pub object. + :param bio: M2Crypto.BIO.BIO object containing RSA public key in PEM + format. + + :return: M2Crypto.RSA.RSA_pub object. """ rsa = m2.rsa_read_pub_key(bio._ptr()) if rsa is None: @@ -419,13 +447,15 @@ def new_pub_key(e_n): """ Instantiate an RSA_pub object from an (e, n) tuple. - @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. - @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. - @return: M2Crypto.RSA.RSA_pub object. + :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. + + :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. + + :return: M2Crypto.RSA.RSA_pub object. """ (e, n) = e_n rsa = m2.rsa_new() diff --git a/M2Crypto/SMIME.py b/M2Crypto/SMIME.py index 8695c8f..f267890 100644 --- a/M2Crypto/SMIME.py +++ b/M2Crypto/SMIME.py @@ -37,7 +37,7 @@ class PKCS7: def __init__(self, pkcs7=None, _pyfree=0): # type: (Optional[bytes], int) -> None """ - @param pkcs7: binary representation of + :param pkcs7: binary representation of the OpenSSL type PKCS7 """ if pkcs7 is not None: diff --git a/M2Crypto/SSL/Checker.py b/M2Crypto/SSL/Checker.py index 1dde2a4..d3cb7f6 100644 --- a/M2Crypto/SSL/Checker.py +++ b/M2Crypto/SSL/Checker.py @@ -38,11 +38,11 @@ class WrongHost(SSLVerificationError): peer was issued for a different host than we tried to connect to. This could be due to a server misconfiguration or an active attack. - @param expectedHost: The name of the host we expected to find in the + :param expectedHost: The name of the host we expected to find in the certificate. - @param actualHost: The name of the host we actually found in the + :param actualHost: The name of the host we actually found in the certificate. - @param fieldName: The field name where we noticed the error. This + :param fieldName: The field name where we noticed the error. This should be either 'commonName' or 'subjectAltName'. """ if fieldName not in ('commonName', 'subjectAltName'): diff --git a/M2Crypto/SSL/Cipher.py b/M2Crypto/SSL/Cipher.py index 0b03909..eec92aa 100644 --- a/M2Crypto/SSL/Cipher.py +++ b/M2Crypto/SSL/Cipher.py @@ -39,7 +39,7 @@ class Cipher_Stack: # noqa def __init__(self, stack): # type: (bytes) -> None """ - @param stack: binary of the C-type STACK_OF(SSL_CIPHER) + :param stack: binary of the C-type STACK_OF(SSL_CIPHER) """ self.stack = stack diff --git a/M2Crypto/SSL/Connection.py b/M2Crypto/SSL/Connection.py index e82ed3d..2637d33 100644 --- a/M2Crypto/SSL/Connection.py +++ b/M2Crypto/SSL/Connection.py @@ -47,9 +47,9 @@ class Connection: # type: (Context, socket.socket, int) -> None """ - @param ctx: SSL.Context - @param sock: socket to be used - @param family: socket family + :param ctx: SSL.Context + :param sock: socket to be used + :param family: socket family """ self.ctx = ctx self.ssl = m2.ssl_new(self.ctx.ctx) @@ -115,7 +115,7 @@ class Connection: SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time. - @param mode: set the mode bitmask. + :param mode: set the mode bitmask. """ m2.ssl_set_shutdown1(self.ssl, mode) @@ -151,8 +151,8 @@ class Connection: will be called (for both the reading and writing side, if different). - @param readbio: BIO for reading - @param writebio: BIO for writing. + :param readbio: BIO for reading + :param writebio: BIO for writing. """ m2.ssl_set_bio(self.ssl, readbio._ptr(), writebio._ptr()) @@ -165,11 +165,13 @@ class Connection: Makes sense only for servers. - @param cafile: Filename from which to load the CA list. - @return: 0 A failure while manipulating the STACK_OF(X509_NAME) + :param cafile: Filename from which to load the CA list. + + :return: 0 A failure while manipulating the STACK_OF(X509_NAME) object occurred or the X509_NAME could not be extracted from cacert. Check the error stack to find out the reason. + 1 The operation succeeded. """ m2.ssl_set_client_CA_list_from_file(self.ssl, cafile) @@ -195,7 +197,7 @@ class Connection: By default, SSL struct will be freed in __del__. Call with m2.bio_close to override this default. - @param flag: either m2.bio_close or m2.bio_noclose + :param flag: either m2.bio_close or m2.bio_noclose """ if flag not in (m2.bio_close, m2.bio_noclose): raise ValueError("flag must be m2.bio_close or m2.bio_noclose") @@ -230,7 +232,7 @@ class Connection: The communication channel must already have been set and assigned to the ssl by setting an underlying BIO. - @return: 0 The TLS/SSL handshake was not successful but was shut + :return: 0 The TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. Call get_error() with the return value ret to find out the reason. @@ -256,10 +258,11 @@ class Connection: connection object and addr is the address bound to the other end of the SSL connection. - @return: tuple of Connection and addr. Address can take very - various forms (see socket documentation), for IPv4 it is - tuple(str, int), for IPv6 a tuple of four (host, port, flowinfo, - scopeid), where the last two are optional ints. + :return: tuple of Connection and addr. Address can take very + various forms (see socket documentation), for IPv4 it + is tuple(str, int), for IPv6 a tuple of four (host, + port, flowinfo, scopeid), where the last two are + optional ints. """ sock, addr = self.socket.accept() ssl = Connection(self.ctx, sock) @@ -288,8 +291,9 @@ class Connection: # type: (util.AddrType) -> int """Overloading socket.connect() - @param addr: addresses have various depending on their type - @return:status of ssl_connect() + :param addr: addresses have various depending on their type + + :return:status of ssl_connect() """ self.socket.connect(addr) self.addr = addr @@ -365,7 +369,7 @@ class Connection: s.setblocking(0) is equivalent to s.settimeout(0.0); s.setblocking(1) is equivalent to s.settimeout(None). - @param mode: new mode to be set + :param mode: new mode to be set """ self.socket.setblocking(mode) if mode: @@ -389,7 +393,7 @@ class Connection: # type: (int, int, Optional[int]) -> Union[int, bytes] """Get the value of the given socket option. - @param level: level at which the option resides. + :param level: level at which the option resides. To manipulate options at the sockets API level, level is specified as socket.SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate @@ -397,16 +401,19 @@ class Connection: to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of socket.SOL_TCP; see getprotoent(3). - @param optname: The value of the given socket option is + + :param optname: The value of the given socket option is described in the Unix man page getsockopt(2)). The needed symbolic constants (SO_* etc.) are defined in the socket module. - @param buflen: If it is absent, an integer option is assumed + + :param buflen: If it is absent, an integer option is assumed and its integer value is returned by the function. If buflen is present, it specifies the maximum length of the buffer used to receive the option in, and this buffer is returned as a bytes object. - @return: Either integer or bytes value of the option. It is up + + :return: Either integer or bytes value of the option. It is up to the caller to decode the contents of the buffer (see the optional built-in module struct for a way to decode C structures encoded as byte strings). @@ -417,14 +424,17 @@ class Connection: # type: (int, int, Union[int, bytes, None]) -> Optional[bytes] """Set the value of the given socket option. - @param level: same as with getsockopt() above - @param optname: same as with getsockopt() above - @param value: an integer or a string representing a buffer. In + :param level: same as with getsockopt() above + + :param optname: same as with getsockopt() above + + :param value: an integer or a string representing a buffer. In the latter case it is up to the caller to ensure that the string contains the proper bits (see the optional built-in module struct for a way to encode C structures as strings). - @return: None for success or the error handler for failure. + + :return: None for success or the error handler for failure. """ return self.socket.setsockopt(level, optname, value) @@ -443,8 +453,8 @@ class Connection: established. It however can be of significant interest during the handshake. - @return: 6 letter string indicating the current state of the SSL - object ssl. + :return: 6 letter string indicating the current state of the SSL + object ssl. """ return m2.ssl_get_state(self.ssl) @@ -484,9 +494,9 @@ class Connection: """Return the peer certificate chain; if the peer did not provide a certificate chain, return None. - @warning: The returned chain will be valid only for as long as the - connection object is alive. Once the connection object gets freed, - the chain will be freed as well. + :warning: The returned chain will be valid only for as long as the + connection object is alive. Once the connection object + gets freed, the chain will be freed as well. """ c = m2.ssl_get_peer_cert_chain(self.ssl) if c is None: @@ -537,7 +547,7 @@ class Connection: for instance. (The format of the address returned depends on the address family -- see above.) - @return:socket's address as addr type + :return:socket's address as addr type """ return self.socket.getsockname() @@ -549,7 +559,7 @@ class Connection: for instance. On some systems this function is not supported. - @return: + :return: """ return self.socket.getpeername() diff --git a/M2Crypto/SSL/Context.py b/M2Crypto/SSL/Context.py index 9c5892e..21baa8c 100644 --- a/M2Crypto/SSL/Context.py +++ b/M2Crypto/SSL/Context.py @@ -84,11 +84,11 @@ class Context: # type: (AnyStr, Optional[AnyStr], Callable) -> None """Load certificate and private key into the context. - @param certfile: File that contains the PEM-encoded certificate. - @param keyfile: File that contains the PEM-encoded private key. + :param certfile: File that contains the PEM-encoded certificate. + :param keyfile: File that contains the PEM-encoded private key. Default value of None indicates that the private key is to be found in 'certfile'. - @param callback: Callable object to be invoked if the private key is + :param callback: Callable object to be invoked if the private key is passphrase-protected. Default callback provides a simple terminal-style input for the passphrase. """ @@ -105,12 +105,12 @@ class Context: # type: (AnyStr, Optional[AnyStr], Callable) -> None """Load certificate chain and private key into the context. - @param certchainfile: File object containing the PEM-encoded + :param certchainfile: File object containing the PEM-encoded certificate chain. - @param keyfile: File object containing the PEM-encoded private + :param keyfile: File object containing the PEM-encoded private key. Default value of None indicates that the private key is to be found in 'certchainfile'. - @param callback: Callable object to be invoked if the private key + :param callback: Callable object to be invoked if the private key is passphrase-protected. Default callback provides a simple terminal-style input for the passphrase. @@ -128,7 +128,7 @@ class Context: """Load CA certs into the context. These CA certs are sent to the peer during *SSLv3 certificate request*. - @param cafile: File object containing one or more PEM-encoded CA + :param cafile: File object containing one or more PEM-encoded CA certificates concatenated together. """ m2.ssl_ctx_set_client_CA_list_from_file(self.ctx, cafile) @@ -143,13 +143,16 @@ class Context: These CA certs are used during verification of the peer's certificate. - @param cafile: File containing one or more PEM-encoded CA + :param cafile: File containing one or more PEM-encoded CA certificates concatenated together. - @param capath: Directory containing PEM-encoded CA certificates + + :param capath: Directory containing PEM-encoded CA certificates (one certificate per file). - @return 0 if the operation failed because CAfile and CApath are NULL + + :return: 0 if the operation failed because CAfile and CApath are NULL or the processing at one of the locations specified failed. Check the error stack to find out the reason. + 1 The operation succeeded. """ if cafile is None and capath is None: @@ -163,7 +166,7 @@ class Context: # type: (bytes) -> None """Sets the session id for the SSL.Context w/in a session can be reused. - @param id: Sessions are generated within a certain context. When + :param id: Sessions are generated within a certain context. When exporting/importing sessions with i2d_SSL_SESSION/d2i_SSL_SESSION it would be possible, to re-import a session generated from another context @@ -196,6 +199,7 @@ class Context: @return 0 if the operation failed. A missing default location is still treated as a success. No error code is set. + 1 The operation succeeded. """ ret = m2.ssl_ctx_set_default_verify_paths(self.ctx) @@ -207,7 +211,7 @@ class Context: """Set the context to accept/reject a peer certificate if the certificate's CA is unknown. - @param ok: True to accept, False to reject. + :param ok: True to accept, False to reject. """ self.allow_unknown_ca = ok @@ -226,12 +230,12 @@ class Context: Set verify options. Most applications will need to call this method with the right options to make a secure SSL connection. - @param mode: The verification mode to use. Typically at least + :param mode: The verification mode to use. Typically at least SSL.verify_peer is used. Clients would also typically add SSL.verify_fail_if_no_peer_cert. - @param depth: The maximum allowed depth of the certificate chain + :param depth: The maximum allowed depth of the certificate chain returned by the peer. - @param callback: Callable that can be used to specify custom + :param callback: Callable that can be used to specify custom verification checks. """ if callback is None: @@ -253,7 +257,7 @@ class Context: # type: (AnyStr) -> int """Load ephemeral DH parameters into the context. - @param dhpfile: Filename of the file containing the PEM-encoded + :param dhpfile: Filename of the file containing the PEM-encoded DH parameters. """ f = BIO.openfile(dhpfile) @@ -264,7 +268,7 @@ class Context: # type: (Optional[Callable]) -> None """Sets the callback function for SSL.Context. - @param callback: Callable to be used when a DH parameters are required. + :param callback: Callable to be used when a DH parameters are required. """ if callback is not None: m2.ssl_ctx_set_tmp_dh_callback(self.ctx, callback) @@ -273,7 +277,7 @@ class Context: # type: (RSA.RSA) -> int """Load ephemeral RSA key into the context. - @param rsa: RSA.RSA instance. + :param rsa: RSA.RSA instance. """ if isinstance(rsa, RSA.RSA): return m2.ssl_ctx_set_tmp_rsa(self.ctx, rsa.rsa) @@ -295,7 +299,7 @@ class Context: It can be used to get state information about the SSL connections that are created from this context. - @param callback: Callback function. The default prints + :param callback: Callback function. The default prints information to stderr. """ m2.ssl_ctx_set_info_callback(self.ctx, callback) @@ -304,9 +308,9 @@ class Context: # type: (str) -> int """Sets the list of available ciphers. - @param cipher_list: The format of the string is described in + :param cipher_list: The format of the string is described in ciphers(1). - @return: 1 if any cipher could be selected and 0 on complete + :return: 1 if any cipher could be selected and 0 on complete failure. """ return m2.ssl_ctx_set_cipher_list(self.ctx, cipher_list) @@ -315,10 +319,11 @@ class Context: # type: (Session) -> int """Add the session to the context. - @param session: the session to be added. + :param session: the session to be added. - @return: 0 The operation failed. It was tried to add the same + :return: 0 The operation failed. It was tried to add the same (identical) session twice. + 1 The operation succeeded. """ return m2.ssl_ctx_add_session(self.ctx, session._ptr()) @@ -327,10 +332,11 @@ class Context: # type: (Session) -> int """Remove the session from the context. - @param session: the session to be removed. + :param session: the session to be removed. - @return: 0 The operation failed. The session was not found in + :return: 0 The operation failed. The session was not found in the cache. + 1 The operation succeeded. """ return m2.ssl_ctx_remove_session(self.ctx, session._ptr()) @@ -362,7 +368,7 @@ class Context: SSL_CTX_set_timeout() returns the previously set timeout value. - @return: the currently set timeout value. + :return: the currently set timeout value. """ return m2.ssl_ctx_get_session_timeout(self.ctx) @@ -373,8 +379,9 @@ class Context: See self.get_session_timeout() for explanation of the session timeouts. - @param timeout: new timeout value. - @return: the previously set timeout value. + :param timeout: new timeout value. + + :return: the previously set timeout value. """ return m2.ssl_ctx_set_session_timeout(self.ctx, timeout) @@ -384,8 +391,9 @@ class Context: The mode is set by using m2.SSL_SESS_CACHE_* constants. - @param mode: new mode value. - @return: the previously set cache mode value. + :param mode: new mode value. + + :return: the previously set cache mode value. """ return m2.ssl_ctx_set_session_cache_mode(self.ctx, mode) @@ -395,7 +403,7 @@ class Context: The mode is set to m2.SSL_SESS_CACHE_* constants. - @return: the previously set cache mode value. + :return: the previously set cache mode value. """ return m2.ssl_ctx_get_session_cache_mode(self.ctx) @@ -420,10 +428,10 @@ class Context: do not affect already created SSL objects. SSL.clear() does not affect the settings. - @param op: bitmask of additional options specified in - SSL_CTX_set_options(3) manpage. + :param op: bitmask of additional options specified in + SSL_CTX_set_options(3) manpage. - @return: the new options bitmask after adding options. + :return: the new options bitmask after adding options. """ return m2.ssl_ctx_set_options(self.ctx, op) @@ -432,7 +440,7 @@ class Context: """ Get the certificate store associated with this context. - @warning: The store is NOT refcounted, and as such can not be relied - to be valid once the context goes away or is changed. + :warning: The store is NOT refcounted, and as such can not be relied + to be valid once the context goes away or is changed. """ return X509.X509_Store(m2.ssl_ctx_get_cert_store(self.ctx)) diff --git a/M2Crypto/SSL/TwistedProtocolWrapper.py b/M2Crypto/SSL/TwistedProtocolWrapper.py index ab4fea4..39a96cc 100644 --- a/M2Crypto/SSL/TwistedProtocolWrapper.py +++ b/M2Crypto/SSL/TwistedProtocolWrapper.py @@ -166,14 +166,14 @@ class TLSProtocolWrapper(ProtocolWrapper): def __init__(self, factory, wrappedProtocol, startPassThrough, client, contextFactory, postConnectionCheck): """ - @param factory: - @param wrappedProtocol: - @param startPassThrough: If true we won't encrypt at all. Need to + :param factory: + :param wrappedProtocol: + :param startPassThrough: If true we won't encrypt at all. Need to call startTLS() later to switch to SSL/TLS. - @param client: True if this should be a client protocol. - @param contextFactory: Factory that creates SSL.Context objects. + :param client: True if this should be a client protocol. + :param contextFactory: Factory that creates SSL.Context objects. The called function is getContext(). - @param postConnectionCheck: The post connection check callback that + :param postConnectionCheck: The post connection check callback that will be called just after connection has been established but before any real data has been exchanged. The first argument to diff --git a/M2Crypto/X509.py b/M2Crypto/X509.py index 74a2819..917a78d 100644 --- a/M2Crypto/X509.py +++ b/M2Crypto/X509.py @@ -84,10 +84,10 @@ class X509_Extension: # noqa Mark this extension critical or noncritical. By default an extension is not critical. - @param critical: Nonzero sets this extension as critical. + :param critical: Nonzero sets this extension as critical. Calling this method without arguments will set this extension to critical. - @return: 1 for success, 0 for failure + :return: 1 for success, 0 for failure """ return m2.x509_extension_set_critical(self.x509_ext, critical) @@ -96,7 +96,7 @@ class X509_Extension: # noqa """ Return whether or not this is a critical extension. - @return: Nonzero if this is a critical extension. + :return: Nonzero if this is a critical extension. """ return m2.x509_extension_get_critical(self.x509_ext) @@ -112,8 +112,8 @@ class X509_Extension: # noqa """ Get the extension value, for example 'DNS:www.example.com'. - @param flag: Flag to control what and how to print. - @param indent: How many spaces to print before actual value. + :param flag: Flag to control what and how to print. + :param indent: How many spaces to print before actual value. """ buf = BIO.MemoryBuffer() m2.x509_ext_print(buf.bio_ptr(), self.x509_ext, flag, indent) @@ -124,11 +124,12 @@ class X509_Extension_Stack: # noqa """ X509 Extension Stack - @warning: Do not modify the underlying OpenSSL stack - except through this interface, or use any OpenSSL functions that do so - indirectly. Doing so will get the OpenSSL stack and the internal pystack - of this class out of sync, leading to python memory leaks, exceptions - or even python crashes! + :warning: Do not modify the underlying OpenSSL stack + except through this interface, or use any OpenSSL + functions that do so indirectly. Doing so will get the + OpenSSL stack and the internal pystack of this class out + of sync, leading to python memory leaks, exceptions or + even python crashes! """ m2_sk_x509_extension_free = m2.sk_x509_extension_free @@ -175,8 +176,8 @@ class X509_Extension_Stack: # noqa """ Push X509_Extension object onto the stack. - @param x509_ext: X509_Extension object to be pushed onto the stack. - @return: The number of extensions on the stack. + :param x509_ext: X509_Extension object to be pushed onto the stack. + :return: The number of extensions on the stack. """ self.pystack.append(x509_ext) ret = m2.sk_x509_extension_push(self.stack, x509_ext._ptr()) @@ -188,7 +189,7 @@ class X509_Extension_Stack: # noqa """ Pop X509_Extension object from the stack. - @return: X509_Extension popped + :return: X509_Extension popped """ x509_ext_ptr = m2.sk_x509_extension_pop(self.stack) if x509_ext_ptr is None: @@ -207,8 +208,8 @@ class X509_Name_Entry: # noqa def __init__(self, x509_name_entry, _pyfree=0): # type: (bytes, int) -> None """ - @param x509_name_entry: this should be OpenSSL X509_NAME_ENTRY binary - @param _pyfree: + :param x509_name_entry: this should be OpenSSL X509_NAME_ENTRY binary + :param _pyfree: """ self.x509_name_entry = x509_name_entry self._pyfree = _pyfree @@ -227,8 +228,8 @@ class X509_Name_Entry: # noqa """ Sets the field name to asn1obj - @param asn1obj: - @return: 0 on failure, 1 on success + :param asn1obj: + :return: 0 on failure, 1 on success """ return m2.x509_name_entry_set_object(self.x509_name_entry, asn1obj._ptr()) @@ -238,8 +239,8 @@ class X509_Name_Entry: # noqa """ Sets the field name to asn1obj - @param data: data in a binary form to be set - @return: 0 on failure, 1 on success + :param data: data in a binary form to be set + :return: 0 on failure, 1 on success """ return m2.x509_name_entry_set_data(self.x509_name_entry, type, util.py3bytes(data)) @@ -290,8 +291,8 @@ class X509_Name: # noqa def __init__(self, x509_name=None, _pyfree=0): # type: (bytes, int) -> None """ - @param x509_name: this should be OpenSSL X509_NAME binary - @param _pyfree: + :param x509_name: this should be OpenSSL X509_NAME binary + :param _pyfree: """ if x509_name is not None: assert m2.x509_name_type_check(x509_name), "'x509_name' type error" @@ -327,7 +328,7 @@ class X509_Name: # noqa def __setattr__(self, attr, value): # type: (str, AnyStr) -> int """ - @return: 1 for success of 0 if an error occurred. + :return: 1 for success of 0 if an error occurred. """ if attr in self.nid: assert m2.x509_name_type_check(self.x509_name), \ @@ -361,11 +362,11 @@ class X509_Name: # noqa """ Add X509_Name field whose name is identified by its name. - @param field: name of the entry - @param type: use MBSTRING_ASC or MBSTRING_UTF8 + :param field: name of the entry + :param type: use MBSTRING_ASC or MBSTRING_UTF8 (or standard ASN1 type like V_ASN1_IA5STRING) - @param entry: value - @param len: buf_len of the entry + :param entry: value + :param len: buf_len of the entry (-1 and the length is computed automagically) The ``loc`` and ``set`` parameters determine where a new entry @@ -374,16 +375,16 @@ class X509_Name: # noqa This adds a new entry to the end of name as a single valued RelativeDistinguishedName (RDN). - @param loc: determines the index where the new entry is + :param loc: determines the index where the new entry is inserted: if it is -1 it is appended. - @param set: determines how the new type is added. If it is zero + :param set: determines how the new type is added. If it is zero a new RDN is created. If set is -1 or 1 it is added to the previous or next RDN structure respectively. This will then be a multivalued RDN: since multivalues RDNs are very seldom used set is almost always set to zero. - @return: 1 for success of 0 if an error occurred. + :return: 1 for success of 0 if an error occurred. """ return m2.x509_name_add_entry_by_txt(self.x509_name, util.py3bytes(field), type, @@ -398,9 +399,9 @@ class X509_Name: # noqa """ Retrieve the next index matching nid. - @param nid: name of the entry (as m2.NID* constants) + :param nid: name of the entry (as m2.NID* constants) - @return: list of X509_Name_Entry items + :return: list of X509_Name_Entry items """ ret = [] lastpos = -1 @@ -420,9 +421,9 @@ class X509_Name: # noqa """ as_text returns the name as a string. - @param indent: Each line in multiline format is indented + :param indent: Each line in multiline format is indented by this many spaces. - @param flags: Flags that control how the output should be formatted. + :param flags: Flags that control how the output should be formatted. """ assert m2.x509_name_type_check(self.x509_name), \ "'x509_name' type error" @@ -453,9 +454,9 @@ class X509: def __init__(self, x509=None, _pyfree=0): # type: (Optional[bytes], int) -> None """ - @param x509: binary representation of + :param x509: binary representation of the underlying OpenSSL X509 object. - @param _pyfree: + :param _pyfree: """ if x509 is not None: assert m2.x509_type_check(x509), "'x509' type error" @@ -496,8 +497,8 @@ class X509: def save_pem(self, filename): # type: (AnyStr) -> int """ - @param filename: name of the file to be loaded - @return: 1 for success or 0 for failure + :param filename: name of the file to be loaded + :return: 1 for success or 0 for failure """ with BIO.openfile(filename, 'wb') as bio: return m2.x509_write_pem(bio.bio_ptr(), self.x509) @@ -508,11 +509,14 @@ class X509: Saves X.509 certificate to a file. Default output format is PEM. - @param filename: Name of the file the cert will be saved to. - @param format: Controls what output format is used to save the cert. - Either FORMAT_PEM or FORMAT_DER to save in PEM or DER format. - Raises a ValueError if an unknow format is used. - @return: 1 for success or 0 for failure + :param filename: Name of the file the cert will be saved to. + + :param format: Controls what output format is used to save the cert. + Either FORMAT_PEM or FORMAT_DER to save in PEM or + DER format. Raises a ValueError if an unknow + format is used. + + :return: 1 for success or 0 for failure """ with BIO.openfile(filename, 'wb') as bio: if format == FORMAT_PEM: @@ -528,8 +532,8 @@ class X509: """ Set version of the certificate. - @param version: Version number. - @return: Returns 0 on failure. + :param version: Version number. + :return: Returns 0 on failure. """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_version(self.x509, version) @@ -537,7 +541,7 @@ class X509: def set_not_before(self, asn1_time): # type: (ASN1.ASN1_TIME) -> int """ - @return: 1 on success, 0 on failure + :return: 1 on success, 0 on failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_not_before(self.x509, asn1_time._ptr()) @@ -545,7 +549,7 @@ class X509: def set_not_after(self, asn1_time): # type: (ASN1.ASN1_TIME) -> int """ - @return: 1 on success, 0 on failure + :return: 1 on success, 0 on failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_not_after(self.x509, asn1_time._ptr()) @@ -553,7 +557,7 @@ class X509: def set_subject_name(self, name): # type: (X509_Name) -> int """ - @return: 1 on success, 0 on failure + :return: 1 on success, 0 on failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_subject_name(self.x509, name.x509_name) @@ -561,7 +565,7 @@ class X509: def set_issuer_name(self, name): # type: (X509_Name) -> int """ - @return: 1 on success, 0 on failure + :return: 1 on success, 0 on failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_issuer_name(self.x509, name.x509_name) @@ -582,8 +586,9 @@ class X509: """ Set serial number. - @param serial: Serial number. - @return 1 for success and 0 for failure. + :param serial: Serial number. + + :return 1 for success and 0 for failure. """ assert m2.x509_type_check(self.x509), "'x509' type error" # This "magically" changes serial since asn1_integer @@ -621,8 +626,9 @@ class X509: """ Set the public key for the certificate - @param pkey: Public key - @return 1 for success and 0 for failure + :param pkey: Public key + + :return 1 for success and 0 for failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_pubkey(self.x509, pkey.pkey) @@ -637,8 +643,9 @@ class X509: """ Set issuer name. - @param name: subjectName field. - @return 1 for success and 0 for failure + :param name: subjectName field. + + :return 1 for success and 0 for failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_issuer_name(self.x509, name.x509_name) @@ -653,8 +660,9 @@ class X509: """ Set subject name. - @param name: subjectName field. - @return 1 for success and 0 for failure + :param name: subjectName field. + + :return 1 for success and 0 for failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_set_subject_name(self.x509, name.x509_name) @@ -664,8 +672,9 @@ class X509: """ Add X509 extension to this certificate. - @param ext: Extension - @return 1 for success and 0 for failure + :param ext: Extension + + :return 1 for success and 0 for failure """ assert m2.x509_type_check(self.x509), "'x509' type error" return m2.x509_add_ext(self.x509, ext.x509_ext, -1) @@ -675,8 +684,9 @@ class X509: """ Get X509 extension by name. - @param name: Name of the extension - @return: X509_Extension + :param name: Name of the extension + + :return: X509_Extension """ # Optimizations to reduce attribute accesses m2x509_get_ext = m2.x509_get_ext @@ -696,8 +706,9 @@ class X509: """ Get X509 extension by index. - @param index: Name of the extension - @return: X509_Extension + :param index: Name of the extension + + :return: X509_Extension """ if index < 0 or index >= self.get_ext_count(): raise IndexError @@ -717,10 +728,12 @@ class X509: """ Sign the certificate. - @param pkey: Public key - @param md: Message digest algorithm to use for signing, + :param pkey: Public key + + :param md: Message digest algorithm to use for signing, for example 'sha1'. - @return int + + :return int """ assert m2.x509_type_check(self.x509), "'x509' type error" mda = getattr(m2, md, None) @@ -741,9 +754,9 @@ class X509: """ Check if the certificate is a Certificate Authority (CA) certificate. - @return: 0 if the certificate is not CA, nonzero otherwise. + :return: 0 if the certificate is not CA, nonzero otherwise. - @requires: OpenSSL 0.9.8 or newer + :requires: OpenSSL 0.9.8 or newer """ return m2.x509_check_ca(self.x509) @@ -752,9 +765,11 @@ class X509: """ Check if the certificate's purpose matches the asked purpose. - @param id: Purpose id. See X509_PURPOSE_* constants. - @param ca: 1 if the certificate should be CA, 0 otherwise. - @return: 0 if the certificate purpose does not match, nonzero + :param id: Purpose id. See X509_PURPOSE_* constants. + + :param ca: 1 if the certificate should be CA, 0 otherwise. + + :return: 0 if the certificate purpose does not match, nonzero otherwise. """ return m2.x509_check_purpose(self.x509, id, ca) @@ -764,8 +779,9 @@ class X509: """ Get the fingerprint of the certificate. - @param md: Message digest algorithm to use. - @return: String containing the fingerprint in hex format. + :param md: Message digest algorithm to use. + + :return: String containing the fingerprint in hex format. """ der = self.as_der() md = EVP.MessageDigest(md) @@ -779,12 +795,13 @@ def load_cert(file, format=FORMAT_PEM): """ Load certificate from file. - @param file: Name of file containing certificate in either DER or + :param file: Name of file containing certificate in either DER or PEM format. - @param format: Describes the format of the file to be loaded, + + :param format: Describes the format of the file to be loaded, either PEM or DER. - @return: M2Crypto.X509.X509 object. + :return: M2Crypto.X509.X509 object. """ with BIO.openfile(file) as bio: if format == FORMAT_PEM: @@ -804,12 +821,13 @@ def load_cert_bio(bio, format=FORMAT_PEM): """ Load certificate from a bio. - @param bio: BIO pointing at a certificate in either DER or PEM format. - @param format: Describes the format of the cert to be loaded, + :param bio: BIO pointing at a certificate in either DER or PEM format. + + :param format: Describes the format of the cert to be loaded, either PEM or DER (via constants FORMAT_PEM and FORMAT_FORMAT_DER) - @return: M2Crypto.X509.X509 object. + :return: M2Crypto.X509.X509 object. """ if format == FORMAT_PEM: cptr = m2.x509_read_pem(bio._ptr()) @@ -828,11 +846,13 @@ def load_cert_string(string, format=FORMAT_PEM): """ Load certificate from a string. - @param string: String containing a certificate in either DER or PEM format. - @param format: Describes the format of the cert to be loaded, + :param string: String containing a certificate in either DER or PEM format. + + :param format: Describes the format of the cert to be loaded, either PEM or DER (via constants FORMAT_PEM and FORMAT_FORMAT_DER) - @return: M2Crypto.X509.X509 object. + + :return: M2Crypto.X509.X509 object. """ string = util.py3bytes(string) bio = BIO.MemoryBuffer(string) @@ -844,8 +864,9 @@ def load_cert_der_string(string): """ Load certificate from a string. - @param string: String containing a certificate in DER format. - @return: M2Crypto.X509.X509 object. + :param string: String containing a certificate in DER format. + + :return: M2Crypto.X509.X509 object. """ string = util.py3bytes(string) bio = BIO.MemoryBuffer(string) @@ -866,7 +887,7 @@ class X509_Store_Context: # noqa # type: (bytes, int) -> None """ - @param x509_store_ctx: binary data for + :param x509_store_ctx: binary data for OpenSSL X509_STORE_CTX type """ self.ctx = x509_store_ctx @@ -888,8 +909,9 @@ class X509_Store_Context: # noqa """ Get current X.509 certificate. - @warning: The returned certificate is NOT refcounted, so you can not - rely on it being valid once the store context goes away or is modified. + :warning: The returned certificate is NOT refcounted, so you can not + rely on it being valid once the store context goes + away or is modified. """ return X509(m2.x509_store_ctx_get_current_cert(self.ctx), _pyfree=0) @@ -912,7 +934,7 @@ class X509_Store_Context: # noqa """ Get certificate chain. - @return: Reference counted (i.e. safe to use even after the store + :return: Reference counted (i.e. safe to use even after the store context goes away) stack of certificates in the chain. """ return X509_Stack(m2.x509_store_ctx_get1_chain(self.ctx), 1, 1) @@ -928,7 +950,7 @@ class X509_Store: # noqa def __init__(self, store=None, _pyfree=0): # type: (Optional[bytes], int) -> None """ - @param store: binary data for OpenSSL X509_STORE_CTX type. + :param store: binary data for OpenSSL X509_STORE_CTX type. """ if store is not None: self.store = store @@ -948,8 +970,9 @@ class X509_Store: # noqa def load_info(self, file): # type: (AnyStr) -> int """ - @param file: filename - @return: 1 on success, 0 on failure + :param file: filename + + :return: 1 on success, 0 on failure """ ret = m2.x509_store_load_locations(self.store, file) if ret < 1: @@ -963,23 +986,25 @@ class X509_Store: # noqa assert isinstance(x509, X509) return m2.x509_store_add_cert(self.store, x509._ptr()) - def set_verify_cb(self, callback=None): # type: (Optional[callable]) -> None """ Set callback which will be called when the store is verified. Wrapper over OpenSSL X509_STORE_set_verify_cb(). - @param callback: Callable to specify verification options. + :param callback: Callable to specify verification options. Type of the callable must be: (int, X509_Store_Context) -> int. If None: set the standard options. - @note compile-time or run-time errors in the callback would result + + :note: compile-time or run-time errors in the callback would result in mysterious errors during verification, which could be hard to trace. - @note Python exceptions raised in callbacks do not propagate to + + :note: Python exceptions raised in callbacks do not propagate to verify() call. - @return: None + + :return: None """ if callback is None: return self.set_verify_cb(x509_store_default_cb) @@ -995,11 +1020,12 @@ class X509_Stack: # noqa """ X509 Stack - @warning: Do not modify the underlying OpenSSL stack - except through this interface, or use any OpenSSL functions that do so - indirectly. Doing so will get the OpenSSL stack and the internal pystack - of this class out of sync, leading to python memory leaks, exceptions - or even python crashes! + :warning: Do not modify the underlying OpenSSL stack + except through this interface, or use any OpenSSL + functions that do so indirectly. Doing so will get the + OpenSSL stack and the internal pystack of this class out + of sync, leading to python memory leaks, exceptions or + even python crashes! """ m2_sk_x509_free = m2.sk_x509_free @@ -1044,8 +1070,9 @@ class X509_Stack: # noqa """ push an X509 certificate onto the stack. - @param x509: X509 object. - @return: The number of X509 objects currently on the stack. + :param x509: X509 object. + + :return: The number of X509 objects currently on the stack. """ assert isinstance(x509, X509) self.pystack.append(x509) @@ -1058,8 +1085,8 @@ class X509_Stack: # noqa """ pop a certificate from the stack. - @return: X509 object that was popped, or None if there is nothing - to pop. + :return: X509 object that was popped, or None if there is + nothing to pop. """ x509_ptr = m2.sk_x509_pop(self.stack) if x509_ptr is None: @@ -1080,7 +1107,7 @@ def new_stack_from_der(der_string): """ Create a new X509_Stack from DER string. - @return: X509_Stack + :return: X509_Stack """ der_string = util.py3bytes(der_string) stack_ptr = m2.make_stack_from_der_sequence(der_string) @@ -1140,11 +1167,14 @@ class Request: Saves X.509 certificate request to a file. Default output format is PEM. - @param filename: Name of the file the request will be saved to. - @param format: Controls what output format is used to save the request. - Either FORMAT_PEM or FORMAT_DER to save in PEM or DER format. - Raises ValueError if an unknown format is used. - @return: 1 for success, 0 for failure. + :param filename: Name of the file the request will be saved to. + + :param format: Controls what output format is used to save the + request. Either FORMAT_PEM or FORMAT_DER to save + in PEM or DER format. Raises ValueError if an + unknown format is used. + + :return: 1 for success, 0 for failure. The error code can be obtained by ERR_get_error. """ with BIO.openfile(filename, 'wb') as bio: @@ -1161,7 +1191,7 @@ class Request: """ Get the public key for the request. - @return: Public key from the request. + :return: Public key from the request. """ return EVP.PKey(m2.x509_req_get_pubkey(self.req), _pyfree=1) @@ -1170,9 +1200,9 @@ class Request: """ Set the public key for the request. - @param pkey: Public key + :param pkey: Public key - @return: Return 1 for success and 0 for failure. + :return: Return 1 for success and 0 for failure. """ return m2.x509_req_set_pubkey(self.req, pkey.pkey) @@ -1181,7 +1211,7 @@ class Request: """ Get version. - @return: Returns version. + :return: Returns version. """ return m2.x509_req_get_version(self.req) @@ -1190,8 +1220,8 @@ class Request: """ Set version. - @param version: Version number. - @return: Returns 0 on failure. + :param version: Version number. + :return: Returns 0 on failure. """ return m2.x509_req_set_version(self.req, version) @@ -1204,8 +1234,8 @@ class Request: """ Set subject name. - @param name: subjectName field. - @return: 1 for success and 0 for failure + :param name: subjectName field. + :return: 1 for success and 0 for failure """ return m2.x509_req_set_subject_name(self.req, name.x509_name) @@ -1216,8 +1246,8 @@ class Request: """ Add X509 extensions to this request. - @param ext_stack: Stack of extensions to add. - @return: 1 for success and 0 for failure + :param ext_stack: Stack of extensions to add. + :return: 1 for success and 0 for failure """ return m2.x509_req_add_extensions(self.req, ext_stack._ptr()) @@ -1225,8 +1255,8 @@ class Request: # type: (EVP.PKey) -> int """ - @param pkey: PKey to be verified - @return: 1 for success and 0 for failure + :param pkey: PKey to be verified + :return: 1 for success and 0 for failure """ return m2.x509_req_verify(self.req, pkey.pkey) @@ -1234,9 +1264,9 @@ class Request: # type: (EVP.PKey, str) -> int """ - @param pkey: PKey to be signed - @param md: used algorigthm - @return: 1 for success and 0 for failure + :param pkey: PKey to be signed + :param md: used algorigthm + :return: 1 for success and 0 for failure """ mda = getattr(m2, md, None) if mda is None: @@ -1249,12 +1279,12 @@ def load_request(file, format=FORMAT_PEM): """ Load certificate request from file. - @param file: Name of file containing certificate request in + :param file: Name of file containing certificate request in either PEM or DER format. - @param format: Describes the format of the file to be loaded, + :param format: Describes the format of the file to be loaded, either PEM or DER. (using constants FORMAT_PEM and FORMAT_DER) - @return: Request object. + :return: Request object. """ with BIO.openfile(file) as f: if format == FORMAT_PEM: @@ -1275,12 +1305,12 @@ def load_request_bio(bio, format=FORMAT_PEM): """ Load certificate request from a bio. - @param bio: BIO pointing at a certificate request in + :param bio: BIO pointing at a certificate request in either DER or PEM format. - @param format: Describes the format of the request to be loaded, + :param format: Describes the format of the request to be loaded, either PEM or DER. (using constants FORMAT_PEM and FORMAT_DER) - @return: M2Crypto.X509.Request object. + :return: M2Crypto.X509.Request object. """ if format == FORMAT_PEM: cptr = m2.x509_req_read_pem(bio._ptr()) @@ -1299,13 +1329,13 @@ def load_request_string(string, format=FORMAT_PEM): """ Load certificate request from a string. - @param string: String containing a certificate request in + :param string: String containing a certificate request in either DER or PEM format. - @param format: Describes the format of the request to be loaded, + :param format: Describes the format of the request to be loaded, either PEM or DER. (using constants FORMAT_PEM and FORMAT_DER) - @return: M2Crypto.X509.Request object. + :return: M2Crypto.X509.Request object. """ string = util.py3bytes(string) bio = BIO.MemoryBuffer(string) @@ -1317,8 +1347,8 @@ def load_request_der_string(string): """ Load certificate request from a string. - @param string: String containing a certificate request in DER format. - @return: M2Crypto.X509.Request object. + :param string: String containing a certificate request in DER format. + :return: M2Crypto.X509.Request object. """ string = util.py3bytes(string) bio = BIO.MemoryBuffer(string) @@ -1336,7 +1366,7 @@ class CRL: # type: (Optional[bytes], int) -> None """ - @param crl: binary representation of + :param crl: binary representation of the underlying OpenSSL X509_CRL object. """ if crl is not None: @@ -1356,7 +1386,7 @@ class CRL: """ Return CRL in PEM format in a string. - @return: String containing the CRL in PEM format. + :return: String containing the CRL in PEM format. """ buf = BIO.MemoryBuffer() m2.x509_crl_print(buf.bio_ptr(), self.crl) @@ -1368,9 +1398,9 @@ def load_crl(file): """ Load CRL from file. - @param file: Name of file containing CRL in PEM format. + :param file: Name of file containing CRL in PEM format. - @return: M2Crypto.X509.CRL object. + :return: M2Crypto.X509.CRL object. """ with BIO.openfile(file) as f: cptr = m2.x509_crl_read_pem(f.bio_ptr()) diff --git a/M2Crypto/httpslib.py b/M2Crypto/httpslib.py index f1df5db..fb22daf 100644 --- a/M2Crypto/httpslib.py +++ b/M2Crypto/httpslib.py @@ -30,12 +30,12 @@ class HTTPSConnection(HTTPConnection): Represents one transaction with an HTTP server over the SSL connection. - @param host: host name - @param port: port number - @param strict: if switched on, it raises BadStatusLine to be + :param host: host name + :param port: port number + :param strict: if switched on, it raises BadStatusLine to be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1 status line. - @param ssl: dict with all remaining named real parameters of the + :param ssl: dict with all remaining named real parameters of the function. Specifically, ``ssl_context`` is expected to be included with SSL.Context; if it is not default ``'sslv23'`` is substituted). @@ -133,20 +133,20 @@ class ProxyHTTPSConnection(HTTPSConnection): """ Create the ProxyHTTPSConnection object. - @param host: host name of the proxy server - @param port: port number of the proxy server - @param strict: if switched on, it raises BadStatusLine to be + :param host: host name of the proxy server + :param port: port number of the proxy server + :param strict: if switched on, it raises BadStatusLine to be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1 status line. - @param username: username on the proxy server, when required + :param username: username on the proxy server, when required Username can be ``str``, but preferred type is ``bytes``. M2Crypto does some conversion to ``bytes`` when necessary, but it's better when the user of the library does it on its own. - @param password: password on the proxy server, when required + :param password: password on the proxy server, when required The same as with ``username``, ``str`` is accepted, but ``bytes`` are preferred. - @param ssl: dict with all remaining named real parameters of the + :param ssl: dict with all remaining named real parameters of the function. Specifically, ``ssl_context`` is expected to be included with SSL.Context; if it is not default ``'sslv23'`` is substituted). diff --git a/M2Crypto/m2urllib.py b/M2Crypto/m2urllib.py index 6a69bac..eed70e5 100644 --- a/M2Crypto/m2urllib.py +++ b/M2Crypto/m2urllib.py @@ -28,10 +28,10 @@ def open_https(self, url, data=None, ssl_context=None): """ Open URL over the SSL connection. - @param url: URL to be opened - @param data: data for the POST request - @param ssl_context: SSL.Context to be used - @return: + :param url: URL to be opened + :param data: data for the POST request + :param ssl_context: SSL.Context to be used + :return: """ if ssl_context is not None and isinstance(ssl_context, SSL.Context): self.ctx = ssl_context diff --git a/M2Crypto/m2urllib2.py b/M2Crypto/m2urllib2.py index afc12c0..ac58619 100644 --- a/M2Crypto/m2urllib2.py +++ b/M2Crypto/m2urllib2.py @@ -70,8 +70,11 @@ class HTTPSHandler(AbstractHTTPHandler): http_class must implement the HTTPConnection API from httplib. The addinfourl return value is a file-like object. It also has methods and attributes including: + - info(): return a mimetools.Message object for the headers + - geturl(): return the original request URL + - code: HTTP status code """ # https://docs.python.org/3.3/library/urllib.request.html#urllib.request.Request.get_host diff --git a/doc/M2Crypto.rst b/doc/M2Crypto.rst index b5f4c61..31a03ad 100644 --- a/doc/M2Crypto.rst +++ b/doc/M2Crypto.rst @@ -193,14 +193,6 @@ M2Crypto Package :undoc-members: :show-inheritance: -:mod:`six` Module ------------------ - -.. automodule:: M2Crypto.six - :members: - :undoc-members: - :show-inheritance: - :mod:`threading` Module ----------------------- diff --git a/doc/ZServerSSL-HOWTO.rst b/doc/ZServerSSL-HOWTO.rst index d09426d..91ef5af 100644 --- a/doc/ZServerSSL-HOWTO.rst +++ b/doc/ZServerSSL-HOWTO.rst @@ -1,3 +1,5 @@ +:orphan: + .. _zserverssl-howto: ZServerSSL-HOWTO diff --git a/doc/conf.py b/doc/conf.py index f5b7dff..d782515 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -91,7 +91,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +# html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/doc/howto.ca.rst b/doc/howto.ca.rst index 3c6b460..e950b59 100644 --- a/doc/howto.ca.rst +++ b/doc/howto.ca.rst @@ -1,3 +1,5 @@ +:orphan: + .. _howto-ca: HOWTO: Creating your own CA with OpenSSL diff --git a/doc/howto.smime.rst b/doc/howto.smime.rst index dfd7abf..715e7c4 100644 --- a/doc/howto.smime.rst +++ b/doc/howto.smime.rst @@ -1,3 +1,5 @@ +:orphan: + .. _howto-smime: HOWTO: Programming S/MIME in Python with M2Crypto diff --git a/doc/howto.ssl.rst b/doc/howto.ssl.rst index ab9b17d..7f3278c 100644 --- a/doc/howto.ssl.rst +++ b/doc/howto.ssl.rst @@ -1,3 +1,5 @@ +:orphan: + .. _howto-ssl: HOWTO: Programming SSL in Python with M2Crypto @@ -48,9 +48,9 @@ def openssl_version(req_ver, required=False): """ Compare version of the installed OpenSSL with the maximum required version. - @param req_ver: required version as a str (e.g., '1.0.1') - @param required: whether we want bigger-or-equal or less-or-equal - @return: Boolean indicating whether the satisfying version of + :param req_ver: required version as a str (e.g., '1.0.1') + :param required: whether we want bigger-or-equal or less-or-equal + :return: Boolean indicating whether the satisfying version of OpenSSL has been installed. """ ver_str = None @@ -209,8 +209,8 @@ def swig_version(req_ver): """ Compare version of the swig with the required version - @param req_ver: required version as a str (e.g., '2.0.4') - @return: Boolean indicating whether the satisfying version of swig + :param req_ver: required version as a str (e.g., '2.0.4') + :return: Boolean indicating whether the satisfying version of swig has been installed. """ ver_str = None |