src/keymanagement.h
author Volker Birk <vb@pep-project.org>
Mon, 28 Sep 2015 15:06:07 +0200
changeset 357 9b796d54b0ea
parent 354 3e5db18f227b
child 410 00adb9b21ae9
permissions -rw-r--r--
key_compromized() added
vb@39
     1
#pragma once
vb@39
     2
vb@217
     3
#include "pEpEngine.h"
vb@217
     4
vb@0
     5
#ifdef __cplusplus
vb@0
     6
extern "C" {
vb@0
     7
#endif
vb@0
     8
vb@0
     9
// update_identity() - update identity information
vb@0
    10
//
vb@0
    11
//  parameters:
vb@0
    12
//      session (in)        session to use
vb@0
    13
//      identity (inout)    identity information of communication partner
vb@0
    14
//
vb@0
    15
//  caveat:
vb@10
    16
//      if this function returns PEP_ct_unknown or PEP_ct_key_expired in
vb@10
    17
//      identity->comm_type, the caller must insert the identity into the
vb@10
    18
//      asynchronous management implementation, so retrieve_next_identity()
vb@10
    19
//      will return this identity later
vb@21
    20
//      at least identity->address must be a non-empty UTF-8 string as input
vb@0
    21
vb@0
    22
DYNAMIC_API PEP_STATUS update_identity(
vb@0
    23
        PEP_SESSION session, pEp_identity * identity
vb@0
    24
    );
vb@0
    25
vb@0
    26
vb@0
    27
// myself() - ensures that the own identity is being complete
vb@0
    28
//
vb@0
    29
//  parameters:
vb@0
    30
//      session (in)        session to use
vb@0
    31
//      identity (inout)    identity of local user
vb@0
    32
//                          at least .address, .username, .user_id must be set
vb@0
    33
//
vb@0
    34
//  return value:
vb@0
    35
//      PEP_STATUS_OK if identity could be completed or was already complete,
vb@0
    36
//      any other value on error
vb@0
    37
//
vb@0
    38
//  caveat:
vb@0
    39
//      this function generates a keypair on demand; because it's synchronous
vb@0
    40
//      it can need a decent amount of time to return
vb@0
    41
//      if you need to do this asynchronous, you need to return an identity
vb@0
    42
//      with retrieve_next_identity() where pEp_identity.me is true
vb@0
    43
vb@0
    44
DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
vb@0
    45
vb@0
    46
vb@0
    47
// retrieve_next_identity() - callback being called by do_keymanagement()
vb@0
    48
//
vb@0
    49
//  parameters:
vb@0
    50
//      management (in)     data structure to deliver (implementation defined)
vb@0
    51
//
vb@0
    52
//  return value:
vb@0
    53
//      identity to check or NULL to terminate do_keymanagement()
vb@0
    54
//      if given identity must be created with new_identity()
vb@0
    55
//      the identity struct is going to the ownership of this library
vb@0
    56
//      it must not be freed by the callee
vb@0
    57
//
vb@0
    58
//  caveat:
vb@0
    59
//      this callback has to block until an identity or NULL can be returned
vb@0
    60
//      an implementation is not provided by this library; instead it has to be
vb@0
    61
//      implemented by the user of this library
vb@0
    62
vb@0
    63
typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
vb@0
    64
vb@0
    65
vb@292
    66
// examine_identity() - callback for appending to queue
vb@292
    67
//
vb@292
    68
//  parameters:
vb@292
    69
//      ident (in)          identity to examine
vb@292
    70
//      management (in)     data structure to deliver (implementation defined)
vb@292
    71
//
vb@292
    72
//  return value:
vb@292
    73
//      0 if identity was added successfully to queue or nonzero otherwise
vb@292
    74
vb@296
    75
typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
vb@292
    76
vb@292
    77
vb@292
    78
// register_examine_function() - register examine_identity() callback
vb@292
    79
//
vb@292
    80
//  parameters:
vb@292
    81
//      session (in)            session to use
vb@292
    82
//      examine_identity (in)   examine_identity() function to register
vb@292
    83
//      management (in)     data structure to deliver (implementation defined)
vb@292
    84
vb@296
    85
DYNAMIC_API PEP_STATUS register_examine_function(
vb@292
    86
        PEP_SESSION session, 
vb@292
    87
        examine_identity_t examine_identity,
vb@292
    88
        void *management
vb@292
    89
    );
vb@292
    90
vb@292
    91
vb@0
    92
// do_keymanagement() - function to be run on an extra thread
vb@0
    93
//
vb@0
    94
//  parameters:
vb@0
    95
//      retrieve_next_identity  pointer to retrieve_next_identity() callback
vb@0
    96
//                              which returns at least a valid address field in
vb@0
    97
//                              the identity struct
vb@0
    98
//      management              management data to give to keymanagement
vb@0
    99
//                              (implementation defined)
vb@0
   100
//
vb@0
   101
//  return value:
vb@0
   102
//      PEP_STATUS_OK if thread has to terminate successfully or any other
vb@0
   103
//      value on failure
vb@0
   104
//
vb@0
   105
//  caveat:
vb@0
   106
//      to ensure proper working of this library, a thread has to be started
vb@0
   107
//      with this function immediately after initialization
vb@0
   108
//      do_keymanagement() calls retrieve_next_identity(management)
vb@0
   109
vb@0
   110
DYNAMIC_API PEP_STATUS do_keymanagement(
vb@0
   111
        retrieve_next_identity_t retrieve_next_identity,
vb@0
   112
        void *management
vb@0
   113
    );
vb@0
   114
vb@215
   115
vb@215
   116
// key_compromized() - mark key as being compromized
vb@215
   117
//
vb@215
   118
//  parameters:
vb@215
   119
//      session (in)        session to use
vb@357
   120
//      ident (in)          person and key which was compromized
vb@215
   121
vb@357
   122
DYNAMIC_API PEP_STATUS key_compromized(
vb@357
   123
        PEP_SESSION session,
vb@357
   124
        pEp_identity *ident
vb@357
   125
    );
vb@215
   126
vb@215
   127
vb@354
   128
// trust_personal_key() - mark a key as trusted with a person
vb@354
   129
//
vb@354
   130
//  parameters:
vb@354
   131
//      session (in)        session to use
vb@354
   132
//      ident (in)          person and key to trust in
vb@354
   133
//
vb@354
   134
//  caveat:
vb@354
   135
//      the fields user_id, address and fpr must be supplied
vb@354
   136
vb@354
   137
DYNAMIC_API PEP_STATUS trust_personal_key(
vb@354
   138
        PEP_SESSION session,
vb@354
   139
        pEp_identity *ident
vb@354
   140
    );
vb@354
   141
vb@354
   142
vb@0
   143
#ifdef __cplusplus
vb@0
   144
}
vb@0
   145
#endif
vb@0
   146