neuer stand generate_api
authornk
Wed, 27 Mar 2019 17:11:24 +0100
branchgenerate_api
changeset 3405ec4598385828
parent 3328 c09e7d4bd944
child 3414 10dd8071d216
neuer stand
api/basic_api.yml2
api/keymanagement_api.yml2
api/message_api.yml2
api/pEp.yml2
     1.1 --- a/api/basic_api.yml2	Tue Mar 05 13:59:00 2019 +0100
     1.2 +++ b/api/basic_api.yml2	Wed Mar 27 17:11:24 2019 +0100
     1.3 @@ -28,18 +28,6 @@
     1.4  
     1.5  type string_pair is pair< string, string >;
     1.6  
     1.7 -// string:  text
     1.8 -// int:     integer number
     1.9 -// blob:    Binary Large Object
    1.10 -// size_t:  size in memory
    1.11 -// const:
    1.12 -// identity:
    1.13 -// message:
    1.14 -// rating:
    1.15 -// enc_format:
    1.16 -// bool:
    1.17 -// cryptotech:
    1.18 -
    1.19  
    1.20  enum comm_type {
    1.21      hex unknown 0;
    1.22 @@ -131,3 +119,4 @@
    1.23  
    1.24  } // struct Identity
    1.25  
    1.26 +
     2.1 --- a/api/keymanagement_api.yml2	Tue Mar 05 13:59:00 2019 +0100
     2.2 +++ b/api/keymanagement_api.yml2	Wed Mar 27 17:11:24 2019 +0100
     2.3 @@ -60,31 +60,6 @@
     2.4  	}
     2.5  
     2.6  
     2.7 -	method initialise_own_identities
     2.8 -		doc="ensures that an own identity is complete"
     2.9 -	{
    2.10 -	// parms
    2.11 -	
    2.12 -	supply identity_list my_idents
    2.13 -	doc="""
    2.14 -		identities of local user to quick-set
    2.15 -		For these, at least .address must be set.
    2.16 -		if no .user_id is set, AND the DB doesn't contain
    2.17 -		a default user_id, own_userid will be used and
    2.18 -		become the perennial default for the DB.
    2.19 -		
    2.20 -		This function does NOT generate keypairs. It is intended to
    2.21 -		precede running of the engine on actual messages. It effectively
    2.22 -		behaves like myself(), but when there would normally be key generation
    2.23 -		(when there is no valid key, for example),
    2.24 -		it instead stores an identity without keys.
    2.25 -
    2.26 -		N.B. to adapter devs - this function is likely unnecessary, so please
    2.27 -		do not put work into exposing it yet. Tickets will be filed if need be.
    2.28 -		"""
    2.29 -	}
    2.30 -
    2.31 -
    2.32  	method myself
    2.33  		doc="ensures that an own identity is complete"
    2.34  	{
    2.35 @@ -115,53 +90,6 @@
    2.36  		"""
    2.37  	}
    2.38  
    2.39 -	method retrieve_next_identity
    2.40 -		doc="callback being called by do_keymanagement"
    2.41 -	{
    2.42 -	// parms
    2.43 -
    2.44 -XXXXXX
    2.45 -
    2.46 -	method examine_identity
    2.47 -		doc="callback for appending to queue"
    2.48 -	{
    2.49 -	// parms
    2.50 -
    2.51 -XXXX
    2.52 -
    2.53 -	method register_examine_function
    2.54 -		doc="register examine_identity() callback"
    2.55 -	{
    2.56 -	//parms
    2.57 -
    2.58 -	provide?? examine_identity?? examine_identity doc="examine_identity() function to register";
    2.59 -
    2.60 -	provide void management doc="data structure to deliver (implementation defined)"
    2.61 -
    2.62 -XXX?
    2.63 -// do_keymanagement() - function to be run on an extra thread
    2.64 -//
    2.65 -//  parameters:
    2.66 -//      retrieve_next_identity (in) pointer to retrieve_next_identity()
    2.67 -//                                  callback which returns at least a valid
    2.68 -//                                  address field in the identity struct
    2.69 -//
    2.70 -//  return value:
    2.71 -//      PEP_STATUS_OK if thread has to terminate successfully or any other
    2.72 -//      value on failure
    2.73 -//
    2.74 -//  caveat:
    2.75 -//      to ensure proper working of this library, a thread has to be started
    2.76 -//      with this function immediately after initialization
    2.77 -//
    2.78 -//      do_keymanagement() calls retrieve_next_identity(management)
    2.79 -//
    2.80 -//      messageToSend can only be null if no transport is application based
    2.81 -//      if transport system is not used it must not be NULL
    2.82 -DYNAMIC_API PEP_STATUS do_keymanagement(
    2.83 -        retrieve_next_identity_t retrieve_next_identity,
    2.84 -        void *management
    2.85 -
    2.86  
    2.87  	method key_mistrusted
    2.88  		doc="mark key as being compromised"
    2.89 @@ -183,37 +111,118 @@
    2.90  	}
    2.91  
    2.92  
    2.93 -	method trust_personal_key
    2.94 +    method trust_personal_key
    2.95  		doc="mark a key as trusted for a user"
    2.96  	{
    2.97  	// parms
    2.98  
    2.99 -	ident (in)          person and key to trust in - this must not be an
   2.100 -//                          own_identity in which the .me flag is set or
   2.101 -//                          the user_id is an own user_id.
   2.102 -//
   2.103 -//  caveat:
   2.104 -//      the fields user_id, address and fpr must be supplied
   2.105 -//      own identities will result in a return of PEP_ILLEGAL_VALUE.
   2.106 -//      for non-own users, this will 1) set the trust bit on its comm type in the DB,
   2.107 -//      2) set this key as the identity default if the current identity default
   2.108 -//      is not trusted, and 3) set this key as the user default if the current
   2.109 -//      user default is not trusted.
   2.110 +	use identity ident
   2.111 +    doc="""
   2.112 +        person and key to trust in - this must not be an own_identity in which 
   2.113 +        the .me flag is set or the user_id is an own user_id. The fields user_id, 
   2.114 +        address and fpr must be supplied own identities will result in a return 
   2.115 +        of illegal_value.
   2.116 +        For non-own users, this will 1) set the trust bit on its comm type in the DB,
   2.117 +        2) set this key as the identity default if the current identity default
   2.118 +        is not trusted, and 3) set this key as the user default if the current user
   2.119 +        default is not trusted.
   2.120 +        """
   2.121 +    }
   2.122  
   2.123 -DYNAMIC_API PEP_STATUS trust_personal_key(
   2.124 -        PEP_SESSION session,
   2.125 -        pEp_identity *ident
   2.126  
   2.127 +    method trust_own_key
   2.128 +        doc="""
   2.129 +            mark a key as trusted for self, generally used when we need to trust 
   2.130 +            a public key associated with outselves for issues like manual key import.
   2.131 +            """
   2.132 +    {
   2.133 +    // parms
   2.134  
   2.135 +    use identity ident
   2.136 +    doc="""
   2.137 +        own ident containing fpr to trust. 
   2.138 +        If this is a public key only, keep in mind that if the private part of the 
   2.139 +        keypair is later added, it will not undergo separate trust evaluation. This 
   2.140 +        is fine - even desired - as long as the semantics of this function are 
   2.141 +        understood as both trusting the key and verifying it as an own key. This will 
   2.142 +        NEVER cause replacement of or setting of a default *alone*. However, if a 
   2.143 +        private key is ever associated with this fpr, please keep in mind that trusting 
   2.144 +        it here makes it an eligible key for selection for encryption later. So use 
   2.145 +        this function on purpose with an understanding of what you're doing!
   2.146 +        """
   2.147 +    }
   2.148  
   2.149  
   2.150 +    method key_reset_trust
   2.151 +        doc="""
   2.152 +            reset trust bit or explicitly mistrusted status for an identity and its 
   2.153 +            accompanying key/user_id pair.
   2.154 +            """
   2.155 +    {
   2.156 +    // parms
   2.157  
   2.158 +    use ientity ident
   2.159 +    doc="""
   2.160 +        identity for person and key whose trust status is to be reset.
   2.161 +        Ident is INPUT ONLY. If you want updated trust on the identity, you'll have 
   2.162 +        to call update_identity or myself respectively after this.
   2.163 +        N.B. If you are calling this on a key that is the identity or user default,
   2.164 +        it will be removed as the default key for the identity and user (but is still
   2.165 +        available for key election, it is just not the cached default anymore).
   2.166 +        """
   2.167 +    }
   2.168  
   2.169 -   
   2.170  
   2.171 +    method own_key_is_listed 
   2.172 +        doc="returns true id key is listed as own key"
   2.173 +    {
   2.174 +    // parms
   2.175  
   2.176 +    use hash fpr doc="fingerprint of key to test"
   2.177  
   2.178 +    return bool listed doc="flags if key is own"
   2.179 +    }
   2.180  
   2.181  
   2.182 +    method own_identities_retrieve
   2.183 +        doc="retrieve all own identities"
   2.184 +    {
   2.185  
   2.186 +    // parms
   2.187  
   2.188 +    create identity_list own_identities 
   2.189 +    doc="""
   2.190 +        list of own identities. 
   2.191 +        The ownership of the copy of own_identities goes to the caller.
   2.192 +        """
   2.193 +    }
   2.194 +
   2.195 +
   2.196 +method own_keys_retrieve 
   2.197 +        doc="retrieve all flagged keypair fingerprints" 
   2.198 +    {
   2.199 +    // parms
   2.200 +
   2.201 +    create hashlist keylist doc="list of fingerprints"
   2.202 +    }
   2.203 +
   2.204 +
   2.205 +method set_own_key 
   2.206 +        doc="mark a key as own key"
   2.207 +    {
   2.208 +    // parms
   2.209 +
   2.210 +    supply identity me 
   2.211 +    doc="""
   2.212 +        own identity this key is used for. The key has to be in the key ring already.
   2.213 +        me->address, me->user_id and me->username must be set to valid data.
   2.214 +        myself is called by set_own_key without key generation.
   2.215 +        me->flags are ignored
   2.216 +        me->address must not be an alias
   2.217 +        me->fpr will be ignored and replaced by fpr.
   2.218 +        """
   2.219 +
   2.220 +    use hash fpr (in)                fingerprint of the key to mark as own key
   2.221 +    }
   2.222 +}
   2.223 +
     3.1 --- a/api/message_api.yml2	Tue Mar 05 13:59:00 2019 +0100
     3.2 +++ b/api/message_api.yml2	Wed Mar 27 17:11:24 2019 +0100
     3.3 @@ -243,27 +243,27 @@
     3.4  
     3.5          // flags
     3.6          
     3.7 -        decrypt_flags {
     3.8 -            decrypt_flag_own_private_key 0x1 
     3.9 +        flags {
    3.10 +            flag decrypt_flag_own_private_key 0x1 
    3.11              doc="""
    3.12                  private key was imported for one of our addresses (NOT trusted
    3.13                  or set to be used - handshake/trust is required for that)
    3.14                  """;
    3.15 -            decrypt_flag_consume 0x2 doc=’used by sync';
    3.16 -            decrypt_flag_ignore 0x4 doc=’used by sync';
    3.17 -            decrypt_flag_src_modified 0x8 
    3.18 +            flag decrypt_flag_consume 0x2 doc=’used by sync';
    3.19 +            flag decrypt_flag_ignore 0x4 doc=’used by sync';
    3.20 +            flag decrypt_flag_src_modified 0x8 
    3.21              doc="""
    3.22                  indicates that the src object has been modified. At the moment,
    3.23                  this is always as a direct result of the behaviour driven
    3.24                  by the input flags. This flag is the ONLY value that should be
    3.25                  relied upon to see if such changes have taken place.
    3.26                  """;
    3.27 -            decrypt_flag_untrusted_server 0x100 
    3.28 +            flag decrypt_flag_untrusted_server 0x100 
    3.29              doc="""
    3.30                  input flags. Used to signal that decrypt function should engage in behaviour
    3.31                  specified for when the server storing the source is untrusted.
    3.32                  """;
    3.33 -    }
    3.34 +        }
    3.35  
    3.36      // exceptions
    3.37      
    3.38 @@ -479,7 +479,7 @@
    3.39      throws record_not_found
    3.40          doc="if no trust record for user_id and fpr can be found"
    3.41      }
    3.42 -}    
    3.43 +}
    3.44  
    3.45  
    3.46  func color_from_rating
    3.47 @@ -493,7 +493,7 @@
    3.48      return color rating_color doc="color representing that rating"
    3.49  }
    3.50  
    3.51 -        
    3.52 +
    3.53  func get_binary_path
    3.54      doc="retrieve path of cryptotech binary if available"
    3.55  {
    3.56 @@ -508,24 +508,3 @@
    3.57          the library, do not change it!;
    3.58          """
    3.59  }
    3.60 -
    3.61 -
    3.62 -
    3.63 -
    3.64 -
    3.65 -    
    3.66 -
    3.67 -
    3.68 -
    3.69 -
    3.70 -
    3.71 -
    3.72 -
    3.73 -
    3.74 -
    3.75 -
    3.76 -
    3.77 -
    3.78 -
    3.79 -
    3.80 -
     4.1 --- a/api/pEp.yml2	Tue Mar 05 13:59:00 2019 +0100
     4.2 +++ b/api/pEp.yml2	Wed Mar 27 17:11:24 2019 +0100
     4.3 @@ -38,21 +38,14 @@
     4.4  decl throws @except;
     4.5  decl caveat(mode=caveat) alias doc;
     4.6  
     4.7 +
     4.8  // base types
     4.9  
    4.10  // string:  text
    4.11  // int:     integer number
    4.12  // blob:    Binary Large Object
    4.13  // size_t:  size in memory
    4.14 -// const:
    4.15 -// identity:
    4.16 -// message:
    4.17 -// rating:
    4.18 -// enc_format:
    4.19 -// hash:
    4.20 -// TID:
    4.21 -// bool:
    4.22 -// cryptotech:
    4.23 +// bool:    true or false
    4.24  
    4.25  
    4.26  // collections