All Projects → capitalone → Fpe

capitalone / Fpe

Licence: apache-2.0
A format-preserving encryption implementation in Go

Programming Languages

go
31211 projects - #10 most used programming language
golang
3204 projects

Projects that are alternatives of or similar to Fpe

Encpipe
The dum^H^H^Hsimplest encryption tool in the world.
Stars: ✭ 135 (-15.62%)
Mutual labels:  encryption
Mega.py
Python library for the https://mega.nz/ API.
Stars: ✭ 145 (-9.37%)
Mutual labels:  encryption
Emberclear
Encrypted Chat. No History. No Logs.
Stars: ✭ 157 (-1.87%)
Mutual labels:  encryption
Encryptedrmd
🔑 Password protected markdown html reports in R using libsodium
Stars: ✭ 136 (-15%)
Mutual labels:  encryption
Go Jose
An implementation of JOSE standards (JWE, JWS, JWT) in Go
Stars: ✭ 1,849 (+1055.63%)
Mutual labels:  encryption
Jose2go
Golang (GO) implementation of Javascript Object Signing and Encryption specification
Stars: ✭ 150 (-6.25%)
Mutual labels:  encryption
Seal Python
Microsoft SEAL 3.X For Python
Stars: ✭ 134 (-16.25%)
Mutual labels:  encryption
Fsociety
Script for encrypting a GNU/Linux filesystem and then destroying the keys
Stars: ✭ 159 (-0.62%)
Mutual labels:  encryption
Gocryptfs
Encrypted overlay filesystem written in Go
Stars: ✭ 2,088 (+1205%)
Mutual labels:  encryption
End to end encryption
🔐 Server API to support End-to-End Encryption
Stars: ✭ 155 (-3.12%)
Mutual labels:  encryption
Cli
🧰 A zero trust swiss army knife for working with X509, OAuth, JWT, OATH OTP, etc.
Stars: ✭ 2,151 (+1244.38%)
Mutual labels:  encryption
Aegis
A free, secure and open source app for Android to manage your 2-step verification tokens.
Stars: ✭ 2,692 (+1582.5%)
Mutual labels:  encryption
Discordcrypt
End-To-End File & Message Encryption For Discord
Stars: ✭ 150 (-6.25%)
Mutual labels:  encryption
Padding Oracle Attacker
🔓 CLI tool and library to execute padding oracle attacks easily, with support for concurrent network requests and an elegant UI.
Stars: ✭ 136 (-15%)
Mutual labels:  encryption
Cyberchef
The Cyber Swiss Army Knife - a web app for encryption, encoding, compression and data analysis
Stars: ✭ 13,674 (+8446.25%)
Mutual labels:  encryption
Tessera
Tessera - Enterprise Implementation of Quorum's transaction manager
Stars: ✭ 135 (-15.62%)
Mutual labels:  encryption
Masuit.tools
ldqk.xyz/55
Stars: ✭ 2,539 (+1486.88%)
Mutual labels:  encryption
Crypto Notepad
🔑 Simple notepad for Windows with encryption features
Stars: ✭ 160 (+0%)
Mutual labels:  encryption
Shhh
Share sensitive info without leaving a trace in your chat logs or email accounts.
Stars: ✭ 159 (-0.62%)
Mutual labels:  encryption
Mixplaintext
可对 Xcode 项目工程所有的 objective-c 文件内包含的明文进行加密混淆,提高逆向分析难度。
Stars: ✭ 152 (-5%)
Mutual labels:  encryption

Godoc Build Status Go Report Card Sourcegraph License

fpe - Format Preserving Encryption Implementation in Go

An implementation of the NIST approved Format Preserving Encryption (FPE) FF1 and FF3 algorithms in Go.

NIST Recommendation SP 800-38G

This follows the FF1 and FF3 schemes for Format Preserving Encryption outlined in the NIST Recommendation, released in March 2016. For FF1, it builds on and formalizes (differing from but remaining mathematically equivalent to) the FFX-A10 scheme by Bellare, Rogaway and Spies as defined here and here. For FF3, it formalizes the BPS scheme.

A note about FF3: There was some recent cryptanalysis about the FF3 algorithm that is important to review. NIST has concluded that FF3 is no longer suitable as a general-purpose FPE method.

A note about FF2: FF2 was originally NOT recommended by NIST, but it is under review again as DFF. You can read about it here.

Testing

There are some official test vectors for both FF1 and FF3 provided by NIST, which are used for testing in this package.

To run unit tests on this implementation with all test vectors from the NIST link above, run the built-in tests:

  1. go test -v github.com/capitalone/fpe/ff1
  2. go test -v github.com/capitalone/fpe/ff3

To run only benchmarks:

  1. go test -v -bench=. -run=NONE github.com/capitalone/fpe/ff1
  2. go test -v -bench=. -run=NONE github.com/capitalone/fpe/ff3

