Public key Info Base (PIB) Service¶

Public Key Info Management¶

NDN data packets are secured through digital signatures.
In order to generate a valid signature, an NDN application needs to know not only the correct key to use but also the correct public key information that should be put into the KeyLocator of a data packet.
The information needs to be managed locally on the system where the application is running.

The information related to keys is managed at three granularities: identities, keys, and certificates.
A key is always associated with a namespace, called "identity".
An identity however may have more than one keys.
Each key is named as /<Identity>/[KeyId].
The KeyId uniquely identifies a key which belongs to the Identity.
Among these keys, only one is the default key of the identity.
If only identity is provided when signing a packet, the default key of the identity will be used to sign the packet.

A certificate is always associated with the key in the certificate
If a certificate is provided when signing a packet, the corresponding private key should be used to sign the packet
and the name of the certificate name may be put into the KeyLocator of the packet.

A key may have more than one certificates (e.g., certificates may be issued by different parties).
Among these certificates, only one is the default certificate of the key.
The default certificate of the default key of an identity is the default certificate of the identity.
If only identity is provided when signing a packet, the name of the default certificate of the identity may be put into the KeyLocator of the packet.

All the information above may be accessed by different APIs and applications on the same system,
therefore it is desirable to make the information provisioning as a system service.

Since public keys and certificates are supposed to be publicly available,
the service also serves as a local storage of certificate and public keys,
besides providing the public key related information.

PIB management model¶

The public key information of each system user is managed separately in PIB.
For now, PIB service is a system service (i.e., run by root).
PIB service may be separated into several user services (i.e., run by each user) in the future.

Each user has three tables in PIB: identity table, key table, and certificate table.
The public key information of a user is managed in these tables.
Identity table consists of two columns: identity (primary key) and default_key_id.
Identity table schema:

User_[UserName]_ID(
    identity             BLOB NOT NULL,        
    default_key_id       BLOB,

    PRIMARY KEY (identity)                     
);                                             

Key Table consists of five columns: identity, key_id, key_type, key_bits, and default_cert_name.
The combination of identity and key_id is the primary key of key table.
Key table schema:

User_[UserName]_KEY(
    identity             BLOB NOT NULL,        
    key_id               BLOB NOT NULL,        
    key_type             INTEGER NOT NULL,     
    key_bits             BLOB NOT NULL,        
    default_cert_name    BLOB,                 
    PRIMARY KEY (identity, key_id)             
);

Certificate table consists of four columns: certificate_name (primary key), identity, key_id, and certificate_data.
Certificate table schema:

User_[UserName]_CERT(
    certificate_name     BLOB NOT NULL,        
    identity             BLOB NOT NULL,        
    key_id               BLOB NOT NULL,        
    certificate_data     BLOB NOT NULL,        
    PRIMARY KEY (certificate_name)             
);

Besides the tables for each user, PIB has two more management tables: user table and certificate_publishing table.
User table stores user's local management key (we will discuss it later) and user's default identity
Each user has its own default identity.
From the default identity, the default key and certificate of the user can be derived.

User table schema:

User(                                       
    user_name             BLOB NOT NULL,    
    has_default_identity  INTEGER DEFAULT 0,
    default_identity      BLOB,             
    local_management_cert BLOB NOT NULL,    

    PRIMARY KEY (user_name)                 
);

Certificate_Publishing table schema:

Certificate_Publishing(
    user_name             BLOB NOT NULL,
    publish_namespace     BLOB NOT NULL,

    PRIMARY KEY (user_name, publish_namespace)
);  

The read access to a user's public key information is not restricted,
while the write access to a user's public key information requires authentication.
The write access is expressed as signed commands.
The signing key can be authenticated only if the key already exists in the corresponding user's PIB tables.
Each key has its own write access privilege which is defined as:

• The root user has the root key of the local system. The root key has the highest privilege, i.e., its owner is allowed to change anything in PIB. The identity of the root key is /localhost, and the name of the root key should be /localhost/[KeyId].
• Each user has its own local management key. The local management key is allowed to change anything in the user's PIB info including the three tables and user's own entry in the user table. The identity of the user local management key is /localhost/user/[UserName], and the name of the key should be /localhost/user/[UserName]/[KeyId]. Note that the local management key of the root user is the root key.
• All the other keys are called regular keys. A regular key is allowed to change keys/certificates with identities under the key's own namespace, e.g., a key with the identity /ndn/ucla/alice is allowed to change a key with the identity /ndn/ucla/alice/chat but is not allowed to change a key with the identity /ndn/ucla/bob.

PIB Service Protocol¶

PIB service provides an interface to NDN applications for public key info lookup.
The interface is defined in terms of NDN packets (interest/data).
Depending on the query type, a query to PIB is expressed as a signed interest (for Write operation) or normal interest (for Read operation).
The query interest is defined as:

/localhost/pib/[UserName]/[Verb]/[Param]/<signed_interest_security_components>
                                        |<-- Required for Write operation -->|

