👩‍🏫 Tutoriels

Déployer en production

Avant de déployer un bot ou un programme en production, nous vous conseillons très fortement de lire et de considérer les points suivants.

Danger

Gardez absolument les points suivants à l’esprit.

• Le daemon et ses données sont extrêmement sensibles. Ils ont accès à l’ensemble des messages, des pièces jointes et bien plus. Il vous appartient de faire le nécessaire pour que ces données soient correctement hébergées et protégées.

• Le trafic entre le daemon et ses clients n’est pas chiffré par défaut (voir Chiffrement Tls). Il ne doit en aucun cas être exposé.

• Sans chiffrement TLS, les clés clientes ne servent qu’à compartimenter les appels API, et ne peuvent être utilisées à des fins d’authentification.

Creer un bot keycloak

Note

Cette section ne s’adresse qu’aux clients qui ont un plugin Keycloak deployé 😬.

Si vous ne savez pas ce que c’est vous pouvez cliquer 👉️ ici 👈️ pour en apprendre plus sur cette fonctionalité premium.

Configurer un Bot Keycloak

Configurer un Bot Keycloak vous permet de le gérer comme l’un de vos utilisateurs standard Keycloak. Il peut être ajouté ou supprimé des groupes, et les utilisateurs peuvent interagir avec le bot via l’onglet « Annuaire » dans leur application. Cela facilite considérablement son intégration et son utilisation à grande échelle.

Les étapes suivantes nécessitent un accès à la console de gestion Olvid de votre Keycloak.

Activer les bots dans Keycloak

Astuce

Cette étape n’est nécessaire que pour votre premier bot.

Pour votre realm, si vous ne voyez pas le bouton « Bots » dans la barre latérale gauche, cliquez sur le bouton « Paramètres » de votre realm.

Bouton Bot

Bouton Paramètres du realm

Ensuite, dans les paramètres de votre realm, activez l’option « Activer les bots ».

Activer les bots

Créer un nouveau Bot Keycloak

Accédez à la page « Bots » de votre Realm. Le bouton est situé dans le panneau latéral gauche.

Bouton Bots

Lorsque vous êtes sur la page de gestion des bots, cliquez sur le bouton « Créer un bot » en haut à gauche.

Page de gestion des bots

Cela affichera un formulaire à remplir avec le nom d’utilisateur et les détails d’identité de votre nouveau bot.

Formulaire de création du bot

