Seald: documentation

Français

English

Français

English

class SealdSdk ​

objc
@interface SealdSdk : NSObject
@interface SealdSdk : NSObject

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

MembersDescriptions
initWithApiUrl:appId:dbPath:dbb64SymKey:instanceName:logLevel:logNoColor:encryptionSessionCacheTTL:keySize:error:Initialize a Seald SDK Instance.
closeWithError:Close the current SDK instance. This frees any lock on the current database. After calling close, the instance cannot be used anymore.
closeAsyncWithCompletionHandler:Close the current SDK instance. This frees any lock on the current database. After calling close, the instance cannot be used anymore.
createAccountWithSignupJwt:deviceName:displayName:expireAfter:error: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.
createAccountAsyncWithSignupJwt:deviceName:displayName:expireAfter:completionHandler: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.
getCurrentAccountInfoReturn information about the current account, or nil if there is none.
getCurrentAccountInfoAsyncWithCompletionHandler:Return information about the current account, or nil if there is none.
updateCurrentDeviceWithError:Updates the locally known information about the current device.
updateCurrentDeviceAsyncWithCompletionHandler:Updates the locally known information about the current device.
renewKeysWithExpireAfter:error:Renew the keys of the current device, extending their validity. If the current device has expired, you will need to call renewKeysWithExpireAfter:error: 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.
renewKeysAsyncWithExpireAfter:completionHandler:Renew the keys of the current device, extending their validity. If the current device has expired, you will need to call renewKeysWithExpireAfter:error: 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.
createSubIdentityWithDeviceName:expireAfter:error:Create a new sub-identity, or new device, for the current user account. After creating this new device, you will probably want to call massReencryptWithDeviceId:options:error:, so that the newly created device will be able to decrypt EncryptionSessions previously created for this account.
createSubIdentityAsyncWithDeviceName:expireAfter:completionHandler:Create a new sub-identity, or new device, for the current user account. After creating this new device, you will probably want to call massReencryptWithDeviceId:options:error:, so that the newly created device will be able to decrypt EncryptionSessions previously created for this account.
importIdentity:error: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.
importIdentityAsyncWithIdentity:completionHandler: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.
exportIdentityWithError:Export the current device as an identity export.
exportIdentityAsyncWithCompletionHandler:Export the current device as an identity export.
pushJWT:error:Push a given JWT to the Seald server, for example to add a connector to the current account.
pushJWTAsyncWithJWT:completionHandler:Push a given JWT to the Seald server, for example to add a connector to the current account.
heartbeatWithError:Just call the Seald server, without doing anything. This may be used for example to verify that the current instance has a valid identity.
heartbeatAsyncWithCompletionHandler:Just call the Seald server, without doing anything. This may be used for example to verify that the current instance has a valid identity.
createGroupWithGroupName:members:admins:error:Create a group, and returns the created group's ID. admins must also be members. admins must include yourself.
createGroupAsyncWithGroupName:members:admins:completionHandler:Create a group, and returns the created group's ID. admins must also be members. admins must include yourself.
addGroupMembersWithGroupId:membersToAdd:adminsToSet:error: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.
addGroupMembersAsyncWithGroupId:membersToAdd:adminsToSet:completionHandler: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.
removeGroupMembersWithGroupId:membersToRemove:error:Remove members from the group. Can only be done by a group administrator. You should call renewGroupKeyWithGroupId:error: after this.
removeGroupMembersAsyncWithGroupId:membersToRemove:completionHandler:Remove members from the group. Can only be done by a group administrator. You should call renewGroupKeyWithGroupId:error: after this.
renewGroupKeyWithGroupId:error:Renew the group's private key. Can only be done by a group administrator. Should be called after removing members from the group.
renewGroupKeyAsyncWithGroupId:completionHandler:Renew the group's private key. Can only be done by a group administrator. Should be called after removing members from the group.
setGroupAdminsWithGroupId:addToAdmins:removeFromAdmins:error: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.
setGroupAdminsAsyncWithGroupId:addToAdmins:removeFromAdmins:completionHandler: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.
createEncryptionSessionWithRecipients:useCache:error:Create an encryption session, and returns the associated SealdEncryptionSession 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.
createEncryptionSessionAsyncWithRecipients:useCache:completionHandler:Create an encryption session, and returns the associated SealdEncryptionSession 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.
retrieveEncryptionSessionWithSessionId:useCache:lookupProxyKey:lookupGroupKey:error:Retrieve an encryption session with the sessionId, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionAsyncWithSessionId:useCache:lookupProxyKey:lookupGroupKey:completionHandler:Retrieve an encryption session with the sessionId, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionFromMessage:useCache:lookupProxyKey:lookupGroupKey:error:Retrieve an encryption session from a seald message, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionAsyncFromMessage:useCache:lookupProxyKey:lookupGroupKey:completionHandler:Retrieve an encryption session from a seald message, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionFromFile:useCache:lookupProxyKey:lookupGroupKey:error:Retrieve an encryption session from a file URI, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionAsyncFromFile:useCache:lookupProxyKey:lookupGroupKey:completionHandler:Retrieve an encryption session from a file URI, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionFromBytes:useCache:lookupProxyKey:lookupGroupKey:error:Retrieve an encryption session from an NSData*, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionAsyncFromBytes:useCache:lookupProxyKey:lookupGroupKey:completionHandler:Retrieve an encryption session from an NSData*, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.
retrieveEncryptionSessionByTmr:sessionId:overEncryptionKey:tmrAccessesFilters:tryIfMultiple:useCache:error:Retrieve an encryption session with a TMR access JWT.
retrieveEncryptionSessionAsyncByTmr:sessionId:overEncryptionKey:tmrAccessesFilters:tryIfMultiple:useCache:completionHandler:Retrieve an encryption session with a TMR access JWT.
getSealdIdsFromConnectors:error: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.
getSealdIdsAsyncFromConnectors:completionHandler: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.
getConnectorsFromSealdId:error:List all connectors know locally for a given sealdId.
getConnectorsAsyncFromSealdId:completionHandler:List all connectors know locally for a given sealdId.
addConnectorWithValue:connectorType:preValidationToken:error:Add a connector to the current identity. If no preValidationToken is given, the connector will need to be validated before use.
addConnectorAsyncWithValue:connectorType:preValidationToken:completionHandler:Add a connector to the current identity. If no preValidationToken is given, the connector will need to be validated before use.
validateConnector:challenge:error:Validate an added connector that was added without a preValidationToken.
validateConnectorAsyncWithConnectorId:challenge:completionHandler:Validate an added connector that was added without a preValidationToken.
removeConnector:error:Remove a connector belonging to the current account.
removeConnectorAsyncWithConnectorId:completionHandler:Remove a connector belonging to the current account.
listConnectorsWithError:List connectors associated to the current account.
listConnectorsAsyncWithCompletionHandler:List connectors associated to the current account.
retrieveConnector:error:Retrieve a connector by its connectorId, then updates the local cache of connectors.
retrieveConnectorAsyncWithConnectorId:completionHandler:Retrieve a connector by its connectorId, then updates the local cache of connectors.
massReencryptWithDeviceId:options:error:Retrieve, re-encrypt, and add missing keys for a certain device.
massReencryptAsyncWithDeviceId:options:completionHandler:Retrieve, re-encrypt, and add missing keys for a certain device.
devicesMissingKeysWithForceLocalAccountUpdate:error:List which of the devices of the current account are missing keys, so you can call massReencryptWithDeviceId:options:error: for them.
devicesMissingKeysAsyncWithForceLocalAccountUpdate:completionHandler:List which of the devices of the current account are missing keys, so you can call massReencryptWithDeviceId:options:error: for them.
getSigchainHashWithUserId:position:error:Get a user's sigchain transaction hash at index position.
getSigchainHashAsyncWithUserId:position:completionHandler:Get a user's sigchain transaction hash at index position.
checkSigchainHashWithUserId:expectedHash:position:error: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.
checkSigchainHashAsyncWithUserId:expectedHash:position:completionHandler: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.
convertTmrAccesses:overEncryptionKey:conversionFilters:deleteOnConvert:error: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:overEncryptionKey:conversionFilters:deleteOnConvert:completionHandler: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.

