Merge remote-tracking branch 'origin/master' into development

Author: Markus Humm

Demos/Cipher_Console/Cipher_Console.dpr

@@ -63,7 +63,6 @@ begin
 
       // Encrypt
       Output := Cipher.EncodeBytes(Input);
-      // clean up inside the cipher instance, which also removes the key from RAM
       Cipher.Done;
 
       Write('Encrypted data in hex: ');
@@ -75,7 +74,6 @@ begin
       // Decrypt
       Cipher.Init(CipherKey, IV, 0);
       Output := Cipher.DecodeBytes(Output);
-      // clean up inside the cipher instance, which also removes the key from RAM
       Cipher.Done;
 
       SourceText := RawByteString(System.SysUtils.StringOf(Output));
@@ -89,7 +87,6 @@ begin
       CipherKey := 'Password';
       Cipher.Init(CipherKey, IV, 0);
       Output := Cipher.DecodeBytes(Output);
-      // clean up inside the cipher instance, which also removes the key from RAM
       Cipher.Done;
 
       SourceText := RawByteString(System.SysUtils.StringOf(Output));
@@ -104,6 +101,7 @@ begin
 
     ReadLn;
   finally
+    // clean up inside the cipher instance, which also removes the key from RAM
     Cipher.Free;
   end;
 end.

Demos/Cipher_Console_KDF/Cipher_Console_KDF.dpr

@@ -71,7 +71,6 @@ begin
 
       // Encrypt
       Output := Cipher.EncodeBytes(Input);
-      // clean up inside the cipher instance, which also removes the key from RAM
       Cipher.Done;
 
       Write('Encrypted data in hex: ');
@@ -83,7 +82,6 @@ begin
       // Decrypt
       Cipher.Init(RawByteString(StringOf(KeyKDF)), IV, 0);
       Output := Cipher.DecodeBytes(Output);
-      // clean up inside the cipher instance, which also removes the key from RAM
       Cipher.Done;
 
       SourceText := RawByteString(System.SysUtils.StringOf(Output));
@@ -96,6 +94,7 @@ begin
 
     ReadLn;
   finally
+    // clean up inside the cipher instance, which also removes the key from RAM
     Cipher.Free;
   end;
 end.

Demos/Cipher_FMX/MainFormCipherFMX.pas

@@ -294,8 +294,8 @@ procedure TFormMain.ButtonDecryptClick(Sender: TObject);
           PlainTextBuffer := (Cipher as TDECFormattedCipher).DecodeBytes(
                             CipherTextFormatting.Decode(CipherTextBuffer));
           // in case of an authenticated cipher mode like cmGCM the Done method
-          // will raise an exceptino when the calculated authentication value does
-          // not match the given expected one
+          // will raise an exception when the calculated authentication value does
+          // not match the given expected one set in SetAuthenticationParams().
           (Cipher as TDECFormattedCipher).Done;
           // If we managed to get to here, the calculated authentication value is
           // ok if we're in an authenticated mode and have entered an expected value.

Demos/Hash_Console/Hash_Console.dpr

@@ -43,7 +43,6 @@ begin
       WriteLn('RipeMD160 digest (hash value) of ' + s + ' is ' + sLineBreak +
               Hash.CalcString(s, TFormat_HEX));
 
-      // Securely erase the memory
       Hash.Done;
     except
       on E: Exception do
@@ -52,6 +51,7 @@ begin
 
     ReadLn;
   finally
+    // Securely erase the memory
     Hash.Free;
   end;
 end.

Source/DECCipherBase.pas

@@ -112,9 +112,6 @@ interface
   ///   csNew : cipher isn't initialized, .Init() must be called before en/decode
   /// </para>
   /// <para>
-  ///   csNew : cipher isn't initialized, .Init() must be called before en/decode
-  /// </para>
-  /// <para>
   ///   csInitialized : cipher is initialized by .Init(), i.e. Keysetup was processed
   /// </para>
   /// <para>
