crypto functions

A set of crypto-related functions to be able to perform hashing and (simple!) encryption operations with gomplate.

Note: These functions are mostly wrappers of existing functions in the Go standard library. The authors of gomplate are not cryptographic experts, however, and so can not guarantee correctness of implementation. It is recommended to have your resident security experts inspect gomplate’s code before using gomplate for critical security infrastructure!

crypto.Bcrypt

Uses the bcrypt password hashing algorithm to generate the hash of a given string. Wraps the golang.org/x/crypto/brypt package.

Added in gomplate v2.6.0

Usage

crypto.Bcrypt [cost] input
input | crypto.Bcrypt [cost]

Arguments

name description
cost (optional) the cost, as a number from 4 to 31 - defaults to 10
input (required) the input to hash, usually a password

Examples

$ gomplate -i '{{ "foo" | crypto.Bcrypt }}'
$2a$10$jO8nKZ1etGkKK7I3.vPti.fYDAiBqwazQZLUhaFoMN7MaLhTP0SLy

$ gomplate -i '{{ crypto.Bcrypt 4 "foo" }}
$2a$04$zjba3N38sjyYsw0Y7IRCme1H4gD0MJxH8Ixai0/sgsrf7s1MFUK1C

crypto.YescryptMCF(unreleased) (experimental)

Unreleased: This function is in development, and not yet available in released builds of gomplate. Experimental: This function is experimental and may be enabled with the --experimental flag.

Uses the Yescrypt password hashing algorithm to generate the hash of a given string. Wraps the github.com/openwall/yescrypt-go package. Yescrypt is a modern, memory-hard key derivation function designed as an extension of scrypt, providing resistance to GPU/ASIC attacks.

Usage

crypto.YescryptMCF [cost] [blockSize] [salt] input
input | crypto.YescryptMCF [cost] [blockSize] [salt]

Arguments

name description
cost (optional) the cost parameter (log₂ of the iteration count) - integer from 10 to 18 - defaults to 14
blockSize (optional) the block size parameter (r) - integer from 1 to 32 - defaults to 8
salt (optional) the salt string used in hashing - defaults to a random alphanumeric string of length 16
input (required) the input to hash, usually a password

Examples

$ gomplate -i '{{ "foo" | crypto.YescryptMCF }}'
$y$jB5$YZZJoNING3pMhVIKFhIJJ/$n.9CRZ17bqvvDKyrAWqvghg7k5rq9M9F4rpWntnpeV0

$ gomplate -i '{{ crypto.YescryptMCF 10 1 "mysalt" "foo" }}'
$y$j7.$hZrQVl4R$y2MSQDqiVCS0Q7PsGv7f8b4O7s/O0Kmgw.2hvgxbqL1

$ gomplate -i '{{ "pass" | crypto.YescryptMCF 16 4 }}'
$y$jD1$g/5AI/JEAR1KV7bFkJqIu/$zRk92xeixtHGp8Mq6weG2tPlsQPDZ6ybweLJd6jv1w6

$ gomplate -i '{{ crypto.YescryptMCF 16 4 "pass" }}'
$y$jD1$F7IQJtaHnk4Bo3HSYNIAi/$ttB6RTXx2SnSJIn1xsUPlaQmH056JdgejJlZmHyCtq1

crypto.Yescrypt(unreleased) (experimental)

Unreleased: This function is in development, and not yet available in released builds of gomplate. Experimental: This function is experimental and may be enabled with the --experimental flag.

Uses the Yescrypt password hashing algorithm to generate the hash of a given string. Wraps the github.com/openwall/yescrypt-go package. Yescrypt is a modern, memory-hard key derivation function designed as an extension of scrypt, providing resistance to GPU/ASIC attacks.

This function outputs the binary result as a hexadecimal string.

Usage

crypto.Yescrypt input salt cost blockSize keyLen
keyLen | crypto.Yescrypt input salt cost blockSize

Arguments

