More docs.

cbcmode.mod/cbcmode.bmx

@@ -21,7 +21,11 @@ SuperStrict
 
 Rem
 bbdoc: Cipher Block Chaining Mode
-about: A simple mode designed to prevent trivial forms of replay and swap attacks on ciphers.
+about:  Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers.
+It is given as: 
+$$$
+C_i = E_k(P_i \oplus C_{i - 1})
+$$$
 
 It is important that the initialization vector be unique and preferably random for each message encrypted under the same key.
 End Rem
@@ -32,12 +36,17 @@ ModuleInfo "CC_OPTS: -DLTC_NO_TEST -DLTC_NO_FILE -DLTC_CBC_MODE"
 Import "common.bmx"
 
 Rem
-bbdoc: 
+bbdoc: CBC Cipher Mode.
+about: A symmetric mode block cipher.
 End Rem
 Type TCBCCipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Initializes the cipher mode.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
+	about: The @iv value is the initialization vector to be used with the cipher.
+	You must fill the IV yourself and it is assumed they are the same length as the block size of the cipher you choose.
+	It is important that the IV be random for each unique message you want to encrypt.
 	End Rem
 	Method Start:Int(cipher:TCipher, iv:Byte Ptr, key:Byte Ptr, keylen:Int, numRounds:Int)
 		Local res:Int
@@ -56,7 +65,8 @@ Type TCBCCipherMode Extends TCipherMode
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
+	returns: CRYPT_OK on success.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, pt:Byte Ptr, length:UInt)
 		Return bmx_crypto_cbc_decrypt(modePtr, ct, pt, length)

cfbmode.mod/cfbmode.bmx

@@ -21,11 +21,18 @@ SuperStrict
 
 Rem
 bbdoc: Ciphertext Feedback Mode
-about: A mode designed to prevent trivial forms of replay and swap attacks on ciphers.
+about: Ciphertext Feedback Mode is a mode designed to prevent trivial forms of replay and swap attacks on ciphers.
+It is given as:
+$$$
+\begin{aligned}
+C_i &= P_i \oplus C_{-1} \\
+C_{-1} &= E_k(C_i)
+\end{aligned}
+$$$
 
 The output feedback width is equal to the size of the block cipher.
 That is this mode is used to encrypt whole blocks at a time. However, the library will buffer data allowing the user
-to encrypt or decrypt partial blocks without a delay. When this mode is first setup it will initially encrypt the initialization vector as required.
+to encrypt or decrypt partial blocks without a delay. When this mode is first setup it will initially encrypt the initialization vector as required.
 End Rem
 Module Crypto.CFBMode
 
@@ -34,12 +41,17 @@ ModuleInfo "CC_OPTS: -DLTC_NO_TEST -DLTC_NO_FILE -DLTC_CFB_MODE"
 Import "common.bmx"
 
 Rem
-bbdoc: 
+bbdoc: CFB Cipher Mode
+about: A symmetric mode block cipher.
 End Rem
 Type TCFBCipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Initializes the cipher mode.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
+	about: The @iv value is the initialization vector to be used with the cipher.
+	You must fill the IV yourself and it is assumed they are the same length as the block size of the cipher you choose.
+	It is important that the IV be random for each unique message you want to encrypt.
 	End Rem
 	Method Start:Int(cipher:TCipher, iv:Byte Ptr, key:Byte Ptr, keylen:Int, numRounds:Int)
 		Local res:Int
@@ -58,7 +70,8 @@ Type TCFBCipherMode Extends TCipherMode
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
+	returns: CRYPT_OK on success.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, pt:Byte Ptr, length:UInt)
 		Return bmx_crypto_cfb_decrypt(modePtr, ct, pt, length)

ctrmode.mod/ctrmode.bmx

@@ -20,10 +20,16 @@
 SuperStrict
 
 Rem
-bbdoc: Counter mode
+bbdoc: Counter Mode
 about: A mode which only uses the encryption function of the cipher.
 
-The initialization vector is treated as a large binary counter.
+Given a initialization vector which is treated as a large binary counter the CTR mode is given as:
+$$$
+\begin{aligned}
+C_{-1} &= C_{-1} + 1\text{ }(\text{mod }2^W) \\
+C_i &= P_i \oplus E_k(C_{-1})
+\end{aligned}
+$$$
 
 As long as the initialization vector is random for each message encrypted under the same key replay and swap attacks are infeasible.
 CTR mode may look simple but it is as secure as the block cipher is under a chosen plaintext attack (provided the initialization vector is unique).
