This website provides documentation for administrators of 0th Root Secure Network — 0SNet. To know about the product, kindly visit our product website.

Getting Started

0th Root Secure Network — 0SNet works at the domain level and all subdomains of the chosen domain. For example, if you choose a domain example.com then 0SNet will secure all subdomains of example.com ie., *.example.com. Ideally, a third level domain is chosen, such as corp.example.com to secure *.corp.example.com.

1. Network Firewall

It is important that whichever host you setup 0SNet on, only that host should have access to the protected servers. This will require establishing a network firewall on each of the servers.

2. Email Address

An administrator email address need to be specified at the time of configuration. This is the email address which will receive the password protected certificate. Only by using the certificate, can 0SNet be accessed. However, 0SNet can be reconfigured, if there were any mistakes made.

3. Operating System

The server hosting 0SNet should be capable of running Apache HTTP server (2.4.3+). Currently, RHEL 7 and its derivatives are supported, such as CentOS 7.

If you're on AWS or GCP or Azure, you can use our public AMI or Custom Image or Shared Image Gallery to launch a new instance, it comes with 0SNet pre-installed.

Installation

This section will help you through the process of installing 0SNet on your server. Please read Getting Started and have the domain information, administrator email, and the server details ready.

And, open ports 80 (HTTP) and 443 (HTTPS) on the server for 0SNet to work.

0SNet is provided as per these terms of use and privacy policy .

If you face any problems, please feel free to contact us.

Configuration

If you have chosen a domain such as .corp.example.com. You should configure your nameserver (DNS) to resolve the wildcard entry *.corp.example.com to the IP address of 0SNet server.

When Google Sign-In or Microsoft Sign-In is enabled, 0SNet will require login through the corresponding user account. Hence, don't use group email address or a mailing list during configuration.

Setup (1/3)

Type the following command,

sudo 0snet --configure

This should bring up the following screen,

Fill out the form with your domain name, organization name, email ID and user ID. TLS certificate for the administrator will be sent to the specified email address. Choose your user ID carefully, because it will not be possible to modify this later.

IMPORTANT: Note down the password. In case you don't remember it, you can reconfigure 0SNet using,

sudo 0snet --configure

After the Setup Complete message, you should receive an email at the specified address, check your spam/bulk folder if necessary. The email should contain one attachment, sign.p12. It is your personal certificate encrypted using the password and it should be imported into your browser under personal certificates. If you are unsure, as to how to import the certificate, kindly follow the steps here.

Management Interface (2/3)

Once the certificate is imported, you will be able to access the management interface. A special subdomain 0snet is reserved for this purpose. For example, If you have configured your domain as .corp.example.com, you should open https://0snet.corp.example.com.

On successful connection, Browser will ask for a client certificate to be selected. On choosing the correct one, a login page for 0SNet will be shown. Enter the generated password, and change the password after successful login.

Hosts (3/3)

Host Manager should be used to add subdomains, along with IP address / Hostname of origin server, as shown in the image below,

After adding the subdomain, click on Validate Now to validate the domain. The new subdomain will be ready to use within 5 mins.

Certificates

0SNet sends an email to users containing their personal certificate file. In this section, the steps to import the certificate has been provided in detail,

Android / iOS / Windows / Mac

On most devices, simply opening the sign.p12 file (double-click or tap to open) is sufficient to import the certificate.

Preferences

On Linux / Firefox / Opera browser, Search for "certificates" in the browser settings or preferences, and you will likely find "Manage Certificates" or "View Certificates". On opening it, click the Import button under "Your Certificates" or "Personal Certificates" tab and choose the certificate file, sign.p12.

On Google Chrome, you can use the direct link chrome://settings/certificates.

When prompted for a password, type the generated password that has been provided by the administrator.

The certificate should be imported successfully.

To protect the imported certificates, it is recommended that you set a Master Password for the browser.

Role-based Access Controls

By default, all users have equal access to the subdomains, ie., *.corp.example.com. To differentiate users and grant access only to specific subdomain(s), ie., webapp.corp.example.com, access controls should be used. The link to access controls page can be found in user manager.

There are two distinct sections in access controls, ie., the Default and Groups sections.

Default

The default behavior of access controls is governed by this section. There are three components that work together, ie., mode, statements and exceptions, as shown in the image below,

