pEpObjCAdapterFramework/PEPSessionProtocol.h
author Dirk Zimmermann <dz@pep.security>
Fri, 06 Sep 2019 11:03:27 +0200
branchIOS-1784
changeset 1225 6d89f5f624db
parent 1206 1883fde7438a
child 1285 bca0bfd9cc7a
permissions -rw-r--r--
IOS-1784 Separate concerns.
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
dirk@303
    18
@protocol PEPSessionProtocol <NSObject>
dirk@303
    19
dirk@303
    20
/** Decrypt a message */
dirk@596
    21
- (PEPDict * _Nullable)decryptMessageDict:(PEPMutableDict * _Nonnull)messageDict
dz@818
    22
                                    flags:(PEPDecryptFlags * _Nullable)flags
dz@822
    23
                                   rating:(PEPRating * _Nullable)rating
dirk@523
    24
                                extraKeys:(PEPStringList * _Nullable * _Nullable)extraKeys
dz@822
    25
                                   status:(PEPStatus * _Nullable)status
dirk@517
    26
                                    error:(NSError * _Nullable * _Nullable)error __deprecated;
dirk@383
    27
dirk@383
    28
/** Decrypt a message */
dirk@535
    29
- (PEPMessage * _Nullable)decryptMessage:(PEPMessage * _Nonnull)message
dz@818
    30
                                   flags:(PEPDecryptFlags * _Nullable)flags
dz@822
    31
                                  rating:(PEPRating * _Nullable)rating
dirk@523
    32
                               extraKeys:(PEPStringList * _Nullable * _Nullable)extraKeys
dz@822
    33
                                  status:(PEPStatus * _Nullable)status
dirk@517
    34
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@303
    35
dirk@303
    36
/** Re-evaluate rating of decrypted message */
dirk@535
    37
- (BOOL)reEvaluateMessageDict:(PEPDict * _Nonnull)messageDict
dirk@634
    38
                     xKeyList:(PEPStringList *_Nullable)xKeyList
dz@822
    39
                       rating:(PEPRating * _Nonnull)rating
dz@822
    40
                       status:(PEPStatus * _Nullable)status
dirk@516
    41
                        error:(NSError * _Nullable * _Nullable)error __deprecated;
dirk@384
    42
dirk@384
    43
/** Re-evaluate rating of decrypted message */
dirk@535
    44
- (BOOL)reEvaluateMessage:(PEPMessage * _Nonnull)message
dirk@634
    45
                 xKeyList:(PEPStringList *_Nullable)xKeyList
dz@822
    46
                   rating:(PEPRating * _Nonnull)rating
dz@822
    47
                   status:(PEPStatus * _Nullable)status
dirk@516
    48
                    error:(NSError * _Nullable * _Nullable)error;
dirk@303
    49
dirk@522
    50
/**
dirk@522
    51
 Encrypt a message dictionary, indicating the encoding format.
dirk@522
    52
 @note The resulting message dict could be the input one.
dirk@522
    53
 */
dirk@535
    54