initWithApiUrl:appId:dbPath:dbb64SymKey:instanceName:logLevel:logNoColor:encryptionSessionCacheTTL:keySize:error: ​

objc
- (instancetype) initWithApiUrl:(const NSString *)apiUrl
                          appId:(const NSString *)appId
                         dbPath:(const NSString *)dbPath
                    dbb64SymKey:(const NSString *)dbb64SymKey
                   instanceName:(const NSString *)instanceName
                       logLevel:(const NSInteger)logLevel
                     logNoColor:(const BOOL)logNoColor
      encryptionSessionCacheTTL:(const NSTimeInterval)encryptionSessionCacheTTL
                        keySize:(const NSInteger)keySize
                          error:(NSError *_Nullable *)error;
- (instancetype) initWithApiUrl:(const NSString *)apiUrl
                          appId:(const NSString *)appId
                         dbPath:(const NSString *)dbPath
                    dbb64SymKey:(const NSString *)dbb64SymKey
                   instanceName:(const NSString *)instanceName
                       logLevel:(const NSInteger)logLevel
                     logNoColor:(const BOOL)logNoColor
      encryptionSessionCacheTTL:(const NSTimeInterval)encryptionSessionCacheTTL
                        keySize:(const NSInteger)keySize
                          error:(NSError *_Nullable *)error;

Initialize a Seald SDK Instance.

Parameters ​

  • apiUrl The Seald server for this instance to use. This value is given on your Seald dashboard.

  • appId The ID given by the Seald server to your app. This value is given on your Seald dashboard.

  • dbPath The path where to store the local Seald database. If no path is passed, uses an in-memory only database.

  • dbb64SymKey The 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 NSData of 64 bytes.

  • instanceName An 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.

  • logLevel The 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.

  • logNoColor Should be set to NO if you want to enable colors in the log output, YES if you don't.

  • encryptionSessionCacheTTL The duration of cache lifetime. -1 to cache forever. Default to 0 (no cache).

  • keySize The Asymmetric key size for newly generated keys. Defaults to 4096. Warning: for security, it is extremely not recommended to lower this value.

  • error Error pointer.

closeWithError: ​

objc
- (void) closeWithError:(NSError *_Nullable *)error;
- (void) closeWithError:(NSError *_Nullable *)error;

Close the current SDK instance. This frees any lock on the current database. After calling close, the instance cannot be used anymore.

Parameters ​

  • error Error pointer.

closeAsyncWithCompletionHandler: ​

objc
- (void) closeAsyncWithCompletionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) closeAsyncWithCompletionHandler:(void(^)(NSError *_Nullable error))completionHandler;

Close the current SDK instance. This frees any lock on the current database. After calling close, the instance cannot be used anymore.

Parameters ​

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

createAccountWithSignupJwt:deviceName:displayName:expireAfter:error: ​

objc
- (SealdAccountInfo *) createAccountWithSignupJwt:(const NSString *)signupJwt
                                       deviceName:(const NSString *)deviceName
                                      displayName:(const NSString *)displayName
                                      expireAfter:(const NSTimeInterval)expireAfter
                                            error:(NSError *_Nullable *)error;
- (SealdAccountInfo *) createAccountWithSignupJwt:(const NSString *)signupJwt
                                       deviceName:(const NSString *)deviceName
                                      displayName:(const NSString *)displayName
                                      expireAfter:(const NSTimeInterval)expireAfter
                                            error:(NSError *_Nullable *)error;

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.

Parameters ​

  • signupJwt The JWT to allow this SDK instance to create an account.

  • deviceName A name for the device to create. This is metadata, useful on the Seald Dashboard for recognizing this device.

  • displayName A name for the user to create. This is metadata, useful on the Seald Dashboard for recognizing this user.

  • expireAfter The duration during which the created device key will be valid without renewal. Optional, defaults to 5 years.

  • error Error pointer.

Returns ​

A SealdAccountInfo instance, containing the Seald ID of the newly created Seald user, the device ID, and the date at which the current device keys will expire.

createAccountAsyncWithSignupJwt:deviceName:displayName:expireAfter:completionHandler: ​

objc
- (void) createAccountAsyncWithSignupJwt:(const NSString *)signupJwt
                              deviceName:(const NSString *)deviceName
                             displayName:(const NSString *)displayName
                             expireAfter:(const NSTimeInterval)expireAfter
                       completionHandler:(void(^)(SealdAccountInfo *accountInfo, NSError *_Nullable error))completionHandler;
- (void) createAccountAsyncWithSignupJwt:(const NSString *)signupJwt
                              deviceName:(const NSString *)deviceName
                             displayName:(const NSString *)displayName
                             expireAfter:(const NSTimeInterval)expireAfter
                       completionHandler:(void(^)(SealdAccountInfo *accountInfo, NSError *_Nullable error))completionHandler;

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.

Parameters ​

  • signupJwt The JWT to allow this SDK instance to create an account.

  • deviceName A name for the device to create. This is metadata, useful on the Seald Dashboard for recognizing this device.

  • displayName A name for the user to create. This is metadata, useful on the Seald Dashboard for recognizing this user.

  • expireAfter The duration during which the created device key will be valid without renewal. Optional, defaults to 5 years.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdAccountInfo* representing the created user and a NSError that indicates if any error occurred.

getCurrentAccountInfo ​

objc
- (nullable SealdAccountInfo *) getCurrentAccountInfo;
- (nullable SealdAccountInfo *) getCurrentAccountInfo;

Return information about the current account, or nil if there is none.

Returns ​

A SealdAccountInfo instance, containing the Seald ID of the local Seald user, the device ID, and the date at which the current device keys will expire. nil if there is no local user.

getCurrentAccountInfoAsyncWithCompletionHandler: ​

objc
- (void) getCurrentAccountInfoAsyncWithCompletionHandler:(void(^)(SealdAccountInfo *_Nullable))completionHandler;
- (void) getCurrentAccountInfoAsyncWithCompletionHandler:(void(^)(SealdAccountInfo *_Nullable))completionHandler;

Return information about the current account, or nil if there is none.

Parameters ​

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdAccountInfo* containing the current user infos and a NSError* that indicates if any error occurred.

updateCurrentDeviceWithError: ​

objc
- (void) updateCurrentDeviceWithError:(NSError *_Nullable *)error;
- (void) updateCurrentDeviceWithError:(NSError *_Nullable *)error;

Updates the locally known information about the current device.

You should never have to call this manually, except if you getting nil in sealdAccountInfo.deviceExpires, which can happen if migrating from an older version of the SDK, or if the internal call to updateCurrentDevice failed when calling importIdentity:error:.

Parameters ​

  • error Error pointer.

updateCurrentDeviceAsyncWithCompletionHandler: ​

objc
- (void) updateCurrentDeviceAsyncWithCompletionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) updateCurrentDeviceAsyncWithCompletionHandler:(void(^)(NSError *_Nullable error))completionHandler;

Updates the locally known information about the current device.

You should never have to call this manually, except if you getting nil in sealdAccountInfo.deviceExpires, which can happen if migrating from an older version of the SDK, or if the internal call to updateCurrentDevice failed when calling importIdentity:error:.

Parameters ​

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

renewKeysWithExpireAfter:error: ​

objc
- (void) renewKeysWithExpireAfter:(const NSTimeInterval)expireAfter
                            error:(NSError *_Nullable *)error;
- (void) renewKeysWithExpireAfter:(const NSTimeInterval)expireAfter
                            error:(NSError *_Nullable *)error;

