Skip to content

SealdSDK

class SealdSDK@JvmOverloadsconstructor(apiURL: String = "https://api.seald.io/", appId: String, dbPath: String? = null, dbb64SymKey: String? = null, instanceName: String = "SealdSDK", logLevel: Byte = 0, logNoColor: Boolean = true, encryptionSessionCacheTTL: Duration? = Duration.ZERO, keySize: Int = 4096)

This is the main class for the Seald SDK. It represents an instance of the Seald SDK.

Parameters

apiURLThe Seald server for this instance to use. This value is given on your Seald dashboard.
appIdThe ID given by the Seald server to your app. This value is given on your Seald dashboard.
dbPathThe path where to store the local Seald database. If no path is passed, uses an in-memory only database.
dbb64SymKeyThe encryption key with which to encrypt the local Seald database. Required when passing dbPath. This must be the Base64 string encoding of a cryptographically random buffer of 64 bytes.
instanceNameAn arbitrary name to give to this Seald instance. Can be useful for debugging when multiple instances are running in parallel, as it is added to logs.
logLevelThe minimum level of logs you want. All logs of this level or above will be displayed. -1: Trace; 0: Debug; 1: Info; 2: Warn; 3: Error; 4: Fatal; 5: Panic; 6: NoLevel; 7: Disabled.
logNoColorShould be set to false if you want to enable colors in the log output. Defaults to true.
encryptionSessionCacheTTLThe duration of cache lifetime. null to cache forever. Default to 0 (no cache).
keySizeThe Asymmetric key size for newly generated keys. Defaults to 4096. Warning: for security, it is extremely not recommended to lower this value. For advanced use only.

Throws

SealdException

Constructors

SealdSDK@JvmOverloads
constructor(apiURL: String = "https://api.seald.io/", appId: String, dbPath: String? = null, dbb64SymKey: String? = null, instanceName: String = "SealdSDK", logLevel: Byte = 0, logNoColor: Boolean = true, encryptionSessionCacheTTL: Duration? = Duration.ZERO, keySize: Int = 4096)

Functions