- (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
dirk@535
    55
                                extraKeys:(PEPStringList * _Nullable)extraKeys
dz@818
    56
                                encFormat:(PEPEncFormat)encFormat
dz@822
    57
                                   status:(PEPStatus * _Nullable)status
dirk@522
    58
                                    error:(NSError * _Nullable * _Nullable)error __deprecated;
dirk@303
    59
dirk@522
    60
/**
dirk@522
    61
 Encrypt a message, indicating the encoding format
dirk@522
    62
 @note The resulting message dict could be the input one.
dirk@522
    63
 */
dirk@535
    64
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@535
    65
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@818
    66
                               encFormat:(PEPEncFormat)encFormat
dz@822
    67
                                  status:(PEPStatus * _Nullable)status
dirk@522
    68
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@379
    69
dirk@518
    70
/** Encrypt a message with default encryption format (PEP_enc_PEP) */
dirk@535
    71
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@535
    72
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@822
    73
                                  status:(PEPStatus * _Nullable)status
dirk@522
    74
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@518
    75
dirk@526
    76
/** Encrypt a message dict for the given own identity */
dirk@535
    77
- (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
dirk@557
    78
                                  forSelf:(PEPIdentity * _Nonnull)ownIdentity
dirk@556
    79
                                extraKeys:(PEPStringList * _Nullable)extraKeys
dz@822
    80
                                   status:(PEPStatus * _Nullable)status
dirk@526
    81
                                    error:(NSError * _Nullable * _Nullable)error __deprecated;
dirk@303
    82
dirk@518
    83
/** Encrypt a message for the given own identity */
dirk@535
    84
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@557
    85
                                 forSelf:(PEPIdentity * _Nonnull)ownIdentity
dirk@556
    86
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@822
    87
                                  status:(PEPStatus * _Nullable)status
dirk@526
    88
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@381
    89
dirk@607
    90
/** Encrypt a message dict to the given recipient FPR, attaching the private key */
dirk@607
    91
- (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
dirk@607
    92
                                    toFpr:(NSString * _Nonnull)toFpr
dz@818
    93
                                encFormat:(PEPEncFormat)encFormat
dz@818
    94
                                    flags:(PEPDecryptFlags)flags
dz@822
    95
                                   status:(PEPStatus * _Nullable)status
dirk@607
    96
                                    error:(NSError * _Nullable * _Nullable)error __deprecated;
dirk@607
    97
dirk@607
    98
/** Encrypt a message dict to the given recipient FPR, attaching the private key */
dirk@607
    99
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@607
   100
                                   toFpr:(NSString * _Nonnull)toFpr
dz@818
   101
                               encFormat:(PEPEncFormat)encFormat
dz@818
   102
                                   flags:(PEPDecryptFlags)flags
dz@822
   103
                                  status:(PEPStatus * _Nullable)status
dirk@607
   104
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@607
   105
dirk@303
   106
/** Determine the status color of a message to be sent */
dirk@650
   107
- (NSNumber * _Nullable)outgoingRatingForMessage:(PEPMessage * _Nonnull)theMessage
dirk@573
   108
                                           error:(NSError * _Nullable * _Nullable)error;
dirk@377
   109
dirk@652
   110
/** Determine the preview status color of a message to be sent */
dirk@652
   111
- (NSNumber * _Nullable)outgoingRatingPreviewForMessage:(PEPMessage * _Nonnull)theMessage
dirk@652
   112
                                                  error:(NSError * _Nullable * _Nullable)error;
dirk@652
   113
andreas@407
   114
/**
andreas@407
   115
 Determine the rating of an identity.
andreas@407
   116
 The rating is the rating a _message_ would have, if it is sent to this (and only this) identity.
andreas@407
   117
 It is *not* a rating of the identity. In fact, there is no rating for identities.
andreas@407
   118
 */
dirk@574
   119
- (NSNumber * _Nullable)ratingForIdentity:(PEPIdentity * _Nonnull)identity
dirk@574
   120
                                    error:(NSError * _Nullable * _Nullable)error;
dirk@303
   121
dirk@303
   122
/** Get trustwords for a fingerprint */
dirk@531
   123
- (NSArray * _Nullable)trustwordsForFingerprint:(NSString * _Nonnull)fingerprint
dirk@531
   124
                                     languageID:(NSString * _Nonnull)languageID
dirk@531
   125
                                      shortened:(BOOL)shortened
dirk@531
   126
                                          error:(NSError * _Nullable * _Nullable)error;
dirk@303
   127
dirk@303
   128
/**
dirk@303
   129
 Supply an account used by our user himself. The identity is supplemented with the missing parts
dirk@303
   130
dirk@303
   131
 An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
dirk@303
   132
 An identity can have the following fields (all other keys are ignored).
dirk@303
   133
 It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
dirk@303
   134
dirk@303
   135
 @"username": real name or nick name (if pseudonymous) of identity
dirk@303
   136
 @"address": URI or SMTP address
andreas@407
   137
 @"user_id": persistent unique ID for the *user* that belongs to the identity.
andreas@407
   138
                A user can have multiple identities which all of them MUST use the same user_id.
dirk@303
   139
 @"lang": preferred languageID for communication with this ID (default: @"en")
dirk@303
   140
 @"fpr": fingerprint of key to use for communication with this ID
dirk@303
   141
 @"comm_type": communication type code (usually not needed)
dirk@303
   142
dirk@303
   143
 As an example:
dirk@303
   144
dirk@303
   145
 User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
dirk@303
   146
dirk@303
   147
 NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
dirk@303
   148
 @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address",
dirk@303
   149
 @"23", @"user_id", nil];
dirk@303
   150
dirk@303
   151
 */
dirk@535
   152
- (BOOL)mySelf:(PEPIdentity * _Nonnull)identity error:(NSError * _Nullable * _Nullable)error;
dirk@303
   153
dirk@303
   154
/**
dirk@303
   155
 Supplement missing information for an arbitrary identity (used for communication partners).
dirk@521
   156
 Will call the engine's myself() or update_identity() internally, depending on the given
dirk@521
   157
 identity.
dirk@303
   158
 */
dirk@535
   159
- (BOOL)updateIdentity:(PEPIdentity * _Nonnull)identity
dirk@535
   160
                 error:(NSError * _Nullable * _Nullable)error;
dirk@303
   161
dirk@303
   162
/**
dirk@303
   163
 Mark a key as trusted with a person.
dirk@303
   164
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@303
   165
 */
dirk@535
   166
- (BOOL)trustPersonalKey:(PEPIdentity * _Nonnull)identity
dirk@534
   167
                   error:(NSError * _Nullable * _Nullable)error;
dirk@303
   168
dirk@303
   169
/**
dirk@303
   170
 if a key is not trusted by the user tell this using this message
dirk@303
   171
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@303
   172
 */
dirk@536
   173
- (BOOL)keyMistrusted:(PEPIdentity * _Nonnull)identity
dirk@536
   174
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   175
dirk@303
   176
/**
dirk@303
   177
 Use this to undo keyCompromized or trustPersonalKey
dirk@303
   178
 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
dirk@303
   179
 */
dirk@545
   180
- (BOOL)keyResetTrust:(PEPIdentity * _Nonnull)identity
dirk@545
   181
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   182
dz@1189
   183
/**
dz@1189
   184
 Enables key sync.
dz@1189
   185
dz@1189
   186
 Wraps enable_identity_for_sync.
dz@1189
   187
dz@1189
   188
 @param identity The (own) identity to enable key sync for.
dz@1189
   189
 @param error The usual cocoa error handling.
dz@1189
   190
 @return The usual cocoa error handling.
dz@1189
   191
 */
dz@1181
   192
- (BOOL)enableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1181
   193
                        error:(NSError * _Nullable * _Nullable)error;
dz@1181
   194
dz@1189
   195
/**
dz@1189
   196
 Disables key sync.
dz@1189
   197
dz@1189
   198
 Wraps disable_identity_for_sync.
dz@1189
   199
dz@1189
   200
 @param identity The (own) identity to disable key sync for.
dz@1189
   201
 @param error The usual cocoa error handling.
dz@1189
   202
 @return The usual cocoa error handling.
dz@1189
   203
 */
dz@1186
   204
- (BOOL)disableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1186
   205
                         error:(NSError * _Nullable * _Nullable)error;
dz@1186
   206
dz@1190
   207
/**
dz@1206
   208
 Queries the given own identity on whether it has key sync disabled or not.
dz@1190
   209
dz@1190
   210
 @param identity The (own) identity to query.
dz@1190
   211
 @param error The usual cocoa error handling.
dz@1190
   212
 @return An NSNumber containing a boolean denoting whether key sync is enabled or not, or
dz@1206
   213
         nil on error. YES means that key sync is allowed for this identity, otherwise it's NO.
dz@1190
   214
 */
dz@1190
   215
- (NSNumber * _Nullable)queryKeySyncEnabledForIdentity:(PEPIdentity * _Nonnull)identity
dz@1190
   216
                                                 error:(NSError * _Nullable * _Nullable)error;
dz@1190
   217
dirk@303
   218
#pragma mark -- Internal API (testing etc.)
dirk@303
   219
dirk@303
   220
/** For testing purpose, manual key import */
dirk@672
   221
- (NSArray<PEPIdentity *> * _Nullable)importKey:(NSString * _Nonnull)keydata
dirk@672
   222
                                          error:(NSError * _Nullable * _Nullable)error;
dirk@303
   223
dirk@553
   224
- (BOOL)logTitle:(NSString * _Nonnull)title
dirk@553
   225
          entity:(NSString * _Nonnull)entity
dirk@553
   226
     description:(NSString * _Nullable)description
dirk@553
   227
         comment:(NSString * _Nullable)comment
dirk@553
   228
           error:(NSError * _Nullable * _Nullable)error;
dirk@303
   229
dirk@303
   230
/**
dirk@475
   231
 Retrieves the log from the engine, or nil, if there is nothing yet.
dirk@303
   232
 */
dirk@552
   233
- (NSString * _Nullable)getLogWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   234
dirk@303
   235
/** Determine trustwords for two identities */
dirk@535
   236
- (NSString * _Nullable)getTrustwordsIdentity1:(PEPIdentity * _Nonnull)identity1
dirk@535
   237
                                     identity2:(PEPIdentity * _Nonnull)identity2
dirk@535
   238
                                      language:(NSString * _Nullable)language
dirk@558
   239
                                          full:(BOOL)full
dirk@558
   240
                                         error:(NSError * _Nullable * _Nullable)error;
dirk@303
   241
vb@986
   242
/** Determine trustwords for two fprs */
vb@986
   243
- (NSString * _Nullable)getTrustwordsFpr1:(NSString * _Nonnull)fpr1
vb@986
   244
                                     fpr2:(NSString * _Nonnull)fpr2
vb@986
   245
                                 language:(NSString * _Nullable)language
vb@986
   246
                                     full:(BOOL)full
vb@986
   247
                                    error:(NSError * _Nullable * _Nullable)error;
vb@986
   248
dirk@303
   249
/**
dirk@303
   250
 @returns The list of supported languages for trustwords.
dirk@303
   251
 */
dirk@560
   252
- (NSArray<PEPLanguage *> * _Nullable)languageListWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   253
dirk@303
   254
/**
dz@822
   255
 Can convert a string like "cannot_decrypt" into its equivalent PEPRating_cannot_decrypt.
dirk@417
   256
 */
dz@822
   257
- (PEPRating)ratingFromString:(NSString * _Nonnull)string;
dirk@417
   258
dirk@417
   259
/**
dz@822
   260
 Can convert a pEp rating like PEPRating_cannot_decrypt
dirk@417
   261
 into its equivalent string "cannot_decrypt" .
dirk@417
   262
 */
dz@822
   263
- (NSString * _Nonnull)stringFromRating:(PEPRating)rating;
dirk@417
   264
dirk@427
   265
/**
dirk@427
   266
 Is the given identity really a pEp user?
dirk@453
   267
 If the engine indicates an error, or the identity is not a pEp user, returns false.
dirk@427
   268
 */
dirk@567
   269
- (NSNumber * _Nullable)isPEPUser:(PEPIdentity * _Nonnull)identity
dirk@567
   270
                            error:(NSError * _Nullable * _Nullable)error;
dirk@427
   271
dirk@501
   272
/**
dirk@501
   273
 When (manually) importing (secret) keys, associate them with the given own identity.
dirk@501
   274
 */
dirk@501
   275
- (BOOL)setOwnKey:(PEPIdentity * _Nonnull)identity fingerprint:(NSString * _Nonnull)fingerprint
dirk@501
   276
            error:(NSError * _Nullable * _Nullable)error;
dirk@501
   277
dirk@624
   278
/**
dirk@624
   279
 Wraps the engine's `config_passive_mode`.
dz@1109
   280
 @note That there's absolutely no error handling.
dirk@624
   281
 */
dirk@624
   282
- (void)configurePassiveModeEnabled:(BOOL)enabled;
dirk@624
   283
dirk@768
   284
/**
dz@929
   285
 Wraps set_identity_flags.
dirk@768
   286
 */
dz@825
   287
- (BOOL)setFlags:(PEPIdentityFlags)flags
dirk@772
   288
     forIdentity:(PEPIdentity * _Nonnull)identity
dirk@768
   289
           error:(NSError * _Nullable * _Nullable)error;
dirk@768
   290
dz@919
   291
/**
dz@1122
   292
 Indicate the user's choice during a handshake dialog display.
dz@1122
   293
dz@1122
   294
 Wraps the engine's deliverHandshakeResult. Should be called in response to
dz@1123
   295
 [PEPNotifyHandshakeDelegate notifyHandshake:me:partner:signal
dz@1123
   296
 in accordance with the user's choices.
dz@1122
   297
dz@1122
   298
 @param result The choice the user made with regards to the currently active handshake dialog.
dz@1122
   299
 @param identitiesSharing The identities that are involved for the user's choice.
dz@1122
   300
                          That is, the user can chose to respond only for a subset of the
dz@1122
   301
                          identities that were originally involved in the handshake.
dz@1122
   302
 @param error The default cocoa error handling.
dz@1122
   303
 @return `YES` when the call succedded, `NO` otherwise. In the `NO` case, see `error` for details.
dz@919
   304
 */
dz@827
   305
- (BOOL)deliverHandshakeResult:(PEPSyncHandshakeResult)result
dz@913
   306
             identitiesSharing:(NSArray<PEPIdentity *> * _Nullable)identitiesSharing
dirk@773
   307
                         error:(NSError * _Nullable * _Nullable)error;
dirk@773
   308
dz@775
   309
/**
dz@929
   310
 Wraps trust_own_key.
dz@775
   311
 */
dz@928
   312
- (BOOL)trustOwnKeyIdentity:(PEPIdentity * _Nonnull)identity
dz@775
   313
                      error:(NSError * _Nullable * _Nullable)error;
dz@775
   314
dz@856
   315
/**
dz@856
   316
 Wraps color_from_rating.
dz@856
   317
 */
dz@856
   318
- (PEPColor)colorFromRating:(PEPRating)rating;
dz@856
   319
dz@927
   320
/**
dz@927
   321
 Wraps key_reset_identity.
dz@927
   322
 */
dz@927
   323
- (BOOL)keyReset:(PEPIdentity * _Nonnull)identity
dz@927
   324
     fingerprint:(NSString * _Nullable)fingerprint
dz@927
   325
           error:(NSError * _Nullable * _Nullable)error;
dz@927
   326
dz@1010
   327
/** Wraps leave_device_group. */
dz@1010
   328
- (BOOL)leaveDeviceGroupError:(NSError * _Nullable * _Nullable)error;
dz@1010
   329
dirk@303
   330
@end