API reference details.md
author Roker <roker@pep-project.org>
Thu, 07 Jun 2018 12:44:11 +0200
branchJSON-93
changeset 537 ff1cdc290c32
parent 505 0fa0fa164f4f
child 619 4ad8b10e6021
permissions -rw-r--r--
JSON-94: re-implement combining of UTF-16 surrogate pairs. the 1st implementation was nuts. :-9
roker@505
     1
### Detailed Function reference for the p≡p JSON Server Adapter. Version “(38) Frankenberg”, API version 0.15.0 ###
roker@242
     2
Output parameters are denoted by a  **⇑** , InOut parameters are denoted by a  **⇕**  after the parameter type.
roker@242
     3
roker@242
     4
Nota bene: This list was created manually from the "authorative API description" and might be outdated.
roker@242
     5
roker@242
     6
#### Message API ####
roker@242
     7
roker@242
     8
##### MIME_encrypt_message( String mimetext, Integer size, StringList extra, String⇑ mime_ciphertext, PEP_enc_format env_format, Integer flags)
roker@242
     9
roker@242
    10
encrypt a MIME message, with MIME output
roker@242
    11
roker@242
    12
```
roker@242
    13
  parameters:
roker@242
    14
      mimetext (in)           MIME encoded text to encrypt
roker@242
    15
      size (in)               size of input mime text
roker@242
    16
      extra (in)              extra keys for encryption
roker@242
    17
      mime_ciphertext (out)   encrypted, encoded message
roker@242
    18
      enc_format (in)         encrypted format
roker@242
    19
      flags (in)              flags to set special encryption features
roker@242
    20
roker@242
    21
  return value:
roker@242
    22
      PEP_STATUS_OK           if everything worked
roker@242
    23
      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
roker@242
    24
      PEP_CANNOT_CREATE_TEMP_FILE
roker@242
    25
                              if there are issues with temp files; in
roker@242
    26
                              this case errno will contain the underlying
roker@242
    27
                              error
roker@242
    28
      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
roker@242
    29
```
roker@242
    30
*Caveat:* the encrypted, encoded mime text will go to the ownership of the caller; mimetext
roker@242
    31
will remain in the ownership of the caller
roker@242
    32
roker@242
    33
roker@505
    34
##### MIME_encrypt_message_for_self( Identity target_id, String mimetext, Integer size, StringList extra, String⇑ mime_ciphertext, PEP_enc_format enc_format, Integer flags) #####
roker@505
    35
encrypt MIME message for user's identity only,  ignoring recipients and other identities from
roker@505
    36
the message, with MIME output
roker@505
    37
roker@505
    38
```
roker@505
    39
  parameters:
roker@505
    40
      target_id (in)          self identity this message should be encrypted for
roker@505
    41
      mimetext (in)           MIME encoded text to encrypt
roker@505
    42
      size (in)               size of input mime text
roker@505
    43
      extra (in)              extra keys for encryption
roker@505
    44
      mime_ciphertext (out)   encrypted, encoded message
roker@505
    45
      enc_format (in)         encrypted format
roker@505
    46
      flags (in)              flags to set special encryption features
roker@505
    47
roker@505
    48
  return value:
roker@505
    49
      PEP_STATUS_OK           if everything worked
roker@505
    50
      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
roker@505
    51
      PEP_CANNOT_CREATE_TEMP_FILE
roker@505
    52
                              if there are issues with temp files; in
roker@505
    53
                              this case errno will contain the underlying
roker@505
    54
                              error
roker@505
    55
      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
roker@505
    56
roker@505
    57
  caveat:
roker@505
    58
      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
roker@505
    59
      will remain in the ownership of the caller
roker@505
    60
```
roker@505
    61
roker@505
    62
roker@505
    63
##### MIME_decrypt_message(String mimetext, Integer size, String⇑ mime_plaintext, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇕ flags, String⇑ modified_src)
roker@242
    64
roker@242
    65
decrypt a MIME message, with MIME output
roker@242
    66
