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