Project

General

Profile

PublicKey Info Base » History » Version 78

Davide Pesavento, 06/28/2020 02:27 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 68 Yingdi Yu
PIB service is run as a separate service for each user.
38 1 Yingdi Yu
39 66 Yingdi Yu
Users' public key information is managed in three tables in PIB: identity table, key table, and certificate table.
40 1 Yingdi Yu
Identity table schema:
41
42 76 Yingdi Yu
    identities(
43 68 Yingdi Yu
        id                   INTEGER PRIMARY KEY,
44 1 Yingdi Yu
        identity             BLOB NOT NULL,        
45 76 Yingdi Yu
        is_default           INTEGER DEFAULT 0
46 68 Yingdi Yu
    );
47 66 Yingdi Yu
48 68 Yingdi Yu
A unique index is created on (identity).
49
50 1 Yingdi Yu
Key table schema:
51 4 Yingdi Yu
52 76 Yingdi Yu
    keys(
53 68 Yingdi Yu
        id                   INTEGER PRIMARY KEY,
54 66 Yingdi Yu
        identity             BLOB NOT NULL,        
55
        key_id               BLOB NOT NULL,        
56 18 Yingdi Yu
        key_type             INTEGER NOT NULL,     
57 1 Yingdi Yu
        key_bits             BLOB NOT NULL,        
58 76 Yingdi Yu
        is_default           INTEGER DEFAULT 0,
59 68 Yingdi Yu
        FOREIGN KEY(identity) REFERENCES identities(identity) ON DELETE CASCADE             
60
    );    
61 1 Yingdi Yu
62 68 Yingdi Yu
A unique index is created on (identity, key_id).
63
64 1 Yingdi Yu
Certificate table schema:
65 66 Yingdi Yu
66 76 Yingdi Yu
    certificates(
67 68 Yingdi Yu
        id                   INTEGER PRIMARY KEY,
68 18 Yingdi Yu
        certificate_name     BLOB NOT NULL,        
69
        identity             BLOB NOT NULL,        
70
        key_id               BLOB NOT NULL,        
71
        certificate_data     BLOB NOT NULL,        
72 76 Yingdi Yu
        is_default           INTEGER DEFAULT 0,
73 68 Yingdi Yu
        FOREIGN KEY(identity, key_id) REFERENCES keys(identity, key_id) ON DELETE CASCADE
74 4 Yingdi Yu
    );
75 3 Yingdi Yu
76 68 Yingdi Yu
A unique index is created on (certificate_name).
77 1 Yingdi Yu
78 68 Yingdi Yu
Besides these tables  PIB has one more management tables: `mgmt` table.
79
`mgmt` table stores owner name, corresponding tpm locator, and local management key (we will discuss it later).
80
81 19 Yingdi Yu
User table schema:
82
83 75 Yingdi Yu
    mgmt(                                       
84 68 Yingdi Yu
        id                    INTEGER PRIMARY KEY
85
        owner                 BLOB NOT NULL,
86
        tpm_locator           BLOB,
87 19 Yingdi Yu
        local_management_cert BLOB NOT NULL,    
88 5 Yingdi Yu
    );
