Project

General

Profile

PublicKey Info Base » History » Version 64

Yingdi Yu, 07/23/2014 06:45 PM

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 63 Yingdi Yu
* The root user has its own **local management key**. The root user key has the highest privilege, i.e., its owner is allowed to change anything in PIB. The identity of the root key is `/localhost/pib/user`, and the name of the root key should be `/localhost//pib/user/[KeyId]`. Any change to root user's local management key should be done offline and requires super user privilege.
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/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.
109
* 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.
110
111
112
113
114 3 Yingdi Yu
115
## PIB Service Protocol 
116
117
PIB service provides an interface to NDN applications for public key info lookup. 
118 1 Yingdi Yu
The interface is defined in terms of NDN packets (interest/data).
119 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).
120 5 Yingdi Yu
The query interest is defined as:
121
122
    /localhost/pib/[UserName]/[Verb]/[Param]/<signed_interest_security_components>
123 34 Yingdi Yu
                                            |<-- Required for Write operation -->|
124 5 Yingdi Yu
125
`UserName` indicates the tables in which the query should apply.
126
`Verb` indicates the access operation. 
127 42 Yingdi Yu
Five types of operations are defined: 
128 40 Yingdi Yu
129 41 Yingdi Yu
Verb                 | Access Type       | Description
130 42 Yingdi Yu
-------------------- | ----------------- | ----------------------------------------------------------
131
Get                  | Read              | Get a single entity (user, identity, key, or certificate)
132 41 Yingdi Yu
Default              | Read              | Get the default setting of an entity
133
List                 | Read              | List the name of a set of entities
134 1 Yingdi Yu
Update               | Write             | Add/Change an entity
135
Delete               | Write             | Delete an entity
136
137
`Param` is a TLV block containing parameters of the query.
138
Different types of operations have their own parameters.
139
140 42 Yingdi Yu
### Query Responses
141
142
The response to a query interest is a data packet signed by PIB.
143
The public key certificate of PIB is stored in a read-only file and is accessible to all users on the system.
144
145
Several TLVs are defined for the content of query responses.
146
`Identity` TLV:
147
148
    PibIdentity := PIB-IDENTITY-TYPE TLV-LENGTH
149
                   Name
150
151
`PublicKey` TLV:
152
153
    PibPublicKey := PIB-PUBLIC-KEY-TYPE TLV-LENGTH
154
                    Name
155
                    PibBytes
156
157
`Certificate` TLV:
158
159
    PibCertificate := PIB-CERTIFICATE-TYPE TLV-LENGTH
160
                      Data 
161 55 Yingdi Yu
162
`User` TLV:
163
164
    PibUser := PIB-USER-TYPE TLV-LENGTH
165
               Data // local management certificate
166 56 Yingdi Yu
               ...  // Other information to add if exists
167 42 Yingdi Yu
 
168
A response may also be a error code defined a non-negative integer:
169
170 64 Yingdi Yu
     PibError := PIB-ERROR-TYPE TLV-LENGTH
171 53 Yingdi Yu
                 ErrorCode
172
                 Bytes
173
174 42 Yingdi Yu
    ErrorCode := ERROR-CODE-TYPE TLV-LENGTH
175
                 nonNegativeInteger