@@ -41,16 +47,29 @@ Enum ECTRCounterMode
 End Enum
 
 Rem
-bbdoc: 
+bbdoc: CTR Cipher Mode
+about: A symmetric mode block cipher.
 End Rem
 Type TCTRCipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Initializes the cipher mode.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
+	about: The @iv value is the initialization vector to be used with the cipher.
+	You must fill the IV yourself and it is assumed they are the same length as the block size of the cipher you choose.
+	It is important that the IV be random for each unique message you want to encrypt.
+
+	The @counterMode parameter specfies the mode that the counter is to be used in. If #ECTRCounterMode LITTLE_ENDIAN is specfied
+	then the counter will be treated as a little endian value. Otherwise, if BIG_ENDIAN is specified the counter will be treated as a
+	big endian value.
+	The RFC 3686 style of increment for encryption is also supported, by OR'ing RFC3686 with the CTR mode value.
+	The counter will be incremented before encrypting it for the first time.
+	It also supports variable length counters for CTR mode. The (optional) counter length is specified by OR'ing the octet length of
+	the counter against the @counterMode parameter. The default, zero, indicates that a full block length counter will be used.
 	End Rem
-	Method Start:Int(cipher:TCipher, iv:Byte Ptr, key:Byte Ptr, keylen:Int, numRounds:Int, counterMode:ECTRCounterMode)
+	Method Start:Int(cipher:TCipher, iv:Byte Ptr, key:Byte Ptr, keylen:Int, numRounds:Int, counterMode:Int)
 		Local res:Int
-		modePtr = bmx_crypto_ctr_start(cipher.index, iv, key, keylen, numRounds, counterMode.Ordinal(), res)
+		modePtr = bmx_crypto_ctr_start(cipher.index, iv, key, keylen, numRounds, counterMode, res)
 		Return res
 	End Method
 
@@ -65,7 +84,8 @@ Type TCTRCipherMode Extends TCipherMode
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
+	returns: CRYPT_OK on success.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, pt:Byte Ptr, length:UInt)
 		Return bmx_crypto_ctr_decrypt(modePtr, ct, pt, length)

ctrmode.mod/doc/tctrciphermode.bmx

@@ -0,0 +1,38 @@
+SuperStrict
+
+Framework brl.standardio
+Import crypto.ctrmode
+Import crypto.aescipher
+Import crypto.crypto
+Import brl.base64
+
+Local cipher:TCipher = TCipher.Find("aes")
+Local cipherMode:TCTRCipherMode = New TCTRCipherMode
+
+Local txt:String = "The quick brown fox jumped over the lazy dog"
+Print "Text    = " + txt
+
+Local iv:Byte[32]
+Local key:Byte[32]
+TCryptoRandom.FillBuffer(iv)
+TCryptoRandom.FillBuffer(key)
+
+Print "IV      = " + TBase64.Encode(iv)
+Print "Key     = " + TBase64.Encode(key)
+
+Local pbuf:Byte Ptr = txt.ToUTF8String()
+Local cbuf:Byte[txt.length]
+
+cipherMode.Start(cipher, iv, key, 32, 14, ECTRCounterMode.LITTLE_ENDIAN)
+cipherMode.Encrypt(pbuf, cbuf, UInt(txt.length))
+cipherMode.Done()
+
+Print "Encoded = " + TBase64.Encode(cbuf)
+
+Local buf:Byte[txt.length + 1]
+
+cipherMode.Start(cipher, iv, key, 32, 14, ECTRCounterMode.LITTLE_ENDIAN)
+cipherMode.Decrypt(cbuf, buf, txt.length)
+cipherMode.Done()
+
+Print "Decoded = " + String.FromUTF8String(buf)

ecbmode.mod/ecbmode.bmx

@@ -21,7 +21,12 @@ SuperStrict
 
 Rem
 bbdoc: Electronic Codebook Mode
-about: The simplest method to use.
+about: Electronic Codebook Mode is the simplest method to use.
+It is given as:
+$$$
+C_i = E_k(P_i)
+$$$
+
 It is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more than once.
 End Rem
 Module Crypto.ECBMode
@@ -31,12 +36,14 @@ ModuleInfo "CC_OPTS: -DLTC_NO_TEST -DLTC_NO_FILE -DLTC_ECB_MODE"
 Import "common.bmx"
 
 Rem
-bbdoc: 
+bbdoc: ECB Cipher Mode
+about: A symmetric mode block cipher.
 End Rem
 Type TECBCipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Initializes the cipher mode.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
 	End Rem
 	Method Start:Int(cipher:TCipher, key:Byte Ptr, keylen:Int, numRounds:Int)
 		Local res:Int
