EVS

NOTE: This is a 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. Since the Linux Widevine CDM does not support VMP, and thus does not require a VMP signature, EVS does not provide signing of Linux binaries. It is a free service, but requires signup to use.

As part of the Widevine 3PL program castLabs also offers commercial VMP certification of custom Chromium/Electron adaptations, which enables the use of EVS for signing custom builds. See the 3PL subsection for more details about this.

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. avoiding 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 []: [email protected]
>> 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.

Logging in to an existing account (or switching accounts)

You can log in to an existing EVS account on a new machine, or switch accounts, by executing:

% python3 -m castlabs_evs.account reauth
Discarding authorization token(s)
Refreshing authorization token(s)
>> Account Name [example]: 
>> Password []: XXXXXXXX

The previously used account name, if there is one, is pre-filled and just requires you to hit enter. If you want to switch accounts you need to enter the new account name instead.

Refreshing the authorization tokens

Your authorization tokens have a limited lifespan and needs to be refreshed periodically, currently every month. This is typically handled automatically while signing, by asking you for your credentials if necessary, but in cases with build automation it may be necessary to manually refresh your tokens every once in a while to avoid distruption of the automated scripts. You can explicitly re-authenticate, and thus refresh your authorization tokens, by using the command described in the Logging in to an existing account (or switching accounts) section above.

Signing an ECS 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.vmp sign-pkg path/to/package-directroy
Signing: path/to/package-directroy/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.vmp sign-pkg --persistent path/to/package-directroy
Signing: path/to/package-directroy/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!

The path/to/package-directroy means the path to the directory that contains your .app or .exe, NOT the path to the .app or .exe themselves. You can pass multiple paths to sign several packages in one go.

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.

3PL

As a partner in the Widevine 3PL program castLabs can offer commercial VMP certification of custom Chromium/Electron adaptations. This involves an audit of the application and the relevant code to make sure it adheres to the requirements of VMP.

Once an implementation is audited commercial 3PL access to EVS is granted, which allows VMP signing of the custom application builds for select user accounts. Such builds are signed using a different set of, 3PL specific, VMP certificates. As these implementations may not follow the same layout as ECS, especially in the case of custom Chromium adaptations, the convenience of the sign-pkg/verify-pkg commands of the EVS client may not be possible to use (see the 3PL client requirements and Signing a 3PL application subsections).

For more details, contact castLabs at: [email protected]

3PL client requirements

To be able to successfully use EVS for 3PL signing these requirements need to be fulfilled:

• You need a recent EVS client, currently 1.0.0rc5 or later
• 3PL audit needs to be finished and 3PL access enabled for your account
• You need to refresh your authorization tokens after 3PL access is enabled for your account

Signing a 3PL application

If your application uses the same layout as ECS, you can use the somewhat easier method described in the Signing an ECS application package section, as it does not require knowledge of the specific locations of the signature file for different platforms.

To sign an application you would typically do this after building/packaging but before zipping the final package up. 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 executable for streaming you would execute something like this:

% python3 -m castlabs_evs.vmp sign path/to/executable path/to/signature
Signing: path/to/executable
Verifying any existing VMP signature
 - Signature invalid: Failed to verify signature
 - Requesting VMP signature

In case path/to/signature is left out, .sig will be appended to path/to/executable and used as the VMP signature file. You need to take care to place the signature in the specific location searched by your implementation of VMP, which can vary between platforms due to the different layout of typical application packages.

You can also request persistent signing by adding the --persistent option to the above command line.

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 directory

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.