Lorsque vous avez validé le formulaire, un lien de configuration (commençant par https://configuration.olvid.io/#) sera affiché. Enregistrez ce lien pour les étapes suivantes.

Astuce

Si vous avez perdu votre lien de configuration, vous pouvez le réinitialiser avec le bouton « Actualiser » dans la liste des bots.

Créer l’identité du bot

Lorsque vous disposez du lien de configuration, vous devrez utiliser la CLI. Cliquez ici si vous ne vous souvenez pas comment l’utiliser.

Créer une nouvelle identité Keycloak

Démarrez la CLI et créez votre nouvelle identité en utilisant le lien de configuration. Elle générera automatiquement une clé client à passer à votre futur bot.

# create keycloak identity
0 > identity kc new https://configuration.olvid.io/#AAAAAAAAA.....
# client is automatically created
identity creation > Here is your client key to connect to daemon with this identity: 00000000-0000-0000-0000-000000000000
# save your client key and enter yes to finish process
identity creation > Did you saved your client key ? (y/N)
> yes

Note

Tous les utilisateurs Keycloak peuvent maintenant découvrir et interagir avec votre bot via leur bouton « Annuaire » dans l’application Olvid.

Vous pouvez également gérer votre bot à partir de la console d’administration !

Configuration TLS

Ajouté dans la version 1.0.1.

Nativement gRPC prend en charge le chiffrement TLS. Nous pouvons distinguer deux modes :

• Authentification serveur : Le daemon utilise son propre certificat auto-signé et sa clé privée associée. Les clients utiliseront ce certificat pour chiffrer les communications avec le daemon.

• Authentification client : On crée notre propre Autorité de Certification (CA). On peut ainsi créer un certificat et une clé privée pour le daemon et un par client. Ainsi, les clients peuvent chiffrer les communications avec le daemon, et le daemon peut vérifier que les clients ont été autorisés à se connecter.

Authentification serveur

Configuration du Daemon

Dans un premier temps, on génère le certificat et la cle privée du serveur à l’aide de la commande openssl.

Important

Remplacez localhost par le nom d’hôte de votre daemon. Le nom d’hôte est l’adresse IP ou le nom de domaine que les clients utiliseront pour établir une connexion avec le daemon.

openssl req -x509 -newkey rsa:4096 -keyout server.key \
    -days 36500 -out server.pem -nodes -subj '/CN=localhost'

Si vous utilisez Docker, créez un répertoire credentials contenant le certificat et la clé générés précédemment. Ajoutez ce répertoire en tant que volume en lecture seule et utilisez une variable d’environnement pour activer l’authentification TLS simple dans le daemon.

On utilise les variables d’environnement suivantes pour configurer le daemon :

• DAEMON_CERTIFICATE_FILE

• DAEMON_KEY_FILE

Ce qui nous donne un fichier docker-compose.yaml similaire à celui-ci.

daemon:
  image: olvid/bot-daemon:latest
  environment:
    - OLVID_ADMIN_CLIENT_KEY_CLI=ToSet
    - DAEMON_CERTIFICATE_FILE=./credentials/server.pem
    - DAEMON_KEY_FILE=./credentials/server.key
  ports:
    - 50051:50051
  restart: unless-stopped
  volumes:
    - ./data:/daemon/data
    - ./backups:/daemon/backups
    - ./credentials:/daemon/credentials:ro

Configuration du Client Python

Pour assurer le chiffrement des communications, votre bot a besoin du certificat du daemon.

On suppose que vous avez un répertoire credentials contenant le fichier server.pem généré précédemment. Il existe plusieurs moyens de faire en sorte que votre client utilise ce fichier pour authentifier le daemon et chiffrer le traffic.

Environnement

Configurez la variable d’environnement dans votre fichier docker-compose.yaml, dans votre commande docker ou votre environnement local.

OLVID_SERVER_CERTIFICATE_PATH=./credentials/server.pem

N’importe quel sous-classe de la classe OlvidClient chargera automatiquement la configuration TLS.

Fichiers

Au démarrage les sous-classes de la classe OlvidClient cherchent des noms de fichiers spécifiques pour charger les configurations TLS. Si un fichier .server.pem existe il sera automatiquement utilisé pour configurer le TLS.

ln -s ./credentials/server.pem .server.pem

Code

Vous pouvez également configurer manuellement les certificats et clés à utiliser dans votre code Python.

Dans ce cas, il faut créer un object GrpcSimpleTlsConfiguration et le passer en tant que tls_configuration à la creation du client.

import asyncio
from olvid import OlvidClient

async def main():
    client = OlvidClient(tls_configuration=OlvidClient.GrpcSimpleTlsConfiguration(
            server_certificate_path="./credentials/server.pem"
    ))
    print(await client.identity_get())

asyncio.set_event_loop(asyncio.get_event_loop())
asyncio.get_event_loop().run_until_complete(main())

Configuration du Client Javascript

Actuellement notre implementation de Client JavaScript ne supporte pas nativement l’utilisation du protocole TLS.

Authentification client

Génération des certificats

Nous vous recommandons de créer un répertoire credentials et d’exécuter les commandes suivantes depuis celui-ci.

Note

Pour générer le CA et le certificat serveur, vous aurez besoin de ces deux modèles openssl. Téléchargez-les ou créez-les dans votre répertoire de travail actuel.

• ca-openssl.cnf

• server-openssl.cnf

Génération de notre autorité de certification locale (CA)

# you can leave default values
openssl req -x509 -new -newkey rsa:2048 -nodes -keyout ca.key -out ca.pem \
  -config ca-openssl.cnf -days 36500 -extensions v3_req

Génération du certificat et la clé serveur.

Remplacez localhost par le nom d’hôte de votre daemon. Le nom d’hôte correspond à l’adresse IP ou le nom de domaine que les clients utiliseront pour établir une connexion avec le daemon.

# generate server private key
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out server.key
# generate server certificate
openssl req -new -key server.key -out server.csr -config server-openssl.cnf \
    -subj '/CN=localhost'
openssl x509 -req -CA ca.pem -CAkey ca.key -CAcreateserial -in server.csr \
  -out server.pem -extensions v3_req -extfile server-openssl.cnf -days 36500

Génération d’un certificat et d’une clé privée pour un client

# generate client private key
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out client.key

# generate client certificate request (leave default values)
openssl req -new -key client.key -out client.csr
openssl x509 -req -CA ca.pem -CAkey ca.key -CAcreateserial -in client.csr \
  -out client.pem -days 36500

Configuration du Daemon

Le daemon aura besoin de son certificat, de sa clé privée et du CA pour vérifier que les clients sont autorisés à se connecter. Nous allons utiliser trois variables d’environnement pour spécifier les chemins des fichiers :

• DAEMON_CERTIFICATE_FILE

• DAEMON_KEY_FILE

• DAEMON_CA_FILE

Créez un répertoire credentials et copiez-y les fichiers générés précédemment.

Ce qui nous donne un fichier docker-compose.yaml similaire à celui-ci.

daemon:
  image: olvid/bot-daemon
  environment:
    - OLVID_ADMIN_CLIENT_KEY_CLI=ToSet
    - DAEMON_CERTIFICATE_FILE=./credentials/server.pem
    - DAEMON_KEY_FILE=./credentials/server.key
    - DAEMON_ROOT_CERTIFICATE_FILE=./credentials/ca.pem
  ports:
    - 50051:50051
  restart: unless-stopped
  volumes:
    - ./data:/daemon/data
    - ./backups:/daemon/backups
    - ./credentials:/daemon/credentials:ro

Configuration du Client Python

Pour configurer le client, vous pouvez utiliser l’une des méthodes suivantes :

Environnement

Configurez les variables d’environnement suivantes dans votre fichier docker-compose.yaml, dans votre commande docker ou votre environnement local.

OLVID_CLIENT_TLS_CERTIFICATE_FILE=./credentials/client.pem
OLVID_CLIENT_TLS_KEY_FILE=./credentials/client.key
OLVID_CLIENT_TLS_CA_FILE=./credentials/ca.pem

N’importe quel sous-classe de la classe OlvidClient chargera automatiquement la configuration TLS.

Fichiers

Au démarrage les sous-classes de la classe OlvidClient cherchent des noms de fichiers spécifiques pour charger les configurations TLS. Si elle trouve les trois fichiers suivants, ils seront automatiquement utilisé pour configurer le TLS.

• .ca.pem

• .client.pem

• .client.key

ln -s ./credentials/ca.pem .ca.pem
ln -s ./credentials/client.pem .client.pem
ln -s ./credentials/client.key .client.key

Code

Vous pouvez également configurer manuellement les certificats et clés à utiliser dans votre code Python. Dans ce cas il faut créer un objet GrpcMutualAuthTlsConfiguration et le passer en tant que paramètre tls_configuration au constructeur d’une sous-classe OlvidClient.

import asyncio
from olvid import OlvidClient

async def main():
    client = OlvidClient(tls_configuration=OlvidClient.GrpcMutualAuthTlsConfiguration(
            root_certificate_path="/path/to/ca.pem",
            certificate_chain_path="/path/to/client.pem",
            private_key_path="/path/to/client.key"
    ))
    print(await client.identity_get())

asyncio.set_event_loop(asyncio.new_event_loop())
asyncio.get_event_loop().run_until_complete(main())

Configuration du Client Javascript

Actuellement notre implementation de Client JavaScript ne supporte pas nativement l’utilisation du protocole TLS.

Sauvegardes

Dans vos projets, le daemon est un élément central, c’est là où toutes les données sont stockées. En réalité, les données que vous manipulez (identités, messages, …) ne constituent qu’une petite partie des données gérées par le daemon. Ce sont ces donnée invisibles qui doivent être sauvegardées, car elles permettent un échange sécurisé avec les contacts du bot.

Avertissements

Danger

Veuillez examiner attentivement les recommandations et avertissements suivants avant de continuer.

• Les sauvegardes contiennent des données sensibles équivalentes au répertoire de données du daemon. Il est impératif de les manipuler avec la même rigueur et niveau de sécurité.

• Les sauvegardes mentionnées ici sont des sauvegardes Olvid, qui ne contiennent pas de messages ou de pièces jointes Ces sauvegardes vous permettent de restaurer votre carnet d’adresses, vos groupes et votre stockage, mais pas le contenu des discussions (messages et pièces jointes).

• Les sauvegardes sont… des sauvegardes. Vous devrez les conserver dans un endroit sûr pour pouvoir les réutiliser si nécessaire. Dans un environnement de production, la meilleure pratique minimale serait de stocker les sauvegardes sur un disque séparé du reste du système.

• La restauration d’une sauvegarde sur un autre daemon et l’exécution simultanée des deux entraînera un comportement imprévisible.

Configuration des sauvegardes automatiques

Le daemon crée automatiquement et périodiquement des sauvegardes. Les sauvegardes sont créées chaque fois que cela est nécessaire (votre bot a ajouté un contact, rejoint ou quitte un groupe, …). Ces sauvegardes sont stockées dans le répertoire /daemon/backups.

Si vous souhaitez conserver ces sauvegardes, vous devez monter le répertoire /daemon/backups en tant que volume. Voici un exemple de fichier docker-compose.yaml.

services:
  daemon:
    image: olvid/bot-daemon
    volumes:
      - ./data:/daemon/data
      - ./backups:/daemon/backups

Voici un exemple de l’arborescence du répertoire /daemon/backups.

| backups
|  | 0001
|  |  | backup-1041588600.bytes
|  |  | backup-1569233400.bytes
|  |  | backup_seed.txt

Chaque sous-répertoire (0001, 0002) doit contenir son propre fichier backup_seed.txt, sinon le daemon incrémentera et créera automatiquement un nouveau répertoire. Ce fichier de graine est nécessaire pour déchiffrer et restaurer les sauvegardes. Sans lui votre sauvegarde est inutilisable.

À l’intérieur d’un sous-répertoire, le daemon crée et stocke jusqu’à 10 fichiers de sauvegarde avant de supprimer les plus anciens. Toutes ces sauvegardes sont nommées en utilisant l’horodatage de leur création.

Restauration d’une sauvegarde

Danger

La restauration d’une sauvegarde n’est pas une action triviale et ne doit être effectuée qu’en dernier recours. Vous perdrez tous vos messages et pièces jointes stockés dans le daemon au cours de ce processus. Seuls les éléments enregistrés à l’aide de l’API de stockage seront encore disponibles.

Pour restaurer une sauvegarde, vous devez exécuter la commande suivante depuis le repertoire qui contient votre daemon habituellement. Vérifiez bien que le répertoire data est vide avant de lancer une restauration, autrement, elle échouera.

docker run --rm \
    -v ./data:/daemon/data \
    -v ./backups:/daemon/backups \
    olvid/bot-daemon -r backups/0001/backup-1569233400.bytes | grep Backup

Lorsque vous voyez le message 💾 BackupRestoration: Finished backup restoration process, vous pouvez arrêter le daemon (CTRL + C) et le démarrer normalement avec la commande docker-compose up -d.

Vous pouvez maintenant vérifier à l’aide de la CLI que la restauration a été réussie. Vous devriez trouver vos identités, contacts, groupes, clés client, …

Les éléments stockés à l’aide de l’API de stockage du démon sont également accessibles par les moyens habituels.

Configuration JVM

Ajouté dans la version 1.0.1.

Il est possible de passer des options arbitraires à la JVM qui fait tourner votre daemon. Pour cela, vous pouvez utiliser la variable d’environnement JAVA_FLAGS.

Configuration proxy

Pour permettre au daemon d’utiliser un proxy HTTP, il faut passer des paramètres spécifiques a la JVM. (cf: Proxy Properties).

Voici un exemple de configuration possible pour utiliser un proxy fictif accessible en tant que proxy.example.com sur le port 8000.

JAVA_FLAGS=-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8000