Commit 975a0146 authored by taco@waag.org's avatar taco@waag.org
Browse files

v0 doc

parent 7bc10f87
## PoP HTML Protocol v0 -- draft
### Proof of provenance For HTML fragments
In version zero we describe signing and verification of fragments of HTML documents; more specifically, HTML 'articles' or 'blogs' or documents of similar nature. This is limited in scope, but should provide valuable insight and experience. Typically, such a document has a **title**, an **author**, an **abstract** and a **body** and **images**. These may not all be present. We'll call them *categories* in the rest of this document. Irrespective of their actual meaning, these categories exist because they are labelled as such (under the responsibility of the author or editor, by the cms plugin or otherwise) prior to signing.
We describe the signing and verification of **text data** using the functionality that the IRMA ecosystem offers. The signatures are **attribute-based**; the protocol does not prescribe the attributes that are used for signing. A minimal use-case is one where the document is signed with an email address of the organisation of employment. The "pbdf.sidn-pbdf.email.email" attribute is used as an example.
When images are present, a (perceptual) blockhash of the image data are expected to be calculated and signed.
For audio and video, links to the media could be part of the text to be signed, using a canonical URI to the asset at (a proxy at) the organisation that does the signing. For now this is out of scope.
For simplicity's sake we suggest a separate signature for each of the fragments, of course depending on the presence of the categories. Another reason for decision that each fragment can be shared individually. And a third reason for seperate signing is that we can markup each fragment differently in the 'provenance view'.
We intend to explore the feasibility of signing complex elements by grouping together fragments later in the project.
#### PoP Data attributes
Fragments are annotated as being a pop-fragment by annotating the HTML tag with a data-attribute.
We have come up with the following naming scheme:
data-pop-<VERSION>-<ID>-<CATEGORY>
* VERSION indicates the protocol version for example 'v0'.
* ID is a reserved token that we foresee to be used as an id in version management of a fragment so that we will be able to track changes to the content. Since this will be worked out later, in version 0 this is always the literal string 'id'.
* CATEGORY indicates the fragment type. (title,abstract,author,body,img)
To be complete, all supported data attributes for v0 literally are:
* data-pop-v0-id-title * data-pop-v0-id-abstract * data-pop-v0-id-author
* data-pop-v0-id-body
* data-pop-v0-id-img
#### Normalisation
It is imperative that signing and verification of the signature consider the exact same text content, down to a single bit. In this context, it is also good to realize that (in an HTML document) **css manipulation** may very well change the meaning of the content, if only through the visibility status of text blocks or the text color or emphasis.
We have decided to address this problem by designing a special provenance view that shows only the text content that was the input of the verification function to the reader. In version 0 the normalisation function works by using the browsers built-in 'textContent' function to strip the fragment all of the original CSS.
#### Signing content
In pop v0 we follow these steps for signing each separate fragment:
- Provide the normalized text or an image hash as message to a IRMA signing session.
- Parse the response from IRMA, and take only the signature object. We don't want to encode the disclosed attributes clear text, instead we rely entirely on the validation function to retrieve this information.
- Strip the message from the signature object. (Including it would allow to create fake positive validation results)
- Base64 encode the signature object as the signature string. (So that a fragment can be easily annotated with one value)
- Put the signature string as a value in a pop data attribute (e.g. data-pop-v0-id-body or data-pop-v0-id-img)
A javascript function (pop_sign) can be found [here](https://gitlab.waag.org/code/proof_of_provenance/-/blob/main/src/signing-frontend/pop.js) .
#### Verification
In pop v0 we follow these steps for validating each pop annotated fragment:
- Base64 decode the signature string to get the signature object
- Add a normalized version of the fragment content as message to the signature object
- Call the IRMA Validation function with the signature object as an argument
- Display the disclosed attributes and verification result from the validation function
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment