z_crypto (zotonic_core v1.0.0-rc.17)

Crypto related functions for checksums and signatures.

Summary

Functions

auth_hash(SiteSecret, UserSecret, Data)

Hash a value for authentication. This is used for signing payload data in user authentication flows. The data is signed using the concatenation of the Site secret and the user secret. Changing any of those will invalidate all signed data (cookies, autologon secrets etc.) for the user.

checksum(Data, Context)

Calculate a checksum for the given data using the sign_key_simple of the site.

checksum_assert(Data, Checksum, Context)

Assert that the checksum is correct. Throws an exception of class error with reason checksum_invalid if the checksum is not valid. The sign_key_simple if used for the checksum calculation.

decode_value(Data, Context)

Decode a value. Crash if the checksum is invalid.

decode_value_expire(Encoded, Context)

Decode a value using a checksum, check date to check for expiration. Crashes if the checksum is invalid.

depickle(Data, Context)

Decode pickled base64url data. If the data checksum is invalid then an exception of class error with reason checksum_invalid is thrown. The site's sign_key is used as the secret.

encode_value(Value, Context)

Encode value to a binary with a checksum, for use in cookies.

encode_value_expire(Value, Date, Context)

Encode a value using a checksum, add a date to check for expiration.

hex_sha2(Value)

Hash256 data and encode into a hex string safe for filenames and texts.

hex_sha2_file(File)

Calculate the hash of a file by incrementally reading it.

hex_sha(Value)

Hash data and encode into a hex string safe for filenames and texts.

pickle(Term, Context)

Encode an arbitrary to a binary. A checksum is added to prevent decoding erlang terms not originating from this server. An Nonce is added so that identical terms vary in their checksum. The encoded value is safe to use in URLs (base64url). The site's sign_key is used as the secret.

Functions

auth_hash(SiteSecret, UserSecret, Data)

-spec auth_hash(SiteSecret, UserSecret, Data) -> Hash
                   when
                       SiteSecret :: binary(),
                       UserSecret :: binary(),
                       Data :: iodata(),
                       Hash :: binary().

Hash a value for authentication. This is used for signing payload data in user authentication flows. The data is signed using the concatenation of the Site secret and the user secret. Changing any of those will invalidate all signed data (cookies, autologon secrets etc.) for the user.

checksum(Data, Context)

-spec checksum(Data, Context) -> Checksum
                  when Data :: iodata(), Context :: z:context(), Checksum :: binary().

Calculate a checksum for the given data using the sign_key_simple of the site.

checksum_assert(Data, Checksum, Context)

-spec checksum_assert(Data, Checksum, Context) -> ok | no_return()
                         when Data :: iodata(), Checksum :: binary() | string(), Context :: z:context().

Assert that the checksum is correct. Throws an exception of class error with reason checksum_invalid if the checksum is not valid. The sign_key_simple if used for the checksum calculation.

decode_value(Data, Context)

Decode a value. Crash if the checksum is invalid.

decode_value_expire(Encoded, Context)

-spec decode_value_expire(Encoded, Context) -> {ok, Value} | {error, expired}
                             when Encoded :: binary(), Value :: term(), Context :: z:context().

Decode a value using a checksum, check date to check for expiration. Crashes if the checksum is invalid.

depickle(Data, Context)

-spec depickle(Data, Context) -> Term | no_return()
                  when Data :: binary(), Context :: z:context(), Term :: term().

Decode pickled base64url data. If the data checksum is invalid then an exception of class error with reason checksum_invalid is thrown. The site's sign_key is used as the secret.

encode_value(Value, Context)

Encode value to a binary with a checksum, for use in cookies.

encode_value_expire(Value, Date, Context)

-spec encode_value_expire(Value, Date, Context) -> Encoded
                             when
                                 Value :: term(),
                                 Date :: calendar:datetime(),
                                 Context :: z:context(),
                                 Encoded :: binary().

Encode a value using a checksum, add a date to check for expiration.

hex_sha2(Value)

-spec hex_sha2(Value) -> Hash when Value :: iodata(), Hash :: binary().

Hash256 data and encode into a hex string safe for filenames and texts.

hex_sha2_file(File)

-spec hex_sha2_file(File) -> {ok, Hash} | {error, Reason}
                       when
                           File :: file:filename_all(),
                           Hash :: binary(),
                           Reason :: file:posix() | term().

Calculate the hash of a file by incrementally reading it.

hex_sha(Value)

-spec hex_sha(Value) -> Hash when Value :: iodata(), Hash :: binary().

Hash data and encode into a hex string safe for filenames and texts.

pickle(Term, Context)

-spec pickle(Term, Context) -> Data when Term :: term(), Context :: z:context(), Data :: binary().

Encode an arbitrary to a binary. A checksum is added to prevent decoding erlang terms not originating from this server. An Nonce is added so that identical terms vary in their checksum. The encoded value is safe to use in URLs (base64url). The site's sign_key is used as the secret.