```
roker@242
    67
  parameters:
roker@242
    68
      mimetext (in)           MIME encoded text to decrypt
roker@242
    69
      size (in)               size of mime text to decode (in order to decrypt)
roker@242
    70
      mime_plaintext (out)    decrypted, encoded message
roker@242
    71
      keylist (out)           stringlist with keyids
roker@242
    72
      rating (out)            rating for the message
roker@505
    73
      flags (inout)           flags to signal special decryption features
roker@505
    74
      modified_src (out)      modified source string, if decrypt had reason to change it
roker@242
    75
roker@242
    76
  return value:
roker@242
    77
      decrypt status          if everything worked with MIME encode/decode, 
roker@242
    78
                              the status of the decryption is returned 
roker@242
    79
                              (PEP_STATUS_OK or decryption error status)
roker@242
    80
      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
roker@242
    81
      PEP_CANNOT_CREATE_TEMP_FILE
roker@242
    82
                              if there are issues with temp files; in
roker@242
    83
                              this case errno will contain the underlying
roker@242
    84
                              error
roker@242
    85
      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
roker@505
    86
roker@505
    87
  flag values:
roker@505
    88
      in:
roker@505
    89
          PEP_decrypt_flag_untrusted_server
roker@505
    90
              used to signal that decrypt function should engage in behaviour
roker@505
    91
              specified for when the server storing the source is untrusted.
roker@505
    92
      out:
roker@505
    93
          PEP_decrypt_flag_own_private_key
roker@505
    94
              private key was imported for one of our addresses (NOT trusted
roker@505
    95
              or set to be used - handshake/trust is required for that)
roker@505
    96
          PEP_decrypt_flag_src_modified
roker@505
    97
              indicates that the modified_src field should contain a modified
roker@505
    98
              version of the source, at the moment always as a result of the
roker@505
    99
              input flags. 
roker@505
   100
          PEP_decrypt_flag_consume
roker@505
   101
              used by sync 
roker@505
   102
          PEP_decrypt_flag_ignore
roker@505
   103
              used by sync 
roker@505
   104
 
roker@505
   105
  caveat:
roker@505
   106
      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
roker@505
   107
      will remain in the ownership of the caller
roker@242
   108
```
roker@242
   109
roker@242
   110
roker@242
   111
##### startKeySync()
roker@242
   112
Start Key Synchronization for the current session.
roker@242
   113
roker@242
   114
##### stopKeySync()
roker@242
   115
Stop Key Synchronization for the current session.
roker@242
   116
roker@242
   117
##### startKeyserverLookup()
roker@242
   118
Start a global thread for Keyserver Lookup. This thread handles all keyserver communication for all sessions.
roker@242
   119
roker@242
   120
##### stopKeyserverLookup()
roker@242
   121
Stop the global thread for Keyserver Lookup.
roker@242
   122
roker@242
   123
roker@244
   124
##### encrypt_message(Message src, StringList extra_keys, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
roker@242
   125
encrypt message in memory
roker@242
   126
```
roker@242
   127
  parameters:
roker@242
   128
      src (in)            message to encrypt
roker@244
   129
      extra_keys (in)     extra keys for encryption
roker@242
   130
      dst (out)           pointer to new encrypted message or NULL on failure
roker@242
   131
      enc_format (in)     encrypted format
roker@242
   132
      flags (in)          flags to set special encryption features
roker@242
   133
roker@242
   134
  return value:
roker@242
   135
      PEP_STATUS_OK                   on success
roker@242
   136
      PEP_KEY_NOT_FOUND               at least one of the receipient keys
roker@242
   137
                                      could not be found
roker@242
   138
      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
roker@242
   139
                                      an ambiguous name
roker@242
   140
      PEP_GET_KEY_FAILED              cannot retrieve key
roker@242
   141
      PEP_UNENCRYPTED                 no recipients with usable key, 
roker@242
   142
                                      message is left unencrypted,
roker@242
   143
                                      and key is attached to it
roker@242
   144
```
roker@242
   145
roker@244
   146
##### encrypt_message_for_self(Identity target_id, Message src, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
roker@242
   147
encrypt message in memory for user's identity only,
roker@242
   148
ignoring recipients and other identities from
roker@242
   149
the message.
roker@242
   150
roker@242
   151
```
roker@242
   152
  parameters:
roker@242
   153
      target_id (in)      self identity this message should be encrypted for
roker@242
   154
      src (in)            message to encrypt
roker@242
   155
      dst (out)           pointer to new encrypted message or NULL on failure
roker@242
   156
      enc_format (in)     encrypted format
roker@242
   157
      flags (in)          flags to set special encryption features
roker@242
   158
roker@242
   159
  return value:       (FIXME: This may not be correct or complete)
roker@242
   160
      PEP_STATUS_OK            on success
roker@242
   161
      PEP_KEY_NOT_FOUND        at least one of the receipient keys
roker@242
   162
                               could not be found
roker@242
   163
      PEP_KEY_HAS_AMBIG_NAME   at least one of the receipient keys has
roker@242
   164
                               an ambiguous name
roker@242
   165
      PEP_GET_KEY_FAILED       cannot retrieve key
roker@242
   166
```
roker@242
   167
