Agent to agent communication API draft

doc/libsovrin-agent-2-agent.puml

@@ -0,0 +1,96 @@
+@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: <b>1. sovrin_create_and_store_my_did
+RL -> RW: Store receiver keys
+
+RA -> RL: <b>2. sovrin_agent_listen
+RL -> RS: Start listening
+RL -> RA: Listener handle (cb)
+
+=== Establish connection ==
+
+SA -> SL: <b>3. sovrin_create_and_store_my_did
+SL -> SW: Store sender keys
+
+SA -> SL: <b>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: 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 -> RL: Connection verification
+RL -> RS: DID message answer
+RS -> SS: DID message answer
+SS -> SL: DID message answer
+SL -> SA: Connection handle (cb)
+RL -> RA: Connection handle (cb)
+
+=== Exchange messages ==
+
+SA -> SL: <b>4. sovrin_agent_send
+SL -> SS: Message
+SS -> RS: Message
+RS -> RL: Message
+RL -> RA: Message (cb)
+
+RA -> RL: <b>5. sovrin_agent_send
+RL -> RS: Message
+RS -> SS: Message
+SS -> SL: Message
+SL -> SA: Message (cb)
+
+=== Clean up ==
+
+SA -> SL:  <b>5. sovrin_agent_close_connection
+SL -> SS: Close socket
+
+RA -> RL: <b>5. sovrin_agent_close_listener
+RL -> RS: Close socket
+
+
+
+
+@enduml

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<extern fn(xcommand_handle: i32,
+                                                                   err: ErrorCode,
+                                                                   connection_handle: i32)>,
+                                   message_cb: Option<extern fn(xconnection_handle: i32,
+                                                                err: ErrorCode,
+                                                                message: *const c_char)>) -> 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<extern fn(xcommand_handle: i32,
+                                                                err: ErrorCode,
+                                                                listener_handle: i32)>,
+                                  connection_cb: Option<extern fn(xlistener_handle: i32,
+                                                                  err: ErrorCode,
+                                                                  connection_handle: i32,
+                                                                  sender_did: *const c_char,
+                                                                  receiver_did: *const c_char)>,
+                                  message_cb: Option<extern fn(xconnection_handle: i32,
+                                                               err: ErrorCode,
+                                                               message: *const c_char)>) -> 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<extern fn(xcommand_handle: i32,
+                                                     err: ErrorCode)>) -> 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<extern fn(xcommand_handle: i32,
+                                                                 err: ErrorCode)>) -> 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<extern fn(xcommand_handle: i32,
+                                                                 err: ErrorCode)>) -> ErrorCode {
+    unimplemented!()
+}

src/api/mod.rs

@@ -1,5 +1,6 @@
 extern crate libc;
 
+pub mod agent;
 pub mod anoncreds;
 pub mod signus;
 pub mod ledger;