pEpObjCAdapterFramework/PEPSessionProtocol.h
author Dirk Zimmermann <dz@pep.security>
Tue, 03 Dec 2019 14:07:27 +0100
branchIOSAD-160
changeset 1370 d8d271b0bab8
parent 1369 c22f0fbc9597
child 1371 3fa5bcebb17b
permissions -rw-r--r--
IOSAD-160 Improve docs
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@1368
    88
/// Marks an identity as an own identity.
dz@1370
    89
/// @return Returns YES on success, NO on error, setting `*error` accordingly if possible.
dz@1368
    90
/// @note See the engine's myself function for details.
dz@1368
    91
/// @param identity The identity to mark as own.
dz@1368
    92
/// @param pEpSyncEnabled Whether to enable sync, or not. Will set PEP_idf_not_for_sync
dz@1368
    93
/// accordingly.
dz@1368
    94
/// @param error Standard cocoa error handling.
dz@1368
    95
- (BOOL)mySelf:(PEPIdentity * _Nonnull)identity
dz@1368
    96
pEpSyncEnabled:(BOOL)pEpSyncEnabled
dz@1368
    97
         error:(NSError * _Nullable * _Nullable)error;
dirk@303
    98
dz@1369
    99
/// Calls the engine's update_identity on the given identity.
dz@1369
   100
/// @note Prior this was invoking myself if the identity was identified as being an own
dz@1369
   101
/// identity, but this not the case anymore, since it cannot decide if the identity should
dz@1369
   102
/// participate in pEp sync or not.
dz@1369
   103
/// @return Returns YES on success, NO on error, setting `*error` accordingly if possible.
dz@1369
   104
/// @param identity The identity for which to call update_identity.
dz@1369
   105
/// @param error Standart cocoa error handling.
dirk@535
   106
- (BOOL)updateIdentity:(PEPIdentity * _Nonnull)identity
dirk@535
   107
                 error:(NSError * _Nullable * _Nullable)error;
dirk@303
   108
dirk@303
   109
/**
dirk@303
   110
 Mark a key as trusted with a person.
dirk@303
   111
 */
dirk@535
   112
- (BOOL)trustPersonalKey:(PEPIdentity * _Nonnull)identity
dirk@534
   113
                   error:(NSError * _Nullable * _Nullable)error;
dirk@303
   114
dirk@303
   115
/**
dirk@303
   116
 if a key is not trusted by the user tell this using this message
dirk@303
   117
 */
dirk@536
   118
- (BOOL)keyMistrusted:(PEPIdentity * _Nonnull)identity
dirk@536
   119
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   120
dirk@303
   121
/**
dirk@303
   122
 Use this to undo keyCompromized or trustPersonalKey
dirk@303
   123
 */
dirk@545
   124
- (BOOL)keyResetTrust:(PEPIdentity * _Nonnull)identity
dirk@545
   125
                error:(NSError * _Nullable * _Nullable)error;
dirk@303
   126
dz@1189
   127
/**
dz@1189
   128
 Enables key sync.
dz@1189
   129
dz@1189
   130
 Wraps enable_identity_for_sync.
dz@1189
   131
dz@1189
   132
 @param identity The (own) identity to enable key sync for.
dz@1189
   133
 @param error The usual cocoa error handling.
dz@1189
   134
 @return The usual cocoa error handling.
dz@1189
   135
 */
dz@1181
   136
- (BOOL)enableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1181
   137
                        error:(NSError * _Nullable * _Nullable)error;
dz@1181
   138
dz@1189
   139
/**
dz@1189
   140
 Disables key sync.
dz@1189
   141
dz@1189
   142
 Wraps disable_identity_for_sync.
dz@1189
   143
dz@1189
   144
 @param identity The (own) identity to disable key sync for.
dz@1189
   145
 @param error The usual cocoa error handling.
dz@1189
   146
 @return The usual cocoa error handling.
dz@1189
   147
 */
dz@1186
   148
- (BOOL)disableSyncForIdentity:(PEPIdentity * _Nonnull)identity
dz@1186
   149
                         error:(NSError * _Nullable * _Nullable)error;
