File : acf-hash-message_digests.ads
------------------------------------------------------------------------
-- (c) 2001, Antonio Duran. All rights reserved --
-- aduran@inicia.es --
------------------------------------------------------------------------
-- The Ada Cryptographic Framework (ACF) is free software; you can --
-- redistribute it and/or modify it under terms of the GNU General --
-- Public License as published by the Free Software Foundation; --
-- either version 2, or (at your option) any later version. --
-- --
-- The ACF is distributed in the hope that it will be useful, but --
-- WITHOUT ANY WARRANTY; without even the implied warranty of --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU --
-- General Public License for more details. You should have received --
-- a copy of the GNU General Public License distributed with the ACF; --
-- see file COPYING. If not, write to the Free Software Foundation, --
-- 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. --
------------------------------------------------------------------------
-- Identification
-- File name : acf-hash-message_digests.ads
-- File kind : Ada package specification
-- Author : Antonio Duran
-- Creation date : November 20th., 2001
-- Current version : 1.0
------------------------------------------------------------------------
-- Purpose:
-- Provides a type definition and operations on values of that type
-- to handle the message digest produced by the hashing algorithms
-- implemented in the ACF.
------------------------------------------------------------------------
-- Portability issues:
-- TBD.
------------------------------------------------------------------------
-- Performance issues:
-- TBD.
------------------------------------------------------------------------
-- Revision history:
--
-- Ver Who When Why
-- 1.0 ADD 11202001 Initial implementation
--
------------------------------------------------------------------------
with Ada.Finalization;
with ACF.Types; use ACF.Types;
package ACF.Hash.Message_Digests is
---------------------------------------------------------------------
-- Type definitions
---------------------------------------------------------------------
--+---[Message_Digest]-----------------------------------------------
--| Type for handling the message digests produced by the hashing
--| algorithms implemented in the ACF.
--+------------------------------------------------------------------
type Message_Digest is private;
---------------------------------------------------------------------
-- Constants
---------------------------------------------------------------------
--+---[Null_Message_Digest]------------------------------------------
--| Constant that represents a null message digest object.
--+------------------------------------------------------------------
Null_Message_Digest : constant Message_Digest;
---------------------------------------------------------------------
-- Subprogram specifications
---------------------------------------------------------------------
--+---[To_Message_Digest]--------------------------------------------
--| Purpose:
--| Builds and returns a Message_Digest value from a Byte_Array.
--|
--| Arguments:
--| Source Byte_Array value from which the
--| Message_Digest will be built.
--|
--| Returned value:
--| Returns a Message_Digest value built out of the Source
--| Byte_Array. If Source'Length is 0 the function will return
--| a Null_Message_Digest.
--|
--| Exceptions:
--| ACF_Storage_Error if fails the allocation of the necessary
--| space.
--+------------------------------------------------------------------
function To_Message_Digest(
Source : in Byte_Array)
return Message_Digest;
--+---[To_Message_Digest]--------------------------------------------
--| Purpose:
--| Builds and returns a Message_Digest value from an hexadecimal
--| String that represents a byte array.
--|
--| Arguments:
--| Source String that contains the hexadecimal
--| representation of a byte array. String
--| length must be 0 or a multiple of 2. Each
--| byte is represented by a pair of hexadecimal
--| digits. Hexadecimal digit case is irrelevant.
--| No whitespace, or other separators or
--| format effectors are allowed at the
--| beginning and the end of the string or
--| between hex digits.
--|
--| Returned value:
--| Returns a Message_Digest value built out of the Source
--| String. If Source'Length is 0 the function will return
--| a Null_Message_Digest.
--|
--| Exceptions:
--| ACF_Storage_Error if fails the allocation of the necessary
--| space.
--| ACF_Syntax_Error if Source does not conform the syntax
--| conventions or contains invalid hexadecimal digit
--| characters.
--+------------------------------------------------------------------
function To_Message_Digest(
Source : in String)
return Message_Digest;
--+---[Set_Message_Digest]-------------------------------------------
--| Purpose:
--| Sets the Message_Digest to the sequence of bytes contained in
--| a Byte_Array.
--|
--| Arguments:
--| The_Digest Message_Digest object to set.
--| From Byte_Array to set the Message_Digest to.
--|
--| Exceptions:
--| ACF_Storage_Error if fails the allocation of the necessary
--| space. In case this exception is raised The_Digest is
--| left unmodified.
--+------------------------------------------------------------------
procedure Set_Message_Digest(
The_Digest : in out Message_Digest;
From : in Byte_Array);
--+---[Clear]--------------------------------------------------------
--| Purpose:
--| Zeroizes a Message_Digest object.
--|
--| Arguments:
--| The_Digest Message_Digest object to clear.
--|
--| Exceptions:
--| None.
--+------------------------------------------------------------------
procedure Clear(
The_Digest : in out Message_Digest);
--+---[To_Byte_Array]------------------------------------------------
--| Purpose:
--| Returns the byte array with the bytes of a Message_Digest.
--|
--| Arguments:
--| From_Digest Message_Digest object to obtain the byte
--| array from.
--|
--| Returned value:
--| Returns a Byte_Array with the sequence of bytes corresponding
--| to the Message_Digest. The array index is always 1 based.
--|
--| Exceptions:
--| ACF_Null_Argument_Error is From_Digest is a
--| Null_Message_Digest.
--+------------------------------------------------------------------
function To_Byte_Array(
From_Digest : in Message_Digest)
return Byte_Array;
--+---[To_Hex_String]------------------------------------------------
--| Purpose:
--| Returns a string containing the hexadecimal representation of
--| a message digest.
--|
--| Arguments:
--| From_Digest Message_Digest to obtain the hex string
--| representation from.
--| Digit_Case Case of the digits in the haxadecimal
--| representation (see ACF.Types).
--|
--| Returned value:
--| String with the hexadecimal representation of the message
--| digest.
--|
--| Exceptions:
--| ACF_Null_Argument_Error is From_Digest is a
--| Null_Message_Digest.
--+------------------------------------------------------------------
function To_Hex_String(
From_Digest : in Message_Digest;
Digit_Case : in Hex_Digit_Case := Upper_Case)
return String;
--+---["="]----------------------------------------------------------
--| Purpose:
--| Equality test for message digests.
--|
--| Arguments:
--| Left, Right Message_Digest objects to compare.
--|
--| Returned value:
--| Boolean value with the result of comparision.
--|
--| Exceptions:
--| None.
--+------------------------------------------------------------------
function "="(
Left : in Message_Digest;
Right : in Message_Digest)
return Boolean;
--+---[Get_Size]-----------------------------------------------------
--| Purpose:
--| Returns the size in bytes of a Message_Digest object.
--|
--| Arguments:
--| Of_Digest Message_Digest to obtain the size from.
--|
--| Returned value:
--| Natural value with the message digest length (0 if it is a
--| Null_Message_Digest.
--|
--| Exceptions:
--| None.
--+------------------------------------------------------------------
function Get_Size(
Of_Digest : in Message_Digest)
return Natural;
---------------------------------------------------------------------
-- Private part
---------------------------------------------------------------------
private
---------------------------------------------------------------------
-- Type definitions
---------------------------------------------------------------------
--+---[Byte_Array_Ptr]-----------------------------------------------
--| Access type to Byte_Array values.
--+------------------------------------------------------------------
type Byte_Array_Ptr is access all Byte_Array;
--+---[Message_Digest]-----------------------------------------------
--| Type for handling the message digests produced by the hashing
--| algorithms implemented in the ACF. It is a type extension of
--| the Ada.Finalization.Controlled tagged type that contains the
--| following fields:
--|
--| Bytes Reference to the Byte_Array that contains the
--| message digest bytes.
--+------------------------------------------------------------------
type Message_Digest is new Ada.Finalization.Controlled with
record
Bytes : Byte_Array_Ptr := null;
end record;
---------------------------------------------------------------------
-- Subprograms
---------------------------------------------------------------------
--+---[Methods inherited of Ada.Dinalization.Controlled]-------------
--| Next three subprograms are the methods inherited from
--| Ada.Finalization.Controlled that control the initialization,
--| assignment, and finalization of Message_Digest objects.
--+------------------------------------------------------------------
procedure Initialize(
Object : in out Message_Digest);
procedure Adjust(
Object : in out Message_Digest);
procedure Finalize(
Object : in out Message_Digest);
---------------------------------------------------------------------
-- Constants
---------------------------------------------------------------------
--+---[Null_Message_Digest]------------------------------------------
--| Constant that represents a null message digest object.
--+------------------------------------------------------------------
Null_Message_Digest : constant Message_Digest :=
(Ada.Finalization.Controlled with
Bytes => null);
end ACF.Hash.Message_Digests