leviathan
/
pEpJSONServerAdapter
forked from pEp.foundation/pEpJSONServerAdapter
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 0 Wiki Activity
Browse Source

finish detailed API documentation. I hope so.

JSON-57
Roker 5 years ago
parent
ceb1bd2d61
commit
073712183f
1 changed files with 393 additions and 46 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +393
    -46
      API reference details.md

+ 393
- 46
API reference details.md View File

@ -56,7 +56,7 @@ the message, with MIME output.
```
##### MIME_decrypt_message(String, Integer, String⇑, StringList⇑, PEP_rating⇑, Integer⇑ )
##### MIME_decrypt_message(String mimetext, Integer size, String⇑ mime_plaintext, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇑ flags)
decrypt a MIME message, with MIME output
```
@ -100,12 +100,12 @@ Start a global thread for Keyserver Lookup. This thread handles all keyserver co
Stop the global thread for Keyserver Lookup.
##### encrypt_message(Message, StringList, Message⇑, PEP_enc_format, Integer)
##### encrypt_message(Message src, StringList extra_keys, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
encrypt message in memory
```
parameters:
src (in) message to encrypt
extra (in) extra keys for encryption
extra_keys (in) extra keys for encryption
dst (out) pointer to new encrypted message or NULL on failure
enc_format (in) encrypted format
flags (in) flags to set special encryption features
@ -122,7 +122,7 @@ encrypt message in memory
and key is attached to it
```
##### encrypt_message_for_self(Identity, Message, Message⇑, PEP_enc_format, Integer)
##### encrypt_message_for_self(Identity target_id, Message src, Message⇑ dst, PEP_enc_format enc_format, Integer flags)
encrypt message in memory for user's identity only,
ignoring recipients and other identities from
the message.
@ -147,7 +147,7 @@ the message.
only if the target_id refers to self!)
##### decrypt_message(Message, Message⇑, StringList⇑, PEP_rating⇑, Integer⇑)
##### decrypt_message(Message src, Message⇑ dst, StringList⇑ keylist, PEP_rating⇑ rating, Integer⇑ flags)
decrypt message in memory
```
parameters:
@ -167,7 +167,7 @@ decrypt message in memory
dst to NULL
```
##### outgoing_message_rating(Message, PEP_rating⇑)
##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
get rating for an outgoing message
```
parameters:
@ -182,13 +182,13 @@ get rating for an outgoing message
msg->dir must be PEP_dir_outgoing
```
##### re_evaluate_message_rating(Message, StringList, PEP_rating, PEP_rating⇑)
##### re_evaluate_message_rating(Message msg, StringList keylist, PEP_rating enc_status, PEP_rating⇑ rating)
re-evaluate already decrypted message rating
```
parameters:
msg (in) message to get the rating for
x_keylist (in) decrypted message recipients keys fpr
x_enc_status (in) original rating for the decrypted message
keylist (in) decrypted message recipients keys fpr
enc_status (in) original rating for the decrypted message
rating (out) rating for the message
return value:
@ -203,7 +203,7 @@ re-evaluate already decrypted message rating
msg->from must point to a valid pEp_identity
```
##### identity_rating(Identity, PEP_rating⇑)
##### identity_rating(Identity ident, PEP_rating⇑ rating)
get rating for a single identity
```
parameters:
@ -218,100 +218,447 @@ re-evaluate already decrypted message rating
get path of gpg binary.
#### pEp Engine Core API ####
##### log_event(String, String, String, String)
##### log_event(String title, String entity, String description, String comment)
log a user defined event defined by UTF-8 encoded strings into management log
##### get_trustwords(Identity, Identity, Language, String⇑, Integer⇑, Bool)
parameters:
title (in) C string with event name
entity (in) C string with name of entity which is logging
description (in) C string with long description for event or NULL if omitted
comment (in) C string with user defined comment or NULL if omitted
##### get_languagelist(String⇑)
return value:
PEP_STATUS_OK log entry created
```
##### get_trustwords(Identity id1, Identity id2, Language lang, String⇑ words, Integer⇑ wsize, Bool full)
get full trustwords string for a *pair* of identities
``
parameters:
id1 (in) identity of first party in communication - fpr can't be NULL
id2 (in) identity of second party in communication - fpr can't be NULL
lang (in) C string with ISO 639-1 language code
words (out) pointer to C string with all trustwords UTF-8 encoded,
separated by a blank each
NULL if language is not supported or trustword
wordlist is damaged or unavailable
wsize (out) length of full trustwords string
full (in) if true, generate ALL trustwords for these identities.
else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
subset in next version)
return value:
PEP_STATUS_OK trustwords retrieved
PEP_OUT_OF_MEMORY out of memory
PEP_TRUSTWORD_NOT_FOUND at least one trustword not found
```
##### get_languagelist(String⇑ languages)
get the list of languages
```
parameters:
languages (out) languages as string in double quoted CSV format
column 1 is the ISO 639-1 language code
column 2 is the name of the language
```
##### get_phrase(Language lang, Integer phrase_id, String⇑ phrase)
get phrase in a dedicated language through i18n
``
parameters:
lang (in) C string with ISO 639-1 language code
phrase_id (in) id of phrase in i18n
phrase (out) phrase as UTF-8 string
```
##### get_engine_version()
returns the current version of pEpEngine (this is different from the pEp protocol version!)
* parameters: (none)
* return_value: String containing the engine version string constant
##### config_passive_mode(Bool enable)
enable passive mode
##### get_phrase(Language, Integer, String⇑)
* parameters: enable (in) flag if enabled or disabled
##### get_engine_version | String | )
##### config_passive_mode | Void | Bool)
##### config_unencrypted_subject(Bool enable)
disable subject encryption
##### config_unencrypted_subject | Void | Bool)
* parameters: enable (in) flag if enabled or disabled
#### Identity Management API ####
##### get_identity(String, String, Identity⇑)
##### get_identity(String address, String user_id, Identity⇑ identity)
get identity information
```
parameters:
address (in) string with communication address, UTF-8 encoded
user_id (in) unique string to identify person that identity is refering to
identity (out) pEp_identity structure with results or NULL if failure
```
##### set_identity(Identity)
set identity information
```
parameters:
identity (in) pEp_identity structure
return value:
PEP_STATUS_OK = 0 encryption and signing succeeded
PEP_CANNOT_SET_PERSON writing to table person failed
PEP_CANNOT_SET_PGP_KEYPAIR writing to table pgp_keypair failed
PEP_CANNOT_SET_IDENTITY writing to table identity failed
PEP_COMMIT_FAILED SQL commit failed
PEP_KEY_BLACKLISTED Key blacklisted, cannot set identity
caveat:
address, fpr, user_id and username must be given
```
##### mark_as_comprimized(String fpr)
mark key in trust db as compromized
* parameters: fpr (in) fingerprint of key to mark
##### identity_rating(Identity ident, PEP_rating⇑ rating)
get rating for a single identity
```
parameters:
ident (in) identity to get the rating for
rating (out) rating for the identity
return value:
error status or PEP_STATUS_OK on success
```
##### outgoing_message_rating(Message msg, PEP_rating⇑ rating)
get rating for an outgoing message
```
parameters:
msg (in) message to get the rating for
rating (out) rating for the message
return value:
error status or PEP_STATUS_OK on success
caveat:
msg->from must point to a valid pEp_identity
msg->dir must be PEP_dir_outgoing
```
##### mark_as_comprimized(String)
##### set_identity_flags(Identity⇕ identity, Integer flags)
update identity flags on existing identity
```
parameters:
identity (in,out) pointer to pEp_identity structure
flags (in) new value for flags
##### identity_rating(Identity, PEP_rating⇑)
return value:
PEP_STATUS_OK = 0 encryption and signing succeeded
PEP_CANNOT_SET_IDENTITY update of identity failed
##### outgoing_message_rating(Message, PEP_rating⇑)
caveat:
address and user_id must be given in identity
```
##### set_identity_flags(Identity, Integer)
##### unset_identity_flags(Identity⇕ identity, Integer flags)
update identity flags on existing identity
```
parameters:
identity (in,out) pointer to pEp_identity structure
flags (in) new value for flags
##### unset_identity_flags(Identity, Integer)
return value:
PEP_STATUS_OK = 0 encryption and signing succeeded
PEP_CANNOT_SET_IDENTITY update of identity failed
caveat:
address and user_id must be given in identity
```
#### Low level Key Management API ####
##### generate_keypair(Identity⇕)
##### generate_keypair(Identity⇕ identity)
generate a new key pair and add it to the key ring
```
parameters:
identity (inout) pEp_identity structure
return value:
PEP_STATUS_OK = 0 encryption and signing succeeded
PEP_ILLEGAL_VALUE illegal values for identity fields given
PEP_CANNOT_CREATE_KEY key engine is on strike
caveat:
address and username fields must be set to UTF-8 strings
the fpr field must be set to NULL
```
##### delete_keypair(String)
##### delete_keypair(String fpr)
delete a public key or a key pair from the key ring
```
parameters:
fpr (in) string with key id or fingerprint of the public key
##### import_key(String, Integer, IdentityList⇑)
return value:
PEP_STATUS_OK = 0 key was successfully deleted
PEP_KEY_NOT_FOUND key not found
PEP_ILLEGAL_VALUE not a valid key id or fingerprint
PEP_KEY_HAS_AMBIG_NAME fpr does not uniquely identify a key
PEP_OUT_OF_MEMORY out of memory
```
##### export_key(String, String⇑, Integer⇑)
##### import_key(String key_data, Integer size, IdentityList⇑ private_keys)
import key from data
```
parameters:
key_data (in) key data, i.e. ASCII armored OpenPGP key
size (in) amount of data to handle
private_keys (out) list of private keys that have been imported
##### find_keys(String, StringList⇑)
return value:
PEP_STATUS_OK = 0 key was successfully imported
PEP_OUT_OF_MEMORY out of memory
PEP_ILLEGAL_VALUE there is no key data to import
```
##### get_trust(Identity⇕)
##### export_key(String fpr, String⇑ key_data, Integer⇑ size)
export ascii armored key
```
parameters:
fpr (in) key id or fingerprint of key
key_data (out) ASCII armored OpenPGP key
size (out) amount of data to handle
##### own_key_is_listed(String, Bool⇑)
return value:
PEP_STATUS_OK = 0 key was successfully exported
PEP_OUT_OF_MEMORY out of memory
PEP_KEY_NOT_FOUND key not found
```
##### own_identities_retrieve(IdentityList⇑)
##### find_keys(String pattern, StringList⇑ keylist)
find keys in keyring
```
parameters:
pattern (in) key id, user id or address to search for as UTF-8 string
keylist (out) list of fingerprints found or NULL on error
```
##### myself(Identity⇕)
##### get_trust(Identity⇕ identity)
get the trust level a key has for a person
```
parameters:
identity (inout) user_id and fpr to check as UTF-8 strings (in)
user_id and comm_type as result (out)
```
This function modifies the given identity struct; the struct remains in
the ownership of the caller.
If the trust level cannot be determined identity->comm_type is set
to PEP_ct_unknown.
##### own_key_is_listed(String fpr, Bool⇑ listed)
returns true id key is listed as own key
```
parameters:
fpr (in) fingerprint of key to test
listed (out) flags if key is own
```
##### own_identities_retrieve(IdentityList⇑ own_identities)
retrieve all own identities
```
parameters:
own_identities (out) list of own identities
```
##### myself(Identity⇕ identity)
ensures that the own identity is being complete
```
parameters:
identity (inout) identity of local user. At least .address, .username, .user_id must be set.
return value:
PEP_STATUS_OK if identity could be completed or was already complete, any other value on error
caveat:
This function generates a keypair on demand; because it's synchronous
it can need a decent amount of time to return.
If you need to do this asynchronous, you need to return an identity
with retrieve_next_identity() where pEp_identity.me is true.
```
##### update_dentity(Identity⇕)
update identity information
```
parameters:
identity (inout) identity information of communication partner
(identity->fpr is OUT ONLY)
return value:
PEP_STATUS_OK if identity could be updated,
PEP_GET_KEY_FAILED for own identity that must be completed (myself())
any other value on error
caveat:
if this function returns PEP_ct_unknown or PEP_ct_key_expired in
identity->comm_type, the caller must insert the identity into the
asynchronous management implementation, so retrieve_next_identity()
will return this identity later
at least identity->address must be a non-empty UTF-8 string as input
update_identity() never writes flags; use set_identity_flags() for
writing
this function NEVER reads the incoming fpr, only writes to it.
```
##### trust_personal_key(Identity)
mark a key as trusted with a person
```
parameters:
ident (in) person and key to trust in
caveat:
the fields user_id, address and fpr must be supplied
```
##### key_mistrusted(Identity)
mark key as being compromized
```
parameters:
ident (in) person and key which was compromized
```
##### key_reset_trust(Identity)
undo trust_personal_key and key_mistrusted() for keys we don't own
```
parameters:
ident (in) person and key which was compromized
```
##### least_trust(String fpr, PEP_comm_type⇑ comm_type)
get the least known trust level for a key in the database
```
parameters:
fpr (in) fingerprint of key to check
comm_type (out) least comm_type as result (out)
```
##### least_trust(String, PEP_comm_type⇑)
If the trust level cannot be determined comm_type is set to PEP_ct_unknown.
##### get_key_rating(String fpr, PEP_comm_type⇑ comm_type)
get the rating a bare key has
```
parameters:
fpr (in) unique identifyer for key as UTF-8 string
comm_type (out) key rating
```
##### get_key_rating(String, PEP_comm_type⇑)
Iif an error occurs, *comm_type is set to PEP_ct_unknown and an error is returned
##### renew_key(String, Timestamp)
##### revoke(String, String)
##### renew_key(String fpr, Timestamp ts)
renew an expired key
```
parameters:
fpr (in) ID of key to renew as UTF-8 string
ts (in) timestamp when key should expire or NULL for default
```
##### key_expired(String, Integer, Bool⇑)
##### revoke(String fpr, String reason)
revoke a key
```
parameters:
fpr (in) ID of key to revoke as UTF-8 string
reason (in) text with reason for revoke as UTF-8 string
or NULL if reason unknown
caveat:
reason text must not include empty lines
this function is meant for internal use only; better use
key_mistrusted() of keymanagement API
```
##### key_expired(String fpr, Integer when, Bool⇑ expired)
flags if a key is already expired
```
parameters:
fpr (in) ID of key to check as UTF-8 string
when (in) UTC time of when should expiry be considered
expired (out) flag if key expired
```
#### from blacklist.h & OpenPGP_compat.h ####
##### blacklist_add(String)
##### blacklist_add(String fpr)
add to blacklist
* parameters: fpr (in) fingerprint of key to blacklist
##### blacklist_delete(String)
##### blacklist_is_listed(String, Bool⇑)
##### blacklist_delete(String fpr)
delete from blacklist
* parameters: fpr (in) fingerprint of key to blacklist
##### blacklist_retrieve(StringList⇑)
##### blacklist_is_listed(String fpr, Bool⇑ listed)
is_listed in blacklist
```
parameters:
session (in) session to use
fpr (in) fingerprint of key to blacklist
listted (out)
```
##### OpenPGP_list_keyinfo(String, StringPairList⇑)
##### blacklist_retrieve(StringList⇑ blacklist)
retrieve full blacklist of key fingerprints
* parameters: blacklist (out) copy of blacklist
##### OpenPGP_list_keyinfo(String search_pattern, StringPairList⇑ keyinfo_list)
get a key/UID list for pattern matches in keyring ("" to return entire keyring), filtering out revoked keys in the results
```
parameters:
search_pattern (in) search pattern - either an fpr, or something within the UID, or "" for all keys
keyinfo_list (out) a key/value pair list for each key / UID combination
```
#### Event Listener & Results ####
##### registerEventListener(String, Integer, String)
##### registerEventListener(String address, Integer port, String security_context)
Register an address/port pair where a JSON-RPC call shall be made to, when the Engine wants to call the client application.
These RPC calls are authenticated with a security_context parameter that is given to all calls (and can be different from the security_context
that is used for calls from the client to the JSON Server Adapter).
##### unregisterEventListener(String, Integer, String)
Currently there are two functions that can be called:
* messageToSend( Message )
* notifyHandshake( Identity self, Identity partner, sync_handshake_signal sig )
##### deliverHandshakeResult(Identity, PEP_sync_handshake_result)
##### unregisterEventListener(String address, Integer port, String security_context)
Unregister a previous registered JSON-RPC listener.
##### deliverHandshakeResult(Identity partner, PEP_sync_handshake_result result)
give the result of the handshake dialog back to the Engine
```
parameters:
partner (in) the parther of the handshake
result (in) handshake result
```
#### Other ####
##### version()
Returns a codename for the current JSON Server Adapter's version.
##### apiVersion()
Returns a numerical API version, currently the API version is 2.
##### getGpgEnvironment()
Returns a struct holding 3 members
* gnupg_path
* gnupg_home environment variable, if set
* gpg_agent_info environment variable, if set.

Write Preview
Loading…
Cancel
Save