Project

General

Profile

PublicKey Info Base » History » Version 59

Yingdi Yu, 07/21/2014 09:21 AM

1 1 Yingdi Yu
Public key Info Base (PIB) Service
2
==================================
3
4
## Public Key Info Management 
5
6
NDN data packets are secured through digital signatures.
7 2 Yingdi Yu
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. 
8
The information needs to be managed locally on the system where the application is running.
9
10
The information related to keys is managed at three granularities: identities, keys, and certificates. 
11
A key is always associated with a namespace, called "identity".
12 4 Yingdi Yu
An identity however may have more than one keys.
13
Each key is named as `/<Identity>/[KeyId]`. 
14
The `KeyId` uniquely identifies a key which belongs to the `Identity`.
15 2 Yingdi Yu
Among these keys, only one is the default key of the identity.
16
If only identity is provided when signing a packet, the default key of the identity will be used to sign the packet.
17
18
A certificate is always associated with the key in the certificate
19
If a certificate is provided when signing a packet, the corresponding private key should be used to sign the packet 
20
and the name of the certificate name may be put into the `KeyLocator` of the packet.
21
22
A key may have more than one certificates (e.g., certificates may be issued by different parties).
23
Among these certificates, only one is the default certificate of the key.
24
The default certificate of the default key of an identity is the default certificate of the identity.
25
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.
26
27 3 Yingdi Yu
All the information above may be accessed by different APIs and applications on the same system, 
28
therefore it is desirable to make the information provisioning as a system service. 
29 1 Yingdi Yu
30 3 Yingdi Yu
Since public keys and certificates are supposed to be publicly available, 
31
the service also serves as a local storage of certificate and public keys, 
32
besides providing the public key related information.
33 1 Yingdi Yu
34 3 Yingdi Yu
## PIB management model
35 1 Yingdi Yu
36 3 Yingdi Yu
The public key information of each system user is managed separately in PIB.
37
For now, PIB service is a system service (i.e., run by root).
38
PIB service may be separated into several user services (i.e., run by each user) in the future.
39 1 Yingdi Yu
40 3 Yingdi Yu
Each user has three tables in PIB: identity table, key table, and certificate table.
41 1 Yingdi Yu
The public key information of a user is managed in these tables.
42 4 Yingdi Yu
Identity table consists of two columns: `identity` (primary key) and `default_key_id`.
43 16 Yingdi Yu
Identity table schema:
44
45 17 Yingdi Yu
    User_[UserName]_ID(
46 16 Yingdi Yu
        identity             BLOB NOT NULL,        
47
        default_key_id       BLOB,
48
                     
49
        PRIMARY KEY (identity)                     
50
    );                                             
51
52 4 Yingdi Yu
Key Table consists of five columns: `identity`, `key_id`, `key_type`, `key_bits`, and `default_cert_name`. 
53
The combination of `identity` and `key_id` is the primary key of key table.
54 18 Yingdi Yu
Key table schema:
55
56
    User_[UserName]_KEY(
57
        identity             BLOB NOT NULL,        
58
        key_id               BLOB NOT NULL,        
59
        key_type             INTEGER NOT NULL,     
60
        key_bits             BLOB NOT NULL,        
61
        default_cert_name    BLOB,                 
62
        PRIMARY KEY (identity, key_id)             
63
    );
64
65 4 Yingdi Yu
Certificate table consists of four columns: `certificate_name` (primary key), `identity`, `key_id`, and `certificate_data`.
66 18 Yingdi Yu
Certificate table schema:
67
68
    User_[UserName]_CERT(
69
        certificate_name     BLOB NOT NULL,        
70
        identity             BLOB NOT NULL,        
71
        key_id               BLOB NOT NULL,        
72
        certificate_data     BLOB NOT NULL,        
73
        PRIMARY KEY (certificate_name)             
74
    );
