Skip to main content

Ruoska Encoding
draft-ruoska-encoding-04

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Active".
Author Jukka-Pekka Mäkelä
Last updated 2013-03-21
RFC stream Independent Submission
Formats
Additional resources
Stream ISE state Submission Received
Consensus boilerplate Unknown
Document shepherd (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ruoska-encoding-04
Network Working Group                                         JP. Makela
Internet-Draft                                            March 21, 2013
Intended status: Experimental
Expires: September 22, 2013

                            Ruoska Encoding
                        draft-ruoska-encoding-04

Abstract

   This document describes hierarchically structured binary encoding
   format called the Ruoska Encoding (RSK).  The main design goals are
   minimal resource usage, well defined structured with good selection
   of widely known data types, and still extendable for future usage.

   The main benefit when compared to non binary hierarchically
   structured formats like XML is simplicity and minimal resource
   demands.  Even basic XML parsing is time and memory consuming
   operation.

   When compared to other binary formats like encoding formats of ASN.1
   the main benefit is simplicity.  ASN.1 with different encondings is
   complex and even simple implementation needs a lot of effort.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 22, 2013.

Copyright Notice

   Copyright (c) 2013 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal

Makela                 Expires September 22, 2013               [Page 1]
Internet-Draft               Ruoska Encoding                  March 2013

   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Document Structure . . . . . . . . . . . . . . . . . . . . . .  4
     2.1.  Endianness . . . . . . . . . . . . . . . . . . . . . . . .  5
     2.2.  String Encoding  . . . . . . . . . . . . . . . . . . . . .  5
   3.  Frame  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
     3.1.  Leading Byte . . . . . . . . . . . . . . . . . . . . . . .  6
     3.2.  Meta Frames  . . . . . . . . . . . . . . . . . . . . . . .  7
       3.2.1.  Begin Frame  . . . . . . . . . . . . . . . . . . . . .  7
       3.2.2.  End Frame  . . . . . . . . . . . . . . . . . . . . . .  7
       3.2.3.  Modifier Frame . . . . . . . . . . . . . . . . . . . .  8
       3.2.4.  Array Frame  . . . . . . . . . . . . . . . . . . . . .  9
     3.3.  Data Frames  . . . . . . . . . . . . . . . . . . . . . . . 10
       3.3.1.  Boolean Frame  . . . . . . . . . . . . . . . . . . . . 10
       3.3.2.  Integer Frames . . . . . . . . . . . . . . . . . . . . 10
       3.3.3.  Float Frames . . . . . . . . . . . . . . . . . . . . . 11
       3.3.4.  String Frame . . . . . . . . . . . . . . . . . . . . . 12
       3.3.5.  Binary Frame . . . . . . . . . . . . . . . . . . . . . 12
       3.3.6.  DateTime Frame . . . . . . . . . . . . . . . . . . . . 13
       3.3.7.  Timestamp Frame  . . . . . . . . . . . . . . . . . . . 14
     3.4.  Extended Frames  . . . . . . . . . . . . . . . . . . . . . 15
   4.  Identifiers  . . . . . . . . . . . . . . . . . . . . . . . . . 17
     4.1.  Identifier Types in Leading Byte . . . . . . . . . . . . . 17
     4.2.  Null Identifier  . . . . . . . . . . . . . . . . . . . . . 17
     4.3.  Integer Identifiers  . . . . . . . . . . . . . . . . . . . 18
     4.4.  String Identifier  . . . . . . . . . . . . . . . . . . . . 18
   5.  Implementation Notes . . . . . . . . . . . . . . . . . . . . . 19
     5.1.  Minimal Requirements . . . . . . . . . . . . . . . . . . . 19
     5.2.  Forward Compatibility  . . . . . . . . . . . . . . . . . . 19
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 20
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 21
   8.  Normative References . . . . . . . . . . . . . . . . . . . . . 22
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 23

Makela                 Expires September 22, 2013               [Page 2]
Internet-Draft               Ruoska Encoding                  March 2013

1.  Introduction

   The RSK is very suitable for fast prototyping and studying data
   exchange and storage solutions in environments with wide range of
   different kind of devices from small microcontrollers to mainframe
   computers.

   Only small subset of all features and data types are strictly
   required for every single implementation.  This enables
   implementations for minimal systems like microcontrollers with modest
   computing capacity and memory.  Minimal requirements are defined in
   Section 5.1.

   This version defines also mechanisms for later extensions.  Actual
   structures and data types are not known but common structure for
   extended features is defined so they can be skipped by implementation
   versions which are not able interpret them.  See Section 5.2 for
   details.

Makela                 Expires September 22, 2013               [Page 3]
Internet-Draft               Ruoska Encoding                  March 2013

2.  Document Structure

   The principal entity of RSK document is frame.  Two main classes of
   frames exist.  Meta Frames to define structure and Data Frames to
   hold actual payload data.  Additional frame class is Extended Frame
   which enables forward compatibility with future versions.  See
   Section 5.2 for details.

   All frames start with Leading Byte which defines frame type and some
   type depended instructions.  Some meta frames and all data frames can
   be tagged with an identifier.  Identifier type is defined in Leading
   Byte.  If identifier exists it is placed right after the Leading
   Byte.  In Data Frames payload comes after identifier.  Meta Frames
   may also have payload or special fields or both.  Data type of the
   payload is defined by frame type and type depended instructions.  All
   frame types are explained in Section 3.

   All implementations may not be able to handle all frame types but
   minimal requirements are defined in Section 5.1.

   RSK document is structured as finite tree.  The tree is rooted to
   Begin Frame.  After the rooting Begin Frame follows data frames as
   leafs and Begin - End Frame pairs as branches.  Branches may contain
   data frames as leafs and again Begin - End Frame pairs as sub
   branches.  Nesting levels start from 0 and maximum level is
   artifially limited to 255 to keep implementations simple.

   RSK document always ends with End Frame.  Use of End Frame is two
   fold.  It is used to return from branch to parent level and terminate
   the document.  So document must always start with Begin Frame and end
   with End Frame.  Root nesting level 0 must not contain any other than
   rooting Begin and terminating End Frames.  Between root Begin and
   terminating End Frame is nesting level 1.  Nesting level 1 may
   contain data frames or branches or both.

   Example Tree Structure

   0  1  2  Nesting levels
   |  |  |
   Begin[id:tractor]                              Begin Frame at level 0
   |  String[id:manufacturer, value:Valmet]         Leaf at level 1
   |  String[id:model, value:33D]                   Leaf at level 1
   |  Begin[id:engine]                              Branch at level 1
   |  |  String[id:fuel, value:Diesel]                Leaf at level 2
   |  |  Int8[signed:true, id:horsepower, value:37]   Leaf at level 2
   |  End                                           Ending branch
   End                                            Terminating at level 0

Makela                 Expires September 22, 2013               [Page 4]
Internet-Draft               Ruoska Encoding                  March 2013

                         Figure 1: Tree Structure

2.1.  Endianness

   Big-endian networking byte order is used.  Endianness applies to all
   integer and floating point numbers.  This includes payload of any
   data frames like Integer, Float, and Timestamp and 16-bits wide
   integer identifier values and also meta data fields like length of
   payload.  Canonical network byte order is fully described in RFC791,
   Appendix B.

2.2.  String Encoding

   All strings are UTF-8 encoded.  This applies to string identifiers
   and payload of String and DateTime Frames.

   Implementations using String Frame, String Identifier, or DateTime
   Frame must be able to validate UTF-8 encoding.  See RFC 3629
   [RFC3629] for details.

Makela                 Expires September 22, 2013               [Page 5]
Internet-Draft               Ruoska Encoding                  March 2013

3.  Frame

   As mentioned earlier the principal entity is frame.  This section
   explains all frame types and type dependent special instructions in
   detail.

3.1.  Leading Byte

   All frames start with Leading Byte.  Leading Byte determines frame
   type and type dependent instructions.  The most significant bit is
   reserved for Extended Frames which may be introduced in later
   versions.  See Section 3.4 and Section 5.2 for details.

   Leading Byte is presented as bit array where left-most bit is the
   most significant bit.  MSB 0 bit numbering scheme is used with two
   exceptions.  Left-most bit is reserved for Extended Frame and thus
   marked as 'X' for all Leading Byte definitions.  Also some bits are
   marked with 'R' meaning that they are reserved for later use and must
   not be set in this version.

   Leading Byte is followed by frame type dependent fields like
   Identifier or Payload or both.  These fields are presented as labeled
   byte blocks with possible lengths in bytes or in kilobytes like 64k.

      Leading Byte    Example Field   Example Payload
   +-+-------+-----+ +-------------+ +---------------+
   |X|1|2|3|4|5|6|7| |   4 or 8    | |    0 - 64k    |
   +-+-------+-----+ +-------------+ +---------------+
    | \     / \   /
    |  \   /   \ /
    |   \ /     | Frame type dependent instructions bits
    |    |
    |    | Frame type bits
    |
    | Extended frame bit

                               Leading Byte

   Example Field:  Example of possible frame type dependent byte field.
      4 or 8 means that field can be 4 or 8 bytes long.  Actual length
      can be determined by frame type, instruction bits, or some other
      field.

   Example Payload:  Example of possible frame type dependent payload
      field. 0 - 64k means that field can be from 0 to 65535 bytes long.
      Actual length can be determined by frame type, instruction bits,
      or some other field.

Makela                 Expires September 22, 2013               [Page 6]
Internet-Draft               Ruoska Encoding                  March 2013

   Frame type dependent instructions bits:  These bits determine type
      dependent instructions.  See specific frame type sections for
      details.

   Frame type bits:  This bit field determines frame type.

   Extended frame bit:  Extended frame bit.  See Section 3.4 for
      details.

3.2.  Meta Frames

   Meta Frames define document structure.  Some of the Meta Frames are
   optional for minimal implementations.  See Section 5.1 for details.

3.2.1.  Begin Frame

   Document and branches starts with Begin Frame.  Begin Frame may have
   an identifier.  More details about tree structure see Section 2.

     Leading Byte     Identifier
   +-+-------+-+---+ +----------+
   |X|1|2|3|4|R|6|7| | 0 - 256  |
   +-+-------+-+---+ +----------+
      \     /   \ /
       \   /     | Id bits
        \ /
         | Type bits

                                Begin Frame

   Identifier & Id bits:  See Section 4 for details.

   Type bits:  Begin Frame type: 0000

3.2.2.  End Frame

   End Frame is used to return from branch to parent level in tree
   structure and also used to terminate a document.  More details about
   tree structure see Section 2.

     Leading Byte
   +-+-------+-----+
   |X|1|2|3|4|R|R|R|
   +-+-------+-----+
      \     /
       \   /
        \ /
         | Type bits

Makela                 Expires September 22, 2013               [Page 7]
Internet-Draft               Ruoska Encoding                  March 2013

                                 End Frame

   Type bits:  End Frame type: 0001

3.2.3.  Modifier Frame

   Modifier Frame is used to apply a modifier for example compression or
   encryption to same portions of document.  RSK does not define any
   modifiers.  When used they are defined in specifications based on
   RSK.

   Modified payload must consists of valid frames.  On reading phase
   payload and meta data is passed to demodifier routine and then
   handled like ordinary frames.  Modifier Frame is wrapper for other
   frames but not a sub branch for document tree structure.  Payload may
   contain sub branches but branches must return to same nesting level
   as at beginning of payload.

   Meta field is intended to be used to store modifier specific data.
   For example original data length and padding byte count for a block
   compression.  Meaning of Meta data must be defined in specifications
   based on RSK when Modifier Frame is used.

      Leading Byte   Identifier  MetLen Meta   Length   Payload
   +-+-------+-+---+ +---------+ +----+------+ +----+ +---------+
   |X|1|2|3|4|R|6|7| | 0 - 256 | | 2  | 0-4k | | 2  | | 0 - 64k |
   +-+-------+-+---+ +---------+ +----+------+ +----+ +---------+
      \     /   \ /
       \   /     | Id bits
        \ /
         |
         | Type bits

                         Figure 2: Modifier Frame

   Identifier & Id bits:  See Section 4 for details.

   MetLen:  16-bits wide unsigned integer telling length of meta data.
      MetLen must not exceed 4095 bytes!

   Meta:  Custom meta data.

   Length:  16-bits wide unsigned integer telling length of modified
      payload data.

Makela                 Expires September 22, 2013               [Page 8]
Internet-Draft               Ruoska Encoding                  March 2013

   Payload:  Modified payload data.

   Type bits:  Modifier Frame type: 0010

3.2.4.  Array Frame

   Fixed length Integer or Float frames with null or integer identifier
   can be enclosed into an array.  This saves some resources when
   dealing with large number of items.  This can be also used to make
   portions of encoded document random accessible.

   Array itself and each item may have identifiers.  All items are same
   type.  All items have identifier of same type.  Frame and identifier
   type for all items are defined by CLB (Common Leading Byte).

     Leading Byte    Identifier   CLB    Length     II      IP
   +-+-------+-+---+ +---------+ +---+ +-------+ +-------+-------+
   |X|1|2|3|4|5|6|7| | 0 - 256 | | 1 | | 1 - 2 | | 0 - 2 | 1 - 8 | * * *
   +-+-------+-+---+ +---------+ +---+ +-------+ +-------+-------+
      \     / | \ /                              |                     |
       \   /  |  | Id bits                       \---- Array items ----/
        \ /   |
         |    | Length bit
         |
         | Type bits

                                Array Frame

   Identifier & Id bits:  Array identifier.  See Section 4 for details.

   CLB:  Common Leading Byte for all Items.  Determines type of Item and
      it's identifier.  Frame type must be Integer or Float and
      identifier type must be Null or Integer.

   Length:  8 or 16-bits wide unsigned integer telling length of array
      items in bytes.

   II:  Item Identifier.  See Section 4 for details.

   IP:  Item Payload.

   Length bit:  If bit is set then Length is 16-bits otherwise 8-bits
      wide unsigned integer.

   Type bits:  Array Frame type: 0011

Makela                 Expires September 22, 2013               [Page 9]
Internet-Draft               Ruoska Encoding                  March 2013

3.3.  Data Frames

   Data Frames are collection of widely used data types.  There are
   frames for boolean, integer and floating point numbers, UTF-8 encoded
   strings, dates, and timestamps.  There is also frame for raw binary
   data.  All data frames can be tagged with an identifier.

3.3.1.  Boolean Frame

   Boolean frame can hold single True or False value.

      Leading Byte    Identifier
   +-+-------+-+---+ +----------+
   |X|1|2|3|4|5|6|7| | 0 - 256  |
   +-+-------+-+---+ +----------+
      \     / | \ /
       \   /  |  | Id bits
        \ /   |
         |    | Boolean bit
         |
         | Type bits

                               Boolean Frame

   Identifier & Id bits:  See Section 4 for details.

   Boolean bit:  If Boolean bit is set when boolean value is True
      otherwise False.

   Type bits:  Boolean Frame type: 0100

3.3.2.  Integer Frames

   Wide range of integer types are supported.  Integer width is defined
   by choosing corresponding Integer Frame type.  Integers can be
   defined as unsigned by setting Unsigned bit in Leading Byte otherwise
   they are signed.  Negative values of signed integers are presented in
   two's complement notation.

   Integer payload is always stored in big-endian format.  See
   Section 2.1 for details.

Makela                 Expires September 22, 2013              [Page 10]
Internet-Draft               Ruoska Encoding                  March 2013

      Leading Byte    Identifier       Payload
   +-+-------+-+---+ +----------+ +--------------+
   |X|1|2|3|4|5|6|7| | 0 - 256  | |  1,2,4 or 8  |
   +-+-------+-+---+ +----------+ +--------------+
      \     / | \ /
       \   /  |  | Id bits
        \ /   |
         |    | Unsigned bit
         |
         | Type bits

                              Integer Frames

   Identifier & Id bits:  See Section 4 for details.

   Unsigned bit:  If Unsigned bit is set when payload is unsigned
      otherwise signed integer.

   Payload:  Payload integer value.

   Type bits:  Integer Frame types:

      0101  8-bits wide integer.

      0110  16-bits wide integer.

      0111  32-bits wide integer.

      1000  64-bits wide integer.

3.3.3.  Float Frames

   Floating point number precision is defined by choosing corresponding
   Float Frame type.  Floats are presented in IEEE754 standard format
   and endianness big-endian.  See Section 2.1 for details.

      Leading Byte    Identifier      Payload
   +-+-------+-+---+ +----------+ +------------+
   |X|1|2|3|4|R|6|7| | 0 - 256  | |  2,4 or 8  |
   +-+-------+-+---+ +----------+ +------------+
      \     /   \ /
       \   /     | Id bits
        \ /
         |
         |
         | Type bits

                               Float Frames

Makela                 Expires September 22, 2013              [Page 11]
Internet-Draft               Ruoska Encoding                  March 2013

   Identifier & Id bits:  See Section 4 for details.

   Payload:  Payload float value.

   Type bits:  Float Frame types:

      1001  16-bits wide half precision float.

      1010  32-bits wide single precision float.

      1011  64-bits wide double precision float.

3.3.4.  String Frame

   String Frame can hold UTF-8 encoded string.  If implementation
   supports String Frame it must be able to validate UTF-8 encoding.
   See Section 2.2 for details.

      Leading Byte    Identifier   Length       Payload
   +-+-------+-+---+ +----------+ +-------+ +-------------+
   |X|1|2|3|4|5|6|7| | 0 - 256  | | 1 - 2 | |   0 - 64k   |
   +-+-------+-+---+ +----------+ +-------+ +-------------+
      \     / | \ /
       \   /  |  | Id bits
        \ /   |
         |    | Length bit
         |
         | Type bits

                               String Frame

   Identifier & Id bits:  See Section 4 for details.

   Length:  8 or 16-bits wide unsigned integer telling length of string
      in bytes.

   Length bit:  If bit is set then Length is 16-bits otherwise 8-bits
      wide unsigned integer.

   Payload:  UTF-8 encoded string.

   Type bits:  String Frame type: 1100

3.3.5.  Binary Frame

   Single Binary Frame can hold up to 65535 bytes and obviously a
   document may contain as many binary frames as needed.  So the only
   issue with big binary masses is data fragmentation to multiple

Makela                 Expires September 22, 2013              [Page 12]
Internet-Draft               Ruoska Encoding                  March 2013

   frames.

      Leading Byte    Identifier   Length       Payload
   +-+-------+-+---+ +----------+ +-------+ +-------------+
   |X|1|2|3|4|5|6|7| | 0 - 256  | | 1 - 2 | |   0 - 64k   |
   +-+-------+-+---+ +----------+ +-------+ +-------------+
      \     / | \ /
       \   /  |  | Id bits
        \ /   |
         |    | Length bit
         |
         | Type bits

                               Binary Frame

   Identifier & Id bits:  See Section 4 for details.

   Length:  8 or 16-bits wide unsigned integer telling length of payload
      in bytes.

   Length bit:  If bit is set then Length is 16-bits otherwise 8-bits
      wide unsigned integer.

   Payload:  Binary payload.

   Type bits:  Binary Frame type: 1101

3.3.6.  DateTime Frame

   DateTime Frame holds date or date and time in UTC timescale as UTF-8
   encoded string.  Date is presented as ("YYYY-MM-DD") and DateTime is
   ("YYYY-MM-DDTHH:MM:SS.SSSZ").  String formats are compatible with RFC
   3339 [RFC3339].

   If implementation supports DateTime Frame it must be able to validate
   UTF-8 encoding.  See Section 2.2 for details.

      Leading Byte    Identifier  Date/DateTime
   +-+-------+-+---+ +----------+ +-----------+
   |X|1|2|3|4|5|6|7| | 0 - 256  | | 10 or 24  |
   +-+-------+-+---+ +----------+ +-----------+
      \     / | \ /
       \   /  |  | Id bits
        \ /   |
         |    | DateTime bit
         |
         | Type bits

Makela                 Expires September 22, 2013              [Page 13]
Internet-Draft               Ruoska Encoding                  March 2013

                              DateTime Frame

   Identifier & Id bits:  See Section 4 for details.

   Date/DateTime:  Date or DateTime string.

   DateTime bit:  If bit is set then payload is DateTime otherwise Date.

   Type bits:  DateTime Frame type: 1110

3.3.7.  Timestamp Frame

   Timestamp is very similar, with some exceptions, as NTP Date Format
   defined in RFC 5905 [RFC5905].

   Differences to NTP Date Format

   Width of Era field:  NTP Date Format has 32-bits wide Era field.
      Here Era is only 8-bits wide.  Intepretation is same but with
      narrowed range.  Epoch is same so Era 0 starts at 1900-01-01 00:
      00:00 UTC like in NTP Date Format.

   Fraction field is optional:  In NTP Date Format Fraction field always
      exists.  Here it is optional.  It exists only if Fraction bit is
      set in Leading Byte.

   Width of Fraction Field:  NTP Date Format uses 64-bits wide Fraction
      field.  Here fraction is only 32-bits wide and thus capable to 232
      picosecond resolution.

      Leading Byte    Identifier   Era   Offset   Fraction
   +-+-------+-+---+ +----------+ +---+ +------+ +--------+
   |X|1|2|3|4|5|6|7| | 0 - 256  | | 1 | |  4   | | 0 or 4 |
   +-+-------+-+---+ +----------+ +---+ +------+ +--------+
      \     / | \ /
       \   /  |  | Id bits
        \ /   |
         |    | Fraction bit
         |
         | Type bits

                              Timestamp Frame

Makela                 Expires September 22, 2013              [Page 14]
Internet-Draft               Ruoska Encoding                  March 2013

   Identifier & Id bits:  See Section 4 for details.

   Era:  8-bit signed integer telling the era of timestamp.  See RFC
      5905 [RFC5905] for era definitions.

   Offset:  32-bit unsigned integer holding number of seconds since
      beginning of the Era.

   Fraction:  32-bit unsigned integer holding fractions of second.

   Fraction bit:  If Fraction bit is set then optional Fraction field
      exists.

   Type bits:  Timestamp Frame type: 1111

3.4.  Extended Frames

   Extended Frame is concept to introduce new structures and data types
   to future versions of RSK.  The most significant bit in Leading Byte
   is reserved for Extended Frames.  In this version Extended bit must
   not be set when writing a RSK document.

   Forward compatible implementations must be able to detect Extended
   Frames and interprete Length bit and Length field to get correct
   length of payload.  Payload can be then skipped and processing
   continues with next frame.

   Extended Frame is not part of Minimal Requirements see Section 5.1.

      Leading Byte       Length       Payload
   +-+-----------+-+   +--------+   +---------+
   |X|1|2|3|4|5|6|7|   | 1 - 2  |   | 0 - 64k |
   +-+-----------+-+   +--------+   +---------+
    | \         / |
    |  \---+---/  | Length bit
    |      |
    |      | Type and instructions bits
    |
    | Extended bit

                              Extended Frames

   Length:  8 or 16-bits wide unsigned integer telling length of payload
      in bytes.

Makela                 Expires September 22, 2013              [Page 15]
Internet-Draft               Ruoska Encoding                  March 2013

   Payload:  Payload can be skipped in this version.

   Length bit:  If bit is set then Length is 16-bits otherwise 8-bits
      wide unsigned integer.

   Type and instructions bits:  Extended Frame type and instruction bits
      will be defined in future Ruoska Encoding versions.  These can be
      skipped in this version.

   Extended bit:  If set frame must be handled as Extended Frame.

Makela                 Expires September 22, 2013              [Page 16]
Internet-Draft               Ruoska Encoding                  March 2013

4.  Identifiers

   All data frames and some of the meta frames can be tagged with an
   identifier.  Identifier can be defined as 8 or 16-bit wide unsigned
   integer or as length-prefixed UTF-8 encoded string.  If identifier is
   not needed it can be set to Null.

   Frame's Leading Byte tells type of identifier.  Identifier bytes are
   placed immediately after the Leading Byte.  In case of integer
   identifier there is one or two bytes depending on selected integer
   width.  String identifier can take up to 256 bytes.  See following
   sections for details.

   All identifier types are not required for minimal implementations.
   See Section 5.1 for details.

4.1.  Identifier Types in Leading Byte

   Two least significant bits of Leading Byte are reserved for Id bits
   in all frame types which can be tagged with an identifier.

     Leading Byte     Identifier
   +-+---------+---+ +----------+
   |X|1|2|3|4|5|6|7| | 0 - 256  |
   +-+---------+---+ +----------+
                \ /
                 | Id bits

                             Identifier Types

   Id bits values and identifier types:

   00 Null Identifier.  See Section 4.2.

   01 8-bits wide Integer Identifier.  See Section 4.3.

   10 16-bits wide Integer Identifier.  See Section 4.3.

   11 String Identifier.  See Section 4.4

4.2.  Null Identifier

   Some frames in a document may not need identifier so it can be left
   empty by setting it Null in Leading Byte.

Makela                 Expires September 22, 2013              [Page 17]
Internet-Draft               Ruoska Encoding                  March 2013

4.3.  Integer Identifiers

   Integer identifier types are 8 or 16-bits wide unsigned integers.
   Integer identifiers are presented in big-endian format as all numbers
   in RSK.  See Section 2.1 for details.

4.4.  String Identifier

   String identifier is length-prefixed and UTF-8 encoded.  Length is
   presented by one byte as 8-bits wide unsigned integer at the
   beginning of identifier field.  String identifier itself can be 255
   bytes long at maximum.

   If implementation supports string identifiers it must be able to
   validate UTF-8 encoding.  See Section 2.2 for details.

     Leading Byte      Length     UTF-8 Encoded String
   +---------------+ +--------+ +----------------------+
   |X|1|2|3|4|5|6|7| | 1 byte | |    0 - 255 bytes     |
   +---------------+ +--------+ +----------------------+
                     |                                 |
                     \---------- Identifier -----------/

                             String Identifier

Makela                 Expires September 22, 2013              [Page 18]
Internet-Draft               Ruoska Encoding                  March 2013

5.  Implementation Notes

   RSK is designed so that implementations could have very small memory
   and other resource demands.  Pay attention to memory usage and try to
   perform IO operations efficiently.

   Implementations must make sure that well formed documents are
   written.  On reading phase any deformation in document or frame
   structure must be detected and handled as error condition.

   Implementations can vary many ways depending on environment and
   usage.  Minimal Requirements define absolute minimum requirements for
   all implementations.  All other feature can be left out to save
   resources in implementations for small devices.  See Section 5.1 for
   details.

5.1.  Minimal Requirements

   Absolute minimal requirements for all implementations to be
   compatible with RSK are listed here.

   Binary Frame Payload length:  8 bytes.

   Nesting levels:  0 - 255

   Meta Frame types:  Begin and End Frames.

   Identifier types:  Null and Integer identifiers.

   Data Frame types:  Boolean, Binary, and 8 and 16-bits wide Integer
      Frames.

   All other features like frame types Array, Modifier, Float, String,
   DateTime, and Timestamp are optional.  String identifier is optional.
   Longer than 8 bytes payloads are optional.  Support for Extended
   Frames is also optional.

5.2.  Forward Compatibility

   An implementation may take advantage of Extended Frame concept to
   provide forward compatibility for later RSK versions.  This is not
   required for all implementations and can be left out if not needed.
   See Section 5.1 for Minimal Requirements and Section 3.4 for Extended
   Frame.

Makela                 Expires September 22, 2013              [Page 19]
Internet-Draft               Ruoska Encoding                  March 2013

6.  Security Considerations

   RSK is data encoding format and does not include any executable
   commands.  Implementations must make sure that any parts of encoded
   documents are not leaked into execution memory.  Even malformed
   documents must be handled so that memory leaks are avoided.

   RSK does not include any means to validate payload data integrity.
   Protocols based on RSK or underlying mechanisms which are utilized by
   those protocols must take care of this.  If data integrity is not
   checked can data get corrupted by malfunctioning devices, software,
   or malicious attackers.

   Modifier Frame enables encryption for selected portions of a
   document.  RSK does not define any encryption methods but almost any
   kind of encryption cipher could be used.  If needed encryption
   methods should be defined in specifications based on RSK.

Makela                 Expires September 22, 2013              [Page 20]
Internet-Draft               Ruoska Encoding                  March 2013

7.  IANA Considerations

   The MIME media type for RSK documents is application/ruoska.

   Type name:  application

   Subtype name:  ruoska

   Required parameters:  n/a

   Optional parameters:  n/a

Makela                 Expires September 22, 2013              [Page 21]
Internet-Draft               Ruoska Encoding                  March 2013

8.  Normative References

   [RFC3339]  Klyne, G., Ed. and C. Newman, "Date and Time on the
              Internet: Timestamps", RFC 3339, July 2002.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, November 2003.

   [RFC5905]  Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network
              Time Protocol Version 4: Protocol and Algorithms
              Specification", RFC 5905, June 2010.

Makela                 Expires September 22, 2013              [Page 22]
Internet-Draft               Ruoska Encoding                  March 2013

Author's Address

   Jukka-Pekka Makela
   Janakkala,
   Finland

Makela                 Expires September 22, 2013              [Page 23]