name description
input (required) the input to hash, usually a password
salt (required) the salt string used in hashing
cost (required) the cost parameter, integer > 1 and a power of 2
blockSize (required) the block size parameter (r) - integer > 0
keyLen (required) desired length of derived key

Examples

$ gomplate -i '{{ crypto.Yescrypt "foo" "mysalt" 32768 8 32 }}'
8d967e29526ea6b57b914e7df477cd2c2b6804816ba68d47284d1f75aa2a617e

crypto.AESDecrypt

Alias: crypto.DecryptAES (deprecated)

Decrypts the given input using the given key. By default, uses AES-256-CBC, but supports 128- and 192-bit keys as well.

This function prints the output as a string. Note that this may result in unreadable text if the decrypted payload is binary. See crypto.AESDecryptBytes for another method.

This function is suitable for decrypting data that was encrypted by Helm’s encryptAES function, when the input is base64-decoded, and when using 256-bit keys.

Added in gomplate v3.11.0

Usage

crypto.AESDecrypt key [keyBits] input
input | crypto.AESDecrypt key [keyBits]

Arguments

name description
key (required) the key to use for decryption
keyBits (optional) the key length to use - defaults to 256
input (required) the input to decrypt

Examples

$ gomplate -i '{{ base64.Decode "Gp2WG/fKOUsVlhcpr3oqgR+fRUNBcO1eZJ9CW+gDI18=" | crypto.AESDecrypt "swordfish" 128 }}'
hello world

crypto.AESDecryptBytes

Alias: crypto.DecryptAESBytes (deprecated)

Decrypts the given input using the given key. By default, uses AES-256-CBC, but supports 128- and 192-bit keys as well.

This function outputs the raw byte array, which may be sent as input to other functions.

This function is suitable for decrypting data that was encrypted by Helm’s encryptAES function, when the input is base64-decoded, and when using 256-bit keys.

Added in gomplate v3.11.0

Usage

crypto.AESDecryptBytes key [keyBits] input
input | crypto.AESDecryptBytes key [keyBits]

Arguments

name description
key (required) the key to use for decryption
keyBits (optional) the key length to use - defaults to 256
input (required) the input to decrypt

Examples

$ gomplate -i '{{ base64.Decode "Gp2WG/fKOUsVlhcpr3oqgR+fRUNBcO1eZJ9CW+gDI18=" | crypto.AESDecryptBytes "swordfish" 128 }}'
hello world

crypto.AESEncrypt

Alias: crypto.EncryptAES (deprecated)

Encrypts the given input using the given key. By default, uses AES-256-CBC, but supports 128- and 192-bit keys as well.

This function is suitable for encrypting data that will be decrypted by Helm’s decryptAES function, when the output is base64-encoded, and when using 256-bit keys.

Added in gomplate v3.11.0

Usage

crypto.AESEncrypt key [keyBits] input
input | crypto.AESEncrypt key [keyBits]

Arguments

name description
key (required) the key to use for encryption
keyBits (optional) the key length to use - defaults to 256
input (required) the input to encrypt

Examples

$ gomplate -i '{{ "hello world" | crypto.AESEncrypt "swordfish" 128 | base64.Encode }}'
MnRutHovsh/9JN3YrJtBVjZtI6xXZh33bCQS2iZ4SDI=

crypto.DerivePublicKey

Derive a public key from any supported private key type (RSA, ECDSA, or Ed25519) and output in PKIX ASN.1 DER form. The key type is auto-detected from the PEM block type.

This is a unified function that can replace the algorithm-specific crypto.RSADerivePublicKey, crypto.ECDSADerivePublicKey, and crypto.Ed25519DerivePublicKey functions.

Added in gomplate v5.1.0

Usage

crypto.DerivePublicKey key
key | crypto.DerivePublicKey

Arguments

name description
key (required) the private key to derive a public key from

Examples

$ gomplate -i '{{ crypto.RSAGenerateKey | crypto.DerivePublicKey }}'
-----BEGIN PUBLIC KEY-----
...

$ gomplate -i '{{ crypto.ECDSAGenerateKey | crypto.DerivePublicKey }}'
-----BEGIN PUBLIC KEY-----
...

