FAQ

What is CodeNotary at a high level?

CodeNotary brings trust and integrity to DevOps and the software industry. It allows development teams to strongly identify and track their digital assets and artifacts, such as libraries, builds, source code, containers, and dependencies throughout the DevOps process. This way organizations can always guarantee the veracity and integrity of their digital assets to themselves as a team and to others outside the team. By using digital ledger technology, it creates an immutable chain of trust and for the first time enables zero trust to be infused into application development and operation.

 

What is CodeNotary’s core functionality?

CodeNotary allows software publishers to sign their source code and binaries in 1 simple step. Once signed, assets can easily be verified by their customers. Through the CodeNotary dashboard, software publishers can analyze the use of their signed assets: when they were signed, how many times they have been verified, and by whom. Finally, when an asset must be retired from the market because it’s buggy or obsolete, software publishers can quickly recall it by revoking its signature. CodeNotary uses the blockchain to notarize signatures, instead of old fashioned Digital Certificate Authorities.

 

Who is vChain?

vChain is the company behind CodeNotary. It’s based in the US. You can read more about vChain at www.vchain.us

 

What is an asset?

In CodeNotary terms, an asset, or software asset, is any type of software application or component, such as a piece of code, a binary, an application, a container or server image, a repository, a script, a patch/fix, etc.

What are the possible statuses an asset can have?

Software assets can have three statuses in CodeNotary:

  1. Trusted
  2. Untrusted
  3. Unsupported
  4. Unknown

A software asset signed by its owner is set to ‘Trusted’ status. The same owner can decide to untrust it, meaning that the software should not be used by any customer. The asset will then appear to all CodeNotary users as ‘Untrusted’. Also, if the software becomes obsolete or simply unsupported, its owner can change its status to ‘Unsupported’. Both ‘Untrusted’ and ‘Unsupported’ status push to the customers of that software asset a notification for upgrading. Lastly, any asset that has never been signed using CodeNotary, is categorized as ‘Unknown’.

What are asset levels good for?

Asset’s levels are representative of the software publisher’s identification level when the asset was signed. In CodeNotary there are 4 Levels: L1, L2, L3, L4. For more information on the software publishers level, see “What is the software publishers’ level?” section below.

What does a software publishers’ level mean?

Software publishers can have 4 Levels of identification: L1, L2, L3, and L4. L1 (email-verified) is a software publisher whose email has been verified. L2 (social verification) is granted when the software publisher has also provided the details of a social account (either LinkedIn or GitHub or GitLab) that was successfully verified. L3 (ID verified) is granted when the publisher has provided a copy of their state of national picture ID such as a driver’s license, passport, etc. Finally, L4 (proof of address) is granted when the publisher has proved their official address.

How do I sign an asset?

Once you have created your account on the CodeNotary Dashboard and installed the CodeNotary Command Line Interface (CLI), you are then able to sign your software assets from the CodeNotary CLI simply by typing “vcn sign <asset-name>”. For more details on CLI commands, visit our GitHub page here.

What happens when I sign an asset?

The unique composition of your file is used to produce a unique signature (digital fingerprint) of your file using a U.S. National Security Agency-approved algorithm. The fingerprint (and only the fingerprint, not the file itself) is then automatically stored on the blockchain. There it remains forever, exactly the same as it was when it was originally created, never to be changed.

 

How do I verify an asset?

Software assets can be verified from the CodeNotary command line interface typing “vcn verify <asset-name>”. Alternatively, you can install our Google Chrome extension or  use the verify.codenotary.io drag and drop page. 

What happens when I verify an asset?

When you verify a file that claims to be a copy of the original, a fingerprint of that copy is quickly created for comparison to the original file fingerprint. (Neither the comparison file or its fingerprint are stored on the blockchain.) If the two fingerprints match, you have an authentic, unchanged copy. If not, you know the file copy has been modified (maliciously or otherwise). For more information on verifying, check out our video on the ‘3 Ways to Verify’ using CodeNotary.

 

How do I change the status of an asset?

To change the status of a software asset you just need to run the command “vcn untrust” or “vcn unsupport” from CodeNotary Command Line Interface.

What is CodeNotary Command Line interface?

CodeNotary offers a simple to use command line interface to run its basic commands: sign, verify, untrust, list, etc. The command line interface can be downloaded on our GitHub page here

How do I delete an asset from CodeNotary?

CodeNotary stores the assets on a blockchain, which makes the solution immutable and tamper-proof. For this reason, assets cannot be deleted from CodeNotary, but their status can be changed to ‘Untrusted’ or ‘Unsupported’ in order for your customers to know they should no longer use that asset. Assets can also be set to either private or public visibility, which means the publisher’s information is visible to the greater audience or not depending on this attribute. For more information on Private/public Assets, see the “What are private and public assets?” section below.

What are private and public assets?

In CodeNotary, assets can be signed as private or public. When an asset is public, no information about its owner is shared with the public. Users will still be able to see the asset has been signed with CodeNotary and when, but they will not know who signed it. On the other side, Public assets are assets’ whose owner information is visible and accessible to anyone using CodeNotary. By default, assets are signed as private. To sign them as public you need to add the switch “–public” as a parameter to the “vcn sign” command. The most recent status will be applied to your asset (i.e. if you have signed an asset first as public and then as private, it would be considered private).

What is CodeNotary Dashboard?