Renew the keys of the current device, extending their validity. If the current device has expired, you will need to call renewKeysWithExpireAfter:error: 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.

Parameters ​

  • expireAfter The duration during which the renewed device key will be valid without further renewal. Optional, defaults to 5 years.

  • error Error pointer.

renewKeysAsyncWithExpireAfter:completionHandler: ​

objc
- (void) renewKeysAsyncWithExpireAfter:(const NSTimeInterval)expireAfter
                     completionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) renewKeysAsyncWithExpireAfter:(const NSTimeInterval)expireAfter
                     completionHandler:(void(^)(NSError *_Nullable error))completionHandler;

Renew the keys of the current device, extending their validity. If the current device has expired, you will need to call renewKeysWithExpireAfter:error: 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.

Parameters ​

  • expireAfter The duration during which the renewed device key will be valid without further renewal. Optional, defaults to 5 years.

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

createSubIdentityWithDeviceName:expireAfter:error: ​

objc
- (SealdCreateSubIdentityResponse *) createSubIdentityWithDeviceName:(const NSString *)deviceName
                                                         expireAfter:(const NSTimeInterval)expireAfter
                                                               error:(NSError *_Nullable *)error;
- (SealdCreateSubIdentityResponse *) createSubIdentityWithDeviceName:(const NSString *)deviceName
                                                         expireAfter:(const NSTimeInterval)expireAfter
                                                               error:(NSError *_Nullable *)error;

Create a new sub-identity, or new device, for the current user account. After creating this new device, you will probably want to call massReencryptWithDeviceId:options:error:, so that the newly created device will be able to decrypt EncryptionSessions previously created for this account.

Parameters ​

  • deviceName An optional name for the device to create. This is metadata, useful on the Seald Dashboard for recognizing this device. Optional.

  • expireAfter The duration during which the device key for the device to create will be valid without renewal. Optional, defaults to 5 years.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

Returns ​

A CreateSubIdentityResponse instance, containing deviceId (the ID of the newly created device) and backupKey (the identity export of the newly created sub-identity).

createSubIdentityAsyncWithDeviceName:expireAfter:completionHandler: ​

objc
- (void) createSubIdentityAsyncWithDeviceName:(const NSString *)deviceName
                                  expireAfter:(const NSTimeInterval)expireAfter
                            completionHandler:(void(^)(SealdCreateSubIdentityResponse *response, NSError *_Nullable error))completionHandler;
- (void) createSubIdentityAsyncWithDeviceName:(const NSString *)deviceName
                                  expireAfter:(const NSTimeInterval)expireAfter
                            completionHandler:(void(^)(SealdCreateSubIdentityResponse *response, NSError *_Nullable error))completionHandler;

Create a new sub-identity, or new device, for the current user account. After creating this new device, you will probably want to call massReencryptWithDeviceId:options:error:, so that the newly created device will be able to decrypt EncryptionSessions previously created for this account.

Parameters ​

  • deviceName An optional name for the device to create. This is metadata, useful on the Seald Dashboard for recognizing this device. Optional.

  • expireAfter The duration during which the device key for the device to create will be valid without renewal. Optional, defaults to 5 years.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdCreateSubIdentityResponse* representing the created sub-identity and a NSError that indicates if any error occurred.

importIdentity:error: ​

objc
- (void) importIdentity:(const NSData *)identity
                  error:(NSError *_Nullable *)error;
- (void) importIdentity:(const NSData *)identity
                  error:(NSError *_Nullable *)error;

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.

Parameters ​

  • identity The identity export that this SDK instance should import.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

importIdentityAsyncWithIdentity:completionHandler: ​

objc
- (void) importIdentityAsyncWithIdentity:(const NSData *)identity
                       completionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) importIdentityAsyncWithIdentity:(const NSData *)identity
                       completionHandler:(void(^)(NSError *_Nullable error))completionHandler;

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.

Parameters ​

  • identity The identity export that this SDK instance should import.

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

exportIdentityWithError: ​

objc
- (NSData *) exportIdentityWithError:(NSError *_Nullable *)error;
- (NSData *) exportIdentityWithError:(NSError *_Nullable *)error;

Export the current device as an identity export.

Parameters ​

  • error If an error occurs, upon return contains an NSError object that describes the problem.

Returns ​

The identity export of the current identity of this SDK instance.

exportIdentityAsyncWithCompletionHandler: ​

objc
- (void) exportIdentityAsyncWithCompletionHandler:(void(^)(NSData *identity, NSError *_Nullable error))completionHandler;
- (void) exportIdentityAsyncWithCompletionHandler:(void(^)(NSData *identity, NSError *_Nullable error))completionHandler;

Export the current device as an identity export.

Parameters ​

  • completionHandler A callback called after function execution. This callback take two arguments, a NSData* containing the exported identity, and a NSError that indicates if any error occurred.

pushJWT:error: ​

objc
- (void) pushJWT:(const NSString *)jwt
           error:(NSError *_Nullable *)error;
- (void) pushJWT:(const NSString *)jwt
           error:(NSError *_Nullable *)error;

Push a given JWT to the Seald server, for example to add a connector to the current account.

Parameters ​

  • jwt The JWT to push

  • error If an error occurs, upon return contains an NSError object that describes the problem.

pushJWTAsyncWithJWT:completionHandler: ​

objc
- (void) pushJWTAsyncWithJWT:(const NSString *)jwt
           completionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) pushJWTAsyncWithJWT:(const NSString *)jwt
           completionHandler:(void(^)(NSError *_Nullable error))completionHandler;

Push a given JWT to the Seald server, for example to add a connector to the current account.

Parameters ​

  • jwt The JWT to push

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

heartbeatWithError: ​

objc
- (void) heartbeatWithError:(NSError *_Nullable *)error;
- (void) heartbeatWithError:(NSError *_Nullable *)error;

Just call the Seald server, without doing anything. This may be used for example to verify that the current instance has a valid identity.

Parameters ​

  • error If an error occurs, upon return contains an NSError object that describes the problem.

heartbeatAsyncWithCompletionHandler: ​

objc
- (void) heartbeatAsyncWithCompletionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) heartbeatAsyncWithCompletionHandler:(void(^)(NSError *_Nullable error))completionHandler;

Just call the Seald server, without doing anything. This may be used for example to verify that the current instance has a valid identity.

Parameters ​

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

createGroupWithGroupName:members:admins:error: ​

objc
- (NSString *) createGroupWithGroupName:(const NSString *)groupName
                                members:(const NSArray< NSString * > *)members
                                 admins:(const NSArray< NSString * > *)admins
                                  error:(NSError *_Nullable *)error;
- (NSString *) createGroupWithGroupName:(const NSString *)groupName
                                members:(const NSArray< NSString * > *)members
                                 admins:(const NSArray< NSString * > *)admins
                                  error:(NSError *_Nullable *)error;

Create a group, and returns the created group's ID. admins must also be members. admins must include yourself.

Parameters ​

  • groupName A name for the group. This is metadata, useful on the Seald Dashboard for recognizing this user.

  • members The Seald IDs of the members to add to the group. Must include yourself.

  • admins The Seald IDs of the members to also add as group admins. Must include yourself.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

Returns ​

The ID of the created group.

createGroupAsyncWithGroupName:members:admins:completionHandler: ​

objc
- (void) createGroupAsyncWithGroupName:(const NSString *)groupName
                               members:(const NSArray< NSString * > *)members
                                admins:(const NSArray< NSString * > *)admins
                     completionHandler:(void(^)(NSString *groupId, NSError *_Nullable error))completionHandler;
- (void) createGroupAsyncWithGroupName:(const NSString *)groupName
                               members:(const NSArray< NSString * > *)members
                                admins:(const NSArray< NSString * > *)admins
                     completionHandler:(void(^)(NSString *groupId, NSError *_Nullable error))completionHandler;