@@ -128,10 +125,11 @@ interface
   ///                   be processed, the cipher is blocked
   /// </para>
   /// <para>
-  ///   csDone : Processing is finished and Cipher.Done was called. Now new En/Decoding
+  ///   csDone : Processing is finished and Cipher.Done was called. Now, new En/Decoding
   ///            can be started without calling .Init() before. csDone is basically
   ///            identical to csInitialized, except Cipher.Buffer holds the encrypted
-  ///            last state of Cipher.Feedback, thus Cipher.Buffer can be used as C-MAC.
+  ///            last state of Cipher.Feedback which can be used as
+  ///            Cipher-based message authentication code (CMAC).
   /// </para>
   /// </summary>
   TCipherState = (csNew, csInitialized, csEncode, csDecode, csPadded, csDone);
@@ -252,6 +250,8 @@   TDECCipher = class(TDECObject)
     ///   Some algorithms, mostly the cipher mode ones, need a temporary buffer
     ///   to work with. Some other methods like Done or Valid cipher need to pass
     ///   a buffer as parameter as that is ecpected by the called method.
+    ///   If Done was called, FBuffer contains a C-MAC which is the encryption
+    ///   of the last block concatention feedback.
     /// </summary>
     FBuffer: PUInt8Array;
 
@@ -296,7 +296,7 @@   TDECCipher = class(TDECObject)
     ///   FAdditionalBuffer points to as well, and for some algorithms this part
     ///   of the memory may not be altered during initialization so it is
     ///   backupped to this memory location and restored after the IV got encrypted.
-    ///   In DoDone it needs to be restored as well to prevent any unwanted
+    ///   In Done it needs to be restored as well to prevent any unwanted
     ///   leftovers which might pose a security issue.
     /// </summary>
     FAdditionalBufferBackup: Pointer;
@@ -444,7 +444,8 @@   TDECCipher = class(TDECObject)
     constructor Create; override;
     /// <summary>
     ///   Frees internal structures and where necessary does so in a save way so
-    ///   that data in those structures cannot be "stolen".
+    ///   that data in those structures cannot be "stolen". It removes the key
+    ///   from RAM.
     /// </summary>
     destructor Destroy; override;
 
@@ -578,8 +579,9 @@   TDECCipher = class(TDECObject)
 
     /// <summary>
     ///   Properly finishes the cryptographic operation. It needs to be called
-    ///   at the end of encrypting or decrypting data, otherwise the last block
-    ///   or last byte of the data will not be properly processed.
+    ///   at the end of encrypting or decrypting data. It does NOT remove the
+    ///   keys from RAM (this will be done in the destruction only).
+    ///   You can continue encrypting/decrypting without calling Init() again.
     /// </summary>
     procedure Done; virtual;
 
@@ -696,18 +698,34 @@   TDECCipher = class(TDECObject)
     /// </exception>
     function DecodeBytes(const Source: TBytes; Format: TDECFormatClass): TBytes;
 
-    // CalcMACBytes deferred since the current implementation would neither be
-    // performant (that would require another TFormatBase.Encode variant from
-    // pointer to TBytes and that would require a new method name as overloads
-    // may not differ in return values only and it would require a lot of unit
-    // tests to get implemented. Deferred in particular also due to not yet
-    // really understanding the purpose of CalcMAC
-//    function CalcMACByte(Format: TDECFormatClass = nil): TBytes; overload;
+    /// <summary>
+    ///   Calculates a Cipher-based message authentication code (CMAC).
+    ///   This is the encryption of the last block concatenation feedback value.
+    ///   In decryption scenarios it can be used to check if the data arrived
+    ///   unaltered if the sender provides the MAC value along with the encrypted
+    ///   text. Both need to match after decrypting. Using this method is less
+    ///   secure than using the HMAC algorithm!
+    ///   This method cannot be used in the ECB cipher mode.
+    ///   Side effect: "Done" will be called if it hasn't been called before.
+    /// </summary>
+    /// <param name="Format">
+    ///   Optional parameter. Here a formatting method can be passed. The
+    ///   data to be decrypted will be formatted with this function, if one
+    ///   has been passed. Examples are hex or base 64 formatting.
+    ///   This is used for removing a formatting applied by the EncodeRawByteString
+    ///   method.
+    /// </param>
+    /// <returns>
+    ///   Calculates a Cipher-based message authentication code (CMAC).
+    /// </returns>
+    /// <exception cref="EDECCipherException">
+    ///   Exception raised the cipher mode is ECB.
+    /// </exception>
+    { TODO: Add unit test }
+    function CalcMAC(Format: TDECFormatClass = nil): RawByteString;
 