176
177
Error code                    | Value             | Description
178
----------------------------- | ----------------- | ----------------------------------
179
ERR\_SUCCESS                  | 0                 | No error
180
ERR\_INCOMPLETE\_COMMAND      | 1                 | Incomplete interest
181
ERR\_WRONG\_VERB              | 2                 | Wrong verb in interest
182
ERR\_WRONG\_PARAM             | 3                 | Wrong parameter in interest
183
ERR\_NON\_EXISTING\_USER      | 128               | User does not exist
184
ERR\_NON\_EXISTING\_ID        | 129               | Identity does not exist
185
ERR\_NON\_EXISTING\_KEY       | 130               | Public key does not exist
186
ERR\_NON\_EXISTING\_CERT      | 131               | Certificate does not exist
187
ERR\_NO\_DEFAULT\_ID          | 256               | No default identity is set
188
ERR\_NO\_DEFAULT\_KEY         | 257               | No default public key is set 
189
ERR\_NO\_DEFAULT\_CERT        | 258               | No default certificate is set
190
ERR\_DELETE\_DEFAULT\_SETTING | 384               | Trying to delete default setting
191
192 62 Yingdi Yu
A response is signed by a PIB instance key with the name `/localhost/pib/dsk-...`.
193
The PIB instance key is signed by another key with the name `/localhost/pib/ksk-...` which is the trust anchor of the PIB service.
194
195 11 Yingdi Yu
### `Get` Parameters
196 8 Yingdi Yu
For `get` operation, `Param` is defined as:
197 1 Yingdi Yu
198 42 Yingdi Yu
    PibGetParam := PIB-GET-PARAM-TYPE TLV-LENGTH
199
                   PibType
200
                   Name?
201 1 Yingdi Yu
202
`Type` indicates which table the query will be applied eventually.
203
204 42 Yingdi Yu
    PibType := PIB-TYPE-TYPE TLV-LENGTH
205
               nonNegativeInteger
206 22 Yingdi Yu
207 42 Yingdi Yu
Type constant                               | Assigned value    | Assigned value (hex)
208
------------------------------------------- | ----------------- | --------------------
209
USER                                        | 0                 | 0x00
210
ID                                          | 1                 | 0x01
211
KEY                                         | 2                 | 0x02
212
CERT                                        | 3                 | 0x03
213 30 Yingdi Yu
214 5 Yingdi Yu
215 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).
216
Name is ignored if type is USER.
217 5 Yingdi Yu
218 42 Yingdi Yu
If error happens during processing the query, the content of the response is an ErrorCode TLV.
219
If no error happens, the content depends on the `Type`.
220 5 Yingdi Yu
When `Type` is `ID`, the query is actually invalid. 
221 42 Yingdi Yu
The response is an ErrorCode with value `ERR_WRONG_PARAM`.
222
223 57 Yingdi Yu
For `USER`, the content is a `PibUser` TLV.
224 42 Yingdi Yu
For `KEY`, the content is a `PibPublicKey` TLV. 
225 48 Yingdi Yu
For `CERT`, the content is a `PibCertificate` TLV.
226 1 Yingdi Yu
227 42 Yingdi Yu
### `Default` Parameters
228 1 Yingdi Yu
229 42 Yingdi Yu
The parameters of `default` operation is defined as.
230 12 Yingdi Yu
231 42 Yingdi Yu
      PibDefaultParam := PIB-DEFAULT-PARAM-TYPE TLV-LENGTH
232
                         PibType    // target type
233
                         PibType    // origin type
234
                         Name?      // origin name
