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.
PIB service is run as a separate service for each user.

Users' public key information is managed in three tables in PIB: identity table, key table, and certificate table.
Identity table schema:

identities(
    id                   INTEGER PRIMARY KEY,
    identity             BLOB NOT NULL,        
    is_default           INTEGER DEFAULT 0
);

A unique index is created on (identity).

Key table schema:

keys(
    id                   INTEGER PRIMARY KEY,
    identity             BLOB NOT NULL,        
    key_id               BLOB NOT NULL,        
    key_type             INTEGER NOT NULL,     
    key_bits             BLOB NOT NULL,        
    is_default           INTEGER DEFAULT 0,
    FOREIGN KEY(identity) REFERENCES identities(identity) ON DELETE CASCADE             
);    

A unique index is created on (identity, key_id).

Certificate table schema:

certificates(
    id                   INTEGER PRIMARY KEY,
    certificate_name     BLOB NOT NULL,        
    identity             BLOB NOT NULL,        
    key_id               BLOB NOT NULL,        
    certificate_data     BLOB NOT NULL,        
    is_default           INTEGER DEFAULT 0,
    FOREIGN KEY(identity, key_id) REFERENCES keys(identity, key_id) ON DELETE CASCADE
);

A unique index is created on (certificate_name).

Besides these tables PIB has one more management tables: mgmt table.
mgmt table stores owner name, corresponding tpm locator, and local management key (we will discuss it later).

User table schema:

mgmt(                                       
    id                    INTEGER PRIMARY KEY
    owner                 BLOB NOT NULL,
    tpm_locator           BLOB,
    local_management_cert BLOB NOT NULL,    
);

The read access to PIB is not restricted,
while the write access to PIB 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 local management key is allowed to change anything in the PIB info in the three tables. The identity of the user local management key is /localhost/pib/user/[UserName], and the name of the key should be /localhost/pib/user/[UserName]/[KeyId]. Adding a new normal user's local management key is not restricted for now, because we expect in future that OS will prevent a user from registering another user in PIB. However, changing a existing user's local management key requires a signature generated by the existing 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. Importing a self-signed regular key requires the signature generated by the corresponding user's local management key.

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.
Five types of operations are defined:

Verb	Access Type	Description
Get	Read	Get a single entity (user, identity, key, or certificate)
Default	Read	Get the default setting of an entity
List	Read	List the name of a set of entities
Update	Write	Add/Change an entity
Delete	Write	Delete an entity

Param is a TLV block containing parameters of the query.
Different types of operations have their own parameters.

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.

Several TLVs are defined for the content of query responses.
Identity TLV:

PibIdentity := PIB-IDENTITY-TYPE TLV-LENGTH
               Name

PublicKey TLV:

PibPublicKey := PIB-PUBLIC-KEY-TYPE TLV-LENGTH
                Name
                PibBytes

Certificate TLV:

PibCertificate := PIB-CERTIFICATE-TYPE TLV-LENGTH
                  Data 

User TLV:

PibUser := PIB-USER-TYPE TLV-LENGTH
           Data // local management certificate
           ...  // Other information to add if exists

A response may also be a error code defined a non-negative integer:

 PibError := PIB-ERROR-TYPE TLV-LENGTH
             ErrorCode
             Bytes

ErrorCode := ERROR-CODE-TYPE TLV-LENGTH
             nonNegativeInteger

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

A response is signed by a PIB instance key with the name /localhost/pib/[UserName]/dsk-....
The PIB instance key is signed by another key with the name /localhost/pib/[UserName]/ksk-... which is the trust anchor of the PIB service.
Note that it is difference from the management key name which is /localhost/pib/user/[UserName]/dsk-....
Management key is used by PIB owner to sign update/delete command interest,
while PIB instance key is used by PIB service to sign PIB responses.

Get Parameters¶

For get operation, Param is defined as:

PibGetParam := PIB-GET-PARAM-TYPE TLV-LENGTH
               PibType
               Name?

Type indicates which table the query will be applied eventually.