*Caveat:* message is NOT encrypted for identities other than the target_id (and then,
roker@242
   168
only if the target_id refers to self!)
roker@242
   169
roker@242
   170
roker@505
   171
##### decrypt_message(Message⇕ src, Message⇑ dst, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇕ flags)
roker@242
   172
decrypt message in memory
roker@242
   173
```
roker@242
   174
  parameters:
roker@505
   175
      src (inout)         message to decrypt
roker@242
   176
      dst (out)           pointer to new decrypted message or NULL on failure
roker@242
   177
      keylist (out)       stringlist with keyids
roker@242
   178
      rating (out)        rating for the message
roker@505
   179
      flags (inout)       flags to signal special decryption features
roker@242
   180
roker@242
   181
  return value:
roker@242
   182
      error status 
roker@242
   183
      or PEP_DECRYPTED if message decrypted but not verified
roker@505
   184
      or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly
roker@505
   185
         verified) but a reencryption operation is expected by the caller
roker@505
   186
         and failed
roker@242
   187
      or PEP_STATUS_OK on success
roker@242
   188
roker@505
   189
  flag values:
roker@505
   190
      in:
roker@505
   191
          PEP_decrypt_flag_untrusted_server
roker@505
   192
              used to signal that decrypt function should engage in behaviour
roker@505
   193
              specified for when the server storing the source is untrusted
roker@505
   194
      out:
roker@505
   195
          PEP_decrypt_flag_own_private_key
roker@505
   196
              private key was imported for one of our addresses (NOT trusted
roker@505
   197
              or set to be used - handshake/trust is required for that)
roker@505
   198
          PEP_decrypt_flag_src_modified
roker@505
   199
              indicates that the src object has been modified. At the moment,
roker@505
   200
              this is always as a direct result of the behaviour driven
roker@505
   201
              by the input flags. This flag is the ONLY value that should be
roker@505
   202
              relied upon to see if such changes have taken place.
roker@505
   203
          PEP_decrypt_flag_consume
roker@505
   204
              used by sync 
roker@505
   205
          PEP_decrypt_flag_ignore
roker@505
   206
              used by sync 
roker@505
   207
roker@505
   208
roker@242
   209
 caveat:
roker@505
   210
      the ownership of src remains with the caller - however, the contents 
roker@505
   211
          might be modified (strings freed and allocated anew or set to NULL,
roker@505
   212
          etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
roker@505
   213
          is set.
roker@505
   214
      the ownership of dst goes to the caller
roker@505
   215
      the ownership of keylist goes to the caller
roker@242
   216
      if src is unencrypted this function returns PEP_UNENCRYPTED and sets
roker@505
   217
         dst to NULL
roker@242
   218
```
roker@242
   219
roker@244
   220
##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
roker@242
   221
get rating for an outgoing message
roker@242
   222
```
roker@242
   223
  parameters:
roker@242
   224
      msg (in)            message to get the rating for
roker@242
   225
      rating (out)        rating for the message
roker@242
   226
roker@242
   227
  return value:
roker@242
   228
      error status or PEP_STATUS_OK on success
roker@242
   229
roker@242
   230
  caveat:
roker@242
   231
      msg->from must point to a valid pEp_identity
roker@242
   232
      msg->dir must be PEP_dir_outgoing
roker@242
   233
```
roker@242
   234
roker@244
   235
##### re_evaluate_message_rating(Message msg, StringList keylist, PEP_rating enc_status, PEP_rating⇑ rating)
roker@242
   236
re-evaluate already decrypted message rating
roker@242
   237
```
roker@242
   238
  parameters:
roker@242
   239
      msg (in)                message to get the rating for
roker@244
   240
      keylist (in)            decrypted message recipients keys fpr
roker@244
   241
      enc_status (in)         original rating for the decrypted message
roker@242
   242
      rating (out)            rating for the message
roker@242
   243
roker@242
   244
  return value:
roker@242
   245
      PEP_ILLEGAL_VALUE       if decrypted message doesn't contain 
roker@242
   246
                              X-EncStatus optional field and x_enc_status is 
roker@242
   247
                              pEp_rating_udefined
roker@242
   248
                              or if decrypted message doesn't contain 
roker@242
   249
                              X-Keylist optional field and x_keylist is NULL
roker@242
   250
      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
roker@242
   251
roker@242
   252
  caveat:
roker@242
   253
      msg->from must point to a valid pEp_identity
roker@242
   254
```
roker@242
   255
roker@244
   256
##### identity_rating(Identity ident, PEP_rating⇑ rating)
roker@242
   257
 get rating for a single identity
roker@242
   258