Example Usage

The example code below can help you get started. Copy it into a file called main.go, and run it with go run main.go.

package main

import (
	"encoding/hex"
	"fmt"
	"github.com/capitalone/fpe/ff1"
)

// panic(err) is just used for example purposes.
func main() {
	// Key and tweak should be byte arrays. Put your key and tweak here.
	// To make it easier for demo purposes, decode from a hex string here.
	key, err := hex.DecodeString("EF4359D8D580AA4F7F036D6F04FC6A94")
	if err != nil {
		panic(err)
	}
	tweak, err := hex.DecodeString("D8E7920AFA330A73")
	if err != nil {
		panic(err)
	}

	// Create a new FF1 cipher "object"
	// 10 is the radix/base, and 8 is the tweak length.
	FF1, err := ff1.NewCipher(10, 8, key, tweak)
	if err != nil {
		panic(err)
	}

	original := "123456789"

	// Call the encryption function on an example SSN
	ciphertext, err := FF1.Encrypt(original)
	if err != nil {
		panic(err)
	}

	plaintext, err := FF1.Decrypt(ciphertext)
	if err != nil {
		panic(err)
	}

	fmt.Println("Original:", original)
	fmt.Println("Ciphertext:", ciphertext)
	fmt.Println("Plaintext:", plaintext)
}

Usage notes

There is a FIPS Document that containsRequirements for Vendor Affirmation of SP 800-38G on page 155.

There are some patent related details for FF1 and FF3 as Voltage Security (which was acquired by what is now HP Enterprise) originally developed FFX, which became FF1. They provided NIST with a Letter of Assurance on the matter.

It can be used as part of sensitive data tokenization, especially in regards to PCI and cryptographically reversible tokens. This implementation does not provide any gaurantees regarding PCI DSS or other validation.

It's important to note that, as with any cryptographic package, managing and protecting the key appropriately to your situation is crucial. This package does not provide any guarantees regarding the key in memory.

Implementation Notes

Overall, this was originally written with the following goals:

  • Be as idiomatic as possible from a Go language, package, and interface perspective
  • Follow the algorithm as outlined in the NIST recommendation as closely as possible
  • Attempt to be a reference implementation since one does not exist yet

As such, it was not necessarily written from a performance perspective. While some performance optimizations have been added in v1.1, the nature of format preserving encryption is to operate on strings, which are inherently slow as compared to traditional encryption algorithms which operate on bytes.

Further, while the test vectors all pass, the lack of a reference implementation makes it difficult to test ALL input combinations for correctness.

As of Go 1.9, the standard library's math/big package did not support radices/bases higher than 36. As such, the initial release only supports base 36 strings, which can contain numeric digits 0-9 or lowercase alphabetic characters a-z.

Base 62 support should be available come Go 1.10. See this commit and this tracking issue.

The only cryptographic primitive used for FF1 and FF3 is AES. This package uses Go's standard library's crypto/aes package for this. Note that while it technically uses AES-CBC mode, in practice it almost always is meant to act on a single-block with an IV of 0, which is effectively ECB mode. AES is also the only block cipher function that works at the moment, and the only allowed block cipher to be used for FF1/FF3, as per the spec.

In the spec, it says that the radix and minimum length (minLen) of the message should be such that radix^minLen >= 100. In Appendix A, it mentions this is to prevent a generic MITM against the Feistel structure, but for better security, radix^minLen >= 1,000,000. In ff1.go and ff3.go there is a const called FEISTEL_MIN that can be changed to a sufficient value (like 1,000,000), but by default, it only follows the bare spec.

Regarding how the "tweak" is used as input: I interpreted the spec as setting the tweak in the initial NewCipher call, instead of in each Encrypt and Decrypt call. In one sense, it is similar to passing an IV or nonce once when creating an encryptor object. It's likely that this can be modified to do it in each Encrypt/Decrypt call, if that is more applicable to what you are building.

Existing Implementations

Based on searching GitHub and the Internet, there are no known reference implementations for either algorithm.

An existing Go implementation based on the earlier FFX spec was already created, but the implementation differs slightly from the final NIST recommendation. Further, that implementation doesn't work for higher radices or long strings as it doesn't use math/big (big integers).

There is a Java implementation that was also used for testing and comparison while developing this, as it was the only other fully working implementation available.

Contributors

We welcome your interest in Capital One’s Open Source Projects (the “Project”). Any Contributor to the project must accept and sign a CLA indicating agreement to the license terms. Except for the license granted in this CLA to Capital One and to recipients of software distributed by Capital One, you reserve all right, title, and interest in and to your contributions; this CLA does not impact your rights to use your own contributions for any other purpose.

Link to Individual CLA

Link to Corporate CLA

This project adheres to the Open Source Code of Conduct. By participating, you are expected to honor this code.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].