diff --git a/API reference details.md b/API reference details.md index f7104ac..456775b 100644 --- a/API reference details.md +++ b/API reference details.md @@ -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.