89 4 Yingdi Yu
90 68 Yingdi Yu
The read access to PIB is not restricted,
91
while the write access to PIB requires authentication.
92 63 Yingdi Yu
The write access is expressed as signed commands. 
93
The signing key can be authenticated only if the key already exists in the corresponding user's PIB tables.
94
Each key has its own write access privilege which is defined as:
95
96 68 Yingdi Yu
* 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.
97 63 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`. Importing a self-signed regular key requires the signature generated by the corresponding user's local management key.
98 3 Yingdi Yu
99
## PIB Service Protocol 
100
101
PIB service provides an interface to NDN applications for public key info lookup. 
102 1 Yingdi Yu
The interface is defined in terms of NDN packets (interest/data).
103 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).
104 5 Yingdi Yu
The query interest is defined as:
105
106
    /localhost/pib/[UserName]/[Verb]/[Param]/<signed_interest_security_components>
107 34 Yingdi Yu
                                            |<-- Required for Write operation -->|
108 5 Yingdi Yu
109
`UserName` indicates the tables in which the query should apply.
110
`Verb` indicates the access operation. 
111 42 Yingdi Yu
Five types of operations are defined: 
112 40 Yingdi Yu
113 41 Yingdi Yu
Verb                 | Access Type       | Description
114 42 Yingdi Yu
-------------------- | ----------------- | ----------------------------------------------------------
115
Get                  | Read              | Get a single entity (user, identity, key, or certificate)
116 41 Yingdi Yu
Default              | Read              | Get the default setting of an entity
117
List                 | Read              | List the name of a set of entities
118 1 Yingdi Yu
Update               | Write             | Add/Change an entity
119
Delete               | Write             | Delete an entity
120
121
`Param` is a TLV block containing parameters of the query.
122
Different types of operations have their own parameters.
123
124 42 Yingdi Yu
### Query Responses
125
126
The response to a query interest is a data packet signed by PIB.
127
The public key certificate of PIB is stored in a read-only file and is accessible to all users on the system.
128
129
Several TLVs are defined for the content of query responses.
130
`Identity` TLV:
131
132
    PibIdentity := PIB-IDENTITY-TYPE TLV-LENGTH
133
                   Name
134
135
`PublicKey` TLV:
136
137
    PibPublicKey := PIB-PUBLIC-KEY-TYPE TLV-LENGTH
138
                    Name
139
                    PibBytes
140
141
`Certificate` TLV:
142
143
    PibCertificate := PIB-CERTIFICATE-TYPE TLV-LENGTH
144
                      Data 
145 55 Yingdi Yu
146
`User` TLV:
147
148
    PibUser := PIB-USER-TYPE TLV-LENGTH
149
               Data // local management certificate
150 56 Yingdi Yu
               ...  // Other information to add if exists
151 42 Yingdi Yu
 
152
A response may also be a error code defined a non-negative integer:
153
154 64 Yingdi Yu
     PibError := PIB-ERROR-TYPE TLV-LENGTH
155 53 Yingdi Yu
                 ErrorCode
156
                 Bytes
157
158 78 Davide Pesavento
    ErrorCode := ERROR-CODE-TYPE TLV-LENGTH NonNegativeInteger
159 42 Yingdi Yu
160
Error code                    | Value             | Description
161
----------------------------- | ----------------- | ----------------------------------
162
ERR\_SUCCESS                  | 0                 | No error
163
ERR\_INCOMPLETE\_COMMAND      | 1                 | Incomplete interest
164
ERR\_WRONG\_VERB              | 2                 | Wrong verb in interest
165
ERR\_WRONG\_PARAM             | 3                 | Wrong parameter in interest
166
ERR\_NON\_EXISTING\_USER      | 128               | User does not exist
167
ERR\_NON\_EXISTING\_ID        | 129               | Identity does not exist
168
ERR\_NON\_EXISTING\_KEY       | 130               | Public key does not exist
169
ERR\_NON\_EXISTING\_CERT      | 131               | Certificate does not exist
170
ERR\_NO\_DEFAULT\_ID          | 256               | No default identity is set
171
ERR\_NO\_DEFAULT\_KEY         | 257               | No default public key is set 
172
ERR\_NO\_DEFAULT\_CERT        | 258               | No default certificate is set
173
ERR\_DELETE\_DEFAULT\_SETTING | 384               | Trying to delete default setting
174
175 70 Yingdi Yu
A response is signed by a PIB instance key with the name `/localhost/pib/[UserName]/dsk-...`.
176
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.
177 73 Yingdi Yu
Note that it is difference from the management key name which is `/localhost/pib/`**user**`/[UserName]/dsk-...`.
178 74 Yingdi Yu
Management key is used by PIB owner to sign update/delete command interest,
179
while PIB instance key is used by PIB service to sign PIB responses.
180 62 Yingdi Yu
181 11 Yingdi Yu
### `Get` Parameters
182 8 Yingdi Yu
For `get` operation, `Param` is defined as:
183 1 Yingdi Yu
184 42 Yingdi Yu
    PibGetParam := PIB-GET-PARAM-TYPE TLV-LENGTH
185
                   PibType
186
                   Name?
187 1 Yingdi Yu
188
`Type` indicates which table the query will be applied eventually.
189 42 Yingdi Yu
190 78 Davide Pesavento
    PibType := PIB-TYPE-TYPE TLV-LENGTH NonNegativeInteger
191 22 Yingdi Yu
192 42 Yingdi Yu
Type constant                               | Assigned value    | Assigned value (hex)
193
------------------------------------------- | ----------------- | --------------------
194
USER                                        | 0                 | 0x00
195
ID                                          | 1                 | 0x01
196
KEY                                         | 2                 | 0x02
197
CERT                                        | 3                 | 0x03
198 30 Yingdi Yu
199 5 Yingdi Yu
200 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).
201
Name is ignored if type is USER.
202 5 Yingdi Yu
203 42 Yingdi Yu
If error happens during processing the query, the content of the response is an ErrorCode TLV.
204
If no error happens, the content depends on the `Type`.
205 5 Yingdi Yu
When `Type` is `ID`, the query is actually invalid. 
206 42 Yingdi Yu
The response is an ErrorCode with value `ERR_WRONG_PARAM`.
207
208 57 Yingdi Yu
For `USER`, the content is a `PibUser` TLV.
209 42 Yingdi Yu
For `KEY`, the content is a `PibPublicKey` TLV. 
210 48 Yingdi Yu
For `CERT`, the content is a `PibCertificate` TLV.
211 1 Yingdi Yu
212 42 Yingdi Yu
### `Default` Parameters
213 1 Yingdi Yu
214 42 Yingdi Yu
The parameters of `default` operation is defined as.
215 12 Yingdi Yu
216 42 Yingdi Yu
      PibDefaultParam := PIB-DEFAULT-PARAM-TYPE TLV-LENGTH
217
                         PibType    // target type
218
                         PibType    // origin type
219
                         Name?      // origin name
220 12 Yingdi Yu
221
222 42 Yingdi Yu
The response to a `default` query is the default entity of the "target type" of the "origin".
223 21 Yingdi Yu
224 42 Yingdi Yu
Possible values of target type include `ID`, `KEY`, and `CERT`.
225
Possible values of origin type include `USER`, `ID`, and `KEY`.
226
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`.)
227
The origin name should be consistent with the origin type.
228
Origin name is ignored if origin type is `USER`.
229
When wrong parameters are supplied, the content of response is an ErrorCode with value `ERR_WRONG_PARAM`.
230 37 Yingdi Yu
231 42 Yingdi Yu
If no error happens in processing the query, the response could be `PibIdentity`, `PibPublicKey`, or `PibCertificate`, depending on the target type.
232 37 Yingdi Yu
233 42 Yingdi Yu
### `List` Parameters
234 36 Yingdi Yu
235 42 Yingdi Yu
The parameters of `list` operation are defined as: 
236 36 Yingdi Yu
237 42 Yingdi Yu
    PibListParam := PIB-LIST-PARAM-TYPE TLV-LENGTH
