Passw0rd CLI

Virgil Security introduces to developers a Passw0rd CLI – an open source tool that provides commands for interacting with the Passw0rd Service. With minimal configuration, you can start using all of the functionality provided by the Passw0rd from your favorite terminal program.

• Linux shells – Use common shell programs such as Bash, Zsh, and tsch to run commands in Linux, macOS, or Unix.
• Windows command line – On Microsoft Windows, run commands in either PowerShell or the Windows Command Processor.

Content

• Installation
• Launching CLI
• Features
• Register your account and set up 2FA
• Commands usage
  • Log in the account
  • Log out the account
  • Create a new application
  • Get application list
  • Get an update token
  • Fetch an update token
  • Delete an update token
  • Update keys
  • Generate a secret key
• Passw0rd Demo
  • Enroll user record
  • Verify user record
  • Rotate user record
• License
• Support

Installation

The passw0rd CLI is provided as a binary file, and it is available for Mac OS, FreeBSD, Linux OS and Windows OS. Download the latest CLI package here: https://github.com/passw0rd/cli/releases.

Launching CLI

FreeBSD / Linux / Mac OS

Run the passw0rd CLI with the following command:

./passw0rd

or use sudo ./passw0rd when you need to run the command as an administrator

Windows OS

Run the passw0rd CLI with the following command:

passw0rd.exe
# or just `passw0rd`

Features

Using the passw0rd CLI you can:

• register and manage your FREE passw0rd account
• register and manage your passw0rd application
• get your passw0rd application credentials, such as: Application Token, Service Public Key, Application Secret Key
• try a passw0rd Demo

To get more information, run the passw0rd CLI or its command with the --help or -h option that displays full help list and available commands.

Register your account and set up 2FA

First, register your account with the following command:

./passw0rd account register my@email.com

You have to confirm your account by entering a confirmation code you got in the email and create your account password.

!!! Once you've confirmed your account and created an account password, the passw0rd CLI immediately asks you to set up two-factor authentication and to create a new passw0rd App (with a default application name) and an app_secret_Key. Accept the offer to get all the necessary credentials (app_token, service_public_key, app_secret_key) to start working with passw0rd service.

Second, set up two-factor authentication (2FA):

• Copy a QR link that you got in a passw0rd CLI
• Open the QR link in a browser or some application
• Scan the QR using your 2FA application
• Enter a 2FA code into a passw0rd CLI

To set up 2FA you have to use an application that generates secure 2 step verification tokens on your device. For example, you can download and install Google Authenticator or Authy.

As a result, you get your passw0rd's application credentials:

• application name
• application app_token
• server service_public_key
• client app_secret_key

Commands usage

The passw0rd CLI has the following usage syntax: passw0rd [global options] command [command options] [arguments...]

The examples below are given for the FreeBSD/Linux/Mac OS platforms.

Log in the account

To log into your prefer account use the following command structure:

./passw0rd login my@email.com

Log out the account

To log out the account use the following command structure:

./passw0rd logout my@email.com

Create a new application

To create a new passw0rd application:

• be sure you're logged in your account. To log in the account use the following command (2FA is required):

./passw0rd login my@email.com

• then, use the create command:

./passw0rd application create my_new_passw0rd_app

where:

• my_new_passw0rd_app - is the name of your new passw0rd application.

Get application list

To show all your registered applications use the following command:

./passw0rd application list

Get an update token

An update token is used to update a user's passw0rd record in your database and to get a new app_secret_key and service_public_key of a specific application.

To get an update token:

• be sure you're logged in your account. To log in the account use the following command (2FA is required):

./passw0rd login my@email.com

• then, use the rotate command;

./passw0rd application rotate <app_token>

where:

• <app_token> - is your application token.

as a result, you get your update_token.

Fetch an update token

In case you forgot your update_token you can fetch the latest one from the Passw0rd service using the following command:

./passw0rd application fetch-update-token <app_token>

Delete an update token

Delete the latest update_token available for current application:

./passw0rd application delete-update-token <app_token>

Update keys

This command is used to update the app_secret_key and service_public_key of a specific application

./passw0rd application update-keys <service_public_key> <app_secret_key> <update_token>

Generate a secret key

This command is used to generate a new app_secret_key:

./passw0rd keygen

Passw0rd Demo

Passw0rd CLI provides you with a Demo mode that allows you to try out passw0rd technologies and see how the functions work without setting up a passw0rd SDK.

To start working with a passw0rd Demo you need to have a registed passw0rd account and created application.

Enroll user record

The demo command allows you to create user's record:

./passw0rd --config passw0rd.yaml demo enroll user_password

where:

• passw0rd.yaml - a config file that contains your account credentials: app_token, service_public_key, app_secret_key. This file is not created by default. So, create passw0rd.yaml file, paste your account credentials into it and specify the pass to it.
• user_password - user password that he or she uses to sign in to your server side.

as a result, you get:

• encryption key - secret key, that can be used to encrypt user data (for example, photos)
• record - database passw0rd's record that is associated with the user.

Verify user record

The demo command allows you to verify user password with the record:

./passw0rd --config passw0rd.yaml demo verify user_password user_passw0rd_record

where:

• passw0rd.yaml - a config file that contains your account credentials: app_token, app_id, service_public_key, app_secret_key. This file is not created by default. So, create passw0rd.yaml file, paste your account credentials into it and specify the pass to it.
• user_password - user password that he or she uses to sign in to your server side.
• user_passw0rd_record - database passw0rd's record that is associated with the user.

As a result, you get an encryption key and information whether the password is correct or not.

Rotate user record

This function allows you to use a special update_token to update the user's record.

Use this flow only if your database has been COMPROMISED! When a user only needs to change his or her own password, use the enroll function (step 5) to replace the user's old record value in your database.

to update user's record:

• get your update_token using passw0rd CLI
• then use the update token function to create a new password_record for your users (you don't need to ask your users to create a new password because the original password is not changing, just the protected record of it in the passw0rd system).
• then update the record with the following command:

./passw0rd --config passw0rd.yaml demo update user_passw0rd_record update_token

where:

• passw0rd.yaml - a config file that contains your account credentials: app_token, service_public_key, app_secret_key. This file is not created by default. So, create passw0rd.yaml file, paste your account credentials into it and specify the pass to it.
• user_passw0rd_record - database user's record that is going to be updated.
• update_token - update token that you got using the update_token command.

As a result, you get an updated user's record.

Then, you have to update the app_secret_key and service_public_key of your application

./passw0rd application update-keys <service_public_key> <app_secret_key> <update_token>

As a result, you get new app_secret_key and service_public_key of your application.

So, now upgrade the passw0rd.yaml file with your new application credentials and use the verify user password step to check whether the password is correct or not.

License

See LICENSE for details.

Support

Our developer support team is here to help you. Find out more information on our Help Center.

Also, get extra help from our support team: support@VirgilSecurity.com.