EVS

NOTE: This is an currenty an early release candidate of the EVS service & client, please report any issues you encounter here.

The Electron for Content Security VMP signing, EVS, service provides production Widevine/VMP signing of macOS/Windows application packages derived from official releases of Electron for Content Security, from v6 and onwards. It is a free service, but requires signup to use.

The EVS client is published as a Python 3.7+ module, castlabs-evs, and can be installed/upgraded from PyPi with:

% python3 -m pip install --upgrade castlabs-evs

The EVS client provides CLI interfaces for account handling and VMP signing. If the pip module binary directory is in your PATH the two convenience scripts evs-account and evs-vmp can be used in place of python3 -m <module> in the examples below. It can be advantageous to use a Python virtual environment to achieve separation, script access, and also reduce platform dissimilarities (e.g. avoid py -3 vs python3 on Windows) in one go.

The CLI interfaces are interactive by default, asking for any information they cannot load from its configuration, unless they are provided through CLI arguments or as environment variables. This behaviour can be overridden by not providing a TTY on STDIN, or by passing the --no-ask option or setting EVS_NO_ASK in the environment, in which case any missing required information will trigger a runtime error instead, making them more suitable for automation.

Rules of Conduct

This is a free service provided as a convenience for users of Electron for Content Security and as such we do ask that you abide by these simple rules of conduct to help us keep it that way:

• Avoid creating extranous accounts, use password reset instead in case you get locked out of your account.
• Avoid routinely forcing a VMP signature request when the existing signature is valid.
• Use the signature kind that is appropriate for your application, streaming for streaming-only applications and persistent for offline playback capable applications. No need to allow for future developments, you can change the signing kind at any time!

Creating an EVS account

To create an EVS account you would execute something like this:

% python3 -m castlabs_evs.account signup
Signing up for castLabs EVS
 - A valid e-mail address is required for account verification
>> E-mail Address []: me@example.com
>> First Name []: Me
>> Last Name []: Example
>> Organization []: Example, Inc
>> Account Name []: example
>> Password []: XXXXXXXX
>> Verify Password []: XXXXXXXX
Confirming EVS account
 - A confirmation code has been sent to your e-mail address
>> Confirmation Code []: XXXXXX
Discarding authorization token(s)
Refreshing authorization token(s)

And that's it, you are all set to use the service. There are other accounting commands available in the CLI, for example if you need to reset your password, fix your information or force reauthorization (perhaps using a different account). All of this is described in the CLI help described below.

Signing an application package

To sign an application you would typically do this after building/packaging but before zipping the final package up. Packagers, like electron-builder offers hooks that can be used to automate this. By default a signature for streaming is generated, but a persistent signature can be requested by passing the appropriate CLI option.

If you are code-signing too, you need to take care to execute the VMP-signing at the right time for the platform. On macOS the VMP-signing needs to take place BEFORE the code-signing, whereas on Windows the VMP-signing needs to take place AFTER the code-signing, or things will break.

To sign an application package for streaming you would execute something like this:

% python3 -m castlabs_evs.account sign-pkg path/to/app
Signing: path/to/app/Electron.app
Verifying any existing VMP signature
 - Signature invalid: Failed to verify signature
Requesting VMP signature

Or if you need persistent signing, for downloaded content:

% python3 -m castlabs_evs.account sign-pkg --persistent path/to/app
Signing: path/to/app/Electron.app
Verifying any existing VMP signature
 - Signature is valid (persistent, min 90 days validity), forego signing

In this case the existing signature was already valid, and no signing request was actually executed!

If your access tokens have expired you may be asked to enter your credentials when the signing request is executed. To avoid this in automated scenarios you can override the behaviour by not providing a TTY on STDIN, or by passing the --no-ask option or setting EVS_NO_ASK in the environment, in which case an error will be raised instead.

There are other VMP commands and options available in the CLI, for example if you manually want to verify the signature. All of this is described in the CLI help described below.

The account handling CLI

The EVS account handling CLI provides the following interface:

% python3 -m castlabs_evs.account --help
usage: account.py [-h] [-v] [-n]
                  {signup,sup,confirm-signup,csup,update,up,reset,res,confirm-reset,cres,refresh,r,deauth,da,reauth,ra,delete,del}
                  ...

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -n, --no-ask          enable non-interactive mode

commands:
  {signup,sup,confirm-signup,csup,update,up,reset,res,confirm-reset,cres,refresh,r,deauth,da,reauth,ra,delete,del}
    signup (sup)        sign up for EVS account
    confirm-signup (csup)
                        confirm account signup
    update (up)         update account details
    reset (res)         reset account password
    confirm-reset (cres)
                        confirm account password reset
    refresh (r)         refresh authorization tokens
    deauth (da)         discard any authorization tokens
    reauth (ra)         discard any authorization tokens & refresh
    delete (del)        delete EVS account

Additional help for each sub-command can be viewed by passing --help to it, for example:

% python3 -m castlabs_evs.account refresh --help
usage: account.py refresh [-h] [-A ACCOUNT_NAME] [-P PASSWD]

optional arguments:
  -h, --help            show this help message and exit
  -A ACCOUNT_NAME, --account-name ACCOUNT_NAME
                        provide account name [CACHED]
  -P PASSWD, --passwd PASSWD
                        provide account password

All command line options can also be passed in as environment variables, using the same names as listed in the help-section prepended with EVS_, for example EVS_ACCOUNT_NAME and EVS_PASSWD.

The VMP signing CLI

The EVS VMP signing handling CLI provides the following interface:

% python3 -m castlabs_evs.vmp --help
usage: vmp.py [-h] [-v] [-n] {verify,v,sign,s,verify-pkg,vp,sign-pkg,sp} ...

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -n, --no-ask          enable non-interactive mode

commands:
  {verify,v,sign,s,verify-pkg,vp,sign-pkg,sp}
    verify (v)          verify signature
    sign (s)            refresh signature
    verify-pkg (vp)     verify electron package signature
    sign-pkg (sp)       refresh electron package signature

Additional help for each sub-command can be viewed by passing --help to it, for example:

% python3 -m castlabs_evs.vmp verify-pkg --help
usage: vmp.py verify-pkg [-h] [-s] [-p] [-N NAME] [-M DAYS] pkg [pkg ...]

positional arguments:
  pkg                   path to electron package

optional arguments:
  -h, --help            show this help message and exit
  -s, --streaming       streaming only signature (default)
  -p, --persistent      streaming and persistent download signature
  -H NAME_HINT, --name-hint NAME_HINT
                        provide name hint
  -M MIN_DAYS, --min-days MIN_DAYS
                        minimum number of remaining valid days

All command line options can also be passed in as environment variables, using the same names as listed in the help-section prepended with EVS_, for example EVS_NAME and EVS_MIN_DAYS.

Legal notice / Disclaimer

THIS SOFTWARE AND SERVICE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. UPDATES, INCLUDING SECURITY UPDATES, WILL BE PROVIDED ON A BEST-EFFORT BASIS.