Ossasepia

November 17, 2018

SMG Comms Chapter 8: Keys Management

Filed under: Coding, SMG_Comms — Diana Coman @ 1:47 p.m.

~ This is a work in progress towards an Ada implementation of Eulora's communication protocol. Start with Chapter 1.~

This chapter makes a few changes to previous code and adds a new part to handle read/write of messages concerning keys management (4.2 and 5.3 in the current protocol specification):

  • (Changed): I've refactored the code for read/write of messages transporting Serpent keys (i.e. the code from Chapter 7 of the SMG Comms series). At the time I wrote those for Chapter 7 I wasn't even sure that I'll continue with that approach to serializing the data structure so I did not bother too much/too early with other considerents. As it turned out that the approach implemented was indeed the most appropriate for the task at hand, the next focus was on making the best use of it given that both Serpent and RSA messages that transport keys effectively have the same structure and differ only in their ID (first octet) and length of padding (due to different sizes). So there clearly was no point in repeating the actual serialization code in 2 separate places, one for Serpent messages and one for RSA messages. Instead, the common core is now done by methods that are private to the Messages package and are called with the correct parameters by the read/write methods for Serpent and RSA messages. Having previously defined RSA and Serpent message types to reflect precisely what they are, namely subtypes of the generic, raw, "Octets" type helped significantly, of course: the private read/write simply take/provide Octets and ID, focusing on the common core and ignoring the rest (which is handled by the caller since that's the point at which Serpent/RSA is a concern). As a result, the public methods are now very short since the actual work is done in the private methods:
    package body Messages is
    
      ----------------------
      -- Serpent Messages --
      ----------------------
    
      procedure Write_SKeys_SMsg( Keyset  : in Serpent_Keyset;
                                  Counter : in Interfaces.Unsigned_16;
                                  Msg     : out Raw_Types.Serpent_Msg) is
      begin
        -- call internal write on Octets with correct type id
        Write_SKeys( Keyset, Counter, SKeys_S_Type, Msg );
      end Write_SKeys_SMsg;
    
      -- Reads a Serpent keyset from given Serpent Message
      procedure Read_SKeys_SMsg( Msg     : in Raw_Types.Serpent_Msg;
                                 Counter : out Interfaces.Unsigned_16;
                                 Keyset  : out Serpent_Keyset) is
      begin
        -- check type id and call internal Read_SKeys if correct
        if Msg(Msg'First) /= SKeys_S_Type then
          raise Invalid_Msg;
        else
          Read_SKeys( Msg, Counter, Keyset );
        end if;
      end Read_SKeys_SMsg;
    
      -- writes given key mgm structure into a Serpent message
      procedure Write_KMgm_SMsg( KMgm    : in Keys_Mgm;
                                 Counter : in Interfaces.Unsigned_16;
                                 Msg     : out Raw_Types.Serpent_Msg) is
      begin
        -- call internal write of key mgm with correct type ID
        Write_KMgm( KMgm, Counter, Key_Mgm_S_Type, Msg );
      end Write_KMgm_SMsg;
    
      -- reads a key mgm structure from the given Serpent message
      procedure Read_KMgm_SMsg( Msg     : in Raw_Types.Serpent_Msg;
                                Counter : out Interfaces.Unsigned_16;
                                KMgm    : out Keys_Mgm) is
      begin
        -- check type id and call internal Read_KMgm if correct
        if Msg(Msg'First) /= Key_Mgm_S_Type then
          raise Invalid_Msg;
        else
          Read_KMgm( Msg, Counter, KMgm );
        end if;
      end Read_KMgm_SMsg;
    
      ------------------
      -- RSA Messages --
      ------------------
    
      procedure Write_SKeys_RMsg( Keyset  : in Serpent_Keyset;
                                  Counter : in Interfaces.Unsigned_16;
                                  Msg     : out Raw_Types.RSA_Msg) is
      begin
        -- call internal write of Serpent keys with correct type ID
        Write_SKeys( Keyset, Counter, SKeys_R_Type, Msg );
      end Write_SKeys_RMsg;
    
      procedure Read_SKeys_RMsg( Msg     : in Raw_Types.RSA_Msg;
                                 Counter : out Interfaces.Unsigned_16;
                                 Keyset  : out Serpent_Keyset) is
      begin
        -- check type id and call internal Read_SKeys if correct
        if Msg(Msg'First) /= SKeys_R_Type then
          raise Invalid_Msg;
        else
          Read_SKeys( Msg, Counter, Keyset );
        end if;
      end Read_SKeys_RMsg;
    
      procedure Write_KMgm_RMsg( KMgm    : in Keys_Mgm;
                                 Counter : in Interfaces.Unsigned_16;
                                 Msg     : out Raw_Types.RSA_Msg) is
      begin
        -- call internal write of key mgm with correct type ID
        Write_KMgm( KMgm, Counter, Key_Mgm_R_Type, Msg );
      end Write_KMgm_RMsg;
    
      procedure Read_KMgm_RMsg( Msg     : in Raw_Types.RSA_Msg;
                                Counter : out Interfaces.Unsigned_16;
                                KMgm    : out Keys_Mgm) is
      begin
        -- check type id and call internal Read_KMgm if correct
        if Msg(Msg'First) /= Key_Mgm_R_Type then
          raise Invalid_Msg;
        else
          Read_KMgm( Msg, Counter, KMgm );
        end if;
      end Read_KMgm_RMsg;
    
      ------------------
      -- private part --
      ------------------
      procedure Cast_LE( LE: in out Raw_Types.Octets ) is
      begin
        -- flip octets ONLY if native is big endian.
        if System.Default_Bit_Order = System.High_Order_First then
          declare
            BE: constant Raw_Types.Octets := LE;
          begin
            for I in 1..LE'Length loop
              LE(LE'First+I-1) := BE(BE'Last-I+1);
            end loop;
          end;
        end if;
        -- NOTHING to do for native little endian
      end Cast_LE;
    
      procedure Write_SKeys( Keyset  : in Serpent_Keyset;
                             Counter : in Interfaces.Unsigned_16;
                             Type_ID : in Interfaces.Unsigned_8;
                             Msg     : out Raw_Types.Octets) is
        Pos   : Integer := Msg'First;
        Check : CRC32.CRC32;
        PadLen: Integer;
        K     : Serpent.Key;
      begin
        -- write Type ID
        Msg(Pos) := Type_ID;
        Pos := Pos + 1;
    
        -- write count of keys (NB: this IS 8 bits by definition)
        Msg(Pos) := Keyset.Keys'Length;
        Pos := Pos + 1;
    
        -- write keys
        for I in Keyset.Keys'Range loop
          -- retrieve Key to write
          K := Keyset.Keys( I );
    
          -- write key itself
          Msg(Pos..Pos+K'Length-1) := K;
          -- ensure little endian order in message
          Cast_LE(Msg(Pos..Pos+K'Length-1));
          Pos := Pos + K'Length;
    
          -- write CRC of key
          Check := CRC32.CRC( K );
          Msg(Pos..Pos+3) := Raw_Types.Cast(Check);
          Cast_LE(Msg(Pos..Pos+3));
          Pos := Pos + 4;
        end loop;
    
        -- write flag
        Msg(Pos) := Keyset.Flag;
        Pos := Pos + 1;
    
        -- write message counter
        Msg(Pos..Pos+1) := Raw_Types.Cast(Counter);
        Cast_LE(Msg(Pos..Pos+1));
        Pos := Pos + 2;
    
        -- write padding as needed; endianness is irrelevant here
        PadLen := Msg'Last - Pos + 1;
        if PadLen > 0 then
          declare
            Pad : Raw_Types.Octets(1..PadLen);
          begin
            RNG.Get_Octets( Pad );
            Msg(Pos..Pos+PadLen-1) := Pad;
          end;
        end if;
    
      end Write_SKeys;
    
      procedure Read_SKeys( Msg     : in Raw_Types.Octets;
                            Counter : out Interfaces.Unsigned_16;
                            Keyset  : out Serpent_Keyset) is
        Pos: Integer := Msg'First;
      begin
        -- read type and check
        if Msg(Pos) = SKeys_S_Type or
           Msg(Pos) = SKeys_R_Type then
          Pos := Pos + 1;
        else
          raise Invalid_Msg;
        end if;
    
        -- read count of keys and check
        if Msg(Pos) in Keys_Count'Range then
          declare
            N     : Keys_Count := Keys_Count(Msg(Pos));
            KS    : Serpent_Keyset(N);
            K     : Serpent.Key;
            Check : CRC32.CRC32;
            O4    : Raw_Types.Octets_4;
            O2    : Raw_Types.Octets_2;
          begin
            Pos := Pos + 1;
            --read keys and check crc for each
            for I in 1 .. N loop
              -- read key and advance pos
              K := Msg(Pos..Pos+K'Length-1);
              Cast_LE(K);
              Pos := Pos + K'Length;
              -- read crc and compare to crc32(key)
              O4 := Msg(Pos..Pos+3);
              Cast_LE(O4);
              Check   := Raw_Types.Cast(O4);
              Pos := Pos + 4;
              if Check /= CRC32.CRC(K) then
                raise Invalid_Msg;
              end if;
              -- if it got here, key is fine so add to set
              KS.Keys(KS.Keys'First + I -1) := K;
            end loop;
            -- read and set flag
            KS.Flag := Msg(Pos);
            Pos := Pos + 1;
            -- read and set message counter
            O2 := Msg(Pos..Pos+1);
            Cast_LE(O2);
            Counter := Raw_Types.Cast(O2);
            -- rest of message is padding so it's ignored
            -- copy keyset to output variable
            Keyset := KS;
          end;
        else
          raise Invalid_Msg;
        end if;
      end Read_SKeys;
    
      -- writes given key management structure to the given octets array
      procedure Write_KMgm( KMgm    : in Keys_Mgm;
                            Counter : in Interfaces.Unsigned_16;
                            Type_ID : in Interfaces.Unsigned_8;
                            Msg     : out Raw_Types.Octets) is
        Pos   : Integer := Msg'First;
      begin
        -- write given type id
        Msg(Pos) := Type_ID;
        Pos := Pos + 1;
    
        -- write count of server keys requested
        Msg(Pos) := KMgm.N_Server;
        Pos := Pos + 1;
    
        -- write count of client keys requested
        Msg(Pos) := KMgm.N_Client;
        Pos := Pos + 1;
    
        -- write id of key preferred for further inbound Serpent messages
        Msg(Pos) := KMgm.Key_ID;
        Pos := Pos + 1;
    
        -- write count of burnt keys in this message
        Msg(Pos..Pos) := Cast( KMgm.N_Burnt );
        Pos := Pos + 1;
    
        -- if there are any burnt keys, write their ids
        if KMgm.N_Burnt > 0 then
          Msg( Pos .. Pos + KMgm.Burnt'Length - 1 ) := KMgm.Burnt;
          Pos := Pos + KMgm.Burnt'Length;
        end if;
    
        -- write the message count
        Msg(Pos..Pos+1) := Raw_Types.Cast( Counter );
        Cast_LE( Msg(Pos..Pos+1) );
        Pos := Pos + 2;
    
        -- pad with random octets until the end of Msg
        RNG.Get_Octets( Msg(Pos..Msg'Last) );
    
      end Write_KMgm;
    
      -- attempts to read from the given array of octets a key management structure
      procedure Read_KMgm( Msg     : in Raw_Types.Octets;
                           Counter : out Interfaces.Unsigned_16;
                           KMgm    : out Keys_Mgm) is
        Pos       : Integer := Msg'First;
        Burnt_Pos : Integer := Msg'First + 4;
      begin
        -- read type and check
        if Msg(Pos) = Key_Mgm_S_Type or
           Msg(Pos) = Key_Mgm_R_Type then
          Pos := Pos + 1;
        else
          raise Invalid_Msg;
        end if;
    
        -- read the count of burnt keys and check
        -- NB: Burnt_Pos IS in range of Counter_8bits since it's an octet
        declare
          N_Burnt : Counter_8bits := Counter_8bits(Msg(Burnt_Pos));
          Mgm     : Keys_Mgm(N_Burnt);
          O2      : Raw_Types.Octets_2;
        begin
          -- read count of server keys requested
          Mgm.N_Server := Msg(Pos);
          Pos := Pos + 1;
    
          -- read count of client keys requested
          Mgm.N_Client := Msg(Pos);
          Pos := Pos + 1;
    
          -- read ID of Serpent key preferred for further inbound messages
          Mgm.Key_ID   := Msg(Pos);
          Pos := Pos + 2; --skip the count of burnt keys as it's read already
    
          -- read ids of burnt keys, if any
          if N_Burnt > 0 then
            Mgm.Burnt := Msg(Pos..Pos+N_Burnt-1);
            Pos := Pos + N_Burnt;
          end if;
    
          -- read and set message counter
          O2 := Msg(Pos..Pos+1);
          Cast_LE(O2);
          Counter := Raw_Types.Cast(O2);
          -- rest of message is padding so it's ignored
          -- copy the keys mgm structure to output param
          KMgm := Mgm;
        end;
      end Read_KMgm;
    
    end Messages;
    
  • (Changed): The Keys_Mgm record in Data_Structs.ads:
    • (Changed): The array of burnt keys was initially declared as holding the actual keys rather than just the ids. I've corrected this so that now the "Burnt" part of Keys_Mgm is simply an array of Unsigned_8 (i.e. Octets type)
    • (Changed): The parameter N_Burnt (the number of IDs of burnt keys in the structure) was initially declared as Unsigned_8. However, after changing the array to the correct Octets type, there was a bit of type-trouble: on one hand, the Octets type can have any length, so the type of its range can't be limited to Unsigned_8 and Unsigned_8 is NOT a subtype of Integer (it's a modular type instead); on the other hand, N_Burnt has to appear by itself in the definition of the record type since it is a discriminant so it couldn't be cast to an Integer subtype that Octets would accept. To address this, I defined the type Counter_8bit to match precisely the meaning of N_Burnt (or any other similar counter): values between 0 and 255.
    • (Changed): Since the N_Burns counter can be 0, it follows that the array of burnt ids should *not* always be present in the record (the only way to have an array of length 0 is effectively to not have it at all). Consequently, I further changed the Keys_Mgm record declaration to reflect this:
        ------------------------------
        -- Serpent Keys Management
        subtype Counter_8bits is Natural range 0..255;
        function Cast is new Ada.Unchecked_Conversion( Counter_8bits,
                                                       Raw_Types.Octets_1 );
        function Cast is new Ada.Unchecked_Conversion( Raw_Types.Octets_1,
                                                       Counter_8bits );
        type Keys_Mgm (N_Burnt: Counter_8bits := 0) is
          record
            -- count of server keys requested
            N_Server: Interfaces.Unsigned_8;
            -- count of client keys requested
            N_Client: Interfaces.Unsigned_8;
            -- ID of Serpent key preferred for further inbound Serpent msgs.
            Key_ID  : Interfaces.Unsigned_8;
            -- IDs of Serpent keys burnt by this message
            case N_Burnt is
              when 0 =>
                null;
              when others =>
                Burnt   : Raw_Types.Octets( 1..N_Burnt );
            end case;
          end record;
      
  • (Added): I've used the Keys_Mgm record from above and the same approach as for keys messages (common core serialization in private methods that are called by public read/write with correct IDs and Octets parameters) to implement the read/write from/to messages for keys management, whether Serpent or RSA messages.
  • (Added): New tests for the new read/write methods for key management messages.
  • (Changed): The existing tests for read/write of messages transporting keys are now updated to test also the read/write to/from RSA messages of the relevant type.

The .vpatch and my signature for it is on the Reference Code Shelf as well as linked here for your convenience:

No Comments »

No comments yet.

RSS feed for comments on this post. TrackBack URL

Leave a comment

Theme and content by Diana Coman