```
roker@242
   259
  parameters:
roker@242
   260
      ident (in)          identity to get the rating for
roker@242
   261
      rating (out)        rating for the identity
roker@242
   262
roker@242
   263
  return value:
roker@242
   264
      error status or PEP_STATUS_OK on success
roker@242
   265
```
roker@242
   266
roker@242
   267
##### get_gpg_path(String⇑)
roker@242
   268
get path of gpg binary.
roker@242
   269
roker@242
   270
#### pEp Engine Core API ####
roker@242
   271
roker@244
   272
##### get_trustwords(Identity id1, Identity id2, Language lang, String⇑ words, Integer⇑ wsize, Bool full)
roker@244
   273
get full trustwords string for a *pair* of identities
Thomas@256
   274
```
roker@244
   275
    parameters:
roker@244
   276
        id1 (in)            identity of first party in communication - fpr can't be NULL  
roker@244
   277
        id2 (in)            identity of second party in communication - fpr can't be NULL
roker@244
   278
        lang (in)           C string with ISO 639-1 language code
roker@244
   279
        words (out)         pointer to C string with all trustwords UTF-8 encoded,
roker@244
   280
                            separated by a blank each
roker@244
   281
                            NULL if language is not supported or trustword
roker@244
   282
                            wordlist is damaged or unavailable
roker@244
   283
        wsize (out)         length of full trustwords string
roker@244
   284
        full (in)           if true, generate ALL trustwords for these identities.
roker@244
   285
                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
roker@244
   286
                            subset in next version)
roker@242
   287
roker@244
   288
    return value:
roker@244
   289
        PEP_STATUS_OK            trustwords retrieved
roker@244
   290
        PEP_OUT_OF_MEMORY        out of memory
roker@244
   291
        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
roker@244
   292
```
roker@242
   293
roker@244
   294
##### get_languagelist(String⇑ languages)
roker@244
   295
get the list of languages
roker@244
   296
```
roker@244
   297
  parameters:
roker@244
   298
      languages (out)         languages as string in double quoted CSV format
roker@244
   299
                              column 1 is the ISO 639-1 language code
roker@244
   300
                              column 2 is the name of the language
roker@244
   301
```
roker@242
   302
roker@386
   303
roker@386
   304
##### is_pep_user(Identity id, Bool⇑  ia_pwp)
roker@386
   305
returns true if the USER corresponding to this identity has been listed in the *person* table as a pEp user
Thomas@256
   306
```
roker@386
   307
parameters:
roker@386
   308
    identity (in) - identity containing the user_id to check (this is
roker@386
   309
                    the only part of the struct we require to be set)
roker@387
   310
    is_pep (out)  - boolean pointer - will return true or false by
roker@387
   311
                    reference with respect to whether or not user is
roker@386
   312
                    a known pep user
roker@244
   313
```
roker@244
   314
roker@244
   315
##### config_passive_mode(Bool enable)
roker@244
   316
enable passive mode
roker@244
   317
roker@244
   318
*  parameters:   enable (in)     flag if enabled or disabled
roker@244
   319
roker@244
   320
roker@244
   321
##### config_unencrypted_subject(Bool enable)
roker@244
   322
disable subject encryption
roker@244
   323
roker@244
   324
* parameters:  enable (in)     flag if enabled or disabled
roker@242
   325
roker@242
   326
roker@242
   327
#### Identity Management API ####
roker@244
   328
##### get_identity(String address, String user_id, Identity⇑ identity)
roker@244
   329
get identity information
roker@244
   330
roker@244
   331
```
roker@244
   332
    parameters:
roker@244
   333
        address (in)        string with communication address, UTF-8 encoded
roker@244
   334
        user_id (in)        unique string to identify person that identity is refering to
roker@244
   335
        identity (out)      pEp_identity structure with results or NULL if failure
roker@244
   336
```
roker@242
   337
roker@242
   338
##### set_identity(Identity)
roker@244
   339
set identity information
roker@244
   340
```
roker@244
   341
    parameters:
roker@244
   342
        identity (in)       pEp_identity structure
roker@242
   343
roker@244
   344
    return value:
roker@244
   345
        PEP_STATUS_OK = 0             encryption and signing succeeded
roker@244
   346
        PEP_CANNOT_SET_PERSON         writing to table person failed
roker@244
   347
        PEP_CANNOT_SET_PGP_KEYPAIR    writing to table pgp_keypair failed
roker@244
   348
        PEP_CANNOT_SET_IDENTITY       writing to table identity failed
roker@244
   349
        PEP_COMMIT_FAILED             SQL commit failed
roker@244
   350
        PEP_KEY_BLACKLISTED           Key blacklisted, cannot set identity
roker@242
   351
roker@244
   352
    caveat:
roker@244
   353
        address, fpr, user_id and username must be given
roker@244
   354
```
roker@242
   355
