You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
219 lines
6.8 KiB
219 lines
6.8 KiB
// p≡p Keymanagement API version 0.1
|
|
|
|
// Copyleft (c) 2019, p≡p foundation
|
|
// this file is under GNU General Public License 3.0
|
|
// see LICENSE.txt
|
|
|
|
// written by Volker Birk
|
|
|
|
|
|
protocol session {
|
|
method update_identity
|
|
doc="update identity information"
|
|
{
|
|
// parms
|
|
|
|
supply identity identity
|
|
doc="""
|
|
identity information of communication partner
|
|
(identity->fpr is OUT ONLY), and at least
|
|
.address must be set.
|
|
If .username is set, it will be used to set or patch
|
|
the username record for this identity.
|
|
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.
|
|
this function will fail if called on an identity which, with its input
|
|
values, *explicitly* indicates it is an own identity (i.e. .me is set
|
|
to true on input, or a user_id is given AND it is a known own user_id).
|
|
however, it can RETURN an own identity if this is not indicated a
|
|
priori, and in fact will do so with prejudice when not faced with a
|
|
matching default (i.e. it is forced to search by address only).
|
|
if the identity is known to be an own identity (or the caller wishes
|
|
to make it one), call myself() on the identity instead.
|
|
|
|
FIXME: is this next point accurate?
|
|
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
|
|
END FIXME
|
|
"""
|
|
|
|
// exceptions
|
|
|
|
throws illegal_value
|
|
doc="""
|
|
if called with illegal inputs, including an identity
|
|
with .me set or with an own user_id specified in the
|
|
*input* (see caveats)
|
|
""";
|
|
|
|
throws key_unsuitable
|
|
doc="""
|
|
if a default key was found for this identity, no
|
|
other acceptable keys were found; if this is returned,
|
|
the reason for rejecting the first default key found
|
|
may be found in the comm_type
|
|
"""
|
|
}
|
|
|
|
|
|
method initialise_own_identities
|
|
doc="ensures that an own identity is complete"
|
|
{
|
|
// parms
|
|
|
|
supply identity_list my_idents
|
|
doc="""
|
|
identities of local user to quick-set
|
|
For these, at least .address must be set.
|
|
if no .user_id is set, AND the DB doesn't contain
|
|
a default user_id, own_userid will be used and
|
|
become the perennial default for the DB.
|
|
|
|
This function does NOT generate keypairs. It is intended to
|
|
precede running of the engine on actual messages. It effectively
|
|
behaves like myself(), but when there would normally be key generation
|
|
(when there is no valid key, for example),
|
|
it instead stores an identity without keys.
|
|
|
|
N.B. to adapter devs - this function is likely unnecessary, so please
|
|
do not put work into exposing it yet. Tickets will be filed if need be.
|
|
"""
|
|
}
|
|
|
|
|
|
method myself
|
|
doc="ensures that an own identity is complete"
|
|
{
|
|
// parms
|
|
|
|
supply identity identity
|
|
doc="""
|
|
identity of local user
|
|
both .address and .user_id must be set.
|
|
if .fpr is set, an attempt will be made to make
|
|
that the default key for this identity after key validation
|
|
if .fpr is not set, key retrieval is performed.
|
|
If .username is set, it will be used to set or patch
|
|
the username record for this identity.
|
|
|
|
If an fpr was entered and is not a valid key, the reason for failure
|
|
is immediately returned in the status and, possibly, identity->comm_type
|
|
If a default own user_id exists in the database, an alias will
|
|
be created for the default for the input user_id. The ENGINE'S default
|
|
user_id is always returned in the .user_id field
|
|
myself() NEVER elects keys from the keyring; it will only choose keys
|
|
which have been set up explicitly via myself(), or which were imported
|
|
during a first time DB setup from an OpenPGP keyring (compatibility only)
|
|
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 identity.me is true.
|
|
"""
|
|
}
|
|
|
|
method retrieve_next_identity
|
|
doc="callback being called by do_keymanagement"
|
|
{
|
|
// parms
|
|
|
|
XXXXXX
|
|
|
|
method examine_identity
|
|
doc="callback for appending to queue"
|
|
{
|
|
// parms
|
|
|
|
XXXX
|
|
|
|
method register_examine_function
|
|
doc="register examine_identity() callback"
|
|
{
|
|
//parms
|
|
|
|
provide?? examine_identity?? examine_identity doc="examine_identity() function to register";
|
|
|
|
provide void management doc="data structure to deliver (implementation defined)"
|
|
|
|
XXX?
|
|
// do_keymanagement() - function to be run on an extra thread
|
|
//
|
|
// parameters:
|
|
// retrieve_next_identity (in) pointer to retrieve_next_identity()
|
|
// callback which returns at least a valid
|
|
// address field in the identity struct
|
|
//
|
|
// return value:
|
|
// PEP_STATUS_OK if thread has to terminate successfully or any other
|
|
// value on failure
|
|
//
|
|
// caveat:
|
|
// to ensure proper working of this library, a thread has to be started
|
|
// with this function immediately after initialization
|
|
//
|
|
// do_keymanagement() calls retrieve_next_identity(management)
|
|
//
|
|
// messageToSend can only be null if no transport is application based
|
|
// if transport system is not used it must not be NULL
|
|
DYNAMIC_API PEP_STATUS do_keymanagement(
|
|
retrieve_next_identity_t retrieve_next_identity,
|
|
void *management
|
|
|
|
|
|
method key_mistrusted
|
|
doc="mark key as being compromised"
|
|
{
|
|
//parms
|
|
|
|
use identity ident
|
|
doc="""
|
|
person and key which was compromised
|
|
ident is INPUT ONLY. If you want updated trust on the identity, you'll have
|
|
to call update_identity or myself respectively after this.
|
|
N.B. If you are calling this on a key that is the identity or user default,
|
|
it will be removed as the default key for ANY identity and user for which
|
|
it is the default. Please keep in mind that the undo in undo_last_mistrust
|
|
will only undo the current identity's / it's user's default, not any
|
|
other identities which may be impacted (this will not affect most use
|
|
cases)
|
|
"""
|
|
}
|
|
|
|
|
|
method trust_personal_key
|
|
doc="mark a key as trusted for a user"
|
|
{
|
|
// parms
|
|
|
|
ident (in) person and key to trust in - this must not be an
|
|
// own_identity in which the .me flag is set or
|
|
// the user_id is an own user_id.
|
|
//
|
|
// caveat:
|
|
// the fields user_id, address and fpr must be supplied
|
|
// own identities will result in a return of PEP_ILLEGAL_VALUE.
|
|
// for non-own users, this will 1) set the trust bit on its comm type in the DB,
|
|
// 2) set this key as the identity default if the current identity default
|
|
// is not trusted, and 3) set this key as the user default if the current
|
|
// user default is not trusted.
|
|
|
|
DYNAMIC_API PEP_STATUS trust_personal_key(
|
|
PEP_SESSION session,
|
|
pEp_identity *ident
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|