$ gomplate -i '{{ crypto.Ed25519GenerateKey | crypto.DerivePublicKey }}'
-----BEGIN PUBLIC KEY-----
...

crypto.ECDSAGenerateKey

Generate a new Elliptic Curve Private Key and output in PEM-encoded PKCS#1 ASN.1 DER form.

Go’s standard NIST P-224, P-256, P-384, and P-521 elliptic curves are all supported.

Default curve is P-256 and can be overridden with the optional curve parameter.

Added in gomplate v3.11.0

Usage

crypto.ECDSAGenerateKey [curve]
curve | crypto.ECDSAGenerateKey

Arguments

name description
curve (optional) One of Go’s standard NIST curves, P-224, P-256, P-384, or P-521 -
defaults to P-256.

Examples

$ gomplate -i '{{ crypto.ECDSAGenerateKey }}'
-----BEGIN EC PRIVATE KEY-----
...

crypto.ECDSADerivePublicKey

Derive a public key from an elliptic curve private key and output in PKIX ASN.1 DER form.

Added in gomplate v3.11.0

Usage

crypto.ECDSADerivePublicKey key
key | crypto.ECDSADerivePublicKey

Arguments

name description
key (required) the private key to derive a public key from

Examples

$ gomplate -i '{{ crypto.ECDSAGenerateKey | crypto.ECDSADerivePublicKey }}'
-----BEGIN PUBLIC KEY-----
...

$ gomplate -d key=priv.pem -i '{{ crypto.ECDSADerivePublicKey (include "key") }}'
-----BEGIN PUBLIC KEY-----
MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBZvTS1wcCJSsGYQUVoSVctynkuhke
kikB38iNwx/80jzdm+Z8OmRGlwH6OE9NX1MyxjvYMimhcj6zkaOKh1/HhMABrfuY
+hIz6+EUt/Db51awO7iCuRly5L4TZ+CnMAsIbtUOqsqwSQDtv0AclAuogmCst75o
aztsmrD79OXXnhUlURI=
-----END PUBLIC KEY-----

crypto.Ed25519GenerateKey

Generate a new Ed25519 Private Key and output in PEM-encoded PKCS#8 ASN.1 DER form.

Added in gomplate v4.0.0

Usage

crypto.Ed25519GenerateKey

Examples

$ gomplate -i '{{ crypto.Ed25519GenerateKey }}'
-----BEGIN PRIVATE KEY-----
...

crypto.Ed25519GenerateKeyFromSeed

Generate a new Ed25519 Private Key from a random seed and output in PEM-encoded PKCS#8 ASN.1 DER form.

Added in gomplate v4.0.0

Usage

crypto.Ed25519GenerateKeyFromSeed encoding seed
seed | crypto.Ed25519GenerateKeyFromSeed encoding

Arguments

name description
encoding (required) the encoding that the seed is in (hex or base64)
seed (required) the random seed encoded in either base64 or hex

Examples

$ gomplate -i '{{ crypto.Ed25519GenerateKeyFromSeed "base64" "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA=" }}'
-----BEGIN PRIVATE KEY-----
...

crypto.Ed25519DerivePublicKey

Derive a public key from an Ed25519 private key and output in PKIX ASN.1 DER form.

Added in gomplate v4.0.0

Usage

crypto.Ed25519DerivePublicKey key
key | crypto.Ed25519DerivePublicKey

Arguments

name description
key (required) the private key to derive a public key from

Examples

$ gomplate -i '{{ crypto.Ed25519GenerateKey | crypto.Ed25519DerivePublicKey }}'
-----BEGIN PUBLIC KEY-----
...

$ gomplate -d key=priv.pem -i '{{ crypto.Ed25519DerivePublicKey (include "key") }}'
-----BEGIN PUBLIC KEY-----
...PK

crypto.PBKDF2

Run the Password-Based Key Derivation Function #2 as defined in RFC 8018 (PKCS #5 v2.1).

This function outputs the binary result as a hexadecimal string.

