pEpObjCAdapter/PEPSession.h
author Dirk Zimmermann <dirk@pep-project.org>
Fri, 20 Oct 2017 14:53:31 +0200
changeset 291 1d64f8889d2c
parent 289 bbe4e8da3568
child 294 fff0d71fe385
permissions -rw-r--r--
IOS-766 PEPSession.cleanup now static
     1 //
     2 //  PEPSession.h
     3 //  pEpObjCAdapter
     4 //
     5 //  Created by Andreas Buff on 11.10.17.
     6 //  Copyright © 2017 p≡p. All rights reserved.
     7 //
     8 
     9 #import <Foundation/Foundation.h>
    10 
    11 #import "PEPMessage.h"
    12 
    13 typedef NSDictionary<NSString *, id> PEPDict;
    14 typedef NSMutableDictionary<NSString *, id> PEPMutableDict;
    15 typedef NSArray<NSString *> PEPStringList;
    16 
    17 @class PEPLanguage;
    18 
    19 /**
    20  Fake session to handle to the client.
    21 
    22  Assures all calls are handled on the correct internal session for the thread it is called on.
    23  You can instatntiate and use this session how often and wherever you want. Also over multiple threads.
    24 
    25  Note: You must call `cleanup()` once before your process gets terminated to be able to gracefully shutdown.
    26  It is the clients responsibility not to make any calls to PEPSession after calling cleanup.
    27 
    28  Also: The Engine requires that the first session is created on the main thread. It is the responibility of the client to call PEPSession init once on the main thread before any other thread is calling it.
    29  */
    30 @interface PEPSession : NSObject
    31 
    32 /**
    33  You must call this method once before your process gets terminated to be able to gracefully shutdown.
    34  You must not make any calls to PEPSession after calling cleanup.
    35  */
    36 + (void)cleanup;
    37 
    38 /** Decrypt a message */
    39 - (PEP_rating)decryptMessageDict:(nonnull PEPDict *)src
    40                             dest:(PEPDict * _Nullable * _Nullable)dst
    41                             keys:(PEPStringList * _Nullable * _Nullable)keys;
    42 
    43 /** Re-evaluate rating of decrypted message */
    44 - (PEP_rating)reEvaluateMessageRating:(nonnull PEPDict *)src;
    45 
    46 /** Encrypt a message */
    47 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    48                            extra:(nullable PEPStringList *)keys
    49                             dest:(PEPDict * _Nullable * _Nullable)dst;
    50 
    51 /** Encrypt a message for the given identity, which is usually a mySelf identity */
    52 - (PEP_STATUS)encryptMessageDict:(nonnull PEPDict *)src
    53                         identity:(nonnull PEPDict *)identity
    54                             dest:(PEPDict * _Nullable * _Nullable)dst;
    55 
    56 /** Determine the status color of a message to be sent */
    57 - (PEP_rating)outgoingMessageColor:(nonnull PEPDict *)msg;
    58 
    59 /** Determine the rating of an identity */
    60 - (PEP_rating)identityRating:(nonnull PEPDict *)identity;
    61 
    62 /** Get trustwords for a fingerprint */
    63 - (nonnull NSArray *)trustwords:(nonnull NSString *)fpr forLanguage:(nonnull NSString *)languageID
    64                       shortened:(BOOL)shortened;
    65 
    66 /**
    67  Supply an account used by our user himself. The identity is supplemented with the missing parts
    68 
    69  An identity is a `NSDictionary` mapping a field name as `NSString` to different values.
    70  An identity can have the following fields (all other keys are ignored).
    71  It is not necessary to supply all fields; missing fields are supplemented by p≡p engine.
    72 
    73  @"username": real name or nick name (if pseudonymous) of identity
    74  @"address": URI or SMTP address
    75  @"user_id": persistent unique ID for identity
    76  @"lang": preferred languageID for communication with this ID (default: @"en")
    77  @"fpr": fingerprint of key to use for communication with this ID
    78  @"comm_type": communication type code (usually not needed)
    79 
    80  As an example:
    81 
    82  User has a mailbox. The mail address is "Dipul Khatri <dipul@inboxcube.com>". Then this would be:
    83 
    84  NSDictionary *ident = [NSDictionary dictionaryWithObjectsAndKeys:
    85  @"Dipul Khatri", @"username", @"dipul@inboxcube.com", @"address",
    86  @"23", @"user_id", nil];
    87 
    88  */
    89 - (void)mySelf:(nonnull PEPMutableDict *)identity;
    90 
    91 /**
    92  Supplement missing information for an arbitrary identity (used for communication partners).
    93  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
    94  */
    95 - (void)updateIdentity:(nonnull PEPMutableDict *)identity;
    96 
    97 /**
    98  Mark a key as trusted with a person.
    99  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   100  */
   101 - (void)trustPersonalKey:(nonnull PEPMutableDict *)identity;
   102 
   103 /**
   104  if a key is not trusted by the user tell this using this message
   105  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   106  */
   107 - (void)keyMistrusted:(nonnull PEPMutableDict *)identity;
   108 
   109 /**
   110  Use this to undo keyCompromized or trustPersonalKey
   111  See `mySelf:(NSMutableDictionary *)identity` for an explanation of identities.
   112  */
   113 - (void)keyResetTrust:(nonnull PEPMutableDict *)identity;
   114 
   115 #pragma mark -- Internal API (testing etc.)
   116 
   117 /** For testing purpose, manual key import */
   118 - (void)importKey:(nonnull NSString *)keydata;
   119 
   120 - (void)logTitle:(nonnull NSString *)title entity:(nonnull NSString *)entity
   121      description:(nullable NSString *)description comment:(nullable NSString *)comment;
   122 
   123 /**
   124  Retrieves the log from the engine.
   125  */
   126 - (nonnull NSString *)getLog;
   127 
   128 /** Determine trustwords for two identities */
   129 - (nullable NSString *)getTrustwordsIdentity1:(nonnull PEPDict *)identity1
   130                                     identity2:(nonnull PEPDict *)identity2
   131                                      language:(nullable NSString *)language
   132                                          full:(BOOL)full;
   133 
   134 /** Determine trustwords between sender of a message and receiving identity */
   135 - (nullable NSString *)getTrustwordsMessageDict:(nonnull PEPDict *)messageDict
   136                                    receiverDict:(nonnull PEPDict *)receiverDict
   137                                       keysArray:(PEPStringList * _Nullable)keysArray
   138                                        language:(nullable NSString *)language
   139                                            full:(BOOL)full
   140                                 resultingStatus:(PEP_STATUS * _Nullable)resultingStatus;
   141 
   142 /**
   143  @returns The list of supported languages for trustwords.
   144  */
   145 - (NSArray<PEPLanguage *> * _Nonnull)languageList;
   146 
   147 /**
   148  Directly invokes the engine's undo_last_mistrust() function
   149  */
   150 - (PEP_STATUS)undoLastMistrust;
   151 
   152 @end