roker@244
   356
##### mark_as_comprimized(String fpr)
roker@244
   357
mark key in trust db as compromized
roker@242
   358
roker@244
   359
* parameters:  fpr (in)            fingerprint of key to mark
roker@242
   360
roker@242
   361
roker@244
   362
##### identity_rating(Identity ident, PEP_rating⇑ rating)
roker@244
   363
get rating for a single identity
roker@244
   364
```
roker@244
   365
  parameters:
roker@244
   366
      ident (in)          identity to get the rating for
roker@244
   367
      rating (out)        rating for the identity
roker@244
   368
roker@244
   369
  return value:
roker@244
   370
      error status or PEP_STATUS_OK on success
roker@244
   371
```
roker@244
   372
roker@244
   373
##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
roker@244
   374
get rating for an outgoing message
roker@244
   375
```
roker@244
   376
  parameters:
roker@244
   377
      msg (in)            message to get the rating for
roker@244
   378
      rating (out)        rating for the message
roker@244
   379
roker@244
   380
  return value:
roker@244
   381
      error status or PEP_STATUS_OK on success
roker@244
   382
roker@244
   383
  caveat:
roker@244
   384
      msg->from must point to a valid pEp_identity
roker@244
   385
      msg->dir must be PEP_dir_outgoing
roker@244
   386
```
roker@244
   387
roker@244
   388
##### set_identity_flags(Identity⇕ identity, Integer flags)
roker@244
   389
update identity flags on existing identity
roker@244
   390
```
roker@244
   391
    parameters:
roker@244
   392
        identity (in,out)   pointer to pEp_identity structure
roker@244
   393
        flags (in)          new value for flags
roker@244
   394
roker@244
   395
    return value:
roker@244
   396
        PEP_STATUS_OK = 0             encryption and signing succeeded
roker@244
   397
        PEP_CANNOT_SET_IDENTITY       update of identity failed
roker@244
   398
roker@244
   399
    caveat:
roker@244
   400
        address and user_id must be given in identity
roker@244
   401
```
roker@244
   402
roker@244
   403
##### unset_identity_flags(Identity⇕ identity, Integer flags)
roker@244
   404
update identity flags on existing identity
roker@244
   405
```
roker@244
   406
    parameters:
roker@244
   407
        identity (in,out)   pointer to pEp_identity structure
roker@244
   408
        flags (in)          new value for flags
roker@244
   409
roker@244
   410
    return value:
roker@244
   411
        PEP_STATUS_OK = 0             encryption and signing succeeded
roker@244
   412
        PEP_CANNOT_SET_IDENTITY       update of identity failed
roker@244
   413
roker@244
   414
    caveat:
roker@244
   415
        address and user_id must be given in identity
roker@244
   416
```
roker@242
   417
roker@242
   418
#### Low level Key Management API ####
roker@244
   419
##### generate_keypair(Identity⇕ identity)
roker@244
   420
generate a new key pair and add it to the key ring
roker@244
   421
```
roker@244
   422
  parameters:
roker@244
   423
        identity (inout)      pEp_identity structure
roker@242
   424
roker@244
   425
    return value:
roker@244
   426
        PEP_STATUS_OK = 0       encryption and signing succeeded
roker@244
   427
        PEP_ILLEGAL_VALUE       illegal values for identity fields given
roker@244
   428
        PEP_CANNOT_CREATE_KEY   key engine is on strike
roker@242
   429
roker@244
   430
  caveat:
roker@244
   431
      address and username fields must be set to UTF-8 strings
roker@244
   432
      the fpr field must be set to NULL
roker@244
   433
```
roker@242
   434
roker@244
   435
##### delete_keypair(String fpr)
roker@244
   436
delete a public key or a key pair from the key ring
roker@244
   437
```
roker@244
   438
  parameters:
roker@244
   439
      fpr (in)                string with key id or fingerprint of the public key
roker@242
   440
roker@244
   441
  return value:
roker@244
   442
      PEP_STATUS_OK = 0       key was successfully deleted
roker@244
   443
      PEP_KEY_NOT_FOUND       key not found
roker@244
   444
      PEP_ILLEGAL_VALUE       not a valid key id or fingerprint
roker@244
   445
      PEP_KEY_HAS_AMBIG_NAME  fpr does not uniquely identify a key
roker@244
   446
      PEP_OUT_OF_MEMORY       out of memory
roker@244
   447
```
roker@242
   448
