OASIS - Security Services TC RL "Bob" Morgan Jeff Hodges 16-Feb-2001 OASIS Security Services Technical Committee Document Guidelines This document is an OASIS-Draft and is in conformance with relevant OASIS SSTC document standards (i.e., itself). comments to: security-services@lists.oasis-open.org Abstract This document specifies document-handling practices for the OASIS Security Services Technical Committee (SSTC) and its subcommittees. 1. Introduction This document recommends standards for name, format, and availability of documents that are being worked on in subcommittees of the OASIS SSTC (and, potentially, other areas of OASIS). It is loosely based on standards for documents in IETF working groups, as described in [2], [3], and [4]. The intended benefits are: clarity of document status, uniform availability, consistent document-handling among different working groups, and facilitation of group web site maintenance; all while being as consistent as possible with the otherwise free-form OASIS process. The standards expressed here are for draft documents and Committee Specifications produced specifically by the SSTC and its subcommittees. See Article 2, Section 2 of [5] for the standards used for producing OASIS Specifications and other OASIS-wide documents. 2. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [1]. "TC" is used throughout this document to mean "Technical Committee", which specifically means the Security Services TC at this stage in this document's life cycle. 3. Intellectual property rights policies The OASIS General Policy for intellectual property rights (IPR) is expressed in [6] as: In all matters of intellectual property rights and procedures, the intention is to benefit the public at large, while respecting the legitimate rights of others. The reader must refer to [6] for detailed description of IPR rules, conventions, and required document noticies. TC and TC subcommittee draft documents SHOULD contain applicable IPR notices from [6], and approved TC final documents MUST contain applicable notices from [6]. 4. Document evolution model 4.1 Overview This recommendation provides a simple model of how documents move from initial ideas to final, approved SSTC work products. Documents begin as drafts, proceed through a number of revisions, and finally, upon approval by the committee, are published as Committee Specifications. Upon approval by the OASIS membership as a whole, they are published as OASIS Specifications. Article 2, Section 2 of [5] documents the latter step of this overall process. This document is concerned with the steps up to and including a document becoming an SSTC Committee Specification. Document filenames reflect the overall process. Draft documents are denoted by their filenames beginning with "draft-". Draft documents are not permanent, and may be superseded or removed at any time. Detailed document guidelines including filename conventions are presented in section 5, below. Completed TC draft documents that are intended to be submitted for OASIS membership approval are to be published as Committee Specifications as specified in section 4.X, below. 4.2 The TC Editor Function The collection of TC documents, including but not limited to TC drafts, individual submissions, Committee Specifications, is managed by the TC Editor Function (the "TC Editor" aka "security-editors"). The TC Editor is a role that is occupied at any particular time by one or more TC members (at this time decided upon at the pleasure of the TC Chair). The TC Editor is addressed by electronic mail using the address.. security-editors@lists.oasis-open.org The TC Editor has responsibility for assigning document filenames (according to the guidelines in this document), ascertaining whether said documents meet the guidelines as specified in this document, remanding the documents to the authors if deemed necessary (e.g. if the document(s) don't meet these guidelines), publishing said documents on the TC website and denoting status thereof (e.g. whether the document(s) are a TC Draft, individual submission, or Committee Specification). 4.3 Individual submission and TC draft documents A distinction is made between "individual submission" draft documents and "TC or TC subcommittee" draft documents (hereinafter referred to simply as "TC draft documents"). An individual submission (which may of course be submitted by more than one person) represents only the opinions of its authors. A TC draft document is intended to reflect the (rough) consensus of the TC or applicable TC subcommittee. The topics of TC draft documents will typically be specified in the TC or subcommittee charter or are otherwise agreed upon by the TC, while individual submissions may be on any topic relevant to the work. Document filenames reflect the distinction between individual submissions and TC or subcommittee documents. Migration of individual submission draft documents to TC draft documents is done via a motion or general consent of the TC or subcommittee (see Chapter 2, Section 4 of [7]). Likewise, working group document also may migrate to an individual submission of the TC or subcommittee via a motion or general consent of the TC or subcommittee. 4.4 Publishing Committee Specifications A member of the TC or subcommittee may move to recognize a TC draft as a Committee Specification, or the Chair may call for general consent (see Chapter 2, Section 4 of [7]). The TC draft MUST satisfy the document guidelines as specified in this document at the time such a motion is made. A simple majority of the full TC membership is required in order to recognize a TC draft as a Committee Specification. Upon such recognition, the filename of TC draft remains unchanged from the filename (as specified in 5.2 below) at the time of recognition. The TC draft's status as a Committee Specification is duly noted by the TC editor in the TC document repository and any index or content listing thereof. 4.5 TC Document Repository The TC document repository is available via this URL.. http://www.oasis-open.org/committees/security/docs/ 5. Document guidelines These guidelines apply to all documents submitted for committee or subcommittee consideration, and apply while draft documents are being worked on by the applicable group. 5.1 Availability Documents shall be available via the TC's web page on the OASIS web site, or via at most one non-OASIS site. Documents shall be available via HTTP, and optionally via FTP. Documents may be sent to committee e-mail lists, but any documents so sent will subsequently be made available via the committee web site, unless the author specifically informs the committee chair not to do so. Thus, documents sent to mailing lists should conform to these guidelines. The presence of new documents and new revisions shall be announced to the working group mailing list. 5.2 Document Filename Conventions TC drafts MUST be named using the format: "draft-sstc-" + [ subcommittee mailing list acronym + "-" ] + short title + "-" + two-digit version + "." + doc format e.g. "draft-sstc-core-assertions-05.html". The "[ subcommittee mailing list acronym + "-" ]" is NOT used for TC drafts that are TC-wide and/or have been approved as Committee Specifications (see section 4 above). Individual submissions MUST be named using the format: "draft-" + main author's last name + "-" + short title + "-" + two-digit version + "." + doc format e.g. "draft-morgan-coolidea-00.txt". 5.2.1 Subcommittee mailing list acrocyms This is the present list of SSTC subcommittee mailing list acronyms for use with the file name convention for TC drafts: bindings conform core protocol consider use 5.3 Formats PDF format is the preferred distribution document format. Document source formats are XML encoded according to the XXX DTD for text, and Powerpoint source for illustrations (one illustration per powerpoint slide, one powerpoint file containing multiple slides per corresponding XML textual source file). 5.4 Content elements A document must include, at the beginning, the author's names, the date of submission, the document name including version number, the name of the working group, and an email address to which comments can be directed. A document must include, at the end, author contact information for all authors, including at least an email address for each. A document should include, at the beginning, a short abstract, and, if applicable, a table of contents. Sections and subsections should be numbered, and usually named also, for ease of reference. A document should include, at the end, References and Acknowledgements sections. 6. Reference(s) [1] Bradner, S. "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. Available at: http://www.ietf.org/rfc/rfc2119.txt [2] Bradner, S. "IETF Working Group Guidelines and Procedures", BCP 25, RFC 2418, September 1998. Available at: http://www.ietf.org/rfc/rfc2418.txt [3] "Guidelines to Authors of Internet-Drafts", IETF. Available at: http://www.ietf.org/ietf/1id-guidelines.txt [4] Bradner, S. "The Internet Standards Process -- Revision 3", BCP 9, RFC2026, October 1996. Available at: http://www.ietf.org/rfc/rfc2026.txt [5] Organization for the Advancement of Structured Information Standards, "AMENDED AND RESTATED BYLAWS OCTOBER 13, 2000". Available at: http://www.oasis-open.org/who/bylaws.shtml [6] "OASIS Policy on Intellectual Property Rights (OASIS.IPR)" Available at: http://www.oasis-open.org/who/intellectualproperty.shtml [7] Robert III, Henry M., Evans, William J., Honemann, Daniel H., Balch, Thomas J. "Roberts Rules of Order Newly Revised", 10th Ed., Perseus Publishing, New York, October 2000, ISBN 0738203076. [8] Morgan, RL "Bob" "Internet2 Middleware Initiative Working Group Document Guidelines", internet2-mi-doc-guidelines-00.txt, 25-Jan-2001. Available at: http://middleware.internet2.edu/internet2-mi-doc-guidelines-00.txt 7. Acknowledgements This document is largely based on internet2-mi-doc-guidelines-00.txt by RL "Bob" Morgan, [8]. The authors gratefully acknowledge the suggestions of Neal McBurnett, and information about OASIS practices supplied by Karl Best. 8. Author information RL "Bob" Morgan Computing & Communications University of Washington rlmorgan@washington.edu Jeff Hodges Oblix Inc. jhodges@oblix.com 9. OASIS Intellectual Property Notice OASIS takes no position regarding the validity or scope of any intellectual property 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; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication 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 implementors or users of this specification, can be obtained from the OASIS Executive Director. OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director. 10. Copyright Notice Copyright (C) The Organization for the Advancement of Structured Information Standards [OASIS] (date). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMTED 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.