@@ -55,7 +62,8 @@ Type TECBCipherMode Extends TCipherMode
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
+	returns: CRYPT_OK on success.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, pt:Byte Ptr, length:UInt)
 		Return bmx_crypto_ecb_decrypt(modePtr, ct, pt, length)

f8mode.mod/f8mode.bmx

@@ -31,12 +31,15 @@ ModuleInfo "CC_OPTS: -DLTC_NO_TEST -DLTC_NO_FILE -DLTC_F8_MODE"
 Import "common.bmx"
 
 Rem
-bbdoc: 
+bbdoc: F8 Cipher Mode
+about: A chaining mode for block ciphers.
 End Rem
 Type TF8CipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Starts the cipher mode state using @key as the secret key and @iv as the counter.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
+	about: It uses @saltKey as the IV encryption. The salt key can be shorter than the secret key, but not longer.
 	End Rem
 	Method Start:Int(cipher:TCipher, iv:Byte Ptr, key:Byte Ptr, keylen:Int, saltKey:Byte Ptr, saltkeylen:Int, numRounds:Int)
 		Local res:Int
@@ -47,7 +50,7 @@ Type TF8CipherMode Extends TCipherMode
 	Rem
 	bbdoc: Encrypts the plaintext @pt of @length to @ct.
 	returns: CRYPT_OK on success.
-	about: The @length is specified in bytes and does not have to be a multiple of the ciphers block size.
+	about: The @length is specified in bytes and does not have to be a multiple of the ciphers block size.
 	End Rem
 	Method Encrypt:Int(pt:Byte Ptr, ct:Byte Ptr, length:UInt)
 		Return bmx_crypto_f8_encrypt(modePtr, pt, ct, length)
@@ -56,7 +59,7 @@ Type TF8CipherMode Extends TCipherMode
 	Rem
 	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
 	returns: CRYPT_OK on success.
-	about: The @length is specified in bytes and does not have to be a multiple of the ciphers block size.
+	about: The @length is specified in bytes and does not have to be a multiple of the ciphers block size.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, pt:Byte Ptr, length:UInt)
 		Return bmx_crypto_f8_decrypt(modePtr, ct, pt, length)
@@ -64,7 +67,7 @@ Type TF8CipherMode Extends TCipherMode
 
 	Rem
 	bbdoc: Reads the IV out of the chaining mode, and stores it in @IV along with the @length of the IV.
-	about: This works with the current IV value only and not the encrypted IV value specified during the call to #Start.
+	about: This works with the current IV value only and not the encrypted IV value specified during the call to #Start.
 	The purpose of this method is to be able to seek within a current session only. If you want to change the session IV you will have to call #Done and
 	then start a new state with #Start. 
 	End Rem

lrwmode.mod/lrwmode.bmx

@@ -23,7 +23,6 @@ Rem
 bbdoc: LRW Mode
 about: This mode is less susceptible to attack or being compromised than other current techniques such as Counter-Mode encryption or Cipher Block Chaining (CBC) encryption.
 The mode addresses threats such as copy-and-paste and dictionary attacks. LRW mode is specially designed for encryption of storage at the sector level.
-
 End Rem
 Module Crypto.lrwMode
 
@@ -32,12 +31,17 @@ ModuleInfo "CC_OPTS: -DLTC_NO_TEST -DLTC_NO_FILE -DLTC_LRW_MODE -DLTC_LRW_TABLES
 Import "common.bmx"
 
 Rem
-bbdoc: 
+bbdoc: LRW Cipher Mode
 End Rem
 Type TLRWCipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Initializes the cipher mode.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
+	about: The key is specified in two parts. The first @key is the (normally AES) key and can be any length (typically 16, 24 or 32 octets long).
+	The second key is the @tweak key and is always 16 octets long.
+	
+	The @tweak value is NOT a nonce or IV value it must be random and secret.
 	End Rem
 	Method Start:Int(cipher:TCipher, iv:Byte Ptr, key:Byte Ptr, keylen:Int, tweak:Byte Ptr, numRounds:Int)
 		Local res:Int
@@ -56,7 +60,8 @@ Type TLRWCipherMode Extends TCipherMode
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
+	returns: CRYPT_OK on success.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, pt:Byte Ptr, length:UInt)
 		Return bmx_crypto_lrw_decrypt(modePtr, ct, pt, length)

ofbmode.mod/ofbmode.bmx

