From 2da6c24dd9f2f2d440a37ff1419353f5c6a7e73e Mon Sep 17 00:00:00 2001 From: James Cuzella Date: Tue, 28 Jan 2020 17:37:05 -0700 Subject: [PATCH] Hello future people. Here is how to use, test, and build this project! --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/README.md b/README.md index 5098304..ad1f538 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,153 @@ version: _E4.5.3 (r39012)_ 64-bit (x64) unicode Windows Registry I/O tested on Windows 7 x64 Professional +Python Installation: +------------------- + +This python script was built with and only supports Python 2! If you are from the future, or accessing this via the [GitHub Arctic Code Vault 02/02/2020][5], First of all... congratulations on surviving! If this code is useful to you, you may need to obtain a version of Python 2.7. Alternatively, you may use the Python `2to3` utility to convert this source code for use with Python 3 (may take some testing & development to get working on all platforms). + +To install Python 2.7.17 (Latest version as of 01/28/2020. Python 2 End of Life was 01/01/2020): + +### macOS / Linux: +If your system does not have an available `python2` in `PATH` linked: + + # Make sure you have build dependencies installed on your platform: + # For example: GNU make, gcc / g++ compiler, build-essential package, etc... + # Find and/or download Python 2.7 + curl -L -o /tmp/python-v2.7.17.tar.gz https://github.com/python/cpython/archive/v2.7.17.tar.gz + tar -xvf /tmp/python-v2.7.17.tar.gz + cd cpython-2.7.17/ + ./configure + make + sudo make install + # OR: sudo make altinstall + + # Symlink `python2` to the resulting python2.7 binary + # For example: + ln -sf /usr/local/bin/python2.7 /usr/local/bin/python2 + + +### Windows: + +Please refer to the [`python/cpython/PCbuild/readme.txt`][6] for Windows-specific build instructions (Microsoft Visual Studio 2017). The basic idea is to make sure you have build & compilation dependencies installed for Windows platform, and run the `build.bat` script. + +Excerpt: + +> Building Python using the build.bat script +> ---------------------------------------------- +> +> In this directory you can find build.bat, a script designed to make +> building Python on Windows simpler. This script will use the env.bat +> script to detect either Visual Studio 2017 or 2015, either of +> which may be used to build Python. Currently Visual Studio 2017 is +> officially supported. +> +> By default, build.bat will build Python in Release configuration for +> the 32-bit Win32 platform. It accepts several arguments to change +> this behavior, try `build.bat -h` to learn more. + +Installation: +------------- + +This project installs from source via: + + git clone https://github.com/trinitronx/vncpasswd.py.git vncpasswd.py + cd vncpasswd.py + python2 ./vncpasswd.py --help + +Note: The "shebang" line at the top of the python script is: `#!/usr/bin/env python2` + +If you have `python2`, and `/usr/bin/env` binaries available in your system's `PATH`, you should be all set up to just run the executable script file as-is: `./vncpasswd.py` + +To build a Docker image, or Python Source Distribution, see below or run `make help` to see all available `Makefile` targets. + +Usage: +------ + +The `help` output explains the command line flags: + +> usage: vncpasswd.py [-h] [-d] [-e] [-H] [-R] [-f FILENAME] [-t] [passwd] +> +> Encrypt or Decrypt a VNC password +> +> positional arguments: +> passwd A password to encrypt +> +> optional arguments: +> -h, --help show this help message and exit +> -d, --decrypt Decrypt an obfuscated password. +> -e, --encrypt Encrypt a plaintext password. (default mode) +> -H, --hex Assume input is in hex. +> -R, --registry Input or Output to the windows registry. +> -f FILENAME, --file FILENAME +> Input or Output to a specified file. +> -t, --test Run the unit tests for this program. + +### Docker: + +The docker container is ready-built with all dependencies needed. Just mount in your file (e.g.: `-v $HOME/.vnc/:$HOME/.vnc`, or just `-v $HOME:$HOME`), and run: + + # Decrypt ~/.vnc/passwd + docker run -ti -v $HOME:$HOME -w $HOME trinitronx/vncpasswd.py -d -f ~/.vnc/passwd + + # More Examples: + # Encrypt string 'foo' + docker run -v $HOME:$HOME -w $HOME -ti trinitronx/vncpasswd.py -e 'foo' + # Encrypt string 'bar' and output to ~/.vnc/passwd + mkdir -p $HOME/.vnc/ + docker run -v $HOME:$HOME -w $HOME -ti trinitronx/vncpasswd.py -e 'foo' -f ~/.vnc/passwd + # Encrypt string 'bar' as HEX input + docker run -v $HOME:$HOME -w $HOME -ti trinitronx/vncpasswd.py -e -H '6261720000000000' + # Decrypt the encrypted password 'bar' as HEX input + docker run -v $HOME:$HOME -w $HOME -ti trinitronx/vncpasswd.py -d -H '9ca3f3686574f277' + +Testing: +-------- + +This project used TravisCI for Continuous Integration & Continuous Deployment to Docker Hub. The `.travis.yml` contains the build steps. To test this project, install build dependencies & run the tests: + + pip install --user -r ./build/build-requirements.txt + make test + +Python Source Distribution: +--------------------------- + +To create a python source distribution via `setuptools`: + + make setup + +Docker Image Build: +------------------- + +Make sure you have Docker installed on your system, and run: + + make package + +DockerHub / Repository Image Ship: +---------------------------------- + +To ship this image to either DockerHub, or your Docker Image repository of choice, just export the following variables: + + DOCKER_USERNAME=your-username + DOCKER_PASSWORD=your-password + +Then run: + + # DockerHub by default + make ship + + # Alternate Repository + # Override & export these variables set in `./build/main.mk`: + # REGISTRY ?= docker.io + # REPO_NAME ?= $(BIN) + # REPO ?= $(REGISTRY)/trinitronx/$(REPO_NAME) + export REGISTRY=quay.io + export REPO_NAME=your-reponame + export USERNAME=your-username + export REPO=$REGISTRY/$USERNAME/$REPO_NAME + make ship + + Thanks / Props -------------- @@ -59,3 +206,7 @@ References: "Email Thread: Registry Edit to define server password" [4]: http://www.realvnc.com/pipermail/vnc-list/2002-August/033007.html "Email Thread on User vs. System passwords: Password Shift" +[5]: https://archiveprogram.github.com/#arctic-code-vault + "GitHub Archive Program: Preserving open source software for future generations (Get your code into the GitHub Arctic Code Vault 02/02/2020)" +[6]: https://github.com/python/cpython/tree/master/PCbuild + "Building cPython on Windows: PCBuild/readme.txt" \ No newline at end of file