dz@1186
   150
dz@1190
   151
/**
dz@1206
   152
 Queries the given own identity on whether it has key sync disabled or not.
dz@1190
   153
dz@1190
   154
 @param identity The (own) identity to query.
dz@1190
   155
 @param error The usual cocoa error handling.
dz@1190
   156
 @return An NSNumber containing a boolean denoting whether key sync is enabled or not, or
dz@1206
   157
         nil on error. YES means that key sync is allowed for this identity, otherwise it's NO.
dz@1190
   158
 */
dz@1190
   159
- (NSNumber * _Nullable)queryKeySyncEnabledForIdentity:(PEPIdentity * _Nonnull)identity
dz@1190
   160
                                                 error:(NSError * _Nullable * _Nullable)error;
dz@1190
   161
dirk@303
   162
#pragma mark -- Internal API (testing etc.)
dirk@303
   163
dirk@303
   164
/** For testing purpose, manual key import */
dirk@672
   165
- (NSArray<PEPIdentity *> * _Nullable)importKey:(NSString * _Nonnull)keydata
dirk@672
   166
                                          error:(NSError * _Nullable * _Nullable)error;
dirk@303
   167
dirk@553
   168
- (BOOL)logTitle:(NSString * _Nonnull)title
dirk@553
   169
          entity:(NSString * _Nonnull)entity
dirk@553
   170
     description:(NSString * _Nullable)description
dirk@553
   171
         comment:(NSString * _Nullable)comment
dirk@553
   172
           error:(NSError * _Nullable * _Nullable)error;
dirk@303
   173
dirk@303
   174
/**
dirk@475
   175
 Retrieves the log from the engine, or nil, if there is nothing yet.
dirk@303
   176
 */
dirk@552
   177
- (NSString * _Nullable)getLogWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   178
dirk@303
   179
/** Determine trustwords for two identities */
dirk@535
   180
- (NSString * _Nullable)getTrustwordsIdentity1:(PEPIdentity * _Nonnull)identity1
dirk@535
   181
                                     identity2:(PEPIdentity * _Nonnull)identity2
dirk@535
   182
                                      language:(NSString * _Nullable)language
dirk@558
   183
                                          full:(BOOL)full
dirk@558
   184
                                         error:(NSError * _Nullable * _Nullable)error;
dirk@303
   185
vb@986
   186
/** Determine trustwords for two fprs */
vb@986
   187
- (NSString * _Nullable)getTrustwordsFpr1:(NSString * _Nonnull)fpr1
vb@986
   188
                                     fpr2:(NSString * _Nonnull)fpr2
vb@986
   189
                                 language:(NSString * _Nullable)language
vb@986
   190
                                     full:(BOOL)full
vb@986
   191
                                    error:(NSError * _Nullable * _Nullable)error;
vb@986
   192
dirk@303
   193
/**
dirk@303
   194
 @returns The list of supported languages for trustwords.
dirk@303
   195
 */
dirk@560
   196
- (NSArray<PEPLanguage *> * _Nullable)languageListWithError:(NSError * _Nullable * _Nullable)error;
dirk@303
   197
dirk@303
   198
/**
dz@822
   199
 Can convert a string like "cannot_decrypt" into its equivalent PEPRating_cannot_decrypt.
dirk@417
   200
 */
dz@822
   201
- (PEPRating)ratingFromString:(NSString * _Nonnull)string;
dirk@417
   202
dirk@417
   203
/**
dz@822
   204
 Can convert a pEp rating like PEPRating_cannot_decrypt
dirk@417
   205
 into its equivalent string "cannot_decrypt" .
dirk@417
   206
 */
dz@822
   207
- (NSString * _Nonnull)stringFromRating:(PEPRating)rating;
dirk@417
   208
dirk@427
   209
/**
dirk@427
   210
 Is the given identity really a pEp user?
dirk@453
   211
 If the engine indicates an error, or the identity is not a pEp user, returns false.
dirk@427
   212
 */
dirk@567
   213
- (NSNumber * _Nullable)isPEPUser:(PEPIdentity * _Nonnull)identity
dirk@567
   214
                            error:(NSError * _Nullable * _Nullable)error;