roker@244
   449
##### import_key(String key_data, Integer size, IdentityList⇑ private_keys)
roker@244
   450
import key from data
roker@244
   451
```
roker@244
   452
  parameters:
roker@244
   453
      key_data (in)           key data, i.e. ASCII armored OpenPGP key
roker@244
   454
      size (in)               amount of data to handle
roker@244
   455
      private_keys (out)      list of private keys that have been imported
roker@242
   456
roker@244
   457
  return value:
roker@244
   458
      PEP_STATUS_OK = 0       key was successfully imported
roker@244
   459
      PEP_OUT_OF_MEMORY       out of memory
roker@244
   460
      PEP_ILLEGAL_VALUE       there is no key data to import
roker@244
   461
```
roker@242
   462
roker@244
   463
##### export_key(String fpr, String⇑ key_data, Integer⇑ size)
roker@244
   464
export ascii armored key
roker@244
   465
```
roker@244
   466
  parameters:
roker@244
   467
      fpr (in)                key id or fingerprint of key
roker@244
   468
      key_data (out)          ASCII armored OpenPGP key
roker@244
   469
      size (out)              amount of data to handle
roker@242
   470
roker@244
   471
  return value:
roker@244
   472
      PEP_STATUS_OK = 0       key was successfully exported
roker@244
   473
      PEP_OUT_OF_MEMORY       out of memory
roker@244
   474
      PEP_KEY_NOT_FOUND       key not found
roker@244
   475
```
roker@244
   476
roker@244
   477
##### find_keys(String pattern, StringList⇑ keylist)
roker@244
   478
find keys in keyring
roker@244
   479
```
roker@244
   480
  parameters:
roker@244
   481
      pattern (in)            key id, user id or address to search for as UTF-8 string
roker@244
   482
      keylist (out)           list of fingerprints found or NULL on error
roker@244
   483
```
roker@244
   484
roker@244
   485
##### get_trust(Identity⇕ identity)
roker@244
   486
get the trust level a key has for a person
roker@244
   487
roker@244
   488
```
roker@244
   489
  parameters:
roker@244
   490
      identity (inout)        user_id and fpr to check as UTF-8 strings (in)
roker@244
   491
                              user_id and comm_type as result (out)
roker@244
   492
```
roker@244
   493
roker@244
   494
This function modifies the given identity struct; the struct remains in
roker@244
   495
the ownership of the caller.
roker@244
   496
If the trust level cannot be determined identity->comm_type is set
roker@244
   497
to PEP_ct_unknown.
roker@244
   498
roker@244
   499
roker@244
   500
##### own_key_is_listed(String fpr, Bool⇑ listed)
roker@244
   501
returns true id key is listed as own key
roker@244
   502
```
roker@244
   503
  parameters:
roker@244
   504
      fpr (in)            fingerprint of key to test
roker@386
   505
      listed (out)        flags if key is own
roker@244
   506
```
roker@244
   507
roker@244
   508
##### own_identities_retrieve(IdentityList⇑ own_identities)
roker@244
   509
retrieve all own identities
roker@244
   510
```
roker@244
   511
  parameters:
roker@244
   512
      own_identities (out)    list of own identities
roker@244
   513
```
roker@244
   514
roker@386
   515
##### set_own_key( Identity⇕ id, String fpr)
roker@386
   516
mark key as own key
roker@386
   517
```
roker@386
   518
  parameters:
roker@386
   519
     me (inout)              own identity this key is used for                                                                    
roker@386
   520
     fpr (in)                fingerprint of the key to mark as own key                                                            
roker@386
   521
```
roker@386
   522
roker@387
   523
##### undo_last_mistrust()
roker@387
   524
reset identity and trust status for the last`identity in this session marked
roker@387
   525
as mistrusted to their cached values from the time of mistrust
roker@387
   526
roker@387
   527
```
roker@387
   528
  parameters:
roker@387
   529
      (none)
roker@387
   530
roker@387
   531
  return value:
roker@387
   532
      PEP_STATUS_OK if identity and trust were successfully restored.
roker@387
   533
      Otherwise, error status from attempts to set.
roker@387
   534
roker@387
   535
  caveat:
roker@387
   536
      only works for this session, and only once. cache is invalidated
roker@387
   537
      upon use.
roker@387
   538
roker@387
   539
      WILL NOT WORK ON MISTRUSTED OWN KEY
roker@387
   540
```
roker@387
   541
roker@244
   542
##### myself(Identity⇕ identity)
roker@244
   543
ensures that the own identity is being complete
roker@244
   544
```
roker@244
   545
  parameters:
