Certificate: document all different request for the plugins store

Change-Id: Ie7288c1190e87c6ee0f3010d01c35e247a5816ed

developer/jami-plugins-certificate.md

@@ -2,28 +2,51 @@
 
 # Jami plugins certificate
 
-Jami team has introduced plugins as a call/chat feature for GNU/Linux, Windows and Android, providing users the ability to personalize your call/chat experience. If you want to learn more about Jami plugins check [Jami Plugins Page](./jami-plugins.md).
+Jami team has introduced plugins as a call/chat feature for GNU/Linux, Windows, MacOS and Android, providing users the ability to personalize your call/chat experience. If you want to learn more about Jami plugins check [Jami Plugins Page](./jami-plugins.md).
 Jami's team decided to include a Jami plugin store to be able to distribute the Jami's team plugins and third-parties plugins.
 To ensure trust in Jami's team and third-parties plugins, a certificate mechanism is required. Certificates play a crucial role in verifying the authenticity of the plugins available in the Jami plugin store.
 By leveraging certificates, users can have confidence in the origin and integrity of the plugins they choose to install.
 
 ## Certificate
 
-Within the Jami plugin architecture, three types of certificates are available: Store Root C.A., Authority Delegate, Organization Certificate and Plugins Certificate. The Jami Client has the responsibility to verify the certificate chain and enforcing the constraints established by this document.
-An organization is a third party. It has the right to add plugins in the plugins store.
-Certificate within the system, except for the plugin certificate, can sign a certificate or a plugin with the Elliptic-curve cryptography(ECC) algorithm.
-Jami team chose ECC algorithm instead of RSA algorithm due to its strong cryptographic properties with shorter key lengths, making it well-suited for resource-constrained devices like mobile phones.
-Certificates are based on the X.509 standard. Certificate contains essential information such as: issuer information, subject information, signature and validity period, revocation rules and some none essential information.
+Within the Jami plugin architecture, three types of certificates are available: Store Root C.A., Organization Certificate and Plugins Certificate. The Jami Client has the responsibility to verify the certificate chain, enforcing the constraints established by this document.
+An organization is a third party. It can have the right to add plugins in the plugins store.
+Except for the plugin certificate, every certificate can sign a certificate.
+Plugin certificate have the responsability to sign plugin.
+Certificates are based on the X.509 standard and contain essential information such as: issuer information, subject information, signature and validity period, revocation rules and some non essential information.
 It's recommended to set the validity period to 1 year.
 Each Issuer and Subject have a common name, a private key, a dynamic public key and some information about the owner or plugin of the certificate.
