2
0

Move instructions into cli-c for distribution.

This commit is contained in:
Maarten Billemont 2017-09-04 14:17:20 -04:00
parent 4261160902
commit cd70009c2c
3 changed files with 99 additions and 46 deletions

View File

@ -194,49 +194,7 @@ Note that in order to build the Android application, you will need to have the A
Go into the `platform-independent/cli-c` directory and run `./build`. The native command-line client will then be built. Go into the `platform-independent/cli-c` directory and run `./build`. The native command-line client will then be built.
When the build completes, you will have an `mpw` binary you can use. You can copy it into your `PATH` or use the `./install` script to help you do so. For detailed instructions, see [the native CLI instructions](platform-independent/cli-c/README.md).
For example:
./build && sudo ./install
mpw -h
Normally, this is all you need to do, however note that there are a few dependencies that need to be met, depending on which targets you are building (by default, only the `mpw` target is built):
- `mpw`
The C implementation depends either on `libsodium` or Tarsnap's `scrypt` and `openssl-dev`.
We recommend you install `libsodium`. If `libsodium` is not installed when `./build` is executed, the script will try to download and statically link Tarsnap's `scrypt` instead. Tarsnap's `scrypt` depends on you having `openssl-dev` installed.
If you have `mpw_color` enabled (it is enabled by default), the build also depends on `ncurses-dev` to communicate with the terminal.
- `mpw-bench`
This tool compares the performance of a few cryptographic algorithms, including bcrypt. The `./build` script will try to automatically download and statically link `bcrypt`.
- `mpw-tests`
This tool runs a suite of tests to ensure the correct passwords are being generated by the algorithm under various circumstances. The test suite is declared in `mpw-tests.xml` which needs to exist in the current working directory when running the tool. In addition, `libxml2` is used to parse the file, so this target depends on you having it installed when running `./build`.
Finally, there are a few different ways you can modify the build process.
To build additional targets, set the `targets` environment variable:
targets='mpw mpw-tests' ./build
To pass additional compiler arguments, eg. add a library search path, pass them as arguments to the script:
./build -L/usr/local/lib
There are a few toggleable features, to change them, pass them as environment variables:
mpw_color=0 ./build
Currently, there is only one toggleable feature:
- `mpw_color`: [default: 1] Colorized Identicon, depends on `ncurses-dev`.
## Support ## Support

View File

@ -0,0 +1,84 @@
# Native CLI
This is a command-line terminal interface to the Master Password standard implementation.
To use the app, you'll first need to build it, then install it into your system's PATH.
## Building
To build the code to run on your specific system, run the `build` command:
./build
Note that the build depends on your system having certain dependencies already installed.
By default, you'll need to have at least `libsodium`, `libjson-c` and `libncurses` installed.
### Details
The build script comes with a default configuration which can be adjusted. Full details on the build script are available by opening the build script file.
[targets='...'] [mpw_feature=0|1 ...] [CFLAGS='...'] [LDFLAGS='...'] ./build [cc arguments ...]
By default, the build script only builds the `mpw` target. You can specify other targets or `all` to build all available targets. These are the currently available targets:
- `mpw` : The main app. It needs: `mpw_sodium`, optionally supports: `mpw_color`, `mpw_json`.
- `mpw-bench` : A benchmark utility. It needs: `mpw_sodium`.
- `mpw-tests` : An algorithm test suite. It needs: `mpw_sodium`, `mpw_xml`.
It is smart to build the test suite along with the app, eg.:
targets='mpw mpw-tests' ./build
The needed and supported features determine the dependencies that the build will require. The following features exist:
- `mpw_sodium` : Use Sodium for the crypto implementation. It needs libsodium.
- `mpw_json` : Support JSON-based user configuration format. It needs libjson-c.
- `mpw_color` : Show a colorized identicon. It needs libncurses.
- `mpw_xml` : Support XML parsing. It needs libxml2.
By default, all features are enabled. Each feature can be disabled or enabled explicitly by prefixing the build command with an assignment of it to `0` or `1`, eg.:
mpw_color=0 ./build
As a result of this command, you'd build the `mpw` target (which supports `mpw_color`) without color support. The build no longer requires `libncurses` but the resulting `mpw` binary will not have support for colorized identicons.
You can also pass CFLAGS or LDFLAGS to the build, or extra custom compiler arguments as arguments to the build script.
For instance, to add a custom library search path, you could use:
LDFLAGS='-L/usr/local/lib' ./build
## Testing
Once the client is built, you should run a test suite to make sure everything works as intended.
There are currently two test suites:
- `mpw-tests` : Tests the Master Password algorithm implementation.
- `mpw-cli-tests` : Tests the CLI application.
The `mpw-tests` suite is only available if you enabled its target during build (see "Details" above).
The `mpw-cli-tests` is a Bash shell script, hence depends on your system having Bash available.
## Installing
Once you're happy with the result, you can install the `mpw` application into your system's `PATH`.
Generally, all you need to do is copy the `mpw` file into a PATH directory, eg.:
cp mpw /usr/local/bin/
The directory that you should copy the `mpw` file into will depend on your system. Also note that `cp` is a POSIX command, if your system is not a POSIX system (eg. Windows) you'll need to adjust accordingly.
There is also an `install` script to help with this process, though it is a Bash script and therefore requires that you have Bash installed:
./install
After installing, you should be able to run `mpw` and use it from anywhere in the terminal:
mpw -h
mpw google.com

View File

@ -45,9 +45,20 @@ fi
echo echo
inf "You can also save your user name in ~/.bashrc. Leave blank to skip this step." inf "You can also save your user name in ~/.bashrc. Leave blank to skip this step."
if MP_FULLNAME=$(ask "Your full name:") && [[ $MP_FULLNAME ]] ; then if MPW_FULLNAME=$(ask "Your full name:") && [[ $MPW_FULLNAME ]] ; then
printf 'export MP_FULLNAME=%q\n' "$MP_FULLNAME" >> ~/.bashrc printf 'export MPW_FULLNAME=%q\n' "$MPW_FULLNAME" >> ~/.bashrc
fi
inf "If you have an askpass program you'd like to use, you can specify it here."
inf "An askpass program provides a graphical interface for entering things like your master password."
inf "Leave blank to skip this step and enter passwords using the terminal."
if [[ ! $MPW_ASKPASS ]] && hash ssh-askpass 2>/dev/null; then
MPW_ASKPASS=ssh-askpass
fi
if MPW_ASKPASS=$(ask +"$MPW_ASKPASS" "askpass program:") && [[ $MPW_ASKPASS ]] ; then
printf 'export MPW_ASKPASS=%q\n' "$MPW_ASKPASS" >> ~/.bashrc
fi fi
echo echo
inf "To begin using Master Password, type: mpw [site name]" inf "Shell features installed."
inf "To load these convenience features into your already running shell, type: source ~/.bashrc"
inf "To begin using Master Password, type: mpw -h or mpw my-site-name"