Create a group, and returns the created group's ID. admins must also be members. admins must include yourself.

Parameters ​

  • groupName A name for the group. This is metadata, useful on the Seald Dashboard for recognizing this user.

  • members The Seald IDs of the members to add to the group. Must include yourself.

  • admins The Seald IDs of the members to also add as group admins. Must include yourself.

  • completionHandler A callback called after function execution. This callback take two arguments, a NSString* containint the ID of the created group and a NSError that indicates if any error occurred.

addGroupMembersWithGroupId:membersToAdd:adminsToSet:error: ​

objc
- (void) addGroupMembersWithGroupId:(const NSString *)groupId
                       membersToAdd:(const NSArray< NSString * > *)membersToAdd
                        adminsToSet:(const NSArray< NSString * > *)adminsToSet
                              error:(NSError *_Nullable *)error;
- (void) addGroupMembersWithGroupId:(const NSString *)groupId
                       membersToAdd:(const NSArray< NSString * > *)membersToAdd
                        adminsToSet:(const NSArray< NSString * > *)adminsToSet
                              error:(NSError *_Nullable *)error;

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.

Parameters ​

  • groupId The group in which to add members.

  • membersToAdd The Seald IDs of the members to add to the group.

  • adminsToSet The Seald IDs of the newly added members to also set as group admins.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

addGroupMembersAsyncWithGroupId:membersToAdd:adminsToSet:completionHandler: ​

objc
- (void) addGroupMembersAsyncWithGroupId:(const NSString *)groupId
                            membersToAdd:(const NSArray< NSString * > *)membersToAdd
                             adminsToSet:(const NSArray< NSString * > *)adminsToSet
                       completionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) addGroupMembersAsyncWithGroupId:(const NSString *)groupId
                            membersToAdd:(const NSArray< NSString * > *)membersToAdd
                             adminsToSet:(const NSArray< NSString * > *)adminsToSet
                       completionHandler:(void(^)(NSError *_Nullable error))completionHandler;

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.

Parameters ​

  • groupId The group in which to add members.

  • membersToAdd The Seald IDs of the members to add to the group.

  • adminsToSet The Seald IDs of the newly added members to also set as group admins.

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

removeGroupMembersWithGroupId:membersToRemove:error: ​

objc
- (void) removeGroupMembersWithGroupId:(const NSString *)groupId
                       membersToRemove:(const NSArray< NSString * > *)membersToRemove
                                 error:(NSError *_Nullable *)error;
- (void) removeGroupMembersWithGroupId:(const NSString *)groupId
                       membersToRemove:(const NSArray< NSString * > *)membersToRemove
                                 error:(NSError *_Nullable *)error;

Remove members from the group. Can only be done by a group administrator. You should call renewGroupKeyWithGroupId:error: after this.

Parameters ​

  • groupId The group from which to remove members.

  • membersToRemove The Seald IDs of the members to remove from the group.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

removeGroupMembersAsyncWithGroupId:membersToRemove:completionHandler: ​

objc
- (void) removeGroupMembersAsyncWithGroupId:(const NSString *)groupId
                            membersToRemove:(const NSArray< NSString * > *)membersToRemove
                          completionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) removeGroupMembersAsyncWithGroupId:(const NSString *)groupId
                            membersToRemove:(const NSArray< NSString * > *)membersToRemove
                          completionHandler:(void(^)(NSError *_Nullable error))completionHandler;

Remove members from the group. Can only be done by a group administrator. You should call renewGroupKeyWithGroupId:error: after this.

Parameters ​

  • groupId The group from which to remove members.

  • membersToRemove The Seald IDs of the members to remove from the group.

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

renewGroupKeyWithGroupId:error: ​

objc
- (void) renewGroupKeyWithGroupId:(const NSString *)groupId
                            error:(NSError *_Nullable *)error;
- (void) renewGroupKeyWithGroupId:(const NSString *)groupId
                            error:(NSError *_Nullable *)error;

Renew the group's private key. Can only be done by a group administrator. Should be called after removing members from the group.

Parameters ​

  • groupId The group for which to renew the private key.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

renewGroupKeyAsyncWithGroupId:completionHandler: ​

objc
- (void) renewGroupKeyAsyncWithGroupId:(const NSString *)groupId
                     completionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) renewGroupKeyAsyncWithGroupId:(const NSString *)groupId
                     completionHandler:(void(^)(NSError *_Nullable error))completionHandler;

Renew the group's private key. Can only be done by a group administrator. Should be called after removing members from the group.

Parameters ​

  • groupId The group for which to renew the private key.

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

setGroupAdminsWithGroupId:addToAdmins:removeFromAdmins:error: ​

objc
- (void) setGroupAdminsWithGroupId:(const NSString *)groupId
                       addToAdmins:(const NSArray< NSString * > *)addToAdmins
                  removeFromAdmins:(const NSArray< NSString * > *)removeFromAdmins
                             error:(NSError *_Nullable *)error;
- (void) setGroupAdminsWithGroupId:(const NSString *)groupId
                       addToAdmins:(const NSArray< NSString * > *)addToAdmins
                  removeFromAdmins:(const NSArray< NSString * > *)removeFromAdmins
                             error:(NSError *_Nullable *)error;

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.

Parameters ​

  • groupId The group for which to set admins.

  • addToAdmins The Seald IDs of existing group members to add as group admins.

  • removeFromAdmins The Seald IDs of existing group members to remove from group admins.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

setGroupAdminsAsyncWithGroupId:addToAdmins:removeFromAdmins:completionHandler: ​

objc
- (void) setGroupAdminsAsyncWithGroupId:(const NSString *)groupId
                            addToAdmins:(const NSArray< NSString * > *)addToAdmins
                       removeFromAdmins:(const NSArray< NSString * > *)removeFromAdmins
                      completionHandler:(void(^)(NSError *_Nullable error))completionHandler;
- (void) setGroupAdminsAsyncWithGroupId:(const NSString *)groupId
                            addToAdmins:(const NSArray< NSString * > *)addToAdmins
                       removeFromAdmins:(const NSArray< NSString * > *)removeFromAdmins
                      completionHandler:(void(^)(NSError *_Nullable error))completionHandler;

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.

Parameters ​

  • groupId The group for which to set admins.

  • addToAdmins The Seald IDs of existing group members to add as group admins.

  • removeFromAdmins The Seald IDs of existing group members to remove from group admins.

  • completionHandler A callback called after function execution. This callback take a pointer to a NSError that indicates if any error occurred.

createEncryptionSessionWithRecipients:useCache:error: ​

objc
- (SealdEncryptionSession *) createEncryptionSessionWithRecipients:(const NSArray< SealdRecipientWithRights * > *)recipients
                                                          useCache:(const BOOL)useCache
                                                             error:(NSError *_Nullable *)error;
- (SealdEncryptionSession *) createEncryptionSessionWithRecipients:(const NSArray< SealdRecipientWithRights * > *)recipients
                                                          useCache:(const BOOL)useCache
                                                             error:(NSError *_Nullable *)error;

Create an encryption session, and returns the associated SealdEncryptionSession 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.

Parameters ​

  • recipients The Seald IDs with the associated rights of users who should be able to retrieve this session.

  • useCache Whether or not to use the cache (if enabled globally).

  • error The error that occurred while creating the session, if any.

Returns ​

The created SealdEncryptionSession, or null if an error occurred.

createEncryptionSessionAsyncWithRecipients:useCache:completionHandler: ​

objc
- (void) createEncryptionSessionAsyncWithRecipients:(const NSArray< SealdRecipientWithRights * > *)recipients
                                           useCache:(const BOOL)useCache
                                  completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;
- (void) createEncryptionSessionAsyncWithRecipients:(const NSArray< SealdRecipientWithRights * > *)recipients
                                           useCache:(const BOOL)useCache
                                  completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;

Create an encryption session, and returns the associated SealdEncryptionSession 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.