UserName indicates the tables in which the query should apply.
Verb indicates the access operation.
Four types of operations are defined: get (Read), search (Read), update (Write), and delete (Write).
The operation get and search are quite similar to each other.
The only difference is that the response to get is the queried entity per se while the response to search operation is the existence (a boolean value) of the queried entity.
Param is a TLV block containing parameters of the query.
Different types of operations have their own parameters.

Get Parameters¶

For get operation, Param is defined as:

        GetParam := Type
                    Filter
          Filter := DirectFilter | DefaultOfFilter | ListOfFilter
    DirectFilter := Name
 DefaultOfFilter := Type
                    Name
    ListOfFilter := Type
                    Name
            Type := ID | KEY | CERT

Type indicates which table the query will be applied eventually.
Filter indicates how to apply the query.
When Name is specified in Filter, PIB will directly lookup the entry with the same name in the table indicated by Type.
When DefaultOf is specified in Filter, PIB will first derive the name of the target through the default information and lookup the entry in the table indicated by Type.
When ListOf is specified in Filter, PIB will collect all the entries that satisfy the condition specified in ListOf.
Here are some examples of GetParam:

GetParam 
{
  Type: KEY
  Filter 
  {  
    Name: /ndn/edu/ucla/ksk-1234
  }
}

The example above is a query to get a key with the name /ndn/edu/ucla/ksk-1234.

GetParam
{
  Type: CERT
  Filter 
  { 
    DefautOf 
    {
      Type: ID
      Name: /ndn/edu/ucla/alice
    }
  }
}

The example above is a query to get the default certificate of an identity /ndn/edu/ucla/alice.

GetParam
{
  Type: CERT
  Filter 
  { 
    ListOf 
    {
      Type: KEY
      Name: /ndn/edu/ucla/ksk-1234
    }
  }
}

The example above is a query to get a list of certificates of a key /ndn/edu/ucla/alice.

Search Parameters¶

The parameters of search operation is quite similar to get operation except that there is no ListOf filter.

      SearchParam := Type
                     Filter
           Filter := NameFilter | DefaultOfFilter
       NameFilter := Name
  DefaultOfFilter := Type
                     Name
             Type := ID | KEY | CERT

The response to search operation is a boolean value to indicate the existence of the searched entity

Update Parameters¶

The parameters of update operation are defined as:

UpdateParam := Entity
               DefaultOpt
     Entity := Identity | PublicKey | Certificate
   Identity := Name
  PublicKey := Name
               Bytes
Certificate := Data
 DefaultOpt := USER_DEFAULT | ID_DEFAULT | KEY_DEFAULT | NO_DEFAULT

The operation, once validated, will add a new entry in the corresponding table if no such an entry exists or update the existing entry,
and change the default setting according to DefaultOpt.

Delete Parameters¶

The parameters of delete operation are defined as:

DeleteParam := Type
               Name
       Type := ID | KEY | CERT

The entity and its belonging entities will be deleted once the operation is validated.

TLV-TYPE assignments¶

Type	Assigned value	Assigned value (hex)
GetParam	128	0x80
SearchParam	129	0x81
UpdateParam	130	0x82
DeleteParam	131	0x83
Type	132	0x84
NameFilter	133	0x85
DefaultOfFilter	134	0x86
ListOfFilter	135	0x87
Identity	136	0x88
PublicKey	137	0x89
Certificate	138	0x8a
Bytes	139	0x8b
DefaultOpt	140	0x8c

Constant value assignments¶

For type Type:

Constant	Assigned value	Assigned value (hex)
ID	0	0x00
KEY	1	0x01
CERT	2	0x02

For type DefaultOpt:

Constant	Assigned value	Assigned value (hex)
NO_DEFAULT	0	0x00
USER_DEFAULT	1	0x01
ID_DEFAULT	2	0x02
KEY_DEFAULT	3	0x03

Query Responses¶

The response to a query interest is a data packet signed by PIB.
The public key certificate of PIB is stored in a read-only file and is accessible to all users on the system.

The content of the response to get operation could be one of the three TLV defined above: Identity (0x8b), PublicKey (0x8c), and Certificate (0x8d), or a list of these TLVs.
The content of the response to search operation is a byte. Non-zero byte stands for true while 0x00 stands for false.
The content of the response to update or delete operation is an uint32_t which serves as an error code.
0 stands for success while non-zero byte stands for failure.

Error code:

Error code	Value	Description
ERR_SUCCESS	0	No error
ERR_INCOMPLETE_COMMAND	1	Incomplete interest
ERR_WRONG_VERB	2	Wrong verb in interest
ERR_WRONG_PARAM	3	Wrong parameter in interest
ERR_NON_EXISTING_USER	128	User does not exist
ERR_NON_EXISTING_ID	129	Identity does not exist
ERR_NON_EXISTING_KEY	130	Public key does not exist
ERR_NON_EXISTING_CERT	131	Certificate does not exist
ERR_NO_DEFAULT_ID	256	No default identity is set
ERR_NO_DEFAULT_KEY	257	No default public key is set
ERR_NO_DEFAULT_CERT	258	No default certificate is set
ERR_DELETE_DEFAULT_SETTING	384	Trying to delete default setting