-
Notifications
You must be signed in to change notification settings - Fork 40
EVS
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.
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 andpersistent
for offline playback capable applications. No need to allow for future developments, you can change the signing kind at any time!
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.
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.
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.
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.
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: 3pl@castlabs.com
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
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 EVS account handling CLI provides the following interface:
% python3 -m castlabs_evs.account --help
usage: account.py [-h] [-v] [-n]
{signup,sup,resend,rs,confirm-signup,csup,update,up,reset,res,confirm-reset,cres,refresh,r,deauth,da,reauth,ra,delete,del}
...
options:
-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,resend,rs,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
resend (rs) resend EVS account confirmation code
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 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] [-H NAME_HINT] [-M MIN_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_HINT
and EVS_MIN_DAYS
.
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.