Jami Plugins Certificate
========================


**NOTE: this page describe the architecture of the certificate for Jami plugins store**

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., 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 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).

## 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 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).

```bash
├── <plugin_name>.jpl
│   ├── data
│   │   ├── **/*.*
│   ├── lib
│   │   ├── x64-windows
│   │   │   ├── *.dll
│   │   │   ├── *.lib
│   │   ├── x86_64-linux-gnu
│   │       ├── *.so
│   ├── manifest.json
│   ├── <plugin_name>.crt
│   ├── signatures
│   ├── signatures.sig
```

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 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

The Store Root C.A. is the certificate authority. This certificate has the responsibility to sign the Organization Certificate. The Organization Certificate is the certificate of the organization.
This certificate has the responsibility to sign the Plugins Certificate. The Plugins Certificate is the certificate of the plugin. This certificate has the responsibility to sign the plugin.

![certificate-chain](images/jami-plugin-certificate-chain-schema-diagram.png)

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 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.
The root certificate structure is:

```bash
    Certificate:
        tbsCertificate:
            version: 2
            serialNumber: <generate-by-design>
            signature: AlgorithmIdentifier { algorithm: sha512WithRSAEncryption }
            issuer: Name { commonName: "Store Root C.A." }
            validity:
                notBefore: Time { utcTime: "20220101000000Z" }
                notAfter: Time { utcTime: "20520101000000Z" }
            subject: Name { commonName: "Store Root C.A." }
            subjectPublicKeyInfo:
                algorithm: AlgorithmIdentifier { algorithm: id-ecdsa-with-shake256 }
                subjectPublicKey: BIT STRING (ECDSA-256 public key)
```
This stucture is based on [rfc standard certificate v3](https://www.ietf.org/rfc/rfc2459.txt)

## Certificate Revocation

The certificate revocation mechanism allows a certificate signed by a certificate authority to be revoked.
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 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.
6. If one of the certificates that compose the certificate chain is revoked, all the files of the Green Screen plugin are removed

## Sign an organization certificate

### Install dependencies

```bash
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

### Create a self-signed certificate

```bash
python3 ./SDK/certKey.py create --subject <subject-name> <path-to-save-certificate/privatekey>
```

### Create a certificate with an issuer

```bash
python3 ./SDK/certKey.py create --issuer <path-to-delegate-certificate> \
--subject <subject-name> <path-to-save-certificate/privatekey>
```

### Create an organization certificate for the Plugin Store

```bash
python3 ./SDK/certKey.py create --organization --issuer <path-to-delegate-certificate> \
--subject <subject-name> <path-to-save-certificate/privatekey>
```

### Create a certificate signing request

```bash
python3 ./SDK/certKey.py --req create --subject <subject-name> <path-to-save-certificate/privatekey>
```

### Create an organization certificate signing request

```bash
python3 ./SDK/certKey.py --req create --organization --subject <subject-name> <path-to-save-certificate/privatekey>
```

## Sign a plugin

### Install dependencies

```bash
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>
```

### Sign JPL archive

```bash
python3 ./SDK/certKey.py --plugin sign --issuer <path-to-plugin-certificate>\
--path <path-to-archive> <path-to-save-archive-copy>
```

## Revoked a certificate

### Create CRL

```bash
python3 ./certKey.py crl create --crl --issuer <path-to-ca> --subject crl <path-to-save-crl>
```

### Add Revoke certificate to CRL

```bash
python3 ./certKey.py revoke --crl <path-to-crl> --subject <path-to-certificate-to-revoke> --issuer <path-to-ca> [--reason REASON]
```

## Verify certificate

### Verify certificate signing request

```bash
python3 ./certKey.py --req [--archive] verify --path <path-to-csr> --issuer <path-to-issuer>
```

### Verify certificate

```bash
python3 ./certKey.py [--archive] verify --path <path-to-certificate> --issuer <path-to-issuer>
```

### Verify Jami Plugin

```bash
python3 ./certKey.py [--archive] --plugin 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  --plugin verify --path /tmp/foo
```