├── CONTRIBUTING.md ├── LICENSE.md ├── NOTICES.md ├── README.md ├── code_of_conduct.md └── spec ├── GITOID_URI.txt └── SPEC.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Community Specification Contributor License Agreement 1.0 2 | 3 | By making a Contribution to this repository, I agree to the terms of the 4 | following documents located at : 5 | 6 | 1. Community Specification License 1.0 (`LICENSE.md`) 7 | 2. Community Specification Contribution Policy 1.0 (`CONTRIBUTING.md`) 8 | 3. Community Specification Code of Conduct (`CODE_OF_CONDUCT.md`) 9 | 10 | In addition, for source code contributions, I certify that: 11 | 12 | (a) The contribution was created in whole or in part by me and I have the 13 | right to submit it under the open source license indicated in the file; or 14 | (b) The contribution is based upon previous work that, to the best of my 15 | knowledge, is covered under an appropriate open source license and I have 16 | the right under that license to submit that work with modifications, 17 | whether created in whole or in part by me, under the same open source license 18 | (unless I am permitted to submit under a different license), as indicated in 19 | the file; or (c) The contribution was provided directly to me by some other 20 | person who certified (a), (b) or (c) and I have not modified it. (d) I 21 | understand and agree that this working group and the contribution may be 22 | public and that a record of the contribution (including all personal 23 | information I submit with it, including my sign-off) is maintained 24 | indefinitely and may be redistributed consistent with this agreement or the 25 | open source license(s) involved. 26 | 27 | I represent that I am legally entitled to make the grants set forth in the 28 | documents above. If my employer(s) has rights to intellectual property that 29 | may be infringed by the materials developed by this Working Group, I 30 | represent that I have received permission to enter these agreements on behalf 31 | of that employer. 32 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # Community Specification License 1.0 2 | 3 | **The Purpose of this License.** This License sets forth the terms under which 1) Contributor will participate in and contribute to the development of specifications, standards, best practices, guidelines, and other similar materials under this Working Group, and 2) how the materials developed under this License may be used. It is not intended for source code. Capitalized terms are defined in the License’s last section. 4 | 5 | **1. Copyright.** 6 | 7 | **1.1. Copyright License.** Contributor grants everyone a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) copyright license, without any obligation for accounting, to reproduce, prepare derivative works of, publicly display, publicly perform, and distribute any materials it submits to the full extent of its copyright interest in those materials. Contributor also acknowledges that the Working Group may exercise copyright rights in the Specification, including the rights to submit the Specification to another standards organization. 8 | 9 | **1.2. Copyright Attribution.** As a condition, anyone exercising this copyright license must include attribution to the Working Group in any derivative work based on materials developed by the Working Group. That attribution must include, at minimum, the material’s name, version number, and source from where the materials were retrieved. Attribution is not required for implementations of the Specification. 10 | 11 | **2. Patents.** 12 | 13 | **2.1. Patent License.** 14 | 15 | **2.1.1. As a Result of Contributions.** 16 | 17 | **2.1.1.1. As a Result of Contributions to Draft Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims in 1) Contributor’s Contributions and 2) to the Draft Specification that is within Scope as of the date of that Contribution, in both cases for Licensee’s Implementation of the Draft Specification, except for those patent claims excluded by Contributor under Section 3. 18 | 19 | **2.1.1.2. For Approved Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims included the Approved Specification that are within Scope for Licensee’s Implementation of the Approved Specification, except for those patent claims excluded by Contributor under Section 3. 20 | 21 | **2.1.2. Patent Grant from Licensee.** Licensee grants each other Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims for its Implementation, except for those patent claims excluded under Section 3. 22 | 23 | **2.1.3. Licensee Acceptance.** The patent grants set forth in Section 2.1 extend only to Licensees that have indicated their agreement to this License as follows: 24 | 25 | **2.1.3.1. Source Code Distributions.** For distribution in source code, by including this License in the root directory of the source code with the Implementation; 26 | 27 | **2.1.3.2. Non-Source Code Distributions.** For distribution in any form other than source code, by including this License in the documentation, legal notices, via notice in the software, and/or other written materials provided with the Implementation; or 28 | 29 | **2.1.3.3. Via NOTICES.md.** By issuing pull request or commit to the Specification’s repository’s NOTICES.md file by the Implementer’s authorized representative, including the Implementer’s name, authorized individual and system identifier, and Specification version. 30 | 31 | **2.1.4. Defensive Termination.** If any Licensee files or maintains a claim in a court asserting that a Necessary Claim is infringed by an Implementation, any licenses granted under this License to the Licensee are immediately terminated unless 1) that claim is directly in response to a claim against Licensee regarding an Implementation, or 2) that claim was brought to enforce the terms of this License, including intervention in a third-party action by a Licensee. 32 | 33 | **2.1.5. Additional Conditions.** This License is not an assurance (i) that any of Contributor’s copyrights or issued patent claims cover an Implementation of the Specification or are enforceable or (ii) that an Implementation of the Specification would not infringe intellectual property rights of any third party. 34 | 35 | **2.2. Patent Licensing Commitment.** In addition to the rights granted in Section 2.1, Contributor agrees to grant everyone a no charge, royalty-free license on reasonable and non-discriminatory terms to Contributor’s Necessary Claims that are within Scope for: 36 | 1) Implementations of a Draft Specification, where such license applies only to those Necessary Claims infringed by implementing Contributor's Contribution(s) included in that Draft Specification, and 37 | 2) Implementations of the Approved Specification. 38 | 39 | This patent licensing commitment does not apply to those claims subject to Contributor’s Exclusion Notice under Section 3. 40 | 41 | **2.3. Effect of Withdrawal.** Contributor may withdraw from the Working Group by issuing a pull request or commit providing notice of withdrawal to the Working Group repository’s NOTICES.md file. All of Contributor’s existing commitments and obligations with respect to the Working Group up to the date of that withdrawal notice will remain in effect, but no new obligations will be incurred. 42 | 43 | **2.4. Binding Encumbrance.** This License is binding on any future owner, assignee, or party who has been given the right to enforce any Necessary Claims against third parties. 44 | 45 | **3. Patent Exclusion.** 46 | 47 | **3.1. As a Result of Contributions.** Contributor may exclude Necessary Claims from its licensing commitments incurred under Section 2.1.1 by issuing an Exclusion Notice within 45 days of the date of that Contribution. Contributor may not issue an Exclusion Notice for any material that has been included in a Draft Deliverable for more than 45 days prior to the date of that Contribution. 48 | 49 | **3.2. As a Result of a Draft Specification Becoming an Approved Specification.** Prior to the adoption of a Draft Specification as an Approved Specification, Contributor may exclude Necessary Claims from its licensing commitments under this Agreement by issuing an Exclusion Notice. Contributor may not issue an Exclusion Notice for patents that were eligible to have been excluded pursuant to Section 3.1. 50 | 51 | **4. Source Code License.** Any source code developed by the Working Group is solely subject the source code license included in the Working Group’s repository for that code. If no source code license is included, the source code will be subject to the MIT License. 52 | 53 | **5. No Other Rights.** Except as specifically set forth in this License, no other express or implied patent, trademark, copyright, or other rights are granted under this License, including by implication, waiver, or estoppel. 54 | 55 | **6. Antitrust Compliance.** Contributor acknowledge that it may compete with other participants in various lines of business and that it is therefore imperative that they and their respective representatives act in a manner that does not violate any applicable antitrust laws and regulations. This License does not restrict any Contributor from engaging in similar specification development projects. Each Contributor may design, develop, manufacture, acquire or market competitive deliverables, products, and services, and conduct its business, in whatever way it chooses. No Contributor is obligated to announce or market any products or services. Without limiting the generality of the foregoing, the Contributors agree not to have any discussion relating to any product pricing, methods or channels of product distribution, division of markets, allocation of customers or any other topic that should not be discussed among competitors under the auspices of the Working Group. 56 | 57 | **7. Non-Circumvention.** Contributor agrees that it will not intentionally take or willfully assist any third party to take any action for the purpose of circumventing any obligations under this License. 58 | 59 | **8. Representations, Warranties and Disclaimers.** 60 | 61 | **8.1. Representations, Warranties and Disclaimers.** Contributor and Licensee represents and warrants that 1) it is legally entitled to grant the rights set forth in this License and 2) it will not intentionally include any third party materials in any Contribution unless those materials are available under terms that do not conflict with this License. IN ALL OTHER RESPECTS ITS CONTRIBUTIONS ARE PROVIDED "AS IS." The entire risk as to implementing or otherwise using the Contribution or the Specification is assumed by the implementer and user. Except as stated herein, CONTRIBUTOR AND LICENSEE EXPRESSLY DISCLAIM ANY WARRANTIES (EXPRESS, IMPLIED, OR OTHERWISE), INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, CONDITIONS OF QUALITY, OR TITLE, RELATED TO THE CONTRIBUTION OR THE SPECIFICATION. IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Any obligations regarding the transfer, successors in interest, or assignment of Necessary Claims will be satisfied if Contributor or Licensee notifies the transferee or assignee of any patent that it knows contains Necessary Claims or necessary claims under this License. Nothing in this License requires Contributor to undertake a patent search. If Contributor is 1) employed by or acting on behalf of an employer, 2) is making a Contribution under the direction or control of a third party, or 3) is making the Contribution as a consultant, contractor, or under another similar relationship with a third party, Contributor represents that they have been authorized by that party to enter into this License on its behalf. 62 | 63 | **8.2. Distribution Disclaimer.** Any distributions of technical information to third parties must include a notice materially similar to the following: “THESE MATERIALS ARE PROVIDED “AS IS.” The Contributors and Licensees expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.” 64 | 65 | **9. Definitions.** 66 | 67 | **9.1. Affiliate.** “Affiliate” means an entity that directly or indirectly Controls, is Controlled by, or is under common Control of that party. 68 | 69 | **9.2. Approved Specification.** “Approved Specification” means the final version and contents of any Draft Specification designated as an Approved Specification as set forth in the accompanying Governance.md file. 70 | 71 | **9.3. Contribution.** “Contribution” means any original work of authorship, including any modifications or additions to an existing work, that Contributor submits for inclusion in a Draft Specification, which is included in a Draft Specification or Approved Specification. 72 | 73 | **9.4. Contributor.** “Contributor” means any person or entity that has indicated its acceptance of the License 1) by making a Contribution to the Specification, or 2) by entering into the Community Specification Contributor License Agreement for the Specification. Contributor includes its Affiliates, assigns, agents, and successors in interest. 74 | 75 | **9.5. Control.** “Control” means direct or indirect control of more than 50% of the voting power to elect directors of that corporation, or for any other entity, the power to direct management of such entity. 76 | 77 | **9.6. Draft Specification.** “Draft Specification” means all versions of the material (except an Approved Specification) developed by this Working Group for the purpose of creating, commenting on, revising, updating, modifying, or adding to any document that is to be considered for inclusion in the Approved Specification. 78 | 79 | **9.7. Exclusion Notice.** “Exclusion Notice” means a written notice made by making a pull request or commit to the repository’s NOTICES.md file that identifies patents that Contributor is excluding from its patent licensing commitments under this License. The Exclusion Notice for issued patents and published applications must include the Draft Specification’s name, patent number(s) or title and application number(s), as the case may be, for each of the issued patent(s) or pending patent application(s) that the Contributor is excluding from the royalty-free licensing commitment set forth in this License. If an issued patent or pending patent application that may contain Necessary Claims is not set forth in the Exclusion Notice, those Necessary Claims shall continue to be subject to the licensing commitments under this License. The Exclusion Notice for unpublished patent applications must provide either: (i) the text of the filed application; or (ii) identification of the specific part(s) of the Draft Specification whose implementation makes the excluded claim a Necessary Claim. If (ii) is chosen, the effect of the exclusion will be limited to the identified part(s) of the Draft Specification. 80 | 81 | **9.8. Implementation.** “Implementation” means making, using, selling, offering for sale, importing or distributing any implementation of the Specification 1) only to the extent it implements the Specification and 2) so long as all required portions of the Specification are implemented. 82 | 83 | **9.9. License.** “License” means this Community Specification License. 84 | 85 | **9.10. Licensee.** “Licensee” means any person or entity that has indicated its acceptance of the License as set forth in Section 2.1.3. Licensee includes its Affiliates, assigns, agents, and successors in interest. 86 | 87 | **9.11. Necessary Claims.** “Necessary Claims” are those patent claims, if any, that a party owns or controls, including those claims later acquired, that are necessary to implement the required portions (including the required elements of optional portions) of the Specification that are described in detail and not merely referenced in the Specification. 88 | 89 | **9.12. Specification.** “Specification” means a Draft Specification or Approved Specification included in the Working Group’s repository subject to this License, and the version of the Specification implemented by the Licensee. 90 | 91 | **9.13. Scope.** “Scope” has the meaning as set forth in the accompanying SCOPE.md file included in this Specification’s repository. Changes to Scope do not apply retroactively. If no Scope is provided, each Contributor’s Necessary Claims are limited to that Contributor’s Contributions. 92 | 93 | **9.14. Working Group.** “Working Group” means this project to develop specifications, standards, best practices, guidelines, and other similar materials under this License. 94 | 95 | 96 | 97 | *The text of this Community Specification License is Copyright 2020 Joint Development Foundation and is licensed under the Creative Commons Attribution 4.0 International License available at https://creativecommons.org/licenses/by/4.0/.* 98 | 99 | SPDX-License-Identifier: CC-BY-4.0 100 | -------------------------------------------------------------------------------- /NOTICES.md: -------------------------------------------------------------------------------- 1 | # Notices 2 | 3 | ## Code of Conduct 4 | 5 | Contact for Code of Conduct issues or inquires: _________________ 6 | 7 | [Ideally list two different individuals above (not a generic mailing list) as someone submitting a Code of Conduct complaint will want to know exactly who is receiving the complaint. We recommend two individuals in the case one of the individuals is the subject of or directly involved in the subject of a complaint.] 8 | 9 | ## License Acceptance 10 | 11 | Per Community Specification License 1.0 Section 2.1.3.3, Licensees may indicate their acceptance of the Community Specification License by issuing a pull request to the Specification’s repository’s Notice.md file, including the Licensee’s name, authorized individuals' names, and repository system identifier (e.g. GitHub ID), and specification version. 12 | 13 | A Licensee may consent to accepting the current Community Specification License version or any future version of the Community Specification License by indicating "or later" after their specification version. 14 | 15 | --- 16 | 17 | Licensee’s name: 18 | 19 | Authorized individual and system identifier: 20 | 21 | Specification version: 22 | 23 | --- 24 | 25 | ## Withdrawals 26 | 27 | Name of party withdrawing: 28 | 29 | Date of withdrawal: 30 | 31 | --- 32 | 33 | ## Exclusions 34 | 35 | This section includes any Exclusion Notices made against a Draft Deliverable or Approved Deliverable as set forth in the Community Specification Development License. Each Exclusion Notice must include the following information: 36 | 37 | - Name of party making the Exclusion Notice: 38 | 39 | - Name of patent owner: 40 | 41 | - Specification: 42 | 43 | - Version number: 44 | 45 | **For issued patents and published patent applications:** 46 | 47 | (i) patent number(s) or title and application number(s), as the case may be: 48 | 49 | (ii) identification of the specific part(s) of the Specification whose implementation makes the excluded claim a Necessary Claim. 50 | 51 | **For unpublished patent applications must provide either:** 52 | 53 | (i) the text of the filed application; or 54 | 55 | (ii) identification of the specific part(s) of the Specification whose implementation makes the excluded claim a Necessary Claim. 56 | 57 | ----------------------------------------------------------------------------------------- 58 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OmniBOR Specification 2 | 3 | This repository contains the OmniBOR specification, which is the formal 4 | definition of the OmniBOR standard, intended to enable the consistent, 5 | reproducible recording of inputs to builds which produce software 6 | artifacts. 7 | 8 | ## Format 9 | 10 | This standard is intended to be written according to the guidance from 11 | the International Organization for Standardization (ISO) for writing 12 | standards. ISO's [guide to writing standards][iso_guide] is available to 13 | review, as is a [model manuscript of a draft ISO standard][iso_model] 14 | ("The Rice Model"). 15 | 16 | ## Contributing 17 | 18 | Work on the OmniBOR specification is overseen by the OmniBOR Working 19 | Group. If you are interested in contributing to OmniBOR, we recommend 20 | the following: 21 | 22 | - Opening an Issue or a Discussion to share your perspective on a 23 | proposed change, or an issue you've identified in the specification. 24 | - Participating in discussion with respondents to the issue. 25 | - Joining in on the weekly OmniBOR Working Group meetings, where open 26 | issues for the specification can be discussed. 27 | 28 | ## Code of Conduct 29 | 30 | All participants in the OmniBOR project, including anyone communicating 31 | in the OmniBOR Issue Tracker or Discussions, in the OmniBOR Slack channel, 32 | participating in an OmniBOR Working Group meeting, or contributing to any 33 | OmniBOR repository, must abide by the requirements of the project's 34 | [Code of Conduct][coc]. 35 | 36 | ## Licensing 37 | 38 | This specification and the broader contents of this repository are 39 | subject to the Community Specification License 1.0. The full contents 40 | of the license may be found in the [license file][license] in this 41 | repository. This license also includes a description of the licensing 42 | agreed to by contributors to the project. 43 | 44 | [iso_guide]: https://www.iso.org/files/live/sites/isoorg/files/developing_standards/docs/en/how-to-write-standards.pdf 45 | [iso_model]: https://www.iso.org/iso/model_document-rice_model.pdf 46 | [coc]: https://github.com/omnibor/spec/blob/main/CODE_OF_CONDUCT.md 47 | [license]: https://github.com/omnibor/spec/blob/main/LICENSE.md 48 | -------------------------------------------------------------------------------- /code_of_conduct.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to make participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies within all project spaces, and it also applies when 49 | an individual is representing the project or its community in public spaces. 50 | Examples of representing a project or community include using an official 51 | project e-mail address, posting via an official social media account, or acting 52 | as an appointed representative at an online or offline event. Representation of 53 | a project may be further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at [INSERT EMAIL ADDRESS]. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /spec/GITOID_URI.txt: -------------------------------------------------------------------------------- 1 | Scheme name: gitoid 2 | 3 | Status: provisional 4 | 5 | Applications/protocols that use this scheme name: 6 | See [Section 3.5](https://www.rfc-editor.org/rfc/rfc7595.html#section-3.5). 7 | Contact: 8 | Registering party: Ed Warnicke 9 | 10 | Scheme Creator: OmniBOR 11 | 12 | Change controller: 13 | Either the registering party or someone verified to represent 14 | the scheme creator. See previous answer. 15 | 16 | References: 17 | https://git-scm.com/book/en/v2/Git-Internals-Git-Objects 18 | 19 | Scheme syntax: gitoid":"":"":" 20 | 21 | Current valid values for are 'blob','tree','commit', and 'tag'. 22 | Current valid values for are 'sha1' and 'sha256' 23 | should be expressed as a hexadecimal string in lower case. 24 | 25 | Example: gitoid:blob:sha1:261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64 26 | 27 | Scheme semantics: 28 | 29 | gitoid stands for Git Object ID. Git is an object store, which currently supports four types of objects. A git object is formed by prepending an object header to the object's contents. A git object header consists of: 30 | 31 | " ""\0" 32 | 33 | The git object id is computed by applying a hash to the git object. Currently, the most common hash is sha1, but there is some effort to transition to sha256 over time. 34 | 35 | A gitoid URI identifies a git object independent of any particular git repository. Given a byte array and a gitoid, it is possible to construct the analogous git object header from the gitoid, as gitoid contains the git object type. By prepending the constructed git object header to the byte array and performing the hash indicated in the gitoid, it is possible to determine whether or not the gitoid matches the byte array. 36 | 37 | Interoperability considerations: 38 | Unknown, use with care. 39 | 40 | Security considerations: 41 | The use of URIs does not inherently provide any security. See Section 7 of RFC 3986 for a description of URI and security concerns. No other security considerations have been identified at the time of registration. 42 | -------------------------------------------------------------------------------- /spec/SPEC.md: -------------------------------------------------------------------------------- 1 | # OmniBOR Specification 2 | 3 | | Field | Value | 4 | |:--------|:------| 5 | | Version | 0.2 | 6 | | Status | Draft | 7 | 8 | ## 1. Foreword 9 | 10 | This specification is subject to the Community Specification License 1.0, 11 | available at . 12 | 13 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 14 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are used as described in 15 | [RFC 2119][rfc_2119]. 16 | 17 | Attention is drawn to the possibility that some of the elements of this 18 | document may be the subject of patent rights. No party shall be held 19 | responsible for identifying any or all such patent rights. 20 | 21 | Any trade name used in this document is information given for the convenience 22 | of users and does not constitute an endorsement. 23 | 24 | This document was prepared by the OmniBOR Community. 25 | 26 | Known patent licensing exclusions are available in the specification 27 | repository's `NOTICES.md` file. 28 | 29 | Any feedback or questions on this document should be directed to the 30 | specification's repository, located at . 31 | 32 | THESE MATERIALS ARE PROVIDED "AS IS." The Contributors and Licensees expressly 33 | disclaim any warranties (express, implied, or otherwise), including implied 34 | warranties of merchantability, non-infringement, fitness for a particular 35 | purpose, or title, related to the materials. The entire risk as to 36 | implementing or otherwise using the materials is assumed by the implementer and 37 | user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER 38 | PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR 39 | CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND 40 | WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON 41 | BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR 42 | NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 43 | 44 | ## 2. Introduction 45 | 46 | The OmniBOR standard defines two concepts, which together enable the 47 | consistent, reproducible, and embeddable identification of software 48 | artifacts and the encoding of the exact inputs used to build software 49 | artifacts: Artifact Identifiers and Input Manifests. 50 | 51 | An Artifact Identifier is a content-based identifier of a single input (for 52 | example, a single file) used to build a software artifact. Identifiers are 53 | reproducible, meaning two individuals will always derive the same identifier 54 | for the same input. With these identifiers, we can consistently and precisely 55 | identify any software artifact or its input, for use in forensics, accounting, 56 | and vulnerability management. 57 | 58 | Next, an Input Manifest lists the Artifact Identifier of every input used to 59 | produce an artifact. For example, if an executable is compiled by linking 60 | together a collection of object files, the Artifact Identifier of every object 61 | file would be listed in the Input Manifest for the executable. Input Manifests 62 | can be identified by their own Artifact Identifier. The Artifact ID for the 63 | Input Manifest can be embedded directly into executable files, or can be 64 | provided in a separate file alongside the artifact whose inputs they describe. 65 | 66 | Together, Artifact IDs and Input Manifests form a kind of Merkle Tree, where 67 | changes in the input used to build an artifacts cause a change in the Artifact 68 | ID of that artifact, and on any _other_ artifacts further built with it as 69 | a build input. In effect, any change in the entire build dependency chain for 70 | an artifact becomes detectable with the combination of Artifact IDs and Input 71 | Manifests when the Artifact ID of an artifact's Input Manifest is embedded in 72 | the artifact itself. 73 | 74 | The central purpose in the design of Artifact Identifiers and Input Manifests 75 | is to enable creation of Artifact Dependency Graphs. An Artifact Dependency 76 | Graph is a fine-grained description of all inputs, direct or transitive, used 77 | to produce a software artifact. This graph can be constructed from collections 78 | of Input Manifests for all dependencies used in an artifact's construction. 79 | 80 | Returning to the example of building an executable: the executable's Input 81 | Manifest would list the Artifact Identifier of every object file, and each 82 | object file would have its own Input Manifest listing the Artifact Identifier 83 | of each of their source files. This set of Input Manifests can then be 84 | resolved to produce an overall graph completely describing the inputs which 85 | produced the executable. 86 | 87 | With the Artifact Dependency Graph, consumers of this information could then 88 | exactly identify when two artifacts were produced with exactly identical 89 | inputs, and if inputs vary, could identify the exact inputs which vary and 90 | observe how that affects the entirety of the graph. Changes in inputs anywhere 91 | in the graph would result in new Artifact Identifiers for the changed input 92 | and all inputs derived from it, enabling easy detection of changes in 93 | the graph. 94 | 95 | This Artifact Dependency Graph may also be used to supplement vulnerability 96 | information by precisely identifying affected files or resolving the impacts 97 | of changes to those files across all users of those projects. By leveraging 98 | transparent inclusion of Input Manifests into executable and other formats, 99 | users would also gain the benefits of high precision dependency information 100 | without manually recording or updating those manifests as projects develop over 101 | time. 102 | 103 | ## 3. Scope 104 | 105 | This document specifies: 106 | 107 | - The in-memory format of Artifact Identifiers 108 | - The textual representation of Artifact Identifiers 109 | - The process for constructing Artifact Identifiers 110 | - The textual representation of Input Manifests 111 | - How Input Manifests should be stored in a file system 112 | - How Input Manifests should be embedded into the artifacts whose build 113 | inputs they are describing 114 | - How Input Manifests should be constructed by build tools. 115 | 116 | ## 4. Normative References 117 | 118 | - [GitOID URI][gitoid_uri] 119 | 120 | ## 5. Terms and Definitions 121 | 122 | For the purposes of this document, the following terms and definitions apply. 123 | 124 | ### 5.1. Artifact 125 | 126 | An artifact is any object of interest that can be represented as an array of 127 | bytes. 128 | 129 | ### 5.2. Artifact Equivalency 130 | 131 | Two artifacts are equivalent if and only if their binary representations are 132 | equal. 133 | 134 | ### 5.3. Build Tools 135 | 136 | A build tool is anything which reads one or more input artifacts and writes 137 | one or more output artifacts. Examples of build tools include: 138 | 139 | - __Compilers:__ 140 | - `llvm-clang` 141 | - `gcc` 142 | - `javac` 143 | - `rustc` 144 | - `go` 145 | - __Linkers:__ 146 | - `llvm-lld` 147 | - `binutils-ld` 148 | - __Runtimes:__ 149 | - Java JVM 150 | - Node.js 151 | - Python interpreter 152 | - __Code Generators:__ 153 | - `patch` 154 | 155 | ## 6. Specifications 156 | 157 | ### 6.1. Artifact Identifier 158 | 159 | It MUST be possible to identify each artifact with an Artifact Identifier with 160 | the following characteristics: 161 | 162 | - __Reproducible__: Independent parties, presented with equivalent artifacts, 163 | derive the same Artifact Identifier. 164 | - __Unique__: Non-equivalent artifacts have distinct Identifiers. 165 | - __Immutable__: An identified artifact cannot be modified without also 166 | changing its Identifier. 167 | 168 | Artifact Identifier can be shortened to Artifact ID. 169 | 170 | Because two artifacts are equivalent if and only if their binary 171 | representations are equal, meaning that their length in bytes is equal, and 172 | that the values of all bytes of the artifacts are equal. 173 | 174 | ### 6.2. Artifact Identifier Types 175 | 176 | The majority of source code artifacts are already stored in Git and 177 | indexed by their Git Object Identifiers ("GitOIDs") as Git objects of type 178 | "blob". 179 | 180 | For this reason, OmniBOR has chosen to use the "GitOid" of an Artifact as 181 | its Artifact Identifier. 182 | 183 | Git currently supports two varieties of GitOIDs. One is based on SHA-1 and is 184 | in common use. The other is based on SHA-256 and has been slow to garner 185 | adoption. 186 | 187 | Git's use of SHA-1 is additionally complicated by the fact that Git actually 188 | uses a variant of SHA-1 in newer versions, called SHA-1CD (where "CD" stands 189 | for "collision detection") which tries to detect attempts to engineer 190 | purposeful hash collisions in SHA-1 and subverts them by modifying the 191 | operation of the hash algorithm in those cases. Git calls this "SHA-1" and does 192 | not frequently distinguish use of the two similar but not equivalent hash 193 | algorithms. 194 | 195 | The [GitOID URI spec][gitoid_uri] uses different prefixes, 196 | `gitoid:blob:sha1` or `gitoid:blob:sha256`, to distinguish which algorithm is 197 | being used for computing the GitOID of an artifact, subject to the knowledge 198 | that `gitoid:blob:sha1` may describe either SHA-1 or SHA-1CD depending on the 199 | version of Git being used. 200 | 201 | This document adopts the GitOID URI prefixes to distinguish Artifact Identifier 202 | Types. This approach is anticipated to extend gracefully as Git adopts new hash 203 | types in the future. 204 | 205 | Given the challenges with SHA-1 including: 206 | 207 | - Its weakness as a hash algorithm today, with some attacks already being 208 | known publicly which permit collisions in some contexts, 209 | - The fact that Git itself is expending effort to transition away from the use 210 | of SHA-1 and toward SHA-256, 211 | - A concern that SHA-1 could in the next five years be subject to orders to 212 | transition away by some world governments, 213 | 214 | We have decided to only permit the use of SHA-256 as a hash algorithm for 215 | Artifact Identifiers for OmniBOR. 216 | 217 | We reserve the right to extend this list to support additional hash algorithms 218 | in the future, for example if SHA-256 is determined to be broken by future 219 | computing capabilities. 220 | 221 | All subsequent references to Artifact Identifier types in this document should 222 | be interpreted to mean the list: 223 | 224 | - `gitoid:blob:sha256` 225 | 226 | ### 6.3. Input Manifest 227 | 228 | An Input Manifest for an artifact enumerates the inputs to the build tool that 229 | produced the artifact. 230 | 231 | A given Input Manifest utilizes precisely one Artifact Identifier Type. 232 | 233 | #### 6.3.1. Input Manifest Header 234 | 235 | In order to distinguish the type of identifier used in the Input Manifest, 236 | it begins with a single newline-terminated header line: 237 | 238 | ``` 239 | ${Artifact Identifier Type URI prefix}\n 240 | ``` 241 | 242 | For example: 243 | 244 | ``` 245 | gitoid:blob:sha256\n 246 | ``` 247 | 248 | All identifiers in a Input Manifest MUST be of the Artifact Identifier 249 | Type declared in the header. 250 | 251 | #### 6.3.2. Input Manifest Records 252 | 253 | The Input Manifest after the header consists of a list of newline terminated 254 | input records. 255 | 256 | Each input record consists of: 257 | 258 | - The Artifact ID of the input artifact 259 | - Optionally, the Artifact ID of the Input Manifest for the input artifact 260 | 261 | An Input Manifest record for an artifact for which no Input Manifest 262 | is known is represented as: 263 | 264 | ``` 265 | ${artifact identifier of the input artifact}\n 266 | ``` 267 | 268 | An Input Manifest record for an artifact: 269 | 270 | ``` 271 | ${artifact identifier of the input artifact}⎵manifest⎵${artifact identifier of the input manifest for the input artifact}\n 272 | ``` 273 | 274 | `⎵` above refers to the ASCII space character (0x20). 275 | 276 | Artifact Identifiers in Input Manifests should be represented as a string in 277 | lowercase hexadecimal. For example: 278 | 279 | ``` 280 | 514516097a2f95c893f2a9685bcecfb85b7598e6 281 | ``` 282 | 283 | The input artifact records MUST be written to the Input Manifest in lexical 284 | order. This is defined by sorting primarily by the input type, and secondarily 285 | by the Artifact ID of the input artifact. 286 | 287 | The Artifact Identifier for the input artifact and for the input artifact's 288 | Input Manifest MUST both be of the Artifact Identifier Type declared in the 289 | Input Manifest header. 290 | 291 | #### 6.3.3. Input Manifest Character Encoding 292 | 293 | All characters in an Input Manifest are encoded in ASCII. Please note: all '\n' 294 | MUST be encoded as '\n' characters, _not_ the line delimiter of the platform. 295 | This is necessary because the Input Manifest will be hashed to produce its 296 | Artifact Identifier, and these Artifact Identifiers MUST be consistent 297 | regardless of the platform on which the Input Manifest generation is performed. 298 | 299 | #### 6.3.4. Input Manifest Embedding 300 | 301 | Each build tool SHOULD embed into the output artifact a deterministically 302 | ordered list of Artifact IDs for the Input Manifest for each mandatory Artifact 303 | Identifier Type in a manner: 304 | 305 | 1. Appropriate to the type of artifact 306 | 2. Generally agreed upon for that artifact 307 | 308 | If embedding is not possible — for example, if the format of the output 309 | artifact does not permit a method to embed additional information without 310 | breaking the functionality of that artifact — then embedding SHOULD be 311 | skipped. 312 | 313 | #### 6.3.5. Input Manifest Construction 314 | 315 | A build tool creating an output artifact MUST compute an Input Manifest of 316 | each mandatory Artifact Identifier Type. 317 | 318 | For each input artifact the build tool MUST: 319 | 320 | 1. Compute the artifact identifier of the input: `${artifact identifier}` 321 | 2. Examine the input for an embedded Artifact ID for an Input Manifest: 322 | `${input manifest artifact id}` 323 | 324 | The build tool MUST persist an Input Manifest using the 325 | `${artifact identifier}` and `${input manifest artifact id}` for each input. 326 | 327 | #### 6.3.6. Input Manifest Example 328 | 329 | ``` 330 | gitoid:blob:sha256 331 | 09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 332 | 230f3515d1306690815bd9c3da0d15d8b6fcf43894d17100eb44b6d329a92f61 333 | 2f4a51b16b76bbc87c4c27af8ae062b1b50b280f1ab78e3eec155334588dc88e manifest 4f3a822f776412c049dda53c3277bf2225b51b805ce8a99222af23a7d9f55636 334 | c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4 335 | f47ffb3518f236eea6525fd29f057ddd5cda1bb803ccc662e6bc5925afd1e4af 336 | ``` 337 | 338 | ## 7. Storing Input Manifests 339 | 340 | This section documents known methods of persisting Input Manifests to 341 | various stores. 342 | 343 | If a build tool persists an Input Manifest to its local filesystem, 344 | the build tool should write out the Input Manifest to 345 | `${OMNIBOR_DIR}/manifests/${Artifact Identifier Type URI prefix with ':' replaced by '_'}/${Input Manifest Artifact ID:0:2}/${Input Manifest Artifact ID:2:}` 346 | where `${Input Manifest Artifact ID}` is the Artifact ID of the Input 347 | Manifest in lowercase hexadecimal with leading zeros NOT suppressed. 348 | 349 | Example: 350 | 351 | If `OMNIBOR_DIR=.omnibor` then the Input Manifest with Artifact ID 352 | `gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772` 353 | would be stored in: 354 | 355 | ``` 356 | .omnibor/manifests/gitoid_blob_sha256/09/c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 357 | ``` 358 | 359 | ### 7.1. Selection of Storage Location 360 | 361 | The storage location for Input Manifests MAY be set by the following methods, 362 | listed in order of increasing precedence: 363 | 364 | 1. A non-empty env variable named `OMNIBOR_DIR` 365 | 2. A build tool specific flag 366 | 367 | The absence of specification of a storage location via either the build tool 368 | specific flag or `OMNIBOR_DIR` variable MAY be taken as a signal to skip 369 | generation of Input Manifests by build tools. 370 | 371 | ## 8. Embedding Artifact IDs in ELF Files 372 | 373 | This section contains a method of embedding Artifact IDs for Input Manifests 374 | into ELF files. 375 | 376 | If an ELF artifact contains an embedded Artifact ID for an Input Manifest, 377 | then implementations MUST conform to the format specified in this document. 378 | 379 | Artifact IDs for Input Manifests MUST be persisted by build tools when they 380 | build an artifact and produce an Input Manifest for that artifact. 381 | 382 | When persisting Artifact IDs for Input Manifests into an ELF object or an ELF 383 | executable, the build tool MUST create a [section][elf_section] named 384 | `.note.omnibor` and place the Artifact IDs in the descriptor field of the note 385 | entry. 386 | 387 | This section MUST be of type `SHT_NOTE` and MUST have the attribute 388 | `SHF_ALLOC`. Multiple Note entries MAY be created, one for each Artifact 389 | Identifier Type used. 390 | 391 | Each note entry MUST contain the following fields in the same order as given 392 | below: 393 | 394 | 1. `namesz` (4 bytes): This field MUST be set to a value of `8`, the length of 395 | the 'owner' field `OMNIBOR\0` in bytes. 396 | 2. `descz` (4 bytes): This field MUST contain the length of the Artifact ID for 397 | the Input Manifest in bytes, including a byte for the null terminator. 398 | 3. `type` (4 bytes): This field MUST contain the value associated with one of 399 | the reserved Artifact Identifier types. The values for the reserved types 400 | are in the range of `0x00000000` to `0x7fffffff`. Permissible types with 401 | reserved values are: 402 | - `NT_GITOID_BLOB_SHA256` is `0x1` 403 | 4. `owner` (8 bytes): This field MUST contain the string `OMNIBOR\0`, padded 404 | to 8 bytes. 405 | 5. `descriptor`: This field MUST contain the Artifact IDs for the Input 406 | Manifests as raw bytes. The length of this field is the same as the value 407 | in the `descz` field. 408 | 409 | When recording multiple Artifact IDs for Input Manifests in the note section, 410 | 411 | 1. There MUST be only one note entry for each Artifact Identifier Type. 412 | 2. The note entries MUST be in ascending order of Artifact Identifier Type. 413 | 414 | Build tools MUST generate all Artifact Identifier Types, currently only SHA-256. 415 | 416 | ## 9. Embedding Artifact IDs in Text Files 417 | 418 | This section contains a method of embedding an Artifact ID for an Input 419 | Manifest into source code files. 420 | 421 | Most source code files are hand coded by humans. Some however are generated 422 | from other input(s) by a build tool. 423 | 424 | A build tool outputing a source code file may embed the Artifact ID for the 425 | Input Manifest for the output source code file into the output source code 426 | file by adding a comment line containing a string of the form: 427 | 428 | ``` 429 | OmniBOR-Input-Manifests: [ ${comma separated list of Artifact ID URIs for Input Manifests} ] 430 | ``` 431 | 432 | For a file with C commenting semantics (like C, C++, Java, Go, etc) a concrete 433 | example might be: 434 | 435 | ``` 436 | // OmniBOR-Input-Manifests: [ gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ] 437 | ``` 438 | 439 | For a file with shell commenting semantics (like a shell script, Python, etc) a 440 | concrete example might be: 441 | 442 | ``` 443 | # OmniBOR-Input-Manifests: [ gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ] 444 | ``` 445 | 446 | When interpretting an OmniBOR-Input-Manifest-ID comment line a reader should 447 | ignore any leading and trailing spaces around `[` or `]` or `,`. 448 | 449 | ### 9.1. Placement of Embedded Artifact IDs 450 | 451 | The `OmniBOR-Input-Manifest` comment line should be placed as the last line in 452 | the source code file. The `OmniBOR-Input-Manifest` comment line should be 453 | preceded by a blank line to ensure it is not interpretted as part of another 454 | comment block. 455 | 456 | A tool reading the source code file should interpret the last 457 | `OmniBOR-Input-Manifest` comment line it encounters in the file as being the 458 | Artifact ID of the Input Manifest, and ignore previous comment lines in the 459 | file which may contain additional Artifact IDs. 460 | 461 | Example: 462 | 463 | If the input source code file begins with: 464 | 465 | ```go 466 | // Code generated by stringer DO NOT EDIT. 467 | 468 | import ( 469 | "fmt" 470 | ) 471 | ... 472 | ``` 473 | 474 | The output source code file should look like: 475 | ```go 476 | // Code generated by stringer DO NOT EDIT. 477 | 478 | import ( 479 | "fmt" 480 | ) 481 | ... 482 | 483 | // OmniBOR-Input-Manifest: [ gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ] 484 | ``` 485 | 486 | If the input source code file begins with: 487 | 488 | ```c 489 | /* 490 | * Copyright 2023 Yoyodyne Inc 491 | * SPDX-License-Identifier: 492 | */ 493 | 494 | #include 495 | int main() { 496 | // printf() displays the string inside quotation 497 | printf("Hello, World!"); 498 | return 0; 499 | } 500 | ``` 501 | 502 | The output source code file should look like: 503 | 504 | ```c 505 | /* 506 | * Copyright 2023 Yoyodyne Inc 507 | * SPDX-License-Identifier: 508 | */ 509 | 510 | #include 511 | int main() { 512 | // printf() displays the string inside quotation 513 | printf("Hello, World!"); 514 | return 0; 515 | } 516 | 517 | // OmniBOR-Input-Manifest: [ gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ] 518 | ``` 519 | 520 | ### 9.2. Modifying Existing Text Files 521 | 522 | Many source code generation tools, like `patch`, specifically mutate an 523 | existing input source code file which may contain an existing 524 | `OmniBOR-Input-Manifest` comment. In such circumstances the tool SHOULD 525 | either 526 | 527 | 1. Replace an existing `OmniBOR-Input-Manifest` comment if found 528 | 2. Insert the `OmniBOR-Input-Manifest` normally, which will cause it to 529 | be placed _after_ the existing `OmniBOR-Input-Manifest` comment line. 530 | 531 | [elf_section]: https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA.junk/sections.html 532 | [rfc_2119]: https://tools.ietf.org/html/rfc2119 533 | [gitoid_uri]: https://www.iana.org/assignments/uri-schemes/prov/gitoid 534 | --------------------------------------------------------------------------------