{"id":13509877,"url":"https://github.com/google/fscrypt","last_synced_at":"2025-11-12T21:28:55.431Z","repository":{"id":37390711,"uuid":"97037205","full_name":"google/fscrypt","owner":"google","description":"Go tool for managing Linux filesystem encryption","archived":false,"fork":false,"pushed_at":"2025-11-04T18:14:06.000Z","size":2998,"stargazers_count":973,"open_issues_count":42,"forks_count":104,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-11-04T20:20:38.832Z","etag":null,"topics":["argon2","cryptography","ext4-filesystem","filesystem","filesystem-encryption","golang","pam-module"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security/cache.go","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-07-12T17:52:15.000Z","updated_at":"2025-11-04T15:05:01.000Z","dependencies_parsed_at":"2023-02-16T16:50:24.076Z","dependency_job_id":"88f5da0c-bf52-415a-ab8d-b2a7890e9c63","html_url":"https://github.com/google/fscrypt","commit_stats":{"total_commits":419,"total_committers":24,"mean_commits":"17.458333333333332","dds":0.5250596658711217,"last_synced_commit":"f91f8e4fcb59d6db80e5150530a65fe39a836eb2"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/google/fscrypt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Ffscrypt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Ffscrypt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Ffscrypt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Ffscrypt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/fscrypt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Ffscrypt/sbom","scorecard":{"id":436942,"data":{"date":"2025-08-11","repo":{"name":"github.com/google/fscrypt","commit":"827c13689b39814552a3a18449f922b123725b49"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":3,"reason":"Found 7/18 approved changesets -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:65: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:113: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:114: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:128: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:129: update your workflow using https://app.stepsecurity.io/secureworkflow/google/fscrypt/ci.yml/master?enable=pin","Info:   0 out of  10 GitHub-owned GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/google/.github/SECURITY.md:1","Info: Found linked content: github.com/google/.github/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/google/.github/SECURITY.md:1","Info: Found text in security policy: github.com/google/.github/SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"SAST","score":1,"reason":"SAST tool is not run on all commits -- score normalized to 1","details":["Warn: 5 commits out of 29 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":9,"reason":"1 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2025-3487 / GHSA-hcg3-q754-cr77"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T04:54:59.270Z","repository_id":37390711,"created_at":"2025-08-19T04:54:59.270Z","updated_at":"2025-08-19T04:54:59.270Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284115865,"owners_count":26949957,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-12T02:00:06.336Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argon2","cryptography","ext4-filesystem","filesystem","filesystem-encryption","golang","pam-module"],"created_at":"2024-08-01T02:01:15.722Z","updated_at":"2025-11-12T21:28:55.421Z","avatar_url":"https://github.com/google.png","language":"Go","funding_links":[],"categories":["File Encryption","Go","golang"],"sub_categories":["Snippets Manager"],"readme":"# fscrypt [![GitHub version](https://badge.fury.io/go/github.com%2Fgoogle%2Ffscrypt.svg)](https://github.com/google/fscrypt/releases)\n\n[![Build Status](https://github.com/google/fscrypt/workflows/CI/badge.svg)](https://github.com/google/fscrypt/actions?query=workflow%3ACI+branch%3Amaster)\n[![GoDoc](https://godoc.org/github.com/google/fscrypt?status.svg)](https://godoc.org/github.com/google/fscrypt)\n[![Go Report Card](https://goreportcard.com/badge/github.com/google/fscrypt)](https://goreportcard.com/report/github.com/google/fscrypt)\n[![License](https://img.shields.io/badge/LICENSE-Apache2.0-ff69b4.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)\n\n`fscrypt` is a high-level tool for the management of [Linux native filesystem\nencryption](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html).\n`fscrypt` manages metadata, key generation, key wrapping, PAM integration, and\nprovides a uniform interface for creating and modifying encrypted directories.\nFor a small low-level tool that directly sets policies, see\n[`fscryptctl`](https://github.com/google/fscryptctl).\n\nTo use `fscrypt`, you must have a filesystem that supports the Linux native\nfilesystem encryption API (which is also sometimes called \"fscrypt\"; this\ndocumentation calls it \"Linux native filesystem encryption\" to avoid confusion).\nOnly certain filesystems, such as [ext4](https://en.wikipedia.org/wiki/Ext4) and\n[f2fs](https://en.wikipedia.org/wiki/F2FS), support this API.  For a full list\nof supported filesystems and how to enable encryption support on each one, see\n[Runtime dependencies](#runtime-dependencies).\n\nFor the release notes, see the [NEWS file](NEWS.md).\n\n## Table of contents\n\n- [Alternatives to consider](#alternatives-to-consider)\n- [Threat model](#threat-model)\n- [Features](#features)\n- [Building and installing](#building-and-installing)\n- [Runtime dependencies](#runtime-dependencies)\n- [Configuration file](#configuration-file)\n- [Setting up `fscrypt` on a filesystem](#setting-up-fscrypt-on-a-filesystem)\n- [Setting up for login protectors](#setting-up-for-login-protectors)\n  - [Securing your login passphrase](#securing-your-login-passphrase)\n  - [Enabling the PAM module](#enabling-the-pam-module)\n    - [Enabling the PAM module on Debian or Ubuntu](#enabling-the-pam-module-on-debian-or-ubuntu)\n\t- [Enabling the PAM module on Arch Linux](#enabling-the-pam-module-on-arch-linux)\n\t- [Enabling the PAM module on other Linux distros](#enabling-the-pam-module-on-other-linux-distros)\n  - [Allowing `fscrypt` to check your login passphrase](#allowing-fscrypt-to-check-your-login-passphrase)\n- [Backup, restore, and recovery](#backup-restore-and-recovery)\n- [Encrypting existing files](#encrypting-existing-files)\n- [Example usage](#example-usage)\n  - [Setting up fscrypt on a directory](#setting-up-fscrypt-on-a-directory)\n  - [Locking and unlocking a directory](#locking-and-unlocking-a-directory)\n  - [Protecting a directory with your login passphrase](#protecting-a-directory-with-your-login-passphrase)\n  - [Changing a custom passphrase](#changing-a-custom-passphrase)\n  - [Using a raw key protector](#using-a-raw-key-protector)\n  - [Using multiple protectors for a policy](#using-multiple-protectors-for-a-policy)\n- [Contributing](#contributing)\n- [Troubleshooting](#troubleshooting)\n  - [I changed my login passphrase, now all my directories are inaccessible](#i-changed-my-login-passphrase-now-all-my-directories-are-inaccessible)\n  - [Directories using my login passphrase are not automatically unlocking](#directories-using-my-login-passphrase-are-not-automatically-unlocking)\n  - [Getting \"encryption not enabled\" on an ext4 filesystem](#getting-encryption-not-enabled-on-an-ext4-filesystem)\n  - [Getting \"user keyring not linked into session keyring\"](#getting-user-keyring-not-linked-into-session-keyring)\n  - [Getting \"Operation not permitted\" when moving files into an encrypted directory](#getting-operation-not-permitted-when-moving-files-into-an-encrypted-directory)\n  - [Getting \"Package not installed\" when trying to use an encrypted directory](#getting-package-not-installed-when-trying-to-use-an-encrypted-directory)\n  - [Some processes can't access unlocked encrypted files](#some-processes-cant-access-unlocked-encrypted-files)\n  - [Users can access other users' unlocked encrypted files](#users-can-access-other-users-unlocked-encrypted-files)\n  - [Getting \"Required key not available\" when backing up locked encrypted files](#getting-required-key-not-available-when-backing-up-locked-encrypted-files)\n  - [The reported size of encrypted symlinks is wrong](#the-reported-size-of-encrypted-symlinks-is-wrong)\n- [Legal](#legal)\n\n## Alternatives to consider\n\nOperating-system level storage encryption solutions work at either the\nfilesystem or block device level.  [Linux native filesystem\nencryption](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html)\n(the solution configured by `fscrypt`) is filesystem-level; it encrypts\nindividual directories.  Only file contents and filenames are encrypted;\nnon-filename metadata, such as timestamps, the sizes and number of files, and\nextended attributes, is **not** encrypted.  Users choose which directories will\nbe encrypted, and with what keys.\n\nBefore using `fscrypt`, you should consider other solutions:\n\n* [**dm-crypt/LUKS**](https://en.wikipedia.org/wiki/Dm-crypt) is block device\n  level encryption: it encrypts an entire block device (and hence an entire\n  filesystem) with one key.  Unlocking this key will unlock the entire block\n  device.  dm-crypt/LUKS is usually configured using\n  [cryptsetup](https://gitlab.com/cryptsetup/cryptsetup/-/wikis/home).\n\n* [`systemd-homed`](https://systemd.io/HOME_DIRECTORY/) supports encrypting home\n  directories using the same Linux native filesystem encryption API that\n  `fscrypt` uses.  Note that while the `systemd-homed` documentation refers to\n  this as fscrypt support, it does not use the `fscrypt` tool; directories set\n  up using `systemd-homed` cannot be managed by `fscrypt` and vice versa.\n  `systemd-homed` has better integration with systemd than `fscrypt` does.\n  However, `systemd-homed` (as of systemd v255) uses the\n  [\"V1\" Linux kernel encryption API](https://www.kernel.org/doc/html/v6.8/filesystems/fscrypt.html#limitations-of-v1-policies),\n  while `fscrypt` prefers the \"V2\" API. The older API causes\n  [known issues](#some-processes-cant-access-unlocked-encrypted-files), and\n  migrating `systemd-home` to the \"V2\" API is tracked\n  [in this `systemd` issue](https://github.com/systemd/systemd/issues/18280).\n  Issues with `systemd-homed` should be reported to the systemd developers.\n\n* [**eCryptfs**](https://en.wikipedia.org/wiki/ECryptfs) is an alternative\n  filesystem-level encryption solution.  It is a stacked filesystem, which means\n  it sits on top of a real filesystem, rather than being directly integrated\n  into the real filesystem.  Stacked filesystems have a couple advantages (such\n  as working on almost any real filesystem), but also some significant\n  disadvantages.  eCryptfs is usually configured using\n  [ecryptfs-utils](https://packages.debian.org/stretch/ecryptfs-utils).\n\n* Some Linux filesystems support encryption natively, but not in a way that is\n  compatible with the common API that `fscrypt` uses.  Examples of this are\n  Bcachefs and ZFS.  (Note: ZFS is not part of the upstream kernel.)  Bcachefs\n  encryption is similar to dm-crypt in that it encrypts the full filesystem with\n  one key.  ZFS encryption operates on a per-dataset basis.  If you are using\n  one of these filesystems, refer to the documentation for that filesystem.\n\nWhich solution to use?  Here are our recommendations:\n\n* eCryptfs shouldn't be used, if at all possible.  eCryptfs's use of filesystem\n  stacking causes a number of issues, and eCryptfs is no longer actively\n  maintained.  The original author of eCryptfs recommends using Linux native\n  filesystem encryption instead.  The largest users of eCryptfs (Ubuntu and\n  Chrome OS) have switched to dm-crypt or Linux native filesystem encryption.\n\n* If you need fine-grained control of encryption within a filesystem and you are\n  using a filesystem that supports `fscrypt`, then use `fscrypt`, or `fscrypt`\n  together with dm-crypt/LUKS.  If you don't need this, then use dm-crypt/LUKS.\n\n  To understand this recommendation: consider that the main advantage of\n  `fscrypt` is to allow different files on the same filesystem to be encrypted\n  by different keys, and thus be unlockable, lockable, and securely deletable\n  independently from each other.  Therefore, `fscrypt` is useful in cases such\n  as:\n\n    * Multi-user systems, since each user's files can be encrypted with their\n      own key that is unlocked by their own passphrase.\n\n    * Single-user systems where it's not possible for all files to have the\n      strongest level of protection.  For example, it might be necessary for the\n      system to boot up without user interaction.  Any files that are needed to\n      do so can only be encrypted by a hardware-protected (e.g. TPM-bound) key\n      at best.  If the user's personal files are located on the same filesystem,\n      then with dm-crypt/LUKS the user's personal files would be limited to this\n      weak level of protection.  With `fscrypt`, the user's personal files could\n      be fully protected using the user's passphrase.\n\n  `fscrypt` isn't very useful in the following cases:\n\n    * Single-user systems where the user is willing to enter a strong passphrase\n      at boot time to unlock the entire filesystem.  In this case, the main\n      advantage of `fscrypt` would go unused, so dm-crypt/LUKS would be better\n      as it would provide better security (due to ensuring that all files and\n      all filesystem metadata are encrypted).\n\n    * Any case where it is feasible to create a separate filesystem for every\n      encryption key you want to use.\n\n  Note: dm-crypt/LUKS and `fscrypt` aren't mutually exclusive; they can be used\n  together when the performance hit of double encryption is tolerable.  It only\n  makes sense to do this when the keys for each encryption layer are protected\n  in different ways, such that each layer serves a different purpose.  A\n  reasonable set-up would be to encrypt the whole filesystem with dm-crypt/LUKS\n  using a TPM-bound key that is automatically unlocked at boot time, and also\n  encrypt users' home directories with `fscrypt` using their login passphrases.\n\n## Threat model\n\nLike other storage encryption solutions (including dm-crypt/LUKS and eCryptfs),\nLinux native filesystem encryption is primarily intended to protect the\nconfidentiality of data from a single point-in-time permanent offline compromise\nof the disk.  For a detailed description of the threat model, see the [kernel\ndocumentation](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html#threat-model).\n\nIt's worth emphasizing that none of these encryption solutions protect unlocked\nencrypted files from other users on the same system (that's the job of OS-level\naccess control, such as UNIX file permissions), or from the cloud provider you\nmay be running a virtual machine on.  By themselves, they also do not protect\nfrom \"evil maid\" attacks, i.e. non-permanent offline compromises of the disk.\n\n## Features\n\n`fscrypt` is intended to improve upon the work in\n[e4crypt](http://man7.org/linux/man-pages/man8/e4crypt.8.html) by providing a\nmore managed environment and handling more functionality in the background.\n`fscrypt` has a [design document](https://goo.gl/55cCrI) specifying its full\narchitecture.  See also the [kernel documentation for Linux native filesystem\nencryption](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html).\n\nBriefly, `fscrypt` deals with protectors and policies. Protectors represent some\nsecret or information used to protect the confidentiality of your data. The\nthree currently supported protector types are:\n\n1. Your login passphrase, through [PAM](http://www.linux-pam.org/Linux-PAM-html).\n   The included PAM module (`pam_fscrypt.so`) can automatically unlock\n   directories protected by your login passphrase when you log in, and lock them\n   when you log out.  __IMPORTANT:__ before using a login protector, follow\n   [Setting up for login protectors](#setting-up-for-login-protectors).\n\n2. A custom passphrase.  This passphrase is hashed with\n   [Argon2id](https://en.wikipedia.org/wiki/Argon2), by default calibrated to\n   use all CPUs and take about 1 second.\n\n3. A raw key file.  See [Using a raw key protector](#using-a-raw-key-protector).\n\nThese protectors are mutable, so the information can change without needing to\nupdate any of your encrypted directories.\n\nPolicies represent the actual key passed to the kernel. This \"policy key\" is\nimmutable and policies are (usually) applied to a single directory. Protectors\nthen protect policies, so that having one of the protectors for a policy is\nenough to get the policy key and access the data. Which protectors protect a\npolicy can also be changed. This allows a user to change how a directory is\nprotected without needing to reencrypt the directory's contents.\n\nConcretely, `fscrypt` contains the following functionality:\n*   `fscrypt setup` - Creates `/etc/fscrypt.conf` and the `/.fscrypt` directory\n    * This is the only functionality which always requires root privileges\n*   `fscrypt setup MOUNTPOINT` - Gets a filesystem ready for use with fscrypt\n*   `fscrypt encrypt DIRECTORY` - Encrypts an empty directory\n*   `fscrypt unlock DIRECTORY` - Unlocks an encrypted directory\n*   `fscrypt lock DIRECTORY` - Locks an encrypted directory\n*   `fscrypt purge MOUNTPOINT` - Locks all encrypted directories on a filesystem\n*   `fscrypt status [PATH]` - Gets detailed info about filesystems or paths\n*   `fscrypt metadata` - Manages policies or protectors directly\n\nSee the example usage section below or run `fscrypt COMMAND --help` for more\ninformation about each of the commands.\n\n## Building and installing\n\n`fscrypt` has a minimal set of build dependencies:\n*   [Go](https://golang.org/doc/install) 1.23 or higher. Older versions may work\n    but they are not tested or supported.\n*   A C compiler (`gcc` or `clang`)\n*   `make`\n*   Headers for [`libpam`](http://www.linux-pam.org/).\n    Install them with the appropriate package manager:\n    - Debian/Ubuntu: `sudo apt install libpam0g-dev`\n    - Red Hat: `sudo yum install pam-devel`\n    - Arch: [`pam`](https://www.archlinux.org/packages/core/x86_64/pam/)\n      package (usually installed by default)\n\nOnce all the dependencies are installed, clone the repository by running:\n```shell\ngit clone https://github.com/google/fscrypt\n```\nRunning `make` builds the binary (`fscrypt`) and PAM module (`pam_fscrypt.so`)\nin the `bin/` directory.\n\nRunning `sudo make install` installs `fscrypt` into `/usr/local/bin`,\n`pam_fscrypt.so` into `/usr/local/lib/security`, and `pam_fscrypt/config` into\n`/usr/local/share/pam-configs`.\n\nOn Debian (and Debian derivatives such as Ubuntu), use `sudo make install\nPREFIX=/usr` to install into `/usr` instead of the default of `/usr/local`.\nOrdinarily you shouldn't manually install software into `/usr`, since `/usr` is\nreserved for Debian's own packages.  However, Debian's PAM configuration\nframework only recognizes configuration files in `/usr`, not in `/usr/local`.\nTherefore, the PAM module will only work if you install into `/usr`.  Note: if\nyou later decide to switch to using the Debian package `libpam-fscrypt`, you'll\nhave to first manually run `sudo make uninstall PREFIX=/usr`.\n\nIt is also possible to use `make install-bin` to only install the `fscrypt`\nbinary, or `make install-pam` to only install the PAM files.\n\nAlternatively, if you only want to install the `fscrypt` binary to\n`$GOPATH/bin`, simply run:\n```shell\ngo install github.com/google/fscrypt/cmd/fscrypt@latest\n```\n\nSee the `Makefile` for instructions on how to further customize the build.\n\n## Runtime dependencies\n\nTo run, `fscrypt` needs the following libraries:\n*   `libpam.so` (almost certainly already on your system)\n\nIn addition, `fscrypt` requires a filesystem that supports the Linux native\nfilesystem encryption API.  Currently, the filesystems that support this are:\n\n* ext4, with upstream kernel v4.1 or later.  The kernel configuration must\n  contain `CONFIG_FS_ENCRYPTION=y` (for kernels v5.1+) or\n  `CONFIG_EXT4_ENCRYPTION=y` or `=m` (for older kernels).  The filesystem must\n  also have the `encrypt` feature flag enabled; to enable this flag, see\n  [here](#getting-encryption-not-enabled-on-an-ext4-filesystem).\n\n* f2fs, with upstream kernel v4.2 or later.  The kernel configuration must\n  contain `CONFIG_FS_ENCRYPTION=y` (for kernels v5.1+) or\n  `CONFIG_F2FS_FS_ENCRYPTION=y` (for older kernels).  The filesystem must also\n  have the `encrypt` feature flag enabled; this flag can be enabled at format\n  time by `mkfs.f2fs -O encrypt` or later by `fsck.f2fs -O encrypt`.\n\n* UBIFS, with upstream kernel v4.10 or later.  The kernel configuration must\n  contain `CONFIG_FS_ENCRYPTION=y` (for kernels v5.1+) or\n  `CONFIG_UBIFS_FS_ENCRYPTION=y` (for older kernels).\n\n* CephFS, with upstream kernel v6.6 or later.  The kernel configuration must\n  contain `CONFIG_FS_ENCRYPTION=y`.\n\n* [Lustre](https://www.lustre.org/), with Lustre v2.14.0 or later.  For details,\n  see the Lustre documentation.  Please note that Lustre is not part of the\n  upstream Linux kernel, and its encryption implementation has not been reviewed\n  by the authors of `fscrypt`.  Questions/issues about Lustre encryption should\n  be directed to the Lustre developers.  Lustre version 2.14 does not encrypt\n  filenames, even though it claims to, so v2.15.0 or later should be used.\n\nTo check whether the needed option is enabled in your kernel, run:\n```shell\nzgrep -h ENCRYPTION /proc/config.gz /boot/config-$(uname -r) | sort | uniq\n```\n\nIt is also recommended to use Linux kernel v5.4 or later, since this\nallows the use of v2 encryption policies.  v2 policies have several\nsecurity and usability improvements over v1 policies.\n\nIf you configure `fscrypt` to use non-default features, other kernel\nprerequisites may be needed too.  See [Configuration\nfile](#configuration-file).\n\n## Configuration file\n\nRunning `sudo fscrypt setup` will create the configuration file\n`/etc/fscrypt.conf` if it doesn't already exist.  It's a JSON file\nthat looks like the following:\n\n```\n{\n\t\"source\": \"custom_passphrase\",\n\t\"hash_costs\": {\n\t\t\"time\": \"52\",\n\t\t\"memory\": \"131072\",\n\t\t\"parallelism\": \"32\"\n\t},\n\t\"options\": {\n\t\t\"padding\": \"32\",\n\t\t\"contents\": \"AES_256_XTS\",\n\t\t\"filenames\": \"AES_256_CTS\",\n\t\t\"policy_version\": \"2\"\n\t},\n\t\"use_fs_keyring_for_v1_policies\": false,\n\t\"allow_cross_user_metadata\": false\n}\n```\n\nThe fields are:\n\n* \"source\" is the default source for new protectors.  The choices are\n  \"pam\\_passphrase\", \"custom\\_passphrase\", and \"raw\\_key\".\n\n* \"hash\\_costs\" describes how difficult the passphrase hashing is.\n  By default, `fscrypt setup` calibrates the hashing to use all CPUs\n  and take about 1 second.  The `--time` option to `fscrypt setup` can\n  be used to customize this time when creating the configuration file.\n\n* \"options\" are the encryption options to use for new encrypted\n  directories:\n\n    * \"padding\" is the number of bytes by which filenames are padded\n      before being encrypted.  The choices are \"32\", \"16\", \"8\", and\n      \"4\".  \"32\" is recommended.\n\n    * \"contents\" is the algorithm used to encrypt file contents.  The\n      choices are \"AES_256_XTS\", \"AES_128_CBC\", and \"Adiantum\".\n      Normally, \"AES_256_XTS\" is recommended.\n\n    * \"filenames\" is the algorithm used to encrypt file names.  The\n      choices are \"AES_256_CTS\", \"AES_128_CTS\", \"Adiantum\", and\n      \"AES_256_HCTR2\".  Normally, \"AES_256_CTS\" is recommended.\n\n      To use algorithms other than \"AES_256_XTS\" for contents and\n      \"AES_256_CTS\" for filenames, the needed algorithm(s) may need to\n      be enabled in the Linux kernel's cryptography API.  For example,\n      to use Adiantum, `CONFIG_CRYPTO_ADIANTUM` must be set.  Also,\n      not all combinations of algorithms are allowed; for example,\n      \"Adiantum\" for contents can only be paired with \"Adiantum\" for\n      filenames.  See the [kernel\n      documentation](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html#encryption-modes-and-usage)\n      for more details about the supported algorithms.\n\n    * \"policy\\_version\" is the version of encryption policy to use.\n      The choices are \"1\" and \"2\".  If unset, \"1\" is assumed.\n      Directories created with policy version \"2\" are only usable on\n      kernel v5.4 or later, but are preferable to version \"1\" if you\n      don't mind this restriction.\n\n* \"use\\_fs\\_keyring\\_for\\_v1\\_policies\" specifies whether to add keys for v1\n  encryption policies to the filesystem keyrings, rather than to user keyrings.\n  This can solve [issues with processes being unable to access unlocked\n  encrypted files](#some-processes-cant-access-unlocked-encrypted-files).\n  However, it requires kernel v5.4 or later, and it makes unlocking and locking\n  encrypted directories require root.  (The PAM module will still work.)\n\n  The purpose of this setting is to allow people to take advantage of some of\n  the improvements in Linux v5.4 on encrypted directories that are also\n  compatible with older kernels.  If you don't need compatibility with older\n  kernels, it's better to not use this setting and instead (re-)create your\n  encrypted directories with `\"policy_version\": \"2\"`.\n\n* \"allow\\_cross\\_user\\_metadata\" specifies whether `fscrypt` will allow\n  protectors and policies from other non-root users to be read, e.g. to be\n  offered as options by `fscrypt encrypt`.  The default value is `false`, since\n  other users might be untrusted and could create malicious files.  This can be\n  set to `true` to restore the old behavior on systems where `fscrypt` metadata\n  needs to be shared between multiple users.  Note that this option is\n  independent from the permissions on the metadata files themselves, which are\n  set to 0600 by default; users who wish to share their metadata files with\n  other users would also need to explicitly change their mode to 0644.\n\n## Setting up `fscrypt` on a filesystem\n\n`fscrypt` needs some directories to exist on the filesystem on which encryption\nwill be used:\n\n* `MOUNTPOINT/.fscrypt/policies`\n* `MOUNTPOINT/.fscrypt/protectors`\n\n(If login protectors are used, these must also exist on the root filesystem.)\n\nTo create these directories, run `fscrypt setup MOUNTPOINT`.  If MOUNTPOINT is\nowned by root, as is usually the case, then this command will require root.\n\nThere will be one decision you'll need to make: whether non-root users will be\nallowed to create `fscrypt` metadata (policies and protectors).\n\nIf you say `y`, then these directories will be made world-writable, with the\nsticky bit set so that users can't delete each other's files -- just like\n`/tmp`.  If you say `N`, then these directories will be writable only by root.\n\nSaying `y` maximizes the usability of `fscrypt`, and on most systems it's fine\nto say `y`.  However, on some systems this may be inappropriate, as it will\nallow malicious users to fill the entire filesystem unless filesystem quotas\nhave been configured -- similar to problems that have historically existed with\nother world-writable directories, e.g. `/tmp`.  If you are concerned about this,\nsay `N`.  If you say `N`, then you'll only be able to run `fscrypt` as root to\nset up encryption on users' behalf, unless you manually set custom permissions\non the metadata directories to grant write access to specific users or groups.\n\nIf you chose the wrong mode at `fscrypt setup` time, you can change the\ndirectory permissions at any time.  To enable single-user writable mode, run:\n\n    sudo chmod 0755 MOUNTPOINT/.fscrypt/*\n\nTo enable world-writable mode, run:\n\n    sudo chmod 1777 MOUNTPOINT/.fscrypt/*\n\n## Setting up for login protectors\n\nIf you want any encrypted directories to be protected by your login passphrase,\nyou'll need to:\n\n1. Secure your login passphrase (optional, but strongly recommended)\n2. Enable the PAM module (`pam_fscrypt.so`)\n\nIf you installed `fscrypt` from source rather than from your distro's package\nmanager, you may also need to allow `fscrypt` to check your login passphrase.\n\n### Securing your login passphrase\n\nAlthough `fscrypt` uses a strong passphrase hash algorithm, the security of\nlogin protectors is also limited by the strength of your system's passphrase\nhashing in `/etc/shadow`.  On most Linux distributions, `/etc/shadow` by default\nuses SHA-512 with 5000 rounds, which is much weaker than what `fscrypt` uses.\n\nTo mitigate this, you should use a strong login passphrase.\n\nIf using a strong login passphrase is annoying because it needs to be entered\nfrequently to run `sudo`, consider increasing the `sudo` timeout.  That can be\ndone by adding the following to `/etc/sudoers`:\n```\nDefaults timestamp_timeout=60\n```\n\nYou should also increase the number of rounds that your system's passphrase\nhashing uses (though this doesn't increase security as much as choosing a strong\npassphrase).  To do this, find the line in `/etc/pam.d/passwd` that looks like:\n```\npassword\trequired\tpam_unix.so sha512 shadow nullok\n```\n\nAppend `rounds=1000000` (or another number of your choice; the goal is to make\nthe passphrase hashing take about 1 second, similar to `fscrypt`'s default):\n```\npassword\trequired\tpam_unix.so sha512 shadow nullok rounds=1000000\n```\n\nThen, change your login passphrase to a new, strong passphrase:\n```\npasswd\n```\n\nIf you'd like to keep the same login passphrase (not recommended, as the old\npassphrase hash may still be recoverable from disk), then instead run\n`sudo passwd $USER` and enter your existing passphrase.  This re-hashes your\nexisting passphrase with the new `rounds`.\n\n### Enabling the PAM module\n\nTo enable the PAM module `pam_fscrypt.so`, follow the directions for your Linux\ndistro below.  Enabling the PAM module is needed for login passphrase-protected\ndirectories to be automatically unlocked when you log in (and be automatically\nlocked when you log out), and for login passphrase-protected directories to\nremain accessible when you change your login passphrase.\n\n#### Enabling the PAM module on Debian or Ubuntu\n\nThe official `libpam-fscrypt` package for Debian (and Debian derivatives such as\nUbuntu) will install a configuration file for [Debian's PAM configuration\nframework](https://wiki.ubuntu.com/PAMConfigFrameworkSpec) to\n`/usr/share/pam-configs/fscrypt`.  This file contains reasonable defaults for\nthe PAM module.  To automatically apply these defaults, run\n`sudo pam-auth-update` and follow the on-screen instructions.\n\nThis file also gets installed if you build and install `fscrypt` from source,\nbut it is only installed to the correct location if you use `make install\nPREFIX=/usr` to install into `/usr` instead of the default of `/usr/local`.\n\n#### Enabling the PAM module on Arch Linux\n\nOn Arch Linux, follow the recommendations at the [Arch Linux\nWiki](https://wiki.archlinux.org/index.php/Fscrypt#Auto-unlocking_directories).\n\nWe recommend using the Arch Linux package, either `fscrypt` (official) or\n`fscrypt-git` (AUR).  If you instead install `fscrypt` manually using `sudo make\ninstall`, then in addition to the steps on the Wiki you'll also need to [create\n`/etc/pam.d/fscrypt`](#allowing-fscrypt-to-check-your-login-passphrase).\n\n#### Enabling the PAM module on other Linux distros\n\nOn all other Linux distros, follow the general guidance below to edit\nyour PAM configuration files.\n\nThe `fscrypt` PAM module implements the Auth, Session, and Password\n[types](http://www.linux-pam.org/Linux-PAM-html/sag-configuration-file.html).\n\nThe Password functionality of `pam_fscrypt.so` is used to automatically rewrap\na user's login protector when their unix passphrase changes. An easy way to get\nthe working is to add the line:\n```\npassword    optional    pam_fscrypt.so\n```\nafter `pam_unix.so` in `/etc/pam.d/common-password` or similar.\n\nThe Auth and Session functionality of `pam_fscrypt.so` are used to automatically\nunlock directories when logging in as a user, and lock them when logging out.\nAn easy way to get this working is to add the line:\n```\nauth        optional    pam_fscrypt.so\n```\nafter `pam_unix.so` in `/etc/pam.d/common-auth` or similar, and to add the\nline:\n```\nsession     optional    pam_fscrypt.so\n```\nafter `pam_unix.so` in `/etc/pam.d/common-session` or similar, but before\n`pam_systemd.so` or any other module that accesses the user's home directory or\nwhich starts processes that access the user's home directory during their\nsession.\n\n`pam_fscrypt.so` accepts several options:\n\n* `debug`: print additional debug messages to the syslog.  All hook types accept\n  this option.\n\n* `unlock_only`: only unlock directories (at log-in); don't also lock them (at\n  log-out).  This is only relevant for the \"session\" hook.  Note that in\n  `fscrypt` v0.2.9 and earlier, unlock-only was the default behavior, and\n  `lock_policies` needed to be specified to enable locking.\n\n### Allowing `fscrypt` to check your login passphrase\n\nThis step is only needed if you installed `fscrypt` from source code.\n\nSome Linux distros use restrictive settings in `/etc/pam.d/other` that prevent\nprograms from checking your login passphrase unless a per-program PAM\nconfiguration file grants access.  This prevents `fscrypt` from creating any\nlogin passphrase-protected directories, even without auto-unlocking.  To ensure\nthat `fscrypt` will work properly (if you didn't install an official `fscrypt`\npackage from your distro, which should have already handled this), also create a\nfile `/etc/pam.d/fscrypt` containing:\n```\nauth        required    pam_unix.so\n```\n\n## Backup, restore, and recovery\n\nEncrypted files and directories can't be backed up while they are \"locked\", i.e.\nwhile they appear in encrypted form.  They can only be backed up while they are\nunlocked, in which case they can be backed up like any other files.  Note that\nsince the encryption is transparent, the files won't be encrypted in the backup\n(unless the backup applies its own encryption).\n\nFor the same reason (and several others), an encrypted directory can't be\ndirectly \"moved\" to another filesystem.  However, it is possible to create a new\nencrypted directory on the destination filesystem using `fscrypt encrypt`, then\ncopy the contents of the source directory into it.\n\nFor directories protected by a `custom_passphrase` or `raw_key` protector, all\nmetadata needed to unlock the directory (excluding the actual passphrase or raw\nkey, of course) is located in the `.fscrypt` directory at the root of the\nfilesystem that contains the encrypted directory.  For example, if you have an\nencrypted directory `/home/$USER/private` that is protected by a custom\npassphrase, all `fscrypt` metadata needed to unlock the directory with that\ncustom passphrase will be located in `/home/.fscrypt` if you are using a\ndedicated `/home` filesystem or in `/.fscrypt` if you aren't.  If desired, you\ncan back up the `fscrypt` metadata by making a copy of this directory, although\nthis isn't too important since this metadata is located on the same filesystem\nas the encrypted directory(s).\n\n`pam_passphrase` (login passphrase) protectors are a bit different as they are\nalways stored on the root filesystem, in `/.fscrypt`.  This ties them to the\nspecific system and ensures that each user has only a single login protector.\nTherefore, encrypted directories on a non-root filesystem **can't be unlocked\nvia a login protector if the operating system is reinstalled or if the disk is\nconnected to another system** -- even if the new system uses the same login\npassphrase for the user.\n\nBecause of this, `fscrypt encrypt` will automatically generate a recovery\npassphrase when creating a login passphrase-protected directory on a non-root\nfilesystem.  The recovery passphrase is simply a `custom_passphrase` protector\nwith a randomly generated high-entropy passphrase.  Initially, the recovery\npassphrase is stored in a file in the encrypted directory itself; therefore, to\nuse it you **must** record it in another secure location.  It is strongly\nrecommended to do this.  Then, if ever needed, you can use `fscrypt unlock` to\nunlock the directory with the recovery passphrase (by choosing the recovery\nprotector instead of the login protector).\n\nIf you really want to disable the generation of a recovery passphrase, use the\n`--no-recovery` option.  Only do this if you really know what you are doing and\nare prepared for potential data loss.\n\nAlternative approaches to supporting recovery of login passphrase-protected\ndirectories include the following:\n\n* Manually adding your own recovery protector, using\n  `fscrypt metadata add-protector-to-policy`.\n\n* Backing up and restoring the `/.fscrypt` directory on the root filesystem.\n  Note that after restoring the `/.fscrypt` directory, unlocking the login\n  protectors will require the passphrases they had at the time the backup was\n  made **even if they were changed later**, so make sure to remember these\n  passphrase(s) or record them in a secure location.  Also note that if the UUID\n  of the root filesystem changed, you will need to manually fix the UUID in any\n  `.fscrypt/protectors/*.link` files on other filesystems.\n\nThe auto-generated recovery passphrases should be enough for most users, though.\n\n## Encrypting existing files\n\n`fscrypt` isn't designed to encrypt existing files, as this presents significant\ntechnical challenges and usually is impossible to do securely.  Therefore,\n`fscrypt encrypt` only works on empty directories.\n\nOf course, it is still possible to create an encrypted directory, copy files\ninto it, and delete the original files.  The `mv` command will even work, as it\nwill fall back to a copy and delete ([except on older\nkernels](#getting-operation-not-permitted-when-moving-files-into-an-encrypted-directory)).\nHowever, beware that due to the characteristics of filesystems and storage\ndevices, this may not properly protect the files, as their original contents may\nstill be forensically recoverable from disk even after being deleted.  It's\n**much** better to encrypt files from the very beginning.\n\nThere are only a few cases where copying files into an encrypted directory can\nreally make sense, such as:\n\n* The source files are located on an in-memory filesystem such as `tmpfs`.\n\n* The confidentiality of the source files isn't important, e.g. they are\n  system default files and the user hasn't added any personal files yet.\n\n* The source files are protected by a different `fscrypt` policy, the old and\n  new policies are protected by only the same protector(s), and the old policy\n  uses similar strength encryption.\n\nIf one of the above doesn't apply, then it's probably too late to securely\nencrypt your existing files.\n\nAs a best-effort attempt, you can use the `shred` program to try to erase the\noriginal files.  Here are the recommended commands for \"best-effort\" encryption\nof an existing directory named \"dir\":\n\n```bash\nmkdir dir.new\nfscrypt encrypt dir.new\ncp -a -T dir dir.new\nfind dir -type f -print0 | xargs -0 shred -n1 --remove=unlink\nrm -rf dir\nmv dir.new dir\n```\n\nHowever, beware that `shred` isn't guaranteed to be effective on all storage\ndevices and filesystems.  For example, if you're using an SSD, \"overwrites\" of\ndata typically go to new flash blocks, so they aren't really overwrites.\n\nNote: for reasons similar to the above, changed or removed `fscrypt` protectors\naren't guaranteed to be forensically unrecoverable from disk either.  Thus, the\nuse of weak or default passphrases should be avoided, even if changed later.\n\n## Example usage\n\nAll these examples assume there is an ext4 filesystem which supports\nencryption mounted at `/mnt/disk`.  See\n[here](#getting-encryption-not-enabled-on-an-ext4-filesystem) for how\nto enable encryption support on an ext4 filesystem.\n\n### Setting up fscrypt on a directory\n\n```bash\n# Check which directories on our system support encryption\n\u003e\u003e\u003e\u003e\u003e fscrypt status\nfilesystems supporting encryption: 1\nfilesystems with fscrypt metadata: 0\n\nMOUNTPOINT  DEVICE     FILESYSTEM  ENCRYPTION   FSCRYPT\n/           /dev/sda1  ext4        not enabled  No\n/mnt/disk   /dev/sdb   ext4        supported    No\n\n# Create the global configuration file. Nothing else necessarily needs root.\n\u003e\u003e\u003e\u003e\u003e sudo fscrypt setup\nDefaulting to policy_version 2 because kernel supports it.\nCustomizing passphrase hashing difficulty for this system...\nCreated global config file at \"/etc/fscrypt.conf\".\nAllow users other than root to create fscrypt metadata on the root filesystem?\n(See https://github.com/google/fscrypt#setting-up-fscrypt-on-a-filesystem) [y/N] y\nMetadata directories created at \"/.fscrypt\", writable by everyone.\n\n# Start using fscrypt with our filesystem\n\u003e\u003e\u003e\u003e\u003e sudo fscrypt setup /mnt/disk\nAllow users other than root to create fscrypt metadata on this filesystem? (See\nhttps://github.com/google/fscrypt#setting-up-fscrypt-on-a-filesystem) [y/N] y\nMetadata directories created at \"/mnt/disk/.fscrypt\", writable by everyone.\n\n# Initialize encryption on a new empty directory\n\u003e\u003e\u003e\u003e\u003e mkdir /mnt/disk/dir1\n\u003e\u003e\u003e\u003e\u003e fscrypt encrypt /mnt/disk/dir1\nThe following protector sources are available:\n1 - Your login passphrase (pam_passphrase)\n2 - A custom passphrase (custom_passphrase)\n3 - A raw 256-bit key (raw_key)\nEnter the source number for the new protector [2 - custom_passphrase]: 2\nEnter a name for the new protector: Super Secret\nEnter custom passphrase for protector \"Super Secret\":\nConfirm passphrase:\n\"/mnt/disk/dir1\" is now encrypted, unlocked, and ready for use.\n\n# We can see this created one policy and one protector for this directory\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk\next4 filesystem \"/mnt/disk\" has 1 protector and 1 policy\n\nPROTECTOR         LINKED  DESCRIPTION\n7626382168311a9d  No      custom protector \"Super Secret\"\n\nPOLICY                            UNLOCKED  PROTECTORS\n16382f282d7b29ee27e6460151d03382  Yes       7626382168311a9d\n```\n\n#### Quiet version\n```bash\n\u003e\u003e\u003e\u003e\u003e sudo fscrypt setup --quiet --force --all-users\n\u003e\u003e\u003e\u003e\u003e sudo fscrypt setup /mnt/disk --quiet --all-users\n\u003e\u003e\u003e\u003e\u003e echo \"hunter2\" | fscrypt encrypt /mnt/disk/dir1 --quiet --source=custom_passphrase  --name=\"Super Secret\"\n```\n\n### Locking and unlocking a directory\n\n```bash\n# Write a file to our encrypted directory.\n\u003e\u003e\u003e\u003e\u003e echo \"Hello World\" \u003e /mnt/disk/dir1/secret.txt\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk/dir1\n\"/mnt/disk/dir1\" is encrypted with fscrypt.\n\nPolicy:   16382f282d7b29ee27e6460151d03382\nOptions:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2\nUnlocked: Yes\n\nProtected with 1 protector:\nPROTECTOR         LINKED  DESCRIPTION\n7626382168311a9d  No      custom protector \"Super Secret\"\n\n# Lock the directory.  Note: if using a v1 encryption policy instead\n# of v2, you'll need 'sudo fscrypt lock /mnt/disk/dir1 --user=$USER'.\n\u003e\u003e\u003e\u003e\u003e fscrypt lock /mnt/disk/dir1\n\"/mnt/disk/dir1\" is now locked.\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk/dir1\n\"/mnt/disk/dir1\" is encrypted with fscrypt.\n\nPolicy:   16382f282d7b29ee27e6460151d03382\nOptions:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2\nUnlocked: No\n\nProtected with 1 protector:\nPROTECTOR         LINKED  DESCRIPTION\n7626382168311a9d  No      custom protector \"Super Secret\"\n\n# Now the filenames and file contents are inaccessible\n\u003e\u003e\u003e\u003e\u003e ls /mnt/disk/dir1\nu,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P\n\u003e\u003e\u003e\u003e\u003e cat /mnt/disk/dir1/u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P\ncat: /mnt/disk/dir1/u,k20l9HrtrizDjh0zGkw2dTfBkX4T0ZDUlsOhBLl4P: Required key not available\n\n# Unlocking the directory makes the contents available\n\u003e\u003e\u003e\u003e\u003e fscrypt unlock /mnt/disk/dir1\nEnter custom passphrase for protector \"Super Secret\":\n\"/mnt/disk/dir1\" is now unlocked and ready for use.\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk/dir1\n\"/mnt/disk/dir1\" is encrypted with fscrypt.\n\nPolicy:   16382f282d7b29ee27e6460151d03382\nOptions:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2\nUnlocked: Yes\n\nProtected with 1 protector:\nPROTECTOR         LINKED  DESCRIPTION\n7626382168311a9d  No      custom protector \"Super Secret\"\n\u003e\u003e\u003e\u003e\u003e cat /mnt/disk/dir1/secret.txt\nHello World\n```\n\n#### Quiet version\n```bash\n\u003e\u003e\u003e\u003e\u003e fscrypt lock /mnt/disk/dir1 --quiet\n\u003e\u003e\u003e\u003e\u003e echo \"hunter2\" | fscrypt unlock /mnt/disk/dir1 --quiet\n```\n\n### Protecting a directory with your login passphrase\n\nFirst, ensure that you have properly [set up your system for login\nprotectors](#setting-up-for-login-protectors).\n\nThen, you can protect directories with your login passphrase as follows:\n\n```bash\n# Select your login passphrase as the desired source.\n\u003e\u003e\u003e\u003e\u003e mkdir /mnt/disk/dir2\n\u003e\u003e\u003e\u003e\u003e fscrypt encrypt /mnt/disk/dir2\nShould we create a new protector? [y/N] y\nThe following protector sources are available:\n1 - Your login passphrase (pam_passphrase)\n2 - A custom passphrase (custom_passphrase)\n3 - A raw 256-bit key (raw_key)\nEnter the source number for the new protector [2 - custom_passphrase]: 1\nEnter login passphrase for joerichey:\n\"/mnt/disk/dir2\" is now encrypted, unlocked, and ready for use.\n\n# Note that the login protector actually sits on the root filesystem\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk/dir2\n\"/mnt/disk/dir2\" is encrypted with fscrypt.\n\nPolicy:   fe1c92009abc1cff4f3257c77e8134e3\nOptions:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2\nUnlocked: Yes\n\nProtected with 1 protector:\nPROTECTOR         LINKED   DESCRIPTION\n6891f0a901f0065e  Yes (/)  login protector for joerichey\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk\next4 filesystem \"/mnt/disk\" has 2 protectors and 2 policies\n\nPROTECTOR         LINKED   DESCRIPTION\n7626382168311a9d  No       custom protector \"Super Secret\"\n6891f0a901f0065e  Yes (/)  login protector for joerichey\n\nPOLICY                            UNLOCKED  PROTECTORS\n16382f282d7b29ee27e6460151d03382  Yes       7626382168311a9d\nfe1c92009abc1cff4f3257c77e8134e3  Yes       6891f0a901f0065e\n\u003e\u003e\u003e\u003e\u003e fscrypt status /\next4 filesystem \"/\" has 1 protector(s) and 0 policy(ies)\n\nPROTECTOR         LINKED  DESCRIPTION\n6891f0a901f0065e  No      login protector for joerichey\n```\n\n#### Quiet version\n```bash\n\u003e\u003e\u003e\u003e\u003e mkdir /mnt/disk/dir2\n\u003e\u003e\u003e\u003e\u003e echo \"password\" | fscrypt encrypt /mnt/disk/dir2 --source=pam_passphrase --quiet\n```\n\n### Changing a custom passphrase\n```bash\n# First we have to figure out which protector we wish to change.\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk/dir1\n\"/mnt/disk/dir1\" is encrypted with fscrypt.\n\nPolicy:   16382f282d7b29ee27e6460151d03382\nOptions:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2\nUnlocked: Yes\n\nProtected with 1 protector:\nPROTECTOR         LINKED  DESCRIPTION\n7626382168311a9d  No      custom protector \"Super Secret\"\n\n# Now specify the protector directly to the metadata command\n\u003e\u003e\u003e\u003e\u003e fscrypt metadata change-passphrase --protector=/mnt/disk:7626382168311a9d\nEnter old custom passphrase for protector \"Super Secret\":\nEnter new custom passphrase for protector \"Super Secret\":\nConfirm passphrase:\nPassphrase for protector 7626382168311a9d successfully changed.\n```\n\n#### Quiet version\n```bash\n\u003e\u003e\u003e\u003e\u003e printf \"hunter2\\nhunter3\" | fscrypt metadata change-passphrase --protector=/mnt/disk:7626382168311a9d --quiet\n```\n\n### Using a raw key protector\n\n`fscrypt` also supports protectors which use raw key files as the user-provided\nsecret. These key files must be exactly 32 bytes long and contain the raw binary\ndata of the key. Obviously, make sure to store the key file securely (and not in\nthe directory you are encrypting with it). If generating the keys on Linux make\nsure you are aware of\n[how randomness works](http://man7.org/linux/man-pages/man7/random.7.html) and\n[some common myths](https://www.2uo.de/myths-about-urandom/).\n\n```bash\n# Generate a 256-bit key file\n\u003e\u003e\u003e\u003e\u003e head --bytes=32 /dev/urandom \u003e secret.key\n\n# Now create a key file protector without using it on a directory. Note that we\n# could also use `fscrypt encrypt --key=secret.key` to achieve the same thing.\n\u003e\u003e\u003e\u003e\u003e fscrypt metadata create protector /mnt/disk\nCreate new protector on \"/mnt/disk\" [Y/n] y\nThe following protector sources are available:\n1 - Your login passphrase (pam_passphrase)\n2 - A custom passphrase (custom_passphrase)\n3 - A raw 256-bit key (raw_key)\nEnter the source number for the new protector [2 - custom_passphrase]: 3\nEnter a name for the new protector: Skeleton\nEnter key file for protector \"Skeleton\": secret.key\nProtector 2c75f519b9c9959d created on filesystem \"/mnt/disk\".\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk\next4 filesystem \"/mnt/disk\" has 3 protectors and 2 policies\n\nPROTECTOR         LINKED   DESCRIPTION\n7626382168311a9d  No       custom protector \"Super Secret\"\n2c75f519b9c9959d  No       raw key protector \"Skeleton\"\n6891f0a901f0065e  Yes (/)  login protector for joerichey\n\nPOLICY                            UNLOCKED  PROTECTORS\n16382f282d7b29ee27e6460151d03382  Yes       7626382168311a9d\nfe1c92009abc1cff4f3257c77e8134e3  Yes       6891f0a901f0065e\n\n# Finally, we could apply this key to a directory\n\u003e\u003e\u003e\u003e\u003e mkdir /mnt/disk/dir3\n\u003e\u003e\u003e\u003e\u003e fscrypt encrypt /mnt/disk/dir3 --protector=/mnt/disk:2c75f519b9c9959d\nEnter key file for protector \"Skeleton\": secret.key\n\"/mnt/disk/dir3\" is now encrypted, unlocked, and ready for use.\n```\n\n#### Quiet version\n```bash\n\u003e\u003e\u003e\u003e\u003e head --bytes=32 /dev/urandom \u003e secret.key\n\u003e\u003e\u003e\u003e\u003e fscrypt encrypt /mnt/disk/dir3 --key=secret.key --source=raw_key --name=Skeleton\n```\n\n### Using multiple protectors for a policy\n\n`fscrypt` supports the idea of protecting a single directory with multiple\nprotectors. This means having access to any of the protectors is sufficient to\ndecrypt the directory. This is useful for sharing data or setting up access\ncontrol systems.\n\n```bash\n# Add an existing protector to the policy for some directory\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk\next4 filesystem \"/mnt/disk\" has 3 protectors and 3 policies\n\nPROTECTOR         LINKED   DESCRIPTION\n7626382168311a9d  No       custom protector \"Super Secret\"\n2c75f519b9c9959d  No       raw key protector \"Skeleton\"\n6891f0a901f0065e  Yes (/)  login protector for joerichey\n\nPOLICY                            UNLOCKED  PROTECTORS\nd03fb894584a4318d1780e9a7b0b47eb  No        2c75f519b9c9959d\n16382f282d7b29ee27e6460151d03382  No        7626382168311a9d\nfe1c92009abc1cff4f3257c77e8134e3  No        6891f0a901f0065e\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk/dir1\n\"/mnt/disk/dir1\" is encrypted with fscrypt.\n\nPolicy:   16382f282d7b29ee27e6460151d03382\nOptions:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2\nUnlocked: No\n\nProtected with 1 protector:\nPROTECTOR         LINKED  DESCRIPTION\n7626382168311a9d  No      custom protector \"Super Secret\"\n\u003e\u003e\u003e\u003e\u003e fscrypt metadata add-protector-to-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382\nWARNING: All files using this policy will be accessible with this protector!!\nProtect policy 16382f282d7b29ee27e6460151d03382 with protector 2c75f519b9c9959d? [Y/n]\nEnter key file for protector \"Skeleton\": secret.key\nEnter custom passphrase for protector \"Super Secret\":\nProtector 2c75f519b9c9959d now protecting policy 16382f282d7b29ee27e6460151d03382.\n\u003e\u003e\u003e\u003e\u003e fscrypt status /mnt/disk/dir1\n\"/mnt/disk/dir1\" is encrypted with fscrypt.\n\nPolicy:   16382f282d7b29ee27e6460151d03382\nOptions:  padding:32 contents:AES_256_XTS filenames:AES_256_CTS policy_version:2\nUnlocked: No\n\nProtected with 2 protectors:\nPROTECTOR         LINKED  DESCRIPTION\n7626382168311a9d  No      custom protector \"Super Secret\"\n2c75f519b9c9959d  No      raw key protector \"Skeleton\"\n\n# Now the unlock command will prompt for which protector we want to use\n\u003e\u003e\u003e\u003e\u003e fscrypt unlock /mnt/disk/dir1\nThe available protectors are:\n0 - custom protector \"Super Secret\"\n1 - raw key protector \"Skeleton\"\nEnter the number of protector to use: 1\nEnter key file for protector \"Skeleton\": secret.key\n\"/mnt/disk/dir1\" is now unlocked and ready for use.\n\n# The protector can also be removed from the policy (if it is not the only one)\n\u003e\u003e\u003e\u003e\u003e fscrypt metadata remove-protector-from-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382\nWARNING: All files using this policy will NO LONGER be accessible with this protector!!\nStop protecting policy 16382f282d7b29ee27e6460151d03382 with protector 2c75f519b9c9959d? [y/N] y\nProtector 2c75f519b9c9959d no longer protecting policy 16382f282d7b29ee27e6460151d03382.\n```\n\n#### Quiet version\n```bash\n\u003e\u003e\u003e\u003e\u003e echo \"hunter2\" | fscrypt metadata add-protector-to-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382 --key=secret.key --quiet\n\u003e\u003e\u003e\u003e\u003e fscrypt metadata remove-protector-from-policy --protector=/mnt/disk:2c75f519b9c9959d --policy=/mnt/disk:16382f282d7b29ee27e6460151d03382 --quiet --force\n```\n\n## Contributing\n\nWe would love to accept your contributions to `fscrypt`. See the\n`CONTRIBUTING.md` file for more information about signing the CLA and submitting\na pull request.\n\n## Troubleshooting\n\nIn general, if you are encountering issues with `fscrypt`,\n[open an issue](https://github.com/google/fscrypt/issues/new), following the\nguidelines in `CONTRIBUTING.md`. We will try our best to help.\n\n#### I changed my login passphrase, now all my directories are inaccessible\n\nUsually, the PAM module `pam_fscrypt.so` will automatically detect changes to a\nuser's login passphrase and update the user's `fscrypt` login protector so that\nthey retain access their login-passphrase protected directories.  However,\nsometimes a user's login passphrase can become desynchronized from their\n`fscrypt` login protector.  This can happen if `root` assigns the user a new\npassphrase without providing the old one, if the user's login passphrase is\nmanaged by an external system such as LDAP, if the PAM module is not installed,\nor if the PAM module is not properly configured.  See [Enabling the PAM\nmodule](#enabling-the-pam-module) for how to configure the PAM module.\n\nTo fix a user's login protector, find the corresponding protector ID by running\n`fscrypt status \"/\"`.  Then, change this protector's passphrase by running:\n```\nfscrypt metadata change-passphrase --protector=/:ID\n```\n\n#### Directories using my login passphrase are not automatically unlocking\n\nFirst, directories won't unlock if your session starts without password\nauthentication.  The most common case of this is public-key ssh login.  To\ntrigger a password authentication event, run `su $USER -c exit`.\n\nIf your session did start with password authentication, then the following may\nbe causing the issue:\n\n* The PAM module might not be configured correctly.  Ensure you have correctly\n  [configured the PAM module](#enabling-the-pam-module).\n\n* If your login passphrase recently changed, then it might have gotten out of\n  sync with your login protector.  To fix this, [manually change your login\n  protector's\n  passphrase](#i-changed-my-login-passphrase-now-all-my-directories-are-inaccessible)\n  to get it back in sync with your actual login passphrase.\n\n* Due to a [bug in sshd](https://bugzilla.mindrot.org/show_bug.cgi?id=2548),\n  encrypted directories won't auto-unlock when logging in with ssh using the\n  `ChallengeResponseAuthentication` ssh authentication method, which is also\n  called `KbdInteractiveAuthentication`.  This ssh authentication method\n  implements password authentication by default, so it might appear similar to\n  `PasswordAuthentication`.  However, only `PasswordAuthentication` works with\n  `fscrypt`.  To avoid this issue, make sure that your `/etc/ssh/sshd_config`\n  file contains `PasswordAuthentication yes`, `UsePAM yes`, and either\n  `ChallengeResponseAuthentication no` or `KbdInteractiveAuthentication no`.\n\n#### Getting \"encryption not enabled\" on an ext4 filesystem\n\nThis is usually caused by your ext4 filesystem not having the `encrypt` feature\nflag enabled.  The `encrypt` feature flag allows the filesystem to contain\nencrypted files.  (It doesn't actually encrypt anything by itself.)\n\nBefore enabling `encrypt` on your ext4 filesystem, first ensure that all of the\nfollowing are true for you:\n\n* You only need to use your filesystem on kernels v4.1 and later.\n\n  (Kernels v4.0 and earlier can't mount ext4 filesystems that have the `encrypt`\n  feature flag.)\n\n* Either you only need to use your filesystem on kernels v5.5 and later, or your\n  kernel page size (run `getconf PAGE_SIZE`) and filesystem block size (run\n  `tune2fs -l /dev/device | grep 'Block size'`) are the same.\n\n  (Both values will almost always be 4096, but they may differ if your\n  filesystem is very small, if your system uses the PowerPC CPU architecture, or\n  if you overrode the default block size when you created the filesystem.  Only\n  kernels v5.5 and later support ext4 encryption in such cases.)\n\n* Either you aren't using GRUB to boot directly off the filesystem in question,\n  or you are using GRUB 2.04 or later.\n\n  (Old versions of GRUB can't boot from ext4 filesystems that have `encrypt`\n  enabled.  If, like most people, you have a separate `/boot` partition, you are\n  fine.  You are also fine if you are using the GRUB Debian package `2.02-2` or\n  later [*not* `2.02_beta*`], including the version in Ubuntu 18.04 and later,\n  since the patch to support `encrypt` was backported.)\n\nAfter verifying all of the above, enable `encrypt` by running:\n```\ntune2fs -O encrypt /dev/device\n```\n\nIf you need to undo this, first delete all encrypted files and directories on\nthe filesystem.  Then, run:\n```\nfsck -fn /dev/device\ndebugfs -w -R \"feature -encrypt\" /dev/device\nfsck -fn /dev/device\n``` \n\nIf you've enabled `encrypt` but you still get the \"encryption not enabled\"\nerror, then the problem is that ext4 encryption isn't enabled in your kernel\nconfig.  See [Runtime dependencies](#runtime-dependencies) for how to enable it.\n\n#### Getting \"user keyring not linked into session keyring\"\n\nSome older versions of Ubuntu didn't link the user keyring into the session\nkeyring, which caused problems with `fscrypt`.\n\nTo avoid this issue, upgrade to Ubuntu 20.04 or later.\n\n#### Getting \"Operation not permitted\" when moving files into an encrypted directory\n\nOriginally, filesystems didn't return the correct error code when attempting to\nrename unencrypted files (or files with a different encryption policy) into an\nencrypted directory.  Specifically, they returned `EPERM` instead of `EXDEV`,\nwhich caused `mv` to fail rather than fall back to a copy as expected.\n\nThis bug was fixed in version 5.1 of the mainline Linux kernel, as well as in\nversions 4.4 and later of the LTS (Long Term Support) branches of the Linux\nkernel; specifically v4.19.155, 4.14.204, v4.9.242, and v4.4.242.\n\nIf the kernel can't be upgraded, this bug can be worked around by explicitly\ncopying the files instead, e.g. with `cp`.\n\n__IMPORTANT:__ Encrypting existing files can be insecure.  Before doing so, read\n[Encrypting existing files](#encrypting-existing-files).\n\n#### Getting \"Package not installed\" when trying to use an encrypted directory\n\nTrying to create or open an encrypted file will fail with `ENOPKG` (\"Package not\ninstalled\") when the kernel doesn't support one or more of the cryptographic\nalgorithms used by the file or its directory.  Note that `fscrypt encrypt` and\n`fscrypt unlock` will still succeed; it's only using the directory afterwards\nthat will fail.\n\nThe kernel will always support the algorithms that `fscrypt` uses by default.\nHowever, if you changed the contents and/or filenames encryption algorithms in\n[`/etc/fscrypt.conf`](#configuration-file), then you may run into this issue.\nTo fix it, enable the needed `CONFIG_CRYPTO_*` options in your Linux kernel\nconfiguration.  See the [kernel\ndocumentation](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html#encryption-modes-and-usage)\nfor details about which option(s) are required for each encryption mode.\n\n#### Some processes can't access unlocked encrypted files\n\nThis issue is caused by a limitation in the original design of Linux native\nfilesystem encryption which made it difficult to ensure that all processes can\naccess unlocked encrypted files.  This issue can manifest in many ways, such as:\n\n* SSH to a user with an encrypted home directory not working, even when that\n  directory is already unlocked\n\n* Docker containers being unable to access encrypted files that were unlocked\n  from outside the container\n\n* NetworkManager being unable to access certificates stored in the user's\n  already-unlocked encrypted home directory\n\n* Other system services being unable to access already-unlocked encrypted files\n\n* `sudo` sessions being unable to access already-unlocked encrypted files\n\n* A user being unable to access encrypted files that were unlocked by root\n\nIf an OS-level error is shown, it is `ENOKEY` (\"Required key not available\").\n\nTo fix this issue, first run `fscrypt status $dir`, where `$dir` is your\nencrypted directory.  If the output contains `policy_version:2`, then your issue\nis something else, so stop reading now.  If the output contains\n`policy_version:1` or doesn't contain any mention of `policy_version`, then\nyou'll need to upgrade your directory(s) to policy version 2.  To do this:\n\n1. Upgrade to Linux kernel v5.4 or later.\n\n2. Upgrade to `fscrypt` v0.2.7 or later.\n\n3. Run `sudo fscrypt setup --force`.\n\n4. Re-encrypt your encrypted directory(s).  Since files cannot be (re-)encrypted\n   in-place, this requires replacing them with new directories.  For example:\n   ```\n     fscrypt unlock dir  # if not already unlocked\n     mkdir dir.new\n     fscrypt encrypt dir.new\n     cp -a -T dir dir.new\n     find dir -type f -print0 | xargs -0 shred -n1 --remove=unlink\n     rm -rf dir\n     mv dir.new dir\n   ```\n\n   You don't need to create a new protector.  I.e., when `fscrypt encrypt` asks\n   for a protector, just choose the one you were using before.\n\n5. `fscrypt status` on your directory(s) should now show `policy_version:2`,\n   and the issue should be gone.\n\nNote that once your directories are using policy version 2, they will only be\nusable with Linux kernel v5.4 and later and `fscrypt` v0.2.6 and later.  So be\ncareful not to downgrade your software past those versions.\n\nThis issue can also be fixed by setting `\"use_fs_keyring_for_v1_policies\": true`\nin `/etc/fscrypt.conf`, as described in [Configuration\nfile](#configuration-file).  This avoids needing to upgrade directories to\npolicy version 2.  However, this has some limitations, and the same kernel and\n`fscrypt` prerequisites still apply for this option to take effect.  It is\nrecommended to upgrade your directories to policy version 2 instead.\n\n#### Users can access other users' unlocked encrypted files\n\nThis is working as intended.  When an encrypted directory is unlocked (or\nlocked), it is unlocked (or locked) for all users.  Encryption is not access\ncontrol; the Linux kernel already has many access control mechanisms, such as\nthe standard UNIX file permissions, that can be used to control access to files.\n\nSetting the mode of your encrypted directory to `0700` will prevent users other\nthan the directory's owner and `root` from accessing it while it is unlocked.\nIn `fscrypt` v0.2.5 and later, `fscrypt encrypt` sets this mode automatically.\n\nHaving the locked/unlocked status of directories be global instead of per-user\nmay seem unintuitive, but it is actually the only logical way.  The encryption\nis done by the filesystem, so in reality the filesystem either has the key or it\ndoesn't.  And once it has the key, any additional checks of whether particular\nusers \"have\" the key would be OS-level access control checks (not cryptography)\nthat are redundant with existing OS-level access control mechanisms.\n\nSimilarly, any attempt of the filesystem encryption feature to prevent `root`\nfrom accessing unlocked encrypted files would be pointless.  On Linux systems,\n`root` is usually all-powerful and can always get access to files in ways that\ncannot be prevented, e.g. `setuid()` and `ptrace()`.  The only reliable way to\nlimit what `root` can do is via a mandatory access control system, e.g. SELinux.\n\nThe original design of Linux native filesystem encryption actually did put the\nkeys into per-user keyrings.  However, this caused a [massive number of\nproblems](#some-processes-cant-access-unlocked-encrypted-files), as it's\nactually very common that encrypted files need to be accessed by processes\nrunning under different user IDs -- even if it may not be immediately apparent.\n\n#### Getting \"Required key not available\" when backing up locked encrypted files\n\nEncrypted files can't be backed up while locked; you need to unlock them first.\nFor details, see [Backup, restore, and recovery](#backup-restore-and-recovery).\n\n#### The reported size of encrypted symlinks is wrong\n\nOriginally, filesystems didn't conform to POSIX when reporting the size of\nencrypted symlinks, as they gave the size of the ciphertext symlink target\nrather than the size of the plaintext target.  This would make the reported size\nof symlinks appear to be slightly too large when queried using ``lstat()`` or\nsimilar system calls.  Most programs don't care about this, but in rare cases\nprograms can depend on the filesystem reporting symlink sizes correctly.\n\nThis bug was fixed in version 5.15 of the mainline Linux kernel, as well as in\nversions 4.19 and later of the LTS (Long Term Support) branches of the Linux\nkernel; specifically v5.10.63, v5.4.145, and v4.19.207.\n\nIf the kernel can't be upgraded, the only workaround for this bug is to update\nany affected programs to not depend on symlink sizes being reported correctly.\n\n## Legal\n\nCopyright 2017 Google Inc. under the\n[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0); see the\n`LICENSE` file for more information.\n\nAuthor: Joe Richey \u003cjoerichey@google.com\u003e\n\nThis is not an official Google product.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Ffscrypt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Ffscrypt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Ffscrypt/lists"}