Added in gomplate v2.3.0

Usage

crypto.PBKDF2 password salt iter keylen [hashfunc]

Arguments

name description
password (required) the password to use to derive the key
salt (required) the salt
iter (required) iteration count
keylen (required) desired length of derived key
hashfunc (optional) the hash function to use - must be one of the allowed functions (either in the SHA-1 or SHA-2 sets). Defaults to SHA-1

Examples

$ gomplate -i '{{ crypto.PBKDF2 "foo" "bar" 1024 8 }}'
32c4907c3c80792b

crypto.PBKDF2MCF(unreleased) (experimental)

Unreleased: This function is in development, and not yet available in released builds of gomplate. Experimental: This function is experimental and may be enabled with the --experimental flag.

Run the Password-Based Key Derivation Function #2 as defined in RFC 8018 (PKCS #5 v2.1).

This function outputs a Modular Crypt Format (MCF) result string.

Usage

crypto.PBKDF2MCF password salt iter keylen [hashfunc]

Arguments

name description
password (required) the password to use to derive the key
salt (required) the salt
iter (required) iteration count
keylen (required) desired length of derived key
hashfunc (optional) the hash function to use - must be one of the allowed functions (either in the SHA-1 or SHA-2 sets). Defaults to SHA-1

Examples

$ gomplate -i '{{ crypto.PBKDF2MCF "foo" "bar" 1024 8 }}'
$pbkdf2-sha1$1024$YmFy$MsSQfDyAeSs

crypto.RSADecrypt

Decrypt an RSA-encrypted input and print the output as a string. Note that this may result in unreadable text if the decrypted payload is binary. See crypto.RSADecryptBytes for a safer method.

The private key must be a PEM-encoded RSA private key in PKCS#1, ASN.1 DER form, which typically begins with -----BEGIN RSA PRIVATE KEY-----.

The input text must be plain ciphertext, as a byte array, or safely convertible to a byte array. To decrypt base64-encoded input, you must first decode with the base64.DecodeBytes function.

Added in gomplate v3.8.0

Usage

crypto.RSADecrypt key input
input | crypto.RSADecrypt key

Arguments

name description
key (required) the private key to decrypt the input with
input (required) the encrypted input

Examples

$ gomplate -c pubKey=./testPubKey -c privKey=./testPrivKey \
  -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}}
  {{ crypto.RSADecrypt .privKey $enc }}'
hello

$ export ENCRYPTED="ScTcX1NZ6p/EeDIf6R7FKLcDFjvP98YgiBhyhPE4jtehajIyTKP1GL8C72qbAWrgdQ6A2cSVjoyo3viqf/PZxpcBDUUMDJuemTaJqUUjMWaDuPG37mQbmRtcvFTuUhw1qSbKyHorDOgTX5d4DvWV4otycGtBT6dXhnmmb5V72J/w3z68vtTJ21m9wREFD7LrYVHdFFtRZiIyMBAF0ngQ+hcujrxilnmgzPkEAg6E7Ccctn28Ie2c4CojrwRbNNxXNlIWCCkC/8Vq8qlDfZ70a+BsTmJDuScE6BZbTyteo9uGYrLn+bTIHNDj90AeLCKUTyWLUJ5Edi9LhlKVBoJUNQ=="
$ gomplate -c ciphertext=env:///ENCRYPTED -c privKey=./testPrivKey \
  -i '{{ base64.DecodeBytes .ciphertext | crypto.RSADecrypt .privKey }}'
hello

crypto.RSADecryptBytes

Decrypt an RSA-encrypted input and output the decrypted byte array.

The private key must be a PEM-encoded RSA private key in PKCS#1, ASN.1 DER form, which typically begins with -----BEGIN RSA PRIVATE KEY-----.

The input text must be plain ciphertext, as a byte array, or safely convertible to a byte array. To decrypt base64-encoded input, you must first decode with the base64.DecodeBytes function.

See crypto.RSADecrypt for a function that outputs a string.

Added in gomplate v3.8.0

Usage

