pEpObjCAdapterFramework/PEPSessionProtocol.h
author Dirk Zimmermann <dz@pep.security>
Tue, 03 Dec 2019 14:07:27 +0100
branchIOSAD-160
changeset 1372 ac119be204d2
parent 1371 3fa5bcebb17b
child 1387 b0e0c5afc224
permissions -rw-r--r--
IOSAD-160 Add 2nd myself instead of changing the original one
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@535
    21
- (PEPMessage * _Nullable)decryptMessage:(PEPMessage * _Nonnull)message
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;
dirk@303
    27
dirk@303
    28
/** Re-evaluate rating of decrypted message */
dirk@535
    29
- (BOOL)reEvaluateMessage:(PEPMessage * _Nonnull)message
dirk@634
    30
                 xKeyList:(PEPStringList *_Nullable)xKeyList
dz@822
    31
                   rating:(PEPRating * _Nonnull)rating
dz@822
    32
                   status:(PEPStatus * _Nullable)status
dirk@516
    33
                    error:(NSError * _Nullable * _Nullable)error;
dirk@303
    34
dirk@522
    35
/**
dirk@522
    36
 Encrypt a message, indicating the encoding format
dirk@522
    37
 @note The resulting message dict could be the input one.
dirk@522
    38
 */
dirk@535
    39
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@535
    40
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@818
    41
                               encFormat:(PEPEncFormat)encFormat
dz@822
    42
                                  status:(PEPStatus * _Nullable)status
dirk@522
    43
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@379
    44
dirk@518
    45
/** Encrypt a message with default encryption format (PEP_enc_PEP) */
dirk@535
    46
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@535
    47
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@822
    48
                                  status:(PEPStatus * _Nullable)status
dirk@522
    49
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@518
    50
dirk@518
    51
/** Encrypt a message for the given own identity */
dirk@535
    52
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@557
    53
                                 forSelf:(PEPIdentity * _Nonnull)ownIdentity
dirk@556
    54
                               extraKeys:(PEPStringList * _Nullable)extraKeys
dz@822
    55
                                  status:(PEPStatus * _Nullable)status
dirk@526
    56
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@381
    57
andreas@1318
    58
/** Encrypt a message to the given recipient FPR, attaching the private key */
dirk@607
    59
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
dirk@607
    60
                                   toFpr:(NSString * _Nonnull)toFpr
dz@818
    61
                               encFormat:(PEPEncFormat)encFormat
dz@818
    62
                                   flags:(PEPDecryptFlags)flags
dz@822
    63
                                  status:(PEPStatus * _Nullable)status
dirk@607
    64
                                   error:(NSError * _Nullable * _Nullable)error;
dirk@607
    65
dirk@303
    66
/** Determine the status color of a message to be sent */
dirk@650
    67
- (NSNumber * _Nullable)outgoingRatingForMessage:(PEPMessage * _Nonnull)theMessage
dirk@573
    68
                                           error:(NSError * _Nullable * _Nullable)error;
dirk@377
    69
dirk@652
    70
/** Determine the preview status color of a message to be sent */
dirk@652
    71
- (NSNumber * _Nullable)outgoingRatingPreviewForMessage:(PEPMessage * _Nonnull)theMessage
dirk@652
    72
                                                  error:(NSError * _Nullable * _Nullable)error;
dirk@652
    73
andreas@407
    74
/**
andreas@407
    75
 Determine the rating of an identity.
andreas@407
    76
 The rating is the rating a _message_ would have, if it is sent to this (and only this) identity.
andreas@407
    77
 It is *not* a rating of the identity. In fact, there is no rating for identities.
andreas@407
    78
 */
dirk@574
    79
- (NSNumber * _Nullable)ratingForIdentity:(PEPIdentity * _Nonnull)identity
dirk@574
    80
                                    error:(NSError * _Nullable * _Nullable)error;
dirk@303
    81
dirk@303
    82
/** Get trustwords for a fingerprint */
dirk@531
    83
- (NSArray * _Nullable)trustwordsForFingerprint:(NSString * _Nonnull)fingerprint
dirk@531
    84
                                     languageID:(NSString * _Nonnull)languageID
dirk@531
    85
                                      shortened:(BOOL)shortened
