/ 
CryptX-0.088_003
⭐ Starred 36 / Crypt::Misc

NAME

Crypt::Misc - miscellaneous functions related to (or used by) CryptX

SYNOPSIS

use Crypt::Misc ':all';

my $rawbytes = 'hello world';
my $filename = 'sample.bin';
my $pem_data = "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n";
my $str1 = 'same';
my $str2 = 'same';

# Base64 and Base64/URL-safe functions
my $base64    = encode_b64($rawbytes);
my $rawbytes2 = decode_b64($base64);
my $base64url = encode_b64u($rawbytes);
my $rawbytes3 = decode_b64u($base64url);

# read/write file
my $rawdata = read_rawfile($filename);
write_rawfile($filename, $rawdata);

# convert PEM/DER
my $der_data = pem_to_der($pem_data);
my $pem_data2 = der_to_pem($der_data, "PUBLIC KEY");

# others
die "mismatch" unless slow_eq($str1, $str2);

DESCRIPTION

This module contains a collection of mostly unsorted functions loosely-related to CryptX distribution but not implementing cryptography.

Most of them are also available in other perl modules but once you utilize CryptX you might avoid dependencies on other modules by using functions from Crypt::Misc.

By default, Crypt::Misc doesn't import any function. You can import individual functions or use the :all tag.

FUNCTIONS

By default, Crypt::Misc doesn't import any function. You can import individual functions like this:

use Crypt::Misc qw(read_rawfile);

Or import all available functions:

use Crypt::Misc ':all';

All encoding functions (encode_b64, encode_b58b, etc.) accept a binary string and return an ASCII string. All decoding functions (decode_b64, decode_b58b, etc.) accept an ASCII string and return a binary string, or undef if the input is malformed.

An empty string is considered valid input and decodes to an empty string. undef is considered invalid input and results in undef. Non-empty input with no actual payload, such as whitespace-only or padding-only input, is also considered malformed and results in undef.

The Base64 decoders decode_b64 and decode_b64u also accept otherwise valid payload with embedded whitespace. The other decoder families in this module do not; for them, embedded whitespace is treated as malformed input.

read_rawfile

Since: 0.029

$rawdata = read_rawfile($filename);

Read file $filename into a scalar as a binary data (without decoding/transformation).

write_rawfile

Since: 0.029

write_rawfile($filename, $rawdata);

Write $rawdata to file $filename as binary data.

slow_eq

Since: 0.029

if (slow_eq($data1, $data2)) { ... }

Constant time compare (to avoid timing side-channel). Returns 1 if the strings are equal, 0 if they differ, or undef if either argument is undef.

pem_to_der

Since: 0.029

$der_data = pem_to_der($pem_data);
#or
$der_data = pem_to_der($pem_data, $password);

Convert PEM to DER representation. Supports also password protected PEM data. Returns undef if $pem_data cannot be parsed (no valid PEM block found) or if the BEGIN / END labels do not match. Croaks if the PEM is encrypted but no $password is provided. If an encrypted PEM is supplied with the wrong password, decryption is expected to croak from the underlying cipher/padding layer.

der_to_pem

Since: 0.029

$pem_data = der_to_pem($der_data, $header_name);
#or
$pem_data = der_to_pem($der_data, $header_name, $password);
#or
$pem_data = der_to_pem($der_data, $header_name, $password, $cipher_name);

# $header_name e.g. "PUBLIC KEY", "RSA PRIVATE KEY" ...
# $cipher_name e.g. "DES-EDE3-CBC", "AES-256-CBC" (DEFAULT) ...

Convert DER to PEM representation. Returns a PEM string (ASCII). Supports also password protected PEM data. Any defined $password, including false-like values like '' or '0', enables PEM encryption.

Security note: do not use ECB-based ciphers (e.g. AES-256-ECB) for PEM encryption - ECB encrypts each block independently, leaking plaintext structure. Use the default AES-256-CBC or another chaining mode (CBC, CFB, OFB).

Security note: the traditional PEM encryption format uses a single-iteration MD5-based key derivation which is weak against brute-force. For new applications, prefer PKCS#8 encrypted keys (e.g. via "export_key_pem" in Crypt::PK::RSA) or an independent encryption layer.

random_v4uuid

Since: 0.031

my $uuid = random_v4uuid();

Returns cryptographically strong Version 4 random UUID: xxxxxxxx-xxxx-4xxx-Yxxx-xxxxxxxxxxxx where x is any hexadecimal digit and Y is one of 8, 9, A, B (1000, 1001, 1010, 1011) e.g. f47ac10b-58cc-4372-a567-0e02b2c3d479.

is_v4uuid

Since: 0.031

if (is_v4uuid($uuid)) {
  ...
}

Checks the given $uuid string whether it matches Version 4 UUID format with a relaxed variant policy. The variant nibble may be one of 0, 8, 9, A, or B. Returns 0 (mismatch) or 1 (match).

random_v7uuid

Since: CryptX-0.088

my $uuid = random_v7uuid();

Returns a cryptographically strong Version 7 time-ordered UUID: xxxxxxxx-xxxx-7xxx-Yxxx-xxxxxxxxxxxx where the first 48 bits encode the current Unix time in milliseconds (making UUIDs sortable by generation time), followed by random bits. Ordering is therefore coarse at millisecond granularity only; UUIDs generated within the same millisecond are not guaranteed to be lexicographically monotonic. Y is one of 8, 9, A, B (RFC 9562 variant).

is_uuid

Since: CryptX-0.088

if (is_uuid($uuid)) {
  ...
}

Checks whether $uuid is a validly formatted UUID (any version) in the standard xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx form with a relaxed variant policy. The variant nibble may be one of 0, 8, 9, A, or B. Returns 1 (match) or 0 (mismatch). For a version-specific check see "is_v4uuid".

increment_octets_le

Since: 0.048

$octets = increment_octets_le($octets);

Treat input $octets as a little-endian big number and return the incremented value.

increment_octets_be

Since: 0.048

$octets = increment_octets_be($octets);

Treat input $octets as a big-endian big number and return the incremented value.

encode_b64

Since: 0.029

$base64string = encode_b64($rawdata);

Encode $rawbytes into Base64 string, no line-endings in the output string.

decode_b64

Since: 0.029

$rawdata = decode_b64($base64string);

Decode a Base64 string.

encode_b64u

Since: 0.029

$base64url_string = encode_b64u($rawdata);

Encode $rawbytes into Base64/URL-Safe string, no line-endings in the output string.

decode_b64u

Since: 0.029

$rawdata = decode_b64u($base64url_string);

Decode a Base64/URL-Safe string.

encode_b32r

Since: 0.049

$string = encode_b32r($rawdata);

Encode bytes into Base32 (rfc4648 alphabet) string, without "=" padding.

decode_b32r

Since: 0.049

$rawdata = decode_b32r($string);

Decode a Base32 (rfc4648 alphabet) string into bytes.

encode_b32b

Since: 0.049

$string = encode_b32b($rawdata);

Encode bytes into Base32 (base32hex alphabet) string, without "=" padding.

decode_b32b

Since: 0.049

$rawdata = decode_b32b($string);

Decode a Base32 (base32hex alphabet) string into bytes.

encode_b32z

Since: 0.049

$string = encode_b32z($rawdata);

Encode bytes into Base32 (zbase32 alphabet) string.

decode_b32z

Since: 0.049

$rawdata = decode_b32z($string);

Decode a Base32 (zbase32 alphabet) string into bytes.

encode_b32c

Since: 0.049

$string = encode_b32c($rawdata);

Encode bytes into Base32 (crockford alphabet) string.

decode_b32c

Since: 0.049

$rawdata = decode_b32c($string);

Decode a Base32 (crockford alphabet) string into bytes.

encode_b58b

Since: 0.049

$string = encode_b58b($rawdata);

Encode bytes into Base58 (Bitcoin alphabet) string.

decode_b58b

Since: 0.049

$rawdata = decode_b58b($string);

Decode a Base58 (Bitcoin alphabet) string into bytes.

encode_b58f

Since: 0.049

$string = encode_b58f($rawdata);

Encode bytes into Base58 (Flickr alphabet) string.

decode_b58f

Since: 0.049

$rawdata = decode_b58f($string);

Decode a Base58 (Flickr alphabet) string into bytes.

encode_b58r

Since: 0.049

$string = encode_b58r($rawdata);

Encode bytes into Base58 (Ripple alphabet) string.

decode_b58r

Since: 0.049

$rawdata = decode_b58r($string);

Decode a Base58 (Ripple alphabet) string into bytes.

encode_b58t

Since: 0.049

$string = encode_b58t($rawdata);

Encode bytes into Base58 (Tipple alphabet) string.

decode_b58t

Since: 0.049

$rawdata = decode_b58t($string);

Decode a Base58 (Tipple alphabet) string into bytes.

encode_b58s

Since: 0.049

$string = encode_b58s($rawdata);

Encode bytes into Base58 (Stellar alphabet) string.

decode_b58s

Since: 0.049

$rawdata = decode_b58s($string);

Decode a Base58 (Stellar alphabet) string into bytes.

SEE ALSO