pEpObjCAdapterFramework/PEPSessionProtocol.h
author Dirk Zimmermann <dz@pep.security>
Mon, 29 Jun 2020 16:39:43 +0200
branchIOSAD-172
changeset 1553 c6eac6f06d52
parent 1522 86c579f701a2
child 1562 5025d445d120
permissions -rw-r--r--
IOSAD-172 Fix the domain constants
dirk@303
     1
//
dirk@303
     2
//  PEPSessionProtocol.h
dirk@303
     3
//  pEpObjCAdapter
dirk@303
     4
//
dirk@303
     5
//  Created by Dirk Zimmermann on 30.10.17.
dirk@303
     6
//  Copyright © 2017 p≡p. All rights reserved.
dirk@303
     7
//
dirk@303
     8
dirk@303
     9
#import <Foundation/Foundation.h>
dirk@303
    10
dz@902
    11
#import "PEPTypes.h"
dz@902
    12
#import "PEPEngineTypes.h"
dirk@773
    13
dirk@303
    14
@class PEPLanguage;
dirk@305
    15
@class PEPIdentity;
dirk@377
    16
@class PEPMessage;
dirk@303
    17
dz@1489
    18
/// Domain for errors indicated by the pEp engine.
dz@1553
    19
extern NSString * const _Nonnull PEPObjCAdapterEngineStatusErrorDomain;
dz@1489
    20
dz@1489
    21
/// Domain for errors indicated by the pEp adapter itself.
dz@1553
    22
extern NSString * const _Nonnull PEPObjCAdapterErrorDomain;
dz@1489
    23
dz@1490
    24
/// Possible errors from adapter without involvement from the engine.
dz@1490
    25
typedef NS_CLOSED_ENUM(int, PEPAdapterError) {
dz@1490
    26
    /// Passwords are limited in size, and this error indicates a password that contains
dz@1490
    27
    /// too many codepoints.
dz@1490
    28
    PEPAdapterErrorPassphraseTooLong = 0
dz@1490
    29
};
dz@1490
    30
dirk@303
    31
@protocol PEPSessionProtocol <NSObject>
dirk@303
    32
dirk@303
    33
/** Decrypt a message */
dirk@535
    34
- (PEPMessage * _Nullable)decryptMessage:(PEPMessage * _Nonnull)message
dz@818
    35
                                   flags:(PEPDecryptFlags * _Nullable)flags
dz@822
    36
                                  rating:(PEPRating * _Nullable)rating
dirk@523
    37
                               extraKeys:(PEPStringList * _Nullable * _Nullable)extraKeys
dz@822
    38
                                  status:(PEPStatus * _Nullable)status
dirk@517
    39
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@303
    40
dirk@303
    41
/** Re-evaluate rating of decrypted message */
dirk@535
    42
- (BOOL)reEvaluateMessage:(PEPMessage * _Nonnull)message
dirk@634
    43
                 xKeyList:(PEPStringList *_Nullable)xKeyList
dz@822
    44
                   rating:(PEPRating * _Nonnull)rating
dz@822
    45
                   status:(PEPStatus * _Nullable)status
dirk@516
    46
                    error:(NSError * _Nullable * _Nullable)error;
dirk@303
    47
dirk@522
    48
/**
dirk@522
    49
 Encrypt a message, indicating the encoding format
dirk@522
    50
 @note The resulting message dict could be the input one.
dirk@522
    51
 */
dirk@535
    52
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@535
    53
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@818
    54
                               encFormat:(PEPEncFormat)encFormat
dz@822
    55
                                  status:(PEPStatus * _Nullable)status
dirk@522
    56
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@379
    57
dirk@518
    58
/** Encrypt a message with default encryption format (PEP_enc_PEP) */
dirk@535
    59
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@535
    60
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@822
    61
                                  status:(PEPStatus * _Nullable)status
dirk@522
    62
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@518
    63
dirk@518
    64
/** Encrypt a message for the given own identity */
dirk@535
    65
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@557
    66
                                 forSelf:(PEPIdentity * _Nonnull)ownIdentity
dirk@556
    67
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@822
    68
                                  status:(PEPStatus * _Nullable)status
dirk@526
    69
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@381
    70
andreas@1318
    71
