{"id":22845489,"url":"https://github.com/idealista/format-preserving-encryption-java","last_synced_at":"2025-08-21T20:31:48.364Z","repository":{"id":51207617,"uuid":"105005000","full_name":"idealista/format-preserving-encryption-java","owner":"idealista","description":"Format-Preserving Encryption Implementation in Java","archived":false,"fork":false,"pushed_at":"2023-05-29T09:48:34.000Z","size":177,"stargazers_count":95,"open_issues_count":8,"forks_count":40,"subscribers_count":38,"default_branch":"master","last_synced_at":"2024-12-13T03:17:26.699Z","etag":null,"topics":["cryptography","encryption","ff1","format-preserving-encryption","fpe","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/idealista.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-27T10:29:02.000Z","updated_at":"2024-10-23T08:58:51.000Z","dependencies_parsed_at":"2022-09-08T04:10:26.864Z","dependency_job_id":null,"html_url":"https://github.com/idealista/format-preserving-encryption-java","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/idealista%2Fformat-preserving-encryption-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idealista%2Fformat-preserving-encryption-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idealista%2Fformat-preserving-encryption-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idealista%2Fformat-preserving-encryption-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/idealista","download_url":"https://codeload.github.com/idealista/format-preserving-encryption-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230532443,"owners_count":18240792,"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":["cryptography","encryption","ff1","format-preserving-encryption","fpe","java"],"created_at":"2024-12-13T03:17:26.149Z","updated_at":"2024-12-20T04:06:54.834Z","avatar_url":"https://github.com/idealista.png","language":"Java","readme":"![Logo](logo.gif)\r\n[![Build Status](https://travis-ci.org/idealista/format-preserving-encryption-java.svg?branch=master)](https://travis-ci.org/idealista/format-preserving-encryption-java)\r\n# fpe - Format Preserving Encryption Implementation in Java\r\n\r\nFormat-preserving encryption (FPE) is designed for data that is not necessarily binary. In particular, given any finite set of symbols, like the decimal numerals, a method for FPE transforms data that is formatted as a sequence of the symbols in such a way that the encrypted form of the data has the same format, including the length, as the original data. Thus, an FPE-encrypted SSN would be a sequence of nine decimal digits.\r\n\r\nAn implementation of the NIST approved Format Preserving Encryption (FPE) in Java.\r\n\r\n[NIST Recommendation SP 800-38G](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38G.pdf)\r\n\r\n\r\n## Installation\r\n\r\nCheck [requirements](#requirements) section before installation\r\n\r\n\r\nYou can pull it from the central Maven repositories:\r\n\r\n```xml\r\n\u003cdependency\u003e\r\n  \u003cgroupId\u003ecom.idealista\u003c/groupId\u003e\r\n  \u003cartifactId\u003eformat-preserving-encryption\u003c/artifactId\u003e\r\n  \u003cversion\u003e1.0.0\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n## Features\r\n\r\n* Out of the box working algorithm with an easy API\r\n* Custom Domain (any subset of character could be used)\r\n* Custom Pseudo Random Function (_cipher algorithm_)\r\n\r\n## Example Usage\r\n\r\n### Input data\r\n\r\nDuring Format Preserving Encryption object creation, input data shall meet the following requirements:\r\n\r\n- radix ∈ [ 2 .. 2\u003csup\u003e16\u003c/sup\u003e ]\r\n- radix\u003csup\u003eminlen\u003c/sup \u003e= 100\r\n- 2 \u003c= minlen \u003c maxlen \u003c= 2^32\r\n- key is an AES Key, must be 16, 24 or 32 bytes length\r\n\r\nIf default tweak option is used:\r\n\r\n- tweak length should be lower that tweakMaxLength\r\n\r\n### Code\r\n\r\n```java\r\n// with default values\r\nFormatPreservingEncryption formatPreservingEncryption = FormatPreservingEncryptionBuilder\r\n        .ff1Implementation()\r\n        .withDefaultDomain()\r\n        .withDefaultPseudoRandomFunction(anyKey)\r\n        .withDefaultLengthRange()\r\n        .build();\r\n    \r\n//with custom inputs\r\nFormatPreservingEncryption formatPreservingEncryption = FormatPreservingEncryptionBuilder\r\n        .ff1Implementation()\r\n        .withDomain(new BasicAlphabetDomain())\r\n        .withPseudoRandomFunction(new DefaultPseudoRandomFunction(anyKey))\r\n        .withLengthRange(new LengthRange(2, 20))\r\n        .build();\r\n\r\n//usage\r\nString cipherText = formatPreservingEncryption.encrypt(aText, aTweak);\r\nString plainText = formatPreservingEncryption.decrypt(aText, aTweak);\r\n```\r\n\r\n### Custom Inputs\r\n\r\n#### Domain\r\n\r\n[GenericDomain](src/main/java/com/idealista/fpe/config/GenericDomain.java) represents the easiest implementation of a domain.  A valid domain should be able to transform text input to numeral string and numeral string to text.\r\n\r\nThe _domain_ of an instance has two elements:\r\n\r\n- *Alphabet*: A subset of characters that are valid to create a text input for an instance.\r\n- *Transformers*: Functions (Class) that are able to transform text to numeral string or numeral string to text.\r\n\r\nThe [default domain](src/main/java/com/idealista/fpe/config/basic/BasicAlphabet.java) includes the lower case letters of the English alphabet\r\n\r\n#### Pseudo Random Function (PRF)\r\n\r\nA given designated cipher function. By default AES-CBC with 128, 192 or 256 based on the input key is used.\r\n\r\n#### Input text length\r\n\r\nThe minimum length of a text for a given domain is defined using the rules at the start of this section. Although the maximum length is not defined, you must be aware of performance issues when using a very large text.  \r\n\r\n## Requirements\r\n\r\nThe library has been tested with _Apache Maven 3.3.3_ and _JDK 1.6-1.7_. Newer versions of _Apache Maven/JDK_ should work but could also present issues.\r\n\r\nUsage of Java Cryptography Extension (JCE) requires to download an install Policy Files for target java distribution: [1.6](http://www.oracle.com/technetwork/es/java/javase/downloads/jce-6-download-429243.html), [1.7](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html), [1.8](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html)\r\n\r\n## Design choices\r\n\r\n- FF1Algorithm is a _pure_ implementation without checking, input data is checked during object creation or before invoke the algorithm. Be awere of this when using the library and use the `FormatPreservingEncryptionBuilder` class.\r\n- Every input data error throws an `IllegalArgumentException`\r\n\r\n## TODO\r\n\r\n* Implement FF3\r\n\r\n## License \r\n\r\nRead [LICENSE.txt](LICENSE.txt) attached to the project\r\n\r\n## Contribution\r\n\r\nRead [CONTRIBUTION.md](.github/CONTRIBUTING.md)\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidealista%2Fformat-preserving-encryption-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidealista%2Fformat-preserving-encryption-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidealista%2Fformat-preserving-encryption-java/lists"}