75 4 Yingdi Yu
76
Besides the tables for each user, PIB has two more management tables: user table and certificate_publishing table.
77
User table stores user's local management key (we will discuss it later) and user's default identity
78 3 Yingdi Yu
Each user has its own default identity. 
79
From the default identity, the default key and certificate of the user can be derived.
80 1 Yingdi Yu
81 14 Yingdi Yu
User table schema:
82
83
    User(                                       
84
        user_name             BLOB NOT NULL,    
85
        has_default_identity  INTEGER DEFAULT 0,
86
        default_identity      BLOB,             
87
        local_management_cert BLOB NOT NULL,    
88
                                                
89
        PRIMARY KEY (user_name)                 
90
    );
91
92 19 Yingdi Yu
Certificate_Publishing table schema:
93
94
    Certificate_Publishing(
95
        user_name             BLOB NOT NULL,
96
        publish_namespace     BLOB NOT NULL,
97
98
        PRIMARY KEY (user_name, publish_namespace)
99
    );  
100
101 1 Yingdi Yu
The read access to a user's public key information is not restricted,
102
while the write access to a user's public key information requires authentication.
103
The write access is expressed as signed commands. 
104 5 Yingdi Yu
The signing key can be authenticated only if the key already exists in the corresponding user's PIB tables.
105 4 Yingdi Yu
Each key has its own write access privilege which is defined as:
106 3 Yingdi Yu
107 4 Yingdi Yu
* 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]`.
108
* 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.
109 6 Yingdi Yu
* 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`.
110 3 Yingdi Yu
111
## PIB Service Protocol 
112
113
PIB service provides an interface to NDN applications for public key info lookup. 
114 1 Yingdi Yu
The interface is defined in terms of NDN packets (interest/data).
115 32 Yingdi Yu
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).
116 5 Yingdi Yu
The query interest is defined as:
117
118
    /localhost/pib/[UserName]/[Verb]/[Param]/<signed_interest_security_components>
119 34 Yingdi Yu
                                            |<-- Required for Write operation -->|
120 5 Yingdi Yu
121
`UserName` indicates the tables in which the query should apply.
122
`Verb` indicates the access operation. 
123 42 Yingdi Yu
Five types of operations are defined: 
124 40 Yingdi Yu
125 41 Yingdi Yu
Verb                 | Access Type       | Description
126 42 Yingdi Yu
-------------------- | ----------------- | ----------------------------------------------------------
127
Get                  | Read              | Get a single entity (user, identity, key, or certificate)
128 41 Yingdi Yu
Default              | Read              | Get the default setting of an entity
129
List                 | Read              | List the name of a set of entities
130 1 Yingdi Yu
Update               | Write             | Add/Change an entity
131
Delete               | Write             | Delete an entity
132
133
`Param` is a TLV block containing parameters of the query.
134
Different types of operations have their own parameters.
135
136 42 Yingdi Yu
### Query Responses
137
138
The response to a query interest is a data packet signed by PIB.
139
The public key certificate of PIB is stored in a read-only file and is accessible to all users on the system.
140
141
Several TLVs are defined for the content of query responses.
142
`Identity` TLV:
143
144
    PibIdentity := PIB-IDENTITY-TYPE TLV-LENGTH
145
                   Name
146
147
`PublicKey` TLV:
148
149
    PibPublicKey := PIB-PUBLIC-KEY-TYPE TLV-LENGTH
150
                    Name
151
                    PibBytes
152
153
`Certificate` TLV:
154
155
    PibCertificate := PIB-CERTIFICATE-TYPE TLV-LENGTH
156
                      Data 
157 55 Yingdi Yu
158
`User` TLV:
159
160
    PibUser := PIB-USER-TYPE TLV-LENGTH
161
               Data // local management certificate
162 56 Yingdi Yu
               ...  // Other information to add if exists
163 42 Yingdi Yu
 
164
A response may also be a error code defined a non-negative integer:
165
166 53 Yingdi Yu
     Response := CONTENT-TYPE TLV-LENGTH
167
                 ErrorCode
168
                 Bytes
169
170 42 Yingdi Yu
    ErrorCode := ERROR-CODE-TYPE TLV-LENGTH
171
                 nonNegativeInteger