/** Encrypt a message to the given recipient FPR, attaching the private key */
dirk@607
    72
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@607
    73
                                   toFpr:(NSString * _Nonnull)toFpr
dz@818
    74
                               encFormat:(PEPEncFormat)encFormat
dz@818
    75
                                   flags:(PEPDecryptFlags)flags
dz@822
    76
                                  status:(PEPStatus * _Nullable)status
dirk@607
    77
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@607
    78
dirk@303
    79
/** Determine the status color of a message to be sent */
dirk@650
    80
- (NSNumber * _Nullable)outgoingRatingForMessage:(PEPMessage * _Nonnull)theMessage
dirk@573
    81
                                           error:(NSError * _Nullable * _Nullable)error;
dirk@377
    82
dirk@652
    83
/** Determine the preview status color of a message to be sent */
dirk@652
    84
- (NSNumber * _Nullable)outgoingRatingPreviewForMessage:(PEPMessage * _Nonnull)theMessage
dirk@652
    85
                                                  error:(NSError * _Nullable * _Nullable)error;
dirk@652
    86
andreas@407
    87
/**
andreas@407
    88
 Determine the rating of an identity.
andreas@407
    89
 The rating is the rating a _message_ would have, if it is sent to this (and only this) identity.
andreas@407
    90
 It is *not* a rating of the identity. In fact, there is no rating for identities.
andreas@407
    91
 */
dirk@574
    92
- (NSNumber * _Nullable)ratingForIdentity:(PEPIdentity * _Nonnull)identity
dirk@574
    93
                                    error:(NSError * _Nullable * _Nullable)error;
dirk@303
    94
dirk@303
    95
/** Get trustwords for a fingerprint */
dirk@531
    96
- (NSArray * _Nullable)trustwordsForFingerprint:(NSString * _Nonnull)fingerprint
dirk@531
    97
                                     languageID:(NSString * _Nonnull)languageID
dirk@531
    98
                                      shortened:(BOOL)shortened
dirk@531
    99
                                          error:(NSError * _Nullable * _Nullable)error;
dirk@303
   100
dz@1372
   101
/// Marks an identity as an own identity, not changing its participation in pEp sync.
dz@1372
   102
///
dz@1372
   103
/// @return Returns YES on success, NO on error, setting `*error` accordingly if possible.
dz@1372
   104
///
dz@1372
   105
/// @note See the engine's myself function for details.
dz@1372
   106
///
dz@1372
   107
/// @param identity The identity to mark as own.
dz@1372
   108
///
dz@1372
   109
/// @param error Standard cocoa error handling.
dz@1372
   110
- (BOOL)mySelf:(PEPIdentity * _Nonnull)identity
dz@1372
   111
         error:(NSError * _Nullable * _Nullable)error;
dz@1372
   112
dz@1369
   113
/// Calls the engine's update_identity on the given identity.
dz@1371
   114
///
dz@1369
   115
/// @note Prior this was invoking myself if the identity was identified as being an own
dz@1369
   116
/// identity, but this not the case anymore, since it cannot decide if the identity should
dz@1369
   117
/// participate in pEp sync or not.
dz@1371
   118
///
dz@1369
   119
/// @return Returns YES on success, NO on error, setting `*error` accordingly if possible.
dz@1371
   120
///
dz@1369
   121
/// @param identity The identity for which to call update_identity.
dz@1371
   122
/// 
dz@1369
   123
/// @param error Standart cocoa error handling.
dirk@535
   124
- (BOOL)updateIdentity:(PEPIdentity * _Nonnull)identity
dirk@535
   125
                 error:(NSError * _Nullable * _Nullable)error;
dirk@303
   126
dirk@303
   127
/**
dirk@303
   128
 Mark a key as trusted with a person.
dirk@303
   129
 */
dirk@535
   130
- (BOOL)trustPersonalKey:(PEPIdentity * _Nonnull)identity
dirk@534
   131
                   error:(NSError * _Nullable * _Nullable)error;
dirk@303
   132
dirk@303
   133
/**
dirk@303
   134
 if a key is not trusted by the user tell this using this message
dirk@303
   135
 */
dirk@536
   136
- (BOOL)keyMistrusted:(PEPIdentity * _Nonnull)identity
dirk@536
   137
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   138
dirk@303
   139
/**
dirk@303
   140
 Use this to undo keyCompromized or trustPersonalKey
dirk@303
   141
 */
