diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 62 |
1 files changed, 31 insertions, 31 deletions
@@ -1,14 +1,14 @@ -# Roughenough +# Roughenough [](https://crates.io/crates/roughenough) [](https://travis-ci.org/int08h/roughenough) [](https://www.apache.org/licenses/LICENSE-2.0.txt) -**Roughenough** is a [Roughtime](https://roughtime.googlesource.com/roughtime) secure time -synchronization client and server implementation in Rust. +**Roughenough** is a [Roughtime](https://roughtime.googlesource.com/roughtime) secure time +synchronization client and server implementation in Rust. -Roughenough's server and client are functionally complete and -at feature parity with the reference C++ and Golang implementations. +Roughenough's server and client are functionally complete and +at feature parity with the reference C++ and Golang implementations. Requires latest stable Rust to compile. Contributions welcome, see [CONTRIBUTING](../master/CONTRIBUTING.md) for instructions and [limitations](#limitations) for areas that could use attention. @@ -18,14 +18,14 @@ Requires latest stable Rust to compile. Contributions welcome, see * Original [Roughtime project](https://roughtime.googlesource.com/roughtime) * My blog posts giving a [technical deep-dive into Roughtime](https://int08h.com/post/to-catch-a-lying-timeserver/) and exploring details of [on-the-wire Roughtime messages](https://int08h.com/post/roughtime-message-anatomy/). -* Cloudflare's fantastic [blog post](https://blog.cloudflare.com/roughtime/) and accompanying +* Cloudflare's fantastic [blog post](https://blog.cloudflare.com/roughtime/) and accompanying [open-source project](https://developers.cloudflare.com/roughtime/). ## Building and Running ### Rust 1.31 or above required -Roughenough uses [2018 edition](https://rust-lang-nursery.github.io/edition-guide/rust-2018/index.html) +Roughenough uses [2018 edition](https://rust-lang-nursery.github.io/edition-guide/rust-2018/index.html) features and requires Rust 1.31 or newer to build. ### Building @@ -35,14 +35,14 @@ features and requires Rust 1.31 or newer to build. $ cargo build --release ``` -The client binary is `target/release/roughenough-client`. After building you can copy the +The client binary is `target/release/roughenough-client`. After building you can copy the binary and run on its own (no `cargo` needed) if you wish. ```bash -$ cp target/release/roughenough-client /usr/local/bin +$ cp target/release/roughenough-client /usr/local/bin ``` -### Using the Client to Query a Roughtime Server +### Using the Client to Query a Roughtime Server ```bash $ target/release/roughenough-client -v roughtime.int08h.com 2002 @@ -59,12 +59,12 @@ You can use the `date` utility on Linux machines to set the system time to the t sudo date --utc --set "$(roughenough-client -z roughtime.int08h.com 2002)" ``` -### Validating Server Responses +### Validating Server Responses Use the `-p` flag with the client to validate the server's response with its public key. ```bash -# The public key of 'roughtime.int08h.com' is stored in a DNS TXT record +# The public key of 'roughtime.int08h.com' is stored in a DNS TXT record $ host -t TXT roughtime.int08h.com roughtime.int08h.com descriptive text "016e6e0284d24c37c6e4d7d8d5b4e1d3c1949ceaa545bf875616c9dce0c9bec1" @@ -79,7 +79,7 @@ The **`verified=Yes`** in the output confirms that the server's response had a v ### Server Configuration -There are two (mutually exclusive) ways to configure the Roughenough server: +There are two (mutually exclusive) ways to configure the Roughenough server: 1. A YAML file, or 2. Environment variables @@ -97,7 +97,7 @@ YAML Key | Environment Variable | Necessity | Description `kms_protection` | `ROUGHENOUGH_KMS_PROTECTION` | Optional | If compiled with KMS support, the ID of the KMS key used to protect the long-term identity. See [Optional Features](#optional-features). `fault_percentage` | `ROUGHENOUGH_FAULT_PERCENTAGE` | Optional | Likelihood (as a percentage) that the server will intentionally return an invalid client response. An integer range from `0` (disabled, all responses valid) to `50` (50% of responses will be invalid). Default is `0` (disabled). -#### YAML Configuration +#### YAML Configuration The table above lists the YAML keys available in the config file. An example: @@ -115,7 +115,7 @@ $ /path/to/roughenough-server /path/to/config.yaml #### Environment Configuration -Roughenough can be configured via the `ROUGHENOUGH_*` [environment variables](https://12factor.net/config) +Roughenough can be configured via the `ROUGHENOUGH_*` [environment variables](https://12factor.net/config) listed in the table above. Start the server with a single `ENV` argument to have Roughenough configure itself from the environment. Example: @@ -150,11 +150,11 @@ $ target/release/roughenough-server ENV 2018-07-25 00:05:09 INFO [server] Server listening on 127.0.0.1:8686 ``` -The resulting binary is `target/release/roughenough-server`. After building you can copy the +The resulting binary is `target/release/roughenough-server`. After building you can copy the binary and run on its own (no `cargo` needed): ```bash -$ cp target/release/roughenough-server /usr/local/bin +$ cp target/release/roughenough-server /usr/local/bin ``` ### Stopping the Server @@ -164,13 +164,13 @@ Use Ctrl-C or `kill` the process. ## Optional Features -Roughenough has two opt-in (disabled by default) features that are enabled either +Roughenough has two opt-in (disabled by default) features that are enabled either A) via a config setting, or B) at compile-time. -* [HTTP Health Check responder](doc/OPTIONAL-FEATURES.md#http-health-check) +* [HTTP Health Check responder](doc/OPTIONAL-FEATURES.md#http-health-check) to facilitate detection and replacement of "sick" Roughenough servers. * [Key Management System (KMS) support](doc/OPTIONAL-FEATURES.md#key-management-system-kms-support) - to protect the long-term server identity using envelope encryption and + to protect the long-term server identity using envelope encryption and AWS or Google KMS. See [OPTIONAL-FEATURES.md](doc/OPTIONAL-FEATURES.md) for details and instructions @@ -181,18 +181,18 @@ how to enable and use. Roughtime features not implemented by the server: -* On-line (while server is running) key rotation. The server must be restarted to generate a new delegated key. -* The Roughenough server depends on the host's time source to comply with the smeared leap-second - requirement of the Roughtime protocol. A Roughenough server sourcing time from +* On-line (while server is running) key rotation. The server must be restarted to generate a new delegated key. +* The Roughenough server depends on the host's time source to comply with the smeared leap-second + requirement of the Roughtime protocol. A Roughenough server sourcing time from [Google's public NTP servers](https://developers.google.com/time/) would produce compliant smeared leap-seconds but time sourced from members of `pool.ntp.org` likely will not. ## About the Roughtime Protocol -[Roughtime](https://roughtime.googlesource.com/roughtime) is a protocol that aims to achieve rough +[Roughtime](https://roughtime.googlesource.com/roughtime) is a protocol that aims to achieve rough time synchronisation in a secure way that doesn't depend on any particular time server, and in such -a way that, if a time server does misbehave, clients end up with cryptographic proof of it. It was +a way that, if a time server does misbehave, clients end up with cryptographic proof of it. It was created by Adam Langley and Robert Obryk. - + ## Contributors * Stuart Stock (stuart {at} int08h.com) * Aaron Hill (aa1ronham {at} gmail.com) @@ -201,15 +201,15 @@ created by Adam Langley and Robert Obryk. * Zicklag (github.com/zicklag) ## Copyright and License -Roughenough is copyright (c) 2017-2020 int08h LLC. All rights reserved. +Roughenough is copyright (c) 2017-2020 int08h LLC. All rights reserved. -int08h LLC licenses Roughenough (the "Software") to you under the Apache License, version 2.0 -(the "License"); you may not use this Software except in compliance with the License. You may obtain +int08h LLC licenses Roughenough (the "Software") to you under the Apache License, version 2.0 +(the "License"); you may not use this Software except in compliance with the License. You may obtain a copy of the License from the [LICENSE](../master/LICENSE) file included with the Software or at: http://www.apache.org/licenses/LICENSE-2.0 -Unless required by applicable law or agreed to in writing, software distributed under the License +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -implied. See the License for the specific language governing permissions and limitations under +implied. See the License for the specific language governing permissions and limitations under the License. |