From 756bbab9f0cc02274db072efbf07fda44d53ba80 Mon Sep 17 00:00:00 2001 From: Vyacheslav Gudkov Date: Wed, 24 May 2017 14:07:18 +0300 Subject: [PATCH 1/3] * Agent to agent API draft was created --- src/api/agent.rs | 179 +++++++++++++++++++++++++++++++++++++++++++++++ src/api/mod.rs | 1 + 2 files changed, 180 insertions(+) create mode 100644 src/api/agent.rs diff --git a/src/api/agent.rs b/src/api/agent.rs new file mode 100644 index 0000000..24162b3 --- /dev/null +++ b/src/api/agent.rs @@ -0,0 +1,179 @@ +extern crate libc; + +use api::ErrorCode; +use errors::ToErrorCode; +use commands::{Command, CommandExecutor}; +use utils::cstring::CStringUtils; + +use self::libc::c_char; + +/// Establishes agent to agent connection. +/// +/// Information about sender Identity must be saved in the wallet with sovrin_create_and_store_my_did +/// call before establishing of connection. +/// +/// Information about receiver Identity can be saved in the wallet with sovrin_store_their_did +/// call before establishing of connection. If there is no corresponded wallet record for receiver Identity +/// than this call will lookup Identity Ledger and cache this information in the wallet. +/// +/// Note that messages encryption/decryption will be performed automatically. +/// +/// #Params +/// command_handle: Command handle to map callback to caller context. +/// wallet_handle: Wallet handle (created by open_wallet). +/// sender_did: Id of sender Identity stored in secured Wallet. +/// receiver_did: Id of receiver Identity. +/// connection_cb: Callback that will be called after establishing of connection or on error. +/// message_cb: Callback that will be called on receiving of an incomming message. +/// +/// #Returns +/// Error code +/// connection_cb: +/// - xcommand_handle: command handle to map callback to caller context. +/// - err: Error code. +/// - connection_handle: Connection handle to use for messages sending and mapping of incomming messages to this connection. +/// message_cb: +/// - xconnection_handle: Connection handle. Indetnifies connection. +/// - err: Error code. +/// - message: Received message. +#[no_mangle] +pub extern fn sovrin_agent_connect(command_handle: i32, + wallet_handle: i32, + sender_did: *const c_char, + receiver_did: *const c_char, + connection_cb: Option, + message_cb: Option) -> ErrorCode { + unimplemented!() +} + +/// Starts listening of agent connections. +/// +/// On incomming connection listener performs wallet lookup to find corresponded receiver Identity +/// information. Information about receiver Identity must be saved in the wallet with +/// sovrin_create_and_store_my_did call before establishing of connection. +/// +/// Information about sender Identity for incomming connection validation can be saved in the wallet +/// with sovrin_store_their_did call before establishing of connection. If there is no corresponded +/// wallet record for sender Identity than listener will lookup Identity Ledger and cache this +/// information in the wallet. +/// +/// Note that messages encryption/decryption will be performed automatically. +/// +/// #Params +/// command_handle: command handle to map callback to caller context. +/// wallet_handle: wallet handle (created by open_wallet). +/// listener_cb: Callback that will be called after listening started or on error. +/// connection_cb: Callback that will be called after establishing of incomming connection. +/// message_cb: Callback that will be called on receiving of an incomming message. +/// +/// #Returns +/// Error code +/// listener_cb: +/// - xcommand_handle: command handle to map callback to caller context. +/// - err: Error code +/// - listener_handle: Listener handle to use for mapping of incomming connections to this listener. +/// connection_cb: +/// - xlistener_handle: Listener handle. Identifies listener. +/// - err: Error code +/// - connection_handle: Connection handle to use for messages sending and mapping of incomming messages to to this connection. +/// - sender_did: Id of sender Identity stored in secured Wallet. +/// - receiver_did: Id of receiver Identity. +/// message_cb: +/// - xconnection_handle: Connection handle. Indetnifies connection. +/// - err: Error code. +/// - message: Received message. +#[no_mangle] +pub extern fn sovrin_agent_listen(command_handle: i32, + wallet_handle: i32, + listener_cb: Option, + connection_cb: Option, + message_cb: Option) -> ErrorCode { + unimplemented!() +} + +/// Sends message to connected agent. +/// +/// Note that this call works for both incoming and outgoing connections. +/// Note that messages encryption/decryption will be performed automatically. +/// +/// #Params +/// command_handle: command handle to map callback to caller context. +/// connection_handle: Connection handle returned by sovrin_agent_connect or sovrin_agent_listen calls. +/// message: Message to send. +/// cb: Callback that will be called after message sent or on error. +/// +/// #Returns +/// err: Error code +/// cb: +/// - xcommand_handle: Command handle to map callback to caller context. +/// - err: Error code +/// +/// #Errors +#[no_mangle] +pub extern fn sovrin_agent_send(command_handle: i32, + connection_handle: i32, + message: *const c_char, + cb: Option) -> ErrorCode { + unimplemented!() +} + +/// Closes agent connection. +/// +/// Note that this call works for both incoming and outgoing connections. +/// +/// #Params +/// command_handle: command handle to map callback to caller context. +/// connection_handle: Connection handle returned by sovrin_agent_connect or sovrin_agent_listen calls. +/// cb: Callback that will be called after connection closed or on error. +/// +/// #Returns +/// Error code +/// cb: +/// - xcommand_handle: command handle to map callback to caller context. +/// - err: Error code +/// +/// #Errors +#[no_mangle] +pub extern fn sovrin_agent_close_connection(command_handle: i32, + connection_handle: i32, + cb: Option) -> ErrorCode { + unimplemented!() +} + +/// Closes listener and stops listening for agent connections. +/// +/// Note that all opened incomming connections will be closed automatically. +/// +/// #Params +/// command_handle: command handle to map callback to caller context. +/// listener_handle: Listener handle returned by sovrin_agent_listen call. +/// cb: Callback that will be called after listener closed or on error. +/// +/// #Returns +/// Error code +/// cb: +/// - xcommand_handle: command handle to map callback to caller context. +/// - err: Error code +/// +/// #Errors +#[no_mangle] +pub extern fn sovrin_agent_close_listener(command_handle: i32, + listener_handle: i32, + cb: Option) -> ErrorCode { + unimplemented!() +} \ No newline at end of file diff --git a/src/api/mod.rs b/src/api/mod.rs index 831f376..dd8b960 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -1,5 +1,6 @@ extern crate libc; +pub mod agent; pub mod anoncreds; pub mod signus; pub mod ledger; From 08aa2dbb2bc0d787a2b6acc9a26af4b7a19ef26c Mon Sep 17 00:00:00 2001 From: Vyacheslav Gudkov Date: Wed, 24 May 2017 16:31:31 +0300 Subject: [PATCH 2/3] * Added sequence diagram that illustrates Agent 2 Agent communication workflow --- doc/libsovrin-agent-2-agent.puml | 83 ++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 doc/libsovrin-agent-2-agent.puml diff --git a/doc/libsovrin-agent-2-agent.puml b/doc/libsovrin-agent-2-agent.puml new file mode 100644 index 0000000..7fc4a3e --- /dev/null +++ b/doc/libsovrin-agent-2-agent.puml @@ -0,0 +1,83 @@ +@startuml +skinparam ParticipantPadding 20 +skinparam BoxPadding 20 + +title Libsovrin Agent to Agent communucation API +scale 0.9 + +box "Sender Agent" #LightBlue +actor "Sender Agent" as SA +participant "Sender Libsovrin" as SL +participant "Sender Wallet" as SW +participant "Sender Socket" as SS +endbox + +box "Receiver Agent" #LightBlue +actor "Receiver Agent" as RA +participant "Receiver Libsovrin" as RL +participant "Receiver Wallet" as RW +participant "Receiver Socket" as RS +endbox + +participant "Ledger" as L + +=== Start listening == + +RA -> RL: 1. sovrin_create_and_store_my_did +RL -> RW: Store receiver keys + +RA -> RL: 2. sovrin_agent_listen +RL -> RS: Start listening +RL -> RA: Listener handle (cb) + +=== Establish connection == + +SA -> SL: 3. sovrin_create_and_store_my_did +SL -> SW: Store sender keys + +SA -> SL: 4. sovrin_agent_connect +SL -> SW: Get sender keys +SW -> SL: Sender keys +SL -> L: GET_NYM/GET_DDO +L -> SL: Receiver keys and endpoint +SL -> SW: Store receiver keys and endpoint + +SL -> SS: Receiver did, keys and endpoint. Sender did, keys +SS -> RS: init PairwiseCurveCP +RS -> RL: Sender keys and did (from connection) +RL -> L: GET_NYM/GET_DDO +L -> RL: Sender keys and did (from Ledger) +RL -> RS: Connection verified +RS -> SS: Conenction established +SS -> SL: Connection established +SL -> SA: Connection handle (cb) + +RS -> RL: Connection established +RL -> RA: Connection handle (cb) + +=== Exchange messages == + +SA -> SL: 4. sovrin_agent_send +SL -> SS: Message +SS -> RS: Message +RS -> RL: Message +RL -> RA: Message (cb) + +RA -> RL: 5. sovrin_agent_send +RL -> RS: Message +RS -> SS: Message +SS -> SL: Message +SL -> SA: Message (cb) + +=== Clean up == + +SA -> SL: 5. sovrin_agent_close_connection +SL -> SS: Close socket + +RA -> RL: 5. sovrin_agent_close_listener +RL -> RS: Close socket + + + + +@enduml From e24c87b6b7e5edeca4527f6644e14606455226a4 Mon Sep 17 00:00:00 2001 From: Vyacheslav Gudkov Date: Wed, 24 May 2017 18:40:49 +0300 Subject: [PATCH 3/3] * More detailed messages flow for connection establishing procedure --- doc/libsovrin-agent-2-agent.puml | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/doc/libsovrin-agent-2-agent.puml b/doc/libsovrin-agent-2-agent.puml index 7fc4a3e..27d6520 100644 --- a/doc/libsovrin-agent-2-agent.puml +++ b/doc/libsovrin-agent-2-agent.puml @@ -43,16 +43,29 @@ L -> SL: Receiver keys and endpoint SL -> SW: Store receiver keys and endpoint SL -> SS: Receiver did, keys and endpoint. Sender did, keys -SS -> RS: init PairwiseCurveCP -RS -> RL: Sender keys and did (from connection) + +SS -> RS: PairwiseCurveCP Hello message +RS -> RL: Keys lookup request +RL -> RW: Get keys and did for request +RW -> RL: Receiver keys and did +RL -> RS: Receiver keys +RS -> SS: PairwiseCurveCP Welcome message + +SS -> RS: Next PairwiseCurveCP handshake messages +RS -> SS: PairwiseCurveCP handshake messages answers + +SS -> SL: PairwiseCurveCP connection established + +SL -> SS: DID message +SS -> RS: DID message +RS -> RL: Sender did and public key RL -> L: GET_NYM/GET_DDO L -> RL: Sender keys and did (from Ledger) -RL -> RS: Connection verified -RS -> SS: Conenction established -SS -> SL: Connection established +RL -> RL: Connection verification +RL -> RS: DID message answer +RS -> SS: DID message answer +SS -> SL: DID message answer SL -> SA: Connection handle (cb) - -RS -> RL: Connection established RL -> RA: Connection handle (cb) === Exchange messages ==