dirk@545
   142
- (BOOL)keyResetTrust:(PEPIdentity * _Nonnull)identity
dirk@545
   143
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   144
dz@1189
   145
/**
dz@1189
   146
 Enables key sync.
dz@1189
   147
dz@1189
   148
 Wraps enable_identity_for_sync.
dz@1189
   149
dz@1189
   150
 @param identity The (own) identity to enable key sync for.
dz@1189
   151
 @param error The usual cocoa error handling.
dz@1189
   152
 @return The usual cocoa error handling.
dz@1189
   153
 */
dz@1181
   154
- (BOOL)enableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1181
   155
                        error:(NSError * _Nullable * _Nullable)error;
dz@1181
   156
dz@1189
   157
/**
dz@1189
   158
 Disables key sync.
dz@1189
   159
dz@1189
   160
 Wraps disable_identity_for_sync.
dz@1189
   161
dz@1189
   162
 @param identity The (own) identity to disable key sync for.
dz@1189
   163
 @param error The usual cocoa error handling.
dz@1189
   164
 @return The usual cocoa error handling.
dz@1189
   165
 */
dz@1186
   166
- (BOOL)disableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1186
   167
                         error:(NSError * _Nullable * _Nullable)error;
dz@1186
   168
dz@1190
   169
/**
dz@1206
   170
 Queries the given own identity on whether it has key sync disabled or not.
dz@1190
   171
dz@1190
   172
 @param identity The (own) identity to query.
dz@1190
   173
 @param error The usual cocoa error handling.
dz@1190
   174
 @return An NSNumber containing a boolean denoting whether key sync is enabled or not, or
dz@1206
   175
         nil on error. YES means that key sync is allowed for this identity, otherwise it's NO.
dz@1190
   176
 */
dz@1190
   177
- (NSNumber * _Nullable)queryKeySyncEnabledForIdentity:(PEPIdentity * _Nonnull)identity
dz@1190
   178
                                                 error:(NSError * _Nullable * _Nullable)error;
dz@1190
   179
dirk@303
   180
#pragma mark -- Internal API (testing etc.)
dirk@303
   181
dirk@303
   182
/** For testing purpose, manual key import */
dirk@672
   183
- (NSArray<PEPIdentity *> * _Nullable)importKey:(NSString * _Nonnull)keydata
dirk@672
   184
                                          error:(NSError * _Nullable * _Nullable)error;
dirk@303
   185
dirk@553
   186
- (BOOL)logTitle:(NSString * _Nonnull)title
dirk@553
   187
          entity:(NSString * _Nonnull)entity
dirk@553
   188
     description:(NSString * _Nullable)description
dirk@553
   189
         comment:(NSString * _Nullable)comment
dirk@553
   190
           error:(NSError * _Nullable * _Nullable)error;
dirk@303
   191
dirk@303
   192
/**
dirk@475
   193
 Retrieves the log from the engine, or nil, if there is nothing yet.
dirk@303
   194
 */
dirk@552
   195
- (NSString * _Nullable)getLogWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   196
dirk@303
   197
/** Determine trustwords for two identities */
dirk@535
   198
- (NSString * _Nullable)getTrustwordsIdentity1:(PEPIdentity * _Nonnull)identity1
dirk@535
   199
                                     identity2:(PEPIdentity * _Nonnull)identity2
dirk@535
   200
                                      language:(NSString * _Nullable)language
dirk@558
   201
                                          full:(BOOL)full
dirk@558
   202
                                         error:(NSError * _Nullable * _Nullable)error;
dirk@303
   203
vb@986
   204
/** Determine trustwords for two fprs */
vb@986
   205
- (NSString * _Nullable)getTrustwordsFpr1:(NSString * _Nonnull)fpr1
vb@986
   206
                                     fpr2:(NSString * _Nonnull)fpr2
vb@986
   207
                                 language:(NSString * _Nullable)language
vb@986
   208
                                     full:(BOOL)full
vb@986
   209
                                    error:(NSError * _Nullable * _Nullable)error;
vb@986
   210
dirk@303
   211
/**
dirk@303
   212
 @returns The list of supported languages for trustwords.
dirk@303
   213
 */
dirk@560
   214
- (NSArray<PEPLanguage *> * _Nullable)languageListWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   215
dirk@303
   216
