<?xml version="1.0" encoding="UTF-8"?>

<section xml:id="extComEncryption"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude">


<info>
  <title>Encryption extension</title>
</info>

<para>
  This extension allows to configure the commercial encryption features of DMR. Almost all DMR 
  radios implement means for encrypting the traffic. This feature however, is usually illegal 
  when used within amateur radio.
</para>

<example>
  <title></title>
  <programlisting><![CDATA[commercial:
  encryptionKeys:
    - dmr: 
      id: key1
      name: Example key 1
      key: ABCD
    - rc4:
      id: key2
      name: Example key 2
      key: 0123456789
    - aes:
      id: key3
      name: Example key 3
      key: 0123456789ABCDEF0123456789ABCDEF
]]></programlisting>
</example>

<para> 
  This extension is a simple list of keys held in the global <token>commercial</token> extension.
  Each key must either be a DMR (basic), RC4 (enhanced) or AES (advanced) key. 
  To differentiate these key types, each list entry must be a mapping with a single entry. The name
  specifies the type (i.e., either <token>dmr</token>, <token>rc4</token> or <token>aes</token>). 
  The value then specifies the properties of the key.
</para>


<section>
<info>
  <title>Common key attributes</title>
</info>

<para>
  As only the key size differs between the different key types, there are common attributes.
  Specifically, the ID and name of the key.
</para>

<variablelist>
  <title>Common key fields</title>
  <varlistentry>
    <term><token>id</token></term>
    <listitem>
      <para>
        Specifies the ID of the key. This ID can then be used to reference the key within the 
        commercial digital channel extension. See <xref linkend="extComChannel"/>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>name</token></term>
    <listitem>
      <para>
        Specifies the name of the key. This property is usually not encoded in the binary 
        codeplug.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</section>


<section>
<info>
  <title>DMR (basic) key attributes</title>
</info>
    
<variablelist>
  <title>DMR key fields</title>
  <varlistentry>
    <term><token>key</token></term>
    <listitem>
      <para>
        Specifies the key as a HEX string. It must be at least 8bit but can be of variable size. 
        The actual size depends on the device. Usually, a fixed size of 16 or 32bit is supported. 
        Some devices, however, support variable sized keys.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</section>
  

<section>
  <info>
    <title>RC4 (enhanced) key attributes</title>
  </info>
      
  <para>
  </para>
      
  <variablelist>
    <title>RC4 key fields</title>
    <varlistentry>
      <term><token>key</token></term>
      <listitem>
        <para>
          Specifies the key as a HEX string. This key is fixed to a size of 40bit. That is, the hex 
          string must be of length 10.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
  </section>
  
  
  <section>
<info>
  <title>AES (advanced) key attributes</title>
</info>
    
<para>
</para>
    
<variablelist>
  <title>AES key fields</title>
  <varlistentry>
    <term><token>key</token></term>
    <listitem>
      <para>
        Specifies the key as a HEX string. Also this key can be of variable size. Usually, these 
        keys are 128 or 256bit. The actual size depends on the device.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</section>
  
</section>
        