CodeNotary offers a web-based dashboard where software publishers can manage their account and analyze their signed assets. It is possible through the dashboard to see if someone has verified your asset, how many times it has been verified, and when and by whom. On the dashboard, you can also see the history of a specific asset (e.g. if you signed it and then untrusted it) and manage status and level changes.

What happens if someone else has already signed my asset?

CodeNotary cannot control the signing process of a single asset. Nevertheless, as you sign your assets, CodeNotary is able to tell you if that same asset has been signed by someone else (visible on Dashboard under “conflicts” column) and take corrective actions when appropriate.

How can I upgrade to a new Level?

You can request your level to be upgraded from your dashboard in the “My Profile” section. Each user level requires a different set of information to be provided. To see what information is required by each level, see “What is the software publishers’ level?” section above.

What is a signing key?

The signing key is the cryptographic key used to sign assets in CodeNotary. At your first login through the Command Line Interface, CodeNotary generates a key store on your file system that contains a private key and a public key. The private key should never be shared with anyone, as it gives the ability to sign software under your identity. Your public key instead is automatically loaded by CodeNotary on your user profile to prove the ownership and identity of assets to a user that verifies them.

How do I create a signing key?

CodeNotary automatically creates your signing key when you log through the command line interface with the same user credentials you use to log into the dashboard.

How do I associate the signing Key to my profile?

During the signing key generation process, CodeNotary automatically associates the public portion of the key (i.e. your public key) to your profile. You will be able to check your public key directly on the dashboard

How to install CodeNotary?

–Windows installer

  1. Download codenotary_vcn_<version number>_setup.exe
  2. Run codenotary_vcn_<version number>_setup.exe. (NOTE: Windows might complain that the program is not trusted, although it was properly signed with a digital certificate from Sectigo, which you can verify that by checking the file properties
  3. Select the folder where you want to install CodeNotary

–Windows without installer (Download only)

  1. Download the binaries vcn-<version number>-windows-4.0-amd64.exe
  2. Copy the binaries in the working directory (e.g. c:/CodeNotary/)
  3. To make the command easier to use, we recommend renaming the binary file into “vcn” 

–Linux and Mac

  • Download the binaries  vcn_<version number>_<linux/darwin-10.6>_amd64
  • Copy the binaries in the working directory (e.g. $HOME/CodeNotary/)
  • To make the command easier to use, we recommend renaming the binary file into “vcn”

 

How do I uninstall CodeNotary?

–Windows installer

Run the uninstall.exe available on the CodeNotary installation directory.

–Windows without installer (Download only)

Delete all CodeNotary binaries from your computer.

–On Linux and Mac

Delete all CodeNotary binaries from your computer.

What happens if I lose my private key?

Without your private key, you will not be able to sign your assets or modify the status of already signed ones. For this reason, we highly recommend that you safely store your private key and make backups of it. In the event that you lose your private key, or that it gets compromised, you can generate a new signing key and get it associated again with your profile.

To generate a new signing key please run the command “vcn login” from the command line interface after you removed the old keystore (the .vcn directory) from your filesystem. In case you want to untrust all assets signed with the old key and sign them with the new one you can contact our support at support@vchain.us and request a force untrust of all your assets. 

You will be asked for proof of ownership during that process.

What happens if my private key is compromised or stolen?

In case your private key is not trusted anymore (compromised or stolen) we recommend the following steps:

  1. If you still have your private key, you can untrust all assets signed with it directly from the CLI
  2. Communicate the problem to support@vchain.us, we will disable the key and prevent it from signing new assets
  3. Create a new signing key. For that, you need to run the command “vcn login” from the command line interface after you removed the old keystore (the .vcn directory) from your filesystem
  4. Sign your assets with your new signing key

 

Is CodeNotary a Certificate Authority?

CodeNotary is an open and transparent software integrity notarization platform that does not require a central authority to operate. The identity of the software publishers using CodeNotary are verified by vChain (the company behind CodeNotary), during the onboarding process. vChain follows industry standards for its KYC (Know Your Customer). For this reason, vChain will also apply to become itself a Certificate Authority in late 2019.

Does CodeNotary replace GPG?

CodeNotary does not replace GPG, but rather complements it. GPG is mostly used for hashing code and applications, as proof of integrity. GPG mostly meant to secure email and encrypt data. The identity certification of the owner is managed through the GPG’s Web of Trust, which is known for being limited in scalability and performance. As a result, the identity of the software owner is rarely verifiable. CodeNotary provides a notarization platform that allows the verification of both the authenticity (i.e. owner’s identity) and the integrity of software. CodeNotary also allows signatures to be revoked with instant notification to the users, a process that GPG is unable to implement. In the coming future, CodeNotary will also allow software publishers to notarize the hash calculated using GPG or other hashing algorithms.

Does CodeNotary replace Digital Certificates?

CodeNotary does not replace digital certificates but rather complements them. Digital certificates are required by certain OS’s to allow installation of software without warnings. At the same time managing digital certificates is cumbersome and expensive, especially when the number of certificates in use is high. For this reason, digital certificates are used mostly for signing product releases, while scripts, fixes and other more granular assets are not signed. CodeNotary allows signing with infinite granularity. This means that software publishers can rely on 1 certificate product releases as further proof of integrity while using CodeNotary to sign all the more granular assets produced/modified at any stage of the development process. In addition, CodeNotary also allows signatures to be revoked with instant notification to all users, a process that digital certificates struggle to implement given their coarse granularity. In the coming future, CodeNotary will allow software publishers to notarize their digital certificates, to simplify and strengthen certificates management processes.