Seald: documentation

Français

English

Français

English

SymEncKeys ​

Le concept des SymEncKeys est une fonctionnalité du SDK Seald qui permet de récupérer une EncryptionSession sans en être destinataire directement.

L'idée est de transmettre un secret (sous la forme d'un password, ou d'une paire rawSecret/rawSymKey) au destinataire, ainsi que l'ID de la SymEncKey, qui lui permettront de récupérer la EncryptionSession.

Les SymEncKeys fonctionnent de la manière suivante :

  • Le créateur d'une session lui rajoute une SymEncKey avec la méthode session.addSymEncKey(), avec un secret. Cela lui retourne l'ID de la SymEncKey ainsi créée.
  • Le secret est transmis hors-bande à la personne devant déchiffrer (par exemple, via un QRCode). Cette personne peut ensuite utiliser sdk.retrieveEncryptionSessionWithSymEncKey() ou anonymousSdk.retrieveEncryptionSession() pour récupérer la session et déchiffrer.

La manière dont ce secret est transmis du créateur au destinataire est de votre ressort, et dépend de votre cas d'usage.

WARNING

Cette fonctionnalité n'est pour l'instant présente que dans le Seald SDK pour JavaScript, et n'est pas encore implémentée dans le SDK Seald Mobile pour Android, iOS, et Flutter.

Création d'une SymEncKey ​

L'utilisateur qui a créé une EncryptionSession, ou tout utilisateur y ayant accès et qui a le droit forward, peut créer une SymEncKey pour cette EncryptionSession.

Pour créer une SymEncKey, il faut récupérer l'objet EncryptionSession, et utiliser la méthode session.addSymEncKey(). Cette méthode prend comme arguments :

  • ou un password ;
  • ou une paire rawSecret et rawSymKey.

Utiliser un password est plus simple, car il n'y a alors que cette valeur à transmettre au destinataire, mais plus lent, car le SDK dérive ce password en rawSecret et rawSymKey, ce qui peut prendre quelques centaines de millisecondes.

TIP

Afin d'assurer la confidentialité end-to-end, rawSecret et rawSymKey (ou password, qui permet de les dériver) doivent rester secrets, même de votre serveur.

rawSecret permet de prouver au serveur Seald qu'on est en droit de récupérer la clé de session chiffrée, et rawSymKey est la clé qui permet de déchiffrer la clé de session.

Vous pouvez également spécifier des droits pour les utilisateurs de cette SymEncKey avec l'argument rights.

TIP

Les rights par défaut pour une SymEncKey sont { read: true, forward: true, revoke: false }.

La méthode session.addSymEncKey() rend un string, qui est l'ID de la SymEncKey créée. Cet ID n'est pas secret, et peut être transmis à votre serveur.

Exemple d'utilisation :

javascript
const crypto = require('node:crypto')

// `rawSecret` peut être un string arbitraire, tant que celui-ci est suffisamment difficile à deviner. Ici, nous utilisons `crypto` par simplicité. Un UUIDv4 serait également un bon choix.
const rawSecret = crypto.randomBytes(64).toString('base64')
// `rawSymKey` doit nécessairement être un buffer de 64 octets aléatoires cryptographiquement sécurisé, encodé en base64.
const rawSymKey = crypto.randomBytes(64).toString('base64')

// Création de la `SymEncKey`
const symEncKeyId = await session.addSymEncKey({
  rawSecret,
  rawSymKey,
  rights: { read: true, forward: false, revoke: false }
})
const crypto = require('node:crypto')

// `rawSecret` peut être un string arbitraire, tant que celui-ci est suffisamment difficile à deviner. Ici, nous utilisons `crypto` par simplicité. Un UUIDv4 serait également un bon choix.
const rawSecret = crypto.randomBytes(64).toString('base64')
// `rawSymKey` doit nécessairement être un buffer de 64 octets aléatoires cryptographiquement sécurisé, encodé en base64.
const rawSymKey = crypto.randomBytes(64).toString('base64')

// Création de la `SymEncKey`
const symEncKeyId = await session.addSymEncKey({
  rawSecret,
  rawSymKey,
  rights: { read: true, forward: false, revoke: false }
})

Récupération d'une session avec une SymEncKey ​

Pour récupérer une EncryptionSession via une SymEncKey, il faut utiliser la méthode sdk.retrieveEncryptionSessionWithSymEncKey(). Cette méthode prend comme arguments :

  • l'ID de la session ;
  • l'ID de la SymEncKey, qui n'est pas secret et peut être transmis via votre serveur ;
  • le secret de la SymEncKey (sous forme ou d'un password, ou d'une paire rawSecret/rawSymKey).

TIP

Afin d'assurer la confidentialité end-to-end, le secret de la SymEncKey (sous forme de password, ou de paire rawSecret/rawSymKey) doit rester secret, même de votre serveur.

La manière dont ce secret est transmis du créateur au destinataire et de votre ressort, et dépend de votre cas d'usage.

La méthode sdk.retrieveEncryptionSessionWithSymEncKey() rend une EncryptionSession, qui permet ensuite de chiffrer/déchiffrer des messages et fichiers.

TIP

