Property

Abstract types

Property

constant static

FailureChoice  string

The enumeration of options an application has when the SparkCommunications.KeyProviderInterface#profileKeysImportFailed function is called.

Properties

Name Type Optional Description

GenerateNewKeys

 

 

The SDK will generate new profile keys for the user and proceed with setup. The new keys will be relayed to the application once successfully generated SparkCommunications.KeyProviderInterface#saveProfileKeys.

GetProfileKeys

 

 

The SDK will request new profile keys with another call to SparkCommunications.KeyProviderInterface#getProfileKeys. This will allow the application to provide updated keys or to attempt another fetch of the keys. If the new profile keys fail to import again, the SparkCommunications.KeyProviderInterface#profileKeysImportFailed function will also be called again.

AbandonSetup

 

 

The SDK will abandon its attempt to setup for the local user. The setup process in progress will fail with a SparkCommunications.Event.SetupError being emitted.

Methods

getChatKey(chatId) → Promise containing Uint8Array

Get the chat key data associated with the given chatId.

Parameter

Name Type Optional Description

chatId

string

 

The identifier for the chat whose key is to be retrieved from the key provider's underlying storage.

Returns

Promise containing Uint8Array

The promise of the chat key data.

When the promise is rejected with SparkCommunications.Error.NotFoundError, the chat key is known not to exist. When a chat key is known not to exist, the chat will be automatically cleaned up as recovery of chat contents will not be possible.

Any other rejection error will be treated as a temporary error and another call to SparkCommunications.KeyProviderInterface#getChatKey will be made the next time the key is needed. This will result in sub-optimal behaviour patterns and any encrypted information in the chat details and all messages will not be recoverable until SparkCommunications.KeyProviderInterface#getChatKey resolves with a valid key.

getChatKeys() → Promise containing Object with Uint8Array properties

Get the key data associated with all of the chats known to the user.

Returns

Promise containing Object with Uint8Array properties

The promise of the known chat key data returned as a dictionary object. The object members are expected to be the chatIds and the member values are the keys associated with the chatId.

When no chat keys are known an empty object is used to resolve the promise.

Any rejection of this promise will be treated as a temporary failure and the chat keys will be recovered later on demand with a call to SparkCommunications.KeyProviderInterface#getChatKey.

getProfileKeys() → Promise containing SparkCommunications.KeyProviderInterface.ProfileKeys

Get the promise of the local user's encryption and signing key pairs.

If either the encryption or the signing key pair provided cannot be successfully imported, the SDK will call the SparkCommunications.KeyProviderInterface#profileKeysImportFailed function.

Returns

Promise containing SparkCommunications.KeyProviderInterface.ProfileKeys

The promise will be resolved with the local user's SparkCommunications.KeyProviderInterface.ProfileKeys

If no keys are available, resolving the promise with an empty object is allowed. New keys will be generated automatically and a call to SparkCommunications.KeyProviderInterface#saveProfileKeys will be made.

The promise may be rejected with any error. When the promise is rejected, the SparkCommunications.KeyProviderInterface#profileKeysImportFailed function will be called with the error used to reject the promise to ask the application to provide feedback in how it would like the SDK to handle the failure.

getPublicKeys(regId) → Promise containing SparkCommunications.KeyProviderInterface.PublicKeys

Get the public key data for the user identified by their regId.

Parameter

Name Type Optional Description

regId

string

 

The regId of the user whose public keys are to be retrieved.

Returns

Promise containing SparkCommunications.KeyProviderInterface.PublicKeys

The promise of the user's public encryption and signing keys.

The promise may be rejected with any error because the keys were not found or they failed to decode. When this occurs, the user cannot be invited to join chats and any messages from the user in a chat will not be verifiable.

profileKeysImportFailed([error]) → Promise containing SparkCommunications.KeyProviderInterface.FailureChoice

Called when the keys returned via SparkCommunications.KeyProviderInterface#getProfileKeys have failed to import. The application should return an indication of how it would like the SDK to handle the failure.

Parameter

Name Type Optional Description

error

any

Yes

Any error thrown synchronously or used to reject a promise while interacting with the application supplied KeyProviderInterface implementation object to get the profile keys will be captured and returned to the application code via this parameter. This will be undefined when the failure occurs outside of application provided code.

Returns

Promise containing SparkCommunications.KeyProviderInterface.FailureChoice

The way the application would like the SDK to handle the failure to import the profile keys.

This returns a promise to enable the application to delay the next call to SparkCommunications.KeyProviderInterface#getProfileKeys until the application is ready.

When the promise is rejected for any reason, setup of the SDK will be aborted.

removeChatKey(chatId)

Remove the chat key data associated with the given chatId.

It is the application's responsibility to ensure that the chat key data is removed from storage.

Failure to successfully remove the chat key data will result in a leakage of chat keys in external storage.

Parameter

Name Type Optional Description

chatId

string

 

The identifier for the chat whose chat key is to be removed from the key provider and its underlying storage.

Returns

void

saveChatKey(chatId, key)

Save the chat key data associated with the given chatId.

It is the application's responsibility to ensure that the chat key data is safely stored and can be retrieved during the next session.

Failure to successfully save the chat key data will result in the chat identified by chatId being inaccessible during the next session. The user will have to leave the chat and get re-invited to recover the chat key.

Parameters

Name Type Optional Description

chatId

string

 

The identifier for the chat whose chat key is to be stored by the key provider in its underlying storage.

key

Uint8Array

 

The key data.

Returns

void

saveProfileKeys(keys) → Promise

Save the local user's encryption and signing key pairs.

It is the application's responsibility to ensure that these keys are safely stored and can be retrieved during the next session.

Failure to successfully save the keys will have the following impacts on behaviour:

  1. Other users cannot invite the local user to chats because the chat key will not be encrypted with current public encryption key.
  2. Other users will not be able to verify any new message sent to a chat during this session because the user's current public signing key will not be available for others to use.
  3. Messages sent during this session will not be verifiable as being sent by the local user during the next session because the keys used for the current session will have been lost.

Parameter

Name Type Optional Description

keys

SparkCommunications.KeyProviderInterface.ProfileKeys

 

The local user's encryption and signing key pairs.

Returns

Promise

A promise indicating that the keys have been saved. The return value of the promise is ignored. Rejecting the promise is likewise ignored. Be aware that if the KeyProviderInterface implementation cannot later save the keys through some internal mechanism, then the messages sent and received during this session will become impossible to decrypt once the session ends.

Abstract types

static

ProfileKeys  Object

A structure to encapsulate the local user's encryption and signing key pairs.

Properties

Name Type Optional Description

privateEncryptionKey

Uint8Array

 

The private encryption key data for the local user.

privateSigningKey

Uint8Array

 

The private signing key data for the local user.

publicEncryptionKey

Uint8Array

 

The public encryption key data for the local user.

publicSigningKey

Uint8Array

 

The public signing key data for the local user.

static

PublicKeys  Object

A structure to encapsulate a user's public keys that may be used for encryption and signing.

Properties

Name Type Optional Description

encryptionKey

Uint8Array

 

The public encryption key data for the user.

signingKey

Uint8Array

 

The public signing key data for the user.