view release on metacpan or  search on metacpan

stdlib/modules/std/secure.zzm  view on Meta::CPAN

=item C<< Certificate.serial_number() >>

Returns the serial number as uppercase hexadecimal text with no
separators.

=item C<< Certificate.not_before() >> and C<< Certificate.not_after() >>

Return C<std/time> C<Time> objects for the certificate validity bounds.

=item C<< Certificate.fingerprint(String algorithm = "sha256") >>

Returns the certificate fingerprint as a C<BinaryString>. C<sha256> is
the portable baseline; hosts may also support C<sha384> and C<sha512>.

=item C<< Certificate.to_der() >>

Returns the original DER certificate bytes as a C<BinaryString>.

=item C<< Certificate.to_pem() >>

Returns canonical C<CERTIFICATE> PEM text.

=item C<< Certificate.public_key() >>

Returns a C<PublicKey> for supported certificate public-key algorithms.
Unsupported algorithms throw clearly.

=item C<< Certificate.verify_chain(Array chain, Dict options = {}) >>

Verifies an X.509 chain where the host supports chain verification.
C<chain[0]> is the leaf certificate; later entries are intermediates.
Trust roots are supplied through
C<options.roots>, which may be a C<Certificate>, PEM C<String>, C<Array>
of those values, or C<null>. C<options.use_system_roots> defaults to
C<false>; when true, CLI hosts also use the host system trust store.

C<options.hostname> may be a C<String> or C<null>. C<options.time> may
be a C<std/time> C<Time>, numeric epoch seconds, or C<null>; omitted or
null values use the current time.

The method returns a C<Dict> with C<valid>, C<reason>, C<error>,
C<hostname>, C<verified_at>, and C<chain_length>. Validation failures
return C<valid: false> with a stable reason such as C<untrusted-root>,
C<expired>, C<not-yet-valid>, C<hostname-mismatch>, or C<invalid-chain>.
Bad argument types throw.

=back

=head2 TLS Identities

TLS identity objects are parsed and inspected by C<std/secure> and can
be supplied to C<std/net/http> C<UserAgent> or C<Request> objects for
mutual-TLS client authentication. PEM certificate input may contain a
chain; the first certificate is treated as the leaf certificate. The
full chain is retained internally for HTTP TLS use, but this phase does
not expose a public chain accessor.

=over

=item C<< TlsIdentity.from_pem(String certificate_pem, String private_key_pem, String password = null) >>

Parses PEM identity material and returns a C<TlsIdentity>. C<password>
C<null> means an empty passphrase. Browser hosts accept PEM identities,
but the identity is inert for signing-key extraction.

=item C<< TlsIdentity.from_pkcs12(BinaryString bytes, String password = null) >>

Parses PKCS#12 identity material where supported. C<password> C<null>
means an empty passphrase.

=item C<< TlsIdentity.certificate() >>

Returns the leaf certificate as a C<Certificate>.

=item C<< TlsIdentity.private_key() >>

Returns a C<SigningKey> for supported private-key algorithms.
Unsupported key algorithms throw clearly.

=back

=head2 Secure Random

=over

=item C<< SecureRandom.bytes(Number length) >>

Returns a C<BinaryString> of exactly C<length> bytes from the host CSPRNG.
C<length> must be a non-negative integer.

=item C<< SecureRandom.token(Number bytes = 32) >>

Returns URL-safe Base64 text with no padding, generated from C<bytes>
random bytes. C<bytes> must be a non-negative integer.

=item C<< SecureRandom.int(Number max) >>

Returns a number in the range C<0> to C<max - 1>. C<max> must be a
positive integer no greater than C<2^53>. The implementation uses
rejection sampling to avoid modulo bias.

=back

=head2 Async Contract

Every supported asynchronous secure operation will expose an async method
on every runtime. Browser implementations may need async methods for Web
Crypto promises. CLI implementations may return already completed tasks
when an operation is naturally synchronous.

C<async_required> reports which areas need asynchronous APIs on the
current host. The keys are stable even before those areas are implemented.

=head1 COPYRIGHT AND LICENCE

B<< std/secure >> is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.

=cut