Parameters ​

  • recipients The Seald IDs with the associated rights of users who should be able to retrieve this session.

  • useCache Whether or not to use the cache (if enabled globally).

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdEncryptionSession* containing the created encryption session, and a NSError* that indicates if any error occurred.

retrieveEncryptionSessionWithSessionId:useCache:lookupProxyKey:lookupGroupKey:error: ​

objc
- (SealdEncryptionSession *) retrieveEncryptionSessionWithSessionId:(const NSString *)sessionId
                                                           useCache:(const BOOL)useCache
                                                     lookupProxyKey:(const BOOL)lookupProxyKey
                                                     lookupGroupKey:(const BOOL)lookupGroupKey
                                                              error:(NSError *_Nullable *)error;
- (SealdEncryptionSession *) retrieveEncryptionSessionWithSessionId:(const NSString *)sessionId
                                                           useCache:(const BOOL)useCache
                                                     lookupProxyKey:(const BOOL)lookupProxyKey
                                                     lookupGroupKey:(const BOOL)lookupGroupKey
                                                              error:(NSError *_Nullable *)error;

Retrieve an encryption session with the sessionId, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • sessionId The ID of the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • error The error that occurred while retrieving the session, if any.

Returns ​

The retrieved SealdEncryptionSession, or null if an error occurred.

retrieveEncryptionSessionAsyncWithSessionId:useCache:lookupProxyKey:lookupGroupKey:completionHandler: ​

objc
- (void) retrieveEncryptionSessionAsyncWithSessionId:(const NSString *)sessionId
                                            useCache:(const BOOL)useCache
                                      lookupProxyKey:(const BOOL)lookupProxyKey
                                      lookupGroupKey:(const BOOL)lookupGroupKey
                                   completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;
- (void) retrieveEncryptionSessionAsyncWithSessionId:(const NSString *)sessionId
                                            useCache:(const BOOL)useCache
                                      lookupProxyKey:(const BOOL)lookupProxyKey
                                      lookupGroupKey:(const BOOL)lookupGroupKey
                                   completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;

Retrieve an encryption session with the sessionId, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • sessionId The ID of the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdEncryptionSession* instance of the retrieved encryption session, and a NSError* that indicates if any error occurred.

retrieveEncryptionSessionFromMessage:useCache:lookupProxyKey:lookupGroupKey:error: ​

objc
- (SealdEncryptionSession *) retrieveEncryptionSessionFromMessage:(const NSString *_Nonnull)message
                                                         useCache:(const BOOL)useCache
                                                   lookupProxyKey:(const BOOL)lookupProxyKey
                                                   lookupGroupKey:(const BOOL)lookupGroupKey
                                                            error:(NSError *_Nullable *)error;
- (SealdEncryptionSession *) retrieveEncryptionSessionFromMessage:(const NSString *_Nonnull)message
                                                         useCache:(const BOOL)useCache
                                                   lookupProxyKey:(const BOOL)lookupProxyKey
                                                   lookupGroupKey:(const BOOL)lookupGroupKey
                                                            error:(NSError *_Nullable *)error;

Retrieve an encryption session from a seald message, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • message Any message belonging to the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • error The error that occurred while retrieving the session, if any.

Returns ​

The retrieved SealdEncryptionSession, or null if an error occurred.

retrieveEncryptionSessionAsyncFromMessage:useCache:lookupProxyKey:lookupGroupKey:completionHandler: ​

objc
- (void) retrieveEncryptionSessionAsyncFromMessage:(const NSString *_Nonnull)message
                                          useCache:(const BOOL)useCache
                                    lookupProxyKey:(const BOOL)lookupProxyKey
                                    lookupGroupKey:(const BOOL)lookupGroupKey
                                 completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;
- (void) retrieveEncryptionSessionAsyncFromMessage:(const NSString *_Nonnull)message
                                          useCache:(const BOOL)useCache
                                    lookupProxyKey:(const BOOL)lookupProxyKey
                                    lookupGroupKey:(const BOOL)lookupGroupKey
                                 completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;

Retrieve an encryption session from a seald message, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • message Any message belonging to the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdEncryptionSession* instance of the retrieved encryption session, and a NSError* that indicates if any error occurred.

retrieveEncryptionSessionFromFile:useCache:lookupProxyKey:lookupGroupKey:error: ​

objc
- (SealdEncryptionSession *) retrieveEncryptionSessionFromFile:(const NSString *_Nonnull)fileURI
                                                      useCache:(const BOOL)useCache
                                                lookupProxyKey:(const BOOL)lookupProxyKey
                                                lookupGroupKey:(const BOOL)lookupGroupKey
                                                         error:(NSError *_Nullable *)error;
- (SealdEncryptionSession *) retrieveEncryptionSessionFromFile:(const NSString *_Nonnull)fileURI
                                                      useCache:(const BOOL)useCache
                                                lookupProxyKey:(const BOOL)lookupProxyKey
                                                lookupGroupKey:(const BOOL)lookupGroupKey
                                                         error:(NSError *_Nullable *)error;

Retrieve an encryption session from a file URI, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • fileURI An URI to an encrypted file belonging to the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • error The error that occurred while retrieving the session, if any.

Returns ​

The retrieved SealdEncryptionSession, or null if an error occurred.

retrieveEncryptionSessionAsyncFromFile:useCache:lookupProxyKey:lookupGroupKey:completionHandler: ​

objc
- (void) retrieveEncryptionSessionAsyncFromFile:(const NSString *_Nonnull)fileURI
                                       useCache:(const BOOL)useCache
                                 lookupProxyKey:(const BOOL)lookupProxyKey
                                 lookupGroupKey:(const BOOL)lookupGroupKey
                              completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;
- (void) retrieveEncryptionSessionAsyncFromFile:(const NSString *_Nonnull)fileURI
                                       useCache:(const BOOL)useCache
                                 lookupProxyKey:(const BOOL)lookupProxyKey
                                 lookupGroupKey:(const BOOL)lookupGroupKey
                              completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;

Retrieve an encryption session from a file URI, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • fileURI An URI to an encrypted file belonging to the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdEncryptionSession* instance of the retrieved encryption session, and a NSError* that indicates if any error occurred.

retrieveEncryptionSessionFromBytes:useCache:lookupProxyKey:lookupGroupKey:error: ​

objc
- (SealdEncryptionSession *) retrieveEncryptionSessionFromBytes:(const NSData *_Nonnull)fileBytes
                                                       useCache:(const BOOL)useCache
                                                 lookupProxyKey:(const BOOL)lookupProxyKey
                                                 lookupGroupKey:(const BOOL)lookupGroupKey
                                                          error:(NSError *_Nullable *)error;
- (SealdEncryptionSession *) retrieveEncryptionSessionFromBytes:(const NSData *_Nonnull)fileBytes
                                                       useCache:(const BOOL)useCache
                                                 lookupProxyKey:(const BOOL)lookupProxyKey
                                                 lookupGroupKey:(const BOOL)lookupGroupKey
                                                          error:(NSError *_Nullable *)error;

Retrieve an encryption session from an NSData*, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • fileBytes NSData* of an encrypted file belonging to the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • error The error that occurred while retrieving the session, if any.

Returns ​

The retrieved SealdEncryptionSession, or null if an error occurred.

retrieveEncryptionSessionAsyncFromBytes:useCache:lookupProxyKey:lookupGroupKey:completionHandler: ​

objc
- (void) retrieveEncryptionSessionAsyncFromBytes:(const NSData *_Nonnull)fileBytes
                                        useCache:(const BOOL)useCache
                                  lookupProxyKey:(const BOOL)lookupProxyKey
                                  lookupGroupKey:(const BOOL)lookupGroupKey
                               completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;
