Licensekeys is a server for creating, and a package for verifying, keys that authorize use of a software application.

Overview

A license key is a securely signed text file containing data that, when validated, allows usage of an application.

At it's core, Licensekeys simply provides an easy method to work with public key authentication. Only the license key server, which stores the private key, can create authentic license keys. The matching public key is included in your software application's code to authenticate a signature generated by the private key.

Table of Contents:

• Basic Operation
• License Key File Example
• Details
• Installing
• Getting Values From A License Key
• How A License Key File is Created
• How a License Key File is Verified

Basic Operation

Licensekeys operates via two connected pieces:

1. A server for creating and managing license keys that you then distribute.
2. A golang package that is embedded into your software application to verify a license key.

The server side is very simple; it creates and managing license keys. Licenses are created by gathering and signing data using a private key. The data and signature are stored in a text file which is then distributed to, or with, your software application.

The client golang package is used to verify a license key. Verification is done by comparing a license key file's data and signature against a public key where the public key is the matching pair to the private key used to generate the signature. This package also provides tooling for easily accessing any data stored in the license you may need in your application.

License Key File Example

A license key is a human readable text file with a signature verifying its authenticity.

• Human readability allows for people to understand what is "in" their license.
• Text files are easy to distribute.
• Signature ensures that if anything is changed in the file, the license will be invalid.
• Standardized format with custom fields added as needed.

    LicenseID: 10023
    AppName: Example
    CompanyName: ACME Dynamite
    ContactName: Wyle E Coyote
    PhoneNumber: 123-555-1212
    Email: [email protected]
    IssueDate: "2022-05-07"
    IssueTimestamp: 1651958341
    ExpireDate: "2049-09-21"
    Extras:
      CF_String: Hello World!
      Custom Boolean: true
      Custom Field Integer: 5
      Decimal: 5.55
    Signature: GBDAEIIAYPGNFZPDUQHMJ2WDQ4NETOLA4EZZVJ2LWVXIRGBZ6SKGMULV3ESAEIIA2QXHQ2HXLSIF7CUWZVLILT4FNKKDXHOLALM5QV3HQV5K4QWMVICQ====

Details

• Server is a webapp with very minimal requirements (1 CPU & 512 MB of RAM is plenty).
• SQLite database.
• Define any number of applications to generate licenses for.
• Each application can have one or more public-private key pairs for key rotation, development versus production, etc.
• Key pairs can be RSA, ECDSA, or ED25519.
• Private keys can be encrypted at rest.
• License key files can be either JSON or YAML formatted.
• Customize each license with custom fields set when a license is created.
• API to create and retrieve licenses.
• User permissions and audit logging.

Installing

The server can be run by cloning this repo and running go run main.go. You may prefer to build with go build and then run with ./licensekeys. A default configuration file with be created and the database will be deployed upon first run.

To use the client package to verify a license key in your application, run go get github.com/c9845/licensekeys/v2/licensefile@latest in go project's repo. See the client-app.go example in the _example directory at the root of this repo for an idea of how to get started.

Getting Values From A License Key

You can retrieve data from a license key in your software application as needed. For top-level, standard fields, just use f.LicenseID. For accessing custom data in the Extras field, use one of the ExtraAs...() funcs based on the field's value type.

Note that you should only access a license's data after you have verified the license first. You cannot trust the data has not been modified before the license key is verified.

How A License Key File is Created

1. The data for a license key is gathered.
2. The data is hashed.
3. The hash is signed by a private key.
4. The signature is encoded into a textual format.
5. The data and signature are written to a file.

How a License Key File is Verified

1. The license key file is read by your application.
2. The file's data is parsed and the signature is decoded.
3. The data is hashed and compared against the decoded signature using a public key; the response tells you if the license key is authentic.
4. Check if the license is still active (not expired).

Example of Client-Side Validation of License:

Please also see the example in the _example/client-app.go.

//Read the license file.
lic, err := licensefile.Read("/path/to/license.txt", licensefile.FileFormatYAML)
if err != nil {
  //Handle error reading file (file doesn't exist, corrupt, etc.)
}

//Verify the signature.
err = lic.VerifySignature([]byte(publicKey), licensefile.KeyPairAlgoED25519)
if err == licensefile.ErrBadSignature {
  //Handle invalid license file.
} else if err != nil {
  //Handle other error.
}

//Make sure license has not expired.
expired, err := lic.Expired()
if err != nil {
  //Handle error.
}
if expired {
  //Handle expired license
}

Development & Contributing

• Client Side JS:
  • Code is located in in .ts files in the website/static/js/ directory.
  • Code is split into different files based on their usage to organize code better.
  • The .ts files must be combined into one script.js file as per the tsconfig.json file.
  • The script.js file must be minified. minify is used for this.
  • Note the tasks in .vscode/tasks.json to help automate this.
  • Cache busting is handled by the app itself at runtime.
  • Uses Vue 2.x, but not single file components. Just import the Vue .js file in a <script> tag.
• Client Side CSS:
  • Written in one big CSS file located at website/static/css/styles.css.
  • The styles.css file must be minified. minify is used for this.
  • Note the task in .vscode/tasks.json to help automate this.
  • Cache busting is handled by the app itself at runtime.
• HTML Templates:
  • Stored in website/templates/.
  • Use a combination of golang and Vue templating.
  • Most templates are simple HTML with little data. Vue loads data via API calls to populate the templates.
• Backend Go code:
  • Broken apart into many sub-packages for better organization.
  • Database schema is defined in code to allow deploying of new databases as needed.
  • Each database table is stored in a separate file for better organization. These files hold most db queries as well.
  • Can be built into a static binary; CGO is not needed.
  • Embeds HTML, CSS, and JS files into binary for easier distribution of the app.