dirk@531
    86
                                          error:(NSError * _Nullable * _Nullable)error;
dirk@303
    87
dz@1372
    88
/// Marks an identity as an own identity, not changing its participation in pEp sync.
dz@1372
    89
///
dz@1372
    90
/// @return Returns YES on success, NO on error, setting `*error` accordingly if possible.
dz@1372
    91
///
dz@1372
    92
/// @note See the engine's myself function for details.
dz@1372
    93
///
dz@1372
    94
/// @param identity The identity to mark as own.
dz@1372
    95
///
dz@1372
    96
/// @param error Standard cocoa error handling.
dz@1372
    97
- (BOOL)mySelf:(PEPIdentity * _Nonnull)identity
dz@1372
    98
         error:(NSError * _Nullable * _Nullable)error;
dz@1372
    99
dz@1372
   100
/// Marks an identity as an own identity, and decides about participation in pEp sync.
dz@1371
   101
///
dz@1370
   102
/// @return Returns YES on success, NO on error, setting `*error` accordingly if possible.
dz@1371
   103
///
dz@1368
   104
/// @note See the engine's myself function for details.
dz@1371
   105
///
dz@1368
   106
/// @param identity The identity to mark as own.
dz@1371
   107
///
dz@1368
   108
/// @param pEpSyncEnabled Whether to enable sync, or not. Will set PEP_idf_not_for_sync
dz@1368
   109
/// accordingly.
dz@1371
   110
///
dz@1368
   111
/// @param error Standard cocoa error handling.
dz@1368
   112
- (BOOL)mySelf:(PEPIdentity * _Nonnull)identity
dz@1368
   113
pEpSyncEnabled:(BOOL)pEpSyncEnabled
dz@1368
   114
         error:(NSError * _Nullable * _Nullable)error;
dirk@303
   115
dz@1369
   116
/// Calls the engine's update_identity on the given identity.
dz@1371
   117
///
dz@1369
   118
/// @note Prior this was invoking myself if the identity was identified as being an own
dz@1369
   119
/// identity, but this not the case anymore, since it cannot decide if the identity should
dz@1369
   120
/// participate in pEp sync or not.
dz@1371
   121
///
dz@1369
   122
/// @return Returns YES on success, NO on error, setting `*error` accordingly if possible.
dz@1371
   123
///
dz@1369
   124
/// @param identity The identity for which to call update_identity.
dz@1371
   125
/// 
dz@1369
   126
/// @param error Standart cocoa error handling.
dirk@535
   127
- (BOOL)updateIdentity:(PEPIdentity * _Nonnull)identity
dirk@535
   128
                 error:(NSError * _Nullable * _Nullable)error;
dirk@303
   129
dirk@303
   130
/**
dirk@303
   131
 Mark a key as trusted with a person.
dirk@303
   132
 */
dirk@535
   133
- (BOOL)trustPersonalKey:(PEPIdentity * _Nonnull)identity
dirk@534
   134
                   error:(NSError * _Nullable * _Nullable)error;
dirk@303
   135
dirk@303
   136
/**
dirk@303
   137
 if a key is not trusted by the user tell this using this message
dirk@303
   138
 */
dirk@536
   139
- (BOOL)keyMistrusted:(PEPIdentity * _Nonnull)identity
dirk@536
   140
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   141
dirk@303
   142
/**
dirk@303
   143
 Use this to undo keyCompromized or trustPersonalKey
dirk@303
   144
 */
dirk@545
   145
- (BOOL)keyResetTrust:(PEPIdentity * _Nonnull)identity
dirk@545
   146
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   147
dz@1189
   148
/**
dz@1189
   149
 Enables key sync.
dz@1189
   150
dz@1189
   151
 Wraps enable_identity_for_sync.
dz@1189
   152
dz@1189
   153
 @param identity The (own) identity to enable key sync for.
dz@1189
   154
 @param error The usual cocoa error handling.
dz@1189
   155
 @return The usual cocoa error handling.
dz@1189
   156
 */
dz@1181
   157
- (BOOL)enableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1181
   158
                        error:(NSError * _Nullable * _Nullable)error;
dz@1181
   159
dz@1189
   160
