From 55d76cd7dcf7d732722764a1a4327b36838c999c Mon Sep 17 00:00:00 2001 From: Carla Schroder Date: Thu, 2 Jun 2022 15:05:01 -0700 Subject: [PATCH] minor corrections, line breaks, capitalization, expand abbreviations (#802) * minor corrections, line breaks, capitalization, expand abbreviations --- DEVELOPER_README.md | 89 +++++++++++++++++++++++--------------- kanidm_book/src/why_tls.md | 23 +++++----- 2 files changed, 66 insertions(+), 46 deletions(-) diff --git a/DEVELOPER_README.md b/DEVELOPER_README.md index 4e9141ac0..8a6d8269a 100644 --- a/DEVELOPER_README.md +++ b/DEVELOPER_README.md @@ -12,7 +12,8 @@ cargo doc --document-private-items --open --no-deps ### Rust Documentation -A list of links to the library documentation is [here](https://kanidm.com/documentation/). +A list of links to the library documentation is at +[kanidm.com/documentation](https://kanidm.com/documentation/). ### Minimum Supported Rust Version @@ -22,15 +23,13 @@ The MSRV is specified in the package `Cargo.toml` files. #### MacOS -You will need [rustup](https://rustup.rs/) to install a rust toolchain. - -If you plan to work on the web-ui, you may also need npm for setting up some parts. - - brew install npm - +You will need [rustup](https://rustup.rs/) to install a Rust toolchain. + #### SUSE -You will need [rustup](https://rustup.rs/) to install a rust toolchain. If you're using the Tumbleweed release, it's packaged in `zypper`. +You will need [rustup](https://rustup.rs/) to install a Rust toolchain. If +you're +using the Tumbleweed release, it's packaged in `zypper`. You will also need some system libraries to build this: @@ -38,7 +37,7 @@ You will also need some system libraries to build this: #### Fedora -You will need to install the rust toolchain packages. +You need to install the Rust toolchain packages: rust cargo @@ -46,13 +45,13 @@ You will also need some system libraries to build this: systemd-devel sqlite-devel openssl-devel pam-devel -Building the web ui requires additional packages: +Building the Web UI requires additional packages: perl-FindBin perl-File-Compare rust-std-static-wasm32-unknown-unknown #### Ubuntu -You will need [rustup](https://rustup.rs/) to install a rust toolchain. +You need [rustup](https://rustup.rs/) to install a Rust toolchain. You will also need some system libraries to build this, which can be installed by running: @@ -62,9 +61,10 @@ sudo apt-get install libsqlite3-dev libudev-dev libssl-dev Tested with Ubuntu 20.04. -### Get involved +### Get Involved -To get started, you'll need to fork or branch, and we'll merge based on PR's. +To get started, you'll need to fork or branch, and we'll merge based on pull +requests. If you are a contributor to the project, simply clone: @@ -80,7 +80,8 @@ cd kanidm git remote add myfork git@github.com:/kanidm.git ``` -Select an issue (always feel free to reach out to us for advice!), and create a branch to start working: +Select an issue (always feel free to reach out to us for advice!), and create a +branch to start working: ```shell git branch @@ -88,11 +89,13 @@ git checkout cargo test ``` -When you are ready for review (even if the feature isn't complete and you just want some advice) +When you are ready for review (even if the feature isn't complete and you just +want some advice): 1. Run the test suite: `cargo test --workspace` 2. Ensure rust formatting standards are followed: `cargo fmt --check` -3. Try following the suggestions from clippy, after running `cargo clippy`. This is not a blocker on us accepting your code! +3. Try following the suggestions from clippy, after running `cargo clippy`. + This is not a blocker on us accepting your code! 4. Then commit your changes: ```shell @@ -100,8 +103,9 @@ git commit -m 'Commit message' change_file.rs ... git push ``` -If you receive advice or make further changes, just keep commiting to the branch, and pushing to your branch. -When we are happy with the code, we'll merge in GitHub, meaning you can now clean up your branch. +If you receive advice or make further changes, just keep commiting to the branch, +and pushing to your branch. When we are happy with the code, we'll merge in GitHub, +meaning you can now clean up your branch. ``` git checkout master @@ -120,7 +124,8 @@ git checkout git rebase master ``` -Then be sure to fix any merge issues or other comments as they arise. If you have issues, you can always stop and reset with: +Then be sure to fix any merge issues or other comments as they arise. If you +have issues, you can always stop and reset with: ``` git rebase --abort @@ -128,13 +133,18 @@ git rebase --abort ### Development Server Quickstart for Interactive Testing -After getting the code, you will need a rust environment. Please investigate [rustup](https://rustup.rs) for your platform to establish this. +After getting the code, you will need a rust environment. Please investigate +[rustup](https://rustup.rs) for your platform to establish this. -Once you have the source code, you need certificates to use with the server, because without certificates, authentication will fail. +Once you have the source code, you need encryption certificates to use with the server, +because without certificates, authentication will fail. -We recommend using [Let's Encrypt](https://letsencrypt.org), but if this is not possible, please use our insecure cert tool (`insecure_generate_tls.sh`). The insecure cert tool creates `/tmp/kanidm` and puts some self-signed certificates there. +We recommend using [Let's Encrypt](https://letsencrypt.org), but if this is not +possible, please use our insecure certificate tool (`insecure_generate_tls.sh`). The +insecure certificate tool creates `/tmp/kanidm` and puts some self-signed certificates there. -You can now build and run the server with the commands below. It will use a database in `/tmp/kanidm.db`. +You can now build and run the server with the commands below. It will use a database +in `/tmp/kanidm.db`. Create the initial database and generate an `admin` username: @@ -160,25 +170,30 @@ In a new terminal, you can now build and run the client tools with: ### Building the Web UI -__NOTE:__ There is a pre-packaged version of the Web UI at `/kanidmd_web_ui/pkg/`, which can be used directly. This means you don't need to build the Web UI yourself +__NOTE:__ There is a pre-packaged version of the Web UI at `/kanidmd_web_ui/pkg/`, +which can be used directly. This means you don't need to build the Web UI yourself. -The web UI uses rust wasm rather than javascript. To build this you need to set up the environment. +The Web UI uses Rust WebAssembly rather than Javascript. To build this you need +to set up the environment: cargo install wasm-pack npm install --global rollup -Then you are able to build the UI. +Then you are able to build the UI: cd kanidmd_web_ui/ ./build_wasm.sh The "developer" profile for kanidmd will automatically use the pkg output in this folder. -Setting different developer profiles while building is done by setting the environment variable KANIDM_BUILD_PROFILE to one of the bare filename of the TOML files in `/profiles`. +Setting different developer profiles while building is done by setting the +environment +variable KANIDM_BUILD_PROFILE to one of the bare filename of the TOML files in +`/profiles`. For example: `KANIDM_BUILD_PROFILE=release_suse_generic cargo build --release --bin kanidmd` -### Build a kanidm container +### Build a Kanidm Container Build a container with the current branch using: @@ -198,7 +213,7 @@ The following environment variables control the build: |`CONTAINER_TOOL`|Use an alternative container build tool.|`docker`| |`BOOK_VERSION`|Sets version used when building the documentation book.|`master`| -#### Container build examples +#### Container Build Examples Build a `kanidm` container using `podman`: @@ -208,15 +223,21 @@ Build a `kanidm` container and use a redis build cache: CONTAINER_BUILD_ARGS='--build-arg "SCCACHE_REDIS=redis://redis.dev.blackhats.net.au:6379"' make build/kanidmd -#### Automatically built containers +#### Automatically Built Containers -To speed up testing across platforms, we're leveraging GitHub actions to build containers for test use. +To speed up testing across platforms, we're leveraging GitHub actions to build +containers for test use. -Whenever code is merged with the `master` branch of Kanidm, containers are automatically built for `kanidmd` and `radius`. Sometimes they fail to build, but we'll try and keep them avilable. +Whenever code is merged with the `master` branch of Kanidm, containers are automatically +built for `kanidmd` and `radius`. Sometimes they fail to build, but we'll try to +keep them avilable. -To find information on the packages, [visit the Kanidm packages page here](https://github.com/orgs/kanidm/packages?repo_name=kanidm). +To find information on the packages, +[visit the Kanidm packages page](https://github.com/orgs/kanidm/packages?repo_name=kanidm). -An example command for pulling and running the radius container is below. You'll need to [authenticate with the GitHub container registry first](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). +An example command for pulling and running the radius container is below. You'll +need to +[authenticate with the GitHub container registry first](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). ```shell docker pull ghcr.io/kanidm/radius:devel diff --git a/kanidm_book/src/why_tls.md b/kanidm_book/src/why_tls.md index 99943e001..40ee2e008 100644 --- a/kanidm_book/src/why_tls.md +++ b/kanidm_book/src/why_tls.md @@ -2,31 +2,30 @@ # Why TLS? You may have noticed that Kanidm requires you to configure TLS in -your container - or that you provide something *with* TLS in front like haproxy. +your container - or that you provide something *with* TLS in front, like haproxy. This is due to a single setting on the server - `secure_cookies` ## What are Secure Cookies? -`secure-cookies` is a flag set in cookies that "asks" a client to transmit them -back to the origin site if and only if https is present in the URL. +`secure-cookies` is a flag set in cookies that asks a client to transmit them +back to the origin site if and only if HTTPS is present in the URL. -CA verification is *not* checked - you can use invalid, out of date certificates, -or even certificates where the `subjectAltName` does not match, but the client -must see https:// as the destination else it *will not* send the cookies. +Certificate authority (CA) verification is *not* checked - you can use invalid, +out of date certificates, or even certificates where the `subjectAltName` does +not match, but the client must see https:// as the destination else it *will not* +send the cookies. -## How does that affect Kanidm? +## How Does That Affect Kanidm? Kanidm's authentication system is a stepped challenge response design, where you initially request an "intent" to authenticate. Once you establish this intent, the server sets up a session-id into a cookie, and informs the client of what authentication methods can proceed. -When you then go to continue the authentication, if you do NOT have a https url, -the cookie with the session-id is not transmitted. The server detects this as -an invalid-state request in the authentication design and immediately disconnects -you from attempting to continue the authentication as you may be using an insecure -channel. +If you do NOT have a HTTPS URL, the cookie with the session-id is not transmitted. +The server detects this as an invalid-state request in the authentication design, +and immediately breaks the connection, because it appears insecure. Simply put, we are trying to use settings like secure_cookies to add constraints to the server so that you *must* perform and adhere to best practices - such