Impulse License

How impulse verifies if a license is a valid and how to generate a new license

The impulse license is required to execute any synchronization job. An invalid or expired license will result in an error before running a new job. Impulse users have to upload the license file to diesel in order to execute new jobs. Only internal Motiv users should generate new licenses for impulse users.

Licensinator

Licensinator is the licensing library used by impulse to generate and verify licenses. It is a fork of the lk library. It is located in this GitHub repository:

GitHub - motiv-labs/licensinator: Simple licensing library for golang.GitHub

Licensinator includes functionality to generate a private/public key pair, sign a license file containing arbitrary data using the private key, and then verify the license signature using the public key. Also, it includes functionality to encode and decode the license file, using a Base32 or Base 64 string. Since the license file can include any arbitrary data, impulse can store all the fields required to fetch license information.

License Command Line Tools

Impulse license command line tools are provided to generate new licenses and also to upload a new license to diesel. The command line tools are located in this GitHub repository:

https://github.com/motiv-labs/license-gengithub.com

These are the command line tools for impulse licenses:

• key-gen - generates a public/private key pair

• license-gen - generates a license file

• upload-license - uploads a license file to diesel

• print-license - print a license file information

• verify-license - verify a license file

License Generation

Private/Public Key

The first step before generating new licenses is to generate a private/public key pair. This step is only required to be run once by internal Motiv users in charge of license administration. The same key will be used to generate all the required new licenses. In case the key is compromised, or if the DevOps team recommends changing the key after a given elapsed time, a new private/public key pair can be generated.

In order to generate a new private key, run the following command:

gen-key private-key --output=license-key

That will generate a new private key in the ‘license-key’ file. After the private key is generated, run the following command to generate the public key:

gen-key public-key --output=license-key.pub license-key

That will generate the public key in the ‘license-key.pub’ file.

New License Creation

After the private/public key is generated, internal Motiv users in charge of licenses can generate new licenses with a given expiration date. They will require to enter the client name, the expiration date, the license type (prod or development), and the key that will be used to sign the license. You can run the following command to generate a new prod license with the given expiration date:

license-gen --client-name test-client --valid-until 2030-10-01 --type prod 
    --output license.dat license-key

That will generate the new license in the ‘license.dat’ file. To generate a perpetual license without an expiration date, run the following command:

license-gen --client-name test-client --perpetual --type dev 
    --output no-expire-license.dat license-key

That will generate the new perpetual license in the ‘no-expire-license’ file. With the type flag, you can set the license type:

• dev: development license

• prod: production license

After the license file is generated, the license file and the public key can be sent to the impulse users that will use the new license, so they can install it in their impulse application.

Print License

Once impulse users receive the license file from Motiv, they can run this command to print the license information:

print-license license.dat

Verify License

Also, impulse users can verify the license file after they get it from Motiv by running this command:

verify-license license.dat license-key.pub

Upload License

Impulse users receive the license file and also the public key from Motiv. Before uploading the license file, they have to include these environment variables in the sync-manager docker container:

• LICENSE_PUBLIC_KEY : this variable will contain the public key provided by Motiv

• LICENSE_FILE_BUCKET : name of the diesel bucket that will be used to store the license file (defaults to ‘license’)

• LICENSE_FILE_NAME : name of the diesel target location that will be used to store the license file (defaults to ‘license.dat’)

After setting the environment variables, impulse users can upload the license file with the following command:

upload-license --dieselURL http://localhost:8080/private/diesel   
  --organization motiv --user <user> --password <password> 
  --bucket license --target license.dat license.dat

If the bucket and target options are not used, the default bucket (‘license’) and the default target location (‘license.dat’) will be used to as the bucket and location to store the license file in diesel.

Another option is to upload the license file using a direct HTTP request to diesel by running the following curl command (or the equivalent request if you use another tool to send the request):

curl -X PUT http://localhost:8080/private/diesel/files/license/license.dat
  -H 'authorization: Bearer <JWT>' -H 'x-organization: motiv' 
  -d @license.dat

After the license file is stored in diesel, users will be able to run synchronization jobs. Impulse will validate the license signature and expiration date before running a new job.

Impulse License Type

The following go struct type is used to store the impulse license information:

type ImpulseLicense struct {
	LicenseId   uuid.UUID `json:"licenseId"`
	LicenseType string    `json:"licenseType"`
	ClientName  string    `json:"clientName"`
	Perpetual   bool      `json:"perpetual"`
	ValidUntil  time.Time `json:"validUntil"`
}

It includes a license identifier, the license type (dev or prod), if the license is perpetual or not, the expiration date for no perpetual licenses, and the client name.

Setup License for Dev Environment

Impulse developers don’t have to run the ‘upload-license’ command every time they start a new impulse application instance by using astro. The astro.sh start script will automatically include the license in the sync-manager docker container. The only required steps are:

1. Create a ‘license’ directory under the impulse parent directory.

2. Copy the ‘license-pub.key’ file (public key) and the ‘license.dat’ file (license file) under the ‘license’ directory created in the previous step.

You only can use the file names from the above steps for the public key file (license-key.pub) and license file (license.dat). The astro.sh script won’t include the license automatically if you use different file names for the public key or the license files.

The astro.sh script will execute these steps to include the license in the sync-manager container:

1. It will take the public key from the ‘license-key.pub‘ file under the ‘license’ directory and it will set the LICENSE_PUBLIC_KEY variable in the sync-manager container.

2. It will take the license file from the ‘license.dat’ file under the ‘license’ directory and it will set the LICENSE_FILE_CONTENT variable in the sync-manager container.

The LICENSE_FILE_CONTENT variable is a special variable that can be set in the sync-manager container instead of using the LICENSE_FILE_BUCKET and LICENSE_FILE_NAME variables. If the LICENSE_FILE_CONTENT variable is set, the sync-manager application will extract the license for that variable instead of retrieving the license from diesel. This allows to run synchronization jobs in impulse without storing the license in diesel, but using the license file content directly when running in a development environment.

Another important point related to this scenario is that if you set the LICENSE_PUBLIC_KEY or the LICENSE_FILE_CONTENT variables in the ‘astro.conf’ configuration file, astro will use the values from astro.conf instead of the files under the ‘license’ directory. That means that if you want to use files under the ‘license’ directory, you don’t have to include these environment variables in the astro.conf file. The same applies if you set these variables in the environment before running the astro.sh script: astro will use the defined variables from the environment instead of the files under ‘license’ directory.