/**
dz@1189
   161
 Disables key sync.
dz@1189
   162
dz@1189
   163
 Wraps disable_identity_for_sync.
dz@1189
   164
dz@1189
   165
 @param identity The (own) identity to disable key sync for.
dz@1189
   166
 @param error The usual cocoa error handling.
dz@1189
   167
 @return The usual cocoa error handling.
dz@1189
   168
 */
dz@1186
   169
- (BOOL)disableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1186
   170
                         error:(NSError * _Nullable * _Nullable)error;
dz@1186
   171
dz@1190
   172
/**
dz@1206
   173
 Queries the given own identity on whether it has key sync disabled or not.
dz@1190
   174
dz@1190
   175
 @param identity The (own) identity to query.
dz@1190
   176
 @param error The usual cocoa error handling.
dz@1190
   177
 @return An NSNumber containing a boolean denoting whether key sync is enabled or not, or
dz@1206
   178
         nil on error. YES means that key sync is allowed for this identity, otherwise it's NO.
dz@1190
   179
 */
dz@1190
   180
- (NSNumber * _Nullable)queryKeySyncEnabledForIdentity:(PEPIdentity * _Nonnull)identity
dz@1190
   181
                                                 error:(NSError * _Nullable * _Nullable)error;
dz@1190
   182
dirk@303
   183
#pragma mark -- Internal API (testing etc.)
dirk@303
   184
dirk@303
   185
/** For testing purpose, manual key import */
dirk@672
   186
- (NSArray<PEPIdentity *> * _Nullable)importKey:(NSString * _Nonnull)keydata
dirk@672
   187
                                          error:(NSError * _Nullable * _Nullable)error;
dirk@303
   188
dirk@553
   189
- (BOOL)logTitle:(NSString * _Nonnull)title
dirk@553
   190
          entity:(NSString * _Nonnull)entity
dirk@553
   191
     description:(NSString * _Nullable)description
dirk@553
   192
         comment:(NSString * _Nullable)comment
dirk@553
   193
           error:(NSError * _Nullable * _Nullable)error;
dirk@303
   194
dirk@303
   195
/**
dirk@475
   196
 Retrieves the log from the engine, or nil, if there is nothing yet.
dirk@303
   197
 */
dirk@552
   198
- (NSString * _Nullable)getLogWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   199
dirk@303
   200
/** Determine trustwords for two identities */
dirk@535
   201
- (NSString * _Nullable)getTrustwordsIdentity1:(PEPIdentity * _Nonnull)identity1
dirk@535
   202
                                     identity2:(PEPIdentity * _Nonnull)identity2
dirk@535
   203
                                      language:(NSString * _Nullable)language
dirk@558
   204
                                          full:(BOOL)full
dirk@558
   205
                                         error:(NSError * _Nullable * _Nullable)error;
dirk@303
   206
vb@986
   207
/** Determine trustwords for two fprs */
vb@986
   208
- (NSString * _Nullable)getTrustwordsFpr1:(NSString * _Nonnull)fpr1
vb@986
   209
                                     fpr2:(NSString * _Nonnull)fpr2
vb@986
   210
                                 language:(NSString * _Nullable)language
vb@986
   211
                                     full:(BOOL)full
vb@986
   212
                                    error:(NSError * _Nullable * _Nullable)error;
vb@986
   213
dirk@303
   214
/**
dirk@303
   215
 @returns The list of supported languages for trustwords.
dirk@303
   216
 */
dirk@560
   217
- (NSArray<PEPLanguage *> * _Nullable)languageListWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   218
dirk@303
   219
/**
dz@822
   220
 Can convert a string like "cannot_decrypt" into its equivalent PEPRating_cannot_decrypt.
dirk@417
   221
 */
dz@822
   222
- (PEPRating)ratingFromString:(NSString * _Nonnull)string;
dirk@417
   223
dirk@417
   224
/**
dz@822
   225
 Can convert a pEp rating like PEPRating_cannot_decrypt
dirk@417
   226
 into its equivalent string "cannot_decrypt" .
dirk@417
   227
 */
dz@822
   228
- (NSString * _Nonnull)stringFromRating:(PEPRating)rating;
dirk@417
   229
dirk@427
   230
/**
dirk@427
   231
 Is the given identity really a pEp user?
dirk@453
   232
 If the engine indicates an error, or the identity is not a pEp user, returns false.
dirk@427
   233
 */
