From b50afa900c03c7d93ee5a1e4ca1df4311e504e50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s=20Guimar=C3=A3es?= Date: Sun, 1 May 2016 12:11:58 -0300 Subject: [PATCH] adds ciphers docstrings --- wolfcrypt/ciphers.py | 60 ++++++++++++++++++++++++++++++++++++++++++-- wolfcrypt/hashes.py | 21 +++++++++------- 2 files changed, 70 insertions(+), 11 deletions(-) diff --git a/wolfcrypt/ciphers.py b/wolfcrypt/ciphers.py index 78efa5c..e933590 100644 --- a/wolfcrypt/ciphers.py +++ b/wolfcrypt/ciphers.py @@ -41,11 +41,17 @@ _FEEDBACK_MODES = [MODE_ECB, MODE_CBC, MODE_CFB, MODE_OFB, MODE_CTR] class _Cipher(object): + """ + A PEP 272 compliant Block Encryption Algorithm. + """ def __init__(self, key, mode, IV=None): if mode not in _FEEDBACK_MODES: raise ValueError("this mode is not supported") - if mode != MODE_CBC: + if mode == MODE_CBC: + if IV is None: + raise ValueError("this mode requires an 'IV' string") + else: raise ValueError("this mode is not supported by this cipher") if self.key_size: @@ -74,11 +80,27 @@ class _Cipher(object): @classmethod def new(cls, key, mode, IV=None, **kwargs): - # PEP 272 -- API for Block Encryption Algorithms + """ + Returns a ciphering object, using the secret key contained in + the string 'key', and using the feedback mode 'mode', which + must be one of MODE_* defined in this module. + + If 'mode' is MODE_CBC or MODE_CFB, 'IV' must be provided and + must be a string of the same length as the block size. Not + providing a value of 'IV' will result in a ValueError exception + being raised. + """ return cls(key, mode, IV) def encrypt(self, string): + """ + Encrypts a non-empty string, using the key-dependent data in + the object, and with the appropriate feedback mode. The + string's length must be an exact multiple of the algorithm's + block size or, in CFB mode, of the segment size. Returns a + string containing the ciphertext. + """ string = t2b(string) if not string or len(string) % self.block_size: @@ -100,6 +122,13 @@ class _Cipher(object): def decrypt(self, string): + """ + Decrypts 'string', using the key-dependent data in the + object and with the appropriate feedback mode. The string's + length must be an exact multiple of the algorithm's block + size or, in CFB mode, of the segment size. Returns a string + containing the plaintext. + """ string = t2b(string) if not string or len(string) % self.block_size: @@ -166,6 +195,8 @@ class Des3(_Cipher): class _Rsa(object): + RSA_MIN_PAD_SIZE = 11 + def __init__(self): self.native_object = _ffi.new("RsaKey *") ret = _lib.wc_InitRsaKey(self.native_object, _ffi.NULL) @@ -199,6 +230,13 @@ class RsaPublic(_Rsa): def encrypt(self, plaintext): + """ + Encrypts plaintext, using the public key data in the + object. The plaintext's length must not be greater than: + self.output_size - self.RSA_MIN_PAD_SIZE + Returns a string containing the ciphertext. + """ + plaintext = t2b(plaintext) ciphertext = t2b("\0" * self.output_size) @@ -214,6 +252,12 @@ class RsaPublic(_Rsa): def verify(self, signature): + """ + Verifies signature, using the public key data in the + object. The signature's length must be equal to: + self.output_size + Returns a string containing the plaintext. + """ signature = t2b(signature) plaintext = t2b("\0" * self.output_size) @@ -246,6 +290,12 @@ class RsaPrivate(RsaPublic): def decrypt(self, ciphertext): + """ + Decrypts ciphertext, using the private key data in the + object. The ciphertext's length must be equal to: + self.output_size + Returns a string containing the plaintext. + """ ciphertext = t2b(ciphertext) plaintext = t2b("\0" * self.output_size) @@ -260,6 +310,12 @@ class RsaPrivate(RsaPublic): def sign(self, plaintext): + """ + Signs plaintext, using the private key data in the object. + The plaintext's length must not be greater than: + self.output_size - self.RSA_MIN_PAD_SIZE + Returns a string containing the signature. + """ plaintext = t2b(plaintext) signature = t2b("\0" * self.output_size) diff --git a/wolfcrypt/hashes.py b/wolfcrypt/hashes.py index 3ed14e1..88481e5 100644 --- a/wolfcrypt/hashes.py +++ b/wolfcrypt/hashes.py @@ -24,6 +24,9 @@ from wolfcrypt.utils import t2b, b2h from wolfcrypt.exceptions import * class _Hash(object): + """ + A PEP 247 compliant Cryptographic Hash Function. + """ def __init__(self, string=None): self._native_object = _ffi.new(self._native_type) ret = self._init() @@ -34,7 +37,7 @@ class _Hash(object): @classmethod def new(cls, string=None): """ - Create a new hashing object and returns it. The optional + Creates a new hashing object and returns it. The optional 'string' parameter, if supplied, will be immediately hashed into the object's starting state, as if obj.update(string) was called. @@ -50,8 +53,8 @@ class _Hash(object): def copy(self): """ - Return a separate copy of this hashing object. An update to - this copy won't affect the original object. + Returns a separate copy of this hashing object. An update + to this copy won't affect the original object. """ copy = self.new("") @@ -64,9 +67,9 @@ class _Hash(object): def update(self, string): """ - Hash 'string' into the current state of the hashing object. - update() can be called any number of times during a hashing - object's lifetime. + Hashes 'string' into the current state of the hashing + object. update() can be called any number of times during + a hashing object's lifetime. """ string = t2b(string) @@ -77,7 +80,7 @@ class _Hash(object): def digest(self): """ - Return the hash value of this hashing object as a string + Returns the hash value of this hashing object as a string containing 8-bit data. The object is not altered in any way by this function; you can continue updating the object after calling this function. @@ -98,7 +101,7 @@ class _Hash(object): def hexdigest(self): """ - Return the hash value of this hashing object as a string + Returns the hash value of this hashing object as a string containing hexadecimal digits. Lowercase letters are used for the digits 'a' through 'f'. Like the .digest() method, this method doesn't alter the object. @@ -205,7 +208,7 @@ class _Hmac(_Hash): @classmethod def new(cls, key, string=None): """ - Create a new hashing object and returns it. 'key' is a + Creates a new hashing object and returns it. 'key' is a required parameter containing a string giving the key to use. The optional 'string' parameter, if supplied, will be immediately hashed into the object's starting state, as