crypto.RSADecryptBytes key input
input | crypto.RSADecryptBytes key

Arguments

name description
key (required) the private key to decrypt the input with
input (required) the encrypted input

Examples

$ gomplate -c pubKey=./testPubKey -c privKey=./testPrivKey \
  -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}}
  {{ crypto.RSADecryptBytes .privKey $enc }}'
[104 101 108 108 111]

$ gomplate -c pubKey=./testPubKey -c privKey=./testPrivKey \
  -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}}
  {{ crypto.RSADecryptBytes .privKey $enc | conv.ToString }}'
hello

crypto.RSAEncrypt

Encrypt the input with RSA and the padding scheme from PKCS#1 v1.5.

This function is suitable for encrypting data that will be decrypted by Terraform’s rsadecrypt function.

The key should be a PEM-encoded RSA public key in PKIX ASN.1 DER form, which typically begins with BEGIN PUBLIC KEY. RSA public keys in PKCS#1 ASN.1 DER form are also supported (beginning with RSA PUBLIC KEY).

The output will not be encoded, so consider base64-encoding it for display.

Note: Output encrypted with this function will not be deterministic, so encrypting the same input twice will not result in the same ciphertext.

Warning: Using this function may not be safe. See the warning on Go’s rsa.EncryptPKCS1v15 documentation.

Added in gomplate v3.8.0

Usage

crypto.RSAEncrypt key input
input | crypto.RSAEncrypt key

Arguments

name description
key (required) the public key to encrypt the input with
input (required) the encrypted input

Examples

$ gomplate -c pubKey=./testPubKey \
  -i '{{ "hello" | crypto.RSAEncrypt .pubKey | base64.Encode }}'
ScTcX1NZ6p/EeDIf6R7FKLcDFjvP98YgiBhyhPE4jtehajIyTKP1GL8C72qbAWrgdQ6A2cSVjoyo3viqf/PZxpcBDUUMDJuemTaJqUUjMWaDuPG37mQbmRtcvFTuUhw1qSbKyHorDOgTX5d4DvWV4otycGtBT6dXhnmmb5V72J/w3z68vtTJ21m9wREFD7LrYVHdFFtRZiIyMBAF0ngQ+hcujrxilnmgzPkEAg6E7Ccctn28Ie2c4CojrwRbNNxXNlIWCCkC/8Vq8qlDfZ70a+BsTmJDuScE6BZbTyteo9uGYrLn+bTIHNDj90AeLCKUTyWLUJ5Edi9LhlKVBoJUNQ==

$ gomplate -c pubKey=./testPubKey \
  -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}}
  Ciphertext in hex: {{ printf "%x" $enc }}'
71729b87cccabb248b9e0e5173f0b12c01d9d2a0565bad18aef9d332ce984bde06acb8bb69334a01446f7f6430077f269e6fbf2ccacd972fe5856dd4719252ebddf599948d937d96ea41540dad291b868f6c0cf647dffdb5acb22cd33557f9a1ddd0ee6c1ad2bbafc910ba8f817b66ea0569afc06e5c7858fd9dc2638861fe7c97391b2f190e4c682b4aa2c9b0050081efe18b10aa8c2b2b5f5b68a42dcc06c9da35b37fca9b1509fddc940eb99f516a2e0195405bcb3993f0fa31bc038d53d2e7231dff08cc39448105ed2d0ac52d375cb543ca8a399f807cc5d007e2c44c69876d189667eee66361a393c4916826af77479382838cd4e004b8baa05636805a

crypto.RSAGenerateKey

Generate a new RSA Private Key and output in PEM-encoded PKCS#1 ASN.1 DER form.

Default key length is 4096 bits, which should be safe enough for most uses, but can be overridden with the optional bits parameter.

In order to protect against CWE-326, keys shorter than 2048 bits may not be generated.

The output is a string, suitable for use with the other crypto.RSA* functions.

Added in gomplate v3.8.0

Usage

crypto.RSAGenerateKey [bits]
bits | crypto.RSAGenerateKey

Arguments

