PublicKey Info Base » History » Revision 42
Revision 41 (Yingdi Yu, 07/16/2014 09:53 AM) → Revision 42/79 (Yingdi Yu, 07/16/2014 11:38 AM)
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](http://redmine.named-data.net/projects/ndn-cxx/wiki/SignedInterest)** (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 Four types of operations are defined:
Verb | Access Type | Description
-------------------- | ----------------- | ---------------------------------------------------------- ---------------------------------------------------------
Get | Read | Get a single entity (user, identity, key, or certificate) certificate
Check | Read | Check if an entity exists
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
`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.
### Query Responses
The response to a query interest is a data packet signed by PIB. `Get` Parameters
The public key certificate of PIB For `get` operation, `Param` 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 as:
GetParam := PIB-IDENTITY-TYPE TLV-LENGTH
Type
Filter
Filter := DirectFilter | DefaultOfFilter | ListOfFilter
DirectFilter := Name
`PublicKey` TLV:
PibPublicKey
DefaultOfFilter := PIB-PUBLIC-KEY-TYPE TLV-LENGTH
Type
Name
PibBytes
`Certificate` TLV:
PibCertificate
ListOfFilter := PIB-CERTIFICATE-TYPE TLV-LENGTH
Data
A response may also be a error code defined a non-negative integer:
ErrorCode Type
Name
Type := ERROR-CODE-TYPE TLV-LENGTH
nonNegativeInteger
Error code ID | Value KEY | 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 CERT
### `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
`Filter` indicates how to apply the query.
When `Name` is specified in `Filter`, PIB will directly lookup the entry with the same name of in the queried entity. It table indicated by `Type`.
When `DefaultOf` is a TLV defined specified in [NDN-TLV spec](http://named-data.net/doc/ndn-tlv/name.html#name)
If error happens during processing `Filter`, PIB will first derive the query, the content name of the response is an ErrorCode TLV.
If no error happens, target through the content depends on default information and lookup the entry in the table indicated by `Type`.
When `Type` `ListOf` is `User`, specified in `Filter`, PIB will collect all the content is a list entries that satisfy the condition specified in `ListOf`.
Here are some examples of TLVs: `GetParam`:
GetUserContent := CONTENT-TYPE TLV-LENGTH
PibCertificate // local management certificate
... // Other information to add if exists GetParam
{
Type: KEY
DirectFilter
{
Name: /ndn/edu/ucla/ksk-1234
}
}
When `Type` The example above is `ID`, the a query is actually invalid.
The response is an ErrorCode to get a key with value `ERR_WRONG_PARAM`.
For `KEY`, the content is a `PibPublicKey` TLV.
For `CERT`, the content is a `PibCertificate` TLV.
### `Default` Parameters name `/ndn/edu/ucla/ksk-1234`.
GetParam
{
Type: CERT
DefaultOfFilter
{
Type: ID
Name: /ndn/edu/ucla/alice
}
}
The parameters of `default` operation example above 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 to get the default entity certificate of the "target type" of the "origin". an identity `/ndn/edu/ucla/alice`.
GetParam
{
Type: CERT
ListOfFilter
{
Type: KEY
Name: /ndn/edu/ucla/ksk-1234
}
}
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 example above is wrong a query to have get 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 list of response is an ErrorCode with value `ERR_WRONG_PARAM`. certificates of a key `/ndn/edu/ucla/alice`.
If no error happens in processing the query, the response could be `PibIdentity`, `PibPublicKey`, or `PibCertificate`, depending on the target type.
### `List` `Search` Parameters
The parameters of `list` `search` operation are defined as:
PibListParam is quite similar to `get` operation except that there is no `ListOf` filter.
SearchParam := PIB-LIST-PARAM-TYPE TLV-LENGTH
PibType // origin type
Name? // origin name Type
Filter
Filter := NameFilter | DefaultOfFilter
NameFilter := Name
DefaultOfFilter := Type
Name
Type := ID | KEY | CERT
The response to the `list` query `search` operation is a list of `Name`, depending on boolean value to indicate the origin type.
Possible values existence 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. searched entity
### `Update` Parameters
The parameters of `update` operation are defined as:
PibUpdateParam UpdateParam := (PibIdentity Entity
DefaultOpt
Entity := Identity | PibPublicKey PublicKey | PibCertificate)
PibDefaultOpt
`DefaultOpt` is the default option:
PibDefaultOpt Certificate
Identity := PIB-DEFAULT-OPT-TYPE TLV-LENGTH
nonNegativeInteger
Name
PublicKey := Name
Bytes
Certificate := Data
DefaultOpt constant := USER_DEFAULT | Assigned value ID_DEFAULT | Assigned value (hex)
------------------------------------------- KEY_DEFAULT | ----------------- | --------------------
DEFAULT_OPT_NO | 0 | 0x00
DEFAULT_OPT_USER | 1 | 0x01
DEFAULT_OPT_ID | 2 | 0x02
DEFAULT_OPT_KEY | 3 | 0x03 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 `PibDefaultOpt`. `DefaultOpt`.
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 DeleteParam := PibType
Type
Name
Type := ID | KEY | CERT
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 GetParam | 128 | 0x80
PibDefaultParam SearchParam | 129 | 0x81
PibUpdateParam UpdateParam | 130 | 0x82
PibDeleteParam DeleteParam | 131 | 0x83
----------------------------------------------- Type | ----------------- 132 | -------------------- 0x84
PibType NameFilter | 132 133 | 0x90 0x85
PibIdentity DefaultOfFilter | 136 134 | 0x91 0x86
PibPublicKey ListOfFilter | 135 | 0x87
Identity | 136 | 0x88
PublicKey | 137 | 0x92 0x89
PibCertificate Certificate | 138 | 0x93 0x8a
PibBytes Bytes | 139 | 0x94 0x8b
PibDefaultOpt DefaultOpt | 140 | 0x95 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