view release on metacpan or  search on metacpan

lib/Crypt/ASN1.pm  view on Meta::CPAN

B<Keys>: C<type>, C<format>, C<value>, C<bits>.

C<value> is the packed bit data (MSB-first).  C<format> follows the same
rules as C<OCTET_STRING> (C<"bytes">, C<"hex">, or C<"base64">).  All three
forms are accepted by the encoder.

C<bits> is the exact number of significant bits.  The quantity
C<< 8 * byte_length(value) - bits >> gives the number of unused trailing
bits in the last byte.

When C<format> is absent the encoder treats C<value> as raw bytes.  When
C<bits> is absent it defaults to C<< 8 * length(value) >> (no unused bits).

  # default format (raw bytes, 25 significant bits)
  { type => "BIT_STRING", format => "bytes",
    value => "\x03\x02\x01\x00", bits => 25 }

  # hex format
  { type => "BIT_STRING", format => "hex",
    value => "03020100", bits => 25 }

=head3 UTF8_STRING

B<Keys>: C<type>, C<format>, C<value>.

C<value> is a Perl Unicode string (C<utf8> flag on).  C<format> is always
C<"utf8">.

  { type => "UTF8_STRING", format => "utf8", value => "caf\x{e9}" }

=head3 PRINTABLE_STRING, IA5_STRING, TELETEX_STRING

B<Keys>: C<type>, C<format>, C<value>.

C<value> is a byte string.  C<format> is always C<"string"> for all three.

  { type => "PRINTABLE_STRING", format => "string", value => "abc" }
  { type => "IA5_STRING",       format => "string", value => "ia5" }
  { type => "TELETEX_STRING",   format => "string", value => "tele" }

=head3 UTCTIME

B<Keys>: C<type>, C<format>, C<value>.

C<value> is a timestamp.  C<format> describes the representation:

  format    value                          decode option    example
  --------  -----------------------------  ---------------  -----------------------
  rfc3339   RFC 3339 string                (default)        "2024-01-15T10:30:00Z"
  epoch     Unix timestamp (integer)       dt => 'epoch'    1705314600

Both forms are accepted by the encoder.  When C<format> is absent, the
encoder auto-detects: an all-digit value is treated as epoch, a value
matching C<YYYY-> is treated as RFC 3339.

For C<UTCTIME>, encoder input must fall within the UTCTime year window
C<1950..2049>; values outside that range are rejected.  Fractional seconds
are also rejected for C<UTCTIME>.

Time validation in the encoder is currently B<syntactic>, not full calendar
validation.  The encoder checks the accepted input shape and ASN.1-specific
constraints above, but it does not verify that every RFC 3339-looking date
and time is semantically valid.

The decoder expands the 2-digit UTCTime year using the RFC 5280 window
(YY E<gt>= 50 E<rarr> 19YY, else 20YY).  Timezone offsets are preserved
(e.g. C<"2024-01-15T10:30:00+05:30">).

=head3 GENERALIZEDTIME

B<Keys>: C<type>, C<format>, C<value>.

Same C<format> rules as C<UTCTIME>; both forms are accepted by the encoder.
Fractional seconds are preserved (e.g. C<"2024-01-15T10:30:00.125Z">).
Validation is likewise syntactic only; semantically invalid calendar values
that match the accepted timestamp syntax are not currently rejected.

=head3 SEQUENCE

B<Keys>: C<type>, C<format>, C<value>.

C<value> is an arrayref of child node hashrefs (in order).  C<format> is
always C<"array">.

  { type => "SEQUENCE", format => "array", value => [ ...children... ] }

=head3 SET

B<Keys>: C<type>, C<format>, C<value>.

Same structure as C<SEQUENCE>.  C<format> is always C<"array">.  Both
ASN.1 SET and SET OF are represented as C<type =E<gt> "SET"> (they share
the same DER tag C<0x31>).

=head3 CUSTOM

Represents any tag that does not map to one of the built-in type names above.
This is commonly used for context-specific implicit/explicit tags (C<[0]>,
C<[1]>, ...) found in X.509 certificates and other ASN.1 schemas, but it can
also be emitted by the decoder for unsupported universal tags.

B<Keys>: C<type>, C<format>, C<value>, C<class>, C<constructed>, C<tag>.

=over

=item C<class> (string) -- C<"CONTEXT_SPECIFIC">, C<"APPLICATION">, C<"UNIVERSAL">, or C<"PRIVATE">

=item C<constructed> (integer) -- C<1> if constructed, C<0> if primitive

=item C<tag> (integer) -- the tag number (e.g. C<0> for C<[0]>)

Must be a non-negative integer within the range supported by the current
encoder build.

=back

B<Constructed> (C<< constructed => 1 >>): C<value> is an arrayref of child
nodes.  C<format> is C<"array">.

  { type => "CUSTOM", format => "array",
    class => "CONTEXT_SPECIFIC", constructed => 1, tag => 0,
    value => [ { type => "INTEGER", ... } ] }

B<Primitive> (C<< constructed => 0 >>): C<value> is raw data.  C<format>
follows the same rules as C<OCTET_STRING> (C<"bytes">, C<"hex">, or
C<"base64"> depending on the C<bin> decode option).  All three forms are
accepted by the encoder.  Primitive C<CUSTOM> values must not be references.

  # default format
  { type => "CUSTOM", format => "bytes",
    class => "CONTEXT_SPECIFIC", constructed => 0, tag => 1,
    value => "\xAA\xBB" }

  # hex format (bin => 'hex')
  { type => "CUSTOM", format => "hex",