freemansoft/python-vipaccess

A free software implementation of Symantec's VIP Access application and protocol

python-vipaccess

Table of Contents

• python-vipaccess
  • Table of Contents
  • Intro
  • Dependencies
    • Installation
  • Usage
    • Provisioning a new VIP Access credential
    • Display a QR code to register your credential with mobile TOTP apps
    • Generating access codes using an existing credential
      • Usage with a Docker container
      • Build the Docker container from this tree
    • Provisioning a new VIP Access credential with Docker
    • Display a QR code to register your credential with mobile TOTP apps with Docker
  • NOTES

This is a fork of cyrozap/python-vipaccess. Main differences:

• No dependency on qrcode or image libraries; you can easily use external tools such as qrencode to convert an otpauth:// URI to a QR code if needed, so it seems unnecessary to build in this functionality.
• Option to generate either the mobile (SYMC/VSMT) or desktop (SYDC/VSST) versions of the VIP Access tokens; as far as I can tell there is no real difference between them, but some clients require one or the other specifically. There are also some rarer token types/prefixes which can be generated if necessary (reference list from Symantec)
• Command-line utility is expanded to support both token provisioning (creating a new token) and emitting codes for an existing token (inspired by the command-line interface of stoken, which handles the same functions for RSA SecurID tokens

Intro

python-vipaccess is a free and open source software (FOSS) implementation of Symantec's VIP Access client (now owned by Broadcom).

If you need to access a network which uses VIP Access for two-factor authentication, but can't or don't want to use Symantec's proprietary applications—which are only available for Windows, MacOS, Android, iOS—then this is for you.

As @cyrozap discovered in reverse-engineering the VIP Access protocol (original blog post), Symantec VIP Access actually uses a completely open standard called Time-based One-time Password Algorithm for generating the 6-digit codes that it outputs. The only non-standard part is the provisioning protocol used to create a new token.

Dependencies

• Python 3.3+ (recommended) or 2.7 (not recommended)
• oath
• pycryptodome
• requests

For development purposes, you can install the dependencies with pip install -r requirements.txt in the project root directory.

To install pip see the pip installation documentation.

Installation

Install with pip3 to automatically fetch Python dependencies. (Note that on most systems, pip3 invokes the Python 3.x version, while pip invokes the Python 2.7 version; Python 2.7 is still supported, but not recommended because it's nearing obsolescence.)

# Install latest release from PyPI
$ pip3 install python-vipaccess

# Install latest development version from GitHub
$ pip3 install https://github.com/dlenski/python-vipaccess/archive/HEAD.zip

Usage

Provisioning a new VIP Access credential

This is used to create a new VIP Access token. It connects to https://services.vip.symantec.com/prov and requests a new token, then deobfuscates it, and checks whether it is properly decoded and working correctly, via a second request to https://vip.symantec.com/otpCheck.

By default it stores the new token in the file .vipaccess in your home directory (in a format similar to stoken), but it can store to another file instead, or instead just print out the "token secret" string with instructions about how to use it.

usage: vipaccess provision [-h] [-p | -o DOTFILE] [-i ISSUER] [-t TOKEN_MODEL]

optional arguments:
  -h, --help            show this help message and exit
  -p, --print           Print the new credential, but don't save it to a file
  -o DOTFILE, --dotfile DOTFILE
                        File in which to store the new credential (default
                        ~/.vipaccess)
  -i ISSUER, --issuer ISSUER
                        Specify the issuer name to use (default: Symantec)
  -t TOKEN_MODEL, --token-model TOKEN_MODEL
                        VIP Access token model. Often SYMC/VSMT ("mobile"
                        token, default) or SYDC/VSST ("desktop" token). Some
                        clients only accept one or the other. Other more
                        obscure token types also exist:
                        https://support.symantec.com/en_US/article.TECH239895.html

Here is an example of the output from vipaccess provision -p:

Generating request...
Fetching provisioning response from Symantec server...
Getting token from response...
Decrypting token...
Checking token against Symantec server...
Credential created successfully:
    otpauth://totp/VIP%20Access:SYMC12345678?secret=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&issuer=Symantec&algorithm=SHA1&digits=6
This credential expires on this date: 2019-01-15T12:00:00.000Z

You will need the ID to register this credential: SYMC12345678

You can use oathtool to generate the same OTP codes
as would be produced by the official VIP Access apps:

    oathtool    -b --totp AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA  # output one code
    oathtool -v -b --totp AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA  # ... with extra information

Here is the format of the .vipaccess token file output from vipaccess provision [-o ~/.vipaccess]. (This file is created with read/write permissions only for the current user.)

version 1
secret AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
id SYMC12345678
expiry 2019-01-15T12:00:00.000Z

Display a QR code to register your credential with mobile TOTP apps

Once you generate a token with vipaccess provision, use vipaccess uri to show the otpauth:// URI and qrencode to display that URI as a QR code:

qrencode -t UTF8 'otpauth://totp/VIP%20Access:SYMCXXXX?secret=YYYY&issuer=Symantec&algorithm=SHA1&digits=6'

Scan the code into your TOTP generating app, like

• FreeOTP
• Google Authenticator for Android or IOS
• Microsoft Authenticator for Android or IOS

Generating access codes using an existing credential

The vipaccess [show] option will also do this for you: by default it generates codes based on the credential in ~/.vipaccess, but you can specify an alternative credential file or specify the OATH "token secret" on the command line.

usage: vipaccess show [-h] [-s SECRET | -f DOTFILE]

optional arguments:
  -h, --help            show this help message and exit
  -s SECRET, --secret SECRET
                        Specify the token secret on the command line (base32
                        encoded)
  -f DOTFILE, --dotfile DOTFILE
                        File in which the credential is stored (default
                        ~/.vipaccess

Usage with a Docker container

You can generate tokens without modifying your desktop machine if you have docker installed.

Build the Docker container from this tree

This assumes you have the GIT repository checked out and are in a terminal in the root of the repo. The assembled Docker image is relatively lightweight at 150MB. Build the python-vipaccess container with

docker build . -t python-vipaccess

Provisioning a new VIP Access credential with Docker

Generate the otp string for the TOTP applications. This URL can also be used to import the generated credentials as an additional identifier in a Symantec VIP application.

docker run python-vipaccess provision -p

or the following if you wish to change the ID prefix to something like SYMC

docker run python-vipaccess provision -p -t SYMC

Display a QR code to register your credential with mobile TOTP apps with Docker

Convert the URL into a scannable QR code using qrencode bundled with the container. The scannable QR code will display using ANSI graphics in a terminal window.

Replace otpauth:// with the otpauth string generated in the step above.

docker run --entrypoint "qrencode" python-vipaccess -t ANSI256 otpauth://...

NOTES

As alluded to above, you can use other standard OATH-based tools to generate the 6-digit codes identical to what Symantec's official apps produce.