Crypt::X509(3pm)

📦
version 0.55 · 9 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Crypt::X509 — the manual page (this is Crypt::X509(3pm), from the User Contributed Perl Documentation, bestie 💅)

✨ NAME ✨

Crypt::X509 — parse an X.509 certificate. That's it, that's the whole job. 🎀

🎀 SYNOPSIS 🎀

use Crypt::X509;

$decoded = Crypt::X509->new( cert => $cert );

$subject_email = $decoded->subject_email;
print "do not use after: ".gmtime($decoded->not_after)." GMT\n";

🌸 REQUIRES 🌸

  • Convert::ASN1 — yeah she needs it, don't @ me.

🦋 DESCRIPTION 🦋

Crypt::X509 parses X.509 certificates, and the methods give you access to most of the certificate elements. Not all — most. Read the fine print, babes. 💖

It's built on the generic ASN.1 module by Graham Barr, on the x509decode example by Norbert Klasen, and on contributions on the perl-ldap-dev Mailinglist by Chriss Ridd. Iconic lineage honestly, we love a collaborative origin story. 👑

💜 CONSTRUCTOR 💜

🍓 new ( OPTIONS )

Creates and returns a parsed X.509 certificate hash, containing all the parsed contents. The data is organised as specified in RFC 2459. By default only the first ASN.1 Layer is decoded — the nested decoding happens automagically through the data access methods. No cap, it just does it for you. ✨

  • cert => $certificate — a variable holding the DER formatted certificate you wanna parse (e.g. as stored in the "usercertificate;binary" attribute in an LDAP-directory).
use Crypt::X509;
use Data::Dumper;

$decoded= Crypt::X509->new(cert => $cert);

print Dumper($decoded);

💅 METHODS 💅

🔥 error

Returns the last error from parsing, and undef when no error occured. Heads up: this error gets updated on deeper parsing with the data access methods, so check it after you've poked at stuff. 👀

$decoded= Crypt::X509->new(cert => $cert);
if ($decoded->error) {
  warn "Error on parsing Certificate:".$decoded->error;
}

👑 DATA ACCESS METHODS 👑

You can access all the parsed data directly from the returned hash — it's all just sitting there. But for convenience the following methods have been implemented to give quick access to the most-used certificate attributes. 💖

🦋 version

Returns the certificate's version as an integer. NOTE that version is defined as an Integer where 0 = v1, 1 = v2, and 2 = v3. Yes it's off-by-one from what you'd expect, no we're not mad about it, that's just how it is. 😭

🌈 version_string

Returns the certificate's version as a string value.

⭐ serial

returns the serial number (integer or Math::BigInt Object, that gets automagic evaluated in scalar context) from the certificate. 🫶

$decoded= Crypt::X509->new(cert => $cert);
print "Certificate has serial number:".$decoded->serial."\n";

🧚 not_before

returns the GMT-timestamp of the certificate's beginning date of validity. If the Certificate holds this Entry in utcTime, it is guaranteed by the RFC to been correct. ✅

As utcTime is limited to 32-bit values (like unix-timestamps), newer certificates hold the timesamps as "generalTime"-entries. The contents of "generalTime"-entries are not well defined in the RFC and are returned by this module unmodified, if no utcTime-entry is found. So like, don't assume anything about those ones. 😬

$decoded= Crypt::X509->new(cert => $cert);
if ($decoded->notBefore < time()) {
  warn "Certificate: not yet valid!";
}

🎀 not_after

returns the GMT-timestamp of the certificate's ending date of validity. If the Certificate holds this Entry in utcTime, it is guaranteed by the RFC to been correct. ✅

As utcTime is limited to 32-bit values (like unix-timestamps), newer certificates hold the timesamps as "generalTime"-entries. The contents of "generalTime"-entries are not well defined in the RFC and are returned by this module unmodified, if no utcTime-entry is found. Same disclaimer, same energy. 💀

$decoded= Crypt::X509->new(cert => $cert);
print "Certificate expires on ".gmtime($decoded->not_after)." GMT\n";

💜 signature

