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