diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 54 | ||||
| -rw-r--r-- | Makefile | 40 | ||||
| -rw-r--r-- | README.md | 74 |
4 files changed, 122 insertions, 48 deletions
@@ -1,2 +1,2 @@ -build/ +/fscrypt fscrypt.sublime-* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1f69c12 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# How to Contribute to fscrypt + +We'd love to accept your patches and contributions to this project. There are +just a few small guidelines we ask you to follow. + +## Contributor License Agreement + +Contributions to this project must be accompanied by a Contributor License +Agreement. You (or your employer) retain the copyright to your contribution, +this simply gives us permission to use and redistribute your contributions as +part of the project. Head over to <https://cla.developers.google.com/> to see +your current agreements on file or to sign a new one. + +You generally only need to submit a CLA once, so if you've already submitted one +(even if it was for a different project), you probably don't need to do it +again. + +## Code reviews + +All submissions, including submissions by project members, require review. We +use GitHub pull requests for this purpose. Consult +[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more +information on using pull requests. + +## Before you submit a pull request + +If you are making changes to the `fscrypt` component, you will need to have +[govendor](https://github.com/kardianos/govendor) installed, and you will want +to use the following additional commands: +* `make update` - Updates the dependencies in the `vendor/` directory and + updates the `VENDOR_LICENSES` file. +* `make go` - Generates, builds, and tests all the Go code. Requires + [protoc (v3.0 or later)](https://github.com/google/protobuf/releases) and + [protoc-gen-go](https://github.com/golang/protobuf). +* `make format` - Formats all of the go code. +* `make lint` - Checks the code for style errors. Requires + [`golint`](https://github.com/golang/lint). +* `make all` - Runs the above commands and builds `fscrypt`. + +These commands should be run before submitting a pull request. + +Make sure that `$GOPATH/bin` is in you `$PATH`. All the above dependencies can +be installed with: +``` bash +# Grab the latest version of protoc from github.com/google/protobuf/releases +> curl -L <download_link_for_your_architecture> > protoc.zip +> unzip protoc.zip -d protoc +> sudo mv protoc/bin/protoc /usr/local/bin/ +> rm -rf protoc.zip protoc/ +# Grab the go packages in the standard manner +> go get -u github.com/golang/protobuf/protoc-gen-go +> go get -u github.com/kardianos/govendor +> go get -u github.com/golang/lint/golint +``` @@ -16,18 +16,36 @@ # the License. NAME = fscrypt -BUILD_DIR = build -CFLAGS += -O2 -Wall +# VERSION is formatted as <major>.<minor>.<bugfix> +# Bugfix releases resolve issues in existing features. +# Minor releases introduce new features. +# Major releases may introduce breaking changes to the API. +VERSION = 0.1.0 +# Holds a formatted string of the build time +BUILD_TIME = $(shell date) +CFLAGS += -O2 -Wall CMD_DIR = $(NAME)/cmd/$(NAME) -# So we don't have to put our flags in each go file. This also lets the caller -# of the makefile change the build flags in the normal manner: +# The code below lets the caller of the makefile change the build flags for +# fscrypt in a familiar manner. For example, to force the program to statically +# link its C components, run "make fscrypt" with: # make fscrypt "LDFLAGS += -static" +# +# Similarly, to modify the flags passed to the C components, just modify CFLAGS +# or LDFLAGS as you would with a C program. To modify the Go flags, either +# modify GO_FLAGS or GO_LINK_FLAGS (as appropriate). + +# Set the C flags so we don't need to set C flags in each CGO file. export CGO_CFLAGS = $(CFLAGS) -ifdef LDFLAGS - GOFLAGS += --ldflags '-extldflags "$(LDFLAGS)"' -endif + +# Pass the version to the command line program +VERSION_FLAG = -X "main.version=$(VERSION)" +# Pass the current date and time to the command line program +DATE_FLAG = -X "main.buildTime=$(BUILD_TIME)" +# Pass the C linking flags into Go +GO_LINK_FLAGS += -s -w $(VERSION_FLAG) $(DATE_FLAG) -extldflags "$(LDFLAGS)" +GOFLAGS += --ldflags '$(GO_LINK_FLAGS)' .PHONY: default all $(NAME) go update lint format install clean @@ -35,12 +53,11 @@ default: $(NAME) all: update go format lint $(NAME) $(NAME): - @mkdir -p $(BUILD_DIR) - go build $(GOFLAGS) -o $(BUILD_DIR)/$(NAME) $(CMD_DIR) + go build $(GOFLAGS) -o $(NAME) $(CMD_DIR) # Makes sure go files build and tests pass go: - govendor generate $(GOFLAGS) +local + govendor generate +local govendor build $(GOFLAGS) +local govendor test $(GOFLAGS) +local @@ -55,9 +72,10 @@ lint: format: @govendor fmt +local + @find . -name "*.h" -o -name "*.c" -not -path "./vendor/*" | xargs clang-format -i -style=Google install: govendor install $(GOFLAGS) +local clean: - rm -rf $(BUILD_DIR) + rm -rf $(NAME) @@ -54,9 +54,23 @@ more managed environment and handling more functionality in the background. `fscrypt` has a [design document](https://goo.gl/55cCrI) that discusses many of the higher level design choices that were made. -<!-- TODO add in features when command-line interface is complete --> Specifically, `fscrypt` contains the following functionality: -* Telling the time (but this is a stub program) +* `fscrypt info` - Prints detailed application info +* `fscrypt setup global` - Initializes the `fscrypt.conf` file +* `fscrypt setup filesystem` - Gets a filesystem ready for use with fscrypt +* `fscrypt setup directory` - Sets up encryption for a directory +* `fscrypt unlock` - Unlocks an encrypted directory for use +* `fscrypt encrypt` - Shortcut for `fscrypt setup directory`+`fscrypt unlock` +* `fscrypt change` - Changes how a directory is protected +* `fscrypt status` - Gets the status of some component of fscrypt +* `fscrypt backup` - Manages backups of the fscrypt metadata +* `fscrypt recovery` - Manages recovery keys for fscrypt protectors +* `fscrypt cleanup` - Scans filesystem for unused policies +* `fscrypt purge` - Removes keys for a filesystem before unmounting. +* `fscrypt [protector|policy]` - Manages metadata directly + +See the example usage section below or run `fscrypt <command> --help` for more +information about each of the commands. ## Building @@ -82,9 +96,12 @@ You will also want to add `$GOPATH/bin` to your `$PATH`. > make > sudo make install ``` +* Headers for `libblkid` (specifically `blkid/blkid.h`). This can be installed + with your appropriate package manager (`libblkid-dev` for APT, + `libblkid-devel` for RPM, should already be part of `util-linux` for Arch). Once this is setup, you can run `make fscrypt` to build the executable in -`build/fscrypt`. Pass `"LDFLAGS += -static"` to `make` to get a static +the root directory. Pass `"LDFLAGS += -static"` to `make` to get a static executable. If a Go project contains C code, the go compiler produces a dynamically linked binary by default. @@ -95,6 +112,9 @@ dynamically linked binary by default. configuration and specific filesystem) * `libargon2` (see the above installation instructions for Argon2), unless you built a static executable. +* `libblkid` and `libuuid` (these are dependancies for `util-linux` and + `e2fsprogs` so your system almost certainly has it), unless you built a + static executable. Installing it just requires placing it in your path or running `make install`. Change `$GOBIN` to change the install location of `fscrypt`. By default, @@ -102,48 +122,30 @@ Change `$GOBIN` to change the install location of `fscrypt`. By default, ## Example Usage -TODO +```bash +# Setup your global configuration and filesystem +> sudo fscrypt setup global +Created global config file at "/etc/fscrypt.conf". +> fscrypt setup filesystem /mnt/disk/to/encrypt +Setup "/mnt/disk/to/encrypt (/dev/sda1) for use with ext4 filesystem encryption. +``` ## Contributing -If you are making changes to the `fscrypt` component, you will need to have -[govendor](https://github.com/kardianos/govendor) installed, and you will want -to use the following additional commands: -* `make update` - Updates the dependencies in the `vendor/` directory. -* `make go` - Generates, builds, and tests all the Go code. Requires - [protoc (v3.0 or later)](https://github.com/google/protobuf/releases) and - [protoc-gen-go](https://github.com/golang/protobuf). -* `make format` - Formats all of the go code. -* `make lint` - Checks the code for style errors. Requires - [`golint`](https://github.com/golang/lint). -* `make all` - Runs the above commands and builds `fscrypt`. - -These commands should be run before submitting any changes. - -Make sure that `$GOPATH/bin` is in you `$PATH`. All the above dependencies can -be installed with: -``` bash -# Grab the latest version of protoc from github.com/google/protobuf/releases -> curl -L <download_link_for_your_architecture> > protoc.zip -> unzip protoc.zip -d protoc -> sudo mv protoc/bin/protoc /usr/local/bin/ -> rm -rf protoc.zip protoc/ -# Grab the go packages in the standard manner -> go get -u github.com/golang/protobuf/protoc-gen-go -> go get -u github.com/kardianos/govendor -> go get -u github.com/golang/lint/golint -``` +We would love to accept your contributions to `fscrypt`. See the +`CONTRIBUTING.md` file for more information about singing the CLA and submitting +a pull request. ## Known Issues None so far! -## License +## Legal -Copyright 2017 Google Inc. +Copyright 2017 Google Inc. under the +[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0); see the +`LICENSE` file for more information. Author: Joe Richey <joerichey@google.com> -Distributed under the -[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0); see the -`LICENSE` file for more information. +This is not an official Google product. |