pEpObjCAdapter/PEPSessionProtocol.h
author Dirk Zimmermann <dirk@pep-project.org>
Thu, 22 Mar 2018 15:38:12 +0100
changeset 551 6b7914602bc6
parent 545 7217e3c844e0
child 552 0f362cd2de6a
permissions -rw-r--r--
IOSAD-72 importKey error handling
     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 "PEPMessageUtil.h"
    12 
    13 typedef NSDictionary<NSString *, id> PEPDict;
    14 typedef NSMutableDictionary<NSString *, id> PEPMutableDict;
    15 typedef NSArray<NSString *> PEPStringList;
    16 
    17 @class PEPLanguage;
    18 @class PEPIdentity;
    19 @class PEPMessage;
    20 
    21 @protocol PEPSessionProtocol <NSObject>
    22 
    23 /** Decrypt a message */
    24 - (PEPDict * _Nullable)decryptMessageDict:(PEPDict * _Nonnull)messageDict
    25                                    rating:(PEP_rating * _Nullable)rating
    26                                 extraKeys:(PEPStringList * _Nullable * _Nullable)extraKeys
    27                                    status:(PEP_STATUS * _Nullable)status
    28                                     error:(NSError * _Nullable * _Nullable)error __deprecated;
    29 
    30 /** Decrypt a message */
    31 - (PEPMessage * _Nullable)decryptMessage:(PEPMessage * _Nonnull)message
    32                                   rating:(PEP_rating * _Nullable)rating
    33                                extraKeys:(PEPStringList * _Nullable * _Nullable)extraKeys
    34                                   status:(PEP_STATUS * _Nullable)status
    35                                    error:(NSError * _Nullable * _Nullable)error;
    36 
    37 /** Re-evaluate rating of decrypted message */
    38 - (BOOL)reEvaluateMessageDict:(PEPDict * _Nonnull)messageDict
    39                        rating:(PEP_rating * _Nullable)rating
    40                        status:(PEP_STATUS * _Nullable)status
    41                         error:(NSError * _Nullable * _Nullable)error __deprecated;
    42 
    43 /** Re-evaluate rating of decrypted message */
    44 - (BOOL)reEvaluateMessage:(PEPMessage * _Nonnull)message
    45                    rating:(PEP_rating * _Nullable)rating
    46                    status:(PEP_STATUS * _Nullable)status
    47                     error:(NSError * _Nullable * _Nullable)error;
    48 
    49 /**
    50  Encrypt a message dictionary, indicating the encoding format.
    51  @note The resulting message dict could be the input one.
    52  */
    53 - (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
    54                                 extraKeys:(PEPStringList * _Nullable)extraKeys
    55                                 encFormat:(PEP_enc_format)encFormat
    56                                    status:(PEP_STATUS * _Nullable)status
    57                                     error:(NSError * _Nullable * _Nullable)error __deprecated;
    58 
    59 /**
    60  Encrypt a message, indicating the encoding format
    61  @note The resulting message dict could be the input one.
    62  */
    63 - (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
    64                                extraKeys:(PEPStringList * _Nullable)extraKeys
    65                                encFormat:(PEP_enc_format)encFormat
    66                                   status:(PEP_STATUS * _Nullable)status
    67                                    error:(NSError * _Nullable * _Nullable)error;
    68 
    69 /** Encrypt a message with default encryption format (PEP_enc_PEP) */
    70 - (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
    71                                extraKeys:(PEPStringList * _Nullable)extraKeys
    72                                   status:(PEP_STATUS * _Nullable)status
    73                                    error:(NSError * _Nullable * _Nullable)error;
    74 
    75 /** Encrypt a message dict for the given own identity */
    76 - (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
    77                                  identity:(PEPIdentity * _Nonnull)identity
    78                                    status:(PEP_STATUS * _Nullable)status
    79                                     error:(NSError * _Nullable * _Nullable)error __deprecated;
    80 
    81 /** Encrypt a message for the given own identity */
    82 - (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
    83                                 identity:(PEPIdentity * _Nonnull)identity
    84                                   status:(PEP_STATUS * _Nullable)status
    85                                    error:(NSError * _Nullable * _Nullable)error;
    86 
    87 /** Determine the status color of a message to be sent */
    88 - (BOOL)outgoingRating:(PEP_rating * _Nonnull)rating
    89             forMessage:(PEPMessage * _Nonnull)message
    90                  error:(NSError * _Nullable * _Nullable)error;
    91 
    92 /**
    93  Determine the rating of an identity.
    94  The rating is the rating a _message_ would have, if it is sent to this (and only this) identity.
    95  It is *not* a rating of the identity. In fact, there is no rating for identities.
    96  */
    97 - (BOOL)rating:(PEP_rating * _Nonnull)rating
    98    forIdentity:(PEPIdentity * _Nonnull)identity
    99          error:(NSError * _Nullable * _Nullable)error;
   100 
   101 /** Get trustwords for a fingerprint */
   102 - (NSArray * _Nullable)trustwordsForFingerprint:(NSString * _Nonnull)fingerprint
   103                                      languageID:(NSString * _Nonnull)languageID
   104                                       shortened:(BOOL)shortened
   105                                           error:(NSError * _Nullable * _Nullable)error;
   106 
   107 /**
   108  Supply an account used by our user himself. The identity is supplemented with the missing parts
   109 
   110  An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
   111  An identity can have the following fields (all other keys are ignored).
   112  It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
   113 
   114  @"username": real name or nick name (if pseudonymous) of identity
   115  @"address": URI or SMTP address
   116  @"user_id": persistent unique ID for the *user* that belongs to the identity.
   117                 A user can have multiple identities which all of them MUST use the same user_id.
   118  @"lang": preferred languageID for communication with this ID (default: @"en")
   119  @"fpr": fingerprint of key to use for communication with this ID
   120  @"comm_type": communication type code (usually not needed)
   121 
   122  As an example:
   123 
   124  User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
   125 
   126  NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
   127  @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address",
   128  @"23", @"user_id", nil];
   129 
   130  */
   131 - (BOOL)mySelf:(PEPIdentity * _Nonnull)identity error:(NSError * _Nullable * _Nullable)error;
   132 
   133 /**
   134  Supplement missing information for an arbitrary identity (used for communication partners).
   135  Will call the engine's myself() or update_identity() internally, depending on the given
   136  identity.
   137  */
   138 - (BOOL)updateIdentity:(PEPIdentity * _Nonnull)identity
   139                  error:(NSError * _Nullable * _Nullable)error;
   140 
   141 /**
   142  Mark a key as trusted with a person.
   143  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   144  */
   145 - (BOOL)trustPersonalKey:(PEPIdentity * _Nonnull)identity
   146                    error:(NSError * _Nullable * _Nullable)error;
   147 
   148 /**
   149  if a key is not trusted by the user tell this using this message
   150  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   151  */
   152 - (BOOL)keyMistrusted:(PEPIdentity * _Nonnull)identity
   153                 error:(NSError * _Nullable * _Nullable)error;
   154 
   155 /**
   156  Use this to undo keyCompromized or trustPersonalKey
   157  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   158  */
   159 - (BOOL)keyResetTrust:(PEPIdentity * _Nonnull)identity
   160                 error:(NSError * _Nullable * _Nullable)error;
   161 
   162 #pragma mark -- Internal API (testing etc.)
   163 
   164 /** For testing purpose, manual key import */
   165 - (BOOL)importKey:(NSString * _Nonnull)keydata error:(NSError * _Nullable * _Nullable)error;
   166 
   167 - (void)logTitle:(NSString * _Nonnull)title entity:(NSString * _Nonnull)entity
   168      description:(NSString * _Nullable)description comment:(NSString * _Nullable)comment;
   169 
   170 /**
   171  Retrieves the log from the engine, or nil, if there is nothing yet.
   172  */
   173 - (NSString * _Nullable)getLog;
   174 
   175 /** Determine trustwords for two identities */
   176 - (NSString * _Nullable)getTrustwordsIdentity1:(PEPIdentity * _Nonnull)identity1
   177                                      identity2:(PEPIdentity * _Nonnull)identity2
   178                                       language:(NSString * _Nullable)language
   179                                           full:(BOOL)full;
   180 
   181 /**
   182  @returns The list of supported languages for trustwords.
   183  */
   184 - (NSArray<PEPLanguage *> * _Nonnull)languageList;
   185 
   186 /**
   187  Directly invokes the engine's undo_last_mistrust() function
   188  */
   189 - (PEP_STATUS)undoLastMistrust;
   190 
   191 /**
   192  Can convert a string like "cannot_decrypt" into its equivalent PEP_rating_cannot_decrypt.
   193  */
   194 - (PEP_rating)ratingFromString:(NSString * _Nonnull)string;
   195 
   196 /**
   197  Can convert a pEp rating like PEP_rating_cannot_decrypt
   198  into its equivalent string "cannot_decrypt" .
   199  */
   200 - (NSString * _Nonnull)stringFromRating:(PEP_rating)rating;
   201 
   202 /**
   203  Is the given identity really a pEp user?
   204  If the engine indicates an error, or the identity is not a pEp user, returns false.
   205  */
   206 - (BOOL)isPEPUser:(PEPIdentity * _Nonnull)identity;
   207 
   208 /**
   209  When (manually) importing (secret) keys, associate them with the given own identity.
   210  */
   211 - (BOOL)setOwnKey:(PEPIdentity * _Nonnull)identity fingerprint:(NSString * _Nonnull)fingerprint
   212             error:(NSError * _Nullable * _Nullable)error;
   213 
   214 @end