238
                    PibType // origin type
239
                    Name?   // origin name
240 36 Yingdi Yu
241 42 Yingdi Yu
The response to the `list` query is a list of `Name`, depending on the origin type.
242
Possible values of origin type include `USER`, `ID`, and `KEY`.
243
Origin name is ignored if origin type is `USER`.
244
If the origin type is `USER`, the response is a list of identities of the user.
245
If the origin type is `ID`, the response is a list of names of keys of the identity.
246
If the origin type is `KEY`, the response is a list of names of certificates of the key.
247 1 Yingdi Yu
248 50 Yingdi Yu
    PibNameList := PIB-NAME-LIST-TYPE TLV-LENGTH
249
                   Name+
250
251 42 Yingdi Yu
### `Update` Parameters
252 1 Yingdi Yu
253 42 Yingdi Yu
The parameters of `update` operation are defined as: 
254 1 Yingdi Yu
255 45 Yingdi Yu
    PibUpdateParam := PIB-UPDATE-PARAM-TYPE TLV-LENGTH
256 59 Yingdi Yu
                      (PibUser | PibIdentity | PibPublicKey | PibCertificate)
257 42 Yingdi Yu
                      PibDefaultOpt
258 1 Yingdi Yu
259
`DefaultOpt` is the default option:
260
261 42 Yingdi Yu
262 78 Davide Pesavento
    PibDefaultOpt := PIB-DEFAULT-OPT-TYPE TLV-LENGTH NonNegativeInteger
