Seald: documentation

English

Français

English

Français

Proxy Sessions ​

Proxy Sessions are a feature of the Seald SDK that offers an alternative to groups.

The idea of Proxy Sessions is to have a specific EncryptionSession (the Proxy session), which itself is a recipient of another session (the proxied session). A user who then wants to access the proxied session, and is not a direct recipient, but is a recipient of the Proxy session, can access the proxied session.

To allow a user to access all sessions for which the Proxy session is a recipient, you just have to add this user as a recipient of the Proxy session.

Direct access to sessions:

uml diagram

Access via Proxy Session:

uml diagram

This feature is quite similar to Groups in what it allows, but it has important differences:

  • unlike groups, it is necessary to be a recipient of the Proxy Session to add the Proxy Session as a recipient of another session;
  • in use, Proxy Sessions are "lighter" than groups, operations may be a bit faster;
  • the key of the Proxy Session cannot be renewed, so after revoking a member of the proxy session, the guarantee that this person can no longer access the encrypted data afterwards for this proxy session is slightly weaker;
  • the Proxy Session is a session like any other, so it is possible to use a SymEncKey to add oneself to it.

WARNING

It is not possible to use multiple levels of Proxy Sessions.

For example, if a user is a recipient of Session1, which is designated as a ProxySession for Session2, and Session2 is a ProxySession for Session3, the user will not be able to retrieve Session3.

Creating a Proxy Session ​

A Proxy Session is a session like any other. To create a Proxy Session, you just have to create a session with the desired members as recipients.

javascript
const proxySession = await sealdSdk.createEncryptionSession(
  {
    sealdIds: [ // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
      { id: sealdId1 },
      { id: sealdId2 },
      { id: sealdId3 }
    ]
  }
)
const proxySession = await sealdSdk.createEncryptionSession(
  {
    sealdIds: [ // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
      { id: sealdId1 },
      { id: sealdId2 },
      { id: sealdId3 }
    ]
  }
)
swift
let proxySession = try await sealdSdk.createEncryptionSessionAsync(
    withRecipients: [ // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
    SealdRecipientWithRights(recipientId: sealdId1, rights: SealdRecipientRights(read: true, forward: true, revoke: true)),
    SealdRecipientWithRights(recipientId: sealdId2, rights: SealdRecipientRights(read: true, forward: true, revoke: true)),
    SealdRecipientWithRights(recipientId: sealdId3, rights: SealdRecipientRights(read: true, forward: true, revoke: true))
],
    useCache: true
)
let proxySession = try await sealdSdk.createEncryptionSessionAsync(
    withRecipients: [ // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
    SealdRecipientWithRights(recipientId: sealdId1, rights: SealdRecipientRights(read: true, forward: true, revoke: true)),
    SealdRecipientWithRights(recipientId: sealdId2, rights: SealdRecipientRights(read: true, forward: true, revoke: true)),
    SealdRecipientWithRights(recipientId: sealdId3, rights: SealdRecipientRights(read: true, forward: true, revoke: true))
],
    useCache: true
)
objective-c
SealdRecipientRights* allRights = [[SealdRecipientRights alloc] initWithRead:YES forward:YES revoke:YES];

NSArray<SealdRecipientWithRights*>* proxyRecipients = [NSArray arrayWithObjects: // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
                                                       [[SealdRecipientWithRights alloc] initWithRecipientId:sealdId1 rights:allRights],
                                                       [[SealdRecipientWithRights alloc] initWithRecipientId:sealdId2 rights:allRights],
                                                       [[SealdRecipientWithRights alloc] initWithRecipientId:sealdId3 rights:allRights],
                                                       nil];

SealdEncryptionSession* proxySession = [sealdSdk createEncryptionSessionWithRecipients:proxyRecipients
                                                                              useCache:YES
                                                                                 error:&error
                                       ];
/* [Handle error] */
SealdRecipientRights* allRights = [[SealdRecipientRights alloc] initWithRead:YES forward:YES revoke:YES];

NSArray<SealdRecipientWithRights*>* proxyRecipients = [NSArray arrayWithObjects: // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
                                                       [[SealdRecipientWithRights alloc] initWithRecipientId:sealdId1 rights:allRights],
                                                       [[SealdRecipientWithRights alloc] initWithRecipientId:sealdId2 rights:allRights],
                                                       [[SealdRecipientWithRights alloc] initWithRecipientId:sealdId3 rights:allRights],
                                                       nil];

SealdEncryptionSession* proxySession = [sealdSdk createEncryptionSessionWithRecipients:proxyRecipients
                                                                              useCache:YES
                                                                                 error:&error
                                       ];
