2 // PEPSessionProtocol.h
5 // Created by Dirk Zimmermann on 30.10.17.
6 // Copyright © 2017 p≡p. All rights reserved.
9 #import <Foundation/Foundation.h>
11 #import "PEPMessageUtil.h"
13 typedef NSDictionary<NSString *, id> PEPDict;
14 typedef NSMutableDictionary<NSString *, id> PEPMutableDict;
15 typedef NSArray<NSString *> PEPStringList;
21 @protocol PEPSessionProtocol <NSObject>
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;
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;
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;
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;
50 Encrypt a message dictionary, indicating the encoding format.
51 @note The resulting message dict could be the input one.
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;
60 Encrypt a message, indicating the encoding format
61 @note The resulting message dict could be the input one.
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;
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;
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;
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;
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;
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.
97 - (BOOL)rating:(PEP_rating * _Nonnull)rating
98 forIdentity:(PEPIdentity * _Nonnull)identity
99 error:(NSError * _Nullable * _Nullable)error;
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;
108 Supply an account used by our user himself. The identity is supplemented with the missing parts
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.
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)
124 User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
126 NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
127 @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address",
128 @"23", @"user_id", nil];
131 - (BOOL)mySelf:(PEPIdentity * _Nonnull)identity error:(NSError * _Nullable * _Nullable)error;
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
138 - (BOOL)updateIdentity:(PEPIdentity * _Nonnull)identity
139 error:(NSError * _Nullable * _Nullable)error;
142 Mark a key as trusted with a person.
143 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
145 - (BOOL)trustPersonalKey:(PEPIdentity * _Nonnull)identity
146 error:(NSError * _Nullable * _Nullable)error;
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.
152 - (BOOL)keyMistrusted:(PEPIdentity * _Nonnull)identity
153 error:(NSError * _Nullable * _Nullable)error;
156 Use this to undo keyCompromized or trustPersonalKey
157 See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
159 - (BOOL)keyResetTrust:(PEPIdentity * _Nonnull)identity
160 error:(NSError * _Nullable * _Nullable)error;
162 #pragma mark -- Internal API (testing etc.)
164 /** For testing purpose, manual key import */
165 - (BOOL)importKey:(NSString * _Nonnull)keydata error:(NSError * _Nullable * _Nullable)error;
167 - (void)logTitle:(NSString * _Nonnull)title entity:(NSString * _Nonnull)entity
168 description:(NSString * _Nullable)description comment:(NSString * _Nullable)comment;
171 Retrieves the log from the engine, or nil, if there is nothing yet.
173 - (NSString * _Nullable)getLog;
175 /** Determine trustwords for two identities */
176 - (NSString * _Nullable)getTrustwordsIdentity1:(PEPIdentity * _Nonnull)identity1
177 identity2:(PEPIdentity * _Nonnull)identity2
178 language:(NSString * _Nullable)language
182 @returns The list of supported languages for trustwords.
184 - (NSArray<PEPLanguage *> * _Nonnull)languageList;
187 Directly invokes the engine's undo_last_mistrust() function
189 - (PEP_STATUS)undoLastMistrust;
192 Can convert a string like "cannot_decrypt" into its equivalent PEP_rating_cannot_decrypt.
194 - (PEP_rating)ratingFromString:(NSString * _Nonnull)string;
197 Can convert a pEp rating like PEP_rating_cannot_decrypt
198 into its equivalent string "cannot_decrypt" .
200 - (NSString * _Nonnull)stringFromRating:(PEP_rating)rating;
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.
206 - (BOOL)isPEPUser:(PEPIdentity * _Nonnull)identity;
209 When (manually) importing (secret) keys, associate them with the given own identity.
211 - (BOOL)setOwnKey:(PEPIdentity * _Nonnull)identity fingerprint:(NSString * _Nonnull)fingerprint
212 error:(NSError * _Nullable * _Nullable)error;