Merge pull request #15 from ForkbombEu/signature-docs

Signature and Multisignature docs
ForkbombEu · May 24, 2024 · 21ee0ec · 21ee0ec
2 parents 248fa0e + c9bec41
commit 21ee0ec
Show file tree

Hide file tree

Showing 23 changed files with 236 additions and 0 deletions.
diff --git a/docs/guides/5_signature/1_signature.md b/docs/guides/5_signature/1_signature.md
@@ -0,0 +1,132 @@
+# Signature
+
+The Signature features allow to you sign documents and files, according to the standards *PaDES, CaDES, JaDES or XaDES* using your secrets keys and a certificate. 
+
+You can as well verify signatures from 3rd parties. 
+
+## Supported types 
+
+The standard supported (PaDES/CaDES/JaDES/XaDES) are compliant with the [eIDAS regulation](https://en.wikipedia.org/wiki/EIDAS) and are the ones most widely accepted in the industry. 
+
+
+## Signature flow 
+
+The signature occurs in the Webapp, specifically **in the browser**: this implies that your secret keys are only store and used in the browser and never  communicated to anyone, according to the *privacy-by-design* and *end-to-encryption principles*. 
+
+The signature produced in the Webapp is packed into a JSON object and communicated to a service we run in backend using the open source [Digital Signing Service](https://ec.europa.eu/digital-building-blocks/DSS/webapp-demo/doc/dss-documentation.html) software, the official software implemented and maintained by the European Commission, for digital signatures. The software is open source, you can find the source code on [https://github.com/esig/dss/](https://github.com/esig/dss/).
+
+> [!IMPORTANT] Important!
+> The secret key to sign documents is stored and used only in the browser (thus the signature works offline!), are never communicated to anyone and from the signature it's mathematically impossible to recreate the secret key. 
+
+# Import a secret key and certificate 
+
+You probably want to start by importing a secret key and and an X.509 certificate. To do that press on the **Certificates** button on the sidebar:
+
+![Signature1](../images/signature/SS1.png)
+
+Then press the button **Add a Key-Certificate Pair** in top right of the page, a modal window will pop-up, fill it with the info about your key
+
+![Signature1](../images/signature/SS3.png)
+
+As a result you should see your key/certificate appearing in the list. Under **Algorithm** you see the type of signature that can be performed with each given pair of key/certificate. Currently we support: 
+
+- **Elliptic curve signatures**
+  - ECDSA on secp256r1 (also known as P-256 or NIST-256)
+  - EdDSA on Ed25519
+- **RSA**
+  - RSASSA-PKCS1-v1_5
+  - RSA-PSS
+
+In the example below, we added an RSA key/certificate: 
+
+![Signature1](../images/signature/SS4c.png)
+
+
+## Create a certificate (for test purposes)
+
+if you want to test the software, you could create a secret key, along with a self-signed X.509 certificate.
+
+
+1) Create a secret key, in this case this will allow you to produce an ECDSA signature on the secp256r1 curve, with the following line
+
+```bash
+openssl ecparam -out ec_key.pem -name secp256r1 -genkey 
+```
+
+The output should look like: 
+
+```
+-----BEGIN EC PARAMETERS-----
+BggqhkjOPQMBBw==
+-----END EC PARAMETERS-----
+-----BEGIN EC PRIVATE KEY-----
+MHcCAQEEIJwGudHNDpOGGubs0Ta7aBY+0rZJnsaHwwGJ9hWg+E0soAoGCCqGSM49
+AwEHoUQDQgAEFdjev32vpXom5IJ8hOFb2IuQrJvCF3TAV2Ix9LM83VAnGS93uejk
+A7JKERWZwUWxFx7W+n+G/2xox1X1Z5Bpjw==
+-----END EC PRIVATE KEY-----
+```
+
+2) Then create a self-signed X.509 certificate with the link:
+
+```bash
+openssl req -new -key ec_key.pem -x509 -nodes -days 365 -out cert.pem
+```
+
+The output (X.509 certificate) should look like: 
+
+```
+-----BEGIN CERTIFICATE-----
+MIICFjCCAb2gAwIBAgIUM4YXzoETub8fc1ITNG5YmNBjWIQwCgYIKoZIzj0EAwIw
+YTELMAkGA1UEBhMCREsxEzARBgNVBAgMClNvbWUtU3RhdGUxDDAKBgNVBAcMA0NQ
+SDENMAsGA1UECgwETm9uZTEgMB4GCSqGSIb3DQEJARYRYW5kcmVhQGFuZHJlYS5v
+cmcwHhcNMjQwNTIzMTEzNzMxWhcNMjUwNTIzMTEzNzMxWjBhMQswCQYDVQQGEwJE
+SzETMBEGA1UECAwKU29tZS1TdGF0ZTEMMAoGA1UEBwwDQ1BIMQ0wCwYDVQQKDARO
+b25lMSAwHgYJKoZIhvcNAQkBFhFhbmRyZWFAYW5kcmVhLm9yZzBZMBMGByqGSM49
+AgEGCCqGSM49AwEHA0IABBXY3r99r6V6JuSCfIThW9iLkKybwhd0wFdiMfSzPN1Q
+Jxkvd7no5AOyShEVmcFFsRce1vp/hv9saMdV9WeQaY+jUzBRMB0GA1UdDgQWBBQc
+9IznPl5DHE/8ejCMktZVVD49IDAfBgNVHSMEGDAWgBQc9IznPl5DHE/8ejCMktZV
+VD49IDAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIFq3/SXWEsD2
+Gz8xXxMhdLLx/NXdnboflIAosgiKNqQXAiBfR45nGPTbH+0O4BydHi+WToTFU/qC
+ZFDPK7MDIxklfQ==
+-----END CERTIFICATE-----
+```
+
+
+
+## Sign document 
+
+After you have added a key/certificate, you're ready to sign your first document, so click on **My Signatures** on the sidebar, you should see: 
+
+![Signature1](../images/signature/SS5a.png)
+
+
+1) Click on the *New Signature* button on the top right and select:
+
+- Fill the *Title*, the *Description* 
+- Click on *Choose File* load document in the application. 
+- Under *Type* select the format of the signature you want to receive, between *PaDES*, *CaDES*, *JaDES* or *XaDES*. The type of file that you can sign will typically be a PDF, but depending on the signature format you are able sign also other file formats.
+- Then select the *Certificate* you want to use (the correspondent secret key will be selected
+
+
+
+![Signature1](../images/signature/SS5b.png)
+
+
+If all went well, you will see your signature:
+
+![Signature1](../images/signature/SS6.png)
+
+
+From there, if you click on *Preview*, you can open the signed file: 
+
+
+![Signature1](../images/signature/SS7.png)
+
+
+And can as well *Verify the signature* from there: 
+
+
+![Signature1](../images/signature/SS8.png)
+
+
+
diff --git a/docs/guides/5_signature/2_multisignature.md b/docs/guides/5_signature/2_multisignature.md
@@ -0,0 +1,91 @@
+# Multisignature Flow
+
+The Multisignature Flow is a an implementation of the cryptographic flow described in the [Reflow Multisignature](https://arxiv.org/abs/2105.14527) paper. This allows users to create a JSON object to be signed, invite users to sign it, set a deadline and wait for their signatures. The signature process uses the homomorphic capabilities of the BLS 12-381 curve - see [here](https://hackmd.io/@benjaminion/bls12-381) if you're curious. The responses are anonymous and the output is a cryptographical object verifiable by anyone.
+
+## Create a Multisignature
+
+Click on **Multisignatures** in the sidebar to get started: 
+
+![Signature1](../images/multisignature/MM1.png)
+
+The first page is a brieg introducton giving some basic concepts. See below what a *Coconut Issuer* is and what it's used for. 
+
+![Signature1](../images/multisignature/MM2.png)
+
+Click on **Start Setup** to get started, here you'll have to fill: 
+
+- **Name**: the name of this Multisignature flow, the name will appear in your Multisignature page and those you invite as well.
+- **Credential Issuer**: (Coconut Issuer) this is treated in a subchapter below. For now, just select the Coconut issuer we offer from the list
+- **Reflow Seal**: this is the data that you're asking to sign (see the subchapter below). In this Reflow Seal, we have 3 individuals (*Spacetest*, *nenno* and *GI Hefe*) agreeing on their respective yearly designated driver quota.   
+- **Settings**: here you can specify the expiry of the Multisignature, meaning that the invitees will only be allowed to sign until the deadline
+
+The setup page looks like: 
+
+![Signature1](../images/multisignature/MM3.png)
+
+
+
+
+### The *Reflow Seal* and the signing/verification algorithm
+
+A **Reflow Seal** (as in the paper) is the data that the signees have to agree to sign. In our first implementation it's a JSON object and it can easily refer to a document, the content of a URL or something stored in a database or blockchain. 
+
+In fact, that is an oversimplifycation of what a Reflow Seal is, a slightly more encompassing explaination is: the Reflow Seal is a cryptographic object containing the JSON above, along with the public keys and the signatures (if they choose to sign) of the signees. 
+
+If you're not satisfied with this and are ready to deep-dive into the magic world of cryptography, read the text box below. 
+
+
+> [!IMPORTANT] Warning: hard-core cryptography ahead 🤯
+> In the cryptographic flow happening under the hood after the setup, The Reflow Seal is hashed, then each signee (that chooses to sign) will produce a [BLS 12-381 signature](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-04.txt) that will be [homomorphically aggregated](https://eprint.iacr.org/2018/483) to the hash of the Reflow Seal. We did in fact omit an important step: while the Reflow Seal was being hashed, the public keys of the signees have been *homomorphically aggregated*. 
+
+> After all the signatures have been collected and aggregated, a *Miller Loop* ( read a somewhat easy explanation [here](https://crypto.stackexchange.com/questions/61930/simple-explanation-of-millers-algorithm)) is performed to **verify if the aggregated signatures match the aggregated public keys**: if they do, the Multisignature is successful. This is the core of the algorithm, which enables anonymous signatures and was originally designed for blockchain applications. We did actually omit one more step, the Coconut credential issuance, which we cover below. 
+
+
+
+
+### The Coconut Issuer
+
+The [Coconut Paper](https://arxiv.org/abs/1802.07344) defines a zero knowledge proof flow for credential issuance, with plenty of bells and whistles. In our implementation, the Coconut Issuer produces a *Coconut credential* for each of the users invited to sing. 
+
+> [!IMPORTANT] Warning: more hard-core cryptography ahead 🤯🤯
+> Using a Coconut credential has the purpose of  making sure that the ones signing the Reflow Seal, are the ones who have been invited to sign, in order to overcoming the [rogue public key attack](https://eprint.iacr.org/2021/377.pdf) while keeping the signature anonymous and cryptographically verifiable.
+
+
+
+
+
+## Invite the users 
+
+When done with the steps above, click on **Confirm Content** on the top right of the page to land on the **Invite Users** page, that you can use to invite users base on their username or email (if they chose to have the email as public).
+
+![Signature1](../images/multisignature/MM4.png)
+
+We chose to invite the users *Spacetest*, *nenno* and *GI Hefe* which are the people who will be sharing the car, according to the Reflow Seal. 
+
+**Note**: The choice to include the signees' names in the Reflow Seal was aimed exclusively for educational purposes: you can write whatever you want in the Reflow Seal and invite whoever you want to sign it. 
+
+The result should be something like this: 
+
+![Signature1](../images/multisignature/MM5.png)
+
+## Finalize
+
+This page shows you a recap of the Multisignature flow you're working on: at this stage you can still change things, once you click on *Confirm and Sign* in the top right of the page, the cryptographic material will be produced and you won't be able to make changes after that. 
+
+![Signature1](../images/multisignature/MM6.png)
+
+
+
+
+## Wait for signatures
+
+After you clicked on *Confirm and Sign*, the Multisignature is ready to be signed and a **notification is sent per email to the signees**. You'll see it here: 
+
+![Signature1](../images/multisignature/MM7.png)
+
+## Check status
+
+If you click on "View" on the Multisignature, you can see the status, including if everyone has signed or someone is missing.
+
+
+![Signature1](../images/multisignature/MM8.png)
diff --git a/docs/guides/5_signature/index.md b/docs/guides/5_signature/index.md
@@ -0,0 +1,13 @@
+# 🖊️ Signatures 
+
+The application can produce different types of signatures, using different technologies for different purposes. 
+
+
+## Document Signature
+
+The Signature features allow to you sign documents and files, according to the standards *PaDES, CaDES, JaDES or XaDES* using your secrets keys and a certificate. 
+
+
+## Multisignature Flow
+
+The Multisignature Flow is a an implementation of the cryptographic flow described in the [Reflow Multisignature](https://arxiv.org/abs/2105.14527) paper. This allows users to create a JSON object to be signed, invite users to sign it, set a deadline and wait for their signatures. The signature process uses the homomorphic capabilities of the BLS 12-381 curve - see [here](https://hackmd.io/@benjaminion/bls12-381) if you're curious. The responses are anonymous and the output is a cryptographical object verifiable by anyone.
diff --git a/docs/guides/5_components/index.md → docs/guides/6_components/index.md b/docs/guides/5_components/index.md → docs/guides/6_components/index.md
diff --git a/docs/guides/5_components/keypairoom.md → docs/guides/6_components/keypairoom.md b/docs/guides/5_components/keypairoom.md → docs/guides/6_components/keypairoom.md
diff --git a/docs/guides/images/multisignature/MM1.png b/docs/guides/images/multisignature/MM1.png
diff --git a/docs/guides/images/multisignature/MM2.png b/docs/guides/images/multisignature/MM2.png
diff --git a/docs/guides/images/multisignature/MM3.png b/docs/guides/images/multisignature/MM3.png
diff --git a/docs/guides/images/multisignature/MM4.png b/docs/guides/images/multisignature/MM4.png
diff --git a/docs/guides/images/multisignature/MM5.png b/docs/guides/images/multisignature/MM5.png
diff --git a/docs/guides/images/multisignature/MM6.png b/docs/guides/images/multisignature/MM6.png
diff --git a/docs/guides/images/multisignature/MM7.png b/docs/guides/images/multisignature/MM7.png
diff --git a/docs/guides/images/multisignature/MM8.png b/docs/guides/images/multisignature/MM8.png
diff --git a/docs/guides/images/signature/SS1.png b/docs/guides/images/signature/SS1.png
diff --git a/docs/guides/images/signature/SS2.png b/docs/guides/images/signature/SS2.png
diff --git a/docs/guides/images/signature/SS3.png b/docs/guides/images/signature/SS3.png
diff --git a/docs/guides/images/signature/SS4.png b/docs/guides/images/signature/SS4.png
diff --git a/docs/guides/images/signature/SS4c.png b/docs/guides/images/signature/SS4c.png
diff --git a/docs/guides/images/signature/SS5a.png b/docs/guides/images/signature/SS5a.png
diff --git a/docs/guides/images/signature/SS5b.png b/docs/guides/images/signature/SS5b.png
diff --git a/docs/guides/images/signature/SS6.png b/docs/guides/images/signature/SS6.png
diff --git a/docs/guides/images/signature/SS7.png b/docs/guides/images/signature/SS7.png
diff --git a/docs/guides/images/signature/SS8.png b/docs/guides/images/signature/SS8.png