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

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

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

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:

    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

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:

the daemon checks the signature of each file
verifies that the id of the plugin matches the id in the manifest (each manifest must have a id property)
checks the certificate chain.
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.).
If the certificate chain is verified and trusted, the plugin can be installed.
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

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

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

Create a certificate with an issuer

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

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

Create a certificate signing request

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

Create an organization certificate signing request

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

Sign a plugin

Install dependencies

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

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

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

Add Revoke certificate to CRL

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

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

Verify certificate

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

Verify Jami Plugin

python3 ./certKey.py [--archive] --plugin verify --path <path-to-plugin>

Exemple

Create sign a foo plugin for test

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

python3 ./SDK/certKey.py create --issuer /tmp/bar \
--subject foo /tmp/foo

Create a CRL for a bar certificate

python3 ./certKey.py crl create --crl --issuer /tmp/bar --subject bar /tmp/bar

Revoke foo certificate with the bar CRL

python3 ./certKey.py revoke --crl /tmp/bar --subject /tmp/foo --issuer /tmp/bar --reason keyCompromise

Verify the signature of foo Jami Plugin

python3 ./certKey.py  --plugin verify --path /tmp/foo