Programmatic use


To get started we need to first get the Datagram NPM module:

$ npm install -g datagram

Then you want to import it:

const Datagram = require('datagram') // nodejs
// or
import Datagram from 'datagram' // es6

Everything we do with Datagram requires a Datagram instance. As a convention, we write the instance as datagram with lowercase, so we don't mix up Datagram the JavaScript library with the datagram the instance.

Let's create a datagram

First things first, we need a new datagram. This happens by creating a new Datagram instance and then calling ready() to wait until your Datagram is good to go. We are mainly waiting for cryptographic key generators to finish.

const DG = new Datagram()
DG.ready((err, datagram) => {
// datagram -> your new datagram
console.log(datagram) // { ...api }
// or with async/await
const datagram = await DG.ready()
// or with Promises
DG.ready().then(datagram => {
// datagram -> your new datagram
console.log(datagram) // { ...api }

After you have your new datagram ready, remember togetCredentials() and save them so you can open the datagram again in the future.

3-way control flow support

Each API method in Datagram supports the three most common JavaScript control flow methods: Callbacks, Promises and await/async.

In the documentation, we will be using await/async to keep everything nice and short.

Opening datagrams

Datagram requires two sets of security credentials: user credentials and datagram keys.

User credentials

Datagrams are encrypted from head to toe so you will need to pay attention with your credentials. When you create a new datagram, it will automatically generate a new set of credentials for you. You can get them by calling dg.getCredentials().

It can't be emphasized enough that you are responsible for storing and keeping these credentials safe. With true freedom comes great responsibility.

Credentials example

const user = {
id: '29AmtZ6mzjGmbpRnSujYyBjQVRKRnKKN2LGmtNzSVgT64K8nBk',
password: 'U3L3FuFdRRzeKo4z5pNBFWB9ojZQSGv2o3s8vsiA7qkopYC3xtxLTWMZZexb3cB2CzDTxekm9jhSYPTtJDFoLdB9gSA48'

Credentials are used to sign & verify the data you save in your datagram.

Datagram keys

Deep down your datagram is a data structure that grows itself in a very specific way using cryptographic constructs to guarantee data integrity and security.

Each datagram has three keys: read, write and encryption.

Read key allows the user to verify data to be valid, write key allows the user to add new data and encryption key allows the user to decipher and read the data.

Datagram keys are not reusable on another device Do not attempt to copy your datagram keys to another device. It will not work. Keys are per device based. Read the section about cloning and authorization to understand how multi-device usage works.

As with the user credentials, it is up to you to keep your datagram keys safe and secure. You can get them by calling dg.getKeys(). Please note that you can ignore address and auth values.

Datagram keys example

const keys = {
read: 'yktEzbypjQQKZXj9RTagsNp82YL2fd3DQEUr36oS3YzAjwrvu',
write: '4Cx1qqSehY3SeWggGuNJx6r6kD2tWmuP7eeRCP8BKy149uLsnDnJtixAWR4BVPVu8UDA4LVgfiqQ71oQhFbmgVRRUFL5t',
encryption_password: 'D6JhHaUVDb9sXcEau7JuC1VTFBNdH98urGK2DEpGYj7uWxo6m'

Please note that write key is exported only for safe-keeping in case your hardware explodes. Datagram requires read and encryption_password for proper initialization.

Example of opening a datagram

const DG = new Datagram(user, keys)
const dg = await DG.ready()

Opening a datagram is very straight-forward. It's the same call as of when you create one but this time you pass in the credentials and keys.

Setting and getting data

If you don't specify a specific type when you initialize your datagram, Datagram will default to key/value interface. Key/value interface follows familiar get(key) and set(key, value) style.

Key is always a string. Value can be any string, number, object or buffer. When you get the key, the value will be returned in the same format as it was saved as.

Example of set and get

const DG = new Datagram()
const dg = await DG.ready()
await dg.set('hello', 'world')
const world = await dg.get('hello')

Sharing and connecting

After you have created a datagram, you can share it with anyone by calling share(). Share function will output a sharelink that you can then use to connect to this datagram from other devices.

const DG = new Datagram(user)
const dg = await DG.ready()
await dg.set('hello', 'world')
const sharelink = await dg.share()

To connect to the above datagram, we initialize a new datagram with the sharelink.

// Note that you need to copy over your user credentials
const DG = new Datagram({ ...user, sharelink })
const dg = await DG.ready()
const world = await dg.get('hello')

Authorization & multi-device use

At some point, you probably want to add data into your datagram on another device than where you initially created the datagram. Datagrams are meant to be securely shareable which means that if I share a datagram with you, I need to be sure that you can't delete or modify my data unless I explicitly give you the permission. Therefore, we need an authorization model.

Authorization with Datagram is easy. After you have created your datagram on the second device, call getAuthToken() to get a unique authorization token.

// Device #2
const auth_token = await dg.getAuthToken()

To make your original datagram in device #1 accept data from the new datagram in device #2, you authorize it by calling authorizeDevice({ auth_token }).

// Device #1
await dg.authorizeDevice({ auth_token })

Now the original datagram accepts any data from the new datagram.

Authorization equals admin rights Due to how cryptography works, once you authorize another datagram, it has all the same rights as you do. It can do anything it wants, including authorizing other datagrams. This is why Datagram is not recommended for multi-user use at the moment, only for multi-device with one user. This will be fixed in the future versions.