idnits 2.17.1 draft-petithuguenin-p2psip-access-control-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- -- The document has an IETF Trust Provisions (28 Dec 2009) Section 6.c(i) Publication Limitation clause. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 5, 2011) is 4672 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '16' on line 441 -- Looks like a reference, but probably isn't: '17' on line 441 ** Downref: Normative reference to an Informational RFC: RFC 1952 == Outdated reference: A later version (-26) exists of draft-ietf-p2psip-base-15 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMA-262' -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) == Outdated reference: A later version (-15) exists of draft-ietf-p2psip-service-discovery-03 == Outdated reference: A later version (-04) exists of draft-petithuguenin-vipr-reload-usage-01 == Outdated reference: A later version (-03) exists of draft-knauf-p2psip-share-00 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Petit-Huguenin 3 Internet-Draft Stonyfish, Inc. 4 Intended status: Standards Track July 5, 2011 5 Expires: January 6, 2012 7 Configuration of Access Control Policy in REsource LOcation And 8 Discovery (RELOAD) Base Protocol 9 draft-petithuguenin-p2psip-access-control-03 11 Abstract 13 This document describes an extension to the REsource LOcation And 14 Discovery (RELOAD) base protocol to distribute the code of new Access 15 Control Policies without having to upgrade the RELOAD implementations 16 in an overlay. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. This document may not be modified, 22 and derivative works of it may not be created, except to format it 23 for publication as an RFC or to translate it into languages other 24 than English. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 6, 2012. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 60 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 61 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 7.1. Normative References . . . . . . . . . . . . . . . . . . . 7 63 7.2. Informative References . . . . . . . . . . . . . . . . . . 7 64 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 8 65 A.1. Standard Access Control Policies . . . . . . . . . . . . . 8 66 A.1.1. USER-MATCH . . . . . . . . . . . . . . . . . . . . . . 8 67 A.1.2. NODE-MATCH . . . . . . . . . . . . . . . . . . . . . . 8 68 A.1.3. USER-NODE-MATCH . . . . . . . . . . . . . . . . . . . 8 69 A.1.4. NODE-MULTIPLE . . . . . . . . . . . . . . . . . . . . 9 70 A.2. Service Discovery Access Control Policy NODE-ID-MATCH . . 9 71 A.3. VIPR Access Control Policy . . . . . . . . . . . . . . . . 11 72 Appendix B. Release notes . . . . . . . . . . . . . . . . . . . . 11 73 B.1. Modifications between -03 and -02 . . . . . . . . . . . . 11 74 B.2. Modifications between -02 and -01 . . . . . . . . . . . . 12 75 B.3. Modifications between -01 and -00 . . . . . . . . . . . . 12 76 B.4. Running Code Considerations . . . . . . . . . . . . . . . 12 77 B.5. TODO List . . . . . . . . . . . . . . . . . . . . . . . . 12 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 80 1. Introduction 82 The RELOAD base protocol specifies an Access Control Policy as 83 "defin[ing] whether a request from a given node to operate on a given 84 value should succeed or fail." The paragraph continues saying that 85 "[i]t is anticipated that only a small number of generic access 86 control policies are required", but there is indications that this 87 assumption will not hold. On all the RELOAD Usages defined in other 88 documents than the RELOAD base protocol, roughly 50% defines a new 89 Access Control Policy. 91 The problem with a new Access Control Policy is that, because it is 92 executed when a Store request is processed, it needs to be 93 implemented by all the peers and so requires an upgrade of the 94 software. This is something that is probably not possible in large 95 overlays or on overlays using different implementations. For this 96 reason, this document proposes an extension to the RELOAD 97 configuration document that permits to transport the code of a new 98 Access Control Policy to each peer. 100 This extension defines a new element that can 101 be optionally added to a element in the configuration 102 document. The element contains ECMAScript 103 [ECMA-262] code that will be called for each StoredData object that 104 use this access control policy. The code receives four parameters, 105 corresponding to the Resource-ID, Signature, Kind and StoredDataValue 106 of the value to store. The code returns true or false to signal to 107 the implementation if the request should succeed or fail. 109 For example the USER-MATCH Access Control Policy defined in the base 110 protocol could be redefined by inserting the following code in an 111 element: 113 return resource.equalsHash(signer.user_name.bytes()); 115 The parameters are also passed to the code, so the NODE- 116 MULTIPLE Access Control Policy could be implemented like this: 118 for (var i = 0; i < kind.max_node_multiple; i++) { 119 if (resource.equalsHash(signer.node_id, i.width(4))) { 120 return true; 121 } 122 } 123 return false; 125 2. Terminology 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 129 document are to be interpreted as described in [RFC2119]. 131 3. Processing 133 A peer receiving a configuration document containing one or more 134 elements, either by retrieving it from the 135 configuration server or in a ConfigUpdateReq message, MUST reject 136 this configuration if is not is not signed or if the signature 137 verification fails. 139 The Compact Relax NG Grammar for this element is: 141 namespace acp = "http://implementers.org/access-control" 143 parameter &= element acp:access-control-code { 144 attribute name { xsd:string }, 145 xsd:base64Binary 146 }? 148 The "name" attribute defines the access control policy and can then 149 be used in a element as if it was defined by IANA. 151 If the element is present in the namespace 152 allocated to this specification, and the Access Control Policy is not 153 natively implemented, then the code inside the element MUST be called 154 for each DataValue found in a received StoreReq for a Kind that is 155 defined with this access control policy. The content of the element MUST be decoded using the base64 [RFC4648] 157 encoding, uncompressed using gzip [RFC1952] then converted to 158 characters using UTF-8. elements that are not 159 encoded using UTF-8, compressed with gzip or finally converted to the 160 base64 format MUST be ignored. For each call to the code, the 161 following ECMAScript objects, properties and functions MUST be 162 available: 164 configuration.instance_name: The name of the overlay, as a String 165 object. 166 configuration.topology_plugin: The overlay algorithm, as a String 167 object. 169 configuration.node_id_length: The length of a NodeId in bytes, as a 170 Number object. 171 configuration.evaluate(String, String, String): A function that 172 evaluates the first parameter as an XPath expression against the 173 configuration element, and returns the result as a String object. 174 The second parameter must contain a namespace prefix and the third 175 parameter must contain a namespace. 176 kind.id: The id of the Kind associated with the entry, as a Number 177 object. 178 kind.name: If the Kind associated with the entry is registered by 179 IANA, contains the name as a String object. If not, this property 180 is undefined. 181 kind.data_model: The name of the Data Model associated with the 182 entry, as a String object. 183 kind.access_control: The name of the Access Control Policy 184 associated with the entry, as a String object. 185 kind.max_count: The value of the max-count element in the 186 configuration file, as a Number object. 187 kind.max_size: The value of the max-size element in the 188 configuration file as a Number object. 189 kind.max_node_multiple: If the Access Control is MULTIPLE-NODE, 190 contains the value of the max-node-multiple element in the 191 configuration file, as a Number object. If not, this property is 192 undefined. 193 kind.evaluate(String, String, String): A function that evaluates the 194 first parameter as an XPath expression against the kind element, 195 and returns the result as a String object. The second parameter 196 must contain a namespace prefix and the third parameter must 197 contain a namespace. 198 resource: An opaque object representing the Resource-ID, as an array 199 of bytes. 200 resource.equalsHash(Object...): A function that returns true if 201 hashing the concatenation of the arguments according to the 202 mapping function of the overlay algorithm is equal to the 203 Resource-ID. Each argument is an array of bytes. 204 signer.user_name: The rfc822Name stored in the certificate that was 205 used to sign the request, as a String object. 206 signer.node_id: The Node-ID stored in the certificate that was used 207 to sign the request, as an array of bytes. 208 entry.index: If the Data Model is ARRAY, contains the index of the 209 entry, as a Number object. If not, this property is undefined. 210 entry.key: If the Data Model is DICTIONARY, contains the key of the 211 entry, as an array of bytes. If not, this property is undefined. 212 entry.storage_time: The date and time used to store the entry, as a 213 Date object. 215 entry.lifetime: The validity for the entry in seconds, as a Number 216 object. 217 entry.exists: Indicates if the entry value exists, as Boolean 218 object. 219 entry.value: This property contains an opaque object that represents 220 the whole data, as an array of bytes. 222 The properties SHOULD NOT be modifiable or deletable and if they are, 223 modifying or deleting them MUST NOT modify or delete the equivalent 224 internal values (in other words, the code cannot be used to modify 225 the elements that will be stored). 227 The value returned by the code is evaluated to true or false, 228 according to the ECMAScript rules. If the return value of one of the 229 call to the code is evaluated to false, then the StoreReq fails, the 230 state MUST be rolled back and an Error_Forbidden MUST be returned. 232 4. Security Considerations 234 Because the configuration document containing the ECMAScript code is 235 under the responsability of the same entity that will sign it, using 236 a scripting language does not introduce any additional risk if the 237 RELOAD implementers follow the rules in this document (no side effect 238 when modifying the parameters, only base classes of ECMAScript 239 implemented, etc...). It is even possible to deal with less than 240 perfect implementations as long as they do not accept a configuration 241 file that is not signed correctly. One way for the signer to enforce 242 this would be to deliberately send in a ConfigUpdate an incorrectly 243 signed version of the configuration file and blacklist all the nodes 244 that accepted it in a newly issued configuration file. 246 By permitting multiple overlay implementations to interoperate inside 247 one overlay, RELOAD helps build overlays that are not only resistant 248 to hardware or communication failures, but also to programmer errors. 249 Distributing the access control policy code inside the configuration 250 document reintroduces this single point of failure. To mitigate this 251 problem, new access control policies should be implemented natively 252 as soon as possible, but if all implementations uses the script as a 253 blueprint for the native code, an hidden bug can be duplicated. This 254 is why developers should implement new access control policies from 255 the normative text instead of using the code. That is anyway 256 probably not legal under most copyright laws but to help developers 257 do the right thing the code in the configuration is obfuscated by 258 compressing and encoding it as a base64 character string. 260 5. IANA Considerations 262 If this document is accepted as a standard track document this 263 section will request an URN in the "XML Namespaces" class of the 264 "IETF XML Registry" from IANA. Until this is done, implementions 265 should use the following URN: 267 http://implementers.org/access-control 269 6. Acknowledgements 271 This document was written with the xml2rfc tool described in 272 [RFC2629]. 274 7. References 276 7.1. Normative References 278 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L., and G. 279 Randers-Pehrson, "GZIP file format specification version 280 4.3", RFC 1952, May 1996. 282 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 283 Requirement Levels", BCP 14, RFC 2119, March 1997. 285 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 286 Encodings", RFC 4648, October 2006. 288 [I-D.ietf-p2psip-base] 289 Jennings, C., Lowekamp, B., Rescorla, E., Baset, S., and 290 H. Schulzrinne, "REsource LOcation And Discovery (RELOAD) 291 Base Protocol", draft-ietf-p2psip-base-15 (work in 292 progress), May 2011. 294 [ECMA-262] 295 Ecma, "ECMAScript Language Specification 3rd Edition", 296 December 2009. 298 7.2. Informative References 300 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 301 June 1999. 303 [I-D.ietf-p2psip-service-discovery] 304 Maenpaa, J. and G. Camarillo, "Service Discovery Usage for 305 REsource LOcation And Discovery (RELOAD)", 306 draft-ietf-p2psip-service-discovery-03 (work in progress), 307 July 2011. 309 [I-D.petithuguenin-vipr-reload-usage] 310 Rosenberg, J., Jennings, C., and M. Petit-Huguenin, "A 311 Usage of Resource Location and Discovery (RELOAD) for 312 Public Switched Telephone Network (PSTN) Verification", 313 draft-petithuguenin-vipr-reload-usage-01 (work in 314 progress), June 2011. 316 [I-D.knauf-p2psip-share] 317 Knauf, A., Hege, G., Schmidt, T., and M. Waehlisch, "A 318 Usage for Shared Resources in RELOAD (ShaRe)", 319 draft-knauf-p2psip-share-00 (work in progress), 320 March 2011. 322 Appendix A. Examples 324 A.1. Standard Access Control Policies 326 This section shows the ECMAScript code that could be used to 327 implement the standard Access Control Policies defined in 328 [I-D.ietf-p2psip-base]. 330 A.1.1. USER-MATCH 332 String.prototype['bytes'] = function() { 333 var bytes = []; 334 for (var i = 0; i < this.length; i++) { 335 bytes[i] = this.charCodeAt(i); 336 } 337 return bytes; 338 }; 340 return resource.equalsHash(signer.user_name.bytes()); 342 A.1.2. NODE-MATCH 344 return resource.equalsHash(signer.node_id); 346 A.1.3. USER-NODE-MATCH 347 String.prototype['bytes'] = function() { 348 var bytes = []; 349 for (var i = 0; i < this.length; i++) { 350 bytes[i] = this.charCodeAt(i); 351 } 352 return bytes; 353 }; 355 var equals = function(a, b) { 356 if (a.length !== b.length) return false; 357 for (var i = 0; i < a.length; i++) { 358 if (a[i] !== b[i]) return false; 359 } 360 return true; 361 }; 363 return resource.equalsHash(signer.user_name.bytes()) 364 && equals(entry.key, signer.node_id); 366 A.1.4. NODE-MULTIPLE 368 Number.prototype['width'] = function(w) { 369 var bytes = []; 370 for (var i = 0; i < w; i++) { 371 bytes[i] = (this >>> ((w - i - 1) * 8)) & 255; 372 } 373 return bytes; 374 }; 376 for (var i = 0; i < kind.max_node_multiple; i++) { 377 if (resource.equalsHash(signer.node_id, i.width(4))) { 378 return true; 379 } 380 } 381 return false; 383 [[Note that base-15 still does not state exactly the length of i when 384 concatenated in the hash input]] 386 A.2. Service Discovery Access Control Policy NODE-ID-MATCH 388 [I-D.ietf-p2psip-service-discovery] defines a specific Access Control 389 Policy (NODE-ID-MATCH) that need to access the content of the entry 390 to be written. If implemented as specified by this document, the 391 ECMAScript code would look something like this: 393 /* Insert here the code from 394 http://jsfromhell.com/classes/bignumber 395 */ 397 var toBigNumber = function(node_id) { 398 var bignum = new BigNumber(0); 399 for (var i = 0; i < node_id.length; i++) { 400 bignum = bignum.multiply(256).add(node_id[i]); 401 } 402 return bignum; 403 }; 405 var checkIntervals = function(node_id, level, node, factor) { 406 var size = new BigNumber(2).pow(128); 407 var node = toBigNumber(node_id); 408 for (var f = 0; f < factor; f++) { 409 var temp = size.multiply(new BigNumber(f) 410 .pow(new BigNumber(level).negate())); 411 var min = temp.multiply(node.add(new BigNumber(f) 412 .divide(factor))); 413 var max = temp.multiply(node.add(new BigNumber(f + 1) 414 .divide(factor))); 415 if (node.compare(min) === -1 || node.compare(max) == 1 416 || node.compare(max) == 0) return false; 417 } 418 return true; 419 }; 421 var equals = function(a, b) { 422 if (a.length !== b.length) return false; 423 for (var i = 0; i < a.length; i++) { 424 if (a[i] !== b[i]) return false; 425 } 426 return true; 427 }; 429 var level = function(value) { 430 var length = value[16] * 256 + value[17]; 431 return value[18 + length] * 256 + value[18 + length + 1]; 432 }; 434 var node = function(value) { 435 var length = value[16] * 256 + value[17]; 436 return value[18 + length + 2] * 256 437 + value[18 + length + 3]; 438 }; 440 var namespace = function(value) { 441 var length = value[16] * 256 + value[17]; 442 return String.fromCharCode.apply(null, 443 value.slice(18, length + 18)); 444 }; 446 var branching_factor = 447 kind.evaluate('/branching-factor', 448 'redir', 'urn:ietf:params:xml:ns:p2p:redir'); 449 return equals(entry.key, signer.node_id) 450 && (!entry.exists || checkIntervals(entry.key, 451 level(entry.value), node(entry.value), 452 branching_factor)) 453 && (!entry.exists 454 || resource.equalsHash(namespace(entry.value), 455 level(entry.value), node(entry.value))); 457 Note that the code for the BigNumber object was removed from this 458 example, as the licensing terms are unclear. The code is available 459 at . 461 A.3. VIPR Access Control Policy 463 [I-D.petithuguenin-vipr-reload-usage] defines a specific Access 464 Control Policy. If implemented as specified by this document, the 465 ECMAScript code would look something like this: 467 var equals = function(a, b) { 468 if (a.length !== b.length) return false; 469 for (var i = 0; i < a.length; i++) { 470 if (a[i] !== b[i]) return false; 471 } 472 return true; 473 }; 474 var length = configuration.node_id_length; 475 return equals(entry.key.slice(0, length), 476 entry.value.slice(4, length + 4)) 477 && equals(entry.key.slice(0, length), signer.node_id); 479 Appendix B. Release notes 481 This section must be removed before publication as an RFC. 483 B.1. Modifications between -03 and -02 485 o Moved the access-control-code element fom the kind element to the 486 configuration element so the code can be shared between kinds. A 487 new "name" attribute is used to name the access control policy. 489 o Added configuration object to pass information about the whole 490 overlay. 491 o Added evaluate functions to retrieve extensions parameters. 492 o Renamed the signature attribute to signer. 493 o Filled Security section. 494 o Added temporary namespace to IANA section. 495 o The content of the access-control-code is now UTF-8 encoded, 496 compressed with gzip and converted back to characters with base64. 497 o Fixed the implementation of the service discovery access control 498 policy. 499 o Added code for VIPR policy. 501 B.2. Modifications between -02 and -01 503 o Made clear that an unsigned kind with this extension must be 504 rejected. 505 o Removed the kind.params array, and converted the max-count, max- 506 size and max-node-multiple as Number objects. Fixed the examples. 507 o Removed the parsing of extensions in the kind element. The former 508 system did not work with namespaces or attributes, and the right 509 solution (xpath) is probably too complex. The value of the 510 parameters can still be manually mirrored in the script, so there 511 is perhaps no need for the added complexity. Also fixed the 512 examples. 513 o Reference draft-p2psip-share instance of draft-p2psip-disco. 514 o Added a "Running Code Considerations" section that contain the 515 reference to the reference implementation and script tester. 516 o Nits 518 B.3. Modifications between -01 and -00 520 o Changed reference from JavaScript to ECMAScript. 521 o Changed signature from equals() to equalsHash(). 522 o Fixed the examples following implementation. 523 o Replaced automatic decoding of value by ECMAScript code. 524 o Added the type of each property. 525 o Specified that the code cannot be used to modify the value stored. 527 B.4. Running Code Considerations 529 o Reference Implementation and Access Control Policy script tester 530 (). 531 Marc Petit-Huguenin. Implements version -03. 533 B.5. TODO List 534 o The access control policy in ShaRe [I-D.knauf-p2psip-share] 535 requires an access to the list of all values stored at the same 536 Resource-ID than the value currently verified. A major update of 537 this specification is needed for this, so more time is needed to 538 do it right. 540 Author's Address 542 Marc Petit-Huguenin 543 Stonyfish, Inc. 545 Email: petithug@acm.org