/**
dz@822
   217
 Can convert a string like "cannot_decrypt" into its equivalent PEPRating_cannot_decrypt.
dirk@417
   218
 */
dz@822
   219
- (PEPRating)ratingFromString:(NSString * _Nonnull)string;
dirk@417
   220
dirk@417
   221
/**
dz@822
   222
 Can convert a pEp rating like PEPRating_cannot_decrypt
dirk@417
   223
 into its equivalent string "cannot_decrypt" .
dirk@417
   224
 */
dz@822
   225
- (NSString * _Nonnull)stringFromRating:(PEPRating)rating;
dirk@417
   226
dirk@427
   227
/**
dirk@427
   228
 Is the given identity really a pEp user?
dirk@453
   229
 If the engine indicates an error, or the identity is not a pEp user, returns false.
dirk@427
   230
 */
dirk@567
   231
- (NSNumber * _Nullable)isPEPUser:(PEPIdentity * _Nonnull)identity
dirk@567
   232
                            error:(NSError * _Nullable * _Nullable)error;
dirk@427
   233
dirk@501
   234
/**
dirk@501
   235
 When (manually) importing (secret) keys, associate them with the given own identity.
dirk@501
   236
 */
dirk@501
   237
- (BOOL)setOwnKey:(PEPIdentity * _Nonnull)identity fingerprint:(NSString * _Nonnull)fingerprint
dirk@501
   238
            error:(NSError * _Nullable * _Nullable)error;
dirk@501
   239
dirk@624
   240
/**
dirk@624
   241
 Wraps the engine's `config_passive_mode`.
dz@1109
   242
 @note That there's absolutely no error handling.
dirk@624
   243
 */
dirk@624
   244
- (void)configurePassiveModeEnabled:(BOOL)enabled;
dirk@624
   245
dirk@768
   246
/**
dz@929
   247
 Wraps set_identity_flags.
dirk@768
   248
 */
dz@825
   249
- (BOOL)setFlags:(PEPIdentityFlags)flags
dirk@772
   250
     forIdentity:(PEPIdentity * _Nonnull)identity
dirk@768
   251
           error:(NSError * _Nullable * _Nullable)error;
dirk@768
   252
dz@919
   253
/**
dz@1122
   254
 Indicate the user's choice during a handshake dialog display.
dz@1122
   255
dz@1122
   256
 Wraps the engine's deliverHandshakeResult. Should be called in response to
dz@1123
   257
 [PEPNotifyHandshakeDelegate notifyHandshake:me:partner:signal
dz@1123
   258
 in accordance with the user's choices.
dz@1122
   259
dz@1122
   260
 @param result The choice the user made with regards to the currently active handshake dialog.
dz@1122
   261
 @param identitiesSharing The identities that are involved for the user's choice.
dz@1122
   262
                          That is, the user can chose to respond only for a subset of the
dz@1122
   263
                          identities that were originally involved in the handshake.
dz@1122
   264
 @param error The default cocoa error handling.
dz@1122
   265
 @return `YES` when the call succedded, `NO` otherwise. In the `NO` case, see `error` for details.
dz@919
   266
 */
dz@827
   267
- (BOOL)deliverHandshakeResult:(PEPSyncHandshakeResult)result
dz@913
   268
             identitiesSharing:(NSArray<PEPIdentity *> * _Nullable)identitiesSharing
dirk@773
   269
                         error:(NSError * _Nullable * _Nullable)error;
dirk@773
   270
dz@775
   271
/**
dz@929
   272
 Wraps trust_own_key.
dz@775
   273
 */
dz@928
   274
- (BOOL)trustOwnKeyIdentity:(PEPIdentity * _Nonnull)identity
dz@775
   275
                      error:(NSError * _Nullable * _Nullable)error;
dz@775
   276
dz@856
   277
/**
dz@856
   278
 Wraps color_from_rating.
dz@856
   279
 */
dz@856
   280
- (PEPColor)colorFromRating:(PEPRating)rating;
dz@856
   281
dz@927
   282
/**
andreas@1421
   283
 Wraps key_reset_user.
dz@927
   284
 */
dz@927
   285
- (BOOL)keyReset:(PEPIdentity * _Nonnull)identity
dz@927
   286
     fingerprint:(NSString * _Nullable)fingerprint
