github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs-src/content/functions/crypto.yml (about) 1 ns: crypto 2 preamble: | 3 A set of crypto-related functions to be able to perform hashing and (simple!) 4 encryption operations with `gomplate`. 5 6 _Note: These functions are mostly wrappers of existing functions in the Go 7 standard library. The authors of gomplate are not cryptographic experts, 8 however, and so can not guarantee correctness of implementation. It is 9 recommended to have your resident security experts inspect gomplate's code 10 before using gomplate for critical security infrastructure!_ 11 funcs: 12 - name: crypto.Bcrypt 13 released: v2.6.0 14 description: | 15 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. 16 pipeline: true 17 arguments: 18 - name: cost 19 required: false 20 description: the cost, as a number from `4` to `31` - defaults to `10` 21 - name: input 22 required: true 23 description: the input to hash, usually a password 24 examples: 25 - | 26 $ gomplate -i '{{ "foo" | crypto.Bcrypt }}' 27 $2a$10$jO8nKZ1etGkKK7I3.vPti.fYDAiBqwazQZLUhaFoMN7MaLhTP0SLy 28 - | 29 $ gomplate -i '{{ crypto.Bcrypt 4 "foo" }} 30 $2a$04$zjba3N38sjyYsw0Y7IRCme1H4gD0MJxH8Ixai0/sgsrf7s1MFUK1C 31 - name: crypto.DecryptAES 32 experimental: true 33 released: v3.11.0 34 description: | 35 Decrypts the given input using the given key. By default, 36 uses AES-256-CBC, but supports 128- and 192-bit keys as well. 37 38 This function prints the output as a string. Note that this may result in 39 unreadable text if the decrypted payload is binary. See 40 [`crypto.DecryptAESBytes`](#crypto.DecryptAESBytes) for another method. 41 42 This function is suitable for decrypting data that was encrypted by 43 Helm's `encryptAES` function, when the input is base64-decoded, and when 44 using 256-bit keys. 45 pipeline: true 46 arguments: 47 - name: key 48 required: true 49 description: the key to use for decryption 50 - name: keyBits 51 required: false 52 description: the key length to use - defaults to `256` 53 - name: input 54 required: true 55 description: the input to decrypt 56 examples: 57 - | 58 $ gomplate -i '{{ base64.Decode "Gp2WG/fKOUsVlhcpr3oqgR+fRUNBcO1eZJ9CW+gDI18=" | crypto.DecryptAES "swordfish" 128 }}' 59 hello world 60 - name: crypto.DecryptAESBytes 61 experimental: true 62 released: v3.11.0 63 description: | 64 Decrypts the given input using the given key. By default, 65 uses AES-256-CBC, but supports 128- and 192-bit keys as well. 66 67 This function outputs the raw byte array, which may be sent as input to 68 other functions. 69 70 This function is suitable for decrypting data that was encrypted by 71 Helm's `encryptAES` function, when the input is base64-decoded, and when 72 using 256-bit keys. 73 pipeline: true 74 arguments: 75 - name: key 76 required: true 77 description: the key to use for decryption 78 - name: keyBits 79 required: false 80 description: the key length to use - defaults to `256` 81 - name: input 82 required: true 83 description: the input to decrypt 84 examples: 85 - | 86 $ gomplate -i '{{ base64.Decode "Gp2WG/fKOUsVlhcpr3oqgR+fRUNBcO1eZJ9CW+gDI18=" | crypto.DecryptAES "swordfish" 128 }}' 87 hello world 88 - name: crypto.EncryptAES 89 experimental: true 90 released: v3.11.0 91 description: | 92 Encrypts the given input using the given key. By default, 93 uses AES-256-CBC, but supports 128- and 192-bit keys as well. 94 95 This function is suitable for encrypting data that will be decrypted by 96 Helm's `decryptAES` function, when the output is base64-encoded, and when 97 using 256-bit keys. 98 pipeline: true 99 arguments: 100 - name: key 101 required: true 102 description: the key to use for encryption 103 - name: keyBits 104 required: false 105 description: the key length to use - defaults to `256` 106 - name: input 107 required: true 108 description: the input to encrypt 109 examples: 110 - | 111 $ gomplate -i '{{ "hello world" | crypto.EncryptAES "swordfish" 128 | base64.Encode }}' 112 MnRutHovsh/9JN3YrJtBVjZtI6xXZh33bCQS2iZ4SDI= 113 - name: crypto.ECDSAGenerateKey 114 experimental: true 115 released: v3.11.0 116 description: | 117 Generate a new Elliptic Curve Private Key and output in 118 PEM-encoded PKCS#1 ASN.1 DER form. 119 120 Go's standard NIST P-224, P-256, P-384, and P-521 elliptic curves are all 121 supported. 122 123 Default curve is P-256 and can be overridden with the optional `curve` 124 parameter. 125 pipeline: true 126 arguments: 127 - name: curve 128 required: false 129 description: | 130 One of Go's standard NIST curves, P-224, P-256, P-384, or P-521 - 131 defaults to P-256. 132 examples: 133 - | 134 $ gomplate -i '{{ crypto.ECDSAGenerateKey }}' 135 -----BEGIN EC PRIVATE KEY----- 136 ... 137 - name: crypto.ECDSADerivePublicKey 138 experimental: true 139 released: v3.11.0 140 description: | 141 Derive a public key from an elliptic curve private key and output in PKIX 142 ASN.1 DER form. 143 pipeline: true 144 arguments: 145 - name: key 146 required: true 147 description: the private key to derive a public key from 148 examples: 149 - | 150 $ gomplate -i '{{ crypto.ECDSAGenerateKey | crypto.ECDSADerivePublicKey }}' 151 -----BEGIN PUBLIC KEY----- 152 ... 153 - | 154 $ gomplate -d key=priv.pem -i '{{ crypto.ECDSADerivePublicKey (include "key") }}' 155 -----BEGIN PUBLIC KEY----- 156 MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBZvTS1wcCJSsGYQUVoSVctynkuhke 157 kikB38iNwx/80jzdm+Z8OmRGlwH6OE9NX1MyxjvYMimhcj6zkaOKh1/HhMABrfuY 158 +hIz6+EUt/Db51awO7iCuRly5L4TZ+CnMAsIbtUOqsqwSQDtv0AclAuogmCst75o 159 aztsmrD79OXXnhUlURI= 160 -----END PUBLIC KEY----- 161 - name: crypto.Ed25519GenerateKey 162 experimental: true 163 # released: v4.0.0 164 description: | 165 Generate a new Ed25519 Private Key and output in 166 PEM-encoded PKCS#8 ASN.1 DER form. 167 examples: 168 - | 169 $ gomplate -i '{{ crypto.Ed25519GenerateKey }}' 170 -----BEGIN PRIVATE KEY----- 171 ... 172 - name: crypto.Ed25519GenerateKeyFromSeed 173 experimental: true 174 # released: v4.0.0 175 description: | 176 Generate a new Ed25519 Private Key from a random seed and output in 177 PEM-encoded PKCS#8 ASN.1 DER form. 178 pipeline: true 179 arguments: 180 - name: encoding 181 required: true 182 description: the encoding that the seed is in (`hex` or `base64`) 183 - name: seed 184 required: true 185 description: the random seed encoded in either base64 or hex 186 examples: 187 - | 188 $ gomplate -i '{{ crypto.Ed25519GenerateKeyFromSeed "base64" "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA=" }}' 189 -----BEGIN PRIVATE KEY----- 190 ... 191 - name: crypto.Ed25519DerivePublicKey 192 experimental: true 193 # released: v4.0.0 194 description: | 195 Derive a public key from an Ed25519 private key and output in PKIX 196 ASN.1 DER form. 197 pipeline: true 198 arguments: 199 - name: key 200 required: true 201 description: the private key to derive a public key from 202 examples: 203 - | 204 $ gomplate -i '{{ crypto.Ed25519GenerateKey | crypto.Ed25519DerivePublicKey }}' 205 -----BEGIN PUBLIC KEY----- 206 ... 207 - | 208 $ gomplate -d key=priv.pem -i '{{ crypto.Ed25519DerivePublicKey (include "key") }}' 209 -----BEGIN PUBLIC KEY----- 210 ...PK 211 - name: crypto.PBKDF2 212 released: v2.3.0 213 description: | 214 Run the Password-Based Key Derivation Function #2 as defined in 215 [RFC 8018 (PKCS #5 v2.1)](https://tools.ietf.org/html/rfc8018#section-5.2). 216 217 This function outputs the binary result as a hexadecimal string. 218 pipeline: false 219 arguments: 220 - name: password 221 required: true 222 description: the password to use to derive the key 223 - name: salt 224 required: true 225 description: the salt 226 - name: iter 227 required: true 228 description: iteration count 229 - name: keylen 230 required: true 231 description: desired length of derived key 232 - name: hashfunc 233 required: false 234 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` 235 examples: 236 - | 237 $ gomplate -i '{{ crypto.PBKDF2 "foo" "bar" 1024 8 }}' 238 32c4907c3c80792b 239 - name: crypto.RSADecrypt 240 experimental: true 241 released: v3.8.0 242 description: | 243 Decrypt an RSA-encrypted input and print the output as a string. Note that 244 this may result in unreadable text if the decrypted payload is binary. See 245 [`crypto.RSADecryptBytes`](#crypto.RSADecryptBytes) for a safer method. 246 247 The private key must be a PEM-encoded RSA private key in PKCS#1, ASN.1 DER 248 form, which typically begins with `-----BEGIN RSA PRIVATE KEY-----`. 249 250 The input text must be plain ciphertext, as a byte array, or safely 251 convertible to a byte array. To decrypt base64-encoded input, you must 252 first decode with the [`base64.DecodeBytes`](../base64/#base64.DecodeBytes) 253 function. 254 pipeline: true 255 arguments: 256 - name: key 257 required: true 258 description: the private key to decrypt the input with 259 - name: input 260 required: true 261 description: the encrypted input 262 examples: 263 - | 264 $ gomplate -c pubKey=./testPubKey -c privKey=./testPrivKey \ 265 -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}} 266 {{ crypto.RSADecrypt .privKey $enc }}' 267 hello 268 - | 269 $ export ENCRYPTED="ScTcX1NZ6p/EeDIf6R7FKLcDFjvP98YgiBhyhPE4jtehajIyTKP1GL8C72qbAWrgdQ6A2cSVjoyo3viqf/PZxpcBDUUMDJuemTaJqUUjMWaDuPG37mQbmRtcvFTuUhw1qSbKyHorDOgTX5d4DvWV4otycGtBT6dXhnmmb5V72J/w3z68vtTJ21m9wREFD7LrYVHdFFtRZiIyMBAF0ngQ+hcujrxilnmgzPkEAg6E7Ccctn28Ie2c4CojrwRbNNxXNlIWCCkC/8Vq8qlDfZ70a+BsTmJDuScE6BZbTyteo9uGYrLn+bTIHNDj90AeLCKUTyWLUJ5Edi9LhlKVBoJUNQ==" 270 $ gomplate -c ciphertext=env:///ENCRYPTED -c privKey=./testPrivKey \ 271 -i '{{ base64.DecodeBytes .ciphertext | crypto.RSADecrypt .privKey }}' 272 hello 273 - name: crypto.RSADecryptBytes 274 experimental: true 275 released: v3.8.0 276 description: | 277 Decrypt an RSA-encrypted input and output the decrypted byte array. 278 279 The private key must be a PEM-encoded RSA private key in PKCS#1, ASN.1 DER 280 form, which typically begins with `-----BEGIN RSA PRIVATE KEY-----`. 281 282 The input text must be plain ciphertext, as a byte array, or safely 283 convertible to a byte array. To decrypt base64-encoded input, you must 284 first decode with the [`base64.DecodeBytes`](../base64/#base64.DecodeBytes) 285 function. 286 287 See [`crypto.RSADecrypt`](#crypto.RSADecrypt) for a function that outputs 288 a string. 289 pipeline: true 290 arguments: 291 - name: key 292 required: true 293 description: the private key to decrypt the input with 294 - name: input 295 required: true 296 description: the encrypted input 297 examples: 298 - | 299 $ gomplate -c pubKey=./testPubKey -c privKey=./testPrivKey \ 300 -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}} 301 {{ crypto.RSADecryptBytes .privKey $enc }}' 302 [104 101 108 108 111] 303 - | 304 $ gomplate -c pubKey=./testPubKey -c privKey=./testPrivKey \ 305 -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}} 306 {{ crypto.RSADecryptBytes .privKey $enc | conv.ToString }}' 307 hello 308 - name: crypto.RSAEncrypt 309 experimental: true 310 released: v3.8.0 311 description: | 312 Encrypt the input with RSA and the padding scheme from PKCS#1 v1.5. 313 314 This function is suitable for encrypting data that will be decrypted by 315 [Terraform's `rsadecrypt` function](https://www.terraform.io/docs/configuration/functions/rsadecrypt.html). 316 317 The key should be a PEM-encoded RSA public key in PKIX ASN.1 DER form, 318 which typically begins with `BEGIN PUBLIC KEY`. RSA public keys in PKCS#1 319 ASN.1 DER form are also supported (beginning with `RSA PUBLIC KEY`). 320 321 The output will not be encoded, so consider 322 [base64-encoding](../base64/#base64.Encode) it for display. 323 324 _Note:_ Output encrypted with this function will _not_ be deterministic, 325 so encrypting the same input twice will not result in the same ciphertext. 326 327 _Warning:_ Using this function may not be safe. See the warning on Go's 328 [`rsa.EncryptPKCS1v15`](https://golang.org/pkg/crypto/rsa/#EncryptPKCS1v15) 329 documentation. 330 pipeline: true 331 arguments: 332 - name: key 333 required: true 334 description: the public key to encrypt the input with 335 - name: input 336 required: true 337 description: the encrypted input 338 examples: 339 - | 340 $ gomplate -c pubKey=./testPubKey \ 341 -i '{{ "hello" | crypto.RSAEncrypt .pubKey | base64.Encode }}' 342 ScTcX1NZ6p/EeDIf6R7FKLcDFjvP98YgiBhyhPE4jtehajIyTKP1GL8C72qbAWrgdQ6A2cSVjoyo3viqf/PZxpcBDUUMDJuemTaJqUUjMWaDuPG37mQbmRtcvFTuUhw1qSbKyHorDOgTX5d4DvWV4otycGtBT6dXhnmmb5V72J/w3z68vtTJ21m9wREFD7LrYVHdFFtRZiIyMBAF0ngQ+hcujrxilnmgzPkEAg6E7Ccctn28Ie2c4CojrwRbNNxXNlIWCCkC/8Vq8qlDfZ70a+BsTmJDuScE6BZbTyteo9uGYrLn+bTIHNDj90AeLCKUTyWLUJ5Edi9LhlKVBoJUNQ== 343 - | 344 $ gomplate -c pubKey=./testPubKey \ 345 -i '{{ $enc := "hello" | crypto.RSAEncrypt .pubKey -}} 346 Ciphertext in hex: {{ printf "%x" $enc }}' 347 71729b87cccabb248b9e0e5173f0b12c01d9d2a0565bad18aef9d332ce984bde06acb8bb69334a01446f7f6430077f269e6fbf2ccacd972fe5856dd4719252ebddf599948d937d96ea41540dad291b868f6c0cf647dffdb5acb22cd33557f9a1ddd0ee6c1ad2bbafc910ba8f817b66ea0569afc06e5c7858fd9dc2638861fe7c97391b2f190e4c682b4aa2c9b0050081efe18b10aa8c2b2b5f5b68a42dcc06c9da35b37fca9b1509fddc940eb99f516a2e0195405bcb3993f0fa31bc038d53d2e7231dff08cc39448105ed2d0ac52d375cb543ca8a399f807cc5d007e2c44c69876d189667eee66361a393c4916826af77479382838cd4e004b8baa05636805a 348 - name: crypto.RSAGenerateKey 349 experimental: true 350 released: v3.8.0 351 description: | 352 Generate a new RSA Private Key and output in PEM-encoded PKCS#1 ASN.1 DER 353 form. 354 355 Default key length is 4096 bits, which should be safe enough for most 356 uses, but can be overridden with the optional `bits` parameter. 357 358 In order to protect against [CWE-326](https://cwe.mitre.org/data/definitions/326.html), 359 keys shorter than `2048` bits may not be generated. 360 361 The output is a string, suitable for use with the other `crypto.RSA*` 362 functions. 363 pipeline: true 364 arguments: 365 - name: bits 366 required: false 367 description: Length in bits of the generated key. Must be at least `2048`. Defaults to `4096` 368 examples: 369 - | 370 $ gomplate -i '{{ crypto.RSAGenerateKey }}' 371 -----BEGIN RSA PRIVATE KEY----- 372 ... 373 - | 374 $ gomplate -i '{{ $key := crypto.RSAGenerateKey 2048 -}} 375 {{ $pub := crypto.RSADerivePublicKey $key -}} 376 {{ $enc := "hello" | crypto.RSAEncrypt $pub -}} 377 {{ crypto.RSADecrypt $key $enc }}' 378 hello 379 - name: crypto.RSADerivePublicKey 380 experimental: true 381 released: v3.8.0 382 description: | 383 Derive a public key from an RSA private key and output in PKIX ASN.1 DER 384 form. 385 386 The output is a string, suitable for use with other `crypto.RSA*` 387 functions. 388 pipeline: true 389 arguments: 390 - name: key 391 required: true 392 description: the private key to derive a public key from 393 examples: 394 - | 395 $ gomplate -i '{{ crypto.RSAGenerateKey | crypto.RSADerivePublicKey }}' 396 -----BEGIN PUBLIC KEY----- 397 ... 398 - | 399 $ gomplate -c privKey=./privKey.pem \ 400 -i '{{ $pub := crypto.RSADerivePublicKey .privKey -}} 401 {{ $enc := "hello" | crypto.RSAEncrypt $pub -}} 402 {{ crypto.RSADecrypt .privKey $enc }}' 403 hello 404 - rawName: "`crypto.SHA1`, `crypto.SHA224`, `crypto.SHA256`, `crypto.SHA384`, `crypto.SHA512`, `crypto.SHA512_224`, `crypto.SHA512_256`" 405 released: v2.3.0 406 description: | 407 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). 408 409 These functions output the binary result as a hexadecimal string. 410 411 _Warning: SHA-1 is cryptographically broken and should not be used for secure applications._ 412 pipeline: false 413 rawUsage: | 414 ``` 415 crypto.SHA1 input 416 crypto.SHA224 input 417 crypto.SHA256 input 418 crypto.SHA384 input 419 crypto.SHA512 input 420 crypto.SHA512_224 input 421 crypto.SHA512_256 input 422 ``` 423 arguments: 424 - name: input 425 required: true 426 description: the data to hash - can be binary data or text 427 examples: 428 - | 429 $ gomplate -i '{{ crypto.SHA1 "foo" }}' 430 f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 431 - | 432 $ gomplate -i '{{ crypto.SHA512 "bar" }}' 433 cc06808cbbee0510331aa97974132e8dc296aeb795be229d064bae784b0a87a5cf4281d82e8c99271b75db2148f08a026c1a60ed9cabdb8cac6d24242dac4063 434 - rawName: "`crypto.SHA1Bytes`, `crypto.SHA224Bytes`, `crypto.SHA256Bytes`, `crypto.SHA384Bytes`, `crypto.SHA512Bytes`, `crypto.SHA512_224Bytes`, `crypto.SHA512_256Bytes`" 435 released: v3.11.0 436 description: | 437 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). 438 439 These functions output the raw binary result, suitable for piping to other functions. 440 441 _Warning: SHA-1 is cryptographically broken and should not be used for secure applications._ 442 pipeline: false 443 rawUsage: | 444 ``` 445 crypto.SHA1Bytes input 446 crypto.SHA224Bytes input 447 crypto.SHA256Bytes input 448 crypto.SHA384Bytes input 449 crypto.SHA512Bytes input 450 crypto.SHA512_224Bytes input 451 crypto.SHA512_256Bytes input 452 ``` 453 arguments: 454 - name: input 455 required: true 456 description: the data to hash - can be binary data or text 457 examples: 458 - | 459 $ gomplate -i '{{ crypto.SHA256Bytes "foo" | base64.Encode }}' 460 LCa0a2j/xo/5m0U8HTBBNBNCLXBkg7+g+YpeiGJm564= 461 - name: crypto.WPAPSK 462 released: v2.3.0 463 description: | 464 This is really an alias to [`crypto.PBKDF2`](#crypto.PBKDF2) with the 465 values necessary to convert ASCII passphrases to the WPA pre-shared keys for use with WiFi networks. 466 467 This can be used, for example, to help generate a configuration for [wpa_supplicant](http://w1.fi/wpa_supplicant/). 468 pipeline: false 469 arguments: 470 - name: ssid 471 required: true 472 description: the WiFi SSID (network name) - must be less than 32 characters 473 - name: password 474 required: true 475 description: the password - must be between 8 and 63 characters 476 examples: 477 - | 478 $ PW=abcd1234 gomplate -i '{{ crypto.WPAPSK "mynet" (getenv "PW") }}' 479 2c201d66f01237d17d4a7788051191f31706844ac3ffe7547a66c902f2900d34