# Overview

The Nimbus SDK (Software Development Kit) is a .Net library that allows you to send and receive data securely over the Nimbus Secure network.

Using Nimbus Secure allows you to;

Send data to a remote Nimbus Secure endpoint
Receive data from another endpoint on the Nimbus Secure network
Search the global address book
Hook events throughout the send/receive process

Nimbus is a peer to peer data transfer platform, there is no intermediate server that your data is stored on. Nimbus Secure endpoints, including SDK endpoints publish healthcheck data, so that our support team can reach out if we spot any issues with your installation.

You can reach our support team by emailing [email protected].

# Why Use Nimbus Secure SDK?

The majority of software today is hosted in disparate locations. The demand for sharing data is only increasing, however sharing data brings with it considerations around firewalls and who can send what where.

The Nimbus Secure product set (including SDK), uses our private tunnel and encryption implementation to allow you to send data from peer to peer in real-time. Our SDK in particular allows a developer to prepare the data that they want to share, then with a simple one line command, send that to a remote location of their, or their users choosing.

Our of the box, we provide you with a global address book, so that you can easily find other endpoints on the network.

# How Much Does Nimbus SDK Cost?

There is no additional charge to use Nimbus Secure SDK. Nimbus Secure is priced only on the volume data you transfer. To view pricing, please visit https://www.nimbussecure.com.au/pricing. For enterprise agreements or customise agreements, please email our team at [email protected].

# Obtaining a Licence

To use the Nimbus Secure SDK, you must have a licence for each of your locations that will be using the SDK. You cannot share licence keys across multiple locations. Our support team can create a licence key for you. Simply email [email protected].

# Installation

Using the package manager console, run the following command:

Install-Package NimbusSecureDataTransfer

You will be prompted to accept the EULA of dependencies during the installation.

# Basic Use

To instantiate the Secure Data Transfer client is straightforward. Simple create an instance of the SecureDataTransferClient and pass in your Licence Key (see above for obtaining a licence key).

var client = new SecureDataTransferClient(<Licence Key>);

// Your Code Here

client.Dispose();

We strongly advise that you control the instantiation of the client and disposal at the correct points in your application. We would advise that you create the client when your application is launched, and call the dispose when it is exited. Instantiation of the client can take up to 2 minutes whilst a connection to the private tunnel is made.

# Searching The Global Address Book

Nimbus Secure has a centralised, global address book that you can search. You can search for a remote endpoint using varing details, based on what they choose to publish. Endpoints may also choose not to be represented in the global address book, in which case you will need to know their unique profile identifier to recach them, rather than searching for them in the address book.

var searchResults = await client.Search(
    <string: Search Term>
    );

The following fields are searchable:

Profile Identifier
Legal Name
Trading Name
Email (Office only)
Phone (Office only)
Aliases (Active aliases only)

This will return an IEnumerable of endpoints that matched your search criteria. To send to one, use the ProfileIdentifier field as the recipient.

# Sending A File

To send a file, you can provide a path to the file that you would like to send. Note that the calling process must have access to the file that you are sending.

var sendResult = await client.Send(
    <string: Recipient Profile Identifier>, 
    <string: Path to the file>
    );

In this example, sendResult will be a bool. A True result indicates the file was sent (and received) successfully. A False result indicates the file could not be sent.

# Sending A Byte Array

To send a byte array, simply provide the byte array that you would like to send, along with a filename of the file. You would use this method if you are sending JSON or serialised payloads from your application.

var searchResults = await client.Send(
    <string: Recipient Profile Identifier>, 
    <byte[]: File Bytes>, 
    <string: File Name>);

In this example, sendResult will be a bool. A True result indicates the file was sent (and received) successfully. A False result indicates the file could not be sent.

# Receiving A File

To recieve files, you need to hook into the OnFileReceived event. Note that if you do not hook this event, remote endpoints that wish to send to you, will recieve an error and the transfer will not commence.

You should hook this event after instaniating the SecureDataTransferClient.

client.OnFileReceived(
    (string filename, 
        byte[] fileBytes, 
        string senderProfileIdentifier) =>
{
    Console.WriteLine($"The file {filename} was received from {senderProfileIdentifier}");
});