/* [Handle error] */
kotlin
val proxySession =
    sealdSdk.createEncryptionSessionAsync(
        arrayOf( // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
            RecipientWithRights(sealdId1, RecipientRights(read = true, forward = true, revoke = true)),
            RecipientWithRights(sealdId2, RecipientRights(read = true, forward = true, revoke = true)),
            RecipientWithRights(sealdId3, RecipientRights(read = true, forward = true, revoke = true)),
        ),
    )
val proxySession =
    sealdSdk.createEncryptionSessionAsync(
        arrayOf( // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
            RecipientWithRights(sealdId1, RecipientRights(read = true, forward = true, revoke = true)),
            RecipientWithRights(sealdId2, RecipientRights(read = true, forward = true, revoke = true)),
            RecipientWithRights(sealdId3, RecipientRights(read = true, forward = true, revoke = true)),
        ),
    )
dart
final SealdEncryptionSession proxySession =
    await sealdSdk.createEncryptionSessionAsync([
  // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
  SealdRecipientWithRights(
    id: sealdId1,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true),
  ),
  SealdRecipientWithRights(
    id: sealdId2,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true),
  ),
  SealdRecipientWithRights(
    id: sealdId3,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true),
  )
]);
final SealdEncryptionSession proxySession =
    await sealdSdk.createEncryptionSessionAsync([
  // List of members of the Proxy Session, who will be able to decrypt everything that is encrypted for the Proxy Session.
  SealdRecipientWithRights(
    id: sealdId1,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true),
  ),
  SealdRecipientWithRights(
    id: sealdId2,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true),
  ),
  SealdRecipientWithRights(
    id: sealdId3,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true),
  )
]);

Note, the current user must absolutely be a recipient of the session in question in order to use it as a Proxy Session.

Adding a Proxy Session as a recipient of a session ​

On the Seald JavaScript SDK, to add a Proxy Session as a recipient of a session, you must put the proxySessions key in the recipients object, either at the time of session creation or during a call to session.addRecipients. Note, since the current user will have access to the session via the Proxy Session, you may want to set encryptForSelf: false, so they don't also have direct access to the session.

On the Seald mobile SDKs, to add a Proxy Session as a recipient of a session, you must first create the session, then call session.addProxySession.

javascript
// Adding the proxySession at creation
const session = await sealdSdk.createEncryptionSession(
  {
    sealdIds: [],
    proxySessions: [ // The proxySession is a recipient of the session
      { id: proxySession.sessionId }
    ]
  },
  { encryptForSelf: false } // So the current user only has access via the proxySession
)

// Or, adding the proxySession after creation
const session = await sealdSdk.createEncryptionSession( // Creating the session
  {},
  { encryptForSelf: false } // So the current user only has access via the proxySession
)
await session.addRecipients({ proxySessions: [{ id: proxySession.sessionId }] }) // Adding the proxySession as a recipient of the session
// Adding the proxySession at creation
const session = await sealdSdk.createEncryptionSession(
  {
    sealdIds: [],
    proxySessions: [ // The proxySession is a recipient of the session
      { id: proxySession.sessionId }
    ]
  },
  { encryptForSelf: false } // So the current user only has access via the proxySession
)

// Or, adding the proxySession after creation
const session = await sealdSdk.createEncryptionSession( // Creating the session
  {},
  { encryptForSelf: false } // So the current user only has access via the proxySession
)
await session.addRecipients({ proxySessions: [{ id: proxySession.sessionId }] }) // Adding the proxySession as a recipient of the session
swift
// Creating the session
let session = try await sealdSdk.createEncryptionSessionAsync(
    withRecipients: [],
    useCache: true
)
// Adding the proxySession as a recipient of the session
try await session.addProxySessionAsync(
    proxySession.sessionId,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true)
)
// Creating the session
let session = try await sealdSdk.createEncryptionSessionAsync(
    withRecipients: [],
    useCache: true
)
// Adding the proxySession as a recipient of the session
try await session.addProxySessionAsync(
    proxySession.sessionId,
    rights: SealdRecipientRights(read: true, forward: true, revoke: true)
)
objective-c
SealdRecipientRights* allRights = [[SealdRecipientRights alloc] initWithRead:YES forward:YES revoke:YES];

// Creating the session
SealdEncryptionSession* session = [sealdSdk createEncryptionSessionWithRecipients:[NSArray arrayWithObjects:nil]
                                                                         useCache:YES
                                                                            error:&error
                                  ];
/* [Handle error] */

// Adding the proxySession as a recipient of the session
[session addProxySession:proxySession.sessionId rights:allRights error:&error];
/* [Handle error] */
SealdRecipientRights* allRights = [[SealdRecipientRights alloc] initWithRead:YES forward:YES revoke:YES];

// Creating the session
SealdEncryptionSession* session = [sealdSdk createEncryptionSessionWithRecipients:[NSArray arrayWithObjects:nil]
                                                                         useCache:YES
                                                                            error:&error
                                  ];
/* [Handle error] */