-Every file and archive is signed by a plugin certificate. The certificate is able to validate the entire chain of certificate leading back the root certificate([learn more about signature mechanism](#signature-mechanism)).
+Every file and archive is signed by a plugin certificate. The certificate is able to validate the entire chain of certificate leading back to the root certificate([learn more about signature mechanism](#signature-mechanism)).
 The certificate lifecycle management is designed in the Opendht library.
 The certification revocation is also managed by the Opendht library. If you want to know more about the Opendht library check [OpenDHT Page](https://opendht.net).
 
+## Plugins Store Requests
+
+All the requests from an organization that wants to be elegible to or to upload a new plugin in
+the plugins store is done with an Issue request template mechanism on [Github](https://github.com/savoirfairelinux/jami-plugins-store-requests).
+Two types of request are possible: requests to authorize a new organization to upload new plugins and requests to upload plugins.
+
+### Authorize a new organization
+
+The organization must deliver a Certificate Signing Request (CSR).
+The CSR can be generated with our tool from the [SDK](https://git.jami.net/savoirfairelinux/jami-plugins) or
+with openssl tool.
+The certificate authority must review the organization request and sign the certificate with the SDK tool.
+The certificate authority must send the certificate to the organization.
+Before sending it, a job runs to verify that the certificate is correctly signed.
+The certificate authority reserves the right to refuse the certificate request or revoke the certificate. Upon sending a certificate signing request, the organization agrees to the terms of
+use of the certificate authority. If the private key of the organization is compromised, the organization must revoke the certificate and generate a new certificate and notify the certificate authority.
+
+### Upload a new plugin
+
+The organization must deliver the plugin signed correctly with the certificate of the organization.
+A job is triggered to check the signature of the plugin and the certificate are correct.
+The Jami team is not responsible for the plugin content.
+
 ## Signature mechanism
 
 A signature is a hash generate by a subject certificate private key. This signature can be verified with the public key of the subject. As an organization, a certificate has to be signed by the root certificate
-After to be granted by the root certificate, an organization can sign plugins certificate. This plugins certificate is able to sign a file of the plugin.
+After being granted by the root certificate, an organization can sign a plugin certificate. This plugin certificate is able to sign a file of the plugin.
 When a plugin is publish, the plugin certificate must sign all the files.
 The plugin archive(plugin.jpl) must contain the manifest(manifest.json), the library directory(lib), the data directory(data) the plugin certificate(<plugin_name>.crt) and the signature file(signatures) and the signature file(signatures.sig).
 
@@ -47,8 +70,8 @@ The manifest.json contains all information about the plugin.
 The library directory contains all the dependencies to build the plugin.
 The data directory contains all data needed for the plugins(image, model, ...).
 The plugin certificate is the certificate format with x.509 standard.
-The signature file contains a Map include file name as key and signature hash as values(<file_name> <signature_hash>).
-The signature file contain the signature of the signatures file
+The signature file contains a Map including file names as keys and signatures hashes as values(<file_name> <signature_hash>).
+The signature file contains the signature of the signatures file.
 
 ## Certificate Chain
 
@@ -57,16 +80,15 @@ This certificate has the responsibility to sign the Plugins Certificate. The Plu
 
 ![certificate-chain](./images/jami-plugin-certificate-chain-schema-diagram.png)
 
-In this example, the certificate authority trust SFL and Foo organizations. SFL organization trusts there Plugin certificate representation(Green Screen and Whisper).
-Foo organization trust there Plugin certificate representation(Bar). The plugin certificate representation sign the different version of the plugin.
+In this example, the certificate authority trust SFL and Foo organizations.
+Each organization trusts theirs plugin certificate.
+The plugin certificate sign the different version of the plugin.
 
 ## Certificate Constraint
 
-Store Root C.A. certificate sign the delegate certificate.
-Delegate certificate can sign only Organization Certificates.
+Store Root C.A. certificate sign organization certificate.
 A Organization Certificate can sign only Plugin Certificates.
 A Plugins Certificate can sign only Plugin files. The certificate chain must be respected. The certificate chain is the following: Store Root C.A. `->` Organization Certificate `->` Plugins Certificate `->` Plugin Files.
-A Plugins Certificate can sign only Plugin files. The certificate chain must be respected. The certificate chain is the following: Store Root C.A. `->` Organization Certificate `->` Plugins Certificate `->` Plugin Files.
 The root certificate structure is:
 
 ```bash
@@ -89,13 +111,13 @@ This stucture is based on [rfc standard certificate v3](https://www.ietf.org/rfc
 ### Certificate Revocation
 
 The certificate revocation mechanism allows a certificate signed by a certificate authority to be revoked.
-In fact, the root certificate can revoke an organization certificate and a plugin certificate. An organization certificate can revoke its own plugin certificate.
+In fact, the root certificate can revoke any organization certificate. An organization certificate can only revoke its own plugin certificate.
 OpenDHT uses the Certificate Revocation List (CRL) and Online Certificate Status Protocol (OCSP) to verify the status of the certificate. The daemon checks the CRL for every certificate authority. After this check, the daemon sends a request to the OCSP server to check the status of the certificate chain own by the plugin.
 The OCSP server endpoint is stored in the certificate. If the server response indicates that all the certificates in the signature are not revoked and not unknown, the client is allowed to add the plugin to its list.
 For instance, Bob wants to add the Green Screen plugin to his list of plugins. Bob interacts with the front end that triggers an event to pull all files related to the Green Screen plugin.
 The steps to validate the signature of files are:
 1. the daemon checks the signature of each file
-2. verifies that the name of the plugin matches the name in the manifest (each manifest must have a name property)
+2. verifies that the id of the plugin matches the id in the manifest (each manifest must have a id property)
 3. checks the certificate chain.
 4. the daemon requests the status of the certificate chain by requesting the OCSP server (Green Screen plugin certificate, SFL certificate, and Store Root C.A.).
 5. If the certificate chain is verified and trusted, the plugin can be installed.
@@ -106,7 +128,11 @@ The steps to validate the signature of files are:
 ### Install dependencies
 
 ```bash
-git clone git@git.jami.net:savoirfairelinux/jami-plugins.git
+git clone git@git.jami.net:savoirfairelinux/jami-plugins.git &&
+sudo apt install python3 python3-pip &&
+cd <path-to-jami-plugins/SDK> &&
+pip install -r <requirements.txt> &&
+pip install -r <certificate_requirements.txt>
 ```
 
 ### Create certificate
@@ -176,3 +202,37 @@ python3 ./certKey.py [--archive] verify --path <path-to-certificate> --issuer <p
 ```bash
 python3 ./certKey.py [--archive] verify --path <path-to-plugin>
 ```
+
+## Exemple
+
+### Create sign a foo plugin for test
+
+```bash
+python3 ./SDK/certKey.py create --subject foo /tmp/foo &&
+python3 ./SDK/certKey.py --plugin sign --path /tmp/plugins/foo --issuer /tmp/foo /tmp/plugins/foo
+```
+
+### Create a foo certificate with bar organization
+
+```bash
+python3 ./SDK/certKey.py create --issuer /tmp/bar \
+--subject foo /tmp/foo
+```
+
+### Create a CRL for a bar certificate
+
+```bash
+python3 ./certKey.py crl create --crl --issuer /tmp/bar --subject bar /tmp/bar
+```
+
+### Revoke foo certificate with the bar CRL
+
+```bash
+python3 ./certKey.py revoke --crl /tmp/bar --subject /tmp/foo --issuer /tmp/bar --reason keyCompromise
+```
+
+### Verify the signature of foo Jami Plugin
+
+```bash
+python3 ./certKey.py  verify --path /tmp/foo
+```