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