{"id":13452393,"url":"https://github.com/iqlusioninc/sear","last_synced_at":"2025-05-13T16:18:42.661Z","repository":{"id":37924626,"uuid":"170564789","full_name":"iqlusioninc/sear","owner":"iqlusioninc","description":"Signed/Encrypted ARchive: always-encrypted tar-like archive tool with optional signature support","archived":false,"fork":false,"pushed_at":"2023-01-11T13:01:39.000Z","size":330,"stargazers_count":354,"open_issues_count":11,"forks_count":9,"subscribers_count":10,"default_branch":"develop","last_synced_at":"2024-10-01T08:48:41.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/iqlusioninc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-13T19:17:05.000Z","updated_at":"2024-08-20T02:07:37.000Z","dependencies_parsed_at":"2023-02-09T03:01:04.720Z","dependency_job_id":null,"html_url":"https://github.com/iqlusioninc/sear","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqlusioninc%2Fsear","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqlusioninc%2Fsear/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqlusioninc%2Fsear/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqlusioninc%2Fsear/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iqlusioninc","download_url":"https://codeload.github.com/iqlusioninc/sear/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221900927,"owners_count":16898993,"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","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":[],"created_at":"2024-07-31T07:01:22.859Z","updated_at":"2024-10-28T18:31:17.071Z","avatar_url":"https://github.com/iqlusioninc.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# \u003cimg src=\"https://raw.githubusercontent.com/iqlusioninc/sear/develop/img/sear-logo.png\" width=\"450\" height=\"150\"\u003e\n\n[![Crate][crate-img]][crate-link]\n[![Docs][docs-img]][docs-link]\n[![Apache 2.0 License][license-image]][license-link]\n![MSRV][msrv-image]\n[![Safety Dance][safety-image]][safety-link]\n[![Build Status][build-image]][build-link]\n[![Gitter Chat][gitter-image]][gitter-link]\n\nAn always-encrypted *tar*-like file archive format with support for Ed25519\ndigital signatures.\n\n## What is sear?\n\n`sear` is a command-line tool and Rust library for producing tar-like\narchives containing multiple files and potentially preserving attributes\nincluding file ownership, modes/permissions, access control lists,\nSELinux security contexts, and extended attributes (a.k.a. xattrs).\n\nAdditionally, `sear` integrates functionality traditionally provided by\na separate additional encryption tool such as *gpg*. However, where *gpg*\nattempts to be a one-size-fits-all encryption which includes a large number\nof complicated features (web-of-trust security model, messaging/encrypted email\nsupport), `sear` is laser-focused on encrypting and authenticating (via\ndigital signatures) archives of files.\n\n## Installation\n\nNOTE: `sear` is presently vaporware, so this won't do a whole lot yet.\n\n1. [Install Rust] (1.39+)\n2. Run `cargo install sear`\n\n## File Format\n\n*NOTE: This description is presently expert-oriented. We'll have a simpler\ndescription up later!*\n\n`sear` archives have the following high-level structure:\n\n```\n| file 1 | file 2 | file 3 | ... | file N | footer |\n```\n\n...where each of the files consist of segmented AEAD-encrypted ciphertexts of\nthe original file. No additional framing is added to files, although each\nsegment of a file includes an individual authentication tag (i.e. MAC).\n\n### Encryption\n\nWhen constructing the archive, all plaintexts are first concatenated, and then\nencrypted as a single message stream, under a single key/nonce. This means\nindividual segments may span multiple files - a separate stream per file\nis NOT used. This provides the most space efficient means of storing files,\nand can gracefully handle many small files without adding an undue number\nof authentication tags.\n\nSegmented AEAD encryption allows for streaming encryption/decryption of\nindividual files and archives, and also seekability within the archive.\nTo facilitate such encryption securely, a construction from the new\n[Google Tink] cryptography is leveraged, which combines the following:\n\n- [HKDF] key derivation\n- [AES-GCM] encryption\n- [STREAM] segmented AEAD construction\n\nThe STREAM construction has a rigorous and provable security definition:\nit provides a Nonce-based Online Authenticated Encryption (nOAE) scheme\nand defends against reordering and truncation attacks which are often\npossible with naive streaming encryption schemes. However, it also provides\nseekability, allowing individual files within the archive to be decrypted,\nin addition to seeking within those files.\n\n### Metadata\n\nFile metadata is buffered during archive creation, and serialized at the\nend of the file as a footer using [Protocol Buffers].\n\nThe footer itself is split into an encrypted portion at the beginning followed\nby a minimal plaintext portion at the very end of the file. It contains the\nfollowing attributes - ones with ℰ next to them are in the encrypted portion\nof the footer:\n\n- **UUID:** random identifier for this file, and also the nonce for encryption.\n- **Chunk size:** granularity at which streaming encryption/decryption occurs.\n  Files are split apart into fixed-sized chunks prior to encryption.\n- **Encryption key fingerprint:** (optional) fingerprint of the encryption key\n  as a [CryptoURI].\n- **Signing key fingerprint:** (optional) fingerprint of the signing key as a\n  [CryptoURI].\n- **Signature:** (optional) a signature over the contents of the file. See\n  below for more information on how this is computed.\n- **Creator:** (optional, ℰ) username and hostname where archive was created\n- **Date:** (ℰ) timestamp for when the archive was created\n- **File attributes:** (ℰ) each entry in the file can have the following\n  attributes:\n  - **Path:** location of the file\n  - **Length:** length of the file in bytes. Offsets within the ciphertext\n    are computed as a running total of these values (and offset by the AEAD\n    tags on each file segment).\n  - **Owner:** username and groupname who own the file (TODO: UID/GID?)\n  - **Permissions:** access control attributes consisting of the following:\n    - **UNIX mode:** the `chmod`-style mode of the file with user, group, and\n      world permission attributes\n    - **POSIX ACLs:** expressive ACLs on file ownership\n    - **SELinux Labels:** SELinux policy-related metadata\n    - **xattr:** extended attributes\n\n### Signatures\n\nSignatures are optional, and computed over a [Merkle tree] of the ciphertexts\nof the message segments (note that each message segment is further\nauthenticated by an AEAD tag). This allows for the signature to authenticate\nany individual segment within the archive without the entire file being\npresent on disk.\n\nSignature keys are generated and stored as [CryptoURI]s. The only signature\nalgorithm presently supported by this tool is Ed25519. One of the goals for\nthe tool is to allow signatures to be computed by a [YubiHSM2], allowing the\nsignature to be hardware-backed.\n\n### Encryption Keys\n\n`sear` supports the following keys, which are all serialized in [CryptoURI]\nformat:\n\n- **Symmetric:** raw input key material for Tink HKDF-AES-GCM-STREAM\n- **Asymmetric** derive IKM from static public key + ephemeral scalar using\n  a Noise `NK`-like key exchange pattern\n- **Password:** generate and store a random salt, and use it together with\n  the password as input to Argon2i to derive a password.\n\n## Code of Conduct\n\nWe abide by the [Contributor Covenant][cc] and ask that you do as well.\n\nFor more information, please see [CODE_OF_CONDUCT.md].\n\n## License\n\nCopyright © 2019-2020 iqlusion\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    https://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in the work by you shall be dual licensed as above,\nwithout any additional terms or conditions.\n\n[//]: # (badges)\n\n[crate-img]: https://img.shields.io/crates/v/sear.svg\n[crate-link]: https://crates.io/crates/sear\n[docs-img]: https://docs.rs/sear/badge.svg\n[docs-link]: https://docs.rs/sear/\n[license-image]: https://img.shields.io/badge/license-Apache2.0-blue.svg\n[license-link]: https://github.com/iqlusioninc/sear/blob/develop/LICENSE\n[msrv-image]: https://img.shields.io/badge/rustc-1.39+-blue.svg\n[safety-image]: https://img.shields.io/badge/unsafe-forbidden-success.svg\n[safety-link]: https://github.com/rust-secure-code/safety-dance/\n[build-image]: https://github.com/iqlusioninc/sear/workflows/Rust/badge.svg?branch=develop\u0026event=push\n[build-link]: https://github.com/iqlusioninc/sear/actions\n[gitter-image]: https://badges.gitter.im/iqlusioninc/sear.svg\n[gitter-link]: https://gitter.im/iqlusioninc/community\n\n[//]: # (general links)\n\n[Install Rust]: https://www.rust-lang.org/en-US/install.html\n[Google Tink]: https://github.com/google/tink\n[HKDF]: https://en.wikipedia.org/wiki/HKDF\n[AES-GCM]: https://en.wikipedia.org/wiki/Galois/Counter_Mode\n[STREAM]: https://web.cs.ucdavis.edu/~rogaway/papers/oae.pdf\n[Protocol Buffers]: https://developers.google.com/protocol-buffers/\n[CryptoURI]: https://github.com/cryptouri/cryptouri.rs/blob/develop/README.md\n[Merkle tree]: https://en.wikipedia.org/wiki/Merkle_tree\n[YubiHSM2]: https://developers.yubico.com/YubiHSM2/\n[cc]: https://contributor-covenant.org\n[CODE_OF_CONDUCT.md]: https://github.com/iqlusioninc/sear/blob/develop/CODE_OF_CONDUCT.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiqlusioninc%2Fsear","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiqlusioninc%2Fsear","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiqlusioninc%2Fsear/lists"}