dirk@567
   234
- (NSNumber * _Nullable)isPEPUser:(PEPIdentity * _Nonnull)identity
dirk@567
   235
                            error:(NSError * _Nullable * _Nullable)error;
dirk@427
   236
dirk@501
   237
/**
dirk@501
   238
 When (manually) importing (secret) keys, associate them with the given own identity.
dirk@501
   239
 */
dirk@501
   240
- (BOOL)setOwnKey:(PEPIdentity * _Nonnull)identity fingerprint:(NSString * _Nonnull)fingerprint
dirk@501
   241
            error:(NSError * _Nullable * _Nullable)error;
dirk@501
   242
dirk@624
   243
/**
dirk@624
   244
 Wraps the engine's `config_passive_mode`.
dz@1109
   245
 @note That there's absolutely no error handling.
dirk@624
   246
 */
dirk@624
   247
- (void)configurePassiveModeEnabled:(BOOL)enabled;
dirk@624
   248
dirk@768
   249
/**
dz@929
   250
 Wraps set_identity_flags.
dirk@768
   251
 */
dz@825
   252
- (BOOL)setFlags:(PEPIdentityFlags)flags
dirk@772
   253
     forIdentity:(PEPIdentity * _Nonnull)identity
dirk@768
   254
           error:(NSError * _Nullable * _Nullable)error;
dirk@768
   255
dz@919
   256
/**
dz@1122
   257
 Indicate the user's choice during a handshake dialog display.
dz@1122
   258
dz@1122
   259
 Wraps the engine's deliverHandshakeResult. Should be called in response to
dz@1123
   260
 [PEPNotifyHandshakeDelegate notifyHandshake:me:partner:signal
dz@1123
   261
 in accordance with the user's choices.
dz@1122
   262
dz@1122
   263
 @param result The choice the user made with regards to the currently active handshake dialog.
dz@1122
   264
 @param identitiesSharing The identities that are involved for the user's choice.
dz@1122
   265
                          That is, the user can chose to respond only for a subset of the
dz@1122
   266
                          identities that were originally involved in the handshake.
dz@1122
   267
 @param error The default cocoa error handling.
dz@1122
   268
 @return `YES` when the call succedded, `NO` otherwise. In the `NO` case, see `error` for details.
dz@919
   269
 */
dz@827
   270
- (BOOL)deliverHandshakeResult:(PEPSyncHandshakeResult)result
dz@913
   271
             identitiesSharing:(NSArray<PEPIdentity *> * _Nullable)identitiesSharing
dirk@773
   272
                         error:(NSError * _Nullable * _Nullable)error;
dirk@773
   273
dz@775
   274
/**
dz@929
   275
 Wraps trust_own_key.
dz@775
   276
 */
dz@928
   277
- (BOOL)trustOwnKeyIdentity:(PEPIdentity * _Nonnull)identity
dz@775
   278
                      error:(NSError * _Nullable * _Nullable)error;
dz@775
   279
dz@856
   280
/**
dz@856
   281
 Wraps color_from_rating.
dz@856
   282
 */
dz@856
   283
- (PEPColor)colorFromRating:(PEPRating)rating;
dz@856
   284
dz@927
   285
/**
dz@927
   286
 Wraps key_reset_identity.
dz@927
   287
 */
dz@927
   288
- (BOOL)keyReset:(PEPIdentity * _Nonnull)identity
dz@927
   289
     fingerprint:(NSString * _Nullable)fingerprint
dz@927
   290
           error:(NSError * _Nullable * _Nullable)error;
dz@927
   291
dz@1010
   292
/** Wraps leave_device_group. */
andreas@1330
   293
- (BOOL)leaveDeviceGroup:(NSError * _Nullable * _Nullable)error;
dz@1010
   294
dz@1285
   295
/**
dz@1285
   296
 Revoke and mistrust all own keys. See key_reset_all_own_keys for details.
dz@1285
   297
dz@1285
   298
 @param error The default cocoa error handling.
dz@1285
   299
 @return YES on success, NO if there were errors.
dz@1285
   300
 */
dz@1285
   301
- (BOOL)keyResetAllOwnKeysError:(NSError * _Nullable * _Nullable)error;
dz@1285
   302
dirk@303
   303
@end