You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
284 lines
12 KiB
284 lines
12 KiB
//
|
|
// PEPSessionProtocol.h
|
|
// pEpObjCAdapter
|
|
//
|
|
// Created by Dirk Zimmermann on 30.10.17.
|
|
// Copyright © 2017 p≡p. All rights reserved.
|
|
//
|
|
|
|
#import <Foundation/Foundation.h>
|
|
|
|
#import "PEPTypes.h"
|
|
#import "PEPEngineTypes.h"
|
|
|
|
@class PEPLanguage;
|
|
@class PEPIdentity;
|
|
@class PEPMessage;
|
|
|
|
@protocol PEPSessionProtocol <NSObject>
|
|
|
|
/** Decrypt a message */
|
|
- (PEPDict * _Nullable)decryptMessageDict:(PEPMutableDict * _Nonnull)messageDict
|
|
flags:(PEPDecryptFlags * _Nullable)flags
|
|
rating:(PEPRating * _Nullable)rating
|
|
extraKeys:(PEPStringList * _Nullable * _Nullable)extraKeys
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error __deprecated;
|
|
|
|
/** Decrypt a message */
|
|
- (PEPMessage * _Nullable)decryptMessage:(PEPMessage * _Nonnull)message
|
|
flags:(PEPDecryptFlags * _Nullable)flags
|
|
rating:(PEPRating * _Nullable)rating
|
|
extraKeys:(PEPStringList * _Nullable * _Nullable)extraKeys
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Re-evaluate rating of decrypted message */
|
|
- (BOOL)reEvaluateMessageDict:(PEPDict * _Nonnull)messageDict
|
|
xKeyList:(PEPStringList *_Nullable)xKeyList
|
|
rating:(PEPRating * _Nonnull)rating
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error __deprecated;
|
|
|
|
/** Re-evaluate rating of decrypted message */
|
|
- (BOOL)reEvaluateMessage:(PEPMessage * _Nonnull)message
|
|
xKeyList:(PEPStringList *_Nullable)xKeyList
|
|
rating:(PEPRating * _Nonnull)rating
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Encrypt a message dictionary, indicating the encoding format.
|
|
@note The resulting message dict could be the input one.
|
|
*/
|
|
- (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
|
|
extraKeys:(PEPStringList * _Nullable)extraKeys
|
|
encFormat:(PEPEncFormat)encFormat
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error __deprecated;
|
|
|
|
/**
|
|
Encrypt a message, indicating the encoding format
|
|
@note The resulting message dict could be the input one.
|
|
*/
|
|
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
|
|
extraKeys:(PEPStringList * _Nullable)extraKeys
|
|
encFormat:(PEPEncFormat)encFormat
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Encrypt a message with default encryption format (PEP_enc_PEP) */
|
|
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
|
|
extraKeys:(PEPStringList * _Nullable)extraKeys
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Encrypt a message dict for the given own identity */
|
|
- (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
|
|
forSelf:(PEPIdentity * _Nonnull)ownIdentity
|
|
extraKeys:(PEPStringList * _Nullable)extraKeys
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error __deprecated;
|
|
|
|
/** Encrypt a message for the given own identity */
|
|
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
|
|
forSelf:(PEPIdentity * _Nonnull)ownIdentity
|
|
extraKeys:(PEPStringList * _Nullable)extraKeys
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Encrypt a message dict to the given recipient FPR, attaching the private key */
|
|
- (PEPDict * _Nullable)encryptMessageDict:(PEPDict * _Nonnull)messageDict
|
|
toFpr:(NSString * _Nonnull)toFpr
|
|
encFormat:(PEPEncFormat)encFormat
|
|
flags:(PEPDecryptFlags)flags
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error __deprecated;
|
|
|
|
/** Encrypt a message dict to the given recipient FPR, attaching the private key */
|
|
- (PEPMessage * _Nullable)encryptMessage:(PEPMessage * _Nonnull)message
|
|
toFpr:(NSString * _Nonnull)toFpr
|
|
encFormat:(PEPEncFormat)encFormat
|
|
flags:(PEPDecryptFlags)flags
|
|
status:(PEPStatus * _Nullable)status
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Determine the status color of a message to be sent */
|
|
- (NSNumber * _Nullable)outgoingRatingForMessage:(PEPMessage * _Nonnull)theMessage
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Determine the preview status color of a message to be sent */
|
|
- (NSNumber * _Nullable)outgoingRatingPreviewForMessage:(PEPMessage * _Nonnull)theMessage
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Determine the rating of an identity.
|
|
The rating is the rating a _message_ would have, if it is sent to this (and only this) identity.
|
|
It is *not* a rating of the identity. In fact, there is no rating for identities.
|
|
*/
|
|
- (NSNumber * _Nullable)ratingForIdentity:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Get trustwords for a fingerprint */
|
|
- (NSArray * _Nullable)trustwordsForFingerprint:(NSString * _Nonnull)fingerprint
|
|
languageID:(NSString * _Nonnull)languageID
|
|
shortened:(BOOL)shortened
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Supply an account used by our user himself. The identity is supplemented with the missing parts
|
|
|
|
An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
|
|
An identity can have the following fields (all other keys are ignored).
|
|
It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
|
|
|
|
@"username": real name or nick name (if pseudonymous) of identity
|
|
@"address": URI or SMTP address
|
|
@"user_id": persistent unique ID for the *user* that belongs to the identity.
|
|
A user can have multiple identities which all of them MUST use the same user_id.
|
|
@"lang": preferred languageID for communication with this ID (default: @"en")
|
|
@"fpr": fingerprint of key to use for communication with this ID
|
|
@"comm_type": communication type code (usually not needed)
|
|
|
|
As an example:
|
|
|
|
User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
|
|
|
|
NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
|
|
@"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address",
|
|
@"23", @"user_id", nil];
|
|
|
|
*/
|
|
- (BOOL)mySelf:(PEPIdentity * _Nonnull)identity error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Supplement missing information for an arbitrary identity (used for communication partners).
|
|
Will call the engine's myself() or update_identity() internally, depending on the given
|
|
identity.
|
|
*/
|
|
- (BOOL)updateIdentity:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Mark a key as trusted with a person.
|
|
See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
|
|
*/
|
|
- (BOOL)trustPersonalKey:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
if a key is not trusted by the user tell this using this message
|
|
See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
|
|
*/
|
|
- (BOOL)keyMistrusted:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Use this to undo keyCompromized or trustPersonalKey
|
|
See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
|
|
*/
|
|
- (BOOL)keyResetTrust:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
#pragma mark -- Internal API (testing etc.)
|
|
|
|
/** For testing purpose, manual key import */
|
|
- (NSArray<PEPIdentity *> * _Nullable)importKey:(NSString * _Nonnull)keydata
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
- (BOOL)logTitle:(NSString * _Nonnull)title
|
|
entity:(NSString * _Nonnull)entity
|
|
description:(NSString * _Nullable)description
|
|
comment:(NSString * _Nullable)comment
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Retrieves the log from the engine, or nil, if there is nothing yet.
|
|
*/
|
|
- (NSString * _Nullable)getLogWithError:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Determine trustwords for two identities */
|
|
- (NSString * _Nullable)getTrustwordsIdentity1:(PEPIdentity * _Nonnull)identity1
|
|
identity2:(PEPIdentity * _Nonnull)identity2
|
|
language:(NSString * _Nullable)language
|
|
full:(BOOL)full
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Determine trustwords for two fprs */
|
|
- (NSString * _Nullable)getTrustwordsFpr1:(NSString * _Nonnull)fpr1
|
|
fpr2:(NSString * _Nonnull)fpr2
|
|
language:(NSString * _Nullable)language
|
|
full:(BOOL)full
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
@returns The list of supported languages for trustwords.
|
|
*/
|
|
- (NSArray<PEPLanguage *> * _Nullable)languageListWithError:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Can convert a string like "cannot_decrypt" into its equivalent PEPRating_cannot_decrypt.
|
|
*/
|
|
- (PEPRating)ratingFromString:(NSString * _Nonnull)string;
|
|
|
|
/**
|
|
Can convert a pEp rating like PEPRating_cannot_decrypt
|
|
into its equivalent string "cannot_decrypt" .
|
|
*/
|
|
- (NSString * _Nonnull)stringFromRating:(PEPRating)rating;
|
|
|
|
/**
|
|
Is the given identity really a pEp user?
|
|
If the engine indicates an error, or the identity is not a pEp user, returns false.
|
|
*/
|
|
- (NSNumber * _Nullable)isPEPUser:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
When (manually) importing (secret) keys, associate them with the given own identity.
|
|
*/
|
|
- (BOOL)setOwnKey:(PEPIdentity * _Nonnull)identity fingerprint:(NSString * _Nonnull)fingerprint
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Wraps the engine's `config_passive_mode`.
|
|
@note That there's absolutely no error handling.
|
|
*/
|
|
- (void)configurePassiveModeEnabled:(BOOL)enabled;
|
|
|
|
/**
|
|
Wraps set_identity_flags.
|
|
*/
|
|
- (BOOL)setFlags:(PEPIdentityFlags)flags
|
|
forIdentity:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Wraps the engine's deliverHandshakeResult.
|
|
*/
|
|
- (BOOL)deliverHandshakeResult:(PEPSyncHandshakeResult)result
|
|
identitiesSharing:(NSArray<PEPIdentity *> * _Nullable)identitiesSharing
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Wraps trust_own_key.
|
|
*/
|
|
- (BOOL)trustOwnKeyIdentity:(PEPIdentity * _Nonnull)identity
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/**
|
|
Wraps color_from_rating.
|
|
*/
|
|
- (PEPColor)colorFromRating:(PEPRating)rating;
|
|
|
|
/**
|
|
Wraps key_reset_identity.
|
|
*/
|
|
- (BOOL)keyReset:(PEPIdentity * _Nonnull)identity
|
|
fingerprint:(NSString * _Nullable)fingerprint
|
|
error:(NSError * _Nullable * _Nullable)error;
|
|
|
|
/** Wraps leave_device_group. */
|
|
- (BOOL)leaveDeviceGroupError:(NSError * _Nullable * _Nullable)error;
|
|
|
|
@end
|