{"id":22974046,"url":"https://github.com/bolcom/cryptvault","last_synced_at":"2025-08-13T14:33:38.245Z","repository":{"id":57717930,"uuid":"371383357","full_name":"bolcom/cryptvault","owner":"bolcom","description":"Generic, versioned crypto implementation","archived":false,"fork":false,"pushed_at":"2024-09-09T14:34:50.000Z","size":50,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-09-09T17:37:33.759Z","etag":null,"topics":["encryption","java"],"latest_commit_sha":null,"homepage":"","language":"Java","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/bolcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-27T13:29:07.000Z","updated_at":"2024-09-09T14:34:44.000Z","dependencies_parsed_at":"2024-03-14T11:26:43.876Z","dependency_job_id":"7ac224c3-ea0d-4e8d-a772-ac2285b18b3a","html_url":"https://github.com/bolcom/cryptvault","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolcom%2Fcryptvault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolcom%2Fcryptvault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolcom%2Fcryptvault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolcom%2Fcryptvault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bolcom","download_url":"https://codeload.github.com/bolcom/cryptvault/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229767228,"owners_count":18121043,"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":["encryption","java"],"created_at":"2024-12-14T23:59:57.294Z","updated_at":"2024-12-14T23:59:57.862Z","avatar_url":"https://github.com/bolcom.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Maven Central](https://img.shields.io/maven-central/v/com.bol/cryptvault.svg)](http://search.maven.org/#search%7Cga%7C1%7Ccom.bol)\n[![Build](https://github.com/bolcom/cryptvault/actions/workflows/maven.yml/badge.svg)](https://github.com/bolcom/cryptvault/actions)\n\n# Cryptvault: versioned, secure, generic encryption/decryption in Java\n\n\u003e When in doubt, encrypt. When not in doubt, be in doubt.\n\n## Features\n\n- key versioning (to help migrating to new key without need to convert data)\n- uses 256-bit AES by default\n- supports any encryption available in Java (via Java Cryptography Architecture\n  or JCA)\n- simple\n- no dependencies\n\n## Usage\n\nAdd dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.bol\u003c/groupId\u003e\n    \u003cartifactId\u003ecryptvault\u003c/artifactId\u003e\n    \u003cversion\u003e3-2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nAnd add the following to your `application.yml`:\n\n```yaml\ncryptvault:\n  keys:\n    - version: 1\n      key: hqHKBLV83LpCqzKpf8OvutbCs+O5wX5BPu3btWpEvXA=\n```\n\nAnd you're done!\n\nExample usage:\n\n```java\n@Autowired CryptVault cryptVault;\n\n// encrypt\nbyte[] encrypted = cryptVault.encrypt(\"rock\".getBytes());\n\n// decrypt\nbyte[] decrypted = cryptVault.decrypt(encrypted);\n\nnew String(decrypted).equals(\"rock\");   // true \n```\n\n## Keys\n\nThis library uses the encryption keys specified in the configuration directly.\nNotably, it does not use any key-derivation. That means that you are responsible\nfor providing a key from a high-entropy source.\n\nThe length of the key depends on the algorithm specified. When using AES-256,\nyou need to provide a key that is 256 bits/32 bytes long. (For comparison, the\nweak DES uses 64-bit keys.)\n\nTo generate a key suitable for AES-256 bit, you can use the following command:\n\n```console\n$ dd if=/dev/urandom bs=1 count=32 | base64\n```\n\n## Rotating keys\n\nIt is advisable to rotate your keys every now and then. To do so, define a new\nkey version in `application.yml`:\n\n```yaml\ncryptvault:\n  keys:\n    - version: 1\n      key: hqHKBLV83LpCqzKpf8OvutbCs+O5wX5BPu3btWpEvXA=\n    - version: 2\n      key: ge2L+MA9jLA8UiUJ4z5fUoK+Lgj2yddlL6EzYIBqb1Q=\n```  \n\nCryptVault automatically uses the highest versioned key for encryption by\ndefault, but supports decryption using any of the keys. This allows you to\ndeploy a new key, and either let old data slowly get phased out, or run a\nnightly load+save batch job to force key migration. Once all old keys are phased\nout, you may remove the old key from the configuration.\n\n## Specify default key version\n\nYou can use\n\n```yaml\ncryptvault:\n  default-key: 1\n```\n\nto override which version of the defined keys is considered default.\n\n## Specify encryption algorithm\n\nInstead of using the default AES-256 in CBC mode, you can specify the algorithm,\nmode of operation and padding scheme directly in the configuration:\n\n```yaml\ncryptvault:\n  keys:\n    version: 1\n    key: Ifw/+pLuWBjn7a1mjuToQ8hpIh8DV0WLf9b4z7iinGs=\n    transformation: AES/GCM/NoPadding\n```\n\nYou can use all the algorithms specified by JCA. Other valid transformations\nare, for example, \"DES/CTR/NoPadding\" and \"ChaCha20-Poly1305\". For a\ncomprehensive list, see [Java Security Standard Algorithm Names][Java Security\nStandard Algorithm Names]. \n\nThe YAML key is called \"transformation\" because it signifies more than just an\nalgorithm, but rather a set of operations performed on an input to produce some\noutput. Naming it this way is consistent with JCA parlance.\n\n## Format of the encrypted blob\n\nThe encrypted blobs look like (numbers are bits):\n\n```\n0         8         16        24\n+---------+---------+---------+--------------------+--------------------+\n|proto    |key      |param    |params              |ciphertext          |\n|version  |version  |length   |         ...        |            ...     |\n|8        |8        |8        |[0,255]             |[16,inf)            |\n+---------+---------+---------+--------------------+--------------------+\n```\n\n* `proto version` is the protocol version of this blob. Having a version allows\n  making improvements to this blob over time without having to decrypt all the\n  old encryptions and encrypt it under a new (versionless) version.\n* `key version` is the user-controlled version of the key that was used to\n  encrypt the data in this blob.\n* `param length` is the length of next field, the algorithm parameters \n* `params` are the algorithms parameters that that need to be known\n  in order to decrypt the blob successfully. For example, when using\n  AES/CBC/PKCS5Padding, this will (among some overhead) contain the 16-byte IV.\n  See `java.security.AlgorithmParameters#getEncoded` for more information.\n* `ciphertext` contains the output of applying the specified transformation\n  under the specified key to the input.\n\n## Expected size of encrypted data\n\nDepending on the cipher, whether an IV or tag are used and the padding scheme\nyou must expect some overhead for encryption. The default cipher, AES-256-CBC\nwith PKCS #5 padding, requires an extra [22, 37] bytes: proto version (1) + key\nversion (1) + param length (1) + algorithm parameters (18) + padding (best case:\n1, worst case: 16).\n\n## Migrating from version 1 to version 2\n\n### TL;DR: \n\n1. Add `legacy: true` to keys that were in use under version 1.\n2. Create a new key version that will be used for new encryptions.\n\n```yaml\ncryptvault:\n  keys:\n    # the legacy key version (can only decrypt!)\n    - version: 1\n      key: yaF4Gi13Gp+gF5Tm+jMkYbQKMO3c6KYZbQmMqXQyid0=\n      legacy: true\n    # the new version (can encrypt/decrypt as usual)\n    - version: 2\n      key: CqeKXVZuDbeMk0/h1zZrBG0Mul4qMnqShaGjkxWrlQ0=\n```\n\n### More detail\n\nVersion 2 introduced a new format of the binary blob. This provides certain\nbenefits (see under [Format of the encrypted blob,\nabove](#format-of-the-encrypted-blob)). However, the old encrypted blobs have\nbecome incompatible as a result of this breaking change. You can still decrypt\nthe blobs, however. Encrypting with these legacy key versions is not supported,\nhowever. \n\nTo migrate:\n\n1. Add `legacy: true` to the legacy key version(s) in the config. \n2. Create a new key version that will be used for new encryptions.\n\nOld encrypted blobs will not be updated automatically since this library does\nnot handle persistence. There is little harm in keeping them around as they\nare still secure. However, should you wish to upgrade the stored blobs, decrypt\nthem and then overwrite them with a fresh encrypted version under the new key\nversion.\n\n[Java Security Standard Algorithm Names]:\n\u003chttps://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolcom%2Fcryptvault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbolcom%2Fcryptvault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolcom%2Fcryptvault/lists"}