roker@244
   546
      identity (inout)    identity of local user. At least .address, .username, .user_id must be set.
roker@244
   547
roker@244
   548
  return value:
roker@244
   549
      PEP_STATUS_OK if identity could be completed or was already complete, any other value on error
roker@244
   550
roker@244
   551
  caveat:
roker@244
   552
      This function generates a keypair on demand; because it's synchronous
roker@244
   553
      it can need a decent amount of time to return.
roker@244
   554
      If you need to do this asynchronous, you need to return an identity
roker@244
   555
      with retrieve_next_identity() where pEp_identity.me is true.
roker@244
   556
```
roker@242
   557
roker@386
   558
##### update_identity(Identity⇕)
roker@244
   559
update identity information
roker@244
   560
```
roker@244
   561
  parameters:
roker@244
   562
      identity (inout)    identity information of communication partner
roker@244
   563
                          (identity->fpr is OUT ONLY)
roker@244
   564
  return value:
roker@244
   565
      PEP_STATUS_OK if identity could be updated,
roker@244
   566
      PEP_GET_KEY_FAILED for own identity that must be completed (myself())
roker@244
   567
      any other value on error
roker@244
   568
roker@244
   569
  caveat:
roker@244
   570
      if this function returns PEP_ct_unknown or PEP_ct_key_expired in
roker@244
   571
      identity->comm_type, the caller must insert the identity into the
roker@244
   572
      asynchronous management implementation, so retrieve_next_identity()
roker@244
   573
      will return this identity later
roker@244
   574
      at least identity->address must be a non-empty UTF-8 string as input
roker@244
   575
      update_identity() never writes flags; use set_identity_flags() for
roker@244
   576
      writing
roker@244
   577
      this function NEVER reads the incoming fpr, only writes to it.
roker@244
   578
```
roker@242
   579
roker@242
   580
##### trust_personal_key(Identity)
roker@244
   581
mark a key as trusted with a person
roker@244
   582
```
roker@244
   583
  parameters:
roker@244
   584
      ident (in)          person and key to trust in
roker@244
   585
roker@244
   586
  caveat:
roker@244
   587
      the fields user_id, address and fpr must be supplied
roker@244
   588
```
roker@242
   589
roker@242
   590
##### key_mistrusted(Identity)
roker@244
   591
mark key as being compromized
roker@244
   592
```
roker@244
   593
  parameters:
roker@244
   594
      ident (in)          person and key which was compromized
roker@244
   595
```
roker@242
   596
roker@242
   597
##### key_reset_trust(Identity)
roker@244
   598
 undo trust_personal_key and key_mistrusted() for keys we don't own
roker@244
   599
```
roker@244
   600
  parameters:
roker@244
   601
      ident (in)          person and key which was compromized
roker@244
   602
```
roker@242
   603
roker@244
   604
##### least_trust(String fpr, PEP_comm_type⇑ comm_type)
roker@244
   605
get the least known trust level for a key in the database
roker@244
   606
```
roker@244
   607
  parameters:
roker@244
   608
      fpr (in)                fingerprint of key to check
roker@244
   609
      comm_type (out)         least comm_type as result (out)
roker@244
   610
```
roker@242
   611
roker@244
   612
If the trust level cannot be determined comm_type is set to PEP_ct_unknown.
roker@242
   613
roker@242
   614
roker@244
   615
##### get_key_rating(String fpr, PEP_comm_type⇑ comm_type)
roker@244
   616
get the rating a bare key has
roker@244
   617
```
roker@244
   618
  parameters:
roker@244
   619
      fpr (in)                unique identifyer for key as UTF-8 string
roker@244
   620
      comm_type (out)         key rating
roker@244
   621
```
roker@242
   622
roker@244
   623
Iif an error occurs, *comm_type is set to PEP_ct_unknown and an error is returned
roker@244
   624
roker@244
   625
roker@244
   626
##### renew_key(String fpr, Timestamp ts)
roker@244
   627
renew an expired key
roker@244
   628
```
roker@244
   629
  parameters:
roker@244
   630
      fpr (in)                ID of key to renew as UTF-8 string
roker@244
   631
      ts (in)                 timestamp when key should expire or NULL for default
roker@244
   632
```
roker@244
   633
roker@244
   634
##### revoke(String fpr, String reason)
roker@244
   635
revoke a key
roker@244
   636
```
roker@244
   637
  parameters:
roker@244
   638
      fpr (in)                ID of key to revoke as UTF-8 string
roker@244
   639
      reason (in)             text with reason for revoke as UTF-8 string