PibType := PIB-TYPE-TYPE TLV-LENGTH
           nonNegativeInteger

Type constant	Assigned value	Assigned value (hex)
USER	0	0x00
ID	1	0x01
KEY	2	0x02
CERT	3	0x03

Name is the name of the queried entity. It is a TLV defined in NDN-TLV spec.
Name is ignored if type is USER.

If error happens during processing the query, the content of the response is an ErrorCode TLV.
If no error happens, the content depends on the Type.
When Type is ID, the query is actually invalid.
The response is an ErrorCode with value ERR_WRONG_PARAM.

For USER, the content is a PibUser TLV.
For KEY, the content is a PibPublicKey TLV.
For CERT, the content is a PibCertificate TLV.

Default Parameters¶

The parameters of default operation is defined as.

  PibDefaultParam := PIB-DEFAULT-PARAM-TYPE TLV-LENGTH
                     PibType    // target type
                     PibType    // origin type
                     Name?      // origin name

The response to a default query is the default entity of the "target type" of the "origin".

Possible values of target type include ID, KEY, and CERT.
Possible values of origin type include USER, ID, and KEY.
The target type should be always "below" the origin type (e.g., it is wrong to have a target type ID and an origin type CERT.)
The origin name should be consistent with the origin type.
Origin name is ignored if origin type is USER.
When wrong parameters are supplied, the content of response is an ErrorCode with value ERR_WRONG_PARAM.

If no error happens in processing the query, the response could be PibIdentity, PibPublicKey, or PibCertificate, depending on the target type.

List Parameters¶

The parameters of list operation are defined as:

PibListParam := PIB-LIST-PARAM-TYPE TLV-LENGTH
                PibType // origin type
                Name?   // origin name

The response to the list query is a list of Name, depending on the origin type.
Possible values of origin type include USER, ID, and KEY.
Origin name is ignored if origin type is USER.
If the origin type is USER, the response is a list of identities of the user.
If the origin type is ID, the response is a list of names of keys of the identity.
If the origin type is KEY, the response is a list of names of certificates of the key.

PibNameList := PIB-NAME-LIST-TYPE TLV-LENGTH
               Name+

Update Parameters¶

The parameters of update operation are defined as:

PibUpdateParam := PIB-UPDATE-PARAM-TYPE TLV-LENGTH
                  (PibUser | PibIdentity | PibPublicKey | PibCertificate)
                  PibDefaultOpt

DefaultOpt is the default option:

PibDefaultOpt := PIB-DEFAULT-OPT-TYPE TLV-LENGTH
                 nonNegativeInteger

DefaultOpt constant	Assigned value	Assigned value (hex)
DEFAULT_OPT_NO	0	0x00
DEFAULT_OPT_KEY	1	0x01
DEFAULT_OPT_ID	3	0x03
DEFAULT_OPT_USER	7	0x07

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 PibDefaultOpt.

The response is always an ErrorCode: ERR_SUCCESS for a successful operation, others for failure.

Delete Parameters¶

The parameters of delete operation are defined as:

PibDeleteParam := PIB-DELETE-PARAM-TYPE TLV-LENGTH
                  PibType
                  Name

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

The response is always an ErrorCode: ERR_SUCCESS for a successful deletion, others for failure.

TLV-TYPE assignments¶

Type	Assigned value	Assigned value (hex)
PibGetParam	128	0x80
PibDefaultParam	129	0x81
PibListParam	130	0x82
PibUpdateParam	131	0x83
PibDeleteParam	132	0x84
PibUser	144	0x90
PibIdentity	145	0x91
PibPublicKey	146	0x92
PibCertificate	147	0x93
PibBytes	148	0x94
PibDefaultOpt	149	0x95
PibNameList	150	0x96
PibType	151	0x97
PibError	152	0x98
PibTpmLocator	153	0x99
PibErrorCode	252	0xfc

Misc¶

In that case root user's private key is lost in TPM, you have to delete the root user directly in the database.
Since the database file is guarded by filesystem, only system admin can do that.