235 12 Yingdi Yu
236
237 42 Yingdi Yu
The response to a `default` query is the default entity of the "target type" of the "origin".
238 21 Yingdi Yu
239 42 Yingdi Yu
Possible values of target type include `ID`, `KEY`, and `CERT`.
240
Possible values of origin type include `USER`, `ID`, and `KEY`.
241
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`.)
242
The origin name should be consistent with the origin type.
243
Origin name is ignored if origin type is `USER`.
244
When wrong parameters are supplied, the content of response is an ErrorCode with value `ERR_WRONG_PARAM`.
245 37 Yingdi Yu
246 42 Yingdi Yu
If no error happens in processing the query, the response could be `PibIdentity`, `PibPublicKey`, or `PibCertificate`, depending on the target type.
247 37 Yingdi Yu
248 42 Yingdi Yu
### `List` Parameters
249 36 Yingdi Yu
250 42 Yingdi Yu
The parameters of `list` operation are defined as: 
251 36 Yingdi Yu
252 42 Yingdi Yu
    PibListParam := PIB-LIST-PARAM-TYPE TLV-LENGTH
253
                    PibType // origin type
254
                    Name?   // origin name
255 36 Yingdi Yu
256 42 Yingdi Yu
The response to the `list` query is a list of `Name`, depending on the origin type.
257
Possible values of origin type include `USER`, `ID`, and `KEY`.
258
Origin name is ignored if origin type is `USER`.
259
If the origin type is `USER`, the response is a list of identities of the user.
260
If the origin type is `ID`, the response is a list of names of keys of the identity.
261
If the origin type is `KEY`, the response is a list of names of certificates of the key.
262 1 Yingdi Yu
263 50 Yingdi Yu
    PibNameList := PIB-NAME-LIST-TYPE TLV-LENGTH
264
                   Name+
265
266 42 Yingdi Yu
### `Update` Parameters
267 1 Yingdi Yu
268 42 Yingdi Yu
The parameters of `update` operation are defined as: 
269 1 Yingdi Yu
270 45 Yingdi Yu
    PibUpdateParam := PIB-UPDATE-PARAM-TYPE TLV-LENGTH
271 59 Yingdi Yu
                      (PibUser | PibIdentity | PibPublicKey | PibCertificate)
272 42 Yingdi Yu
                      PibDefaultOpt
273 1 Yingdi Yu
274 42 Yingdi Yu
`DefaultOpt` is the default option:
275 1 Yingdi Yu
276
277 42 Yingdi Yu
    PibDefaultOpt := PIB-DEFAULT-OPT-TYPE TLV-LENGTH
278
                     nonNegativeInteger
279
280
DefaultOpt constant                         | Assigned value    | Assigned value (hex)
281 1 Yingdi Yu
------------------------------------------- | ----------------- | --------------------
282 54 Yingdi Yu
DEFAULT\_OPT\_NO                            | 0                 | 0x00
283
DEFAULT\_OPT\_KEY                           | 1                 | 0x01
284
DEFAULT\_OPT\_ID                            | 3                 | 0x03
285
DEFAULT\_OPT\_USER                          | 7                 | 0x07
286 1 Yingdi Yu
287 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,
288
and change the default setting according to `PibDefaultOpt`.
289 1 Yingdi Yu
290 42 Yingdi Yu
The response is always an ErrorCode: `ERR_SUCCESS` for a successful operation, others for failure.
291 1 Yingdi Yu
292 42 Yingdi Yu
### `Delete` Parameters
293 1 Yingdi Yu
294 42 Yingdi Yu
The parameters of `delete` operation are defined as: 
295
296 44 Yingdi Yu
    PibDeleteParam := PIB-DELETE-PARAM-TYPE TLV-LENGTH
297
                      PibType
298 42 Yingdi Yu
                      Name
299
300
The entity and its belonging entities will be deleted once the operation is validated.
301
302
The response is always an ErrorCode: `ERR_SUCCESS` for a successful deletion, others for failure.
303
304
### TLV-TYPE assignments
305
306
Type                                            | Assigned value    | Assigned value (hex)
307
----------------------------------------------- | ----------------- | --------------------
308
PibGetParam                                     | 128               | 0x80
309
PibDefaultParam                                 | 129               | 0x81
310 49 Yingdi Yu
PibListParam                                    | 130               | 0x82
311
PibUpdateParam                                  | 131               | 0x83
312
PibDeleteParam                                  | 132               | 0x84
313 43 Yingdi Yu
PibType                                         | 144               | 0x90
314
PibIdentity                                     | 145               | 0x91
315
PibPublicKey                                    | 146               | 0x92
316
PibCertificate                                  | 147               | 0x93
317
PibBytes                                        | 148               | 0x94 
318
PibDefaultOpt                                   | 149               | 0x95
319 52 Yingdi Yu
PibNameList                                     | 150               | 0x96
320 58 Yingdi Yu
PibUser                                         | 151               | 0x97
321 47 Yingdi Yu
PibErrorCode                                    | 252               | 0xfc