@@ -21,9 +21,16 @@ SuperStrict
 
 Rem
 bbdoc: Output Feedback Mode
-about: Similar to CBC mode, it is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers.
+about: Similar to #Crypto.CBCMode, it is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers.
+It is given as:
+$$$
+\begin{aligned}
+C_{-1} &= E_k(C_{-1}) \\
+C_i &= P_i \oplus C_{-1}
+\end{aligned}
+$$$
 
-Output width in is the same as the width of the block cipher.
+Like in the #Crypto.CFBMode, the output width is the same as the width of the block cipher. 
 This mode will also buffer the output which will allow you to encrypt or decrypt partial blocks without delay.
 End Rem
 Module Crypto.OFBMode
@@ -33,12 +40,17 @@ ModuleInfo "CC_OPTS: -DLTC_NO_TEST -DLTC_NO_FILE -DLTC_OFB_MODE"
 Import "common.bmx"
 
 Rem
-bbdoc: An 
+bbdoc: OFB Cipher Mode
+about: A symmetric mode block cipher.
 End Rem
 Type TOFBCipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Initializes the cipher mode.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
+	about: The @iv value is the initialization vector to be used with the cipher.
+	You must fill the IV yourself and it is assumed they are the same length as the block size of the cipher you choose.
+	It is important that the IV be random for each unique message you want to encrypt.
 	End Rem
 	Method Start:Int(cipher:TCipher, iv:Byte Ptr, key:Byte Ptr, keylen:Int, numRounds:Int)
 		Local res:Int
@@ -57,7 +69,8 @@ Type TOFBCipherMode Extends TCipherMode
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
+	returns: CRYPT_OK on success.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, pt:Byte Ptr, length:UInt)
 		Return bmx_crypto_ofb_decrypt(modePtr, ct, pt, length)

xtsmode.mod/xtsmode.bmx

@@ -25,7 +25,7 @@ about: A chaining mode for 128–bit block ciphers, recommended by IEEE (P1619)
 
 It is meant to be an encryption mode with random access to the message data without compromising privacy.
 It requires two private keys (of equal length) to perform the encryption process.
-Each encryption invocation includes a sector number or unique identifier specified as a 128–bit string. 
+Each encryption invocation includes a sector number or unique identifier specified as a 128–bit string. 
 End Rem
 Module Crypto.XTSMode
 
@@ -34,12 +34,15 @@ ModuleInfo "CC_OPTS: -DLTC_NO_TEST -DLTC_NO_FILE -DLTC_XTS_MODE"
 Import "common.bmx"
 
 Rem
-bbdoc: 
+bbdoc: XTS Cipher Mode.
+about: A chaining mode for 128–bit block ciphers
 End Rem
 Type TXTSCipherMode Extends TCipherMode
 
 	Rem
-	bbdoc: 
+	bbdoc: Initializes the cipher mode.
+	returns: CRYPT_OK if the cipher initialized correctly, otherwise, returns an error code.
+	about: It requires two private keys (of equal length) to perform the encryption process.
 	End Rem
 	Method Start:Int(cipher:TCipher, key1:Byte Ptr, key2:Byte Ptr, keylen:Int, numRounds:Int)
 		Local res:Int
@@ -52,17 +55,18 @@ Type TXTSCipherMode Extends TCipherMode
 	returns: CRYPT_OK on success.
 	about: Supports ciphertext stealing (blocks that are not multiples of 16 bytes).
 	
-	The P1619 specification states the tweak for sector number shall be represented as a 128–bit little endian string.
+	The P1619 specification states the tweak for sector number shall be represented as a 128–bit little endian string.
 	End Rem
 	Method Encrypt:Int(pt:Byte Ptr, ptlength:UInt, ct:Byte Ptr, tweak:Byte Ptr)
 		Return bmx_crypto_xts_encrypt(modePtr, pt, ptlength, ct, tweak)
 	End Method
 	
 	Rem
-	bbdoc: 
+	bbdoc: Decrypts the ciphertext @ct of @length to @pt.
+	returns: CRYPT_OK on success.
 	about: Supports ciphertext stealing (blocks that are not multiples of 16 bytes).
 
-	The P1619 specification states the tweak for sector number shall be represented as a 128–bit little endian string.
+	The P1619 specification states the tweak for sector number shall be represented as a 128–bit little endian string.
 	End Rem
 	Method Decrypt:Int(ct:Byte Ptr, ptlength:UInt, pt:Byte Ptr, tweak:Byte Ptr)
 		Return bmx_crypto_xts_decrypt(modePtr, ct, ptlength, pt, tweak)