263 42 Yingdi Yu
264
DefaultOpt constant                         | Assigned value    | Assigned value (hex)
265 1 Yingdi Yu
------------------------------------------- | ----------------- | --------------------
266 54 Yingdi Yu
DEFAULT\_OPT\_NO                            | 0                 | 0x00
267
DEFAULT\_OPT\_KEY                           | 1                 | 0x01
268
DEFAULT\_OPT\_ID                            | 3                 | 0x03
269
DEFAULT\_OPT\_USER                          | 7                 | 0x07
270 1 Yingdi Yu
271 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,
272
and change the default setting according to `PibDefaultOpt`.
273 1 Yingdi Yu
274 42 Yingdi Yu
The response is always an ErrorCode: `ERR_SUCCESS` for a successful operation, others for failure.
275 1 Yingdi Yu
276 42 Yingdi Yu
### `Delete` Parameters
277 1 Yingdi Yu
278 42 Yingdi Yu
The parameters of `delete` operation are defined as: 
279
280 44 Yingdi Yu
    PibDeleteParam := PIB-DELETE-PARAM-TYPE TLV-LENGTH
281
                      PibType
282 42 Yingdi Yu
                      Name
283
284
The entity and its belonging entities will be deleted once the operation is validated.
285
286
The response is always an ErrorCode: `ERR_SUCCESS` for a successful deletion, others for failure.
287
288
### TLV-TYPE assignments
289
290
Type                                            | Assigned value    | Assigned value (hex)
291
----------------------------------------------- | ----------------- | --------------------
292
PibGetParam                                     | 128               | 0x80
293
PibDefaultParam                                 | 129               | 0x81
294 49 Yingdi Yu
PibListParam                                    | 130               | 0x82
295
PibUpdateParam                                  | 131               | 0x83
296
PibDeleteParam                                  | 132               | 0x84
297 77 Yingdi Yu
PibUser                                         | 144               | 0x90
298 43 Yingdi Yu
PibIdentity                                     | 145               | 0x91
299
PibPublicKey                                    | 146               | 0x92
300
PibCertificate                                  | 147               | 0x93
301
PibBytes                                        | 148               | 0x94 
302
PibDefaultOpt                                   | 149               | 0x95
303 52 Yingdi Yu
PibNameList                                     | 150               | 0x96
304 77 Yingdi Yu
PibType                                         | 151               | 0x97
305 58 Yingdi Yu
PibError                                        | 152               | 0x98
306 77 Yingdi Yu
PibTpmLocator                                   | 153               | 0x99
307 47 Yingdi Yu
PibErrorCode                                    | 252               | 0xfc
308 67 Yingdi Yu
309
## Misc
310
311
In that case root user's private key is lost in TPM, you have to delete the root user directly in the database. 
312
Since the database file is guarded by filesystem, only system admin can do that.