<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
       "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>CAKE Basic Types</title>
  <meta name="Version" content="$Rev$ - $URL$" />
  <link rev="made" href="mailto:eric-www@omnifarious.org" />
  <link rel="stylesheet" href="protodesc.css" type="text/css" />
  <style type="text/css">
td p {
   margin-top: 0;
}
  </style>
</head>

<body>
<p>CAKE has a number of basic types that repeatedly show up in its messages.
Here is some detail on what those types look like and what they're for. The
number of types is kept purposely small to simplify software designed to
encode and decode CAKE messages.</p>

<p>These types have a canonical binary representation, but this does not
preclude their representation in other formats, though the exact details of
such representations are not described in this document. All implementations
<strong>must</strong> understand the binary representation.</p>

<p>The reason I've chosen a binary representation as canonical is that
cryptography requires that messages in transit retain their precise forms.
Changes in whitespace or character encoding defeat digital signature and
message authentication algorithms that are designed to ensure message
integrity.</p>

<h2>Brief, explanatory descriptions</h2>
<dl class="typelist">
  <dt><a id="count"><em>count</em></a></dt>
    <dd><p>A <em>count</em> is a positive integer of limited size. The limit
      on the size of a <em>count</em> is quite large, and should be large
      enough that you could concievably use it to count all of the subatomic
      particles in the visible universe. The limited size is acceptable as a
      <em>count</em> is supposed to be a count of something that exists. It
      is not meant to represent any arbitrary number.</p>
      <a href="#count_detail">Link to octet-by-octet description</a></dd>
  <dt><a id="key_name"><em>key name</em></a></dt>
    <dd><p>A <em>key name</em> is a fixed length string of octets holding the
      unique identifier for a public key. It is the secure hash of a
      serialized representation of the key that includes the type (RSA,
      ECRSA, etc&hellip;) of the key.</p>
      <a href="#key_name_detail">Link to octet-by-octet description</a></dd>
  <dt><a id="vls"><em>variable length string</em></a></dt>
    <dd><p>This is actually a compound type. Since it's very common, it's
      listed here. It consists of a <em>count</em> followed by that many
      bytes of data. This structure is used for almost every variable length
      data component in CAKE.</p>
      <a href="#vls_detail">Link to octet-by-octet description</a></dd>
</dl>

<h2>Detailed descriptions</h2>

<h3><a id="count_detail">Type: <em>count</em></a></h3>

<div class="type">
<p>A <em>count</em> is a positive integer of limited size. The limit on the
size of a <em>count</em> is quite large, and should be large enough that you
could concievably use it to count all of the subatomic particles in the
visible universe. The limited size is acceptable as a <em>count</em> is
supposed to be a count of something that exists. It is not meant to represent
any arbitrary number.</p>

<p><em>count</em>s are encoded rather strangely to minimize their length.
There are three main ways of encoding a <em>count</em>, and they are each
good for a particular range of <em>count</em> values.</p>