The event will receive the following;

filename: The name of the file the remote side sent
fileByes: A byte array containing the contents of the file
senderProfileIdentifier: The profile identifier of the sender

The SecureDataTransferClient does not cache the resulting file, so it is important that your application can handle the file as it arrives and is raised by the event.

# Updating Your Profile

You can manage your profile from the SecureDataTransferClient. A profile update is a replace, any fields that you do not provide in this call are removed from your profile.

As a minimum, you must provide a LegalName, which represents the legal name of the entity that owns the endpoint.

var result = await client.UpdateProfile(new UpdateProfile()
{
    LegalName = "My Awesome Company Pty Ltd",
    // Other profile update fields
});

The available fields are as follows:

Field	Data Type	Required	Notes
HideInPublicAddressBook	bool	yes	Show or hide this endpoint in the global address book.
LegalName	string	yes	The legal name as defined by the relevant government body for the entity that owns the endpoint.
TradingName	string	no	The name the entity prefers to be known as. Commonly a trading name or similar.
MainContactFirstName	string	no	The first name of the person we should contact if we identify an issue with the endpoint. *Not published in the global address book, for support purposes only.*
MainContactLastName	string	no	The last name (surname) of the person we should contact if we identify an issue with the endpoint. *Not published in the global address book, for support purposes only.*
MainContactEmailAddress	string	no	The email address of the person we should contact if we identify an issue with the endpoint. *Not published in the global address book, for support purposes only.*
MainContactMobileNumber	string	no	The phone number (mobile preffered) of the person we should contact if we identify an issue with the endpoint. *Not published in the global address book, for support purposes only.*
Logo	string	no	A logo representing the entity that owns this endpoint. Passed in as a base64 representation of the logo file
Description	string	no	A description of the endpoint. This could be used for a hostname, a description of the business or description of the physical location.
Address	string	no	The address of the entity that owns the endpoint.
PhoneOffice	string	no	The phone number of the entity that owns the endpoint.
EmailOffice	string	no	The email address of the entity that owns the endpoint.
VendorName	string	no	The name of the vendor that has embedded the SDK.
VendorSoftwareName	string	no	The name of the software that the SDK is embedded into.
VendorSoftwareVersion	string	no	The version of the software that the SDK is embedded into.
Aliases	List<string>	no	A list of aliases that this endpoint would like to operate under.

Aliases allow an endpoint to be found by an arbitary identifiter that may relate to another system. Note that not all aliases are avaialbe and are assigned on a first come, first served basis. Once an alias is no longer in use by an endpoint, it is marked as dormant and can NOT be adopted by any other endpoint, other than the one that originally requested it. Aliases cannot be a GUID, and must be a minimum of 5 characters.

Although you are not required to provide the Vendor fields above, however it assists our support team to know how the SDK is being used. It also allows us to better support a mass deployment of endpoints for you.

# Advanced Funtionality

# Controlling the Web Server Port

Internally, Nimbus Secure SDK will run a web server to facilitate the receiving for data and connection validation when sending. By default, this port runs on port TCP/7050, listening on the localhost\loopback address (127.0.0.1).

If you need to change this port, you have two options. You can specify a single port, or a range of ports. If specifying a range of ports, the SDK will find the first free port in the range and start under that port.

To provide a single port, for example, to use port 8020.

var client = new SecureDataTransferClient("12345", 8020);

Alternativly, to use a port range, for example ports 8020-8090.

var client = new SecureDataTransferClient("12345", "8020-8090");

# Events & Delegates

# OnIncomingConnection

This delegate is invoked when another endpoint is attempting to send a file to you. This gives you an oppertunity to accept or reject the connection. The question this delegate is answering is "Am I Expecting A Connection From You?". If you were to implement whitelisting of senders, this is the method you would use to achieve that.

Your delegate should response with an model of type PreventTransfer. A IsPrevented.IsPrevented = True response will prevent the transfer from continuing. You may also provide a Message back to the sending side as to why you prevented the transfer, should you wish to do so.