- (void) retrieveEncryptionSessionAsyncFromBytes:(const NSData *_Nonnull)fileBytes
                                        useCache:(const BOOL)useCache
                                  lookupProxyKey:(const BOOL)lookupProxyKey
                                  lookupGroupKey:(const BOOL)lookupGroupKey
                               completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;

Retrieve an encryption session from an NSData*, and returns the associated SealdEncryptionSession instance, with which you can then encrypt / decrypt multiple messages.

Parameters ​

  • fileBytes NSData* of an encrypted file belonging to the session to retrieve.

  • useCache Whether or not to use the cache (if enabled globally).

  • lookupProxyKey Whether or not to try retrieving the session via a proxy.

  • lookupGroupKey Whether or not to try retrieving the session via a group.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdEncryptionSession* instance of the retrieved encryption session, and a NSError* that indicates if any error occurred.

retrieveEncryptionSessionByTmr:sessionId:overEncryptionKey:tmrAccessesFilters:tryIfMultiple:useCache:error: ​

objc
- (SealdEncryptionSession *) retrieveEncryptionSessionByTmr:(const NSString *)tmrJWT
                                                  sessionId:(const NSString *)sessionId
                                          overEncryptionKey:(const NSData *)overEncryptionKey
                                         tmrAccessesFilters:(const SealdTmrAccessesRetrievalFilters *_Nullable)tmrAccessesFilters
                                              tryIfMultiple:(const BOOL)tryIfMultiple
                                                   useCache:(const BOOL)useCache
                                                      error:(NSError *_Nullable *)error;
- (SealdEncryptionSession *) retrieveEncryptionSessionByTmr:(const NSString *)tmrJWT
                                                  sessionId:(const NSString *)sessionId
                                          overEncryptionKey:(const NSData *)overEncryptionKey
                                         tmrAccessesFilters:(const SealdTmrAccessesRetrievalFilters *_Nullable)tmrAccessesFilters
                                              tryIfMultiple:(const BOOL)tryIfMultiple
                                                   useCache:(const BOOL)useCache
                                                      error:(NSError *_Nullable *)error;

Retrieve an encryption session with a TMR access JWT.

Parameters ​

  • tmrJWT The TMR JWT.

  • sessionId The id of the session to retrieve.

  • overEncryptionKey TMR over-encryption key. This MUST be a cryptographically random NSData of 64 bytes.

  • tmrAccessesFilters Retrieval tmr accesses filters. If multiple TMR Accesses for this session are associated with the auth factor, filter out the unwanted ones.

  • tryIfMultiple If multiple accesses are found for this session associated with the auth factor, whether or not to loop over all of them to find the wanted one.

  • useCache Whether or not to use the cache (if enabled globally).

  • error The error that occurred while retrieving the session, if any.

Returns ​

The retrieved SealdEncryptionSession, or null if an error occurred.

retrieveEncryptionSessionAsyncByTmr:sessionId:overEncryptionKey:tmrAccessesFilters:tryIfMultiple:useCache:completionHandler: ​

objc
- (void) retrieveEncryptionSessionAsyncByTmr:(const NSString *)tmrJWT
                                   sessionId:(const NSString *)sessionId
                           overEncryptionKey:(const NSData *)overEncryptionKey
                          tmrAccessesFilters:(const SealdTmrAccessesRetrievalFilters *_Nullable)tmrAccessesFilters
                               tryIfMultiple:(const BOOL)tryIfMultiple
                                    useCache:(const BOOL)useCache
                           completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;
- (void) retrieveEncryptionSessionAsyncByTmr:(const NSString *)tmrJWT
                                   sessionId:(const NSString *)sessionId
                           overEncryptionKey:(const NSData *)overEncryptionKey
                          tmrAccessesFilters:(const SealdTmrAccessesRetrievalFilters *_Nullable)tmrAccessesFilters
                               tryIfMultiple:(const BOOL)tryIfMultiple
                                    useCache:(const BOOL)useCache
                           completionHandler:(void(^)(SealdEncryptionSession *encryptionSession, NSError *_Nullable error))completionHandler;

Retrieve an encryption session with a TMR access JWT.

Parameters ​

  • tmrJWT The TMR JWT.

  • sessionId The id of the session to retrieve.

  • overEncryptionKey TMR over-encryption key. This MUST be a cryptographically random NSData of 64 bytes.

  • tmrAccessesFilters Retrieval tmr accesses filters. If multiple TMR Accesses for this session are associated with the auth factor, filter out the unwanted ones.

  • tryIfMultiple If multiple accesses are found for this session associated with the auth factor, whether or not to loop over all of them to find the wanted one.

  • useCache Whether or not to use the cache (if enabled globally).

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdEncryptionSession* instance of the retrieved encryption session, and a NSError* that indicates if any error occurred.

getSealdIdsFromConnectors:error: ​

objc
- (NSArray< NSString * > *) getSealdIdsFromConnectors:(const NSArray< SealdConnectorTypeValue * > *)connectorTypeValues
                                                error:(NSError *_Nullable *)error;
- (NSArray< NSString * > *) getSealdIdsFromConnectors:(const NSArray< SealdConnectorTypeValue * > *)connectorTypeValues
                                                error:(NSError *_Nullable *)error;

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.

Parameters ​

  • connectorTypeValues An Array of ConnectorTypeValue instances.

  • error An error pointer to fill in case of an error.

Returns ​

An Array of NSString with the Seald IDs of the users corresponding to these connectors.

getSealdIdsAsyncFromConnectors:completionHandler: ​

objc
- (void) getSealdIdsAsyncFromConnectors:(const NSArray< SealdConnectorTypeValue * > *)connectorTypeValues
                      completionHandler:(void(^)(NSArray< NSString * > *sealdIds, NSError *_Nullable error))completionHandler;
- (void) getSealdIdsAsyncFromConnectors:(const NSArray< SealdConnectorTypeValue * > *)connectorTypeValues
                      completionHandler:(void(^)(NSArray< NSString * > *sealdIds, NSError *_Nullable error))completionHandler;

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.

Parameters ​

  • connectorTypeValues An Array of ConnectorTypeValue instances.

  • completionHandler A callback called after function execution. This callback take two arguments, an Array of NSString with the Seald IDs of the users corresponding to these connectors, and a NSError* that indicates if any error occurred.

getConnectorsFromSealdId:error: ​

objc
- (NSArray< SealdConnector * > *) getConnectorsFromSealdId:(const NSString *)sealdId
                                                     error:(NSError *_Nullable *)error;
- (NSArray< SealdConnector * > *) getConnectorsFromSealdId:(const NSString *)sealdId
                                                     error:(NSError *_Nullable *)error;

List all connectors know locally for a given sealdId.

Parameters ​

  • sealdId The Seald ID for which to list connectors

  • error An error pointer to fill in case of an error.

Returns ​

An Array of Connector instances.

getConnectorsAsyncFromSealdId:completionHandler: ​

objc
- (void) getConnectorsAsyncFromSealdId:(const NSString *)sealdId
                     completionHandler:(void(^)(NSArray< SealdConnector * > *connectors, NSError *_Nullable error))completionHandler;
- (void) getConnectorsAsyncFromSealdId:(const NSString *)sealdId
                     completionHandler:(void(^)(NSArray< SealdConnector * > *connectors, NSError *_Nullable error))completionHandler;

List all connectors know locally for a given sealdId.

Parameters ​

  • sealdId The Seald ID for which to list connectors

  • completionHandler A callback called after function execution. This callback take two arguments, an NSArray of SealdConnector* instances, and a NSError* that indicates if any error occurred.

addConnectorWithValue:connectorType:preValidationToken:error: ​

objc
- (SealdConnector *) addConnectorWithValue:(const NSString *)value
                             connectorType:(const NSString *)connectorType
                        preValidationToken:(const SealdPreValidationToken *)preValidationToken
                                     error:(NSError *_Nullable *)error;