dirk@427
   215
dirk@501
   216
/**
dirk@501
   217
 When (manually) importing (secret) keys, associate them with the given own identity.
dirk@501
   218
 */
dirk@501
   219
- (BOOL)setOwnKey:(PEPIdentity * _Nonnull)identity fingerprint:(NSString * _Nonnull)fingerprint
dirk@501
   220
            error:(NSError * _Nullable * _Nullable)error;
dirk@501
   221
dirk@624
   222
/**
dirk@624
   223
 Wraps the engine's `config_passive_mode`.
dz@1109
   224
 @note That there's absolutely no error handling.
dirk@624
   225
 */
dirk@624
   226
- (void)configurePassiveModeEnabled:(BOOL)enabled;
dirk@624
   227
dirk@768
   228
/**
dz@929
   229
 Wraps set_identity_flags.
dirk@768
   230
 */
dz@825
   231
- (BOOL)setFlags:(PEPIdentityFlags)flags
dirk@772
   232
     forIdentity:(PEPIdentity * _Nonnull)identity
dirk@768
   233
           error:(NSError * _Nullable * _Nullable)error;
dirk@768
   234
dz@919
   235
/**
dz@1122
   236
 Indicate the user's choice during a handshake dialog display.
dz@1122
   237
dz@1122
   238
 Wraps the engine's deliverHandshakeResult. Should be called in response to
dz@1123
   239
 [PEPNotifyHandshakeDelegate notifyHandshake:me:partner:signal
dz@1123
   240
 in accordance with the user's choices.
dz@1122
   241
dz@1122
   242
 @param result The choice the user made with regards to the currently active handshake dialog.
dz@1122
   243
 @param identitiesSharing The identities that are involved for the user's choice.
dz@1122
   244
                          That is, the user can chose to respond only for a subset of the
dz@1122
   245
                          identities that were originally involved in the handshake.
dz@1122
   246
 @param error The default cocoa error handling.
dz@1122
   247
 @return `YES` when the call succedded, `NO` otherwise. In the `NO` case, see `error` for details.
dz@919
   248
 */
dz@827
   249
- (BOOL)deliverHandshakeResult:(PEPSyncHandshakeResult)result
dz@913
   250
             identitiesSharing:(NSArray<PEPIdentity *> * _Nullable)identitiesSharing
dirk@773
   251
                         error:(NSError * _Nullable * _Nullable)error;
dirk@773
   252
dz@775
   253
/**
dz@929
   254
 Wraps trust_own_key.
dz@775
   255
 */
dz@928
   256
- (BOOL)trustOwnKeyIdentity:(PEPIdentity * _Nonnull)identity
dz@775
   257
                      error:(NSError * _Nullable * _Nullable)error;
dz@775
   258
dz@856
   259
/**
dz@856
   260
 Wraps color_from_rating.
dz@856
   261
 */
dz@856
   262
- (PEPColor)colorFromRating:(PEPRating)rating;
dz@856
   263
dz@927
   264
/**
dz@927
   265
 Wraps key_reset_identity.
dz@927
   266
 */
dz@927
   267
- (BOOL)keyReset:(PEPIdentity * _Nonnull)identity
dz@927
   268
     fingerprint:(NSString * _Nullable)fingerprint
dz@927
   269
           error:(NSError * _Nullable * _Nullable)error;
dz@927
   270
dz@1010
   271
/** Wraps leave_device_group. */
andreas@1330
   272
- (BOOL)leaveDeviceGroup:(NSError * _Nullable * _Nullable)error;
dz@1010
   273
dz@1285
   274
/**
dz@1285
   275
 Revoke and mistrust all own keys. See key_reset_all_own_keys for details.
dz@1285
   276
dz@1285
   277
 @param error The default cocoa error handling.
dz@1285
   278
 @return YES on success, NO if there were errors.
dz@1285
   279
 */
dz@1285
   280
- (BOOL)keyResetAllOwnKeysError:(NSError * _Nullable * _Nullable)error;
dz@1285
   281
dirk@303
   282
@end