client.OnIncomingConnection((string sender, string fileHash, string fileType, int fileSize) =>
{
    return new PreventTransfer()
    {
        Message = null,
        IsPrevented = false
    };
});

You will receive the following details of the transfer:

sender: The profile identifier of the sender
fileHash: A file hash of the file being transfered
fileType: The file extension of the file being transfered (if provided)
fileSize: The size of the incoming file, in byes

# OnIncomingFileValidator

When Nimbus Secure sends a file, as part of the connection chain, it makes a connection to the person who is claiming to send the file, to validate if they are indeed atempting to send a file. This is what we refer to as the third leg validation.

We would reccomend that you maintain a list of file hashes that you are attempting to send. When this delegate is raised, validate that the file hash is in your list. If it is not, reject the connection by returning false. If it is in your list, return true to allow it.

You will also receive the senders profile identifier as well. You may perform additional/conditional logic here to prevent or allow the transfer. If you wish to provide more details to the sender, we would suggest implementing the OnIncomingConnection event as well.

client.OnIncomingFileValidator((string fileHash, string senderProfileIdentifier) =>
{
    return true;
});

# OnLogRaised

This event will trigger when the SDK raises a log entry - these log lines can be useful for debugging. It is reccomended that this is a configuration option within your application to enable or disable this event.

The following log levels are returned:

Level 1 : ERROR
Level 3 : INFORMATIONAL
Level 4 : DEBUG

(Log Level 2 is reserved for future use.)

client.OnLogRaised((int LogLevel, string Message) =>
{
    Console.WriteLine("LOG: [" + LogLevel + "]: " + Message);
});

If you are subscribed to the OnLogRaised event, you do not need to subscribe to the OnErrorRaised event as well.

# OnErrorRaised

This event will raise when an ERROR log entry is raised. You should log these to your application to identifiy any issues that are occuring within the SDK.

client.OnErrorRaised((string message) => 
{
    Console.WriteLine("ERROR: " + message);
});

If you are subscribed to the OnLogRaised event, you do not need to subscribe to the OnErrorRaised event as well.

# OnFailedTransfer

The OnFailedTransfer event will raise when a transfer fails. An object will be returned to you with the following details;

Action: the direction of the file (will be SEND or RECEIVE)
FileName: the name of the file that failed
FileHash: the filehash of the failed file
Error: the cause of the failure

client.OnFailedTransfer((FailedTransfer failedTransferDetails) =>
{
    Console.WriteLine("FAILED TRANSFER: " + JsonSerializer.Serialize(failedTransferDetails));
});

For convenience, you can also parse the incoming object as a dynamic rather than using the FailedTransfer model.

# Loopback Sending

For convenience and testing, you may wish to send a file to yourself to trigger all parts of the SDK. You can do this in the following way.

var sendSuccess = await client
            .Send(
                (await client.GetProfile()).ProfileIdentifier,
                <byte[]: File Bytes>, 
                <string: File Name>);

You can use the same paramaters as the 'Sending A Byte Array' process above. The GetProfile() method returns the current endpoints profile, which the ProfileIdentifier is then extracted from it.

Note that as loopback sending traverses the Nimbus Secure network the same as all other transfers, they are charged as per normal transfer rates.

# Disable Sending By Alias\Search

By default, the SecureDataTransferClient will attempt to find the endpoint you want to send to, even if you didn't provide an exact profile identifier in your send. This is to allow you to send to an alias, without having to search first.

In some instanced, you may only want your send method to send to a remote endpoint, if you are certain you are sending to the correct location.

Disabling this functionality can be done on each .Send() call, simply pass an additional paramater, with the value of true.

For example, to prevent this function when sending a byte array, your request would now look like this.

var searchResults = await client.Send(
    <string: Recipient Profile Identifier>, 
    <byte[]: File Bytes>, 
    <string: File Name>,
    true);

# Ideas, Feedback, Questions & Suggestions

We welcome your feedback on the Nimbus Secure SDK, likewise if you have any questions about the SDK, we would be more than happy to assist.

Please contact our support team at [email protected].

← Nimbus Broker API Guide →