From 7cb1de9f30bce86d19c875eb6d7287179e12b703 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Sun, 13 May 2018 13:48:45 -0700 Subject: [PATCH] website: Docs for all of the hash/crypto functions --- .../functions/base64sha256.html.md | 30 +++++++++++++++ .../functions/base64sha512.html.md | 30 +++++++++++++++ .../configuration/functions/bcrypt.html.md | 38 +++++++++++++++++++ .../docs/configuration/functions/md5.html.md | 28 ++++++++++++++ .../functions/rsadecrypt.html.md | 34 +++++++++++++++++ .../docs/configuration/functions/sha1.html.md | 28 ++++++++++++++ .../configuration/functions/sha256.html.md | 29 ++++++++++++++ .../configuration/functions/sha512.html.md | 29 ++++++++++++++ .../docs/configuration/functions/uuid.html.md | 36 ++++++++++++++++++ 9 files changed, 282 insertions(+) create mode 100644 website/docs/configuration/functions/base64sha256.html.md create mode 100644 website/docs/configuration/functions/base64sha512.html.md create mode 100644 website/docs/configuration/functions/bcrypt.html.md create mode 100644 website/docs/configuration/functions/md5.html.md create mode 100644 website/docs/configuration/functions/rsadecrypt.html.md create mode 100644 website/docs/configuration/functions/sha1.html.md create mode 100644 website/docs/configuration/functions/sha256.html.md create mode 100644 website/docs/configuration/functions/sha512.html.md create mode 100644 website/docs/configuration/functions/uuid.html.md diff --git a/website/docs/configuration/functions/base64sha256.html.md b/website/docs/configuration/functions/base64sha256.html.md new file mode 100644 index 000000000..6d05e3791 --- /dev/null +++ b/website/docs/configuration/functions/base64sha256.html.md @@ -0,0 +1,30 @@ +--- +layout: "functions" +page_title: "base64sha256 function" +sidebar_current: "docs-funcs-crypto-base64sha256" +description: |- + The base64sha256 function computes the SHA256 hash of a given string and + encodes it with Base64. +--- + +# `base64sha256` Function + +`base64sha256` computes the SHA256 hash of a given string and encodes it with +Base64. + +The given string is first encoded as UTF-8 and then the SHA256 algorithm is applied +as defined in [RFC 4634](https://tools.ietf.org/html/rfc4634). The raw hash is +then encoded with Base64 before returning. Terraform uses the "standard" Base64 +alphabet as defined in [RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4). + +## Examples + +``` +> base64sha256("hello world") +uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek= +``` + +## Related Functions + +* [`sha256`](./sha256.html) calculates the same hash but returns the result + in a more-verbose hexadecimal encoding. diff --git a/website/docs/configuration/functions/base64sha512.html.md b/website/docs/configuration/functions/base64sha512.html.md new file mode 100644 index 000000000..befcc94ad --- /dev/null +++ b/website/docs/configuration/functions/base64sha512.html.md @@ -0,0 +1,30 @@ +--- +layout: "functions" +page_title: "base64sha512 function" +sidebar_current: "docs-funcs-crypto-base64sha512" +description: |- + The base64sha512 function computes the SHA512 hash of a given string and + encodes it with Base64. +--- + +# `base64sha512` Function + +`base64sha512` computes the SHA512 hash of a given string and encodes it with +Base64. + +The given string is first encoded as UTF-8 and then the SHA512 algorithm is applied +as defined in [RFC 4634](https://tools.ietf.org/html/rfc4634). The raw hash is +then encoded with Base64 before returning. Terraform uses the "standard" Base64 +alphabet as defined in [RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4). + +## Examples + +``` +> base64sha512("hello world") +MJ7MSJwS1utMxA9QyQLytNDtd+5RGnx6m808qG1M2G+YndNbxf9JlnDaNCVbRbDP2DDoH2Bdz33FVC6TrpzXbw== +``` + +## Related Functions + +* [`sha512`](./sha512.html) calculates the same hash but returns the result + in a more-verbose hexadecimal encoding. diff --git a/website/docs/configuration/functions/bcrypt.html.md b/website/docs/configuration/functions/bcrypt.html.md new file mode 100644 index 000000000..5cc89ee31 --- /dev/null +++ b/website/docs/configuration/functions/bcrypt.html.md @@ -0,0 +1,38 @@ +--- +layout: "functions" +page_title: "bcrypt function" +sidebar_current: "docs-funcs-crypto-bcrypt" +description: |- + The bcrypt function computes a hash of the given string using the Blowfish + cipher. +--- + +# `bcrypt` Function + +`bcrypt` computes a hash of the given string using the Blowfish cipher, +returning a string in +[the _Modular Crypt Format_](https://passlib.readthedocs.io/en/stable/modular_crypt_format.html) +usually expected in the shadow password file on many Unix systems. + +```hcl +bcrypt(string, cost) +``` + +The `cost` argument is optional and will default to 10 if unspecified. + +Since a bcrypt hash value includes a randomly selected salt, each call to this +function will return a different value, even if the given string and cost are +the same. Using this function directly with resource arguments will therefore +cause spurious diffs. We recommend using this function only in `provisioner` +blocks, or in data resources whose results are only used in `provisioner` +blocks. + +The version prefix on the generated string (e.g. `$2a$`) may change in future +versions of Terraform. + +## Examples + +``` +> bcrypt("hello world") +$2a$10$D5grTTzcsqyvAeIAnY/mYOIqliCoG7eAMX0/oFcuD.iErkksEbcAa +``` diff --git a/website/docs/configuration/functions/md5.html.md b/website/docs/configuration/functions/md5.html.md new file mode 100644 index 000000000..c63e68ea6 --- /dev/null +++ b/website/docs/configuration/functions/md5.html.md @@ -0,0 +1,28 @@ +--- +layout: "functions" +page_title: "md5 function" +sidebar_current: "docs-funcs-crypto-md5" +description: |- + The md5 function computes the MD5 hash of a given string and encodes it + with hexadecimal digits. +--- + +# `md5` Function + +`md5` computes the MD5 hash of a given string and encodes it with +hexadecimal digits. + +The given string is first encoded as UTF-8 and then the MD5 algorithm is applied +as defined in [RFC 1321](https://tools.ietf.org/html/rfc1321). The raw hash is +then encoded to lowercase hexadecimal digits before returning. + +Before using this function for anything security-sensitive, refer to +[RFC 6151](https://tools.ietf.org/html/rfc6151) for updated security +considerations applying to the MD5 algorithm. + +## Examples + +``` +> md5("hello world") +5eb63bbbe01eeed093cb22bb8f5acdc3 +``` diff --git a/website/docs/configuration/functions/rsadecrypt.html.md b/website/docs/configuration/functions/rsadecrypt.html.md new file mode 100644 index 000000000..46045f536 --- /dev/null +++ b/website/docs/configuration/functions/rsadecrypt.html.md @@ -0,0 +1,34 @@ +--- +layout: "functions" +page_title: "rsadecrypt function" +sidebar_current: "docs-funcs-crypto-rsadecrypt" +description: |- + The rsadecrypt function decrypts an RSA-encrypted message. +--- + +# `rsadecrypt` Function + +`rsadecrypt` decrypts an RSA-encrypted ciphertext, returning the corresponding +cleartext. + +```hcl +rsadecrypt(ciphertext, privatekey) +``` + +`ciphertext` must be a base64-encoded representation of the ciphertext, using +the PKCS #1 v1.5 padding scheme. Terraform uses the "standard" Base64 alphabet +as defined in [RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4). + +`privatekey` must be a PEM-encoded RSA private key that is not itself +encrypted. + +Terraform has no corresponding function for _encrypting_ a message. Use this +function to decrypt ciphertexts returned by remote services using a keypair +negotiated out-of-band. + +## Examples + +``` +> rsadecrypt(filebase64("${path.module}/ciphertext"), file("privatekey.pem")) +Hello, world! +``` diff --git a/website/docs/configuration/functions/sha1.html.md b/website/docs/configuration/functions/sha1.html.md new file mode 100644 index 000000000..382b4579a --- /dev/null +++ b/website/docs/configuration/functions/sha1.html.md @@ -0,0 +1,28 @@ +--- +layout: "functions" +page_title: "sha1 function" +sidebar_current: "docs-funcs-crypto-sha1" +description: |- + The sha1 function computes the SHA1 hash of a given string and encodes it + with hexadecimal digits. +--- + +# `sha1` Function + +`sha1` computes the SHA1 hash of a given string and encodes it with +hexadecimal digits. + +The given string is first encoded as UTF-8 and then the SHA1 algorithm is applied +as defined in [RFC 3174](https://tools.ietf.org/html/rfc3174). The raw hash is +then encoded to lowercase hexadecimal digits before returning. + +Collision attacks have been successfully performed against this hashing +function. Before using this function for anything security-sensitive, review +relevant literature to understand the security implications. + +## Examples + +``` +> sha1("hello world") +2aae6c35c94fcfb415dbe95f408b9ce91ee846ed +``` diff --git a/website/docs/configuration/functions/sha256.html.md b/website/docs/configuration/functions/sha256.html.md new file mode 100644 index 000000000..97f03f118 --- /dev/null +++ b/website/docs/configuration/functions/sha256.html.md @@ -0,0 +1,29 @@ +--- +layout: "functions" +page_title: "sha256 function" +sidebar_current: "docs-funcs-crypto-sha256" +description: |- + The sha256 function computes the SHA256 hash of a given string and encodes it + with hexadecimal digits. +--- + +# `sha256` Function + +`sha256` computes the SHA256 hash of a given string and encodes it with +hexadecimal digits. + +The given string is first encoded as UTF-8 and then the SHA256 algorithm is applied +as defined in [RFC 4634](https://tools.ietf.org/html/rfc4634). The raw hash is +then encoded to lowercase hexadecimal digits before returning. + +## Examples + +``` +> sha256("hello world") +b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 +``` + +## Related Functions + +* [`base64sha256`](./base64sha256.html) calculates the same hash but returns + the result in a more-compact Base64 encoding. diff --git a/website/docs/configuration/functions/sha512.html.md b/website/docs/configuration/functions/sha512.html.md new file mode 100644 index 000000000..88eb38bff --- /dev/null +++ b/website/docs/configuration/functions/sha512.html.md @@ -0,0 +1,29 @@ +--- +layout: "functions" +page_title: "sha512 function" +sidebar_current: "docs-funcs-crypto-sha512" +description: |- + The sha512 function computes the SHA512 hash of a given string and encodes it + with hexadecimal digits. +--- + +# `sha512` Function + +`sha512` computes the SHA512 hash of a given string and encodes it with +hexadecimal digits. + +The given string is first encoded as UTF-8 and then the SHA512 algorithm is applied +as defined in [RFC 4634](https://tools.ietf.org/html/rfc4634). The raw hash is +then encoded to lowercase hexadecimal digits before returning. + +## Examples + +``` +> sha512("hello world") +309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f989dd35bc5ff499670da34255b45b0cfd830e81f605dcf7dc5542e93ae9cd76f +``` + +## Related Functions + +* [`base64sha512`](./base64sha512.html) calculates the same hash but returns + the result in a more-compact Base64 encoding. diff --git a/website/docs/configuration/functions/uuid.html.md b/website/docs/configuration/functions/uuid.html.md new file mode 100644 index 000000000..146bc619f --- /dev/null +++ b/website/docs/configuration/functions/uuid.html.md @@ -0,0 +1,36 @@ +--- +layout: "functions" +page_title: "uuid function" +sidebar_current: "docs-funcs-crypto-uuid" +description: |- + The uuid function generates a unique id. +--- + +# `uuid` Function + +`uuid` generates a unique identifier string. + +The id is a generated and formatted as required by +[RFC 4122 section 4.4](https://tools.ietf.org/html/rfc4122#section-4.4), +producing a Version 4 UUID. The result is a UUID generated only from +pseudo-random numbers. + +This function produces a new value each time it is called, and so using it +directly in resource arguments will result in spurious diffs. We do not +recommend using the `uuid` function in resource configurations, but it can +be used with care in conjunction with +[the `ignore_changes` lifecycle meta-argument](/docs/configuration/resources.html#ignore_changes). + +In most cases we recommend using [the `random` provider](/docs/providers/random/index.html) +instead, since it allows the one-time generation of random values that are +then retained in the Terraform [state](/docs/state/index.html) for use by +future operations. In particular, +[`random_id`](/docs/providers/random/r/id.html) can generate results with +equivalent randomness to the `uuid` function. + +## Examples + +``` +> uuid() +b5ee72a3-54dd-c4b8-551c-4bdc0204cedb +```