// Adding the proxySession as a recipient of the session
[session addProxySession:proxySession.sessionId rights:allRights error:&error];
/* [Handle error] */
kotlin
// Creating the session
val session = sealdSdk.createEncryptionSessionAsync(arrayOf())

// Adding the proxySession as a recipient of the session
session.addProxySession(proxySession.sessionId, RecipientRights(read = true, forward = true, revoke = true))
// Creating the session
val session = sealdSdk.createEncryptionSessionAsync(arrayOf())

// Adding the proxySession as a recipient of the session
session.addProxySession(proxySession.sessionId, RecipientRights(read = true, forward = true, revoke = true))
dart
// Creating the session
final SealdEncryptionSession session =
    await sealdSdk.createEncryptionSessionAsync([]);

// Adding the proxySession as a recipient of the session
await session.addProxySessionAsync(
    proxySession.id,
    SealdRecipientRights(read: true, forward: true, revoke: true),
);
// Creating the session
final SealdEncryptionSession session =
    await sealdSdk.createEncryptionSessionAsync([]);

// Adding the proxySession as a recipient of the session
await session.addProxySessionAsync(
    proxySession.id,
    SealdRecipientRights(read: true, forward: true, revoke: true),
);

Retrieving a session via a Proxy Session ​

To retrieve a session to which one has access via a Proxy Session, simply retrieve the session with retrieveEncryptionSession, setting lookupProxyKey to true.

javascript
// Retrieving a session via proxy
const retrievedSession = await sealdSdk.retrieveEncryptionSession({
  sessionId: session.sessionId,
  lookupProxyKey: true // checks if the session is accessible via a proxy
})
// Retrieving a session via proxy
const retrievedSession = await sealdSdk.retrieveEncryptionSession({
  sessionId: session.sessionId,
  lookupProxyKey: true // checks if the session is accessible via a proxy
})
swift
// Retrieving a session via proxy
let retrievedSession = try await sealdSdk.retrieveEncryptionSessionAsync(
    withSessionId: session.sessionId,
    useCache: true,
    lookupProxyKey: true, // checks if the session is accessible via a proxy
    lookupGroupKey: false)
// Retrieving a session via proxy
let retrievedSession = try await sealdSdk.retrieveEncryptionSessionAsync(
    withSessionId: session.sessionId,
    useCache: true,
    lookupProxyKey: true, // checks if the session is accessible via a proxy
    lookupGroupKey: false)
objective-c
// Retrieving a session via proxy
SealdEncryptionSession* retrievedSession = [sealdSdk retrieveEncryptionSessionWithSessionId:session.sessionId
                                                                                   useCache:YES
                                                                             lookupProxyKey:YES // checks if the session is accessible via a proxy
                                                                              ookupGroupKey:NO
                                                                                      error:&error
                                           ];
/* [Handle error] */
// Retrieving a session via proxy
SealdEncryptionSession* retrievedSession = [sealdSdk retrieveEncryptionSessionWithSessionId:session.sessionId
                                                                                   useCache:YES
                                                                             lookupProxyKey:YES // checks if the session is accessible via a proxy
                                                                              ookupGroupKey:NO
                                                                                      error:&error
                                           ];
/* [Handle error] */
kotlin
// Retrieving a session via proxy
val retrievedSession = sealdSdk.retrieveEncryptionSessionAsync(
    session.sessionId,
    true,
    lookupProxyKey = true, // checks if the session is accessible via a proxy
)
// Retrieving a session via proxy
val retrievedSession = sealdSdk.retrieveEncryptionSessionAsync(
    session.sessionId,
    true,
    lookupProxyKey = true, // checks if the session is accessible via a proxy
)
dart
// Retrieving a session via proxy
final SealdEncryptionSession retrievedSession = await sealdSdk
    .retrieveEncryptionSessionAsync(
        sessionId: session.id,
        useCache: true,
        lookupProxyKey: true); // checks if the session is accessible via a proxy
// Retrieving a session via proxy
final SealdEncryptionSession retrievedSession = await sealdSdk
    .retrieveEncryptionSessionAsync(
        sessionId: session.id,
        useCache: true,
        lookupProxyKey: true); // checks if the session is accessible via a proxy

Rights ​

When using a Proxy Session, there are two sets of rights:

  • the rights of the user, as a recipient of the Proxy Session
  • the rights of the Proxy Session, as a recipient of the session

The rights of the user as a recipient of the Proxy Session only grant rights over the Proxy Session itself. That is, if they have the 'forward' or 'revoke' right, it will allow them to add/revoke members to the Proxy Session itself, and not directly on the sessions to which they have access via the Proxy Session. They can however give access to someone by adding them to the Proxy Session.

The rights of the Proxy Session as a recipient of the session correspond to what is permitted for anyone who has access to the session via this Proxy Session. That is, if the Proxy Session has the 'forward' right on a session, anyone who is a member of the Proxy Session will be able to add recipients to the session.