Skip to content
vChain CodeNotary
Branch: master
Clone or download
Latest commit 3655348 Jul 19, 2019

README.md

vcn - vChain CodeNotary CircleCI

code signing in 1 simple step

How it works

vcn How it works

Installation

Binary (Cross-platform)

It's easiest to download the latest version for your platform from the release page.

Once downloaded, you can rename the binary to vcn, then run it from anywhere.

For Linux and macOS you need to mark the file as executable: chmod +x vcn

Homebrew / Linuxbrew

If you are on macOS and using Homebrew (or on Linux and using Linuxbrew), you can install vcn with the following:

brew tap vchain-us/brew
brew install vcn

From Source

After having installed golang 1.12 or newer clone this repository into your working directory.

Build locally

You can build vcn in the working directory using the provided Makefile.

make vcn

Then run

./vcn

System-wide

This will put the vcn executable into GOBIN which is accessible throughout the system.

make install

Usage

For detailed command line usage see docs/cmd/vcn.md or just run vcn help.

Furthermore, check out our list of integrations:

Basic usage

Register an account with codernotary.io first.

Then start with the login command. vcn will walk you through login and setting up your local keystore upon initial use.

vcn login

You're good to use verify without the above registration.

vcn verify <file>
vcn verify dir://<directory>
vcn verify docker://<imageId>
vcn verify --hash <hash>

Output results in json or yaml formats:

vcn verify --output=json <asset>
vcn verify --output=yaml <asset>

Check out the user guide for further details.

Once your public key is known on the blockchain you can sign assets:

vcn sign <file>
vcn sign dir://<directory>
vcn sign docker://<imageId>
vcn sign --hash <hash>

By default all assets are signed private, so not much information is disclosed about the signer. If you want to make it public and therefore, more trusted, please use the --public flag.

vcn sign --public <file>
vcn sign --public docker://<image>

Change the asset's status:

vcn unsupport <asset>
vcn untrust <asset>

Fetch all assets you've signed:

vcn list

Have a look at analytics and extended functionality on the dashboard (browser needed):

vcn dashboard

Examples

Verify a Docker image automatically prior to running it

First, you’ll need to pull the image by using:

docker pull hello-world

Then use the below command to put in place an automatic safety check. It allows only verified images to run.

vcn verify docker://hello-world && docker run hello-world

If an image was not verified, it will not run and nothing will execute.

Verify multiple assets

You can verify multiple assets by piping other command outputs into vcn:

ls | xargs vcn verify

The exit code will be 0 only if all the assets in you other command outputs are verified.

Verify by a specific signer

By adding --key, you can verify that your asset has been signed by a specific signer’s public key.

vcn verify --key 0x8f2d1422aed72df1dba90cf9a924f2f3eb3ccd87 docker://hello-world

Verify by a list of signers

If an asset you or your organization wants to trust needs to be verified against a list of signers as a prerequisite, then use the vcn verify command and the following syntax:

  • Add a --key flag in front of each key you want to add
    (eg. --key 0x0...1 --key 0x0...2)
  • Or set the env var VCN_KEY correctly by using a space to separate each key (eg. VCN_KEY=0x0...1 0x0...2)

Be aware that using the --key flag will take precedence over VCN_KEY.

The asset verification will succeed only if the asset has been signed by at least one of the signers.

Verify using the asset's hash

If you want to verify an asset using only its hash, you can do so by using the command as shown below:

vcn verify --hash fce289e99eb9bca977dae136fbe2a82b6b7d4c372474c9235adc1741675f587e

Unsupport/untrust an asset you do not have anymore

In case you want to unsupport/untrust an asset of yours that you no longer have, you can do so using the asset hash(es) with the following steps below.

First, you’ll need to get the hash of the asset from your CodeNotary dashboard or alternatively you can use the vcn list command. Then, in the CLI, use:

vcn untrust --hash <asset's hash>
# or 
vcn unsupport --hash <asset's hash>

Signing within automated environments

First, you’ll need to make vcn have access to the ${HOME}/.vcn folder that holds your private keys. Then, set up your environment accordingly using the following commands:

export VCN_USER=<email>
export VCN_PASSWORD=<password>
export KEYSTORE_PASSWORD=<passphrase>

Once done, you can use vcn in your non-interactive environment using:

vcn login
vcn sign --key <your key> <asset>

Other commands like untrust and unsupport will also work.

Working with Docker and Kubernetes

Check out our integrations:

Configuration

See docs/user-guide/configuration.md.

Environments

See docs/user-guide/environments.md.

Testing

make test

Cross-compiling for various platforms

The C libraries of go-ethereum make a more sophisticated cross-compilation necessary. The make dist target takes care of all steps by using xgo and docker.

License

This software is released under GPL3.

You can’t perform that action at this time.