Si vous accédez à une EncryptionSession via une SymEncKey, vous ne pouvez pas utiliser les méthodes de gestions d'accès de celle-ci (session.addRecipients(), session.addSymEncKey(), session.revokeRecipients(), session.listRecipients(), ...).

Exemple d'utilisation :

javascript
// Récupération d'une session avec une `SymEncKey`
const session = await sdk.retrieveEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyId, // `symEncKeyId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyRawSecret, // `symEncKeyRawSecret` est secret, et ne doit jamais être connu de votre serveur
  symEncKeyRawSymKey // `symEncKeyRawSymKey` est secret, et ne doit jamais être connu de votre serveur
})
// Récupération d'une session avec une `SymEncKey`
const session = await sdk.retrieveEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyId, // `symEncKeyId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyRawSecret, // `symEncKeyRawSecret` est secret, et ne doit jamais être connu de votre serveur
  symEncKeyRawSymKey // `symEncKeyRawSymKey` est secret, et ne doit jamais être connu de votre serveur
})

Auto-ajout à une session avec une SymEncKey ​

Si vous avez accès à une EncryptionSession via une SymEncKey, et que cette SymEncKey a le droit forward, vous pouvez également l'utiliser pour vous ajouter comme destinataire "normal" de cette session. Cela vous permet par exemple de transférer ensuite cette session à d'autres utilisateurs, ou à un groupe. Pour cela, vous pouvez utiliser la méthode sdk.selfAddToEncryptionSessionWithSymEncKey(). Cette méthode prend comme arguments :

  • l'ID de la session ;
  • l'ID de la SymEncKey, qui n'est pas secret et peut être transmis via votre serveur ;
  • le secret de la SymEncKey (sous forme ou d'un password, ou d'une paire rawSecret/rawSymKey).

Vous pouvez également spécifier des droits pour vous-même en tant que destinataire de cette session, dans la limite des droits de la SymEncKey, avec l'argument rights.

TIP

Les rights par défaut pour vous-même sont { read: true, forward: true, revoke: false }.

  • le droit de read est nécessaire ;
  • le droit de forward vous permet de transférer cette session à d'autres destinataires via session.addRecipients() et de créer de nouvelles SymEncKeys ;
  • le droit de revoke vous permet de révoquer des destinataires de cette session et d'en supprimer des SymEncKeys.

Par commodité d'usage, la méthode sdk.selfAddToEncryptionSessionWithSymEncKey() rend aussi l'EncryptionSession.

Exemple d'utilisation :

javascript
// Auto-ajout à une session avec une `SymEncKey`
const session = await sdk.selfAddToEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyId, // `symEncKeyId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyRawSecret, // `symEncKeyRawSecret` est secret, et ne doit jamais être connu de votre serveur
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` est secret, et ne doit jamais être connu de votre serveur
  rights: { read: true, forward: false, revoke: false }
})
// Auto-ajout à une session avec une `SymEncKey`
const session = await sdk.selfAddToEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyId, // `symEncKeyId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyRawSecret, // `symEncKeyRawSecret` est secret, et ne doit jamais être connu de votre serveur
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` est secret, et ne doit jamais être connu de votre serveur
  rights: { read: true, forward: false, revoke: false }
})

Récupération anonyme d'une session avec une SymEncKey ​

Pour récupérer anonymement une EncryptionSession via une SymEncKey, il faut utiliser la méthode anonymousSdk.retrieveEncryptionSession(). Cette méthode prend comme arguments :

  • l'ID de la session ;
  • l'ID de la SymEncKey, qui n'est pas secret et peut être transmis via votre serveur ;
  • le secret de la SymEncKey (sous forme ou d'un password et appId, ou d'une paire rawSecret/rawSymKey) ;
  • un JWT retrieveSessionToken, créé par votre serveur, qui autorise la récupération de la session.

TIP

Afin d'assurer la confidentialité end-to-end, le secret de la SymEncKey (sous forme de password, ou de paire rawSecret/rawSymKey) doit rester secret, même de votre serveur.

La manière dont ce secret est transmis du créateur au destinataire et de votre ressort, et dépend de votre cas d'usage.

La méthode anonymousSdk.retrieveEncryptionSession() rend une AnonymousEncryptionSession, qui permet ensuite de chiffrer/déchiffrer des messages et fichiers.

Exemple d'utilisation :

javascript
// Récupération anonyme d'une session avec une `SymEncKey`
const session = await anonymousSdk.retrieveEncryptionSession({
  sessionId, // `sessionId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyId, // `symEncKeyId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyRawSecret, // `symEncKeyRawSecret` est secret, et ne doit jamais être connu de votre serveur
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` est secret, et ne doit jamais être connu de votre serveur
  retrieveSessionToken // JWT généré par votre serveur pour autoriser cette récupération anonyme
})
// Récupération anonyme d'une session avec une `SymEncKey`
const session = await anonymousSdk.retrieveEncryptionSession({
  sessionId, // `sessionId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyId, // `symEncKeyId` n'est pas secret, et peut être transmis via votre serveur
  symEncKeyRawSecret, // `symEncKeyRawSecret` est secret, et ne doit jamais être connu de votre serveur
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` est secret, et ne doit jamais être connu de votre serveur
  retrieveSessionToken // JWT généré par votre serveur pour autoriser cette récupération anonyme
})