-    // Deprecated directive commented out, as replacement CalcMACByte has not
-    // been implemented yet, see remark above. Use case for CalcMAC is not clear
-    // yet either.
-    function CalcMAC(Format: TDECFormatClass = nil): RawByteString; overload; //deprecated 'please use the TBytes based overload';
+    /// Same as CalcMAC, but return TBytes
+    function CalcMACBytes(Format: TDECFormatClass = nil): TBytes;
 
     // properties
 
@@ -1156,27 +1174,19 @@ function TDECCipher.DecodeBytes(const Source: TBytes; Format: TDECFormatClass):
   end;
 end;
 
-
 function TDECCipher.CalcMAC(Format: TDECFormatClass): RawByteString;
 begin
-  Done;
+  Done; { TODO: This might be considered as unwanted side effect. Maybe we should instead raise an Exception if State is not csDone instead? This would also "teach" the user to don't forget to call "Done". }
   if FMode in [cmECBx] then
     raise EDECException.CreateRes(@sInvalidMACMode)
   else
     Result := ValidFormat(Format).Encode(FBuffer^, FBufferSize);
-  { TODO : How to rewrite? EncodeBytes cannot be called directly like that }
 end;
 
-//function TDECCipher.CalcMACByte(Format: TDECFormatClass): TBytes;
-//begin
-//  Done;
-//  if FMode in [cmECBx] then
-//    raise EDECCipherException.Create(sInvalidMACMode)
-//  else
-//  begin
-//    Result := System.SysUtils.BytesOf(ValidFormat(Format).Encode(FBuffer^, FBufferSize));
-//  end;
-//end;
+function TDECCipher.CalcMACBytes(Format: TDECFormatClass): TBytes;
+begin
+  Result := System.SysUtils.BytesOf(CalcMAC);
+end;
 
 {$IFDEF RESTORE_RANGECHECKS}{$R+}{$ENDIF}
 {$IFDEF RESTORE_OVERFLOWCHECKS}{$Q+}{$ENDIF}

Source/DECHashAuthentication.pas

@@ -116,7 +116,7 @@   TDECHashAuthentication = class(TDECHash)
     class function MGF1(const Data; DataSize, MaskSize: Integer): TBytes; overload;
     /// <summary>
     ///   Mask generation: generates an output based on the data given which is
-    ///   similar to a hash function but incontrast does not have a fixed output
+    ///   similar to a hash function but in contrast does not have a fixed output
     ///   length. Use of a MGF is desirable in cases where a fixed-size hash
     ///   would be inadequate. Examples include generating padding, producing
     ///   one time pads or keystreams in symmetric key encryption, and yielding
@@ -341,7 +341,7 @@   TDECHashAuthentication = class(TDECHash)
 
     /// <summary>
     ///   Mask generation: generates an output based on the data given which is
-    ///   similar to a hash function but incontrast does not have a fixed output
+    ///   similar to a hash function but in contrast does not have a fixed output
     ///   length. Use of a MGF is desirable in cases where a fixed-size hash
     ///   would be inadequate. Examples include generating padding, producing
     ///   one time pads or keystreams in symmetric key encryption, and yielding
@@ -372,7 +372,7 @@   TDECHashAuthentication = class(TDECHash)
                         Index: UInt32 = 1): TBytes; overload;
     /// <summary>
     ///   Mask generation: generates an output based on the data given which is
