identity.rst (5558B)
1 2 .. index:: 3 double: IDENTITY; subsystem 4 5 .. _IDENTITY-Subsystem-Dev: 6 7 IDENTITY 8 ======== 9 10 .. _Connecting-to-the-identity-service: 11 12 Connecting to the service 13 ^^^^^^^^^^^^^^^^^^^^^^^^^ 14 15 First, typical clients connect to the identity service using 16 ``GNUNET_IDENTITY_connect``. This function takes a callback as a 17 parameter. If the given callback parameter is non-null, it will be 18 invoked to notify the application about the current state of the 19 identities in the system. 20 21 - First, it will be invoked on all known egos at the time of the 22 connection. For each ego, a handle to the ego and the user's name for 23 the ego will be passed to the callback. Furthermore, a ``void **`` 24 context argument will be provided which gives the client the 25 opportunity to associate some state with the ego. 26 27 - Second, the callback will be invoked with NULL for the ego, the name 28 and the context. This signals that the (initial) iteration over all 29 egos has completed. 30 31 - Then, the callback will be invoked whenever something changes about 32 an ego. If an ego is renamed, the callback is invoked with the ego 33 handle of the ego that was renamed, and the new name. If an ego is 34 deleted, the callback is invoked with the ego handle and a name of 35 NULL. In the deletion case, the application should also release 36 resources stored in the context. 37 38 - When the application destroys the connection to the identity service 39 using ``GNUNET_IDENTITY_disconnect``, the callback is again invoked 40 with the ego and a name of NULL (equivalent to deletion of the egos). 41 This should again be used to clean up the per-ego context. 42 43 The ego handle passed to the callback remains valid until the callback 44 is invoked with a name of NULL, so it is safe to store a reference to 45 the ego's handle. 46 47 .. _Operations-on-Egos: 48 49 Operations on Egos 50 ^^^^^^^^^^^^^^^^^^ 51 52 Given an ego handle, the main operations are to get its associated 53 private key using ``GNUNET_IDENTITY_ego_get_private_key`` or its 54 associated public key using ``GNUNET_IDENTITY_ego_get_public_key``. 55 56 The other operations on egos are pretty straightforward. Using 57 ``GNUNET_IDENTITY_create``, an application can request the creation of 58 an ego by specifying the desired name. The operation will fail if that 59 name is already in use. Using ``GNUNET_IDENTITY_rename`` the name of an 60 existing ego can be changed. Finally, egos can be deleted using 61 ``GNUNET_IDENTITY_delete``. All of these operations will trigger updates 62 to the callback given to the ``GNUNET_IDENTITY_connect`` function of all 63 applications that are connected with the identity service at the time. 64 ``GNUNET_IDENTITY_cancel`` can be used to cancel the operations before 65 the respective continuations would be called. It is not guaranteed that 66 the operation will not be completed anyway, only the continuation will 67 no longer be called. 68 69 .. _The-anonymous-Ego: 70 71 The anonymous Ego 72 ^^^^^^^^^^^^^^^^^ 73 74 A special way to obtain an ego handle is to call 75 ``GNUNET_IDENTITY_ego_get_anonymous``, which returns an ego for the 76 \"anonymous\" user --- anyone knows and can get the private key for this 77 user, so it is suitable for operations that are supposed to be anonymous 78 but require signatures (for example, to avoid a special path in the 79 code). The anonymous ego is always valid and accessing it does not 80 require a connection to the identity service. 81 82 .. _Convenience-API-to-lookup-a-single-ego: 83 84 Convenience API to lookup a single ego 85 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 86 87 As applications commonly simply have to lookup a single ego, there is a 88 convenience API to do just that. Use ``GNUNET_IDENTITY_ego_lookup`` to 89 lookup a single ego by name. Note that this is the user's name for the 90 ego, not the service function. The resulting ego will be returned via a 91 callback and will only be valid during that callback. The operation can 92 be canceled via ``GNUNET_IDENTITY_ego_lookup_cancel`` (cancellation is 93 only legal before the callback is invoked). 94 95 .. _The-IDENTITY-Client_002dService-Protocol: 96 97 The IDENTITY Client-Service Protocol 98 ------------------------------------ 99 100 A client connecting to the identity service first sends a message with 101 type ``GNUNET_MESSAGE_TYPE_IDENTITY_START`` to the service. After that, 102 the client will receive information about changes to the egos by 103 receiving messages of type ``GNUNET_MESSAGE_TYPE_IDENTITY_UPDATE``. 104 Those messages contain the private key of the ego and the user's name of 105 the ego (or zero bytes for the name to indicate that the ego was 106 deleted). A special bit ``end_of_list`` is used to indicate the end of 107 the initial iteration over the identity service's egos. 108 109 The client can trigger changes to the egos by sending ``CREATE``, 110 ``RENAME`` or ``DELETE`` messages. The CREATE message contains the 111 private key and the desired name. The RENAME message contains the old 112 name and the new name. The DELETE message only needs to include the name 113 of the ego to delete. The service responds to each of these messages 114 with a ``RESULT_CODE`` message which indicates success or error of the 115 operation, and possibly a human-readable error message. 116 117 Finally, the client can bind the name of a service function to an ego by 118 sending a ``SET_DEFAULT`` message with the name of the service function 119 and the private key of the ego. Such bindings can then be resolved using 120 a ``GET_DEFAULT`` message, which includes the name of the service 121 function. The identity service will respond to a GET_DEFAULT request 122 with a SET_DEFAULT message containing the respective information, or 123 with a RESULT_CODE to indicate an error. 124 125