291 lines
11 KiB
ObjectPascal
291 lines
11 KiB
ObjectPascal
{*****************************************************************************
|
|
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
|
|
with the License. A copy of this licence is found in the root directory
|
|
of this project in the file LICENCE.txt or alternatively at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing,
|
|
software distributed under the License is distributed on an
|
|
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
KIND, either express or implied. See the License for the
|
|
specific language governing permissions and limitations
|
|
under the License.
|
|
*****************************************************************************}
|
|
unit DECHashInterface;
|
|
|
|
interface
|
|
|
|
uses
|
|
{$IFDEF FPC}
|
|
SysUtils, Classes,
|
|
{$ELSE}
|
|
System.SysUtils, System.Classes,
|
|
{$ENDIF}
|
|
DECFormat, DECUtil;
|
|
|
|
type
|
|
/// <summary>
|
|
/// Generic interface for all hash classes.
|
|
/// Unfortunately without all the class methods, as they are not accepted
|
|
/// in interface declarations
|
|
/// </summary>
|
|
IDECHash = Interface
|
|
/// <summary>
|
|
/// Generic initialization of internal data structures. Additionally the
|
|
/// internal algorithm specific (because of being overridden by each
|
|
/// hash algorithm) DoInit method. Needs to be called before each hash
|
|
/// calculation.
|
|
/// </summary>
|
|
procedure Init;
|
|
/// <summary>
|
|
/// Calculates one chunk of data to be hashed.
|
|
/// </summary>
|
|
/// <param name="Data">
|
|
/// Data on which the hash value shall be calculated on
|
|
/// </param>
|
|
/// <param name="DataSize">
|
|
/// Size of the data in bytes
|
|
/// </param>
|
|
procedure Calc(const Data; DataSize: Integer);
|
|
|
|
/// <summary>
|
|
/// Frees dynamically allocated buffers in a way which safeguards agains
|
|
/// data stealing by other methods which afterwards might allocate this memory.
|
|
/// Additionaly calls the algorithm spercific DoDone method.
|
|
/// </summary>
|
|
procedure Done;
|
|
|
|
/// <summary>
|
|
/// Returns the calculated hash value as byte array
|
|
/// </summary>
|
|
function DigestAsBytes: TBytes;
|
|
|
|
/// <summary>
|
|
/// Returns the calculated hash value as formatted Unicode string
|
|
/// </summary>
|
|
/// <param name="Format">
|
|
/// Optional parameter. If a formatting class is being passed the formatting
|
|
/// will be applied to the returned string. Otherwise no formatting is
|
|
/// being used.
|
|
/// </param>
|
|
/// <returns>
|
|
/// Hash value of the last performed hash calculation
|
|
/// </returns>
|
|
/// <remarks>
|
|
/// We recommend to use a formatting which results in 7 bit ASCII chars
|
|
/// being returned, otherwise the conversion into the Unicode string might
|
|
/// result in strange characters in the returned result.
|
|
/// </remarks>
|
|
function DigestAsString(Format: TDECFormatClass = nil): string;
|
|
/// <summary>
|
|
/// Returns the calculated hash value as formatted RawByteString
|
|
/// </summary>
|
|
/// <param name="Format">
|
|
/// Optional parameter. If a formatting class is being passed the formatting
|
|
/// will be applied to the returned string. Otherwise no formatting is
|
|
/// being used.
|
|
/// </param>
|
|
/// <returns>
|
|
/// Hash value of the last performed hash calculation
|
|
/// </returns>
|
|
/// <remarks>
|
|
/// We recommend to use a formatting which results in 7 bit ASCII chars
|
|
/// being returned, otherwise the conversion into the RawByteString might
|
|
/// result in strange characters in the returned result.
|
|
/// </remarks>
|
|
function DigestAsRawByteString(Format: TDECFormatClass = nil): RawByteString;
|
|
|
|
/// <summary>
|
|
/// Calculates the hash value (digest) for a given buffer
|
|
/// </summary>
|
|
/// <param name="Buffer">
|
|
/// Untyped buffer the hash shall be calculated for
|
|
/// </param>
|
|
/// <param name="BufferSize">
|
|
/// Size of the buffer in byte
|
|
/// </param>
|
|
/// <returns>
|
|
/// Byte array with the calculated hash value
|
|
/// </returns>
|
|
function CalcBuffer(const Buffer; BufferSize: Integer): TBytes;
|
|
/// <summary>
|
|
/// Calculates the hash value (digest) for a given buffer
|
|
/// </summary>
|
|
/// <param name="Data">
|
|
/// The TBytes array the hash shall be calculated on
|
|
/// </param>
|
|
/// <returns>
|
|
/// Byte array with the calculated hash value
|
|
/// </returns>
|
|
function CalcBytes(const Data: TBytes): TBytes;
|
|
|
|
/// <summary>
|
|
/// Calculates the hash value (digest) for a given unicode string
|
|
/// </summary>
|
|
/// <param name="Value">
|
|
/// The string the hash shall be calculated on
|
|
/// </param>
|
|
/// <param name="Format">
|
|
/// Formatting class from DECFormat. The formatting will be applied to the
|
|
/// returned digest value. This parameter is optional.
|
|
/// </param>
|
|
/// <returns>
|
|
/// string with the calculated hash value
|
|
/// </returns>
|
|
function CalcString(const Value: string;
|
|
Format: TDECFormatClass = nil): string; overload;
|
|
/// <summary>
|
|
/// Calculates the hash value (digest) for a given rawbytestring
|
|
/// </summary>
|
|
/// <param name="Value">
|
|
/// The string the hash shall be calculated on
|
|
/// </param>
|
|
/// <param name="Format">
|
|
/// Formatting class from DECFormat. The formatting will be applied to the
|
|
/// returned digest value. This parameter is optional.
|
|
/// </param>
|
|
/// <returns>
|
|
/// string with the calculated hash value
|
|
/// </returns>
|
|
function CalcString(const Value: RawByteString;
|
|
Format: TDECFormatClass): RawByteString; overload;
|
|
|
|
/// <summary>
|
|
/// Calculates the hash value over a givens stream of bytes
|
|
/// </summary>
|
|
/// <param name="Stream">
|
|
/// Memory or file stream over which the hash value shall be calculated.
|
|
/// The stream must be assigned. The hash value will always be calculated
|
|
/// from the current position of the stream.
|
|
/// </param>
|
|
/// <param name="Size">
|
|
/// Number of bytes within the stream over which to calculate the hash value
|
|
/// </param>
|
|
/// <param name="HashResult">
|
|
/// In this byte array the calculated hash value will be returned
|
|
/// </param>
|
|
/// <param name="OnProgress">
|
|
/// Optional callback routine. It can be used to display the progress of
|
|
/// the operation.
|
|
/// </param>
|
|
procedure CalcStream(const Stream: TStream; Size: Int64; var HashResult: TBytes;
|
|
const OnProgress:TDECProgressEvent = nil); overload;
|
|
/// <summary>
|
|
/// Calculates the hash value over a givens stream of bytes
|
|
/// </summary>
|
|
/// <param name="Stream">
|
|
/// Memory or file stream over which the hash value shall be calculated.
|
|
/// The stream must be assigned. The hash value will always be calculated
|
|
/// from the current position of the stream.
|
|
/// </param>
|
|
/// <param name="Size">
|
|
/// Number of bytes within the stream over which to calculate the hash value
|
|
/// </param>
|
|
/// <param name="Format">
|
|
/// Optional formatting class. The formatting of that will be applied to
|
|
/// the returned hash value.
|
|
/// </param>
|
|
/// <param name="OnProgress">
|
|
/// Optional callback routine. It can be used to display the progress of
|
|
/// the operation.
|
|
/// </param>
|
|
/// <returns>
|
|
/// Hash value over the bytes in the stream, formatted with the formatting
|
|
/// passed as format parameter, if used.
|
|
/// </returns>
|
|
function CalcStream(const Stream: TStream; Size: Int64; Format: TDECFormatClass = nil;
|
|
const OnProgress:TDECProgressEvent = nil): RawByteString; overload;
|
|
|
|
/// <summary>
|
|
/// Calculates the hash value over the contents of a given file
|
|
/// </summary>
|
|
/// <param name="FileName">
|
|
/// Path and name of the file to be processed
|
|
/// </param>
|
|
/// <param name="HashResult">
|
|
/// Here the resulting hash value is being returned as byte array
|
|
/// </param>
|
|
/// <param name="OnProgress">
|
|
/// Optional callback. If being used the hash calculation will call it from
|
|
/// time to time to return the current progress of the operation
|
|
/// </param>
|
|
procedure CalcFile(const FileName: string; var HashResult: TBytes;
|
|
const OnProgress:TDECProgressEvent = nil); overload;
|
|
/// <summary>
|
|
/// Calculates the hash value over the contents of a given file
|
|
/// </summary>
|
|
/// <param name="FileName">
|
|
/// Path and name of the file to be processed
|
|
/// </param>
|
|
/// <param name="Format">
|
|
/// Optional parameter: Formatting class. If being used the formatting is
|
|
/// being applied to the returned string with the calculated hash value
|
|
/// </param>
|
|
/// <param name="OnProgress">
|
|
/// Optional callback. If being used the hash calculation will call it from
|
|
/// time to time to return the current progress of the operation
|
|
/// </param>
|
|
/// <returns>
|
|
/// Calculated hash value as RawByteString.
|
|
/// </returns>
|
|
/// <remarks>
|
|
/// We recommend to use a formatting which results in 7 bit ASCII chars
|
|
/// being returned, otherwise the conversion into the RawByteString might
|
|
/// result in strange characters in the returned result.
|
|
/// </remarks>
|
|
function CalcFile(const FileName: string; Format: TDECFormatClass = nil;
|
|
const OnProgress:TDECProgressEvent = nil): RawByteString; overload;
|
|
|
|
/// <summary>
|
|
/// Returns the current value of the padding byte used to fill up data
|
|
/// if necessary
|
|
/// </summary>
|
|
function GetPaddingByte: Byte;
|
|
/// <summary>
|
|
/// Changes the value of the padding byte used to fill up data
|
|
/// if necessary
|
|
/// </summary>
|
|
/// <param name="Value">
|
|
/// New value for the padding byte
|
|
/// </param>
|
|
procedure SetPaddingByte(Value: Byte);
|
|
|
|
/// <summary>
|
|
/// Defines the byte used in the KDF methods to padd the end of the data
|
|
/// if the length of the data cannot be divided by required size for the
|
|
/// hash algorithm without reminder
|
|
/// </summary>
|
|
property PaddingByte: Byte read GetPaddingByte write SetPaddingByte;
|
|
end;
|
|
|
|
/// <summary>
|
|
/// Interface for all hash classes which are able to operate on bit sized
|
|
/// message lengths instead of byte sized ones only.
|
|
/// </summary>
|
|
IDECHashBitsized = Interface(IDECHash)
|
|
/// <summary>
|
|
/// Returns the number of bits the final byte of the message consists of
|
|
/// </summary>
|
|
function GetFinalByteLength: UInt8;
|
|
/// <summary>
|
|
/// Sets the number of bits the final byte of the message consists of
|
|
/// </summary>
|
|
procedure SetFinalByteLength(const Value: UInt8);
|
|
|
|
/// <summary>
|
|
/// Setting this to a number of bits allows to process messages which have
|
|
/// a length which is not a exact multiple of bytes.
|
|
/// </summary>
|
|
property FinalBitLength : UInt8
|
|
read GetFinalByteLength
|
|
write SetFinalByteLength;
|
|
end;
|
|
|
|
implementation
|
|
|
|
end.
|
|
|