172
173
Error code                    | Value             | Description
174
----------------------------- | ----------------- | ----------------------------------
175
ERR\_SUCCESS                  | 0                 | No error
176
ERR\_INCOMPLETE\_COMMAND      | 1                 | Incomplete interest
177
ERR\_WRONG\_VERB              | 2                 | Wrong verb in interest
178
ERR\_WRONG\_PARAM             | 3                 | Wrong parameter in interest
179
ERR\_NON\_EXISTING\_USER      | 128               | User does not exist
180
ERR\_NON\_EXISTING\_ID        | 129               | Identity does not exist
181
ERR\_NON\_EXISTING\_KEY       | 130               | Public key does not exist
182
ERR\_NON\_EXISTING\_CERT      | 131               | Certificate does not exist
183
ERR\_NO\_DEFAULT\_ID          | 256               | No default identity is set
184
ERR\_NO\_DEFAULT\_KEY         | 257               | No default public key is set 
185
ERR\_NO\_DEFAULT\_CERT        | 258               | No default certificate is set
186
ERR\_DELETE\_DEFAULT\_SETTING | 384               | Trying to delete default setting
187
188 11 Yingdi Yu
### `Get` Parameters
189 8 Yingdi Yu
For `get` operation, `Param` is defined as:
190 1 Yingdi Yu
191 42 Yingdi Yu
    PibGetParam := PIB-GET-PARAM-TYPE TLV-LENGTH
192
                   PibType
193
                   Name?
194 1 Yingdi Yu
195
`Type` indicates which table the query will be applied eventually.
196
197 42 Yingdi Yu
    PibType := PIB-TYPE-TYPE TLV-LENGTH
198
               nonNegativeInteger