-    ///   similar to a hash function but incontrast does not have a fixed output
+    ///   similar to a hash function but in contrast does not have a fixed output
     ///   length. Use of a MGF is desirable in cases where a fixed-size hash
     ///   would be inadequate. Examples include generating padding, producing
     ///   one time pads or keystreams in symmetric key encryption, and yielding

Unit Tests/Tests/TestDECHashSHA3.pas

@@ -1,4 +1,4 @@
-{*****************************************************************************
+{*****************************************************************************
   The DEC team (see file NOTICE.txt) licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
@@ -1829,7 +1829,6 @@ procedure TestTHash_Keccak_224.SetUp;
 
   //Source https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Algorithm-
   //       Validation-Program/documents/sha3/sha-3bittestvectors.zip
-
   FTestFileNames.Add('..\..\Unit Tests\Data\SHA3_224ShortMsg.rsp');
   FTestFileNames.Add('..\..\Unit Tests\Data\SHA3_224LongMsg.rsp');
   // SourceEnd
@@ -2068,20 +2067,29 @@ procedure TestTHash_Keccak_256.SetUp;
 
   // Source https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-
   //        and-Guidelines/documents/examples/SHA3-256_Msg5.pdf
+  // TODO:
+  // expected: <7b0047cf5a456882363cbf0fb05322cf65f4b7059a46365e830132e3b5d957af>
+  // but was:  <1594a22d1e1dd176e6f35ae26d8efa294589e23676e1fdc917423a1282546528>
   lDataRow := FTestData.AddRow;
   lDataRow.ExpectedOutput           := '7b0047cf5a456882363cbf0fb05322cf65f4b705' +
                                        '9a46365e830132e3b5d957af';
   AddLastByteForCodeTest(lDataRow, #$13, 5);
 
   // Source https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-
   //        and-Guidelines/documents/examples/SHA3-256_Msg30.pdf
+  // TODO:
+  // expected: <c8242fef409e5ae9d1f1c857ae4dc624b92b19809f62aa8c07411c54a078b1d0>
+  // but was:  <ce8c2109c14e5416785a205f34316b50fa11993fac9c7236c643cb5e7b00afbd>
   lDataRow := FTestData.AddRow;
   lDataRow.ExpectedOutput           := 'c8242fef409e5ae9d1f1c857ae4dc624b92b1980' +
                                        '9f62aa8c07411c54a078b1d0';
-  AddLastByteForCodeTest(lDataRow, #$53#$58#$7B#$19, 6);
+  AddLastByteForCodeTest(lDataRow, #$53#$58#$7B#$19, 30 mod 8);
 
   // Source https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-
   //        and-Guidelines/documents/examples/SHA3-256_Msg1605.pdf
+  // TODO:
+  // expected: <81ee769bed0950862b1ddded2e84aaa6ab7bfdd3ceaa471be31163d40336363c>
+  // but was:  <ffc38f204f021c3adf97c55e0d453904749b6ad71c15612f60d018e946d00c24>
   lDataRow := FTestData.AddRow;
   lDataRow.ExpectedOutput           := '81ee769bed0950862b1ddded2e84aaa6ab7bfdd3' +
                                        'ceaa471be31163d40336363c';
@@ -2110,6 +2118,9 @@ procedure TestTHash_Keccak_256.SetUp;
 
   // Source https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-
   //        and-Guidelines/documents/examples/SHA3-256_1630.pdf
+  // TODO:
+  // expected: <52860aa301214c610d922a6b6cab981ccd06012e54ef689d744021e738b9ed20>
+  // but was:  <96eb974c5cfdfc80fe2e8b0203652998827cda5b8ecd2a99ab90e653ed1eacc1>
   lDataRow := FTestData.AddRow;
   lDataRow.ExpectedOutput           := '52860aa301214c610d922a6b6cab981ccd06012e' +
                                        '54ef689d744021e738b9ed20';