Project

General

Profile

PublicKey Info Base » History » Version 34

Yingdi Yu, 07/15/2014 09:23 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 8 Yingdi Yu
Four types of operations are defined: `get` (Read), `search` (Read), `update` (Write), and `delete` (Write).
124 5 Yingdi Yu
The operation `get` and `search` are quite similar to each other. 
125
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.
126
`Param` is a TLV block containing parameters of the query.
127
Different types of operations have their own parameters.
128
129
### `Get` Parameters
130
For `get` operation, `Param` is defined as:
131
132 23 Yingdi Yu
            GetParam := Type
133
                        Filter
134
              Filter := NameFilter | DefaultOfFilter | ListOfFilter
135 25 Yingdi Yu
          NameFilter := Name
136 26 Yingdi Yu
     DefaultOfFilter := Type
137
                        Name
138
        ListOfFilter := Type
139 23 Yingdi Yu
                        Name
140
                Type := ID | KEY | CERT
141 5 Yingdi Yu
142
`Type` indicates which table the query will be applied eventually.
143
`Filter` indicates how to apply the query. 
144
When `Name` is specified in `Filter`, PIB will directly lookup the entry with the same name in the table indicated by `Type`.
145
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`.
146
When `ListOf` is specified in `Filter`, PIB will collect all the entries that satisfy the condition specified in `ListOf`. 
147
Here are some examples of `GetParam`:
148
149
    GetParam 
150
    {
151
      Type: KEY
152
      Filter 
153
      {  
154
        Name: /ndn/edu/ucla/ksk-1234
155
      }
156
    }
157
158
The example above is a query to get a key with the name `/ndn/edu/ucla/ksk-1234`.
159
160
    GetParam
161
    {
162
      Type: CERT
163
      Filter 
164
      { 
165
        DefautOf 
166
        {
167
          Type: ID
168
          Name: /ndn/edu/ucla/alice
169
        }
170
      }
171
    }
172
173
The example above is a query to get the default certificate of an identity `/ndn/edu/ucla/alice`.
174
175
    GetParam
176
    {
177
      Type: CERT
178
      Filter 
179
      { 
180
        ListOf 
181
        {
182
          Type: KEY
183
          Name: /ndn/edu/ucla/ksk-1234
184
        }
185
      }
186
    }
187
188 10 Yingdi Yu
The example above is a query to get a list of certificates of a key `/ndn/edu/ucla/alice`.
189 5 Yingdi Yu
190
### `Search` Parameters
191
192
The parameters of `search` operation is quite similar to `get` operation except that there is no `ListOf` filter.
193
194 24 Yingdi Yu
          SearchParam := Type
195
                         Filter
196
               Filter := NameFilter | DefaultOfFilter
197
           NameFilter := Name
198 27 Yingdi Yu
      DefaultOfFilter := Type
199 24 Yingdi Yu
                         Name
200
                 Type := ID | KEY | CERT
201 10 Yingdi Yu
202 24 Yingdi Yu
The response to `search` operation is a boolean value to indicate the existence of the searched entity
203 5 Yingdi Yu
204
### `Update` Parameters
205
206
The parameters of `update` operation are defined as: 
207
208
    UpdateParam := Entity
209
                   DefaultOpt
210
         Entity := Identity | PublicKey | Certificate
211
       Identity := Name
212
      PublicKey := Name
213
                   Bytes
214 31 Yingdi Yu
    Certificate := Data
215 5 Yingdi Yu
     DefaultOpt := USER_DEFAULT | ID_DEFAULT | KEY_DEFAULT | NO_DEFAULT
216
217 7 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,
218 1 Yingdi Yu
and change the default setting according to `DefaultOpt`.
219
220 8 Yingdi Yu
### `Delete` Parameters
221 1 Yingdi Yu
222 8 Yingdi Yu
The parameters of `delete` operation are defined as: 
223
224 28 Yingdi Yu
    DeleteParam := Type
225 8 Yingdi Yu
                   Name
226
           Type := ID | KEY | CERT
227
228 11 Yingdi Yu
The entity and its belonging entities will be deleted once the operation is validated.
229 8 Yingdi Yu
230 1 Yingdi Yu
### TLV-TYPE assignments
231
232
Type                                        | Assigned value    | Assigned value (hex)
233
------------------------------------------- | ----------------- | --------------------
234
GetParam                                    | 128               | 0x80
235
SearchParam                                 | 129               | 0x81
236
UpdateParam                                 | 130               | 0x82
237 8 Yingdi Yu
DeleteParam                                 | 131               | 0x83
238
Type                                        | 132               | 0x84
239 22 Yingdi Yu
NameFilter                                  | 133               | 0x85
240
DefaultOfFilter                             | 134               | 0x86
241
ListOfFilter                                | 135               | 0x87
242 30 Yingdi Yu
Identity                                    | 136               | 0x88
243
PublicKey                                   | 137               | 0x89
244
Certificate                                 | 138               | 0x8a
245
Bytes                                       | 139               | 0x8b 
246
DefaultOpt                                  | 140               | 0x8c
247 5 Yingdi Yu
248
### Constant value assignments
249
250
For type `Type`:
251
252
Constant                                    | Assigned value    | Assigned value (hex)
253
------------------------------------------- | ----------------- | --------------------
254
ID                                          | 0                 | 0x00
255
KEY                                         | 1                 | 0x01
256
CERT                                        | 2                 | 0x02
257
258
For type `DefaultOpt`:
259
260
Constant                                    | Assigned value    | Assigned value (hex)
261
------------------------------------------- | ----------------- | --------------------
262 1 Yingdi Yu
NO_DEFAULT                                  | 0                 | 0x00
263
USER_DEFAULT                                | 1                 | 0x01
264
ID_DEFAULT                                  | 2                 | 0x02
265
KEY_DEFAULT                                 | 3                 | 0x03
266 12 Yingdi Yu
267
### Query Responses
268
269
The response to a query interest is a data packet signed by PIB.
270
The public key certificate of PIB is stored in a read-only file and is accessible to all users on the system.
271
 
272
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.
273
The content of the response to `search` operation is a byte. Non-zero byte stands for true while 0x00 stands for false.
274 20 Yingdi Yu
The content of the response to `update` or `delete` operation is an uint32_t which serves as an error code. 
275 21 Yingdi Yu
0 stands for success while non-zero byte stands for failure. 
276 13 Yingdi Yu
277
Error code for `update`:
278
279
Error code              | Value             | Description
280
----------------------- | ----------------- | --------------------
281
ERR_SUCCESS             | 0                 | No error
282
283
Error code for `delete`:
284
285
Error code              | Value             | Description
286
----------------------- | ----------------- | --------------------
287
ERR_SUCCESS             | 0                 | No error