diff --git a/README.md b/README.md index 8566ab87..344db1e3 100644 --- a/README.md +++ b/README.md @@ -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. -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 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`. +For detailed instructions, see [the native CLI instructions](platform-independent/cli-c/README.md). ## Support diff --git a/platform-independent/cli-c/README.md b/platform-independent/cli-c/README.md new file mode 100644 index 00000000..94e7f4c9 --- /dev/null +++ b/platform-independent/cli-c/README.md @@ -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 diff --git a/platform-independent/cli-c/install b/platform-independent/cli-c/install index 188bedb9..66828591 100755 --- a/platform-independent/cli-c/install +++ b/platform-independent/cli-c/install @@ -45,9 +45,20 @@ fi echo 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 - printf 'export MP_FULLNAME=%q\n' "$MP_FULLNAME" >> ~/.bashrc +if MPW_FULLNAME=$(ask "Your full name:") && [[ $MPW_FULLNAME ]] ; then + 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 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"