<table border="1">
  <thead>
    <tr>
      <td>First octet values</td>
      <td>Value range</td>
      <td>Explanation</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td class="value"><code>0&nbsp;-&gt;&nbsp;222</code></td>
      <td class="range"><code>0&nbsp;-&gt;&nbsp;222</code></td>
      <td><p>A single octet <em>count</em> for very small values. The value
        of the octet is the same as the value of the <em>count</em>.</p>
      </td>
    </tr>
    <tr>
      <td class="value"><code>223&nbsp;-&gt;&nbsp;254</code></td>
      <td class="range"><code>223&nbsp;-&gt;&nbsp;8414</code></td>
      <td><p>A double octet <em>count</em> for medium sized values. This is
        the most complex encoding. Here is some psuedocode showing how the
        octets (in <code>count_octets</code> produce the <em>count</em> value
        (in <code>count_value</code>):<br/><br/>
        <math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
          <declare type="vector">
            <ci>count_octets</ci>
          </declare>
          <mtable columnalign="left">
            <mtr><mtd>
              <apply>
                <eq/>
                <ci>upper_5bits</ci>
                <apply>
                  <minus/>
                  <apply> <selector/> <ci>count_octets</ci> <cn>0</cn> </apply>
                  <cn>223</cn>
                </apply>
              </apply>
            </mtd></mtr>
            <mtr><mtd>
              <apply>
                <eq/>
                <ci>lower_8bits</ci>
                <apply> <selector/> <ci>count_octets</ci> <cn>1</cn> </apply>
              </apply>
            </mtd></mtr>
            <mtr><mtd>
              <apply>
                <eq/>
                <ci>count_value</ci>
                <apply>
                  <plus/>
                  <semantics>
                    <apply>
                      <times/>
                      <apply> <power/> <cn>2</cn> <cn>8</cn> </apply>
                      <ci>upper_5bits</ci>
                    </apply>
                    <annotation-xml encoding="MathML-Presentation">
                      <mrow>
                        <msup><mn>2</mn><mn>8</mn></msup>
                        <mo>*</mo>
                        <mi>upper_5bits</mi>
                      </mrow>
                    </annotation-xml>
                  </semantics>
                  <ci>lower_8bits</ci>
                  <cn>223</cn>
                </apply>
              </apply>
            </mtd></mtr>
          </mtable>
        </math>
        </p>
<!--
        <pre>upper_5bits &lt;- count_octets[0] - 223
lower_8bits &lt;- count_octets[1]
count_value &lt;- (256 * upper_5bits) + lower_8bits + 223</pre>
        <br />
-->
        <p>From 223 to 254, there are 32 values, which is 5 bits of
        information. The second octet may have any value, which is 8 bits of
        information. 223 is added because if the <em>count</em>'s value was
        less than 223, you could've encoded it using a single octet
        <em>count</em>.</p>
      </td>
    </tr>
    <tr>
      <td class="value"><code>255</code></td>
      <td
        class="range"><code>0&nbsp;-&gt;&nbsp;2<sup>4080</sup>&nbsp;-&nbsp;1</code></td>
      <td><p>This <em>count</em> consists of a variable number of octets. The
        first octet is the marker value, 255. The second is the half the
        number of octets to follow. A value of 0 for the second octet is not
        allowed, though it may be used in some special cases where a
        <em>count</em> also needs to hold some non-<em>count</em> flag value.
        Such uses should be minimal, and will be flagged prominently in
        documentation when they occur.</p>

        <p>The string of octets that follows may have leading 0s. The octets
        are interpreted in big-endian order.</p>

        <p>This representation is rather simple. If you want to write as
        simple an implementation as you can, you can simply encode all values
        this way, even though you will often be wasting a lot of space. Your
        implementation <strong>must</strong>, of course, be able to read all
        the representations.</p>
      </td>
    </tr>
  </tbody>
</table>

<h4>Example <em>count</em>s</h4>

<p>Here are a few octet strings in hex representing <em>count</em>s, and the
corresponding <em>count</em> value in decimal.</p>

<table>
  <tbody>
    <tr>
      <td>Hex string</td>
      <td/>
      <td>Count value</td>
    </tr>
    <tr>
      <td><code>00</code></td>
      <td>=</td>
      <td>0</td>
    </tr>
    <tr>
      <td><code>ff 01 00 00</code></td>
      <td>=</td>
      <td>0</td>
    </tr>
    <tr>
      <td><code>a3</code></td>
      <td>=</td>
      <td>163</td>
    </tr>
    <tr>
      <td><code>de</code></td>
      <td>=</td>
      <td>222</td>
    </tr>
    <tr>
      <td><code>df 00</code></td>
      <td>=</td>
      <td>223 <span class="note">(
          <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
            <apply>
              <eq/> <cn>0xdf</cn> <cn>223</cn>
            </apply>
            <mo separator="true">,</mo>
            <apply>
              <eq/>
              <apply>
                <plus/>
                <apply>
                  <times/>
                  <apply> <power/> <cn>2</cn> <cn>8</cn> </apply>
                  <apply> <minus/> <cn>223</cn> <cn>223</cn> </apply>
                </apply>
                <cn>0x00</cn>
              </apply>
              <cn>0</cn>
            </apply>
            <mo separator="true">,</mo>
            <apply>
              <eq/>
              <apply>
                <plus/> <cn>0</cn> <cn>223</cn>
              </apply>
              <cn>223</cn>
            </apply>
          </math>
          )</span>
      </td>
    </tr>
    <tr>
      <td><code>e0 00</code></td>
      <td>=</td>
      <td>479 <span class="note">(
          <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
            <apply>
              <eq/> <cn>0xe0</cn> <cn>224</cn>
            </apply>
            <mo separator="true">,</mo>
            <apply>
              <eq/>
              <apply>
                <plus/>
                <apply>
                  <times/>
                  <apply> <power/> <cn>2</cn> <cn>8</cn> </apply>
                  <apply> <minus/> <cn>224</cn> <cn>223</cn> </apply>
                </apply>
                <cn>0x00</cn>
              </apply>
              <cn>256</cn>
            </apply>
            <mo separator="true">,</mo>
            <apply>
              <eq/>
              <apply>
                <plus/> <cn>256</cn> <cn>223</cn>
              </apply>
              <cn>479</cn>
            </apply>
          </math>
          )</span>
      </td>
    </tr>
    <tr>
      <td><code>fe ff</code></td>
      <td>=</td>
      <td>8414 <span class="note">(
          <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
            <apply> <eq/> <cn>0xfe</cn> <cn>254</cn> </apply>
            <mo separator="true">,</mo>
            <apply>
              <eq/>
              <apply>
                <plus/>
                <apply>
                  <times/>
                  <apply> <power/> <cn>2</cn> <cn>8</cn> </apply>
                  <apply> <minus/> <cn>254</cn> <cn>223</cn> </apply>
                </apply>
                <cn>0xff</cn>
              </apply>
              <cn>8191</cn>
            </apply>
            <mo separator="true">,</mo>
            <apply>
              <eq/>
              <apply> <plus/> <cn>8191</cn> <cn>223</cn> </apply>
              <cn>8414</cn>
            </apply>
          </math>
          )</span>
      </td>
    </tr>
    <tr>
      <td><code>ff 01 20 de</code></td>
      <td>=</td>
      <td>8414</td>
    </tr>
    <tr>
      <td><code>ff 01 01 00</code></td>
      <td>=</td>
      <td>256</td>
    </tr>
    <tr>
      <td><code>ff 02 ff ff ff ff</code></td>
      <td>=</td>
      <td>4294967295 <span class="note">
          (<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
            <apply><minus/>
              <apply><power/><cn>2</cn><cn>32</cn></apply>
              <cn>1</cn></apply>
          </math>)
      </span></td>
    </tr>
    <tr>
      <td><code>ff 02 00 00 00 01</code></td>
      <td>=</td>
      <td>1</td>
    </tr>
    <tr>
      <td><code>ff 02 00 00 01</code></td>
      <td>&#x2204;</td>
      <td>Illegal value</td>
    </tr>
    <tr>
      <td><code>ff 00</code></td>
      <td>&#x2204;</td>
      <td>Illegal value</td>
    </tr>
  </tbody>
</table>
</div>

<h3><a id="key_name_detail">Type: <em>key name</em></a></h3>

<div class="type">
<p>A <em>key name</em> is very simple. It is 32 octets of data. The 32 octets
are generated by using SHAD-256 (SHAD-256 vs SHA-256 is described elswhere)
on the canonical representation of the <strong>public key</strong> data for
that key. It is also known as a <em>key id</em>.</p>

<p>It's possible for two distinct keys to have the same name. If the SHAD-256
hash function has a fairly even distribution, it is so astronomically
unlikely as to not even be worth thinking about. I recommend ignoring this
possibility.</p>

<p>There is also a canonical ASCII representation of a <em>key name</em>.
This is the representation when displaying it someplace where someone might
actually read it. It's not very comprehensible, but it works. The canonical
representation is the <em>key name</em> encoded in Base32 as described in <a
href="http://www.faqs.org/rfcs/rfc3548.html">RFC 3548</a> with trailing
'<code>=</code>' signs removed.</p>

<p>Here's an example canonical ASCII representation of a <em>key
name</em>:<br />
<code>2BS2C2HOG62754DFYSMTNMNVFCZA7YQXRPRXNIOF67LNBZNZAK3A</code></p>
</div>

<h3><a id="vls_detail">Type: <em>variable length string</em></a></h3>

<div class="type">
<p>A <em>variable length string</em> is a <a
href="#count_detail"><em>count</em></a> followed by a number of bytes equal
to the <em>count</em>'s value. These tend to occur when there is a value
(like a key, or message body) that is of intedeterminate length, and (unlike
a <em>count</em>) does not encode its own length.</p>

<p>Note that values ending in a delimiter or tag value are not considered to
encode their own length for two main reasons. First, it must be possible to
know how big a buffer you will need to hold something after reading the first
1000 bytes or so of the message.</p>

<p>Secondly, to keep parsing simple, fast, and less prone to error, no escape
sequences must exist. That is to say, there must be no value which has
significance in one context, but not in another. The parser must be able to
find the last byte of a message without needing a state machine while going
over the message contents. Unless you limit the characters that can be in
your string, there will be no value which will fit this requirement for an
arbitrary string.</p>

<p>So, fixed length fields, or prefix length encoding is used for everything
in CAKE. No delimiter encoding is allowed.</p>
</div>
</body>
</html>