roker@244
   640
                              or NULL if reason unknown
roker@244
   641
roker@244
   642
  caveat:
roker@244
   643
      reason text must not include empty lines
roker@244
   644
      this function is meant for internal use only; better use
roker@244
   645
      key_mistrusted() of keymanagement API
roker@244
   646
```
roker@244
   647
roker@244
   648
##### key_expired(String fpr, Integer when, Bool⇑ expired)
roker@244
   649
flags if a key is already expired
roker@244
   650
```
roker@244
   651
  parameters:
roker@244
   652
      fpr (in)                ID of key to check as UTF-8 string
roker@244
   653
      when (in)               UTC time of when should expiry be considered
roker@244
   654
      expired (out)           flag if key expired
roker@244
   655
```
roker@242
   656
roker@242
   657
roker@242
   658
#### from blacklist.h & OpenPGP_compat.h ####
roker@244
   659
##### blacklist_add(String fpr)
roker@244
   660
add to blacklist
roker@244
   661
*  parameters:  fpr (in)            fingerprint of key to blacklist
roker@242
   662
roker@242
   663
roker@244
   664
##### blacklist_delete(String fpr)
roker@244
   665
delete from blacklist
roker@244
   666
*  parameters:  fpr (in)            fingerprint of key to blacklist
roker@242
   667
roker@244
   668
##### blacklist_is_listed(String fpr, Bool⇑ listed)
roker@244
   669
is_listed in blacklist
roker@244
   670
```
roker@244
   671
  parameters:
roker@244
   672
      session (in)        session to use
roker@244
   673
      fpr (in)            fingerprint of key to blacklist
roker@244
   674
      listted (out)
roker@244
   675
```
roker@242
   676
roker@244
   677
##### blacklist_retrieve(StringList⇑ blacklist)
roker@244
   678
retrieve full blacklist of key fingerprints
roker@244
   679
roker@244
   680
* parameters:   blacklist (out)     copy of blacklist
roker@244
   681
roker@244
   682
roker@244
   683
##### OpenPGP_list_keyinfo(String search_pattern, StringPairList⇑ keyinfo_list)
roker@244
   684
get a key/UID list for pattern matches in keyring ("" to return entire keyring), filtering out revoked keys in the results
roker@244
   685
```
roker@244
   686
  parameters:
roker@244
   687
      search_pattern (in)   search pattern - either an fpr, or something within the UID, or "" for all keys
roker@244
   688
      keyinfo_list (out)    a key/value pair list for each key / UID combination
roker@244
   689
```
roker@242
   690
roker@242
   691
roker@242
   692
#### Event Listener & Results ####
roker@244
   693
##### registerEventListener(String address, Integer port, String security_context)
roker@244
   694
Register an address/port pair where a JSON-RPC call shall be made to, when the Engine wants to call the client application.
roker@244
   695
These RPC calls are authenticated with a security_context parameter that is given to all calls (and can be different from the security_context
roker@244
   696
that is used for calls from the client to the JSON Server Adapter).
roker@242
   697
roker@244
   698
Currently there are two functions that can be called:
roker@244
   699
* messageToSend( Message )
roker@244
   700
* notifyHandshake( Identity self, Identity partner, sync_handshake_signal sig )
roker@242
   701
roker@244
   702
##### unregisterEventListener(String address, Integer port, String security_context)
roker@244
   703
Unregister a previous registered JSON-RPC listener.
roker@242
   704
roker@244
   705
##### deliverHandshakeResult(Identity partner, PEP_sync_handshake_result result)
roker@244
   706
give the result of the handshake dialog back to the Engine
roker@244
   707
```
roker@244
   708
  parameters:
roker@244
   709
      partner (in)        the parther of the handshake
roker@244
   710
      result (in)         handshake result
roker@244
   711
```
roker@242
   712
roker@242
   713
#### Other ####
roker@387
   714
roker@387
   715
##### serverVersion()
roker@387
   716
Returns a struct with SemVer-compatible ABI version, the codename of the
roker@387
   717
JSON Adapter version etc.
roker@387
   718
roker@242
   719
##### version()
roker@244
   720
Returns a codename for the current JSON Server Adapter's version.
roker@242
   721
roker@242
   722
roker@242
   723
##### getGpgEnvironment()
roker@244
   724
Returns a struct holding 3 members
roker@244
   725
* gnupg_path
roker@244
   726
* gnupg_home environment variable, if set
roker@244
   727
* gpg_agent_info environment variable, if set.
roker@242
   728
roker@387
   729
##### shutdown()
roker@387
   730
shutdown the JSON Adapter