Tools team A. Rousskov Internet-Draft The Measurement Factory Expires: June 22, 2005 December 22, 2004 Requirements for IETF Draft Submission Toolset draft-ietf-tools-draft-submission-07 Status of this Memo This document is an Internet-Draft and is subject to all provisions of section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on June 22, 2005. Copyright Notice Copyright (C) The Internet Society (2004). Abstract This document specifies requirements for an IETF toolset facilitating Internet-Draft submission, validation, and posting. Rousskov Expires June 22, 2005 [Page 1] Internet-Draft Draft Submission Toolset: Requirements December 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. State of this draft . . . . . . . . . . . . . . . . . . . . . 3 3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Notation and Terminology . . . . . . . . . . . . . . . . . . . 4 5. Status quo . . . . . . . . . . . . . . . . . . . . . . . . . . 5 6. Overall Toolset operation . . . . . . . . . . . . . . . . . . 6 7. Upload page . . . . . . . . . . . . . . . . . . . . . . . . . 9 8. Check action . . . . . . . . . . . . . . . . . . . . . . . . . 9 8.1 Preprocessing . . . . . . . . . . . . . . . . . . . . . . 10 8.2 Processing . . . . . . . . . . . . . . . . . . . . . . . . 11 8.3 Storage . . . . . . . . . . . . . . . . . . . . . . . . . 11 8.4 Extraction . . . . . . . . . . . . . . . . . . . . . . . . 11 8.5 Validation . . . . . . . . . . . . . . . . . . . . . . . . 13 8.5.1 Absolute requirements . . . . . . . . . . . . . . . . 14 8.5.2 Desireable features . . . . . . . . . . . . . . . . . 15 8.5.3 DoS thresholds . . . . . . . . . . . . . . . . . . . . 15 8.5.4 WG approval . . . . . . . . . . . . . . . . . . . . . 16 9. Check page . . . . . . . . . . . . . . . . . . . . . . . . . . 17 9.1 External meta-data . . . . . . . . . . . . . . . . . . . . 17 10. Post Now action . . . . . . . . . . . . . . . . . . . . . . 18 10.1 Receipt page . . . . . . . . . . . . . . . . . . . . . . . 19 11. Adjust action . . . . . . . . . . . . . . . . . . . . . . . 20 12. Adjust page . . . . . . . . . . . . . . . . . . . . . . . . 20 13. Post Manually action . . . . . . . . . . . . . . . . . . . . 20 14. Receipt page . . . . . . . . . . . . . . . . . . . . . . . . 20 15. Bypassing the Toolset . . . . . . . . . . . . . . . . . . . 21 16. Email interface . . . . . . . . . . . . . . . . . . . . . . 22 17. Implementation stages . . . . . . . . . . . . . . . . . . . 24 18. Security Considerations . . . . . . . . . . . . . . . . . . 25 19. IANA Considerations . . . . . . . . . . . . . . . . . . . . 25 20. Compliance . . . . . . . . . . . . . . . . . . . . . . . . . 26 A. Comparison with current procedures . . . . . . . . . . . . . . 26 B. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 C. Change log . . . . . . . . . . . . . . . . . . . . . . . . . . 27 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 21.1 Normative References . . . . . . . . . . . . . . . . . . . . 35 21.2 Informative References . . . . . . . . . . . . . . . . . . . 36 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 36 Intellectual Property and Copyright Statements . . . . . . . . 37 Rousskov Expires June 22, 2005 [Page 2] Internet-Draft Draft Submission Toolset: Requirements December 2004 1. Introduction Public Internet-Drafts are primary means of structured communication within IETF. Current Internet-Draft submission and posting mechanisms hinder efficient and timely communication while creating unnecessary load on the IETF Secretariat. The IETF Tools team recommends formalization and automation of the current mechanisms. This document contains specific automation requirements. The IETF Secretariat and many IETF participants have long been proponents of automation. This document attempts to reflect their known needs and wishes, as interpreted by the Tools team. 2. State of this draft This draft version attempts to resolve all known issues. The Tools team may ask IESG to issue a Last Call for it. If you decide to review the draft at this late stage, please limit your comments to critical issues. Please check the Change log in Appendix C before proposing changes as it is possible that your idea has been already discussed. Please post comments on tools-discuss@ietf.org mailing list or email them directly to the author. RFC Editor Note: Please remove this section for the final publication of the document. It has been inspired by draft-rousskov-newtrk-id-state and related NEWTRK WG discussions. 3. Scope The Draft Submission Toolset discussed in this document is about getting a single new version of an Internet-Draft from an IETF participant to the IETF draft repository. A single draft version may include several formats, and dealing with those formats is in scope for the Toolset. Definition and sources of draft meta-information (to be used in Secretariat databases and elsewhere) are in scope. Submitter authentication and submission authorization are in scope. Draft posting may result in various notifications sent to interested parties. While this document recommends a subset of notification targets, details of notifications are out of scope. Creation of new drafts or new draft versions as well as manipulation, visualization, and interaction with the drafts already in the repository are out of scope. Draft expiration and archiving of old draft versions are out of scope. Rousskov Expires June 22, 2005 [Page 3] Internet-Draft Draft Submission Toolset: Requirements December 2004 4. Notation and Terminology The following terms are to be interpreted according to their definitions below. posted draft: A draft accepted into public IETF draft repository and, hence, publicly available on IETF web site. Posting of a draft does not imply any IETF or IESG review and endorsement. draft version: A meant-to-be-public snapshot of an Intenet-Draft with a meant-to-be-unique version number. Also known as "draft revision". draft format: Any draft source or presentation format, including original and preprocessed XML, original or generated plain text as well as PDF, PostScript, and HTML formats. primary draft format: The first available draft format from the following list: plain text, PDF, PostScript, or XML. WG draft: A draft which identifier (a.k.a. filename) is known and starts with "draft-ietf-". individual draft: A draft other than a WG draft. submitter: A human or software agent initiating submission of an Internet-Draft version for validation or posting. In some cases, the Secretariat staff does the actual submission, but always on behalf of a submitter. In some cases (including but not limited to malicious attacks), the submitter is not the draft author. lawful submitter: A submitter that is authorized by IETF rules to post a given draft. This includes a draft author or editor (listed in the draft text), a corresponding WG Chair, or an IESG member. authorized submitter: A lawful submitter authenticated by the Toolset. Authentication is initially limited to verifying submitter access to submitter's email address. immediately: Without human interaction or artificial software delays and within a few seconds. The Toolset is specified using a set of normative requirements. These requirements are English phrases ending with an "(Rnnn/s)" mark, where "nnn" is a unique requirement number, and "s" is a single letter code ("a", "b", or "c") specifying the implementation stage for the requirement. Implementation stages are documented in Section Rousskov Expires June 22, 2005 [Page 4] Internet-Draft Draft Submission Toolset: Requirements December 2004 17. This document specifies interface and functionality of the Toolset, not details of a Toolset implementation. However, implementation hints or examples are often useful. To avoid mixup with Toolset requirements, such hints and examples are often marked with a "Hint:" prefix. Implementation hints do not carry any normative force, and a different implementation may be the best choice. 5. Status quo This section summarizes the process for draft submission and posting as it exists at the time of writing. To get an Internet-Draft posted on the IETF web site, an IETF participant emails draft text to the IETF Secretariat, along with an informal note asking to post the draft. Secretariat staff reads the note, reviews the draft according to a checklist, and then approves or rejects the submission. Draft approval triggers the corresponding announcement to be sent to appropriate IETF mailing lists. Every 4 hours, approved drafts are automatically copied to the IETF drafts repository and become available on IETF web site. Collectively, IETF participants submit thousands of Internet-Drafts per year (in the year 2000, about three thousand drafts were submitted; 2002: 5k; 2004: 7k [secretariat]). About 30-50% of posted drafts are Working Group drafts (among some 2,100 drafts, there were about 380 new and 290 updated WG drafts posted in 2003). While no rejection statistics is available, the vast majority of submitted drafts are approved by Secretariat for posting. It usually takes the Secretariat a few minutes to review a given draft. However, since the Secretariat staff does not work 24/7, does not work in all time zones, has other responsibilities, and since approved drafts are posted in batches every 4 hours, it may take from several hours to several days to get a draft posted. Due to much higher demand and fixed processing capacity, postings during the last weeks before IETF face-to-face meetings take much longer, creating a long queue of unprocessed drafts that are then announced nearly simultaneously. To give IETF face-to-face meeting participants time to review relevant documents, Secretariat does not accept Internet-Draft submissions close to IETF meetings (regardless of whether a draft is relevant to the upcoming meeting). Many Working Groups have come up with ad hoc solutions to cope with posting delays. For example, many draft snapshots are "temporarily" Rousskov Expires June 22, 2005 [Page 5] Internet-Draft Draft Submission Toolset: Requirements December 2004 published on personal web sites or sent (completely or in part) to the group list. Alternative means of publication may effectively replace official IETF interfaces, with only a few major draft revisions ending up posted on IETF web site. Informal interfaces for submitting and posting drafts discourage automation. Lack of submission automation increases Secretariat load, complicates automated indexing and cross-referencing of the drafts, and, for some authors, leads to stale drafts not being updated often enough. Beyond a short Secretariat checklist, submitted drafts are not checked for compliance with IETF requirements for archival documents, and submitters are not notified of any violations. As a result, IESG and RFC Editor may have to spend resources (and delay approval) resolving violations with draft authors. Often, these violations can be detected automatically and would have been fixed by draft authors if the authors knew about them before requesting to publish the draft. Technically, anybody and anything can submit a draft to the Secretariat. There is no reliable authentication mechanism in place. Initial submissions of WG drafts require WG Chair approval, which can be faked just like the submission request itself. No malicious impersonations or fake approvals have been reported to date however. Lack of authentication is not perceived as a serious problem, possibly because serious falsification are likely to be noticed before serious damage can be done. Due to the informal and manual nature of the submission mechanism, its massive automated abuse is unlikely to cause anything but a short denial of draft posting service and, hence, is probably not worth defending against. However, future automation may result in a different trade-off. 6. Overall Toolset operation This section provides a high-level description for the proposed Toolset. The description is meant to show overall operation and order; please refer to other sections for details specific to each step. A typical submitter goes through a sequence of 2-4 web pages and associated actions. The number of pages depends on the draft validation and meta-data extraction results. For example, validating the draft without posting it requires interacting with two web pages: Upload and Check. The common case of posting a valid draft without manual meta-data adjustments takes three web pages (Upload, Check, Receipt). Rousskov Expires June 22, 2005 [Page 6] Internet-Draft Draft Submission Toolset: Requirements December 2004 Here is a brief overview of pages and actions: Upload page: Interface to copy draft from submitter's computer into the Toolset staging area (Section 7). Multiple formats are accepted. The draft is sent to the Check action. Check action: Stores the draft in the Toolset staging area, extracts draft meta-data, validates the submission (Section 8). Produces the Check page. Check page: Displays draft interpretation and validation results (Section 9). Draft preview may also be given on this page. After reviewing draft interpretation and validation results, the submitter has four basic choices (a) auto-post draft "as is" now; (b) make manual corrections and submit the draft to Secretariat for manual posting later; (c) cancel submission; or (d) do nothing. The automated posting option may not be available for drafts with validation errors. Automated posting: If the submitter decides to proceed with automated posting from the Check page, the system authenticates the submitter and checks whether the submitter is allowed to post the draft. If the submitter is authorized, the draft is immediately posted, deleted from the staging area, and the submitter is notified of the result via email and Receipt page (Section 10). Manual adjustment and posting: If the submitter decides to adjust meta-data, the draft remains in the Toolset staging area, and the Adjust action (Section 11) presents the submitter with an Adjust page (Section 12). When submitter makes the adjustments and proceeds with manual posting, a pointer to the stored draft and its adjusted meta-data is sent to the secretariat for manual processing (Section 13). The submitter is notified of the pending Secretariat request via email and Receipt page. Cancellation: If the submitter decides to explicitly cancel the submission, the submission state (including the draft) is immediately deleted from the Toolset staging area and an appropriate Receipt page is generated without further actions (R123/a). Cancellation of posted drafts is out of this document scope. Receipt page: Contains details of a successful or failed draft submission and informs the submitter of the next appropriate step(s) related to submission result. The following informal diagram illustrates the basic submission logic: Rousskov Expires June 22, 2005 [Page 7] Internet-Draft Draft Submission Toolset: Requirements December 2004 /---> Post Now / Upload --> Check -+-----> Adjust ---> Send to Secretariat \ \---> Cancel If the submitter does nothing while the Toolset is expecting some response, the abandoned submission times out (R124/a). The timeout value depends on the submission state. Hint: A timeout value of one hour is probably large enough unless the Toolset is waiting for some kind of a 3rd party confirmation (e.g., WG chair approval). Doing nothing is functionally equivalent to explicitly canceling the submission, except that explicit cancellation requires immediate removal of submission state while the state of submissions marked as abandoned is garbage-collected. The staging area maintenance algorithms must keep the area in a consistent, correct state in the presence of DoS attacks attempting to overwhelm the area with fake submissions in various stages (R67/ a). Hint: denial of service to legitimate users is acceptable under DoS attack conditions, but corruption of storage area is not. The "web pages" this text is referring to are distinct dialogs, that may be visible to the submitter under the same or different URL, and supported by a single or several server-side programs. The Toolset must handle multiple submitters simultaneously submitting the same draft (R72/a) and a single submitter simultaneously submitting two drafts (R73/a). The latter might happen, for example, when the submitter is using several browser windows to submit several drafts or is submitting drafts via email interface. The term "simultaneously" means that submission processing times overlap. Hint: Except for the Upload page, pages contain a submission session identifier to provide actions with access to stored information. The identifier is specific to the submission rather than the draft version or the submitter. While the nature of the web interface allows the session identifier to be invisible to the submitter, email communication would need to identify the session so that the recipient (and Toolset) know the context. Hint: A single action may correspond to multiple server-side programs and, vice versa, a single program may implement several actions. This document does not mandate any specific technology (e.g., CGI, PHP, and/or Java servlets) to implement server-side support. The implementor experience, code reuse across web and email interfaces, and other factors will determine the right technology choice. Rousskov Expires June 22, 2005 [Page 8] Internet-Draft Draft Submission Toolset: Requirements December 2004 Hint: Actions preserve and exchange state by storing it along with draft. Grouping all submission-specific information in one subdirectory named using the session identifier may increase robustness and simplify debugging. Session creation and destruction can then be logged in a global index. Ways to partially or completely bypass the Toolset are documented in Section 15 The Toolset implementation should be available under an open-source license approved by Open Source Initiative [OSI] (R144/a), with an interface to report bugs and request feature enhancements (R145/b). Hint: Hosting the Toolset at an open-source-friendly project management site like SourceForge.net would provide the IETF community with decent, ready-to-use interface to access to code, bug reports, and discussion forums. 7. Upload page To upload the draft, the submitter goes to a well-known page on the IETF web site (R1/b). There, the draft text can be uploaded using an HTML file upload form. This form provides fields to upload plain text format of the draft (R2/a) and all other formats allowed by IETF draft publication rules (R3/b). At the time of writing, these formats are: XML ([RFC2629] and [I-D.mrose-writing-rfcs]), PDF, and PostScript. Submitted forms are handled by the Check action documented in Section 8. The Upload page also has a validate-only flag, indicating that uploaded draft must not be posted and may be deleted immediately after the validation (R74/b). Regardless of the validation results, the stored draft meta-data is marked so that validation-only drafts can be identified and deleted first by garbage collector for the Toolset staging area (R75/b). Drafts uploaded in a validate-only mode cannot be posted (R76/b); they would need to be uploaded again, without the validate-only flag, and the validation results page should explain that (R77/b). This flag is useful for tools using online validation, especially for bulk draft processing. Hint: it may be better to implement this flag as a hidden HTML input field to simplify the interface for human submitters. 8. Check action The Check action preprocesses submission, generates plain text format (if needed, see R70), stores submitted draft (all formats) in the staging area, and then extracts meta-data and validates each format Rousskov Expires June 22, 2005 [Page 9] Internet-Draft Draft Submission Toolset: Requirements December 2004 (R6/a). Errors and warnings are indicated to the submitter in the response via computer-friendly tag(s) and human-friendly text (R7/a). If any error is found, automated posting becomes impossible (R113/a). This rule applies to all errors, even those that do not refer to R113 and do not explicitly prohibit automated posting. If automated posting is not possible, the Toolset still gives the submitter an option of sending the draft for manual validation and posting (R114/ a). Since each submission is treated in isolation, the submitter also has an option of correcting the problem and resubmitting for automated posting. It is an error to submit a draft which has neither plain text nor XML sources format (R68/a). XML source is acceptable without accompanying plain text only if the Toolset successfully generates a draft in plain text format from the XML source, as a part of the processing step documented below (R69/b). These rules imply that PDF- or PostScript-only drafts cannot be posted without Secretariat involvement. Furthermore, drafts containing PDF or Postscript format must not be auto-posted until the Toolset can validate that their content matches plain text format (R143/a). Draft format acceptance rules above are meant to decrease chances that multiple posted draft formats for a single draft contain substantially different documents. With experience, the rules may be simplified so that, for example, only submissions containing nothing but XML or plain text sources can be posted without Secretariat involvement and all other submissions require manual actions to match formats or extract meta-data. 8.1 Preprocessing Submitting compressed drafts is a desirable feature, especially for submitters behind slow or content-altering links. Compressed draft formats may be accepted (R150/c). Compressed formats, if any, must be decompressed during the preprocessing step (R151/c) so that other processors do not have to deal with compressed formats. Hint: While this specification does not document a list of supported compression standards, it is expected that such popular methods as "zip" and "gzip" should be accepted if compression is supported. Accepting a collection of draft formats within a single compressed archive may also be desirable. XML source containing XML processor instructions (PIs) is preprocessed to include references (R8/b). This step is needed to remove external dependencies from XML sources and to simplify tools processing posted XML. Rousskov Expires June 22, 2005 [Page 10] Internet-Draft Draft Submission Toolset: Requirements December 2004 The XML preprocessor uses public database(s) to resolve PI references (R85/b). The Toolset documentation specifies what databases are used and how PIs are mapped to database entries (R86/b). The Toolset must not rely on PIs existence (R87/b) because some XML sources will be preprocessed before the submission or will be written without PIs. Hint: Local up-to-date copies of Marshall Rose's reference databases at xml.resource.org can be used. Both original and preprocessed XML sources may be posted later. The original source with include PIs may be useful to the RFC Editor and generation of diffs (against future or past original sources). The preprocessed source without PIs becomes the default public XML source of the posted draft (R10/b). If any of the include PIs known to the Toolset cannot be handled, an error is recorded (R11/b), and the submitter is encouraged to do the preprocessing locally, before submitting the draft (R111/b). Uncompressed draft formats other than XML are not preprocessed. 8.2 Processing When no plain text format of the draft is submitted, but XML sources are available, the Toolset attempts to generate plain text format from submitted XML sources (R70/b). If XML sources are available, the Toolset generates HTML draft format (R112/c). HTML generation failures should result in warnings, not errors (R115/c). HTML generation is not meant to be implemented until the Enhancement stage is reached (R130/a). In general, HTML generation is desirable because HTML drafts are usually easier to navigate than plain text drafts due to improved overall readability and links. As any Enhancement Stage feature, HTML generation may be dropped or drastically changed to reflect then-current IETF consensus and the experience of the first two implementation stages. 8.3 Storage The Check action needs to store all draft formats so that successfully validated drafts can later be auto-posted at submitter request. The action stores all submitted formats of the draft in a staging area dedicated to the Toolset (R12/a). If, after garbage collection, the staging area is full (i.e., the total used size reached configured maximum capacity), the submitter and the Secretariat are notified of a fatal error (R13/a). 8.4 Extraction The Toolset extracts meta-data from the following stored draft Rousskov Expires June 22, 2005 [Page 11] Internet-Draft Draft Submission Toolset: Requirements December 2004 formats: plain text (R131/a), XML (R132/b), and other (R133/c). If a meta-data extraction fails, the Toolset records an error (R15/a). Meta-data extraction is necessary to validate and post the draft. Section 17 documents a non-obvious implementation schedule related to the above two requirements. When only partial support for format interpretation is available, only interpreted formats are subject to extraction and validation requirements. In other words, if the Toolset does not yet support interpretation of a given format, then the corresponding information is stored and made available "as is", regardless of the actual content. The draft interpreter extracts the following meta-data from each draft format (R16/a). identifier: Also known as draft "filename". For example, draft-ietf-tools-draft-submission-13. version: A non-negative integer number representing draft version number (also known as draft revision number). For example, the number seven in draft-ietf-tools-draft-submission-07. name: Common part of all draft identifiers for all versions of the same draft. In other words, a draft identifier without the version component. For example, draft-ietf-tools-draft-submission in draft-ietf-tools-draft-submission-07. WG ID: Working Group identifier. WG ID value is empty for individual drafts not meant to be work items of a known WG and for non-IETF drafts. For example, "tools" in "draft-ietf-tools-draft-submission-07" and "opes" in "draft-rousskov-opes-ocp-00" are both WG IDs. Extraction of WG ID from a given individual draft identifier is an Enhancement Stage feature; the process is imprecise and requires checking with a list of known IETF working groups, teams, and similar structures. WG flag: True for WG drafts and false for all other drafts. For example, "true" for "draft-ietf-tools-draft-submission-13". title: A human-friendly draft title. For example, the title of this draft is "Requirements for IETF Draft Submission Toolset" authors: A list of all draft authors. For each author, their name and email address are extracted. abstract: Draft abstract text. Rousskov Expires June 22, 2005 [Page 12] Internet-Draft Draft Submission Toolset: Requirements December 2004 creation date: Draft version creation date. expiration date: Draft version expiration date. size: The number of pages and octets in primary format of the draft. The definition of a page depends on the format and may be imprecise or arbitrary for some formats. Failure to extract any field results in error (R95/a). The Toolset requires author email addresses because they are essential for notifying co-authors that their draft has been posted. If there are no such notifications, a submitter adding a co-author to the draft without co-author consent may not be caught for a while. Such "surprise" co-authorships has happened in the past and can be quite annoying. However, since the Toolset does not solicit co-authors consent to post a valid draft (and such solicitation would not go beyond email control verification anyway), it is not possible to stop a malicious submitter from adding co-authors without their knowledge. Like other meta-data items above, draft creation and expiration dates are extracted from the draft; their values do not depend on the actual submission time (i.e., the time the Check action starts). However, the validation procedure may declare some dates invalid after comparing them with the submission time. 8.5 Validation Drafts need to be validated to catch broken submissions. Validation also helps educate or warn authors of problems that may become show-stoppers when the draft is sent for IETF Last Call and IESG review. IETF standards have to follow a set of syntax and semantics requirements (see ID-NITS document at . Most of those requirements are not enforced for Internet-Drafts. However, following them may improve draft quality, reduce IESG load, and increase the chances of the draft being approved as an RFC. When validating a given draft, it is important to distinguish between absolute requirements and desirable draft properties. Both categories are checked for, but violations have different effects depending on the category. The two categories are detailed in the following subsections. When a valid draft is being posted and submitter authorization or co-author notification is performed, validation results should be included in the email (R81/b) so that the submitter can see meta-data Rousskov Expires June 22, 2005 [Page 13] Internet-Draft Draft Submission Toolset: Requirements December 2004 extraction and validation warnings. Note that these results cannot include errors since only valid drafts can be posted. 8.5.1 Absolute requirements Violating any of these requirements would prevent a draft to be automatically posted (R17/a). The offending draft would have to be fixed or submitted for manual posting, with an explanation why the absolute requirements need to be violated (or why Validator mis-detected violations). These explanations may speed up Secretariat posting decision and may help Secretariat to improve Toolset implementation. 1. All available meta-data entries must match across all submitted draft formats (R18/a). For example, if the interpreter managed to extract draft title from plain text and PDF format, both titles must match. This requirement prevents accidental submission of mismatching formats. 2. Version 00 of a Working Group draft has a corresponding Working Group approval (R20/a). This approval can be relayed before or after the first draft submission, by a Chair or Secretary of the WG. See Section 8.5.4 for related requirements. 3. Draft ID must be correct (R22/a), including the draft version number value. Draft version numbers must start with zero and increase by one with every new version. To satisfy this requirement, the Toolset would have to consult the repository of already posted drafts, including expired ones. 4. An IETF IPR Statement and other boilerplate required for drafts according to [RFC3667] and [RFC3668] (or successors) must appear in the draft text (R23/a). 5. The creation of the draft version could have happened 48 hours or less before submission time. Hint: Implementors should be careful to handle creation dates that appear to be in the past or in the future, due to possible time zone differences. Making the most forgiving/permissive assumption about the time zone should suffice. 6. The draft version expiration date obeys IETF draft expiration rules. 7. No IETF submission blackout period applies. Hint: IETF blackouts must be enforced based on submission time, not possible draft creation time. Rousskov Expires June 22, 2005 [Page 14] Internet-Draft Draft Submission Toolset: Requirements December 2004 8. Posting this draft must not result in any Denial of Service (DoS) attack threshold to be crossed (R97/a). Specific thresholds are documented in Section 8.5.3. 8.5.2 Desireable features Violating any of the following requirements does not prevent the submitter from auto-posting the draft (R24/a). 1. All automatically testable nits in ID-NITS document at (R116/b). The Toolset should use external tools to check these rather than embed nits checking code (R117/a). Hint: Henrik Levkowetz' idnits tool can be used (http://ietf.levkowetz.com/tools/idnits/) and other tools can be written or adopted. 2. New draft versions are expected (R21/b). For example, version 00 of an individual draft is always expected, while posting a new version of a draft already under IESG review should generate a warning. 3. If both XML and plain text formats are submitted, the submitted plain text matches what can be generated based on submitted XML (R146/b). 4. Previous version, if any, was posted at least 24 hours ago (R96/ b). This warning may prevent some human errors, especially when multiple authors may post the same draft. When comparing generated and submitted plain text formats to satisfy R146, a standard word-based diff is sufficient short-term (R147/b). However, a custom fuzzy matching function can be developed (R148/c) to minimize false warnings due to, for example, draft text formatting differences. When differences are detected, a complete diff may be provided on a separate page (R149/c), in addition to the warning. Hint: When comparing generated and submitted plain text formats, the Toolset may try several recent xml2rfc versions for plain text generation, to eliminate warnings due to differences among xml2rfc versions. 8.5.3 DoS thresholds The following table documents DoS attack thresholds for various draft categories. Daily limits correspond to all drafts (and all draft formats) within the category. Other thresholds may be introduced and these initial thresholds may be adjusted as necessary. The Rousskov Expires June 22, 2005 [Page 15] Internet-Draft Draft Submission Toolset: Requirements December 2004 thresholds are likely to become more smart/dynamic with experience. DoS attack thresholds +----------------------------------------+--------------+-----------+ | category | versions/day | MB/day | +----------------------------------------+--------------+-----------+ | drafts with the same draft name | 3 | 5 | | drafts with the same submitter | 5 | 10 | | WG drafts with the same WG ID | 10 | 15 | | all drafts | 300 | 150 | +----------------------------------------+--------------+-----------+ The thresholds are meant to limit destructive effects of DoS attacks (e.g., full disks cause other tasks to fail), allow for capacity planning (e.g., how much storage space the Toolset needs), and limit annoying side-effects of "too many" drafts being posted (e.g., when a person receives posting notifications about a given draft or a given working group). The Toolset should warn the Secretariat if total submissions are approaching any threshold (R134/b). Hint: Bandwidth available for submissions may need to be throttled (on a network subnet basis?) to make reaching the daily size quota (with malicious intent) difficult. 8.5.4 WG approval For version 00 of a WG draft, the Toolset checks for an existing WG approval (R125/a). If (a) no approval exists, and (b) the Toolset does not support the "waiting for WG approval" feature, the toolset records an error (R135/a). If (a) no approval exists, (b) the Toolset supports the "waiting for WG approval" feature, and (c) the draft cannot be posted even if WG approval is received, then the Toolset records a warning that a WG approval would be required once all errors preventing draft from posting are fixed (R137/b). If (a) no approval exists, (b) the Toolset supports the "waiting for WG approval" feature, and (c) the draft can be posted if WG approval is received, then the Toolset explains the situation to the submitter and asks whether the submitter will solicit an explicit approval from the WG (R126/b). If the submitter decides to go ahead with solicitation, the Toolset puts the submission into a "waiting for WG approval" state until the approval is available (R127/b). Otherwise, the Toolset records a "no WG approval is expected" error (R138/b). Details of the approval recording and access interfaces as well as the mechanism to resume the submission upon approval are out of this Rousskov Expires June 22, 2005 [Page 16] Internet-Draft Draft Submission Toolset: Requirements December 2004 document scope. 9. Check page The Check page, created by the Check action displays extracted draft meta-data and validation results (R25/a). The purpose of the page is to allow the submitter to verify whether the stored draft and automatically extracted meta-data match submitter's intent and to be informed of validation problems. Meta-data items specified in Section 8.4 that failed validation checks must be marked specially (rather than silently omitted or ignored) (R26/b). Hint: rendering those items in red, with links to corresponding validation errors or warnings, may force authors to pay attention. Validation messages include both errors and warnings. Each validation message refers to normative document(s) containing corresponding validation rules (R27/b). The Check page allows the submitter to enter external meta-data (Section 9.1) (R28/a). If validation was successful, an "automatically post the draft now" button is provided (R29/a). Regardless of validation results, "adjust and post manually" and "cancel" buttons are provided (R30/a). The Check page provides a preview of the draft plain text format (R31/a), with a link to see how the entire draft (with all its formats) would look like if posted (R82/b). Hint: the Check page preview should be sufficiently long to let authors detect obvious draft mismatch or misinterpretation errors but short enough to avoid dominating the page. Displaying the first line of the draft through the last line of the abstract may be sufficient. For draft updates, the Check page reports the time and the submitter of the last update (R83/b). This information is especially useful when multiple authors are working on the same draft. The page also provides a link to generate a diff against the last posted version (R84/c). 9.1 External meta-data The Check page solicits the following meta-data from the submitter. This information must be supplied by submitter because it cannot be extracted from the draft: Submitter email address (R32/a). When submitter is not a lawful submitter (see Section 4), automated posting is not possible and Rousskov Expires June 22, 2005 [Page 17] Internet-Draft Draft Submission Toolset: Requirements December 2004 the draft has to go through the Secretariat (R98). Hint: A set of checkboxes next to extracted author names along with a "none of the above" checkbox with an input field would suffice. List of drafts obsoleted by this draft (R33/c). This is useful to make obsoleted drafts invisible. This document does not specify any actions necessary to make an existing draft obsolete because existing draft manipulation is out of scope, and because security concerns and other complications of such actions would be better addressed by a separate specification. Primary email address for discussion of this draft (R71/b). Hint: The Toolset can suggest WG mailing list address for WG drafts, [submitting] author address for individual drafts, or even the first email address in draft text. Offering a few likely addresses instead of relying exclusively on user input would also reduce the number of typos. Except for the submitter email address, external meta-data is optional (R109/a). If a given submitter email address belongs to a lawful submitter (i.e., belongs to one of the lawful categories below), the Toolset performs submitter authentication during a Post Now action (R19/a). Otherwise, an error is reported (R118/a). The following possible lawful submitters are identified by the Toolset, without any Secretariat intervention: For version 00 of a draft, any submitter (R119/a). For version N+1 of a draft, an author of version N of the same draft (R120/a). This requirement only needs to be satisfied for drafts for which Nth version was posted using the Toolset; other drafts may not have meta-information required to reliably get a list of authors. For a WG draft, a Chair of the corresponding WG (R121/b). For any draft, an IESG member (R122/c). 10. Post Now action The Post Now action checks that the draft has been successfully validated (R34/a), validates external meta-data (including submitter email address) (R35/a), and posts the draft (R36/a). Submitter is notified of the action progress and the final result (R37/a). Rousskov Expires June 22, 2005 [Page 18] Internet-Draft Draft Submission Toolset: Requirements December 2004 External meta-data contains submitter email address. As a part of the validation procedure, the Post Now action authorizes the submitter. The initial action implementation checks that the submitter has access to email sent to that address (R38/a). Eventually, the Toolset should accept client certificates signed by IETF, PGP-signed email, and/or other forms of client-side authentication to eliminate the weak and annoying email access check (R110/c). If submitter authentication fails, the submission eventually and silently times out (R39/a). The Toolset provides both web (R99/a) and email (R139/b) interfaces for confirming email access. Hint: To check submitter's access to email, the tool can email a hard-to-guess cookie or token to the submitter's address. To continue with the submission, the submitter is requested to paste the cookie at the specified URL, go to the token-holding URL, or respond to the email. Immediately after sending an email to the submitter, the The Post Now action generates an intermediate Receipt page that explains Toolset expectations and provides the submitter with the submission ID (R100/ a). That number allows the Secretariat to troubleshoot stuck submissions (R101/a) and can also be used for checking submission status without Secretariat involvement (R140/b). Immediately after posting the draft, the Toolset notifies all authors (with known email addresses) of the posting (R102/a). Notification email contains information available on the "successful posting" Receipt page described below (R103/a). If draft posting is successful, the submission state is marked as available for deletion (R105/a) so that the garbage collection routine eventually deletes it. 10.1 Receipt page A successful Post Now action reports at least the following information on the final Receipt page (R104/a): o draft ID and a link to the draft status page; o draft title, authors, and abstract; o submission ID o a link to the draft submission status page (when status queries are supported, see R140). o submitter name and email address. Rousskov Expires June 22, 2005 [Page 19] Internet-Draft Draft Submission Toolset: Requirements December 2004 The primary purpose of the Receipt page is to inform all draft authors that [supposedly] their draft has been posted. The secondary purpose is to let authors create a permanent record of the event and troubleshoot postings. The same information should be sent to other parties interested in the draft (e.g., WG mailing list), but 3rd party notification specifics are out of this draft scope. 11. Adjust action The Adjust action generates the Adjust page (R40/a), populating it with available extracted meta-data and external meta-data as well as validation results and preview. Some information may be missing, depending on draft interpretation and preview generation success. 12. Adjust page The Adjust page includes the same information as the Check page, but allows the submitter to adjust all extracted draft meta-data (and, naturally, external meta-data) at will (R41/a). Such adjustment is necessary when automated extraction failed to extract [correct] information. To avoid mismatch between draft and its meta-data, adjusted drafts cannot be automatically posted and require manual validation by Secretariat (R42/a). Secretariat staff can post drafts with adjusted meta-data as described in Section 15. The Adjust page allows the submitter to enter an informal comment explaining why adjustments are necessary and automated posting mode cannot be used (R48/a). The "post manually" and "cancel" buttons are provided (R43/a). The former is backed by the "Post Manually" action (Section 13). 13. Post Manually action The Post Manually action sends adjusted meta-data and draft pointer to the Secretariat for manual validation and posting (R44/a). A receipt page is generated, instructing the submitter to wait (R45/a). Secretariat will notify the submitter once the draft is posted or rejected. This notification is sent by the Toolset if the Secretariat is using the Toolset to post the draft (R46/a). 14. Receipt page The Receipt page is generated by various actions to inform the submitter of current submission status and further actions. The contents of the page is likely to be highly dependent on the action and state for which receipt is being generated. This section documents general requirements applicable to all actions and states. Rousskov Expires June 22, 2005 [Page 20] Internet-Draft Draft Submission Toolset: Requirements December 2004 The Receipt page should give the submitter a URI or another identifier that can be used by Secretariat for manual troubleshooting of the submission (R63/a). The identifier should be perpetual (R64/ a) even though the associated details are likely to be eventually lost (e.g., draft submission data and logs are deleted from the staging area as a part of the garbage collection routine). Hint: Tools should distinguish old identifiers from invalid ones; when a given identifier is referring to deleted data, the tools accepting the identifier should inform their users that identified submission information has expired. The Receipt page should give the submitter a Secretariat point-of-contact to report submission problems (R65/a). 15. Bypassing the Toolset A buggy Toolset implementation or unusual circumstances may force a submitter to submit a draft to Secretariat for manual processing. This can be done by choosing the "manual posting" route supported by the Toolset (R47/a) or, as a last resort, by emailing the draft directly to Secretariat. In either case, an informal "cover letter" has to accompany the draft. The letter should explain why the automated interface cannot be used. When processing manual submissions, the Secretariat may be able to use the Toolset. A Manual Check page similar to the default Check page provides authenticated Secretariat staff with editable meta-data fields and a "force posting" action (R50/b). The forced posting action accepts meta-data fields "as is", does not verify submitter access to email or WG draft authorization, and posts the draft as if no validation errors were found (R51/b). The Manual Check page should still contain all the errors and warnings identical to those seen by ordinary submitters (R106/b) so that the Secretariat knows what the Toolset is unhappy about (if anything). Using manual processing may result in significant posting delays. Generated submission receipts or notifications ought to give the submitter an expected processing time estimate (R53/a). The intent of this mode is to provide a way for submitters to bypass bugs or limitations of the automated mechanisms in order to post an "unusual" draft or to post a draft under "unusual" circumstances. One example would be a draft that does not contain standard IETF boilerplate but has a special IESG permission to post the draft with the experimental boilerplate. Another example is a draft that fails automated validation tests due to a validator bug. The bypass mode is also likely to be used (effectively) by the Rousskov Expires June 22, 2005 [Page 21] Internet-Draft Draft Submission Toolset: Requirements December 2004 majority of submitters during the Trial stage of the Toolset implementation, when few submitters know about (or are allowed to use) the Toolset. 16. Email interface The Toolset should have email interface for automated posting of valid drafts (R55/b). While virtually every documented Toolset functionality can, technically, be implemented behind an email interface, features other than posting of valid drafts are believed to be prohibitively awkward to implement or use via email. The email interface accepts a draft as a set of email part(s) (one per draft format) (R56/b). For example, plain text format can be submitted in the "body" of the email message while XML source format can be optionally sent as an "attachment" of the same email message. Each part can either contain the actual format data (R141/b) or a single URL pointing to it (R142/c). In the latter case, the Toolset has to fetch the format data. Details of URL-fetching option are not documented here, but it is assumed that HTTP URLs are supported (at least) and fetching errors are reported. This document does not specify how the format of each email part is determined, but it is assumed that MIME type and content would need to be analyzed. After accepting the draft, the Toolset uses sender's email address to select submitter's identity (R57/b), checks the submission (R58/b), and posts the draft if the check is successful (R59/b). The submitter should be notified of the outcome of the draft submission via email (R60/b). Other requirements for web interface (including requirements on submission preprocessing, draft validation, submitter authentication, draft posting, and notification) apply to email interface. Therefore, a typical successful submission via email interface may result in the following exchange of messages ("T" is for "Toolset", "S" is for "submitter", and "A" is for "all authors and submitter"): S-->T: the draft version S<--T: a challenge to verify email access S-->T: a response to the challenge A<--T: warnings and the receipt where the message containing the challenge may include warnings as well. Rousskov Expires June 22, 2005 [Page 22] Internet-Draft Draft Submission Toolset: Requirements December 2004 When draft validation fails, the following emails may be exchanged: S-->T: the draft version S<--T: errors and receipt Email parts/attachments that are not recognized as draft formats are not considered as draft formats. Such parts are ignored by the Toolset (R107/b), except a warning is generated for each unrecognizable part containing more than whitespace (R108/b). These two requirements are meant to make the interface robust in the presence of email signatures and other parts outside of the submitter control. Hint: Toolset actions can be implemented to support email and web interfaces without code duplication. While both web and email interfaces allow for fast posting of valid drafts, there are significant differences between the two interfaces. Primary advantages of email interface are: off-line mode: A submitter can do all the manual work required to submit a draft while being disconnected from the network. The email client actually submits the draft when connectivity is regained. poor connectivity: Email systems are often better suited for automated transmission and re-transmission of emails when network connectivity is poor due to high packet loss ratios, transmission delays, and other problems. convenience: Some IETFers consider email interfaces as generally "more convenient". Primary advantages of web interface are: confirmation: A submitter is given a chance to verify that automated extraction of meta-data produced reasonable results. Other useful confirmations are possible (e.g., "Are you sure you want to post a version of the draft that was updated 30 seconds ago by your co-author?"). validation: A submitter can validate the draft without posting it. quality: Non-critical warnings may prompt the submitter to postpone posting to improve draft quality. Rousskov Expires June 22, 2005 [Page 23] Internet-Draft Draft Submission Toolset: Requirements December 2004 manual adjustments: The submitter can adjust extracted meta-data and ease Secretariat work on manually posting an unusual draft. meta-data: The submitter can specify optional external meta-data (that cannot be extracted from the draft itself). For example, an email address for draft discussion can be specified. context help: Web interface makes it easy to provide links to extra information about input fields, errors, posting options, deadlines, etc. opaqueness: Files submitted via web interface are arguably less susceptible to various in-transit transformations and misinterpretation than emails. Emails are often mutated by mail agents (e.g., automated disclaimers added by senders and extra line feeds added by recepients). convenience: Some IETFers consider web interfaces as generally "more convenient". 17. Implementation stages This section defines Toolset implementation stages or phases. There are three consecutive stages, marked with letters "a", "b", or "c". Earlier stage requirements must still be satisfied in later stages. Thus, all earlier requirements need to be re-interpreted and re-evaluated for every new stage or feature added. Unless noted otherwise, requirements listed in later stages may be covered in earlier stages, but do not have to be. If implementors decide to add some functionality from a future stage, they has to be very careful to satisfy all requirements related to that functionality. Unfortunately, there is no reliable, pragmatic way to identify "all requirements" related to a given feature. (a) Trial Stage: Initial basic implementation to test major concepts and relieve the Secretariat from handling the most common submission case. This stage focuses on plain text draft submission via the web interface. Trial stage should take a dedicated professional about 45 calendar days to finish (i.e., to comply with all the listed requirements). (b) Production Stage: Support for all major features. Once this stage is completed, the Secretariat should only handle unusual draft submissions. This stage should take about 100 calendar days to finish. Gradual release of implemented features is possible and expected. Rousskov Expires June 22, 2005 [Page 24] Internet-Draft Draft Submission Toolset: Requirements December 2004 (c) Enhancement Stage: A never-ending stage focusing on sophisticated features (e.g., draft interpretation or validation) that improve the overall quality of the Toolset. This stage is documented primarily to highlight the overall direction of the Toolset; its requirements are often imprecise and many are expected to change. Implementation experience is likely to result in changes of the Toolset requirements. Such changes should be documented as a part of stage evaluation activities. 18. Security Considerations Removing humans in the draft submission and posting process (a.k.a., automation) requires adding features to make the Toolset reliable in the presence of denial of service (DoS) attacks and attempts to corrupt draft repository. Ideally, the Toolset needs to resist both premeditated malicious actions and good-intent accidents. This document contains specific requirements to minimize impact of DoS attacks (e.g., R97). The requirements are designed with the assumption that it is acceptable for the Toolset to block valid submissions during a DoS attack as long as Toolset maintainers are notified and already posted drafts are not damaged. This document also contains many specific requirements related to detection of drafts violating IETF posting rules. Those requirements help reduce the number of "bad" drafts posted by mistake but do not offer reliable protection from submitters with malicious intent: Since automated tools do not truly understand drafts (and will not do so in the foreseeable future), it is technically possible to post a rogue draft violating IETF posting rules. For example, a draft may contain abstract text that makes the IETF-approved IPR statements following the abstract meaningless or legally non-binding. Stronger submitter authentication may be required to deter malicious submitters. The documented authentication mechanism (i.e., read access to ones email) is deemed appropriate to deploy the first versions of the Toolset, under close Secretariat supervision. Hint: to increase chances of detecting problems early enough, it may be a good idea to automatically inform a designated human of every posted submission (during initial deployment of the Toolset). 19. IANA Considerations None. Rousskov Expires June 22, 2005 [Page 25] Internet-Draft Draft Submission Toolset: Requirements December 2004 20. Compliance A Toolset implementation is compliant with this specification if it satisfies all normative requirements (i.e., the phrases marked with "Rnnn" as defined in Section 4). Compliance should be evaluated for each implementation stage as some requirements do not apply to some stages. IESG evaluates implementations and interprets requirements as necessary. Appendix A. Comparison with current procedures This section summarizes major differences between draft submission approach currently in use by IETF and the proposed Toolset, including violations of the current IETF rules. o The Toolset allows posting of XML and PDF draft formats. XML format is not currently accepted by the Secretariat, and legality of PDF acceptance by the Secretariat has been questioned. XML sources should be accepted to enable IETF tools and participants to have access to raw draft meta-data and content. They are also useful to the RFC Editor and, hence, it is a good idea to validate and get them "into the system" early. The latter argument applies to PDF drafts as well, although the first Toolset versions are not expected to interpret PDF drafts. o The Toolset may eventually generate HTML draft formats from XML draft sources (see R112). Currently, IETF does not provide HTML draft formats -- the Secretariat does not accept HTML sources and no HTML is generated from accepted draft sources. Note, however, that this document does not suggest that the Toolset should eventually accept drafts in HTML format. o The Toolset defines "WG draft" as a draft which name starts with "draft-ietf-". All other drafts are treated as individual drafts. Currently, an IETF WG does not have to follow a single WG draft naming format. Thus, the 00 version of a draft that the WG considers a WG draft can be posted by the Toolset without WG consent. Affected WGs would have to deal with the consequences of their decision not to use a common naming format. The Tools team suggests that IETF requires WGs to name their drafts using a single format to minimize confusion. Hopefully, there are no humans named "Ietf" or, at least, none of them wants to auto-post individual drafts. o The Toolset will automatically notify authors of posted drafts. Currently, neither the submitter nor any of the co-authors are Rousskov Expires June 22, 2005 [Page 26] Internet-Draft Draft Submission Toolset: Requirements December 2004 explicitly notified when the draft is posted. Notification is meant, in part, to allow co-authors detect cases where their name is put on the authors list without permission. Eventually, there will be a general IETF mechanism to allow 3rd parties such as ADs, chairs, or reviewers to register for draft notifications. o The Toolset may eventually accept compressed drafts (see R150). Currently, the Secretariat does not accept "zip" archives due to virus contamination concerns. A proper implementation of the Toolset must address such concerns, while the Secretariat may still need to reject certain formats if they are submitted via the manual route. Appendix B. Acknowledgments The author gratefully acknowledges the contributions of Harald Tveit Alvestrand (Cisco), Brian E. Carpenter (IBM), Barbara B. Fuller (Foretec), Henrik Levkowetz, Larry Masinter (Adobe), Pekka Savola (Netcore), Henning Schulzrinne (Columbia University), and Stanislav Shalunov (Internet2). Special thanks to Marshall Rose for his xml2rfc tool. Appendix C. Change log RFC Editor Note: This section is to be removed during the final publication of the document. Internal WG revision control ID: $Id: id.xml,v 1.36 2004/12/22 05:49:02 rousskov Exp $ version 07 * Added R146, a requirement to generate a warning (and, eventually, a complete diff) when the produced plain text does not match the submitted one (even if metadata matches). * Added a stage-c suggestion R148 to add a smart fuzzy match function to compare submitted and generated-from-XML texts. Hinted at using multiple xml2rfc versions to avoid warnings based on minor xml2rfc differences alone. * Added R150 to eventually support submission of compressed drafts (via both web and email interfaces). Noted that the Secretariat currently does not accept "zip" archives. * Be explicit that CGI is not somehow mandated for server-side Rousskov Expires June 22, 2005 [Page 27] Internet-Draft Draft Submission Toolset: Requirements December 2004 implementations. The implementor will pick the right technology given all the factors, including her experience and available tools (Henning Schulzrinne). * Added "opaqueness" to the list of web interface advantages, inspired by the number of folks complaining about their drafts being mutated by the mail system while in-transit to the draft archive. version 06 * Instead of using a special section to map requirements to Toolset implementation stages, encode the stage with each requirement. The reader now knows requirement "urgency" when reading the requirement itself, instead of having to search for the requirement code in the "Implementation stages" section. Also, this makes it much easier to make sure that all requirements are "staged". * Reflected Tools team concerns about HTML generation by placing that feature in the Enhancement implementation stage and explicitly mentioning that the feature may be gone before its implemented. * Added R143/a to avoid mismatching formats: Drafts containing PDF or Postscript format must not be auto-posted until the Toolset can validate that their content matches plain text format. Documented rationale and future direction for format acceptance rules. * Defined "WG draft" as a draft which name starts with "draft-ietf-". All other drafts are treated as individual drafts. * Support (eventually) fetching draft data using an email-embedded URL (Stanislav Shalunov). * Re-Resolved XXX37: support submitting drafts in main email "body", not just attachments (Stanislav Shalunov). * Renamed draft submission date into draft version creation date and documented how creation and expiration dates are validated and the fact that they do not depend on submission time. * Required implementation to be open-source (see R144/a). Rousskov Expires June 22, 2005 [Page 28] Internet-Draft Draft Submission Toolset: Requirements December 2004 version 05 * Changed draft status to solicit editorial comments and indicate close-to-be-last-called state. * Wrote "Security Considerations" section. * Refer to ID-NITS document as an list of nits the Toolset should check for in R116. Hinted that Henrik's idnits tool can be used for actual checks. More checking tools can be added eventually. * Added more submission cancellation details. Covered both explicit (via submitter action) and implicit (via timeout) cancellations (Stanislav Shalunov). * Adjusted "Global" DoS threshold from 500 to 300 and added a "WG" DoS threshold of 30 draft versions per day (inspired by Stanislav Shalunov). * Illustrated what emails may be exchanged when email interface is in use (Stanislav Shalunov). * Replaced Validation page with validate-only flag on the Upload page. This helps avoid multiple well-known locations for similar tools and might simplify the implementation. * Resolved XXX12: Simply refer to the ID-NITS document for now. * Resolved XXX13, XXX14: Placed "lawful submitter" check into the "External meta-data" section. Documented what submitters the Toolset has to identify as lawful submitters (R119 - R122). Others would require manual checks by the Secretariat. * Resolved XXX58: Documented what the Toolset must do if no approval exists at the time of the WG draft submission (R123, R124). * Removed XXX64: PDF drafts are currently allowed to be posted; why they are allowed is not really important. * Resolved XXX66: XML draft sources are currently not allowed to be posted. * Resolved XXX68: use draft "version" instead of "revision". Guidelines to Authors of Internet-Drafts document uses both. RFC 2026 uses "version", which is also a more popular and arguably more precise term. Rousskov Expires June 22, 2005 [Page 29] Internet-Draft Draft Submission Toolset: Requirements December 2004 version 04 * In Check action, documented once, early, and explicitly that errors make auto-posting impossible but should let the submitter to post manually. Removed references to vague "action fails" statements (Henrik Levkowetz). * HTTP error codes should not be used to indicate Check action errors because doing so would be a layering violation and, in some cases, may complicate both automated and manual interpretation of the Toolset responses. Rewrote R7 to require use of computer-friendly tags in response body instead of HTTP status codes. * Split "Preprocessing" subsection into "Preprocessing" and "Processing". The former deals with XML include PIs while the latter talks about plain text and HTML generation (Henrik Levkowetz). * Removed post-if-valid functionality (R78 - R80). Automation tools such as the ones that process e-mail-based submissions would benefit from having the knob, but they cannot use the Check action "as is", even with the knob, because there are other differences in the interface (e.g., submitter identification logic). In other words, more knobs would be needed, which would defeat the purpose of reusing the same action. When implementing web and e-mail interfaces, the Secretariat should still be able to reuse the base action code, of course. * Defined compliance. * Resolved XXX2: inform all authors that their draft was posted. Documented what information should go into the posting notification message/page. * Resolved XXX16 and XXX57: R23 now says that an IETF IPR Statement and other boilerplate required for drafts according to RFC 3667 and 3668 (or successors) must appear in the draft text (Henrik Levkowetz). * Resolved XXX23 and XXX62: Manual Check page and actions used by secretariat do not verify submitter access to e-mail. Last resort option should be as flexible and forgiving as possible. * Resolved XXX26: it should be possible to respond to do-you-have-access-to-your-email message by e-mail, in addition to cut-and-pasting a URL. Rousskov Expires June 22, 2005 [Page 30] Internet-Draft Draft Submission Toolset: Requirements December 2004 * Resolved XXX30 and XXX31: R98 now requires that when submitter is not an author, Secretariat has to be involved. * Resolved XXX37: E-mail submissions must use attachments, even if there is only one draft format. This may help to keep the Toolset simple (no smarts needed to isolate true draft text from notes in the beginning of the e-mail and signatures). * Resolved XXX38: do not require special Subject: lines for e-mail submission to keep the Toolset simple. Since we verify submitter access to e-mail, no automated spam is likely to result in a draft submission. * Resolved XXX43, XXX44, and XXX60: making an existing draft obsolete is out of this document scope. This complex feature can be documented and integrated later to satisfy R33. * Resolved XXX49 and XXX52: the first two implementation stages should take 30 and 90 days, provided a single full-time person effort. * Resolved XXX50: specify approximate effort required to complete the first two implementation stages. Let IESG and the Secretariat use our estimates to agree on a specific implementation schedule/deadlines. * Resolved XXX53: lack of author e-mail causes a warning, not error. See R95 for rationale. * Resolved XXX11: added page count and size of primary draft format to meta-data because this information is useful to some humans and tools, and because it is usually much easier and cheaper to get this information in static form (e.g., some draft meta-data XML file) than compute it dynamically. * Resolved XXX15: always allow posting of a new revision but warn if new revision is not expected. Moved the corresponding R21 from absolute to desired requirements. * Resolved XXX33 and XXX59: prevent DoS attacks (absolute requirement R97) and warn about too-close submissions (desired feature R96). * Defined draft version, format and primary format terms. Rousskov Expires June 22, 2005 [Page 31] Internet-Draft Draft Submission Toolset: Requirements December 2004 2004/10/05 * Resolved XXX9: The Toolset should eventually offer a Validation-only page. * Resolved XXX19: The Toolset should eventually provide the submitter with a way to preview the entire draft, with all formats. * Resolved XXX40, XXX41, and XXX56: first use draft name to extract WG flag and WG name and hope for an IETF policy change. If IETF policy on naming drafts does not change soon, add code to query some databases to map individual-looking drafts to WG names. * Resolved XXX46 and XXX47: store and make public both original and preprocessed XML sources. Most tools are likely to use preprocessed XML format. Humans and some diff tools may prefer the original. 2004/09/30 * Added requirements R72 and R73 to handle multiple submitters submitting the same draft and a single submitter submitting two drafts at the same time, addressing XXX27. * Resolved XXX7: There seems to be no good reason to support cut-and-paste mode. Submission via file upload interface should suffice. * Semi-resolved XXX53: Toolset should accept PDFs because RFC Editor does. Still need to check whether the Secretariat accepts PDFs legally today (XXX64). 2004/09/29 * Clarified and polished the "Scope" section. * Updated "State of this draft" to document approaching-last-call state of the draft and to solicit editorial-level feedback. 2004/09/27 * Marked formal toolset requirements using a Rnnn notation to (a) document implementation schedule, and (b) make compliant implementation and compliance evaluation easier. * Marked informal implementation hints with a "Hint:" tag, to Rousskov Expires June 22, 2005 [Page 32] Internet-Draft Draft Submission Toolset: Requirements December 2004 avoid possible confusion with formal requirements. * Started documenting implementation schedule. For example, only plain text formats are interpreted during the first stage, then XML support is added, then other formats. Meanwhile, un-interpreted formats are accepted and posted as is as long as plain text version validates. * Added explicit requirements for managing abandoned submissions (Brian E. Carpenter) * Plain text or XML formats are always required (Brian E. Carpenter) * Added XXX55: Accepting PDFs is a change of current documented procedures? (Brian E. Carpenter) * Added an optional "discussion address" to the external meta-data to help reviewers know where to send comments (inspired by Brian E. Carpenter suggestion; Brian wanted this to be a required extractable meta-data) * Resolved XXX17, XXX28, and XXX29: Today, -00 WG drafts are approved by the Chair either before and after submission, depending on several factors. Based on WG chairs feedback we still need to support both modes. Thus, there is no policy change to talk about (and more work for the tool implementors to support both modes). Still need to add specific toolset requirements in case there is no approval recorded. * Resolved XXX18, XXX32, and XXX45: We are going to move "request for publication" functionality to a separate [simple] tool that works with an existing/posted draft. * Resolved XXX6: We are going to move the "withdraw this ID" functionality desired by Secretariat to a separate [simple] tool that works with an existing/posted draft. * Added a "comment" field to the Adjust page so that the submitter can tell Secretariat why manual action is necessary. This may both save time Secretariat and let them improve the toolset to minimize manual submissions (including fixing validation/extraction bugs). * Added the Receipt page to the list of documented pages, for completeness. * Emphasized that common sequence of pages to go through is as Rousskov Expires June 22, 2005 [Page 33] Internet-Draft Draft Submission Toolset: Requirements December 2004 short as possible for a given set of features, and that "page" means "distinct dialog", not necessarily a "distinct URL". Some reviewers thought "there are too many pages". 2004/09/20 * Added "E-mail Interface" section to document how key toolset functionality can be accessed via e-mail. Compared e-mail and web interfaces. (Suggested by Pekka Savola) * Split "WG ID" meta-data into "WG ID" and "WG Flag". The former seems to be easy to extract from the draft name. Noted that the latter (i.e., "this is a working group draft" status) cannot be inferred from some WG drafts (Pekka Savola). * Added "List of drafts obsoleted by this draft" external meta-data item (Pekka Savola), but questioned whether we are ready to automate that. * Added more conflicting opinions to XXX15 and proposed a solution. * Added "Preprocessing" subsection to reflect the discussion on how/whether handle include PIs in XML draft sources. Needs more discussion/work. * Further clarified how an author can request the draft revision to be published (i.e., forwarded to IESG or RFC Editor for review and publication as an RFC or BCP). It's just a checkbox on the web interface. Raised doubts we can pull this off (see XXX45). * Suggested in XXX2 that we would inform all authors but not seek their consent (except for the submitter) when posting their draft. 2004/09/09 * Polished high-level page/action summary and replaced text-based steps diagram with something that looks more like a diagram. * Added "Comparison with current procedures" section placeholder for summarizing what this draft improves/changes/violates. * Frequent draft updates is not always a good thing (Henrik Levkowetz) * Added ideas regarding frequent draft updates warnings Rousskov Expires June 22, 2005 [Page 34] Internet-Draft Draft Submission Toolset: Requirements December 2004 (Stanislav Shalunov) * Added "State of this draft" section to encourage review. 2004/09/02 * Documented all major toolset pages and corresponding actions. 2004/09/01 * Deleted all primary modes except for what used to be called "Posting Automation". Focus on the latter and mention other modes as exceptions or side-effects. * Changed draft outline and depth to describe specific submission steps and corresponding web pages rather than more general ideas/requirements. * Assume, for now, that Chair authorization of WG draft work must exist for WG draft to be published. This needs to be documented and perhaps relaxed to allow post-submission approvals. 2004/08/30 * Use "toolset" instead of a less accurate "interfaces" in the draft title and throughout the text (Henrik Levkowetz) * Use "post" instead of "publish"" in the draft title and throughout the text (Barbara B. Fuller and Larry Masinter) * Nits, clarifications, datapoints (Harald Tveit Alvestrand, Henrik Levkowetz, Larry Masinter, and Barbara B. Fuller for the Secretariat) 2004/08/25 * Initial revision. 21. References 21.1 Normative References [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. [RFC3667] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC Rousskov Expires June 22, 2005 [Page 35] Internet-Draft Draft Submission Toolset: Requirements December 2004 3667, February 2004. [RFC3668] Bradner, S., "Intellectual Property Rights in IETF Technology", BCP 79, RFC 3668, February 2004. 21.2 Informative References [I-D.mrose-writing-rfcs] Rose, M., "Writing I-Ds and RFCs using XML (revised)", draft-mrose-writing-rfcs (work in progress), April 2004. [secretariat] "Private communication with the IETF Secretariat", 2004. [OSI] "Open Source Licenses Approved by the Open Source Initiative", 2004. Author's Address Alex Rousskov The Measurement Factory EMail: rousskov@measurement-factory.com URI: http://www.measurement-factory.com/ Rousskov Expires June 22, 2005 [Page 36] Internet-Draft Draft Submission Toolset: Requirements December 2004 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Rousskov Expires June 22, 2005 [Page 37]