NFD

Signed Command Interests

========================

**Command Interest** is a mechanism to issue an authenticated control command.

Command Interests are similar to Signed Interests, but in addition to basic cryptographic signature, also ensure uniqueness of each command.

The signature of a command Interest packet is embedded into the last component of the Interest name.

The signature covers a continuous block starting from the first name component TLV to the penultimate name component TLV:

    +-------------+----------+-----------------------------------------------------------------------------------+

    |  Interest   | Interest | +------+--------+--------------------------------------------------+ +----------+ |

    | Type (0x01) |  length  | | Name |  Name  | +---------+--   --+---------+---------+---------+| | Other    | |

    |             |          | | Type | Length | |Component|  ...  |Component|Component|Component|| | TLVs ... | |

    |             |          | |      |        | |  TLV 1  |       | TLV n-2 | TLV n-1 |  TLV n  || | in       | |

    |             |          | |      |        | +---------+--   --+---------+---------+---------+| | Interest | |

    |             |          | +------+--------+--------------------------------------------------+ +----------+ |

    +-------------+----------+-----------------------------------------------------------------------------------+

                                                 \                                    /\        /

                                                  ----------------  ------------------  ---  ---

                                                                  \/                       \/

                                                       Signed portion of Interest       Signature

More specifically, the CommandInterest is defined to have three additional components:

* ``<timestamp>``

* ``<random-value>``

* ``<SignatureInfo>``

* ``<SignatureValue>``

For example, for ``/signed/interest/name`` name, CommandInterest will be defined as:

     /signed/interest/name/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>

                           \                                                         /

                            -------------------------  ------------------------------

                                                     \/

                                   Additional components of Command Interest 

## Signed Interest specific Name components

### Timestamp component (n-3 *th*)

The value of the n-3 *th* component is the control command's timestamp (in terms of millisecond offset from UTC 1970-01-01 00:00:00) encoded as [nonNegativeInteger](http://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding). 

The timestamp is used to protect against replay attack.

### Random value (n-2 *th*)

The value of the n-2 *th* component is random value (32bits) that adds additional assurances that the command Interest will be unique, even if multiple commands are issued at the same time.

The random value is also encoded as [nonNegativeInteger](http://named-data.net/doc/ndn-tlv/tlv.html#non-negative-integer-encoding). 

### SignatureInfo component (n-1 *th*)

The value of the n-1 *th* component is actually a [SignatureInfo](http://named-data.net/doc/ndn-tlv/signature.html) TLV.

    +---------+---------+-------------------+

    |Component|Component| +---------------+ |

    |   Type  |  Length | | SignatureInfo | |

    |         |         | |      TLV      | |

    |         |         | +---------------+ |

    +---------+---------+-------------------+

    |                                       |

    |<---------The n-1 th Component-------->|

### SignatureValue component (n *th*)

The value of the n *th* component is actually a [SignatureValue](http://named-data.net/doc/ndn-tlv/signature.html) TLV.

    +---------+---------+--------------------+

    |Component|Component| +----------------+ |

    |   Type  |  Length | | SignatureValue | |

    |         |         | |      TLV       | |

    |         |         | +----------------+ |

    +---------+---------+--------------------+

    |                                        |

    |<----------The n th Component---------->|

## Command Interest processing

On receiving an Interest, the producer, according to the Interest name prefix, should be able to tell whether the Interest is required to be signed.

If the received Interest is supposed to be signed, it will be treated as invalid in the following four cases:

- one of the three components above (SignatureValue, SignatureInfo, and Timestamp) is missing or cannot be parsed correctly;

- the key is not trusted for signing the control command;

- the signature cannot be verified with the public key pointed by the [KeyLocator](http://named-data.net/doc/ndn-tlv/signature.html#keylocator) in SignatureInfo;

- the producer has already received a valid signed Interest whose timestamp is **equal or later** than the timestamp of the received one.

Note that in order to detect the fourth case, the producer needs to maintain a *latest timestamp* state for each trusted public key

(**Since public key cryptography is used, sharing private keys is not recommended. If private key sharing is inevitable, it is the key owner's responsibility to keep clock synchronized**).

For each trusted public key, the state is initialized as the timestamp of the first valid Interest signed by the key.

Since then, the state will be updated every time when the producer receives a valid command Interest.

Note that for the first Interest, the state is not available. 

To handle this special situation, the producer should check the Interest's timestamp against a proper interval (e.g., 120 seconds) [current\_timestamp - interval/2, current\_timestamp + interval/2].

The first interest is invalid if its timestamp is outside of the interval.