1 Connection manager and result acceptance handlers/callbacks
4 Peer state tracing / changes notifications
6 NAT traversal - Direct communication tunnel creation between peers
8 Security, key exchange and data encryption/decryption
9 Add firewall exception for your application in application installer
To use quickP2P with your .NET(or Mono) project you first need to add a reference to quickP2Plib. Then include it in the class file where you need to use it and that's pretty much all. QuickP2Plib .NET works both with x86/x64 so you don't need to worry about that regarding this particular library. If you use Mono you need Mono build for the particular platform.
1 Connection manager and result acceptance handlers/callbacks
ConnectionManager is the main object you use with API. All client operations are initiated using methods in this class with exception of virtual index manager which is a subobject of ConnectionManager(ConnnectionManager.VNIndexManager).
quickP2P API is based on the asynchronous model. You initiate operation by making a request and you wait for the result in the event handler or provided the callback. For most of the requests, there is an option to choose between event handler and callback to handle response depending what you want to do or what you prefer.
This would be the comparison of using events and callbacks.
1.1 Event handlers
- When you hook event once, it will execute response every time correspondent request arrives until you unhook it.
- If you have both events hooked and callback provided to execute on the request completion first event is triggered then the callback
- quickP2P will execute event handlers on UI thread (if UI thread available). This makes easy for you to interact with visual elements directly from handler method. But that also creates one dangerous situation if you start long running an operation like large file transfer or video transfer in handler method your application UI may block. So, in this case, create a new thread to run that. That would be the best option. Or place something like Application.doEvents() inside the long-running loop if you need "on-fly" solution. To demonstrate that, we will turn again to demo project provided with the application. See Form1.cs
In some moment we initiate tunnel creation to another peer:
....
//we found peer we will connect to now. Note that track_connect_transaction_uid will match TransactionUID argument in [void cm_onPeerConnect(...]
Guid track_connect_transaction_uid =
cm.Connect(FoundPeers.First(), ConnectionType.TCP);//NEXT WE WAIT FOR RESULT IN HANDLER [void cm_onPeerConnect(...] AND ON OTHER SIDE [void cm_onPeerAccepted(...] will trigger instead
....
When operation finishes with success, this handler will be triggered:
....
//After successful connect operation this handler is triggered
void cm_onPeerConnect(Peer Peer, Guid TransactionUID)
{
//TUNNEL IS CREATED!
//Peer.Socket is System.Net.Sockets.Socket object!
//EVENTS ARE RAISED ON UI THREAD MAKING EASIER FOR YOU TO INTERACT DIRECTLY WITH UI FROM HANDLER BODY
//BUT THAT HAS SIDE EFFECT THAT LONG RUNNING OPERATIONS COULD BLOCK UI SO WE EXECUTE THEM IN SEPARATE THREAD
Thread t = new Thread(new ParameterizedThreadStart(delegate(object state)
{
var FS = System.IO.File.OpenRead(FileToSend);//we open file for reading
Peer.Socket.Send(BitConverter.GetBytes(FS.Length));//we send file length first
//we read and send file blocks
byte[] buff = new byte[8192];
int read = 0;
while ((read = FS.Read(buff, 0, buff.Length)) > 0)
Peer.Socket.Send(buff, 0, read, System.Net.Sockets.SocketFlags.None);
FS.Close();
//we wait for some response as confirmation
read = Peer.Socket.Receive(buff);
if (read > 0)
showMessageFromUIThread("File Sent!");
//we close socket
Peer.Socket.Close();
}));
t.Start();
}
....
So you see we have created a new thread to run file transfer in anonymous thread method leaving UI thread to do its job. Note that for showing message box on file transfer completion we did not just call MessageBox.Show("....."). Instead we called showMessageFromUIThread("File Sent!");. For file transfer, we created a separate thread. But when we finished and wanted to show message box which is a visual element we needed to make sure that message box is executed for UI thread. So that method looks like this:
delegate void showMessageFromUIThreadDelegate(string message);
public void showMessageFromUIThread(string message) {
if (this.InvokeRequired){
showMessageFromUIThreadDelegate bmd = new showMessageFromUIThreadDelegate(showMessageFromUIThread);
this.Invoke(bmd, new object[] { message });//we this invoke method on UI thread
}else //we are now in UI thread
MessageBox.Show(message);
}
1.2 Callbacks
Callbacks are usually provided as optional arguments to request invoking methods. They are executed on request completion only once .
Callback is executed from "some" thread that accepted request respons. Watch for that when interacting with UI elements.
Callbacks are handy because they provide you a way to concentrate request and response handler execution code in one place. So, they are good for things like connect operation. You don't need to distinguish from which request response came back using Transaction UID . If your application is multi-purpose let's say transfers files and enables video chat and you want to have two connections to the same peer at once and you use event handler:
....
cm.onPeerConnect += new ConnectionManager.PeerConnect(cm_onPeerConnect);
Guid track_file_transaction_uid;
Guid track_video_transaction_uid;
....
track_file_transaction_uid =
cm.Connect(PeerToConnectTo, ConnectionType.TCP);
....
....
track_video_transaction_uid =
cm.Connect(PeerToConnectTo, ConnectionType.TCP);
....
void cm_onPeerConnect(Peer PeerConnectedTo, Guid TransactionUID)
{
if (TransactionUID == track_file_transaction_uid){
//do file transfer
}
else if (TransactionUID == track_video_transaction_uid) {
//do video transfer
}
}
....
So we had to check if tunnel creation was for file or video by comparing UIDs. The same thing with callback would look like this:
Guid track_file_transaction_uid;
Guid track_video_transaction_uid;
track_file_transaction_uid =
cm.Connect(PeerToConnectTo, ConnectionType.TCP, callback: new ConnectionManager.PeerConnectCallback(delegate(Peer PeerConnectedTo, Guid PeerCheckpointUID, Guid PeerUID, Guid TransactionUID,bool Success, quickP2PLib.ConnectionManager.PeerConnectFailureReason FailReason) {
//do file transfer
}));
track_video_transaction_uid =
cm.Connect(PeerToConnectTo, ConnectionType.TCP, callback: new ConnectionManager.PeerConnectCallback(delegate(Peer PeerConnectedTo, Guid PeerCheckpointUID, Guid PeerUID, Guid TransactionUID,bool Success, quickP2PLib.ConnectionManager.PeerConnectFailureReason FailReason) {
//do video transfer
}));
Here is for example ConnectionManger.Open request with the provided callback to execute:
.........
ConnectionManager cm = new ConnectionManager(new IPEndPoint(checkpoint_address,
checkpoint_port));
.........
cm.Open(new ConnectionManager.SessionOpenCallback(delegate(ConnectionManager sender, bool success, ConnectionManager.SessionFailReason Failreason) {
//I'm an anonymous callback handler method
if (success)
showMessageFromUIThread("From callback: Session opened first time");
else
showMessageFromUIThread("From callback: Session open failed because of this reason:" + Failreason.ToString());
}));
.........
Unlike event provided callback is executed once. So in this particular case, if ConnectionManager is set to automatically recreate session in case of temporal loss of connection with super-node (default behavior - for example, you lost internet connection for some time), the callback would not trigger on session re-establishment but event handler would.
The equivalent thing done with events looks like this:
.........
ConnectionManager cm = new ConnectionManager(new IPEndPoint(checkpoint_address,
checkpoint_port));
//raised when we connect to checkpoint, or session automatically recovers after downtime (example you drive your laptop through underground tunnel and you have wifi connection)
cm.onSessionOpenSuccess += new ConnectionManager.SessionOpenSuccess(cm_onSessionOpenSuccess);
//raised when we try to connect to checkpoint, but session creation fails because of some reason
cm.onSessionOpenFailure += new ConnectionManager.SessionOpenFailure(cm_onSessionOpenFailure);
.........
void cm_onSessionOpenSuccess(ConnectionManager ConnectionManager)
{//we have successfully registered peer in supernode network!
MessageBox.Show("From event handler: Session opened first time or re-established");
}
void cm_onSessionOpenFailure(ConnectionManager ConnectionManager, ConnectionManager.SessionFailReason Reason)
{//something went wrong
MessageBox.Show("From event handler: Session open failed because of this reason:" + Reason.ToString());
}
.........
2 Peer session creation
For quickP2P client, to be able to do any operation like tunnel opening, sending an instant message, searching peers ... we first need to join an abstract peer-to-peer network like you connect to the internet when your computer powers up. Steps for joining application peer to the super-node network would be this:
1 - Create ConnectionManager object to handle operations, set required C.M. properties, handles...
It's always required to set access tokens:
cm.setAccessTokens(Guid.Parse("00000000-XXXX-XXXX-XXXX-XXXXXXXXXXXX"), Guid.Parse("00000000-XXXX-XXXX-XXXX-XXXXXXXXXXXX"), "");
First argument is provider UID , second application UID , third is access key. You can see this values in you provider portal.
2 - Set some meta-data so other peers can find us and we can find them by filtering values
cm.LocalPeer["some_meta"] = "bla bla bla";
cm.LocalPeer["email"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";
cm.LocalPeer["gender"] = "male";
you can also alter these properties later after session open, you need to call
cm.BrodcastStateChange() to update local peer information on network.
3-Initate ConnectionManager.Open to open session
4- Wait for open session completion handler to execute
(note, after session open completion avoid initiating connect - "tunnel open" operation in next 2-3 sec to give time to API to inspect your network environment properly)
The actual code for the session open is in an example from the previous section.
Once we have established the session with super-node we can:
- Query for other peers on network (Peer lookup) with mongo db-like queries in our application scope
- Register for peers’ status tracking and receive notifications about changes
- Send/Receive instant messages
- Open communication tunnels to other peers and other peers can open tunnels to us
- Use virtual index manager if we need it:
- Create|Delete|Edit Virtual Networks|Users
- Search virtual networks|users with mongo DB like queries
- Join|Un-join users to networks
....
We will talk about all of these operations in following texts
3 Peer lookup queries
Peer lookup queries to query for peers that are currently online. The query request is initiated using
Guid QueryTransactionID = cm.Query(string QueryText, PeerQueryCompleted Callback = null, int page = 0, int pageLimit = 64)
or handy overload if we need to check single peer:
Guid QueryTransactionID = cm.Query(Guid PeerUID, PeerQueryCompleted Callback = null)
methods of a ConnectionManager object. Callback and event handler method has in-print like this:
delegate void PeerQueryCompleted(List<Peer> FoundPeers, bool Completed, Guid QueryTransactionID, int Page, int PageLimit, int TotalPeers)
method arguments:
FoundPeers: List of peers returned by query
Completed: If completed then true, not that sometimes result will contain pees but this value will be false. This can happen for example if 10.000.000 peers are found by search criteria and operation timeout expires before all results are collected
QueryTransactionID: Transaction ID of query request
Page: Page returned if pagination exists
PageLimit: Number of peers per page if pagination exists
TotalPeers: Total number of peers matched by query
Event hook example:
cm.onPeerQueryResponse += new ConnectionManager.PeerQueryCompleted(cm_onPeerQueryResponse);
Query text format is mongo DB like a query with the exception that you don't put opening and closing brackets.
Let's say we defined some meta properties for our peer like this:
cm.LocalPeer["City"] = "Palo Alto";
cm.LocalPeer["Sex"] = "female";
cm.LocalPeer["Email"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";
cm.LocalPeer["Age"] = "31";
Here are some examples of queries that will include this peer in result:
Find peer with email "This email address is being protected from spambots. You need JavaScript enabled to view it." that is currently online :
cm.Query("\"Properties.Email\":\"This email address is being protected from spambots. You need JavaScript enabled to view it.\"") ;
Find peers with email contained in this list [This email address is being protected from spambots. You need JavaScript enabled to view it., This email address is being protected from spambots. You need JavaScript enabled to view it., This email address is being protected from spambots. You need JavaScript enabled to view it.] that are currently online:
cm.Query("\"Properties.Email\":{$in:[\"This email address is being protected from spambots. You need JavaScript enabled to view it. \",\"This email address is being protected from spambots. You need JavaScript enabled to view it. \",\"This email address is being protected from spambots. You need JavaScript enabled to view it.\"]}") ;
Find female peers form Palo Alto that are currently online:
cm.Query("\"Properties.City \":\"Palo Alto\", \"Properties.Sex\":\"female\"") ;
Find female peers form Palo Alto with above 30 that are currently online:
cm.Query("\"Properties.City \":\"Palo Alto\", \"Properties.Sex\":\"female\", \"Properties.Age\":{$gt:30}") ;
You can test your queries on provider portal.
4 Peer state tracing / changes notifications
There is often a need for some peer to have some state on the network like away, busy, available... You probably saw that as a common feature of chat applications. If you think you could achieve the same functionality using Instant messages or something else, you are right. But this provides you a more elegant way of transferring such information to peers instantly. Also, there are certain situations when this comes handy as an irreplaceable feature. Imagine you have some chat like application and you keep your peer buddies in some list or dictionary... your buddy kid rips power cables from his computer so his application
doesn't manage to notify you that he is offline. Super-node will notice that in max 90sec, and if you registered for that peer state tracking you will get the notification that he is offline.
To use this feature you need to hook event to accept notifications:
cm.onPeerStateChanged += new ConnectionManager.PeerStateChanged(cm_onPeerStateChanged);
.....
void cm_onPeerStateChanged(Peer Peer, uint State)
{
//do something
}
This is a rare case where you don't have the option to use callback because you never know when notification will come.
Also, you have to inform super-nodes that you want to be notified about that peer changes. You do that using following ConnectionManager functions:
cm.RegisterStateTracking
method having 4 overloads. Commonplace to place RegisterStateTrackingmethod is in a body of peer query response handler because that is a moment when you get fresh information of who is online. If peer goes offline you will get Peer.DisconnectedState (0) state argument value. If he comes back he needs to inform you that he is back online and you again need to register for its state tracking again. So status track is valid until peer goes offline, if he comes back you need to register state tracking again. Also, you see there is a need to combine instant messages with this to make it fully usable, why:
- You do peer query and you get fresh information about online peers. But after 30 sec some peer that should be visible to you by application terms appears on the network. You don't know that he is online in that moment and you would not know that he is online until you do peer query again. But he also does peer query and he knows you are online so all he has to do is to inform you about that. He can do that by simply sending you some instant message.
cm.SendInstantMessage(YourPeer,"some text - not nessery",YourApplicationMessagesEnum.IM_ONLINE);
void cm_onReceiveInstantMessage(Guid FromPeer, Guid FromPeerCheckpoint, Guid MessageGUID, int MessageType, byte[] Data)
{
if(MessageType == (int) YourApplicationMessagesEnum.IM_ONLINE){
//update your list or do query to check all again
}else....
}
We will talk about instant messages later so you could fully understand this code.
In state changed notification handler: cm_onPeerStateChanged(Peer Peer, uint State)you see two arguments Peer and State. First is complete fresh peer object of peer whose state changed and State is a new state of that peer. You notice it is unsigned int value so you are free to use any value in range from 2 to uint.MAX for your application.
Values 0 and 1 are reserved for
Peer.DisconnectedState = 0;
Peer.AuthentificatedState = 1;
The system depends on them so you cannot use these values for anything else.
To notify other peers about your state change code would be something like this:
- for example, you are now busy
cm.LocalPeer.State = (uint)MyApplicationPeerStateEnums.BUSY;
cm.BrodcastStateChange();
So we use cm.BrodcastStateChange(); to inform others of our state changes. This function also updates our peer object information on super-node so we also use it when we change meta properties while the session is active.
You don't need to do state broadcast when you are closing session/disposing C.M. because ConnectionManager will do that automatically.
5 Instant messages
Instant messages are carried using super-nodes. Their purpose is to transfer short messages between peers in the network. Often it is not practical to always open direct communication channel between two peers if one needs to inform other about something. It is because tunnel creation takes 1-15s and also maybe we want first another peer to confirm that he willingly accepts that connection. These are commonly some control messages from your application or something like chat messages.
To be able to receive them you need to hook following event handler:
cm.onReceiveInstantMessage += new ConnectionManager.ReceiveInstantMessage(cm_onReceiveInstantMessage);
.....
void cm_onReceiveInstantMessage(Guid FromPeer, Guid FromPeerCheckpoint, Guid MessageGUID, int MessageType, byte[] Data)
{
if (MessageType == (int)YourApplicationMessagesEnum.TextMessage) {
//do something
}
else if (MessageType == (int)YourApplicationMessagesEnum.IM_ONLINE) {
//do something
}
else if (MessageType == (int)YourApplicationMessagesEnum.ALOW_FILE_TRANSFER){
//do something
}...
}
To send an instant message you use one of 4 overloads of cm.SendInstantMessage function:
public Guid SendInstantMessage(Guid RemotePeerCheckpointUID, Guid RemotePeerUID, byte[] messageBytes, int InstantMessageType = 0, SendInstantMessageComplete Callback = null)
public Guid SendInstantMessage(Guid RemotePeerCheckpointUID, Guid RemotePeerUID, string Message, int InstantMessageType = 0, SendInstantMessageComplete Callback = null)
public Guid SendInstantMessage(Peer Peer, byte[] messageBytes, int InstantMessageType = 0, SendInstantMessageComplete Callback = null)
public Guid SendInstantMessage(Peer Peer, string Message, int InstantMessageType = 0, SendInstantMessageComplete Callback = null)
Example of sending instant message request:
cm.SendInstantMessage(OtherPeer,"Hi man!",YourApplicationMessagesEnum.TextMessage);
You notice all have an optional argument to InstantMessageTypeused to distinguish them. for example, you have a number of control messages and text messages so this gives you an easy way to distinguish them.
You also notice there is callback argument. That callback will trigger when the message is delivered to your super-node. It does not mean it is delivered to another peer when callback triggers. The message will travel to destination peer super-node and then it will be delivered to it.
6 Direct communication tunnel creation between peers
The main API feature and probably the main reason why you use it is the ability to create direct communication channels between two computers that are both behind NAT (router) devices using NAT traversal techniques. The main advantage of this API is that as a result you will get standard platform socket to use from then on. The system will self-inspect what is the best method of tunnel criterion between two peers and create it. So you don't need to know anything about STUN, NAT port mapping prediction, UPnP, NAT PMP, PCP... or anything else that happens in the background and just wait for your prepared socket.
(Note - special situations when both peers are on the same local network or even on the same computer are handled by API. Data will be transferred locally and not going over the Internet) .
In past texts, we talked about how to find some peer. When you know that, and you want to open direct communication channel you initiate connect request. On the other side, the peer needs to accept this request so handshake procedure could start.
You need this two event handlers:
//When we make connect request (tunnel creation) we wait for operation completion to trigger event
cm.onPeerConnect += new ConnectionManager.PeerConnect(cm_onPeerConnect);
//When some other peer initiate tunnel creation to us, operation completion will trigger event
cm.onPeerAccepted += new ConnectionManager.PeerAccept(cm_onPeerAccepted);
.....
//After successful connect operation this handler is triggered
void cm_onPeerConnect(Peer Peer, Guid TransactionUID)
{
// Peer.Socket is tunneled socket ready for data transfer
Peer.Socket.Send(Encoding.UTF8.GetBytes("Hello through tunnel!"));
//do something else
}
.....
//THIS WILL TRIGGER WHEN OTHER SIDE CALL cm.connect(... TARGETING LOCAL PEER
void cm_onPeerAccepted(Peer Peer, Guid TransactionUID)
{
// Peer.Socket is tunneled socket ready for data transfer
byte[] buff = new byte[8192];
Peer.Socket.Receive(buff);
Peer.Socket.Send(Encoding.UTF8.GetBytes("Hello through tunnel to you to!"));
//do something else
}
One peer initiates connect request that would in this case use event handlers that look like this:
Guid track_connect_transaction_uid =
cm.Connect(OtherPeer, ConnectionType.TCP);
and on completion void cm_onPeerConnect(Peer Peer, Guid TransactionUID)would trigger on his side. On other side voie void cm_onPeerAccepted(Peer Peer, Guid TransactionUID) would trigger.
On a side of peer accepting connection if you need to control access - how it can connect and how it cannot, you can override cm.AcceptPeerConnectionReslover
cm.AcceptPeerConnectionReslover = delegate (Peer formPeer, ConnectionType ConnType)
{
if(???your condition to accept tunnel creation???)
return true;
else
return true;
};
By default, all connection request will be accepted unless you set cm.BlockIncoming = true;
Same thing using callbacks would look like this:
cm.PeerAccepted = delegate(Peer Peer, Guid PeerCheckpointUID, Guid PeerUID, Guid TransactionUID, bool Success, ConnectionManager.PeerConnectFailureReason FailReason)
{
if(sucess){
//Peer.Socket is tunneled socket ready for data transfer
byte[] buff = new byte[8192];
Peer.Socket.Receive(buff);
Peer.Socket.Send(Encoding.UTF8.GetBytes("Hello through tunnel to you to!"));
//do something ...
} else){
//do something ...
}
};
track_transaction_uid =
cm.Connect(PeerToConnectTo, ConnectionType.TCP, callback: new ConnectionManager.PeerConnectCallback(delegate(Peer PeerConnectedTo, Guid PeerCheckpointUID, Guid PeerUID, Guid TransactionUID ,bool Success, quickP2PLib.ConnectionManager.PeerConnectFailureReason FailReason) {
if(sucess){
//Peer.Socket is tunneled socket ready for data transfer
Peer.Socket.Send(Encoding.UTF8.GetBytes("Hello through tunnel!"));
//do something ...
} else){
//do something ...
}
}));
Note that events handles are executed in UI thread if found so starting long-running operations can block UI so read under: "Connection manager and result acceptance handlers/callbacks " text on how to handle that if you haven't done so already.
There is nothing special we need to talk about this, you have a ready socket so you do what you want with it from then on. Just have in mind that you are responsible for the socket from then on, so you need to close it when you no longer need it. Also as a good practice to follow is that you can just save that socket when you finish the task for new use if needed. So if you need do new task involving data transfer with that same peer, you can just pool out that socket, instead of invoking tunnel creation again (1-15sec). You can destroy such socket when you leave application or if that peer goes offline.
7 Using virtual index storage
Since quickP2P system goal is to provide you complete environment so you could focus just on the application, we introduced permanent index storage sub-system. We figured out that it would be convenient to provide a way to store and be able to search some commonly used things like user registration data that is more closely aware of peers. You don't need to use this sub-system if you have your own in mind. You would just need some key you would store in peer properties to associate peers with your objects later.
You can imagine index system as a remote database with two tables User and Network. Of course, these are not ordinary tables that have fixed columns. You can store whatever property (name, value) you need and later search them. Besides common operations like SELECT/INSERT/UPDATE/DELETE, the most important is that User object is aware which peers are authenticated with it. Multiple peers can be authenticated with single user object and also open peer can be authenticated with multiple user objects. Both user and network object have UID and custom property bag. Constraints are that User object must have "Username" property and Network object needs to have "Name" property. There cannot be two User objects with the same username in your application scope and same stands for a name for networks. If you somehow need to enable different situation for some reason, you can generate these properties in some special way based on some other property.
The user object has columns "Member of networks" because you can join/un-join some user from the network and "Currently bound Peers" which holds a list of currently bound peer UIDs. User object also has password property you cannot see in provider portal.
An object used for virtual index management is cm.VNIndexManager. All index operations complete synchronously because there are no critical time-dependent functions. If you need asynchronous execution you need to implement it. Also if there is something wrong exception is thrown.
This is a list of all Virtual index manager operations:
public VUser SaveUser(VUser user,string user_password = "")
- Inserts or updates virtual user. You pass user object you want to save and save it providing a password for that user. If VUser UID property is 00000000-0000-0000-0000-000000000000 system will do INSERT otherwise it will do UPDATE. The result of the operation is fresh User object like on index server at that moment. This also meant PeerUIDS property will have a fresh list of authenticated peers. So if UID was empty UID will get some real value from the server after the operation completes.
This would be code to create a new user:
VUser newUser = new VUser();
newUser.Username = "some_username";//THIS IS REQUIRED, IT IS ALIAS FOR newUser["username"]
newUser["name"] = "Mike";
newUser["email"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";
newUser = cm.VNIndexManager.SaveUser(newUser, "somepassword");
if (newUser.UID != Guid.Empty) {
Console.WriteLine("User is saved , assigned UID is:" + newUser.UID.ToString());
}
then update operation would be:
newUser["name"] = "Mike2";
newUser = cm.VNIndexManager.SaveUser(newUser, "somepassword");
Note that after this operation, in case of creating a new user, PeerUIDS property will be empty. Peer need to call in AuthenticateUser method in order to have his UID appearing on this list.
public VUser AuthenticateUser(string Username, string Password)
- Checks for existing username with a password, and if it exists adds pees peer UID to VUser PeerUIDSlist, then returns VUser object.
VUser u;
...
u = cm.VNIndexManager.AuthenticateUser("some_username", "somepassword");
If you perform AuthenticateUser aser is already authenticated that is not a bad operation. It will not have side effects and you can use it to get a fresh VUser object from index server.
public List<VUser> QueryUsers(string QueryCommandText, int skip = 0, int limit = 0, string ascOrderBy = null, string descOrderBy = null)
- Searches for VUsers matching query, then returns a list of found VUsers to a requester
List<VUser> users = cm.VNIndexManager.QueryUsers("\"Properties.City\":\"Palo Alto\"");
If you expect large number of objects to be returned consider using pagination. In last two optional parameters you enter comma separated property names .
public long QueryUsersCount(string QueryCommandText)
- Searches for VUsers matching a query, then returns a number of objects found
public void DeleteUser(Guid userToDeleteUID)
- Deletes VUser object having exact UID:
cm.VNIndexManager.DeleteUser(u.UID);
public void ChangeUserPassword(Guid userUID, string old_password, string new_password)
- Changes VUser object password. Passwords are not visible to anyone. In case that user forgets a password and wants to reset it, you need to use magic value:
(requesterPeerUID.ToString() + ApplicationUID.ToString() + userUID.ToString()).ToLower()
for old password to be able to reset it.
public void JoinUserToNetwork(Guid userUID , Guid networkUID)
- Updates NetworkUIDS list on index server in VUser object identified by userUID argument by adding provided networkUID. You need to update your local VUser object manually after that or to reload.
public void UnJoinUserFromNetwork(Guid userUID, Guid networkUID)
- Updates NetworkUIDSlist on index server in VUser object identified by userUID argument by removing provided networkUID. You need to update your local VUser object manually after that or to reload it.
public VUser LogOffUser(string Username)
- Removes Peer UID from PeerUIDSlist in VUser object on index server. Returns fresh copy of VUser object.
public VNetwork SaveNetwork(VNetwork network)
- Inserts or updates (based on UID value) VNetwrok object. If UID is empty insert will be performed. The result is a fresh copy of VNetwork object from index server.
VNetwork newNetwork = new VNetwork();
newNetwork.Name = "network1";//THIS IS REQUIRED, IT IS ALIAS FOR newNetwork["name"]
newNetwork["owner"] = "Mike";
newNetwork = cm.VNIndexManager.SaveNetwork(newNetwork);
if (newNetwork.UID != Guid.Empty)
{
Console.WriteLine("Network is saved , assigned UID is:" + newNetwork.UID.ToString());
}
then update operation would be:
newNetwork ["owner"] = "Jeff";
newNetwork = cm.VNIndexManager.SaveNetwork(newNetwork);
there cannot be to networks with the same name in application scope.
public void DeleteNetwork(Guid networkToDeleteUID)
- Deletes VNetwork object having exact UID:
cm.VNIndexManager.DeleteNetwork(n.UID);
public List<VNetwork> QueryNeworks(string QueryCommandText, int skip = 0, int limit = 0, string ascOrderBy = null, string descOrderBy = null)
- Searches for VNetworks matching query, then returns a list of found VNetworks to requester
List<VNetwork> networks = cm.VNIndexManager.QueryNetworks("\"Properties.Interes\":\"Ecology\"");
If you expect a large number of object to be returned consider using pagination. In last two optional parameters, you enter comma separated property names.
public long QueryNeworksCount(string QueryCommandText)
- Searches for VNetworks matching query, then returns a number of objects found
public VObject SaveObject(VObject obj)
- Inserts or updates (based on UID value) VObject object (general purpose record). If UID is empty insert will be performed. The result is a fresh copy of VObject object from index server.
VObject newObject = new VObject();
newObject["something"] = "[\"1\",\"2\",\"9\"]";
newObject = cm.VNIndexManager.SaveObject(newObject);
if (newObject.UID != Guid.Empty)
{
Console.WriteLine("Object is saved , assigned UID is:" + newObject.UID.ToString());
}
then update operation would be:
newObject ["something"] = "[\"1\",\"2\",\"9\",\"15\"]";
newObject = cm.VNIndexManager.SaveObject(newObject);
public void DeleteObject(Guid objectToDeleteUID)
- Deletes VObject object having exact UID:
cm.VNIndexManager.DeleteObject(obj.UID);
public List<VObject> QueryObjects(string QueryCommandText, int skip = 0, int limit = 0, string ascOrderBy = null, string descOrderBy = null)
- Searches for VObject-s matching query, then returns a list of found VObject-s to a requester
List<VObject> objs = cm.VNIndexManager.QueryObjectss("\"Properties.something\":\"15\"");
If you expect a large number of object to be returned consider using pagination. In last two optional parameters, you enter comma separated property names .
public long QueryObjectsCount(string QueryCommandText)
- Searches for VObject-s matching query, then returns a number of objects found
Note we used json array for newObject["something"] value. Index server will automatically detect json array string shape or json object string shape and store it in that form. It is important that you don't have blank characters before "[" or "{" in this cases because index server will not do object/array check in that case . This enables you full-scale use of sub-objects in search queries.
You might need to have administrative application or site so you can give support to your users that can perform all index operation. When creating it have in mind that you must open session (become network peer) to gain access to the index server.
8 Security, key exchange and data encryption/decryption
QuickP2P API provides you an easy way to obtain secure keys to be known only to peers involved with a tunnel. You use this keys to crypt/decrypt data during data transfer.
The secure key exchange is based on "Diffie–Hellman" algorithm with encampment to the original concept. There is no "real" fixed key part, instead of some short-lived data existent for few seconds during handshake operation that is used to generate what is called "Fixed part" in the original concept. This eliminates the possibility for an attacker knowing fixed part to intrude data integrity using any encryption breaking theory.
32 bytes of security data is known only to two peers involved with the tunnel. Security data is generated always during handshake procedure. After each successful connect/accept, generated bytes can be obtained from handler function Peer argument object:
void ConnectionManager_onPeerConnected(Peer Peer,Guid TransactionUID)
{
byte[] myKey = Peer.TunnelSecretData.Take(16).ToArray();
....
}
void ConnectionManager_onPeerAccepted(Peer Peer,Guid TransactionUID)
{
byte[] myKey = Peer.TunnelSecretData.Take(16).ToArray();
....
}
quickP2P API has built-in classes that for AES encryption (chippering).
AES class - core AES encryption
If support following AES variants:
Key size:
- 128
- 192
- 256
Chipering mode :
- ECB (each block crypt with key separately, commonly used when partial decryption is required)
- CBC (default - each block is XOR-ed with a previous crypted block then crypted with a key. First 16 chunk is XOR-ed using CBCInitialVector. Single byte difference makes whole data unusable)
Padding:
- None
- PCKS7
AESNetworkStream - used to prepare data for crypt transfer when the tunnel is stream based (TCP). AESNetworkStream is not standardized and it's designed for easy use with quickP2P tunnels (you can use to else ware if both sides have it as the first gate). AESNetworkStream enables you to use CBC mode for real-time communication because provides you the ability to use fairly sized blocks crypt with CBC chippering. Normally in CBC mode you would need to get all data (like the whole file), then decrypt it so you could use it. AESNetworkStream can use more secure CBC mode and provide you partial data decryption.
For UDP datagrams you can simply use core AES class.
One thing to note when working with this classes is that original and crypted data do not have the same size. Crypted data is usually slightly larger than original.
Next is a simple example of crypting and decrypting text with core AES class:
var key = Guid.NewGuid().ToByteArray();//we generate some random key just for testing
quickP2PLib.Security.AES a = new quickP2PLib.Security.AES(quickP2PLib.Security.AES.KeySize.Bits128, key, quickP2PLib.Security.AES.Padding.PCKS7, quickP2PLib.Security.AES.Mode.CBC);
//we generate some test text and convert it to bytes
var original = ASCIIEncoding.ASCII.GetBytes("Hello I'am text to crypt");
byte[] buff1 = new byte[512];
//we crypt
int cryptlen = a.Crypt(original, buff1);
byte[] buff2 = new byte[512];
//we decrypt
int decryptlen = a.Decrypt(buff1, 0, cryptlen, buff2, 0);
//we convert bytes to text
var decrypted_text = ASCIIEncoding.ASCII.GetString(buff2, 0, decryptlen);
This is the same thing done with AESNetworkStream:
var key = Guid.NewGuid().ToByteArray();//we generate some random key just for testing
quickP2PLib.Security.AESNetworkStream ans
= new quickP2PLib.Security.AESNetworkStream(quickP2PLib.Security.AES.KeySize.Bits128, key);
//we generate some text and converti it to bytes
var original = ASCIIEncoding.ASCII.GetBytes("Hello I'am text to crypt");
//we write data to stream to be crypted
ans.WriteForCrypt(original);
byte[] buff1 = new byte[512];
//we read crypted data form stream
int crypted_len = ans.ReadCrypted(buff1);
//we now write crypted data for decryption
ans.WriteForDeCrypt(buff1,0,crypted_len);
byte[] buff2 = new byte[512];
//we read decrypted data
int decrypted_len = ans.ReadDeCrypted(buff2, 0, ans.AvailableDeCrypted);
//we convert bytes back to text
var test2 = ASCIIEncoding.ASCII.GetString(buff2, 0, decrypted_len);
Usually, you also need to set CBC initial vector (commonly "IV" ) if you are using CBC mode. Quick P2P AES class will generate it if not provided based on key value. In above example, we didn't set it but it's recommended you do so. Both classes have means to provide you pointer to internal CBC internal vector buffer you can
set bytes before you do any crypt/decrypt operation.
9 Add firewall exception for your application in application installer
It's recommended that you add a firewall exception for your application. Communication will find its paths anyway but firewall exception can drastically increase performance. While developing you can do that manually but you would probably need a way to do that on user computers.
You can use quickP2PLib.FirewallHelper.Allow in application code but that will not have effect unless current user is a system administrator. Next are instructions how that can be done in case of using standard VS Setup project for application distribution .
The best place to execute a programmatic instruction for the user computer to do firewall exception creation is during application installation because the installer has boosted privileges. See InstallerFirewallException.cs class inside "qp2p_SimplestDemo_FileTransfer " project that you use with this document. So you need to create installer class in your project and provide a method: InstallerRoutine_AfterInstall
private void InstallerRoutine_AfterInstall(object sender, InstallEventArgs e)
{
quickP2PLib.FirewallHelper.Allow(this.Context.Parameters["assemblypath"], "simple_file_transfer_example" + DateTime.Now.ToFileTimeUtc().ToString());
}
For this to be executed by installer you need to add a custom action in setup project to execute on "Commit" even, you state assembly containing installer class (in our demo class is InstallerFirewallException.cs located in project itself so we would put "Primary output from qp2p_SimplestDemo_FileTransfer(Active)" for commit action)
These steps would count for windows distribution with standard VS Setup project. If you have other situation, like if you are creating Mono project for a non-windows platform with .NET API you would probably need different steps.
