remove / fix comments, add comment about openssl version

borg/crypto.pyx

@@ -1,4 +1,7 @@
-"""An AEAD style OpenSSL wrapper"""
+"""An AEAD style OpenSSL wrapper
+
+Note: AES-GCM mode needs OpenSSL >= 1.0.1d due to bug fixes in OpenSSL.
+"""
 
 from libc.stdlib cimport malloc, free
 from cpython.buffer cimport PyBUF_SIMPLE, PyObject_GetBuffer, PyBuffer_Release
@@ -219,9 +222,6 @@ cdef class AES256_CTR_HMAC_SHA256:
             offset += olen
             rc = EVP_DecryptFinal_ex(&self.ctx, odata+offset, &olen)
             if rc <= 0:
-                # this error check is very important for modes with padding or
-                # authentication. for them, a failure here means corrupted data.
-                # CTR mode does not use padding nor authentication.
                 raise Exception('EVP_DecryptFinal_ex failed')
             offset += olen
             return odata[:offset]
@@ -294,7 +294,6 @@ cdef class AES256_GCM:
             rc = EVP_EncryptInit_ex(&self.ctx, EVP_aes_256_gcm(), NULL, NULL, NULL)
             if not rc:
                 raise Exception('EVP_EncryptInit_ex failed')
-            # Set IV length (bytes)
             if not EVP_CIPHER_CTX_ctrl(&self.ctx, EVP_CTRL_GCM_SET_IVLEN, 12, NULL):
                 raise Exception('EVP_CIPHER_CTX_ctrl SET IVLEN failed')
             rc = EVP_EncryptInit_ex(&self.ctx, NULL, NULL, self.enc_key, self.iv)
@@ -339,12 +338,10 @@ cdef class AES256_GCM:
                 raise Exception('EVP_DecryptInit_ex failed')
             iv = self.fetch_iv(<unsigned char *> idata.buf+hlen+16)
             self.set_iv(iv)
-            # Set IV length (bytes)
             if not EVP_CIPHER_CTX_ctrl(&self.ctx, EVP_CTRL_GCM_SET_IVLEN, 12, NULL):
                 raise Exception('EVP_CIPHER_CTX_ctrl SET IVLEN failed')
             if not EVP_DecryptInit_ex(&self.ctx, NULL, NULL, self.enc_key, iv):
                 raise Exception('EVP_DecryptInit_ex failed')
-            # Set expected tag (mac) value. Works in OpenSSL 1.0.1d and later.  <-- XXX WAT!?
             if not EVP_CIPHER_CTX_ctrl(&self.ctx, EVP_CTRL_GCM_SET_TAG, 16, <void *> idata.buf+hlen):
                 raise Exception('EVP_CIPHER_CTX_ctrl SET TAG failed')
             rc = EVP_DecryptUpdate(&self.ctx, NULL, &olen, <const unsigned char*> aad, alen)
@@ -359,9 +356,7 @@ cdef class AES256_GCM:
             offset += olen
             rc = EVP_DecryptFinal_ex(&self.ctx, odata+offset, &olen)
             if rc <= 0:
-                # this error check is very important for modes with padding or
-                # authentication. for them, a failure here means corrupted data.
-                # for GCM mode, a failure here means corrupted / tampered tag (mac) or data
+                # a failure here means corrupted or tampered tag (mac) or data.
                 raise Exception('EVP_DecryptFinal_ex failed')
             offset += olen
             return odata[:offset]
@@ -377,9 +372,8 @@ cdef class AES256_GCM:
         assert amount < 16 * 2**32
         # we need 16 bytes for increment_iv:
         last_iv = b'\0\0\0\0' + self.iv[:12]
-        # gcm mode is special: it appends a internal 32bit counter to the 96bit (12 byte) we provide,
-        # thus we only need to increment the 96bit counter by 1 (and we must not encrypt more than 2^32
-        # 16Byte (128bit) blocks with same IV):
+        # gcm mode is special: it appends a internal 32bit counter to the 96bit (12 byte) we provide, thus we only
+        # need to increment the 96bit counter by 1 (and we must not encrypt more than 2^32 AES blocks with same IV):
         next_iv = increment_iv(last_iv, 1)
         return next_iv[-12:]