ns: crypto preamble: | 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!_ funcs: - name: crypto.Bcrypt released: v2.6.0 description: | Uses the [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) password hashing algorithm to generate the hash of a given string. Wraps the [`golang.org/x/crypto/brypt`](https://godoc.org/golang.org/x/crypto/bcrypt) package. pipeline: true arguments: - name: cost required: false description: the cost, as a number from `4` to `31` - defaults to `10` - name: input required: true description: 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 - name: crypto.DecryptAES experimental: true released: v3.11.0 description: | 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.DecryptAESBytes`](#cryptodecryptaesbytes-_experimental_) 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. pipeline: true arguments: - name: key required: true description: the key to use for decryption - name: keyBits required: false description: the key length to use - defaults to `256` - name: input required: true description: the input to decrypt examples: - | $ gomplate -i '{{ base64.Decode "Gp2WG/fKOUsVlhcpr3oqgR+fRUNBcO1eZJ9CW+gDI18=" | crypto.DecryptAES "swordfish" 128 }}' hello world - name: crypto.DecryptAESBytes experimental: true released: v3.11.0 description: | 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. pipeline: true arguments: - name: key required: true description: the key to use for decryption - name: keyBits required: false description: the key length to use - defaults to `256` - name: input required: true description: the input to decrypt examples: - | $ gomplate -i '{{ base64.Decode "Gp2WG/fKOUsVlhcpr3oqgR+fRUNBcO1eZJ9CW+gDI18=" | crypto.DecryptAES "swordfish" 128 }}' hello world - name: crypto.EncryptAES experimental: true released: v3.11.0 description: | 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. pipeline: true arguments: - name: key required: true description: the key to use for encryption - name: keyBits required: false description: the key length to use - defaults to `256` - name: input required: true description: the input to encrypt examples: - | $ gomplate -i '{{ "hello world" | crypto.EncryptAES "swordfish" 128 | base64.Encode }}' MnRutHovsh/9JN3YrJtBVjZtI6xXZh33bCQS2iZ4SDI= - name: crypto.ECDSAGenerateKey experimental: true released: v3.11.0 description: | 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. pipeline: true arguments: - name: curve required: false description: | 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----- ... - name: crypto.ECDSADerivePublicKey experimental: true released: v3.11.0 description: | Derive a public key from an elliptic curve private key and output in PKIX ASN.1 DER form. pipeline: true arguments: - name: key required: true description: 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----- - name: crypto.Ed25519GenerateKey experimental: true released: v4.0.0 description: | Generate a new Ed25519 Private Key and output in PEM-encoded PKCS#8 ASN.1 DER form. examples: - | $ gomplate -i '{{ crypto.Ed25519GenerateKey }}' -----BEGIN PRIVATE KEY----- ... - name: crypto.Ed25519GenerateKeyFromSeed experimental: true released: v4.0.0 description: | Generate a new Ed25519 Private Key from a random seed and output in PEM-encoded PKCS#8 ASN.1 DER form. pipeline: true arguments: - name: encoding required: true description: the encoding that the seed is in (`hex` or `base64`) - name: seed required: true description: the random seed encoded in either base64 or hex examples: - | $ gomplate -i '{{ crypto.Ed25519GenerateKeyFromSeed "base64" "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA=" }}' -----BEGIN PRIVATE KEY----- ... - name: crypto.Ed25519DerivePublicKey experimental: true released: v4.0.0 description: | Derive a public key from an Ed25519 private key and output in PKIX ASN.1 DER form. pipeline: true arguments: - name: key required: true description: 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 - name: crypto.PBKDF2 released: v2.3.0 description: | Run the Password-Based Key Derivation Function #2 as defined in [RFC 8018 (PKCS #5 v2.1)](https://tools.ietf.org/html/rfc8018#section-5.2). This function outputs the binary result as a hexadecimal string. pipeline: false arguments: - name: password required: true description: the password to use to derive the key - name: salt required: true description: the salt - name: iter required: true description: iteration count - name: keylen required: true description: desired length of derived key - name: hashfunc required: false description: 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 - name: crypto.RSADecrypt experimental: true released: v3.8.0 description: | 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`](#cryptorsadecryptbytes-_experimental_) 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`](../base64/#base64decodebytes) function. pipeline: true arguments: - name: key required: true description: the private key to decrypt the input with - name: input required: true description: 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 - name: crypto.RSADecryptBytes experimental: true released: v3.8.0 description: | 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`](../base64/#base64decodebytes) function. See [`crypto.RSADecrypt`](#cryptorsadecrypt-_experimental_) for a function that outputs a string. pipeline: true arguments: - name: key required: true description: the private key to decrypt the input with - name: input required: true description: 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 - name: crypto.RSAEncrypt experimental: true released: v3.8.0 description: | 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](https://www.terraform.io/docs/configuration/functions/rsadecrypt.html). 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](../base64/#base64encode) 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`](https://pkg.go.dev/crypto/rsa/#EncryptPKCS1v15) documentation. pipeline: true arguments: - name: key required: true description: the public key to encrypt the input with - name: input required: true description: 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 - name: crypto.RSAGenerateKey experimental: true released: v3.8.0 description: | 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](https://cwe.mitre.org/data/definitions/326.html), keys shorter than `2048` bits may not be generated. The output is a string, suitable for use with the other `crypto.RSA*` functions. pipeline: true arguments: - name: bits required: false description: 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 - name: crypto.RSADerivePublicKey experimental: true released: v3.8.0 description: | 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. pipeline: true arguments: - name: key required: true description: 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 - rawName: "`crypto.SHA1`, `crypto.SHA224`, `crypto.SHA256`, `crypto.SHA384`, `crypto.SHA512`, `crypto.SHA512_224`, `crypto.SHA512_256`" released: v2.3.0 description: | Compute a checksum with a SHA-1 or SHA-2 algorithm as defined in [RFC 3174](https://tools.ietf.org/html/rfc3174) (SHA-1) and [FIPS 180-4](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) (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._ pipeline: false rawUsage: | ``` 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: input required: true description: the data to hash - can be binary data or text examples: - | $ gomplate -i '{{ crypto.SHA1 "foo" }}' f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 - | $ gomplate -i '{{ crypto.SHA512 "bar" }}' cc06808cbbee0510331aa97974132e8dc296aeb795be229d064bae784b0a87a5cf4281d82e8c99271b75db2148f08a026c1a60ed9cabdb8cac6d24242dac4063 - rawName: "`crypto.SHA1Bytes`, `crypto.SHA224Bytes`, `crypto.SHA256Bytes`, `crypto.SHA384Bytes`, `crypto.SHA512Bytes`, `crypto.SHA512_224Bytes`, `crypto.SHA512_256Bytes`" released: v3.11.0 description: | Compute a checksum with a SHA-1 or SHA-2 algorithm as defined in [RFC 3174](https://tools.ietf.org/html/rfc3174) (SHA-1) and [FIPS 180-4](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) (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._ pipeline: false rawUsage: | ``` 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: input required: true description: the data to hash - can be binary data or text examples: - | $ gomplate -i '{{ crypto.SHA256Bytes "foo" | base64.Encode }}' LCa0a2j/xo/5m0U8HTBBNBNCLXBkg7+g+YpeiGJm564= - name: crypto.WPAPSK released: v2.3.0 description: | This is really an alias to [`crypto.PBKDF2`](#cryptopbkdf2) 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](http://w1.fi/wpa_supplicant/). pipeline: false arguments: - name: ssid required: true description: the WiFi SSID (network name) - must be less than 32 characters - name: password required: true description: the password - must be between 8 and 63 characters examples: - | $ PW=abcd1234 gomplate -i '{{ crypto.WPAPSK "mynet" (getenv "PW") }}' 2c201d66f01237d17d4a7788051191f31706844ac3ffe7547a66c902f2900d34