name description
bits (optional) Length in bits of the generated key. Must be at least 2048. Defaults to 4096

Examples

$ gomplate -i '{{ crypto.RSAGenerateKey }}'
-----BEGIN RSA PRIVATE KEY-----
...

$ gomplate -i '{{ $key := crypto.RSAGenerateKey 2048 -}}
  {{ $pub := crypto.RSADerivePublicKey $key -}}
  {{ $enc := "hello" | crypto.RSAEncrypt $pub -}}
  {{ crypto.RSADecrypt $key $enc }}'
hello

crypto.RSADerivePublicKey

Derive a public key from an RSA private key and output in PKIX ASN.1 DER form.

The output is a string, suitable for use with other crypto.RSA* functions.

Added in gomplate v3.8.0

Usage

crypto.RSADerivePublicKey key
key | crypto.RSADerivePublicKey

Arguments

name description
key (required) the private key to derive a public key from

Examples

$ gomplate -i '{{ crypto.RSAGenerateKey | crypto.RSADerivePublicKey }}'
-----BEGIN PUBLIC KEY-----
...

$ gomplate -c privKey=./privKey.pem \
  -i '{{ $pub := crypto.RSADerivePublicKey .privKey -}}
  {{ $enc := "hello" | crypto.RSAEncrypt $pub -}}
  {{ crypto.RSADecrypt .privKey $enc }}'
hello

crypto.SHA*

Compute a checksum with a SHA-1 or SHA-2 algorithm as defined in RFC 3174 (SHA-1) and FIPS 180-4 (SHA-2).

These functions output the binary result as a hexadecimal string.

Warning: SHA-1 is cryptographically broken and should not be used for secure applications.

Added in gomplate v2.3.0

Usage

crypto.SHA1 input
crypto.SHA224 input
crypto.SHA256 input
crypto.SHA384 input
crypto.SHA512 input
crypto.SHA512_224 input
crypto.SHA512_256 input

Arguments

name description
input (required) the data to hash - can be binary data or text

Examples

$ gomplate -i '{{ crypto.SHA1 "foo" }}'
f1d2d2f924e986ac86fdf7b36c94bcdf32beec15

$ gomplate -i '{{ crypto.SHA512 "bar" }}'
cc06808cbbee0510331aa97974132e8dc296aeb795be229d064bae784b0a87a5cf4281d82e8c99271b75db2148f08a026c1a60ed9cabdb8cac6d24242dac4063

crypto.SHA*Bytes

Compute a checksum with a SHA-1 or SHA-2 algorithm as defined in RFC 3174 (SHA-1) and FIPS 180-4 (SHA-2).

These functions output the raw binary result, suitable for piping to other functions.

Warning: SHA-1 is cryptographically broken and should not be used for secure applications.

Added in gomplate v3.11.0

Usage

crypto.SHA1Bytes input
crypto.SHA224Bytes input
crypto.SHA256Bytes input
crypto.SHA384Bytes input
crypto.SHA512Bytes input
crypto.SHA512_224Bytes input
crypto.SHA512_256Bytes input

Arguments

name description
input (required) the data to hash - can be binary data or text

Examples

$ gomplate -i '{{ crypto.SHA256Bytes "foo" | base64.Encode }}'
LCa0a2j/xo/5m0U8HTBBNBNCLXBkg7+g+YpeiGJm564=

crypto.WPAPSK

This is really an alias to crypto.PBKDF2 with the values necessary to convert ASCII passphrases to the WPA pre-shared keys for use with WiFi networks.

This can be used, for example, to help generate a configuration for wpa_supplicant.

Added in gomplate v2.3.0

Usage

crypto.WPAPSK ssid password

Arguments

name description
ssid (required) the WiFi SSID (network name) - must be less than 32 characters
password (required) the password - must be between 8 and 63 characters

Examples

$ PW=abcd1234 gomplate -i '{{ crypto.WPAPSK "mynet" (getenv "PW") }}'
2c201d66f01237d17d4a7788051191f31706844ac3ffe7547a66c902f2900d34