- (SealdConnector *) addConnectorWithValue:(const NSString *)value
                             connectorType:(const NSString *)connectorType
                        preValidationToken:(const SealdPreValidationToken *)preValidationToken
                                     error:(NSError *_Nullable *)error;

Add a connector to the current identity. If no preValidationToken is given, the connector will need to be validated before use.

Parameters ​

  • value The value of the connector to add.

  • connectorType The type of the connector.

  • preValidationToken Given by your server to authorize the adding of a connector.

  • error An error pointer to fill in case of an error.

Returns ​

The created Connector.

addConnectorAsyncWithValue:connectorType:preValidationToken:completionHandler: ​

objc
- (void) addConnectorAsyncWithValue:(const NSString *)value
                      connectorType:(const NSString *)connectorType
                 preValidationToken:(const SealdPreValidationToken *)preValidationToken
                  completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;
- (void) addConnectorAsyncWithValue:(const NSString *)value
                      connectorType:(const NSString *)connectorType
                 preValidationToken:(const SealdPreValidationToken *)preValidationToken
                  completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;

Add a connector to the current identity. If no preValidationToken is given, the connector will need to be validated before use.

Parameters ​

  • value The value of the connector to add.

  • connectorType The type of the connector.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdConnector* instances of the added connector, and a NSError* that indicates if any error occurred.

validateConnector:challenge:error: ​

objc
- (SealdConnector *) validateConnector:(const NSString *)connectorId
                             challenge:(const NSString *)challenge
                                 error:(NSError *_Nullable *)error;
- (SealdConnector *) validateConnector:(const NSString *)connectorId
                             challenge:(const NSString *)challenge
                                 error:(NSError *_Nullable *)error;

Validate an added connector that was added without a preValidationToken.

Parameters ​

  • connectorId The ID of the connector to validate.

  • challenge The challenge.

  • error An error pointer to fill in case of an error.

Returns ​

The modified Connector.

validateConnectorAsyncWithConnectorId:challenge:completionHandler: ​

objc
- (void) validateConnectorAsyncWithConnectorId:(const NSString *)connectorId
                                     challenge:(const NSString *)challenge
                             completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;
- (void) validateConnectorAsyncWithConnectorId:(const NSString *)connectorId
                                     challenge:(const NSString *)challenge
                             completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;

Validate an added connector that was added without a preValidationToken.

Parameters ​

  • connectorId The ID of the connector to validate.

  • challenge The challenge.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdConnector* instances of the validated connector, and a NSError* that indicates if any error occurred.

removeConnector:error: ​

objc
- (SealdConnector *) removeConnector:(const NSString *)connectorId
                               error:(NSError *_Nullable *)error;
- (SealdConnector *) removeConnector:(const NSString *)connectorId
                               error:(NSError *_Nullable *)error;

Remove a connector belonging to the current account.

Parameters ​

  • connectorId The ID of the connector to remove.

  • error An error pointer to fill in case of an error.

Returns ​

The modified Connector.

removeConnectorAsyncWithConnectorId:completionHandler: ​

objc
- (void) removeConnectorAsyncWithConnectorId:(const NSString *)connectorId
                           completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;
- (void) removeConnectorAsyncWithConnectorId:(const NSString *)connectorId
                           completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;

Remove a connector belonging to the current account.

Parameters ​

  • connectorId The ID of the connector to remove.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdConnector* instances of the removed connector, and a NSError* that indicates if any error occurred.

listConnectorsWithError: ​

objc
- (NSArray< SealdConnector * > *) listConnectorsWithError:(NSError *_Nullable *)error;
- (NSArray< SealdConnector * > *) listConnectorsWithError:(NSError *_Nullable *)error;

List connectors associated to the current account.

Parameters ​

  • error An error pointer to fill in case of an error.

Returns ​

The array of connectors associated to the current account.

listConnectorsAsyncWithCompletionHandler: ​

objc
- (void) listConnectorsAsyncWithCompletionHandler:(void(^)(NSArray< SealdConnector * > *connectors, NSError *_Nullable error))completionHandler;
- (void) listConnectorsAsyncWithCompletionHandler:(void(^)(NSArray< SealdConnector * > *connectors, NSError *_Nullable error))completionHandler;

List connectors associated to the current account.

Parameters ​

  • completionHandler A callback called after function execution. This callback take two arguments, an NSArray of SealdConnector* instances of the listed connectors, and a NSError* that indicates if any error occurred.

retrieveConnector:error: ​

objc
- (SealdConnector *) retrieveConnector:(const NSString *)connectorId
                                 error:(NSError *_Nullable *)error;
- (SealdConnector *) retrieveConnector:(const NSString *)connectorId
                                 error:(NSError *_Nullable *)error;

Retrieve a connector by its connectorId, then updates the local cache of connectors.

Parameters ​

  • connectorId The ID of the connector to retrieve.

  • error An error pointer to fill in case of an error.

Returns ​

The Connector.

retrieveConnectorAsyncWithConnectorId:completionHandler: ​

objc
- (void) retrieveConnectorAsyncWithConnectorId:(const NSString *)connectorId
                             completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;
- (void) retrieveConnectorAsyncWithConnectorId:(const NSString *)connectorId
                             completionHandler:(void(^)(SealdConnector *connector, NSError *_Nullable error))completionHandler;

Retrieve a connector by its connectorId, then updates the local cache of connectors.

Parameters ​

  • connectorId The ID of the connector to retrieve.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdConnector* instance of the retrieved connector, and a NSError* that indicates if any error occurred.

massReencryptWithDeviceId:options:error: ​

objc
- (SealdMassReencryptResponse *) massReencryptWithDeviceId:(const NSString *)deviceId
                                                   options:(const SealdMassReencryptOptions *)options
                                                     error:(NSError *_Nullable *)error;
- (SealdMassReencryptResponse *) massReencryptWithDeviceId:(const NSString *)deviceId
                                                   options:(const SealdMassReencryptOptions *)options
                                                     error:(NSError *_Nullable *)error;

Retrieve, re-encrypt, and add missing keys for a certain device.

Parameters ​

  • deviceId The ID of the device for which to re-rencrypt.

  • options A SealdMassReencryptOptions instance, or nil to use default options.

  • error An NSError object that will be populated if an error occurs while executing the operation.

Returns ​

A SealdMassReencryptResponse instance, containing the number of re-encrypted keys, and the number of keys for which re-encryption failed.

massReencryptAsyncWithDeviceId:options:completionHandler: ​

objc
- (void) massReencryptAsyncWithDeviceId:(const NSString *)deviceId
                                options:(const SealdMassReencryptOptions *)options
                      completionHandler:(void(^)(SealdMassReencryptResponse *response, NSError *_Nullable error))completionHandler;
- (void) massReencryptAsyncWithDeviceId:(const NSString *)deviceId
                                options:(const SealdMassReencryptOptions *)options
                      completionHandler:(void(^)(SealdMassReencryptResponse *response, NSError *_Nullable error))completionHandler;

Retrieve, re-encrypt, and add missing keys for a certain device.

Parameters ​

  • deviceId The ID of the device for which to re-rencrypt.

  • options A SealdMassReencryptOptions instance, or nil to use default options.

  • completionHandler A callback called after function execution. This callback take two arguments, a SealdMassReencryptResponse* instance containing the number of re-encrypted keys of the retrieved connector, and a NSError* that indicates if any error occurred.

devicesMissingKeysWithForceLocalAccountUpdate:error: ​

objc
- (NSArray< SealdDeviceMissingKeys * > *) devicesMissingKeysWithForceLocalAccountUpdate:(const BOOL)forceLocalAccountUpdate
                                                                                  error:(NSError *_Nullable *)error;
- (NSArray< SealdDeviceMissingKeys * > *) devicesMissingKeysWithForceLocalAccountUpdate:(const BOOL)forceLocalAccountUpdate
                                                                                  error:(NSError *_Nullable *)error;