dz@927
   287
           error:(NSError * _Nullable * _Nullable)error;
dz@927
   288
dz@1010
   289
/** Wraps leave_device_group. */
andreas@1330
   290
- (BOOL)leaveDeviceGroup:(NSError * _Nullable * _Nullable)error;
dz@1010
   291
dz@1285
   292
/**
dz@1285
   293
 Revoke and mistrust all own keys. See key_reset_all_own_keys for details.
dz@1285
   294
dz@1285
   295
 @param error The default cocoa error handling.
dz@1285
   296
 @return YES on success, NO if there were errors.
dz@1285
   297
 */
dz@1285
   298
- (BOOL)keyResetAllOwnKeysError:(NSError * _Nullable * _Nullable)error;
dz@1285
   299
dz@1494
   300
/// Add a passphrase for secret keys to the cache.
dz@1499
   301
///
dz@1494
   302
/// You can add as many passphrases to the cache as needed by calling this method.
dz@1494
   303
/// Every passphrase is valid for 10 min (default, compile-time configurable),
dz@1494
   304
/// after that it gets removed from memory. The maximum count of passphrases is 20.
dz@1494
   305
/// Setting the 21st replaces the 1st.
dz@1494
   306
/// On error, `NO` is returned and the (optional) parameter `error`
dz@1494
   307
/// is set to the error that occurred.
dz@1494
   308
/// On every engine call that returns PEPStatusPassphraseRequired, or PEPStatusWrongPassphrase,
dz@1494
   309
/// the adapter will automatically repeat the call after setting the next cached passphrase
dz@1494
   310
/// (using the engine's `config_passphrase`). The first attempet as always with an empty password.
dz@1494
   311
/// This will be repeated until the call either succeeds, or until
dz@1494
   312
/// the adapter runs out of usable passwords.
dz@1494
   313
/// When the adapter runs out of passwords to try, PEPStatusWrongPassphrase will be thrown.
dz@1494
   314
/// If the engine indicates PEPStatusPassphraseRequired, and there are no passwords,
dz@1494
   315
/// the adapter will throw PEPStatusPassphraseRequired.
dz@1494
   316
/// The passphrase can have a "maximum number of code points of 250", which is
dz@1498
   317
/// approximated by checking the string length.
dz@1494
   318
/// If the passphrase exceeds this limit, the adapter throws PEPAdapterErrorPassphraseTooLong
dz@1494
   319
/// with a domain of PEPObjCAdapterErrorDomain.
dz@1522
   320
/// @Throws PEPAdapterErrorPassphraseTooLong (with a domain of PEPObjCAdapterErrorDomain)
dz@1522
   321
/// or PEPStatusOutOfMemory (with PEPObjCAdapterEngineStatusErrorDomain)
dz@1494
   322
- (BOOL)configurePassphrase:(NSString * _Nonnull)passphrase
dz@1494
   323
                      error:(NSError * _Nullable * _Nullable)error;
dz@1494
   324
dz@1517
   325
/// Sets a passphrase (with a maximum of 250 code points) for
dz@1517
   326
/// (own) secret keys generated from now on.
dz@1517
   327
///
dz@1517
   328
/// For setting a passphrase, `enable` must be set to `YES`,
dz@1517
   329
/// in which case the `passphrase` should contain an actual passphrase.
dz@1517
   330
/// A `nil` `passphrase` with `enable` set to `YES` is undefined.
dz@1517
   331
/// The passphrase can be unset by setting `enable` to `NO`
dz@1517
   332
/// (with or without passphrase, this gets (assumedly)
dz@1517
   333
/// ignored in this case, but has to be verified).
dz@1517
   334
/// Uses the engine's `config_passphrase_for_new_keys`.
dz@1517
   335
/// @Throws PEPAdapterErrorPassphraseTooLong (with a domain of PEPObjCAdapterErrorDomain)
dz@1517
   336
/// or PEPStatusOutOfMemory (with PEPObjCAdapterEngineStatusErrorDomain)
dz@1517
   337
- (BOOL)configurePassphraseForNewKeys:(NSString * _Nullable)passphrase
dz@1517
   338
                               enable:(BOOL)enable error:(NSError * _Nullable * _Nullable)error;
dz@1517
   339
dirk@303
   340
@end