pEpObjCAdapter/PEPSession.h
author Dirk Zimmermann <dirk@pep-project.org>
Thu, 31 Aug 2017 15:29:46 +0200
changeset 213 959a115bc0f7
parent 207 573bc548d19a
child 246 41d279193103
permissions -rw-r--r--
IOSAD-25 test PEP_TRUSTWORDS_DUPLICATE_FPR with trustwords
     1 //
     2 //  PEPSession.h
     3 //  pEpiOSAdapter
     4 //
     5 //  Created by Volker Birk on 08.07.15.
     6 //  Copyright (c) 2015 p≡p. All rights reserved.
     7 //
     8 
     9 #import <Foundation/Foundation.h>
    10 
    11 #import "PEPObjCAdapter.h"
    12 #import "PEPMessage.h"
    13 
    14 typedef NSDictionary<NSString *, id> PEPDict;
    15 typedef NSMutableDictionary<NSString *, id> PEPMutableDict;
    16 typedef NSArray<NSString *> PEPStringList;
    17 
    18 @class PEPSession;
    19 @class PEPLanguage;
    20 
    21 /** Callback type for doing something with a session */
    22 typedef void (^PEPSessionBlock)(PEPSession * _Nonnull session);
    23 
    24 @interface PEPSession : NSObject
    25 
    26 #pragma mark -- Public API
    27 
    28 + (nonnull PEPSession *)session;
    29 
    30 /**
    31  Execute a block concurrently on a session.
    32  The session is created solely for execution of the block.
    33  */
    34 + (void)dispatchAsyncOnSession:(nonnull PEPSessionBlock)block;
    35 
    36 /**
    37  Execute a block on a session and wait for it.
    38  The session is created solely for execution of the block.
    39  */
    40 + (void)dispatchSyncOnSession:(nonnull PEPSessionBlock)block;
    41 
    42 /** Decrypt a message */
    43 - (PEP_rating)decryptMessageDict:(nonnull PEPDict *)src
    44                             dest:(PEPDict * _Nullable * _Nullable)dst
    45                             keys:(PEPStringList * _Nullable * _Nullable)keys;
    46 
    47 /** Re-evaluate rating of decrypted message */
    48 - (PEP_rating)reEvaluateMessageRating:(nonnull PEPDict *)src;
    49 
    50 /** Encrypt a message */
    51 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    52                            extra:(nullable PEPStringList *)keys
    53                             dest:(PEPDict * _Nullable * _Nullable)dst;
    54 
    55 /** Encrypt a message for the given identity, which is usually a mySelf identity */
    56 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    57                         identity:(nonnull PEPDict *)identity
    58                             dest:(PEPDict * _Nullable * _Nullable)dst;
    59 
    60 /** Determine the status color of a message to be sent */
    61 - (PEP_rating)outgoingMessageColor:(nonnull PEPDict *)msg;
    62 
    63 /** Determine the rating of an identity */
    64 - (PEP_rating)identityRating:(nonnull PEPDict *)identity;
    65 
    66 /** Get trustwords for a fingerprint */
    67 - (nonnull NSArray *)trustwords:(nonnull NSString *)fpr forLanguage:(nonnull NSString *)languageID
    68                       shortened:(BOOL)shortened;
    69 
    70 /**
    71  Supply an account used by our user himself. The identity is supplemented with the missing parts
    72 
    73  An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
    74  An identity can have the following fields (all other keys are ignored).
    75  It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
    76 
    77  @"username": real name or nick name (if pseudonymous) of identity
    78  @"address": URI or SMTP address
    79  @"user_id": persistent unique ID for identity
    80  @"lang": preferred languageID for communication with this ID (default: @"en")
    81  @"fpr": fingerprint of key to use for communication with this ID
    82  @"comm_type": communication type code (usually not needed)
    83 
    84  As an example:
    85 
    86  User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
    87 
    88  NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
    89  @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address",
    90  @"23", @"user_id", nil];
    91 
    92  */
    93 - (void)mySelf:(nonnull PEPMutableDict *)identity;
    94 
    95 /**
    96  Supplement missing information for an arbitrary identity (used for communication partners).
    97  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
    98  */
    99 - (void)updateIdentity:(nonnull PEPMutableDict *)identity;
   100 
   101 /**
   102  Mark a key as trusted with a person.
   103  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   104  */
   105 - (void)trustPersonalKey:(nonnull PEPMutableDict *)identity;
   106 
   107 /**
   108  if a key is not trusted by the user tell this using this message
   109  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   110  */
   111 - (void)keyMistrusted:(nonnull PEPMutableDict *)identity;
   112 
   113 /**
   114  Use this to undo keyCompromized or trustPersonalKey
   115  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   116  */
   117 - (void)keyResetTrust:(nonnull PEPMutableDict *)identity;
   118 
   119 #pragma mark -- Internal API (testing etc.)
   120 
   121 /** For testing purpose, manual key import */
   122 - (void)importKey:(nonnull NSString *)keydata;
   123 
   124 - (void)logTitle:(nonnull NSString *)title entity:(nonnull NSString *)entity
   125      description:(nullable NSString *)description comment:(nullable NSString *)comment;
   126 
   127 /**
   128  Retrieves the log from the engine.
   129  */
   130 - (nonnull NSString *)getLog;
   131 
   132 /** Determine trustwords for two identities */
   133 - (nullable NSString *)getTrustwordsIdentity1:(nonnull PEPDict *)identity1
   134                                     identity2:(nonnull PEPDict *)identity2
   135                                      language:(nullable NSString *)language
   136                                          full:(BOOL)full;
   137 
   138 /** Determine trustwords between sender of a message and receiving identity */
   139 - (nullable NSString *)getTrustwordsMessageDict:(nonnull PEPDict *)messageDict
   140                                    receiverDict:(nonnull PEPDict *)receiverDict
   141                                       keysArray:(PEPStringList * _Nullable)keysArray
   142                                        language:(nullable NSString *)language
   143                                            full:(BOOL)full
   144                                 resultingStatus:(PEP_STATUS * _Nullable)resultingStatus;
   145 
   146 /**
   147  @returns The list of supported languages for trustwords.
   148  */
   149 - (NSArray<PEPLanguage *> * _Nonnull)languageList;
   150 
   151 @end