List which of the devices of the current account are missing keys, so you can call massReencryptWithDeviceId:options:error: for them.

Parameters ​

  • forceLocalAccountUpdate Whether to update the local account

  • error If an error occurs, upon return contains an NSError object that describes the problem.

Returns ​

An NSArray of SealdDeviceMissingKeys instances, containing the ID of the device.

devicesMissingKeysAsyncWithForceLocalAccountUpdate:completionHandler: ​

objc
- (void) devicesMissingKeysAsyncWithForceLocalAccountUpdate:(const BOOL)forceLocalAccountUpdate
                                          completionHandler:(void(^)(NSArray< SealdDeviceMissingKeys * > *devices, NSError *_Nullable error))completionHandler;
- (void) devicesMissingKeysAsyncWithForceLocalAccountUpdate:(const BOOL)forceLocalAccountUpdate
                                          completionHandler:(void(^)(NSArray< SealdDeviceMissingKeys * > *devices, NSError *_Nullable error))completionHandler;

List which of the devices of the current account are missing keys, so you can call massReencryptWithDeviceId:options:error: for them.

Parameters ​

  • forceLocalAccountUpdate Whether to update the local account

  • completionHandler A callback called after function execution. This callback take two arguments, an NSArray of SealdDeviceMissingKeys instances, containing the ID of the device, and a NSError* that indicates if any error occurred.

getSigchainHashWithUserId:position:error: ​

objc
- (SealdGetSigchainResponse *) getSigchainHashWithUserId:(const NSString *)userId
                                                position:(const long)position
                                                   error:(NSError *_Nullable *)error;
- (SealdGetSigchainResponse *) getSigchainHashWithUserId:(const NSString *)userId
                                                position:(const long)position
                                                   error:(NSError *_Nullable *)error;

Get a user's sigchain transaction hash at index position.

Parameters ​

  • userId The Seald ID of the concerned user.

  • position Get the hash at the given position. -1 to get the last. Default to -1.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

Returns ​

A SealdGetSigchainResponse instance.

getSigchainHashAsyncWithUserId:position:completionHandler: ​

objc
- (void) getSigchainHashAsyncWithUserId:(const NSString *)userId
                               position:(const long)position
                      completionHandler:(void(^)(SealdGetSigchainResponse *response, NSError *_Nullable error))completionHandler;
- (void) getSigchainHashAsyncWithUserId:(const NSString *)userId
                               position:(const long)position
                      completionHandler:(void(^)(SealdGetSigchainResponse *response, NSError *_Nullable error))completionHandler;

Get a user's sigchain transaction hash at index position.

Parameters ​

  • userId The Seald ID of the concerned user.

  • position Get the hash at the given position. -1 to get the last. Default to -1.

  • completionHandler A callback called after function execution. This callback take two arguments, an [SealdGetSigchainResponse](SealdGetSigchainResponse.md#class-sealdgetsigchainresponse) instance containing the hash, and a NSError* that indicates if any error occurred.

checkSigchainHashWithUserId:expectedHash:position:error: ​

objc
- (SealdCheckSigchainResponse *) checkSigchainHashWithUserId:(const NSString *)userId
                                                expectedHash:(const NSString *)expectedHash
                                                    position:(const long)position
                                                       error:(NSError *_Nullable *)error;
- (SealdCheckSigchainResponse *) checkSigchainHashWithUserId:(const NSString *)userId
                                                expectedHash:(const NSString *)expectedHash
                                                    position:(const long)position
                                                       error:(NSError *_Nullable *)error;

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.

Parameters ​

  • userId The Seald ID of the concerned user.

  • expectedHash The expected sigchain hash.

  • position Position of the sigchain transaction against which to check the hash. -1 to check if the hash exist in the sigchain. Default to -1.

  • error If an error occurs, upon return contains an NSError object that describes the problem.

Returns ​

A SealdCheckSigchainResponse instance.

checkSigchainHashAsyncWithUserId:expectedHash:position:completionHandler: ​

objc
- (void) checkSigchainHashAsyncWithUserId:(const NSString *)userId
                             expectedHash:(const NSString *)expectedHash
                                 position:(const long)position
                        completionHandler:(void(^)(SealdCheckSigchainResponse *response, NSError *_Nullable error))completionHandler;
- (void) checkSigchainHashAsyncWithUserId:(const NSString *)userId
                             expectedHash:(const NSString *)expectedHash
                                 position:(const long)position
                        completionHandler:(void(^)(SealdCheckSigchainResponse *response, NSError *_Nullable error))completionHandler;

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.

Parameters ​

  • userId The Seald ID of the concerned user.

  • expectedHash The expected sigchain hash.

  • position Position of the sigchain transaction against which to check the hash. -1 to check if the hash exist in the sigchain. Default to -1.

  • completionHandler A callback called after function execution. This callback take two arguments, an [SealdCheckSigchainResponse](SealdCheckSigchainResponse.md#class-sealdchecksigchainresponse) instance containing the response, and a NSError* that indicates if any error occurred.

convertTmrAccesses:overEncryptionKey:conversionFilters:deleteOnConvert:error: ​

objc
- (SealdConvertTmrAccessesResult *) convertTmrAccesses:(const NSString *)tmrJWT
                                     overEncryptionKey:(const NSData *)overEncryptionKey
                                     conversionFilters:(const SealdTmrAccessesConvertFilters *_Nullable)conversionFilters
                                       deleteOnConvert:(const BOOL)deleteOnConvert
                                                 error:(NSError *_Nullable *)error;
- (SealdConvertTmrAccessesResult *) convertTmrAccesses:(const NSString *)tmrJWT
                                     overEncryptionKey:(const NSData *)overEncryptionKey
                                     conversionFilters:(const SealdTmrAccessesConvertFilters *_Nullable)conversionFilters
                                       deleteOnConvert:(const BOOL)deleteOnConvert
                                                 error:(NSError *_Nullable *)error;

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.

Parameters ​

  • tmrJWT The TMR JWT.

  • overEncryptionKey TMR over-encryption key. This MUST be a cryptographically random NSData of 64 bytes.

  • conversionFilters Convert tmr accesses filters. If multiple TMR Accesses with the auth factor, filter out the unwanted ones.

  • deleteOnConvert Whether or not to delete the TMR access after conversion.

  • error The error that occurred while retrieving the session, if any.

Returns ​

A SealdConvertTmrAccessesResult instance.

convertTmrAccessesAsync:overEncryptionKey:conversionFilters:deleteOnConvert:completionHandler: ​

objc
- (void) convertTmrAccessesAsync:(const NSString *)tmrJWT
               overEncryptionKey:(const NSData *)overEncryptionKey
               conversionFilters:(const SealdTmrAccessesConvertFilters *_Nullable)conversionFilters
                 deleteOnConvert:(const BOOL)deleteOnConvert
               completionHandler:(void(^)(SealdConvertTmrAccessesResult *response, NSError *_Nullable error))completionHandler;
- (void) convertTmrAccessesAsync:(const NSString *)tmrJWT
               overEncryptionKey:(const NSData *)overEncryptionKey
               conversionFilters:(const SealdTmrAccessesConvertFilters *_Nullable)conversionFilters
                 deleteOnConvert:(const BOOL)deleteOnConvert
               completionHandler:(void(^)(SealdConvertTmrAccessesResult *response, NSError *_Nullable error))completionHandler;

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.

Parameters ​

  • tmrJWT The TMR JWT.

  • overEncryptionKey TMR over-encryption key. This MUST be a cryptographically random NSData of 64 bytes.

  • conversionFilters Convert tmr accesses filters. If multiple TMR Accesses with the auth factor, filter out the unwanted ones.

  • deleteOnConvert Whether or not to delete the TMR access after conversion.

  • completionHandler A callback called after function execution. This callback take two arguments, an convertTmrAccessesAsync instance containing the response, and a NSError* that indicates if any error occurred.