idnits 2.17.1 draft-foudil-securitytxt-02.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. -- 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 27, 2017) is 2311 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 524 == Unused Reference: 'RFC3986' is defined on line 492, but no explicit reference was found in the text == Unused Reference: 'RFC5322' is defined on line 502, 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 (~~), 5 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 4 Intended status: Informational Y. Shafranovich 5 Expires: June 30, 2018 Nightwatch Cybersecurity 6 December 27, 2017 8 A Method for Web Security Policies 9 draft-foudil-securitytxt-02 11 Abstract 13 When security risks in web services are discovered by independent 14 security researchers who understand the severity of the risk, they 15 often lack the channels to properly disclose them. As a result, 16 security issues may be left unreported. security.txt defines a 17 standard to help organizations define the process for security 18 researchers to securely disclose security vulnerabilities. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on June 30, 2018. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. The Specification . . . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Comments . . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.2. Separate Fields . . . . . . . . . . . . . . . . . . . . . 4 60 2.3. Contact: . . . . . . . . . . . . . . . . . . . . . . . . 4 61 2.4. Encryption: . . . . . . . . . . . . . . . . . . . . . . . 4 62 2.5. Signature: . . . . . . . . . . . . . . . . . . . . . . . 5 63 2.6. Policy: . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.7. Acknowledgement: . . . . . . . . . . . . . . . . . . . . 5 65 2.8. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 3. Location of the security.txt file . . . . . . . . . . . . . . 6 67 3.1. Web-based services . . . . . . . . . . . . . . . . . . . 6 68 3.2. File systems . . . . . . . . . . . . . . . . . . . . . . 7 69 3.3. Internal hosts . . . . . . . . . . . . . . . . . . . . . 7 70 3.4. Extensibility . . . . . . . . . . . . . . . . . . . . . . 7 71 4. File Format Description . . . . . . . . . . . . . . . . . . . 7 72 5. Security considerations . . . . . . . . . . . . . . . . . . . 8 73 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 74 6.1. Well-Known URIs registry . . . . . . . . . . . . . . . . 9 75 6.2. Registry for security.txt Header Fields . . . . . . . . . 9 76 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 10 77 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 78 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 79 8.2. Informative References . . . . . . . . . . . . . . . . . 12 80 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 81 Appendix A. Note to Readers . . . . . . . . . . . . . . . . . . 12 82 Appendix B. Document History . . . . . . . . . . . . . . . . . . 12 83 B.1. Since draft-foudil-securitytxt-00 . . . . . . . . . . . . 12 84 B.2. Since draft-foudil-securitytxt-01 . . . . . . . . . . . . 13 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 87 1. Introduction 89 1.1. Motivation 91 Many security researchers encounter situations where they are unable 92 to responsibly disclose security issues to companies because there is 93 no course of action laid out. security.txt is designed to help assist 94 in this process by making it easier for companies to designate the 95 preferred steps for researchers to take when trying to reach out. 97 As per section 4 of [RFC2142], there is an existing convention of 98 using the SECURITY@domain [1] email address for communications 99 regarding security issues. That convention provides only a single, 100 email-based channel of communication for security issues per domain, 101 and does not provide a way for domain owners to publish information 102 about their security disclosure policies. 104 In this document, we propose a richer, machine-parsable and more 105 extensible way for companies to communicate information about their 106 security disclosure policies, which is not limited to email and also 107 allows for additional features such as encryption. 109 1.2. Terminology 111 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 112 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 113 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 115 2. The Specification 117 security.txt is a text file that should be located under the /.well- 118 known/ path ("/.well-known/security.txt") [RFC5785] for web 119 properties. For file systems and version control repositories a 120 .security.txt file should be placed in the root directory. This text 121 file contains 4 directives with different values. The "directive" is 122 the first part of a field all the way up to the colon ("Contact:"). 123 Directives are case-insensitive. The "value" comes after the 124 directive ("https://example.com/security"). A "field" always 125 consists of a directive and a value ("Contact: https://example.com/ 126 security"). A security.txt file can have an unlimited number of 127 fields. It is important to note that you need a separate line for 128 every field. One MUST NOT chain multiple values for a single 129 directive. Everything MUST be in a separate field. 131 A security.txt file only applies to the domain, subdomain, IPv4 or 132 IPv6 address it is located in. 134 # The following only applies to example.com. 135 https://example.com/.well-known/security.txt 137 # This only applies to subdomain.example.com. 138 https://subdomain.example.com/.well-known/security.txt 140 # This security.txt file applies to 192.0.2.0. 141 http://192.0.2.0/.well-known/security.txt 143 2.1. Comments 145 Comments can be added using the # symbol: 147 # This is a comment. 149 You MAY use one or more comments as descriptive text immediately 150 before the field. Parsers can then associate the comments with the 151 respective field. 153 2.2. Separate Fields 155 A separate line is required for every new value and field. You MUST 156 NOT chain everything in to a single field. Every line must end with 157 a line feed character (%x0A). 159 2.3. Contact: 161 Add an address that researchers MAY use for reporting security 162 issues. The value can be an email address, a phone number and/or a 163 contact page with more information. The "Contact:" directive MUST 164 always be present in a security.txt file. URIs SHOULD be loaded over 165 HTTPS. Security email addresses SHOULD use the conventions defined 166 in section 4 of [RFC2142], but there is no requirement for this 167 directive to be an email address. 169 While URIs already include the ability to have both email address and 170 phone numbers via "mailto" and "tel" prefixes, allowing this 171 information to be listed without a prefix is intended for ease of use 172 and readability. 174 The precedence is in listed order. The first field is the preferred 175 method of contact. In the example below, the e-mail address is the 176 preferred method of contact. 178 Contact: security@example.com 179 Contact: +1-201-555-0123 180 Contact: https://example.com/security-contact.html 182 2.4. Encryption: 184 This directive allows you to add your key for encrypted 185 communication. You MUST NOT directly add your key. The value MUST 186 be a link to a page which contains your key. Keys SHOULD be loaded 187 over HTTPS. 189 Encryption: https://example.com/pgp-key.txt 191 2.5. Signature: 193 In order to ensure the authenticty of the security.txt file one 194 SHOULD use the "Signature:" directive, which allows you to link to an 195 external signature. External signature files should be named 196 "security.txt.sig" and also be placed under the /.well-known/ path. 197 External signature files SHOULD be loaded over HTTPS. 199 Here is an example of an external signature file. 201 Signature: https://example.com/.well-known/security.txt.sig 203 2.6. Policy: 205 With the Policy directive you can link to where your security policy 206 and/or disclosure policy is located. This can help security 207 researchers understand what you are looking for and how to report 208 security vulnerabilities. 210 Policy: https://example.com/security-policy.html 212 2.7. Acknowledgement: 214 This directive allows you to link to a page where security 215 researchers are recognized for their reports. The page should list 216 individuals or companies that disclosed security vulnerabilities and 217 worked with you to remediate the issue. 219 Acknowledgement: https://example.com/hall-of-fame.html 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.8. Example 231 # Our security address 232 Contact: security@example.com 234 # Our PGP key 235 Encryption: https://example.com/pgp-key.txt 237 # Our security policy 238 Encryption: https://example.com/security-policy.html 240 # Our security acknowledgements page 241 Acknowledgement: https://example.com/hall-of-fame.html 243 # Verify this security.txt file 244 Signature: https://example.com/.well-known/security.txt.sig 246 3. Location of the security.txt file 248 External 249 +---------------------------------------------------------------+ 250 | Default | 251 | +-----------------------------+ +----------------+ | 252 | | | Redirect | | | 253 | | /.well-known/security.txt <----------+ security.txt | | 254 | | | | | | 255 | +-----------------------------+ +----------------+ | 256 | | 257 +---------------------------------------------------------------+ 259 Internal 260 +------------------------+ 261 | | 262 | +------------------+ | 263 | | | | 264 | | /.security.txt | | 265 | | | | 266 | +------------------+ | 267 | | 268 +------------------------+ 270 3.1. Web-based services 272 Web-based services SHOULD place the security.txt file under the 273 /.well-known/ path; e.g. https://example.com/.well-known/ 274 security.txt. 276 3.2. File systems 278 File systems SHOULD place the security.txt file under the root 279 directory; e.g. /.security.txt, C:.security.txt. 281 user:/$ l 282 .security.txt 283 example-directory-1/ 284 example-directory-2/ 285 example-directory-3/ 286 example-file 288 3.3. Internal hosts 290 A .security.txt file SHOULD be placed in the root directory of an 291 internal host to trigger incident response. 293 3.4. Extensibility 295 Like many other formats and protocols, this format may need to be 296 extended over time to fit the ever-changing landscape of the 297 Internet. Therefore, extensibility is provided via an IANA registry 298 for headers fields as defined in Section 6.2. Any fields registered 299 via that process MUST be considered optional. In order to encourage 300 extensibility and interoperability, implementors MUST ignore any 301 fields they do not explicitly support. 303 4. File Format Description 305 The expected file format of the security.txt file is plain text as 306 defined in section 4.1.3 of [RFC2046] and encoded in UTF-8. 308 The following is an ABNF definition of the security.txt format, using 309 the conventions defined in [RFC5234]. 311 body = *line (contact-field eol) *line 313 line = *1(field / comment) eol 315 eol = *WSP [CR] LF 317 field = contact-field / encryption-field / acknowledgement-field / 318 ext-field 320 fs = ":" 322 comment = "#" *(WSP / VCHAR / %xA0-E007F) 323 contact-field = "Contact" fs SP (email / uri / phone) 325 email = 327 phone = "+" *1(DIGIT / "-" / "(" / ")" / SP) 329 uri = 331 encryption-field = "Encryption" fs SP uri 333 signature-field = "Signature" fs SP uri 335 policy-field = "Policy" fs SP uri 337 acknowledgement-field = "Acknowledgement" fs SP uri 339 ext-field = field-name fs SP unstructured 341 field-name = 343 unstructured = 345 "ext-field" refers to extension fields, which are discussed in 346 Section 3.4 348 5. Security considerations 350 Organizations creating security.txt files will need to take several 351 security-related issues into consideration. These include exposure 352 of sensitive information and attacks where limited access to a server 353 could grant the ability to modify the contents of the security.txt 354 file or affect how it is served. Organizations SHOULD also monitor 355 their security.txt files regularly to detect tampering. 357 To ensure the authenticity of the security.txt file, organizations 358 SHOULD sign the file and include the signature using the "Signature:" 359 directive. 361 As stated in Section 2.4 and Section 2.5, both encryption keys and 362 external signature files SHOULD be loaded over HTTPS. 364 6. IANA Considerations 366 example.com is used in this document following the uses indicated in 367 [RFC2606]. 369 192.0.2.0 is used in this document following the uses indicated in 370 [RFC5735]. 372 6.1. Well-Known URIs registry 374 The "Well-Known URIs" registry should be updated with the following 375 additional values (using the template from [RFC5785]): 377 URI suffix: security.txt URI suffix: security.txt.sig 379 Change controller: IETF 381 Specification document(s): this document 383 6.2. Registry for security.txt Header Fields 385 IANA is requested to create the "security.txt Header Fields" registry 386 in accordance with [RFC8126]. This registry will contain header 387 fields for use in security.txt files, defined by this specification. 389 New registrations or updates MUST be published in accordance with the 390 "Specification Required" guidelines as described in section 4.6 of 391 [RFC8126]. Any new field thus registered is considered optional by 392 this specification unless a new version of this specification is 393 published. 395 New registrations and updates MUST contain the following information: 397 1. Name of the field being registered or updated 399 2. Short description of the field 401 3. Whether the field can appear more than once 403 4. The document in which the specification of the field is published 405 5. New or updated status, which MUST be one of: current: The field 406 is in current use deprecated: The field is in current use but its 407 use is discouraged historic: The field is no longer in current 408 use 410 An update may make a notation on an existing registration indicating 411 that a registered field is historic or deprecated if appropriate. 413 The initial registry contains these values: 415 Field Name: Acknowledgment 416 Description: link to page where security researchers are recognized 417 Multiple Appearances: Yes 418 Published in: this document 419 Status: current 421 Field Name: Contact 422 Description: contact information to use for reporting security issues 423 Multiple Appearances: Yes 424 Published in: this document 425 Status: current 427 Field Name: Encryption 428 Description: link to a key to be used for encrypted communication 429 Multiple Appearances: Yes 430 Published in: this document 431 Status: current 433 Field Name: Signature 434 Description: signature used to verify the authenticity of the file 435 Multiple Appearances: No 436 Published in: this document 437 Status: current 439 Field Name: Policy 440 Description: link to security policy page 441 Multiple Appearances: No 442 Published in: this document 443 Status: current 445 7. Contributors 447 The editor would like to acknowledge the help provided during the 448 development of this document by the following individuals: 450 o Tom Hudson helped writing the "File Format Description" and wrote 451 several security.txt parsers. 453 o Joel Margolis was a big help when it came to wording this document 454 appropriately. 456 o Jobert Abma for raising issues and concerns that might arise when 457 using certain directives. 459 o Gerben Janssen van Doorn for reviewing this document multiple 460 times. 462 o Austin Heap for helping improve the Internet drafts. 464 o Justin Calmus was always there to answer questions related to 465 writing this document. 467 o Casey Ellis had several ideas related to security.txt that helped 468 shape security.txt itself. 470 8. References 472 8.1. Normative References 474 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 475 Extensions (MIME) Part Two: Media Types", RFC 2046, 476 DOI 10.17487/RFC2046, November 1996, . 479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, 481 DOI 10.17487/RFC2119, March 1997, . 484 [RFC2142] Crocker, D., "Mailbox Names for Common Services, Roles and 485 Functions", RFC 2142, DOI 10.17487/RFC2142, May 1997, 486 . 488 [RFC2606] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS 489 Names", BCP 32, RFC 2606, DOI 10.17487/RFC2606, June 1999, 490 . 492 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 493 Resource Identifier (URI): Generic Syntax", STD 66, 494 RFC 3986, DOI 10.17487/RFC3986, January 2005, 495 . 497 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 498 Specifications: ABNF", STD 68, RFC 5234, 499 DOI 10.17487/RFC5234, January 2008, . 502 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 503 DOI 10.17487/RFC5322, October 2008, . 506 [RFC5735] Cotton, M. and L. Vegoda, "Special Use IPv4 Addresses", 507 RFC 5735, DOI 10.17487/RFC5735, January 2010, 508 . 510 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 511 Uniform Resource Identifiers (URIs)", RFC 5785, 512 DOI 10.17487/RFC5785, April 2010, . 515 8.2. Informative References 517 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 518 Writing an IANA Considerations Section in RFCs", BCP 26, 519 RFC 8126, DOI 10.17487/RFC8126, June 2017, 520 . 522 8.3. URIs 524 [1] mailto:SECURITY@domain 526 Appendix A. Note to Readers 528 *Note to the RFC Editor:* Please remove this section prior to 529 publication. 531 Development of this draft takes place on Github at: 532 https://github.com/securitytxt/security-txt 534 Appendix B. Document History 536 *Note to the RFC Editor:* Please remove this section prior to 537 publication. 539 B.1. Since draft-foudil-securitytxt-00 541 o Moved to use IETF's markdown tools for draft updates 543 o Added table of contents and a fuller list of references 545 o Moved file to .well-known URI and added IANA registration (#3) 547 o Added extensibility with an IANA registry for fields (#34) 549 o Added text explaining relationship to RFC 2142 / security@ email 550 address (#25) 552 o Scope expanded to include internal hosts, domains, IP addresses 553 and file systems 555 o Support for digital signatures added (#19) 556 Full list of changes can be viewed via the IETF document tracker: 557 https://tools.ietf.org/html/draft-foudil-securitytxt-01 559 B.2. Since draft-foudil-securitytxt-01 561 o Added appendix with pointer to Github and document history 563 o Added external signature file to the well known URI registry (#59) 565 o Added policy field (#53) 567 o Added diagram explaining the location of the file on public vs. 568 internal systems 570 o Added recommendation that external signature files should use 571 HTTPS (#55) 573 o Added recommendation that organizations should monitor their 574 security.txt files (#14) 576 Full list of changes can be viewed via the IETF document tracker: 577 https://tools.ietf.org/html/draft-foudil-securitytxt-02 579 Authors' Addresses 581 Edwin Foudil 583 Email: contact@edoverflow.com 585 Yakov Shafranovich 586 Nightwatch Cybersecurity 588 Email: yakov+ietf@nightwatchcybersecurity.com