Return's the certificate's signature in binary DER format. (Yes, the apostrophe is doing its own thing here, we don't edit the ancestors.) 🙈

🔥 pubkey

Returns the certificate's public key in binary DER format.

🌸 pubkey_size

Returns the certificate's public key size.

✨ pubkey_algorithm

Returns the algorithm as an OID string which the public key was created with.

👑 PubKeyAlg

returns the subject public key encryption algorithm (e.g. 'RSA') as a string. 🎉

$decoded= Crypt::X509->new(cert => $cert);
print "Certificate public key is encrypted with:".$decoded->PubKeyAlg."\n";

Example Output: Certificate public key is encrypted with: RSA

🦋 pubkey_components

If this certificate contains an RSA key, this function returns a hashref { modulus => $m, exponent => $e) from that key; each value in the hash will be an integer scalar or a Math::BigInt object. (Note the curly-paren situation — that's verbatim, bestie. 💀)

For other pubkey types, it returns undef — and yeah: (implementations welcome!) 👀✨

💅 sig_algorithm

Returns the certificate's signature algorithm as an OID string. 💖

$decoded= Crypt::X509->new(cert => $cert);
print "Certificate signature is encrypted with:".$decoded->sig_algorithm."\n";>

Example Output: Certificate signature is encrypted with: 1.2.840.113549.1.1.5

🌈 SigEncAlg

returns the signature encryption algorithm (e.g. 'RSA') as a string. 🎀

$decoded= Crypt::X509->new(cert => $cert);
print "Certificate signature is encrypted with:".$decoded->SigEncAlg."\n";

Example Output: Certificate signature is encrypted with: RSA

⭐ SigHashAlg

returns the signature hashing algorithm (e.g. 'SHA1') as a string. ✨

$decoded= Crypt::X509->new(cert => $cert);
print "Certificate signature is hashed with:".$decoded->SigHashAlg."\n";

Example Output: Certificate signature is encrypted with: SHA1

🧚 Subject

returns a pointer to an array of strings containing subject nameparts of the certificate. Attributenames for the most common Attributes are translated from the OID-Numbers, unknown numbers are output verbatim. 🫶

$decoded= Convert::ASN1::X509->new($cert);
print "DN for this Certificate is:".join(',',@{$decoded->Subject})."\n";

🎀 SubjectRaw

Returns the RDNs as a list of hashes; values are stringified but the OIDs are not translated.

If a component contains a SET, the component will become an array of hashes on the second level. Nested situation. 💅

💜 SubjectSequence

Returns the subject as returned from the ASN1 parser. Raw and unfiltered, main character energy. 👑

🌸 subject_country

Returns the string value for subject's country (= the value with the OID 2.5.4.6 or in DN Syntax everything after "C="). Only the first entry is returned. undef if subject contains no country attribute. 🗺️

✨ subject_locality

Returns the string value for subject's locality (= the value with the OID 2.5.4.7 or in DN Syntax everything after "l="). Only the first entry is returned. undef if subject contains no locality attribute. 🏘️

🔥 subject_state

Returns the string value for subject's state or province (= the value with the OID 2.5.4.8 or in DN Syntax everything after "S="). Only the first entry is returned. undef if subject contains no state attribute. 🌎

👑 subject_org

Returns the string value for subject's organization (= the value with the OID 2.5.4.10 or in DN Syntax everything after "O="). Only the first entry is returned. undef if subject contains no organization attribute. 🏢

🦋 subject_ou

Returns the string value for subject's organizational unit (= the value with the OID 2.5.4.11 or in DN Syntax everything after "OU="). Only the first entry is returned. undef if subject contains no organization attribute. 🧩

💅 subject_cn

Returns the string value for subject's common name (= the value with the OID 2.5.4.3 or in DN Syntax everything after "CN="). Only the first entry is returned. undef if subject contains no common name attribute. 🌟

🌈 subject_email

Returns the string value for subject's email address (= the value with the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "emailAddress="). Only the first entry is returned. undef if subject contains no email attribute. 📧

⭐ Issuer

returns a pointer to an array of strings building the DN of the certificate issuer (= the DN of the CA). Attributenames for the most common Attributes are translated from the OID-Numbers, unknown numbers are output verbatim. 🏛️

$decoded= Crypt::X509->new($cert);
print "Certificate was issued by:".join(',',@{$decoded->Issuer})."\n";

🧚 issuer_cn

Returns the string value for issuer's common name (= the value with the OID 2.5.4.3 or in DN Syntax everything after "CN="). Only the first entry is returned. undef if issuer contains no common name attribute. 💖

🎀 issuer_country

Returns the string value for issuer's country (= the value with the OID 2.5.4.6 or in DN Syntax everything after "C="). Only the first entry is returned. undef if issuer contains no country attribute. 🗺️

💜 issuer_state

Returns the string value for issuer's state or province (= the value with the OID 2.5.4.8 or in DN Syntax everything after "S="). Only the first entry is returned. undef if issuer contains no state attribute. 🌎

🌸 issuer_locality

Returns the string value for issuer's locality (= the value with the OID 2.5.4.7 or in DN Syntax everything after "L="). Only the first entry is returned. undef if issuer contains no locality attribute. 🏘️

✨ issuer_org

Returns the string value for issuer's organization (= the value with the OID 2.5.4.10 or in DN Syntax everything after "O="). Only the first entry is returned. undef if issuer contains no organization attribute. 🏢

🔥 issuer_email

Returns the string value for issuer's email address (= the value with the OID 1.2.840.113549.1.9.1 or in DN Syntax everything after "E="). Only the first entry is returned. undef if issuer contains no email attribute. 📧

👑 KeyUsage

returns a pointer to an array of strings describing the valid Usages for this certificate. undef is returned, when the extension is not set in the certificate.

If the extension is marked critical, this is also reported. ⚠️

$decoded= Crypt::X509->new(cert => $cert);
print "Allowed usages for this Certificate are:\n".join("\n",@{$decoded->KeyUsage})."\n";

Example Output:
Allowed usages for this Certificate are:
critical
digitalSignature
keyEncipherment
dataEncipherment

🦋 ExtKeyUsage

returns a pointer to an array of ExtKeyUsage strings (or OIDs for unknown OIDs) or undef if the extension is not filled. OIDs of the following ExtKeyUsages are known: serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, OCSPSigning. Slay. 💅

If the extension is marked critical, this is also reported. ⚠️

$decoded= Crypt::X509->new(cert => $cert);
print "ExtKeyUsage extension of this Certificates is: ", join(", ", @{$decoded->ExtKeyUsage}), "\n";

Example Output: ExtKeyUsage extension of this Certificates is: critical, serverAuth

💅 SubjectAltName

returns a pointer to an array of strings containing alternative Subjectnames or undef if the extension is not filled. Usually this Extension holds the e-Mail address for person-certificates or DNS-Names for server certificates. 🖥️📧

It also pre-pends the field type (ie rfc822Name) to the returned value. 🏷️

$decoded= Crypt::X509->new(cert => $cert);
print "E-Mail or Hostnames in this Certificates is/are:", join(", ", @{$decoded->SubjectAltName}), "\n";

Example Output: E-Mail or Hostnames in this Certificates is/are: rfc822Name=user@server.com

🌈 DecodedSubjectAltNames

Returns a pointer to an array of strings containing all the alternative subject name extensions. The whole collection, no crumbs left. ✨

Okay so bestie, each of these extensions is represented as a decoded ASN.1 value — basically a pointer to a list of pointers to objects. Every object has exactly one key, which is the type of the alternative name, and a value that’s specific to that type. It’s giving very structured, very demure. ✨

[
  [
    {
      'directoryName' => {
        'rdnSequence' => [
          [
            {
              'value' => { 'utf8String' => 'example' },
              'type' => '2.5.4.3'
            }
          ]
        ]
      }
    },
    {
      'dNSName' => 'example.com'
    }
  ]
]

authorityCertIssuer 🎀

Returns a pointer to an array of strings that builds the DN of the Authority Cert Issuer. Attribute names for the most common Attributes are translated from the OID-Numbers; unknown numbers are output verbatim. If the extension is not set in the certificate, you get undef. No cap.

$decoded= Crypt::X509->new($cert);
print "Certificate was authorised by:".join(',',@{$decoded->authorityCertIssuer})."\n";

authority_serial 🔢

Returns the authority's certificate serial number. That’s it. Iconic.

key_identifier 🗝️

Returns the authority key identifier — or undef if it is a rooted cert. Rooted certs said “no identifier for me.” 💅

authority_cn 👑

Returns the authority's ca. Lowercase, exactly as written. We don’t question the vibe.

authority_country 🌍

Returns the authority's country.

authority_state 📍

Returns the authority's state.

authority_locality 🏙️

Returns the authority's locality.

authority_org 🏢

Returns the authority's organization.

authority_email 📧

Returns the authority's email.

CRLDistributionPoints 📜

Returns the CRL distribution points as an array of strings — usually with one value.

CRLDistributionPoints2 📚

Returns the CRL distribution points as an array of hashes, allowing for some variations. Flexible, bestie.

CertificatePolicies 📋

Returns the CertificatePolicies as an array of strings.

EntrustVersionInfo 🏷️

Returns the EntrustVersion as a string.

print "Entrust Version: ", $decoded->EntrustVersion, "\n";

Example Output: Entrust Version: V7.0

SubjectDirectoryAttributes 📂

Returns the SubjectDirectoryAttributes as an array of key = value pairs, and it includes a data type.

print "Subject Directory Attributes: ", join( ', ' , @{ $decoded->SubjectDirectoryAttributes } ), "\n";

Example Output: Subject Directory Attributes: 1.2.840.113533.7.68.29 = 7 (integer)

BasicConstraints 🚧

Returns the BasicConstraints as an array, and the criticallity is pre-pended. (Yes, that spelling is iconic — we keep it exactly.) 👑

subject_keyidentifier 🔑

Returns the subject key identifier from the extensions.

SubjectInfoAccess 🕵️

Returns the SubjectInfoAccess as an array of hashes with key=value pairs.

print "Subject Info Access: ";
if ( defined $decoded->SubjectInfoAccess ) {
    my %SIA = $decoded->SubjectInfoAccess;
    for my $key ( keys %SIA ) {
        print "\n\t$key: \n\t";
        print join( "\n\t" , @{ $SIA{$key} } ), "\n";
    }
} else { print "\n" }

Example Output:
    Subject Info Access:
        1.3.6.1.5.5.7.48.5:
        uniformResourceIdentifier = http://pki.treas.gov/root_sia.p7c
        uniformResourceIdentifier = ldap://ldap.treas.gov/ou=US%20Treasury%20Root%20CA,ou=Certification%20Authorities,ou=Department%20of%20the%20Treasury,o=U.S.%20Government,c=US?cACertificate;binary,crossCertificatePair;binary

PGPExtension 🐧

Returns the creation timestamp of the corresponding OpenPGP key. (see http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html)

print "PGPExtension: ";
if ( defined $decoded->PGPExtension ) {
    my $creationtime = $decoded->PGPExtension;
    printf "\n\tcorresponding OpenPGP Creation Time: ", $creationtime, "\n";
        }

Example Output:
    PGPExtension:
                whatever

👀 SEE ALSO 👀

See the examples of "Convert::ASN1" and the <perl-ldap@perl.org> Mailing List. An example on how to load certificates can be found in t\Crypt-X509.t.

💖 ACKNOWLEDGEMENTS 💖

This module is based on the x509decode script, which was contributed to Convert::ASN1 in 2002 by Norbert Klasen. Giving credit where it’s due, periodt. 💖

✨ AUTHORS ✨

Mike Jackson <mj@sci.fi>, Alexander Jung <alexander.w.jung@gmail.com>, Duncan Segrest <duncan@gigageek.info> Oliver Welter <owelter@whiterabbitsecurity.com>

Copyright (c) 2005 Mike Jackson <mj@sci.fi>. Copyright (c) 2001-2002 Norbert Klasen, DAASI International GmbH.

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This page is from perl v5.36.0, dated 2023-01-15, and it’s Crypt::X509(3pm). Bye bestie, slay! 💅✨

📦 where this page comes from