Application Development Documentation / Guides

Background

==========

The NDN project is transitioning both the packet format for NDN and the forwarder codebase.  To support comparison, testing, and transition of existing code, the NDN-CPP library supports both wire formats and both forwarders (in certain combinations described below).  Support for NDNx and the ndnb wire format is deprecated and may be removed as early as Fall 2014, so we encourage all new applications to be written for the TLV wire format and NFD forwarder. 

This document currently covers C++ language support of the Common Client Library (NDN-CPP) only, but will be updated to describe Python, Javascript, and Java libraries as well, which have more limited support for multiple wire formats and forwarders.

Using ndn-cpp with NDNx vs. NDNx-TLV vs. NFD

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

[ndn-cpp](https://github.com/named-data/ndn-cpp) is an NDN client library for C++. This document explains how it can be used with any of the three NDN forwarders [NDNx](https://github.com/named-data/ndnx), [NDNx-TLV](https://github.com/named-data/ndnd-tlv) and [NFD](https://github.com/named-data/NFD). (This assumes you have installed the latest ndn-cpp which can work with all the forwarders and wire formats.)

Each forwarder has different support for the wire format of [ndnb (Binary XML)](http://named-data.net/doc/0.1/technical/BinaryEncoding.html) vs. [TLV (type-length-value)](http://named-data.net/doc/ndn-tlv/). Also, each forwarder has different requirements for a registerPrefix signed command interest (see "Using registerPrefix with NFD" below).

Forwarder  | ndnb (Binary XML) wire format? | TLV wire format? | registerPrefix signed command interest?

---------- | ------------------------------ | ---------------- | ---------------------------------------

NDNx       | ✓                              |                  | no

NDNx-TLV   | ✓                              | ✓                | no

NFD        |                                | ✓                | YES

# Writing your application based on the forwarder

## Setting the ndnb wire format (for NDNx)

ndn-cpp will accept an interest or data packet in either ndnb or TLV. By default, ndn-cpp sends an interest or data packet in the TLV wire format. If your application connects to NDNx-TLV or NFD, you do not need to change your code. 

However, if your application connects to NDNx, you need to use ndnb (Binary XML). There are two ways to use the ndnb (Binary XML) wire format. At the beginning of your application code, you can set the default wire format:

    #include <ndn-cpp/encoding/binary-xml-wire-format.hpp>

    ...

    WireFormat::setDefaultWireFormat(BinaryXmlWireFormat::get());

Alternatively, when you use ./configure to build the ndn-cpp library, you can set the default wire format to ndnb (Binary XML):

    ./configure --enable-binary-xml=yes

## Using registerPrefix with NFD

If you only have a consumer application which sends an interest and receives a data packet, and you connect to NDNx, then you only need to follow "Setting the ndnb wire format" above. If you have a publisher application which needs to receive an interest, then it needs to register a prefix with the forwarder. If your application connects to NDNx or NDNx-TLV, you don't need to change your code because the forwarder will accept the self-signed request which is sent by registerPrefix.

However, if your publisher application connects to NFD, it needs to send a signed command interest which is trusted by the forwarder. When you install NFD, it installs a default signing key on your system. For registerPrefix to create a signed command interest using this default signing key, your application needs to use the [default KeyChain constructor](http://named-data.net/doc/ndn-ccl-api/key-chain.html#keychain-constructor) and call [setCommandSigningInfo](http://named-data.net/doc/ndn-ccl-api/face.html#face-setcommandsigninginfo-method) so that the Face can sign the command interest created by [registerPrefix](http://named-data.net/doc/ndn-ccl-api/face.html#face-registerprefix-method):

    Face face("localhost");

    KeyChain keyChain;

    face.setCommandSigningInfo(keyChain, keyChain.getDefaultCertificateName());

(See the example application [test-publish-async-nfd](https://github.com/named-data/ndn-cpp/blob/master/tests/test-publish-async-nfd.cpp) .)  Note that the default KeyChain constructor will only succeed if NFD has installed the default signing key. If your system only has NDNx or NDNx-TLV, then the default KeyChain constructor will fail.  In this case, you should use a KeyChain with a MemoryPrivateKeyStorage as shown in the example application [test-publish-async-ndnx](https://github.com/named-data/ndn-cpp/blob/master/tests/test-publish-async-ndnx.cpp).

# Details

The above should let you make your application work with the different forwarders.  Here are the details of how the ndn-cpp library interacts with the different wire formats and protocols.

## Receiving a packet

When the library receives a data packet, it checks the first byte. If the first byte is 5 (Interest type code), 6 (Data type code) or 0x80, then it decodes the packet as TLV. Otherwise, it decodes it as ndnb (Binary XML). Therefore, you don't have to configure the library for receiving a packet since it automatically handles both TLV and ndnb.

## Sending a register prefix command

For register prefix, NFD uses a signed commmand interest which has a different format than the register prefix message for NDNx and NDNx-TLV. As explained above, to use registerPrefix with NFD, your application must first call setCommandSigningInfo. Therefore, if your application has not called setCommandSigningInfo then the library assumes that you are connected to NDNx or NDNx-TLV and registerPrefix simply sends a self-signed request in the NDNx format, signing with a hard-wired private key.  (NDNx only verifies the signature on the register prefix message using the public key in the message.)  In this message, the internal ForwardingEntry and Data packet payload are encoded as ndnb (Binary XML) regardless of the supplied wire format.  The outer register prefix interest packet is encoded using the supplied wire format, which is OK because NDNx-TLV will re-encode as ndnb if needed before processing.

However, if your application has called setCommandSigningInfo then registerPrefix uses the info to send a signed command command interest in the NFD format. If your application is connected to NFD then register prefix should succeed. But if your application is connected to NDNx or NDNx-TLV, then the forwarder will reject the request. In this case, the library gets an interest timeout and sends a self-signed request in the NDNx format as described above.  Therefore, if your application calls setCommandSigningInfo, registerPrefix will work if connected to any of the forwarders.

## Interest and Data API for TLV vs. ndnb

There are some differences in the Interest and Data packet wire format for TLV vs. ndnb (Binary XML), but the library uses one Interest class and one Data class to support both wire formats. Here are the details on how the API for ndnb (Binary XML) was changed to support TLV.

* In MetaInfo, added get/setFreshnessPeriod. Deprecated get/setFreshnessSeconds. (This is simple factor of 1000 since FreshnessPeriod is milliseconds.)

* In Interest, added get/setMustBeFresh. Deprecated get/setAnswerOriginKind. Internally, use the inverse of the ANSWER_STALE bit of answerOriginKind. When encoding TLV, give an error if other bits are set.

* In the Interest constructor, set MustBeFresh true by default so that it has the same semantics as the default ANSWER_STALE = 0.

* In Interest, added KeyLocator. Deprecated get/setPublisherPublicKeyDigest.

Here is how the fields of the Interest and Data object are treated when encoding as TLV instead of ndnb (Binary XML):

### Interest

Field                        | Treatment if encoding as TLV instead of ndnb (Binary XML)

---------------------------- | ---------------------------------------------------------

name                         | same

minSuffixComponents          | same

maxSuffixComponents          | same

publisherPublicKeyDigest     | Deprecated. If the interest needs a publisher public key digest, the keyLocator type is ndn_KeyLocatorType_KEY_LOCATOR_DIGEST.

KeyLocator                   | if KeyLocator is specified and keyLocatorType is KEYNAME or PUBLISHER_PUBLIC_KEY_DIGEST, use it. Otherwise error.

exclude                      | same

childSelector                | same

answerOriginKind             | Set MustBeFresh based on answerOriginKind ANSWER_STALE bit. Error if other anwerOriginKind bits are set.

scope                        | same

interestLifetimeMilliseconds | same

nonce                        | If none or < 4 bytes, generate new random nonce bytes before issuing the interest. If > 4 bytes, truncate to 4. Deprecate setNonce in the API. Allow getNonce to show the nonce of an incoming Interest. If any Interest fields are changed, clear the nonce.

### Data

Field                    | Treatment if encoding as TLV instead of ndnb (Binary XML)

------------------------ | ---------------------------------------------------------

name                     | same

content                  | same

MetaInfo.type            | Require BLOB, LINK or KEY, otherwise error.

MetaInfo.freshnessPeriod | same

MetaInfo.timestamp       | ignore

MetaInfo.finalBlockID    | same

Signature.keyLocator     | if KeyLocator is specified and keyLocatorType is KEYNAME or PUBLISHER_PUBLIC_KEY_DIGEST, use it. Otherwise error.

Signature.signatureBits  | same

Signature.witness        | ignore. Deprecated get/setWitness.