idnits 2.17.1 draft-foudil-securitytxt-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (December 03, 2017) is 2337 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: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 492 == Unused Reference: 'RFC3986' is defined on line 460, but no explicit reference was found in the text == Unused Reference: 'RFC5322' is defined on line 470, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5735 (Obsoleted by RFC 6890) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Foudil 3 Internet-Draft December 03, 2017 4 Intended status: Informational 5 Expires: June 6, 2018 7 A Method for Web Security Policies 8 draft-foudil-securitytxt-01 10 Abstract 12 When security risks in web services are discovered by independent 13 security researchers who understand the severity of the risk, they 14 often lack the channels to properly disclose them. As a result, 15 security issues may be left unreported. security.txt defines a 16 standard to help organizations define the process for security 17 researchers to securely disclose security vulnerabilities. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on June 6, 2018. 36 Copyright Notice 38 Copyright (c) 2017 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. The Specification . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Comments . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2.2. Separate Fields . . . . . . . . . . . . . . . . . . . . . 4 59 2.3. Contact: . . . . . . . . . . . . . . . . . . . . . . . . 4 60 2.4. Encryption: . . . . . . . . . . . . . . . . . . . . . . . 4 61 2.5. Signature: . . . . . . . . . . . . . . . . . . . . . . . 5 62 2.6. Acknowledgement: . . . . . . . . . . . . . . . . . . . . 5 63 2.7. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 3. Location of the security.txt file . . . . . . . . . . . . . . 6 65 3.1. Web-based services . . . . . . . . . . . . . . . . . . . 6 66 3.2. File systems . . . . . . . . . . . . . . . . . . . . . . 6 67 3.3. Internal hosts . . . . . . . . . . . . . . . . . . . . . 6 68 3.4. Extensibility . . . . . . . . . . . . . . . . . . . . . . 6 69 4. File Format Description . . . . . . . . . . . . . . . . . . . 7 70 5. Security considerations . . . . . . . . . . . . . . . . . . . 8 71 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 72 6.1. Well-Known URIs registry . . . . . . . . . . . . . . . . 8 73 6.2. Registry for security.txt Header Fields . . . . . . . . . 8 74 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 9 75 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 77 8.2. Informative References . . . . . . . . . . . . . . . . . 11 78 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 11 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 81 1. Introduction 83 1.1. Motivation 85 Many security researchers encounter situations where they are unable 86 to responsibly disclose security issues to companies because there is 87 no course of action laid out. security.txt is designed to help assist 88 in this process by making it easier for companies to designate the 89 preferred steps for researchers to take when trying to reach out. 91 As per section 4 of [RFC2142], there is an existing convention of 92 using the SECURITY@domain [1] email address for communications 93 regarding security issues. That convention provides only a single, 94 email-based channel of communication for security issues per domain, 95 and does not provide a way for domain owners to publish information 96 about their security disclosure policies. 98 In this document, we propose a richer, machine-parsable and more 99 extensible way for companies to communicate information about their 100 security disclosure policies, which is not limited to email and also 101 allows for additional features such as encryption. 103 1.2. Terminology 105 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 106 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 107 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 109 2. The Specification 111 security.txt is a text file that should be located under the /.well- 112 known/ path ("/.well-known/security.txt") [RFC5785] for web 113 properties. For file systems and version control repositories a 114 .security.txt file should be placed in the root directory. This text 115 file contains 4 directives with different values. The "directive" is 116 the first part of a field all the way up to the colon ("Contact:"). 117 Directives are case-insensitive. The "value" comes after the 118 directive ("https://example.com/security"). A "field" always 119 consists of a directive and a value ("Contact: https://example.com/ 120 security"). A security.txt file can have an unlimited number of 121 fields. It is important to note that you need a separate line for 122 every field. One MUST NOT chain multiple values for a single 123 directive. Everything MUST be in a separate field. 125 A security.txt file only applies to the domain, subdomain, IPv4 or 126 IPv6 address it is located in. 128 # The following only applies to example.com. 129 https://example.com/.well-known/security.txt 131 # This only applies to subdomain.example.com. 132 https://subdomain.example.com/.well-known/security.txt 134 # This security.txt file applies to 192.0.2.0. 135 http://192.0.2.0/.well-known/security.txt 137 2.1. Comments 139 Comments can be added using the # symbol: 141 142 # This is a comment. 143 145 You MAY use one or more comments as descriptive text immediately 146 before the field. Parsers can then associate the comments with the 147 respective field. 149 2.2. Separate Fields 151 A separate line is required for every new value and field. You MUST 152 NOT chain everything in to a single field. Every line must end with 153 a line feed character (%x0A). 155 2.3. Contact: 157 Add an address that researchers MAY use for reporting security 158 issues. The value can be an email address, a phone number and/or a 159 security page with more information. The "Contact:" directive MUST 160 always be present in a security.txt file. URIs SHOULD be loaded over 161 HTTPS. Security email addresses SHOULD use the conventions defined 162 in section 4 of [RFC2142], but there is no requirement for this 163 directive to be an email address. 165 The precedence is in listed order. The first field is the preferred 166 method of contact. In the example below, the e-mail address is the 167 preferred method of contact. 169 170 Contact: security@example.com 171 Contact: +1-201-555-0123 172 Contact: https://example.com/security 173 175 2.4. Encryption: 177 This directive allows you to add your key for encrypted 178 communication. You MUST NOT directly add your key. The value MUST 179 be a link to a page which contains your key. Keys SHOULD be loaded 180 over HTTPS. 182 183 Encryption: https://example.com/pgp-key.txt 184 186 2.5. Signature: 188 In order to ensure the authenticty of the security.txt file one 189 SHOULD use the "Signature:" directive, which allows you to link to an 190 external signature or to directly include the signature in the file. 191 External signature files should be named "security.txt.sig" and also 192 be placed under the /.well-known/ path. 194 Here is an example of an external signature file. 196 197 Signature: https://example.com/.well-known/security.txt.sig 198 200 Here is an example inline signature. 202 203 Signature: 204 -----BEGIN PGP SIGNATURE----- 206 ... 207 -----END PGP SIGNATURE----- 208 210 2.6. Acknowledgement: 212 This directive allows you to link to a page where security 213 researchers are recognized for their reports. The page should list 214 individuals or companies that disclosed security vulnerabilities and 215 worked with you to remediate the issue. 217 218 Acknowledgement: https://example.com/hall-of-fame.html 219 221 Example security acknowledgements page: 223 We would like to thank the following researchers: 225 (2017-04-15) Frank Denis - Reflected cross-site scripting 226 (2017-01-02) Alice Quinn - SQL injection 227 (2016-12-24) John Buchner - Stored cross-site scripting 228 (2016-06-10) Anna Richmond - A server configuration issue 230 2.7. Example 232 233 # Our security address 234 Contact: security@example.com 236 # Our PGP key 237 Encryption: https://example.com/pgp-key.txt 239 # Our security acknowledgements page 240 Acknowledgement: https://example.com/hall-of-fame.html 242 # Verify this security.txt file 243 Signature: https://example.com/.well-known/security.txt.sig 244 246 3. Location of the security.txt file 248 3.1. Web-based services 250 Web-based services SHOULD place the security.txt file under the 251 /.well-known/ path; e.g. https://example.com/.well-known/ 252 security.txt. 254 3.2. File systems 256 File systems SHOULD place the security.txt file under the root 257 directory; e.g. /.security.txt, C:.security.txt. 259 260 . 261 ├── .security.txt 262 ├── example-directory-1 263 ├── example-directory-2 264 ├── example-directory-3 265 └── example-file 266 268 3.3. Internal hosts 270 A .security.txt file SHOULD be placed in the root directory of an 271 internal host to trigger incident response. 273 3.4. Extensibility 275 Like many other formats and protocols, this format may need to be 276 extended over time to fit the ever-changing landscape of the 277 Internet. Therefore, extensibility is provided via an IANA registry 278 for headers fields as defined in Section 6.2. Any fields registered 279 via that process MUST be considered optional. In order to encourage 280 extensibility and interoperability, implementors MUST ignore any 281 fields they do not explicitly support. 283 4. File Format Description 285 The expected file format of the security.txt file is plain text as 286 defined in section 4.1.3 of [RFC2046] and encoded in UTF-8. 288 The following is an ABNF definition of the security.txt format, using 289 the conventions defined in [RFC5234]. 291 body = *line (contact-field eol) *line 293 line = *1(field / comment) eol 295 eol = *WSP [CR] LF 297 field = contact-field / encryption-field / acknowledgement-field / 298 ext-field 300 fs = ":" 302 comment = "#" *(WSP / VCHAR / %xA0-E007F) 304 contact-field = "Contact" fs SP (email / uri / phone) 306 email = 308 phone = "+" *1(DIGIT / "-" / "(" / ")" / SP) 310 uri = 312 encryption-field = "Encryption" fs SP uri 314 acknowledgement-field = "Acknowledgement" fs SP uri 316 ext-field = field-name fs SP unstructured 318 field-name = 320 unstructured = 322 "ext-field" refers to extension fields, which are discussed in 323 Section 3.4 325 5. Security considerations 327 Companies creating security.txt files will need to take several 328 security-related issues into consideration. These include exposure 329 of sensitive information and attacks where limited access to a server 330 could grant the ability to modify the contents of the security.txt 331 file or affect how it is served. 333 As stated in Section 2.4, keys specified using the "Encryption:" 334 directive SHOULD be loaded over HTTPS. 336 To ensure the authenticity of the security.txt file one should sign 337 the file and include the signature using the "Signature:" directive. 339 6. IANA Considerations 341 example.com is used in this document following the uses indicated in 342 [RFC2606]. 344 192.0.2.0 is used in this document following the uses indicated in 345 [RFC5735]. 347 6.1. Well-Known URIs registry 349 The "Well-Known URIs" registry should be updated with the following 350 additional value (using the template from [RFC5785]): 352 URI suffix: security.txt 354 Change controller: IETF 356 Specification document(s): this document 358 6.2. Registry for security.txt Header Fields 360 IANA is requested to create the "security.txt Header Fields" registry 361 in accordance with [RFC8126]. This registry will contain header 362 fields for use in security.txt files, defined by this specification. 364 New registrations or updates MUST be published in accordance with the 365 "Specification Required" guidelines as described in section 4.6 of 366 [RFC8126]. Any new field thus registered is considered optional by 367 this specification unless a new version of this specification is 368 published. 370 New registrations and updates MUST contain the following information: 372 1. Name of the field being registered or updated 373 2. Short description of the field 375 3. Whether the field can appear more than once 377 4. The document in which the specification of the field is published 379 5. New or updated status, which MUST be one of: current: The field 380 is in current use deprecated: The field is in current use but its 381 use is discouraged historic: The field is no longer in current 382 use 384 An update may make a notation on an existing registration indicating 385 that a registered field is historic or deprecated if appropriate. 387 The initial registry contains these values: 389 Field Name: Acknowledgment 390 Description: link to page where security researchers are recognized 391 Multiple Appearances: Yes 392 Published in: this document 393 Status: current 395 Field Name: Contact 396 Description: contact information to use for reporting security issues 397 Multiple Appearances: Yes 398 Published in: this document 399 Status: current 401 Field Name: Encryption 402 Description: link to a key to be used for encrypted communication 403 Multiple Appearances: Yes 404 Published in: this document 405 Status: current 407 Field Name: Signature 408 Description: signature used to verify the authenticity of the file 409 Multiple Appearances: No 410 Published in: this document 411 Status: current 413 7. Contributors 415 The editor would like to acknowledge the help provided during the 416 development of this document by the following individuals: 418 o Tom Hudson helped writing the "File Format Description" and wrote 419 several security.txt parsers. 421 o Joel Margolis was a big help when it came to wording this document 422 appropriately. 424 o Jobert Abma for raising issues and concerns that might arise when 425 using certain directives. 427 o Gerben Janssen van Doorn for reviewing this document multiple 428 times. 430 o Austin Heap for helping improve the Internet drafts. 432 o Justin Calmus was always there to answer questions related to 433 writing this document. 435 o Casey Ellis had several ideas related to security.txt that helped 436 shape security.txt itself. 438 8. References 440 8.1. Normative References 442 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 443 Extensions (MIME) Part Two: Media Types", RFC 2046, 444 DOI 10.17487/RFC2046, November 1996, . 447 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 448 Requirement Levels", BCP 14, RFC 2119, 449 DOI 10.17487/RFC2119, March 1997, . 452 [RFC2142] Crocker, D., "Mailbox Names for Common Services, Roles and 453 Functions", RFC 2142, DOI 10.17487/RFC2142, May 1997, 454 . 456 [RFC2606] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS 457 Names", BCP 32, RFC 2606, DOI 10.17487/RFC2606, June 1999, 458 . 460 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 461 Resource Identifier (URI): Generic Syntax", STD 66, 462 RFC 3986, DOI 10.17487/RFC3986, January 2005, 463 . 465 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 466 Specifications: ABNF", STD 68, RFC 5234, 467 DOI 10.17487/RFC5234, January 2008, . 470 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 471 DOI 10.17487/RFC5322, October 2008, . 474 [RFC5735] Cotton, M. and L. Vegoda, "Special Use IPv4 Addresses", 475 RFC 5735, DOI 10.17487/RFC5735, January 2010, 476 . 478 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 479 Uniform Resource Identifiers (URIs)", RFC 5785, 480 DOI 10.17487/RFC5785, April 2010, . 483 8.2. Informative References 485 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 486 Writing an IANA Considerations Section in RFCs", BCP 26, 487 RFC 8126, DOI 10.17487/RFC8126, June 2017, 488 . 490 8.3. URIs 492 [1] mailto:SECURITY@domain 494 Author's Address 496 Edwin Foudil 498 Email: contact@edoverflow.com