diff --git a/docs/guides/5_signature/1_signature.md b/docs/guides/5_signature/1_signature.md new file mode 100755 index 0000000..86519af --- /dev/null +++ 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 new file mode 100755 index 0000000..a96595e --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/guides/5_signature/index.md b/docs/guides/5_signature/index.md new file mode 100755 index 0000000..b9f5568 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/guides/5_components/index.md b/docs/guides/6_components/index.md similarity index 100% rename from docs/guides/5_components/index.md rename to docs/guides/6_components/index.md diff --git a/docs/guides/5_components/keypairoom.md b/docs/guides/6_components/keypairoom.md similarity index 100% rename from docs/guides/5_components/keypairoom.md rename to docs/guides/6_components/keypairoom.md diff --git a/docs/guides/6_signature/1_signature.md b/docs/guides/6_signature/1_signature.md deleted file mode 100755 index 4b5958b..0000000 --- a/docs/guides/6_signature/1_signature.md +++ /dev/null @@ -1,48 +0,0 @@ -# Intro - -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 used locally 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 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. - -# Sign document - -1) Click on the *New Signature* button on the top right and select what format of signature you would like to have (PaDES/CaDES/JaDES/XaDES) - -![Signature1](../images/signature/S1.png) - - - -2) Fill the *Title*, the *Description* optionally and upload a PDF. - -![Signature1](../images/signature/S2.png) - -3) If the signature succeded - -![Signature1](../images/signature/S3.png) - - - - -# Verify signature - - -![Signature1](../images/signature/S4.png) - -![Signature1](../images/signature/S5.png) - - -![Signature6](../images/signature/S6.png) \ No newline at end of file diff --git a/docs/guides/6_signature/2_multisignature.md b/docs/guides/6_signature/2_multisignature.md deleted file mode 100755 index c6b9463..0000000 --- a/docs/guides/6_signature/2_multisignature.md +++ /dev/null @@ -1,5 +0,0 @@ -# Multisignature Flow - -After you logged in the Verifier, you will be presented with a list **Verification Flows**, you can run. The flows you see depend on the organization(s) you are member of. - -To start a **Verification Flow** just click the one you want to start from the list: a QR code with a session ID should appear in the next page. \ No newline at end of file diff --git a/docs/guides/6_signature/index.md b/docs/guides/6_signature/index.md deleted file mode 100755 index 7b73871..0000000 --- a/docs/guides/6_signature/index.md +++ /dev/null @@ -1,29 +0,0 @@ -# 📑 Concepts/Components - -**Issuance flow**: TBW - -**Verification flow**: TBW - -**Templates**: TBW - -**Decentralized Identifier (DID)**: A globally unique, self-sovereign identifier that enables individuals and entities to have control over their digital identities without relying on centralized authorities. - -**EUDI-ARF**: Acronym for "The European Digital Identity Wallet Architecture and Reference Framework," a technical core of the eIDAS 2.0 regulation that outlines standards for digital identity wallets. - -**eIDAS 2.0 Regulation**: The updated version of the eIDAS (electronic Identification, Authentication and Trust Services) regulation that sets standards for electronic identification and trusted services within the European Union. - -**Self-Sovereign Identity (SSI)**: A decentralized identity model that enables individuals to have full control over their digital identity and personal data. SSI allows users to manage and share verifiable credentials without the need for intermediaries. - -**Verifiable Credentials (VC)**: Digital attestations that enable the issuance and verification of claims about a subject's identity, attributes, or qualifications. - -**Wallet**: In the context of DidRoom, a software application or platform that allows users to manage their digital identities, store cryptographic keys, create and manage DIDs, and interact with blockchain networks and verifiable credentials. - -**Zero-Knowledge Proofs**: Cryptographic methods that allow a party to prove knowledge of a certain value or statement without revealing the actual value itself. Zero-knowledge proofs enhance privacy and security by demonstrating knowledge without disclosing sensitive information. - -**W3C-DID**: Abbreviation for "W3C Decentralized Identifier," a standard by the World Wide Web Consortium (W3C) for creating, managing, and resolving decentralized identifiers. - -**W3C-VC**: Abbreviation for "W3C Verifiable Credentials," a standard by the World Wide Web Consortium (W3C) for creating and verifying digital credentials in a secure and interoperable manner. - -**Zenroom**: A cryptographic virtual machine developed by Dyne.org Foundation, capable of performing various cryptographic operations and supporting blockchain interoperability. - -**Zenswarm**: A blockchain oracle technology developed for blockchain interoperability and off-chain cryptography, utilizing Zenroom at its core. diff --git a/docs/guides/images/multisignature/M1.png b/docs/guides/images/multisignature/M1.png deleted file mode 100755 index 3567e90..0000000 Binary files a/docs/guides/images/multisignature/M1.png and /dev/null differ diff --git a/docs/guides/images/multisignature/M2.png b/docs/guides/images/multisignature/M2.png deleted file mode 100755 index 06e728b..0000000 Binary files a/docs/guides/images/multisignature/M2.png and /dev/null differ diff --git a/docs/guides/images/multisignature/M3.png b/docs/guides/images/multisignature/M3.png deleted file mode 100755 index 7e9b12c..0000000 Binary files a/docs/guides/images/multisignature/M3.png and /dev/null differ diff --git a/docs/guides/images/multisignature/M4.png b/docs/guides/images/multisignature/M4.png deleted file mode 100755 index 9dc21e5..0000000 Binary files a/docs/guides/images/multisignature/M4.png and /dev/null differ diff --git a/docs/guides/images/multisignature/MM1.png b/docs/guides/images/multisignature/MM1.png new file mode 100755 index 0000000..f16c9b3 Binary files /dev/null and b/docs/guides/images/multisignature/MM1.png differ diff --git a/docs/guides/images/multisignature/MM2.png b/docs/guides/images/multisignature/MM2.png new file mode 100755 index 0000000..c0be799 Binary files /dev/null and b/docs/guides/images/multisignature/MM2.png differ diff --git a/docs/guides/images/multisignature/MM3.png b/docs/guides/images/multisignature/MM3.png new file mode 100755 index 0000000..ca9d90b Binary files /dev/null and b/docs/guides/images/multisignature/MM3.png differ diff --git a/docs/guides/images/multisignature/MM4.png b/docs/guides/images/multisignature/MM4.png new file mode 100755 index 0000000..9b441b5 Binary files /dev/null and b/docs/guides/images/multisignature/MM4.png differ diff --git a/docs/guides/images/multisignature/MM5.png b/docs/guides/images/multisignature/MM5.png new file mode 100755 index 0000000..69dd0f9 Binary files /dev/null and b/docs/guides/images/multisignature/MM5.png differ diff --git a/docs/guides/images/multisignature/MM6.png b/docs/guides/images/multisignature/MM6.png new file mode 100755 index 0000000..b4cbf33 Binary files /dev/null and b/docs/guides/images/multisignature/MM6.png differ diff --git a/docs/guides/images/multisignature/MM7.png b/docs/guides/images/multisignature/MM7.png new file mode 100755 index 0000000..c1c0414 Binary files /dev/null and b/docs/guides/images/multisignature/MM7.png differ diff --git a/docs/guides/images/multisignature/MM8.png b/docs/guides/images/multisignature/MM8.png new file mode 100755 index 0000000..ae2d04e Binary files /dev/null and b/docs/guides/images/multisignature/MM8.png differ diff --git a/docs/guides/images/signature/S1.png b/docs/guides/images/signature/S1.png deleted file mode 100755 index 179ca6d..0000000 Binary files a/docs/guides/images/signature/S1.png and /dev/null differ diff --git a/docs/guides/images/signature/S2.png b/docs/guides/images/signature/S2.png deleted file mode 100755 index cd9ae91..0000000 Binary files a/docs/guides/images/signature/S2.png and /dev/null differ diff --git a/docs/guides/images/signature/S3.png b/docs/guides/images/signature/S3.png deleted file mode 100755 index 5ce5cbe..0000000 Binary files a/docs/guides/images/signature/S3.png and /dev/null differ diff --git a/docs/guides/images/signature/S4.png b/docs/guides/images/signature/S4.png deleted file mode 100755 index add64a9..0000000 Binary files a/docs/guides/images/signature/S4.png and /dev/null differ diff --git a/docs/guides/images/signature/S5.png b/docs/guides/images/signature/S5.png deleted file mode 100755 index 3b1679a..0000000 Binary files a/docs/guides/images/signature/S5.png and /dev/null differ diff --git a/docs/guides/images/signature/S6.png b/docs/guides/images/signature/S6.png deleted file mode 100755 index 913cb1e..0000000 Binary files a/docs/guides/images/signature/S6.png and /dev/null differ diff --git a/docs/guides/images/signature/SS1.png b/docs/guides/images/signature/SS1.png new file mode 100755 index 0000000..836519a Binary files /dev/null and b/docs/guides/images/signature/SS1.png differ diff --git a/docs/guides/images/signature/SS2.png b/docs/guides/images/signature/SS2.png new file mode 100755 index 0000000..7957a5d Binary files /dev/null and b/docs/guides/images/signature/SS2.png differ diff --git a/docs/guides/images/signature/SS3.png b/docs/guides/images/signature/SS3.png new file mode 100755 index 0000000..7698a2e Binary files /dev/null and b/docs/guides/images/signature/SS3.png differ diff --git a/docs/guides/images/signature/SS4.png b/docs/guides/images/signature/SS4.png new file mode 100755 index 0000000..03e4eb3 Binary files /dev/null and b/docs/guides/images/signature/SS4.png differ diff --git a/docs/guides/images/signature/SS4c.png b/docs/guides/images/signature/SS4c.png new file mode 100755 index 0000000..977db15 Binary files /dev/null and b/docs/guides/images/signature/SS4c.png differ diff --git a/docs/guides/images/signature/SS5a.png b/docs/guides/images/signature/SS5a.png new file mode 100755 index 0000000..e9d31bf Binary files /dev/null and b/docs/guides/images/signature/SS5a.png differ diff --git a/docs/guides/images/signature/SS5b.png b/docs/guides/images/signature/SS5b.png new file mode 100755 index 0000000..2af516a Binary files /dev/null and b/docs/guides/images/signature/SS5b.png differ diff --git a/docs/guides/images/signature/SS6.png b/docs/guides/images/signature/SS6.png new file mode 100755 index 0000000..718b86e Binary files /dev/null and b/docs/guides/images/signature/SS6.png differ diff --git a/docs/guides/images/signature/SS7.png b/docs/guides/images/signature/SS7.png new file mode 100755 index 0000000..1238ef7 Binary files /dev/null and b/docs/guides/images/signature/SS7.png differ diff --git a/docs/guides/images/signature/SS8.png b/docs/guides/images/signature/SS8.png new file mode 100755 index 0000000..dbaf489 Binary files /dev/null and b/docs/guides/images/signature/SS8.png differ diff --git a/docs/guides/images/signature/signature1_temp.png b/docs/guides/images/signature/signature1_temp.png deleted file mode 100755 index d86edbd..0000000 Binary files a/docs/guides/images/signature/signature1_temp.png and /dev/null differ