.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Crypt::Misc 3"
.TH Crypt::Misc 3 2026-08-10 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Crypt::Misc \- miscellaneous functions related to (or used by) CryptX
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use Crypt::Misc \*(Aq:all\*(Aq;
\&
\& my $rawbytes = \*(Aqhello world\*(Aq;
\& my $filename = \*(Aqsample.bin\*(Aq;
\& my $pem_data = "\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-\en...\en\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\en";
\& my $str1 = \*(Aqsame\*(Aq;
\& my $str2 = \*(Aqsame\*(Aq;
\&
\& # 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);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module contains a collection of helper functions related to CryptX, but it
does not implement cryptography itself.
.PP
Most of them are also available in other Perl modules. If you already use
CryptX, these helpers can reduce extra dependencies.
.SH EXPORT
.IX Header "EXPORT"
Nothing is exported by default.
.PP
You can export selected functions:
.PP
.Vb 1
\&  use Crypt::Misc qw(read_rawfile write_rawfile slow_eq);
.Ve
.PP
Or all of them at once:
.PP
.Vb 1
\&  use Crypt::Misc \*(Aq:all\*(Aq;
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
All encoding functions (\f(CW\*(C`encode_b64\*(C'\fR, \f(CW\*(C`encode_b58b\*(C'\fR, etc.) accept a binary
string and return an ASCII string. All decoding functions (\f(CW\*(C`decode_b64\*(C'\fR,
\&\f(CW\*(C`decode_b58b\*(C'\fR, etc.) accept an ASCII string and return a binary string, or
\&\f(CW\*(C`undef\*(C'\fR if the input is malformed.
.PP
An empty string is considered valid input and decodes to an empty string.
\&\f(CW\*(C`undef\*(C'\fR is considered invalid input and results in \f(CW\*(C`undef\*(C'\fR. Non\-empty input
with no actual payload, such as whitespace\-only or padding\-only input, is also
considered malformed and results in \f(CW\*(C`undef\*(C'\fR.
.PP
The Base64 decoders \f(CW\*(C`decode_b64\*(C'\fR and \f(CW\*(C`decode_b64u\*(C'\fR 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.
.SS read_rawfile
.IX Subsection "read_rawfile"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 1
\& $rawdata = read_rawfile($filename);
.Ve
.PP
Reads file \f(CW$filename\fR into a scalar as binary data, without decoding or
transformation.
.SS write_rawfile
.IX Subsection "write_rawfile"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 1
\& write_rawfile($filename, $rawdata);
.Ve
.PP
Writes \f(CW$rawdata\fR to file \f(CW$filename\fR as binary data.
.SS slow_eq
.IX Subsection "slow_eq"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 1
\& if (slow_eq($data1, $data2)) { ... }
.Ve
.PP
Compares two strings in constant time to reduce timing side channels. Returns
\&\f(CW1\fR if the strings are equal, \f(CW0\fR if they differ, or \f(CW\*(C`undef\*(C'\fR if either
argument is \f(CW\*(C`undef\*(C'\fR.
.SS pem_to_der
.IX Subsection "pem_to_der"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 3
\&  $der_data = pem_to_der($pem_data);
\&  #or
\&  $der_data = pem_to_der($pem_data, $password);
.Ve
.PP
Converts PEM to DER. Also supports password\-protected PEM data.
Returns \f(CW\*(C`undef\*(C'\fR if \f(CW$pem_data\fR cannot be parsed (no valid PEM block found)
or if the \f(CW\*(C`BEGIN\*(C'\fR / \f(CW\*(C`END\*(C'\fR labels do not match. Croaks if the PEM is
encrypted but no \f(CW$password\fR is provided. If an encrypted PEM is supplied
with the wrong password, decryption is expected to croak from the underlying
cipher/padding layer.
.SS der_to_pem
.IX Subsection "der_to_pem"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 5
\&  $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) ...
.Ve
.PP
Converts DER to PEM. Returns an ASCII PEM string. Also supports
password\-protected PEM data. Any defined \f(CW$password\fR, including
false\-like values like \f(CW\*(Aq\*(Aq\fR or \f(CW\*(Aq0\*(Aq\fR, enables PEM encryption.
.PP
\&\fBSecurity note\fR: do not use ECB\-based ciphers (e.g. \f(CW\*(C`AES\-256\-ECB\*(C'\fR) for PEM
encryption \- ECB encrypts each block independently, leaking plaintext structure.
Use the default \f(CW\*(C`AES\-256\-CBC\*(C'\fR or another chaining mode (CBC, CFB, OFB).
.PP
\&\fBSecurity note\fR: 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.
.SS random_v4uuid
.IX Subsection "random_v4uuid"
\&\fISince: CryptX\-0.031\fR
.PP
.Vb 1
\& my $uuid = random_v4uuid();
.Ve
.PP
Returns a cryptographically strong version 4 random UUID:
\&\f(CW\*(C`xxxxxxxx\-xxxx\-4xxx\-Yxxx\-xxxxxxxxxxxx\*(C'\fR
where \f(CW\*(C`x\*(C'\fR is any hexadecimal digit and \f(CW\*(C`Y\*(C'\fR is one of 8, 9, A, B (1000, 1001, 1010, 1011)
e.g. \f(CW\*(C`f47ac10b\-58cc\-4372\-a567\-0e02b2c3d479\*(C'\fR.
.SS is_v4uuid
.IX Subsection "is_v4uuid"
\&\fISince: CryptX\-0.031\fR
.PP
.Vb 3
\&  if (is_v4uuid($uuid)) {
\&    ...
\&  }
.Ve
.PP
Checks whether the given \f(CW$uuid\fR string matches version 4 UUID format with a
relaxed variant policy. The variant nibble may be one of \f(CW0\fR, \f(CW8\fR, \f(CW9\fR,
\&\f(CW\*(C`A\*(C'\fR, or \f(CW\*(C`B\*(C'\fR. Returns \f(CW0\fR (mismatch) or \f(CW1\fR (match).
.SS random_v7uuid
.IX Subsection "random_v7uuid"
\&\fISince: CryptX\-0.088\fR
.PP
.Vb 1
\& my $uuid = random_v7uuid();
.Ve
.PP
Returns a cryptographically strong version 7 time\-ordered UUID:
\&\f(CW\*(C`xxxxxxxx\-xxxx\-7xxx\-Yxxx\-xxxxxxxxxxxx\*(C'\fR
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. \f(CW\*(C`Y\*(C'\fR is one of 8, 9, A, B
(RFC 9562 variant).
.SS is_uuid
.IX Subsection "is_uuid"
\&\fISince: CryptX\-0.088\fR
.PP
.Vb 3
\&  if (is_uuid($uuid)) {
\&    ...
\&  }
.Ve
.PP
Checks whether \f(CW$uuid\fR is a validly formatted UUID (any version) in the standard
\&\f(CW\*(C`xxxxxxxx\-xxxx\-xxxx\-xxxx\-xxxxxxxxxxxx\*(C'\fR form with a relaxed variant policy.
The variant nibble may be one of \f(CW0\fR, \f(CW8\fR, \f(CW9\fR, \f(CW\*(C`A\*(C'\fR, or \f(CW\*(C`B\*(C'\fR. Returns
\&\f(CW1\fR (match) or \f(CW0\fR (mismatch).
For a version\-specific check see "is_v4uuid".
.SS increment_octets_le
.IX Subsection "increment_octets_le"
\&\fISince: CryptX\-0.048\fR
.PP
.Vb 1
\& $octets = increment_octets_le($octets);
.Ve
.PP
Treats \f(CW$octets\fR as a little\-endian big number and returns the incremented
value.
.SS increment_octets_be
.IX Subsection "increment_octets_be"
\&\fISince: CryptX\-0.048\fR
.PP
.Vb 1
\& $octets = increment_octets_be($octets);
.Ve
.PP
Treats \f(CW$octets\fR as a big\-endian big number and returns the incremented value.
.SS encode_b64
.IX Subsection "encode_b64"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 1
\& $base64string = encode_b64($rawdata);
.Ve
.PP
Encodes \f(CW$rawdata\fR as a Base64 string. No line endings are added.
.SS decode_b64
.IX Subsection "decode_b64"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 1
\& $rawdata = decode_b64($base64string);
.Ve
.PP
Decodes a Base64 string.
.SS encode_b64u
.IX Subsection "encode_b64u"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 1
\& $base64url_string = encode_b64u($rawdata);
.Ve
.PP
Encodes \f(CW$rawdata\fR as a Base64 URL\-safe string. No line endings are added.
.SS decode_b64u
.IX Subsection "decode_b64u"
\&\fISince: CryptX\-0.029\fR
.PP
.Vb 1
\& $rawdata = decode_b64u($base64url_string);
.Ve
.PP
Decodes a Base64 URL\-safe string.
.SS encode_b32r
.IX Subsection "encode_b32r"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b32r($rawdata);
.Ve
.PP
Encode bytes into Base32 (rfc4648 alphabet) string, without "=" padding.
.SS decode_b32r
.IX Subsection "decode_b32r"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b32r($string);
.Ve
.PP
Decode a Base32 (rfc4648 alphabet) string into bytes.
.SS encode_b32b
.IX Subsection "encode_b32b"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b32b($rawdata);
.Ve
.PP
Encode bytes into Base32 (base32hex alphabet) string, without "=" padding.
.SS decode_b32b
.IX Subsection "decode_b32b"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b32b($string);
.Ve
.PP
Decode a Base32 (base32hex alphabet) string into bytes.
.SS encode_b32z
.IX Subsection "encode_b32z"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b32z($rawdata);
.Ve
.PP
Encode bytes into Base32 (zbase32 alphabet) string.
.SS decode_b32z
.IX Subsection "decode_b32z"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b32z($string);
.Ve
.PP
Decode a Base32 (zbase32 alphabet) string into bytes.
.SS encode_b32c
.IX Subsection "encode_b32c"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b32c($rawdata);
.Ve
.PP
Encode bytes into Base32 (crockford alphabet) string.
.SS decode_b32c
.IX Subsection "decode_b32c"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b32c($string);
.Ve
.PP
Decode a Base32 (crockford alphabet) string into bytes.
.SS encode_b58b
.IX Subsection "encode_b58b"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b58b($rawdata);
.Ve
.PP
Encode bytes into Base58 (Bitcoin alphabet) string.
.SS decode_b58b
.IX Subsection "decode_b58b"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b58b($string);
.Ve
.PP
Decode a Base58 (Bitcoin alphabet) string into bytes.
.SS encode_b58f
.IX Subsection "encode_b58f"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b58f($rawdata);
.Ve
.PP
Encode bytes into Base58 (Flickr alphabet) string.
.SS decode_b58f
.IX Subsection "decode_b58f"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b58f($string);
.Ve
.PP
Decode a Base58 (Flickr alphabet) string into bytes.
.SS encode_b58r
.IX Subsection "encode_b58r"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b58r($rawdata);
.Ve
.PP
Encode bytes into Base58 (Ripple alphabet) string.
.SS decode_b58r
.IX Subsection "decode_b58r"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b58r($string);
.Ve
.PP
Decode a Base58 (Ripple alphabet) string into bytes.
.SS encode_b58t
.IX Subsection "encode_b58t"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b58t($rawdata);
.Ve
.PP
Encode bytes into Base58 (Tipple alphabet) string.
.SS decode_b58t
.IX Subsection "decode_b58t"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b58t($string);
.Ve
.PP
Decode a Base58 (Tipple alphabet) string into bytes.
.SS encode_b58s
.IX Subsection "encode_b58s"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $string = encode_b58s($rawdata);
.Ve
.PP
Encode bytes into Base58 (Stellar alphabet) string.
.SS decode_b58s
.IX Subsection "decode_b58s"
\&\fISince: CryptX\-0.049\fR
.PP
.Vb 1
\& $rawdata = decode_b58s($string);
.Ve
.PP
Decode a Base58 (Stellar alphabet) string into bytes.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
CryptX