The Update statements button will be disabled until mode or statements has been changed. On successful update, the access controls are immediately applied. Hence, it is recommended to make all the changes at once.

Mode

The default mode can be one of two values, Allow (or) Deny. In Allow mode, as the name suggests, all incoming requests are allowed after successful authentication, while in Deny mode, they are rejected as unauthorized.

Statements

To alter the default behavior, along with the default mode, statements can be used. The syntax of a statement is as follows,

<deny or allow> <subdomain> [</url> or </urlprefix>]

All statements in the example below are valid, they collectively define access for users,

 allow myapp.corp.example.com
 deny myapp.corp.example.com /this/path/*
 deny webapp.corp.example.com /this/file.php

URL path prefix or an absolute path to file can be optionally specified, as shown in the example above. However, query string and anchor element cannot be matched.

Exceptions

To bypass default mode and statements, an exception can be added for specific users. An exception is an association of user to a specific mode. While an exception exists for the user, default mode and statements will not apply, and only the mode associated to the user will apply.

Groups

To specify access controls for a set of users, control groups can be used. Each group can have its own statements and users, as shown below,

Users can be part of multiple groups and control statements of all those groups will be used for authorization, along with default statements (if applicable). In case of conflicts, longer URL paths and deny statements take higher precedence.

NOTE: Admin user created at the time of 0SNet setup cannot be part of control groups.

To remove user from a control group, click on the user row and confirm. To quickly remove without any confirmation, hold CTRL key when clicking.

Version

Details of last update can be checked with,

sudo 0snet --ac

0SNet versions update to mode and/or statements, above command will output details of current version.

Google Sign-In

Instead of 0SNet password authentication, Google OAuth can be used through the Google Sign-In (GSI) feature. When GSI is used, the user is prompted with a Sign In button, as shown below, instead of the usual username and password,

The email address of the user should match the Google account used for login.

Configuration

Create a new client ID for 0SNet, in Google API Console, and specify the javascript origins. When 0SNet is configured for *.example.com, the javascript origins would be a.example.com, b.example.com and so on. Unlike 0SNet, wildcard is not supported, hence all internal applications and websites need to be added individually.

Enable GSI

The client ID can be set in 0SNet and GSI can be enabled using the command shown below,

sudo 0snet --gsi on [client-id]

To disable GSI at any point, the following command should be used,

sudo 0snet --gsi off

Do remember to restart 0SNet for changes to take effect,

sudo 0snet --stop && sudo 0snet --start

Process Changes

The user creation and certificate installation processes remain the same. Only at the time of login, the user is prompted with a Sign-In button instead of user name and password. Hence, with GSI, user doesn't need access to 0SNet password or username, expect at the time of certificate installation.

Demerits

When GSI is enabled, 0SNet Server requires access to public internet to function. It verifies the connection to external servers using the trusted root certificates available on the server, typically at /etc/pki/tls/certs/ca-bundle.crt. All CAs are treated equally, so it is important to keep the CA bundle upto date.

Microsoft Sign-In

Instead of password authentication method, 0SNet can be configured to use Microsoft OAuth 2.0 through the Microsoft Sign-In (MSI) feature. When MSI is enabled, users will be prompted with a Sign In button to login, as shown below,

The email address of the user should match the Microsoft account used for login.

Configuration

A client-id provided by Microsoft is needed to enable MSI in 0SNet. It can be found in Azure Active Directory.

An application need to be registered, as shown in the images below,

And, to support Sign-In across all sites configured under 0SNet, they need to be added under Redirect URIs for the application,

Enable MSI

The client-id can be set in 0SNet to enable MSI using the command shown below,

sudo 0snet --msi on [client-id]

To disable MSI at any point, the following command should be used,

sudo 0snet --msi off

Do remember to restart 0SNet for changes to take effect,

sudo 0snet --stop && sudo 0snet --start

Process Changes

The user creation and certificate installation processes remain exactly the same. Only at the time of login, users will be presented with a Microsoft Sign-In button. Hence, with MSI enabled, password for the user will need to be used only for certificate installation.

Demerits

Enabling MSI adds a dependency on Microsoft Login and Microsoft Graph API services. If any of them are down, users will not be able to login to 0SNet. This also essentially means, a public internet connection is required on the 0SNet server.

The connections to Microsoft services are verified using the trusted root certificates available on the server, typically at /etc/pki/tls/certs/ca-bundle.crt. All CAs are treated equally, so it is important to keep the CA bundle upto date.

License

0SNet incorporates a licensing system for easier distribution and sale of software. Every install of 0SNet comes with a license file which works for upto 5 users. You can review the license information using the following command,

$ sudo 0snet --license info
                                                                        
0throot license file                                      
                                                                        
     License Key : UzXE/CV82m6kysyrtYQfv6X13wX6tWdnR/IPeULoaroR
         Product : 0th Root Secure Network
          Domain : .corp.example.com
    Organization : Example Company Ltd.
  Date of Expiry : Dec 24, 2019 14:17 IST
           Users : 5
      Valid Upto : N/A

Contact us @ support@0throot.com for any queries.

License files are updated periodically (default: 1hr) through a cronjob. To update them manually, please run,

$ sudo 0snet --license sync
$ 	

Pricing

To upgrade your license file to add more users, you can review our payment terms and purchase options listed below,

Total Users	Pricing (INR)	Pricing (USD)
5 users	Free of charge	Free of charge
50 users	Rs. 5000 per month	$100 per month
each additional user	Rs. 100 per month	$2 per month

When multiple servers are used to serve the same set of users, the following charges are applicable,

Server	Pricing (INR)	Pricing (USD)
1st server	Rs. 0 per month	$0 per month
each additional server	Rs. 3000 per month	$60 per month

* All government taxes will be extra

IMPORTANT: Prices are tentative and subject to change.

Please feel free to contact us at support@0throot.com for further details.

Command Line Interface (CLI)

0snet --cli <action> <arguments>

---

useradd, userreset, userdelete, userstatus, usergroup

    --name "full name"
    --email "email address"
    --userid "user-id"
    --group "group name"
    --allow
    --deny
    --nocert
    --enable
    --disable
    --add
    --remove
    --json
        

    useradd --name <> --email <> --userid <> [--group <>] [--allow | --deny]
    userreset  (--userid <> | --email <>)
    userdelete (--userid <> | --email <>)
    userstatus (--userid <> | --email <>) (--enable | --disable)
    usergroup  (--userid <> | --email <>) --group <> (--add | --remove)
        

DESCRIPTION

The --cli option of 0snet utility provides a command line interface to manage users within 0th Root Secure Network (0SNet). The utility can output in JSON format for easier integrations, refer to OUTPUT section for more details. And, to know more on possible integrations, refer to INTEGRATION section.

useradd can be used to add new user, it requires the --name, --email, --userid to be specified. user-id should be a single word with one or more of the following characters, a-z A-Z 0-9 - . _ :. Optionally, the newly created user can be added to access control groups by specifying the group name, with --group argument. Multiple groups can be specified by repeating --group. Additionally, --allow, --deny can be used to set appropriate exception to default access control statements for the new user. And, --nocert to add the user without certificate.

By default, newly added users are enabled, and they are not administrators. User manager should be used to set the added user as an administrator, if needed.

userreset will reset user certificate and credentials. The command outputs the new password, and it should be securely communicated to the user. When --email is used, all users matching the email address are reset.

userdelete can be used to delete user(s). All users matching the email address are deleted when using --email.

userstatus should be used when a user needs to be disabled, or when a disabled user needs to be re-enabled. On using the --email argument, all matching users are updated.

usergroup will add or remove user(s) from the specified list of groups. Multiple groups can be specified by repeating the --group argument. In case of a failure, the user(s) may be added or removed from some groups and not all.

The actions userstatus and usergroup are idempotent, and can be safely repeated, in case of any error.

OUTPUT

In case of errors, the exit code of the command will be non-zero. The output format for useradd will be,

<user-id> <password>

And, when --json argument is specified, the output format changes to a JSON text, as follows,

{"status":{"code":0,"message":""},"output":{"<user-id>":"<password>"}}

In case of an error, the above JSON text will have code set to non-zero value and message will contain the description of the error.

For userreset, the output may contain multiple user-ids and passwords, one per line, when --email argument is used. The output JSON text can also have multiple user-ids as keys with corresponding passwords as values.

INTEGRATION

Scripts can be developed to process user information and pass on to 0snet-cli to perform a specific action. This could be a one-time task, such as for bulk addition of users, or could be a cron job for periodically adding and removing users.

A job management system could also be used, to securely login to server and run 0snet-cli to perform a specific action.

Exposing the actions of 0snet-cli as a service is NOT RECOMMENDED, and HIGHLY DISCOURAGED.

EXAMPLES

In the examples below, the first line is the command and the below lines are output of the command,

$ sudo 0snet --cli useradd --name "Example User" --email "user@example.com" --userid "example1"
example1 kfuKN16t
        

$ sudo 0snet --cli userstatus --userid "example1" --disable
updated user(s) successfully
        

$ sudo 0snet --cli userreset --userid "example1" --json
{"status":{"code":0,"message":""},"output":{"example1":"Ipt38AY8"}}
        

$ sudo 0snet --cli usergroup --userid "example1" --group "Employee" --add
updated users and groups successfully
        

$ sudo 0snet --cli userstatus --userid "example1" --enable --json
{"status":{"code":0,"message":"updated user(s) successfully"}}
        

$ sudo 0snet --cli userstatus --userid "example1"
example1 enabled
        

$ sudo 0snet --cli useradd --name "Example User (Mobile)" --email "user@example.com" --userid "example2" --group "Sales" --group "Employee" --deny --json
{"status":{"code":0,"message":""},"output":{"example2":"lbLgduIA"}}
        

$ sudo 0snet --cli userreset --email "user@example.com"
example2 RqaHy9zH
example1 Scrn3HJ3
        

$ sudo 0snet --cli userdelete --userid "example2"
deleted user(s) successfully
        

$ sudo 0snet --cli usergroup --userid "example1" --group "Employee" --remove
updated users and groups successfully
        

Let's Encrypt

0SNet provides tools for easier integration with Let's Encrypt TLS certificate. It internally uses Certbot client to obtain and manage Let's Encrypt issued TLS certificates.

NOTE: This feature is intended for setups where 0SNet server has a public IP and the default HTTP port 80 is available. In case of private setups, or where port 80 is used by a different program, the necessary domain validation cannot be done to get certificates.

Certbot

Package for Certbot client is available on various distributions. On CentOS/RHEL 7.x, one can run the following command to install the EPEL repository,

sudo yum install epel-release

and install the certbot package,

sudo yum install certbot

In case, the client couldn't be installed through the native package manager, the following command can be used to download and install Certbot client.

The install of Certbot will be local to 0SNet. However, additional dependent packages will get installed, and/or upgraded, during the process. And, in case of any errors, you can attempt an experimental install with the option --debug, but make sure you have taken the necessary backups before using it.

Hosts

0SNet is intended to secure all subdomains of the chosen domain, such as *.example.com. But, since, Let's Encrypt platform currently supports only multi-domain TLS certificates (upto 100 domains) over HTTP-01 challenge, and not wildcards, the list of subdomains used will be gathered by parsing the /etc/hosts file. This list of subdomains can be verified by running the command shown below,

It should be ensured that all required subdomains are part of the list, before fetching the TLS certificate. On adding a new subdomain, a new TLS certificate should be obtained (fetch) and enabled (on).

Certificate

Let's Encrypt certificates are domain validated and are issued immediately. To obtain a new certificate, the fetch command should be run as follows,

During the process, 0SNet server will be stopped and started, with the service being offline for a few minutes.

Enable/Disable

A newly issued certificate is not automatically used by 0SNet. To enable Let's Encrypt certificate, the following command should be run,

sudo 0snet --letsencrypt on

And, to switch back to the previous certificate, ie., stop using Let's Encrypt certificate, run the command below,

sudo 0snet --letsencrypt off

Renewal

0SNet checks the certificate for renewal daily and it gets automatically renewed. During the renewal process, which happen once in 2-3 months, the server may be offline for a few minutes.

The log messages are written to syslog, and is typically available at /var/log/messages, it should be checked for any errors during renewal.

Contact Us

0SNet is a product of 0^th Root Software Research. For any questions (or) suggestions, please write to us at support@0throot.com

We are located at,

(Primary Address)
RMZ Latitude Commercial,
10th Floor,
Bellary Rd, Hebbal,
Bengaluru - 560 024. (INDIA)

No.24, Tatia Nagar Phase -3,
Nolambur, Maduravoyal PO,
Chennai - 600 095. (INDIA)
+91 44 2653 2984