199 22 Yingdi Yu
200 42 Yingdi Yu
Type constant                               | Assigned value    | Assigned value (hex)
201
------------------------------------------- | ----------------- | --------------------
202
USER                                        | 0                 | 0x00
203
ID                                          | 1                 | 0x01
204
KEY                                         | 2                 | 0x02
205
CERT                                        | 3                 | 0x03
206 30 Yingdi Yu
207 5 Yingdi Yu
208 48 Yingdi Yu
`Name` is the name of the queried entity. It is a TLV defined in [NDN-TLV spec](http://named-data.net/doc/ndn-tlv/name.html#name).
209
Name is ignored if type is USER.
210 5 Yingdi Yu
211 42 Yingdi Yu
If error happens during processing the query, the content of the response is an ErrorCode TLV.
212
If no error happens, the content depends on the `Type`.
213 5 Yingdi Yu
When `Type` is `ID`, the query is actually invalid. 
214 42 Yingdi Yu
The response is an ErrorCode with value `ERR_WRONG_PARAM`.
215
216 57 Yingdi Yu
For `USER`, the content is a `PibUser` TLV.
217 42 Yingdi Yu
For `KEY`, the content is a `PibPublicKey` TLV. 
218 48 Yingdi Yu
For `CERT`, the content is a `PibCertificate` TLV.
219 1 Yingdi Yu
220 42 Yingdi Yu
### `Default` Parameters
221 1 Yingdi Yu
222 42 Yingdi Yu
The parameters of `default` operation is defined as.
223 12 Yingdi Yu
224 42 Yingdi Yu
      PibDefaultParam := PIB-DEFAULT-PARAM-TYPE TLV-LENGTH
225
                         PibType    // target type
226
                         PibType    // origin type
227
                         Name?      // origin name
228 12 Yingdi Yu
229
230 42 Yingdi Yu
The response to a `default` query is the default entity of the "target type" of the "origin".
231 21 Yingdi Yu
232 42 Yingdi Yu
Possible values of target type include `ID`, `KEY`, and `CERT`.
233
Possible values of origin type include `USER`, `ID`, and `KEY`.
234
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`.)
235
The origin name should be consistent with the origin type.
236
Origin name is ignored if origin type is `USER`.
237
When wrong parameters are supplied, the content of response is an ErrorCode with value `ERR_WRONG_PARAM`.
238 37 Yingdi Yu
239 42 Yingdi Yu
If no error happens in processing the query, the response could be `PibIdentity`, `PibPublicKey`, or `PibCertificate`, depending on the target type.
240 37 Yingdi Yu
241 42 Yingdi Yu
### `List` Parameters
242 36 Yingdi Yu
243 42 Yingdi Yu
The parameters of `list` operation are defined as: 
244 36 Yingdi Yu
245 42 Yingdi Yu
    PibListParam := PIB-LIST-PARAM-TYPE TLV-LENGTH
246
                    PibType // origin type
247
                    Name?   // origin name
248 36 Yingdi Yu
249 42 Yingdi Yu
The response to the `list` query is a list of `Name`, depending on the origin type.
250
Possible values of origin type include `USER`, `ID`, and `KEY`.
251
Origin name is ignored if origin type is `USER`.
252
If the origin type is `USER`, the response is a list of identities of the user.
253
If the origin type is `ID`, the response is a list of names of keys of the identity.
254
If the origin type is `KEY`, the response is a list of names of certificates of the key.
255 1 Yingdi Yu
256 50 Yingdi Yu
    PibNameList := PIB-NAME-LIST-TYPE TLV-LENGTH
257
                   Name+
258
259 42 Yingdi Yu
### `Update` Parameters
260 1 Yingdi Yu
261 42 Yingdi Yu
The parameters of `update` operation are defined as: 
262 1 Yingdi Yu
263 45 Yingdi Yu
    PibUpdateParam := PIB-UPDATE-PARAM-TYPE TLV-LENGTH
264 59 Yingdi Yu
                      (PibUser | PibIdentity | PibPublicKey | PibCertificate)
265 42 Yingdi Yu
                      PibDefaultOpt
266 1 Yingdi Yu
267 42 Yingdi Yu
`DefaultOpt` is the default option:
268 1 Yingdi Yu
269
270 42 Yingdi Yu
    PibDefaultOpt := PIB-DEFAULT-OPT-TYPE TLV-LENGTH
271
                     nonNegativeInteger
272
273
DefaultOpt constant                         | Assigned value    | Assigned value (hex)
274 1 Yingdi Yu
------------------------------------------- | ----------------- | --------------------
275 54 Yingdi Yu
DEFAULT\_OPT\_NO                            | 0                 | 0x00
276
DEFAULT\_OPT\_KEY                           | 1                 | 0x01
277
DEFAULT\_OPT\_ID                            | 3                 | 0x03
278
DEFAULT\_OPT\_USER                          | 7                 | 0x07
279 1 Yingdi Yu
280 42 Yingdi Yu
The operation, once validated, will add a new entry in the corresponding table if no such an entry exists or update the existing entry,
281
and change the default setting according to `PibDefaultOpt`.
282 1 Yingdi Yu
283 42 Yingdi Yu
The response is always an ErrorCode: `ERR_SUCCESS` for a successful operation, others for failure.
284 1 Yingdi Yu
285 42 Yingdi Yu
### `Delete` Parameters
286 1 Yingdi Yu
287 42 Yingdi Yu
The parameters of `delete` operation are defined as: 
288
289 44 Yingdi Yu
    PibDeleteParam := PIB-DELETE-PARAM-TYPE TLV-LENGTH
290
                      PibType
291 42 Yingdi Yu
                      Name
292
293
The entity and its belonging entities will be deleted once the operation is validated.
294
295
The response is always an ErrorCode: `ERR_SUCCESS` for a successful deletion, others for failure.
296
297
### TLV-TYPE assignments
298
299
Type                                            | Assigned value    | Assigned value (hex)
300
----------------------------------------------- | ----------------- | --------------------
301
PibGetParam                                     | 128               | 0x80
302
PibDefaultParam                                 | 129               | 0x81
303 49 Yingdi Yu
PibListParam                                    | 130               | 0x82
304
PibUpdateParam                                  | 131               | 0x83
305
PibDeleteParam                                  | 132               | 0x84
306 43 Yingdi Yu
PibType                                         | 144               | 0x90
307
PibIdentity                                     | 145               | 0x91
308
PibPublicKey                                    | 146               | 0x92
309
PibCertificate                                  | 147               | 0x93
310
PibBytes                                        | 148               | 0x94 
311
PibDefaultOpt                                   | 149               | 0x95
312 52 Yingdi Yu
PibNameList                                     | 150               | 0x96
313 58 Yingdi Yu
PibUser                                         | 151               | 0x97
314 47 Yingdi Yu
PibErrorCode                                    | 252               | 0xfc