NameSummary
addConnector@JvmOverloads
fun addConnector(value: String, connectorType: ConnectorType, preValidationToken: PreValidationToken? = null): Connector
Add a connector to the current identity. If no preValidationToken is given, the connector will need to be validated before use.
addConnectorAsync@JvmOverloads
suspend fun addConnectorAsync(value: String, connectorType: ConnectorType, preValidationToken: PreValidationToken? = null): Connector
Add a connector to the current identity. If no preValidationToken is given, the connector will need to be validated before use.
addGroupMembers@JvmOverloads
fun addGroupMembers(groupId: String, membersToAdd: Array<String>, adminsToSet: Array<String> = emptyArray())
Add members to a group. Can only be done by a group administrator. Can also specify which of these newly added group members should also be admins.
addGroupMembersAsync@JvmOverloads
suspend fun addGroupMembersAsync(groupId: String, membersToAdd: Array<String>, adminsToSet: Array<String> = emptyArray())
Add members to a group. Can only be done by a group administrator. Can also specify which of these newly added group members should also be admins.
checkSigchainHash@JvmOverloads
fun checkSigchainHash(userId: String, expectedHash: String, position: Long = -1): CheckSigchainResponse
Verify if a given hash is included in the recipient's sigchain. Use the position option to check the hash of a specific sigchain transaction.
checkSigchainHashAsync@JvmOverloads
suspend fun checkSigchainHashAsync(userId: String, expectedHash: String, position: Long = -1): CheckSigchainResponse
Verify if a given hash is included in the recipient's sigchain. Use the position option to check the hash of a specific sigchain transaction.
closefun close()
Close the current SDK instance. This frees any lock on the current database. After calling close, the instance cannot be used anymore.
closeAsyncsuspend fun closeAsync()
Close the current SDK instance. This frees any lock on the current database. After calling close, the instance cannot be used anymore.
convertTmrAccesses@JvmOverloads
fun convertTmrAccesses(tmrJWT: String, overEncryptionKey: ByteArray, conversionFilters: TMRAccessesConvertFilters? = null, deleteOnConvert: Boolean = true): ConvertTmrAccessesResponse
Convert all TMR Accesses addressed to a given auth factor and matching specified filters to classic message keys. All TMR accesses matching the specified filters must have been encrypted with the same overEncryptionKey.
convertTmrAccessesAsync@JvmOverloads
suspend fun convertTmrAccessesAsync(tmrJWT: String, overEncryptionKey: ByteArray, conversionFilters: TMRAccessesConvertFilters? = null, deleteOnConvert: Boolean = true): ConvertTmrAccessesResponse
Convert all TMR Accesses addressed to a given auth factor and matching specified filters to classic message keys. All TMR accesses matching the specified filters must have been encrypted with the same overEncryptionKey.
createAccount@JvmOverloads
fun createAccount(signupJWT: String, displayName: String = "", deviceName: String = "", expireAfter: Duration = Duration.ofDays(365 * 5)): AccountInfo
Create a new Seald SDK account for this Seald SDK instance. This function can only be called if the current SDK instance does not have an account yet.
createAccountAsync@JvmOverloads
suspend fun createAccountAsync(signupJWT: String, displayName: String = "", deviceName: String = "", expireAfter: Duration = Duration.ofDays(365 * 5)): AccountInfo
Create a new Seald SDK account for this Seald SDK instance. This function can only be called if the current SDK instance does not have an account yet.
createEncryptionSession@JvmOverloads
fun createEncryptionSession(recipients: Array<RecipientWithRights>, useCache: Boolean = true): EncryptionSession
Create an encryption session, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt multiple messages. Warning : if you want to be able to retrieve the session later, you must put your own UserId in the recipients argument.
createEncryptionSessionAsync@JvmOverloads
suspend fun createEncryptionSessionAsync(recipients: Array<RecipientWithRights>, useCache: Boolean = true): EncryptionSession
Create an encryption session, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt multiple messages. Warning : if you want to be able to retrieve the session later, you must put your own UserId in the recipients argument.
createGroupfun createGroup(groupName: String, members: Array<String>, admins: Array<String>): String
Create a group, and returns the created group's ID. admins must also be members. admins must include yourself.
createGroupAsyncsuspend fun createGroupAsync(groupName: String, members: Array<String>, admins: Array<String>): String
Create a group, and returns the created group's ID. admins must also be members. admins must include yourself.
createSubIdentity@JvmOverloads
fun createSubIdentity(deviceName: String, expireAfter: Duration = Duration.ofDays(365 * 5)): CreateSubIdentityResponse
Create a new sub-identity, or new device, for the current user account. After creating this new device, you will probably want to call SealdSDK.massReencrypt, so that the newly created device will be able to decrypt EncryptionSessions previously created for this account.
createSubIdentityAsync@JvmOverloads
suspend fun createSubIdentityAsync(deviceName: String, expireAfter: Duration = Duration.ofDays(365 * 5)): CreateSubIdentityResponse
Create a new sub-identity, or new device, for the current user account. After creating this new device, you will probably want to call SealdSDK.massReencrypt, so that the newly created device will be able to decrypt EncryptionSessions previously created for this account.
devicesMissingKeys@JvmOverloads
fun devicesMissingKeys(forceLocalAccountUpdate: Boolean = false): Array<DeviceMissingKeys>
List which of the devices of the current account are missing keys, so you can call SealdSDK.massReencrypt for them.
devicesMissingKeysAsync@JvmOverloads
suspend fun devicesMissingKeysAsync(forceLocalAccountUpdate: Boolean = false): Array<DeviceMissingKeys>
List which of the devices of the current account are missing keys, so you can call SealdSDK.massReencrypt for them.
exportIdentityfun exportIdentity(): ByteArray
Export the current device as an identity export.
exportIdentityAsyncsuspend fun exportIdentityAsync(): ByteArray
Export the current device as an identity export.
getConnectorsFromSealdIdfun getConnectorsFromSealdId(sealdId: String): Array<Connector>
List all connectors know locally for a given sealdId.
getConnectorsFromSealdIdAsyncsuspend fun getConnectorsFromSealdIdAsync(sealdId: String): Array<Connector>
List all connectors know locally for a given sealdId.
getCurrentAccountInfofun getCurrentAccountInfo(): AccountInfo?
Return information about the current account, or null if there is none.
getCurrentAccountInfoAsyncsuspend fun getCurrentAccountInfoAsync(): AccountInfo?
Return information about the current account, or null if there is none.
getSealdIdsFromConnectorsfun getSealdIdsFromConnectors(connectorTypeValues: Array<ConnectorTypeValue>): Array<String>
Get all the info for the given connectors to look for, updates the local cache of connectors, and returns a slice with the corresponding SealdIds. SealdIds are not de-duped and can appear for multiple connector values. If one of the connectors is not assigned to a Seald user, this will return a ErrorGetSealdIdsUnknownConnector error, with the details of the missing connector.
getSealdIdsFromConnectorsAsyncsuspend fun getSealdIdsFromConnectorsAsync(connectorTypeValues: Array<ConnectorTypeValue>): Array<String>
Get all the info for the given connectors to look for, updates the local cache of connectors, and returns a slice with the corresponding SealdIds. SealdIds are not de-duped and can appear for multiple connector values. If one of the connectors is not assigned to a Seald user, this will return a ErrorGetSealdIdsUnknownConnector error, with the details of the missing connector.
getSigchainHash@JvmOverloads
fun getSigchainHash(userId: String, position: Long = -1): GetSigchainResponse
Get a user's sigchain transaction hash at index position.
getSigchainHashAsync@JvmOverloads
suspend fun getSigchainHashAsync(userId: String, position: Long = -1): GetSigchainResponse
Get a user's sigchain transaction hash at index position.
heartbeatfun heartbeat()
Just call the Seald server, without doing anything. This may be used for example to verify that the current instance has a valid identity.
heartbeatAsyncsuspend fun heartbeatAsync()
Just call the Seald server, without doing anything. This may be used for example to verify that the current instance has a valid identity.
importIdentityfun importIdentity(identity: ByteArray)
Load an identity export into the current SDK instance. This function can only be called if the current SDK instance does not have an account yet.
importIdentityAsyncsuspend fun importIdentityAsync(identity: ByteArray)
Load an identity export into the current SDK instance. This function can only be called if the current SDK instance does not have an account yet.
listConnectorsfun listConnectors(): Array<Connector>
List connectors associated to the current account.
listConnectorsAsyncsuspend fun listConnectorsAsync(): Array<Connector>
List connectors associated to the current account.
massReencrypt@JvmOverloads
fun massReencrypt(deviceId: String, options: MassReencryptOptions = MassReencryptOptions()): MassReencryptResponse
Retrieve, re-encrypt, and add missing keys for a certain device.
massReencryptAsync@JvmOverloads
suspend fun massReencryptAsync(deviceId: String, options: MassReencryptOptions = MassReencryptOptions()): MassReencryptResponse
Retrieve, re-encrypt, and add missing keys for a certain device.
pushJWTfun pushJWT(jwt: String)
Push a given JWT to the Seald server, for example to add a connector to the current account.
pushJWTAsyncsuspend fun pushJWTAsync(jwt: String)
Push a given JWT to the Seald server, for example to add a connector to the current account.
removeConnectorfun removeConnector(connectorId: String): Connector
Remove a connector belonging to the current account.
removeConnectorAsyncsuspend fun removeConnectorAsync(connectorId: String): Connector
Remove a connector belonging to the current account.
removeGroupMembersfun removeGroupMembers(groupId: String, membersToRemove: Array<String>)
Remove members from the group. Can only be done by a group administrator. You should call renewGroupKey after this.
removeGroupMembersAsyncsuspend fun removeGroupMembersAsync(groupId: String, membersToRemove: Array<String>)
Remove members from the group. Can only be done by a group administrator. You should call renewGroupKey after this.
renewGroupKeyfun renewGroupKey(groupId: String)
Renew the group's private key. Can only be done by a group administrator. Should be called after removing members from the group.
renewGroupKeyAsyncsuspend fun renewGroupKeyAsync(groupId: String)
Renew the group's private key. Can only be done by a group administrator. Should be called after removing members from the group.
renewKeys@JvmOverloads
fun renewKeys(expireAfter: Duration = Duration.ofDays(365 * 5))
Renew the keys of the current device, extending their validity. If the current device has expired, you will need to call renewKeys before you are able to do anything else. Warning: if the identity of the current device is stored externally, for example on SSKS, you will want to re-export it and store it again, otherwise the previously stored identity will not be recognized anymore.
renewKeysAsync@JvmOverloads
suspend fun renewKeysAsync(expireAfter: Duration = Duration.ofDays(365 * 5))
Renew the keys of the current device, extending their validity. If the current device has expired, you will need to call renewKeys before you are able to do anything else. Warning: if the identity of the current device is stored externally, for example on SSKS, you will want to re-export it and store it again, otherwise the previously stored identity will not be recognized anymore.
retrieveConnectorfun retrieveConnector(connectorId: String): Connector
Retrieve a connector by its connectorId, then updates the local cache of connectors.
retrieveConnectorAsyncsuspend fun retrieveConnectorAsync(connectorId: String): Connector
Retrieve a connector by its connectorId, then updates the local cache of connectors.
retrieveEncryptionSession@JvmOverloads
fun retrieveEncryptionSession(sessionId: String, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session with the sessionId, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionAsync@JvmOverloads
suspend fun retrieveEncryptionSessionAsync(sessionId: String, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session with the sessionId, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionByTmr@JvmOverloads
fun retrieveEncryptionSessionByTmr(tmrJWT: String, sessionId: String, overEncryptionKey: ByteArray, tmrAccessesFilters: TMRAccessesRetrievalFilters? = null, tryIfMultiple: Boolean = true, useCache: Boolean = true): EncryptionSession
Retrieve an encryption session with a TMR access JWT, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt this file.
retrieveEncryptionSessionByTmrAsync@JvmOverloads
suspend fun retrieveEncryptionSessionByTmrAsync(tmrJWT: String, sessionId: String, overEncryptionKey: ByteArray, tmrAccessesFilters: TMRAccessesRetrievalFilters? = null, tryIfMultiple: Boolean = true, useCache: Boolean = true): EncryptionSession
Retrieve an encryption session with a TMR access JWT, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt this file.
retrieveEncryptionSessionFromBytes@JvmOverloads
fun retrieveEncryptionSessionFromBytes(fileByteArray: ByteArray, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session from a ByteArray, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt this file.
retrieveEncryptionSessionFromBytesAsync@JvmOverloads
suspend fun retrieveEncryptionSessionFromBytesAsync(fileByteArray: ByteArray, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session from a ByteArray, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt this file.
retrieveEncryptionSessionFromFile@JvmOverloads
fun retrieveEncryptionSessionFromFile(fileUri: String, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session from a file URI, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt this file.
retrieveEncryptionSessionFromFileAsync@JvmOverloads
suspend fun retrieveEncryptionSessionFromFileAsync(fileUri: String, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session from a file URI, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt this file.
retrieveEncryptionSessionFromMessage@JvmOverloads
fun retrieveEncryptionSessionFromMessage(message: String, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session from a seald message, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionFromMessageAsync@JvmOverloads
suspend fun retrieveEncryptionSessionFromMessageAsync(message: String, useCache: Boolean = true, lookupProxyKey: Boolean = false, lookupGroupKey: Boolean = true): EncryptionSession
Retrieve an encryption session from a seald message, and returns the associated EncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
setGroupAdminsfun setGroupAdmins(groupId: String, addToAdmins: Array<String> = emptyArray(), removeFromAdmins: Array<String> = emptyArray())
Add some existing group members to the group admins, and/or removes admin status from some existing group admins. Can only be done by a group administrator.
setGroupAdminsAsyncsuspend fun setGroupAdminsAsync(groupId: String, addToAdmins: Array<String> = emptyArray(), removeFromAdmins: Array<String> = emptyArray())
Add some existing group members to the group admins, and/or removes admin status from some existing group admins. Can only be done by a group administrator.
updateCurrentDevicefun updateCurrentDevice()
Updates the locally known information about the current device. You should never have to call this manually, except if you getting null in AccountInfo.deviceExpires, which can happen if migrating from an older version of the SDK, or if the internal call to updateCurrentDevice failed when calling SealdSdk.importIdentity.
updateCurrentDeviceAsyncsuspend fun updateCurrentDeviceAsync()
Updates the locally known information about the current device. You should never have to call this manually, except if you getting null in AccountInfo.deviceExpires, which can happen if migrating from an older version of the SDK, or if the internal call to updateCurrentDevice failed when calling SealdSdk.importIdentity.
validateConnectorfun validateConnector(connectorId: String, challenge: String): Connector
Validate an added connector that was added without a preValidationToken.
validateConnectorAsyncsuspend fun validateConnectorAsync(connectorId: String, challenge: String): Connector
Validate an added connector that was added without a preValidationToken.