gcc/ada/s-sechas.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT LIBRARY COMPONENTS                          --
   4 --                                                                          --
   5 --                 S Y S T E M . S E C U R E _ H A S H E S                  --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --           Copyright (C) 2009, Free Software Foundation, Inc.             --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  This package provides common suporting code for a family of secure
  33 --  hash functions (including MD5 and the FIPS PUB 180-3 functions SHA-1,
  34 --  SHA-224, SHA-256, SHA-384 and SHA-512).
  35
  36 with Ada.Streams;
  37 with Interfaces;
  38
  39 package System.Secure_Hashes is
  40
  41    type Buffer_Type is new String;
  42    for Buffer_Type'Alignment use 8;
  43    --  Secure hash functions use a string buffer that is also accessed as an
  44    --  array of words, which may require up to 64 bit alignment.
  45
  46    --  The function-independent part of processing state:
  47    --  A buffer of data being accumulated until a complete block is ready for
  48    --  hashing.
  49
  50    type Message_State (Block_Length : Natural) is record
  51       Last   : Natural := 0;
  52       --  Index of last used element in Buffer
  53
  54       Length : Interfaces.Unsigned_64 := 0;
  55       --  Total length of processed data
  56
  57       Buffer : Buffer_Type (1 .. Block_Length);
  58       --  Data buffer
  59    end record;
  60
  61    --  The function-specific part of processing state:
  62    --  Each hash function maintains an internal state as an array of words,
  63    --  which is ultimately converted to a stream representation with the
  64    --  appropriate bit order.
  65
  66    generic
  67       type Word is mod <>;
  68       --  Either 32 or 64 bits
  69
  70       with procedure Swap (X : System.Address);
  71       --  Byte swapping function for a Word at X
  72
  73       Hash_Bit_Order : System.Bit_Order;
  74       --  Bit order of the produced hash
  75
  76    package Hash_Function_State is
  77
  78       type State is array (Natural range <>) of Word;
  79       --  Used to store a hash function's internal state
  80
  81       procedure To_Hash
  82         (H      : State;
  83          H_Bits : out Ada.Streams.Stream_Element_Array);
  84       --  Convert H to stream representation with the given bit order.
  85       --  If H_Bits is smaller than the internal hash state, then the state
  86       --  is truncated.
  87
  88    end Hash_Function_State;
  89
  90    --  Generic hashing framework:
  91    --  The user interface for each implemented secure hash function is an
  92    --  instance of this generic package.
  93
  94    generic
  95       Block_Words    : Natural;
  96       --  Number of words in each block
  97
  98       State_Words    : Natural;
  99       --  Number of words in internal state
 100
 101       Hash_Words     : Natural;
 102       --  Number of words in the final hash (must be no greater than
 103       --  State_Words).
 104
 105       Hash_Bit_Order : System.Bit_Order;
 106       --  Bit order used for conversion between bit representation and word
 107       --  representation.
 108
 109       with package Hash_State is new Hash_Function_State (<>);
 110       --  Hash function state package
 111
 112       Initial_State : Hash_State.State;
 113       --  Initial value of the hash function state
 114
 115       with procedure Transform
 116         (H : in out Hash_State.State;
 117          M : in out Message_State);
 118       --  Transformation function updating H by processing a complete data
 119       --  block from M.
 120
 121    package H is
 122
 123       pragma Assert (Hash_Words <= State_Words);
 124
 125       type Context is private;
 126       --  The internal processing state of the hashing function
 127
 128       Initial_Context : constant Context;
 129       --  Initial value of a Context object. May be used to reinitialize
 130       --  a Context value by simple assignment of this value to the object.
 131
 132       procedure Update      (C : in out Context; Input : String);
 133       procedure Wide_Update (C : in out Context; Input : Wide_String);
 134       procedure Update
 135         (C : in out Context; Input : Ada.Streams.Stream_Element_Array);
 136       --  Update C to process the given input. Successive calls to
 137       --  Update are equivalent to a single call with the concatenation
 138       --  of the inputs. For the Wide_String version, each Wide_Character is
 139       --  processed low order byte first.
 140
 141       Word_Length : constant Natural := Hash_State.Word'Size / 8;
 142       Hash_Length : constant Natural := Hash_Words * Word_Length;
 143
 144       subtype Message_Digest is String (1 .. 2 * Hash_Length);
 145       --  The fixed-length string returned by Digest, providing the
 146       --  hash in hexadecimal representation.
 147
 148       function Digest      (C  : Context)     return Message_Digest;
 149       --  Return the hash for the data accumulated with C in hexadecimal
 150       --  representation.
 151
 152       function Digest      (S : String)      return Message_Digest;
 153       function Wide_Digest (W : Wide_String) return Message_Digest;
 154       function Digest
 155         (A : Ada.Streams.Stream_Element_Array) return Message_Digest;
 156       --  These functions are equivalent to the corresponding Update (or
 157       --  Wide_Update) on a default initialized Context, followed by Digest
 158       --  on the resulting Context.
 159
 160    private
 161
 162       Block_Length : constant Natural := Block_Words * Word_Length;
 163       --  Length in bytes of a data block
 164
 165       type Context is record
 166          H_State : Hash_State.State (0 .. State_Words - 1) := Initial_State;
 167          --  Function-specific state
 168
 169          M_State : Message_State (Block_Length);
 170          --  Function-independent state (block buffer)
 171       end record;
 172
 173       Initial_Context : constant Context := (others => <>);
 174       --  Initial values are provided by default initialization of Context
 175
 176    end H;
 177
 178 end System.Secure_Hashes;