`castlabs-evs` is a package that provides a client for the [EVS service](https://github.com/castlabs/electron-releases/wiki/EVS) for [Electron for Content Security](https://github.com/castlabs/electron-releases). EVS provides production Widevine/VMP signing of application packages derived from official releases of Electron for Content Security. It is a free service, but requires signup to use.

As part of the Widevine 3PL program castLabs also offers [commercial VMP certification](https://github.com/castlabs/electron-releases/wiki/EVS#3pl) of custom Chromium/Electron adaptations, which enables the use of EVS for signing custom builds.

`castlabs-evs` supports Python 3.7+ and can be installed with:
```
% python3 -m pip install castlabs-evs
```

This installs the EVS client which provides Python and 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.

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 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.

The Python interfaces are not currently documented, but the CLI provides help sections that can be accessed:
```
% python3 -m castlabs_evs.account --help
usage: account.py [-h] [-v] [-n] [--connect-timeout CONNECT_TIMEOUT] [--auth-timeout AUTH_TIMEOUT]
                  {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

timeout options:
  --connect-timeout CONNECT_TIMEOUT
                        connection timeout in seconds (default: 60)
  --auth-timeout AUTH_TIMEOUT
                        auth request timeout in seconds (default: 60)

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
```
```
% python3 -m castlabs_evs.vmp --help
usage: vmp.py [-h] [-v] [-n] [-a] {verify,v,sign,s,verify-pkg,vp,sign-pkg,sp} ...

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
  -a, --any-ski         verify any subject key identifier

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
```

The `sign` command supports a number of transfer options for controlling timeouts and upload behaviour:
```
% python3 -m castlabs_evs.vmp sign --help
usage: vmp.py sign [-h] [-s] [-p] [-i] [-M MIN_DAYS] [-f] [-z] [-A ACCOUNT_NAME] [-P PASSWD]
                   [--connect-timeout CONNECT_TIMEOUT] [--auth-timeout AUTH_TIMEOUT]
                   [--upload-url-timeout UPLOAD_URL_TIMEOUT] [--upload-timeout UPLOAD_TIMEOUT]
                   [--sign-timeout SIGN_TIMEOUT] [--multipart-threshold MULTIPART_THRESHOLD]
                   [--multipart-part-size MULTIPART_PART_SIZE] [--multipart-retries MULTIPART_RETRIES]
                   [--multipart-max-concurrency MULTIPART_MAX_CONCURRENCY]
                   bin [sig]

positional arguments:
  bin                   path to binary
  sig                   path to signature

options:
  -h, --help            show this help message and exit
  -s, --streaming       streaming only signature (default)
  -p, --persistent      streaming and persistent download signature
  -i, --intermediate    generate intermediate signature
  -M, --min-days MIN_DAYS
                        minimum number of remaining valid days
  -f, --force           force new signature
  -z, --gz              request gzip upload (slower for fast connections)
  -A, --account-name ACCOUNT_NAME
                        provide account name [CACHED]
  -P, --passwd PASSWD   provide account password

transfer options:
  --connect-timeout CONNECT_TIMEOUT
                        connection timeout in seconds (default: 60)
  --auth-timeout AUTH_TIMEOUT
                        auth request timeout in seconds (default: 60)
  --upload-url-timeout UPLOAD_URL_TIMEOUT
                        upload URL request timeout in seconds (default: 60)
  --upload-timeout UPLOAD_TIMEOUT
                        upload request timeout in seconds (default: 300)
  --sign-timeout SIGN_TIMEOUT
                        sign request timeout in seconds (default: 120)
  --multipart-threshold MULTIPART_THRESHOLD
                        multipart upload threshold in MB (default: 100, min: 20)
  --multipart-part-size MULTIPART_PART_SIZE
                        multipart upload part size in MB (default: 50, min: 20)
  --multipart-retries MULTIPART_RETRIES
                        multipart upload max retries (default: 3)
  --multipart-max-concurrency MULTIPART_MAX_CONCURRENCY
                        multipart upload max concurrent connections (default: 2)
```

Binaries larger than `--multipart-threshold` (default 100 MB) are automatically uploaded using S3
multipart upload, which enables parallel, resumable transfers with configurable part size and
concurrency. The `-z`/`--gz` flag enables gzip compression of the upload stream, which can reduce
transfer size at the cost of additional CPU overhead.

# Legal notice / Disclaimer

THIS SOFTWARE 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.
