X509(3p)

NAME
Crypt::OpenSSL::X509 - Perl extension to OpenSSL's X509 API.

SYNOPSIS
  use Crypt::OpenSSL::X509;

  my $x509 = Crypt::OpenSSL::X509->new_from_file('cert.pem');

  print $x509->pubkey() . "\n";
  print $x509->subject() . "\n";
  print $x509->hash() . "\n";
  print $x509->email() . "\n";
  print $x509->issuer() . "\n";
  print $x509->issuer_hash() . "\n";
  print $x509->notBefore() . "\n";
  print $x509->notAfter() . "\n";
  print $x509->modulus() . "\n";
  print $x509->exponent() . "\n";
  print $x509->fingerprint_md5() . "\n";
  print $x509->fingerprint_sha256() . "\n";
  print $x509->as_string() . "\n";

  my $x509 = Crypt::OpenSSL::X509->new_from_string(
    $der_encoded_data, Crypt::OpenSSL::X509::FORMAT_ASN1
  );

  # given a time offset of $seconds, will the certificate be valid?
  if ($x509->checkend($seconds)) {
    # cert is expired at $seconds offset
  } else {
    # cert is ok at $seconds offset
  }

  my $exts = $x509->extensions_by_oid();

  foreach my $oid (keys %$exts) {
    my $ext = $$exts{$oid};
    print $oid, " ", $ext->object()->name(), ": ", $ext->value(), "\n";
  }

ABSTRACT
  Crypt::OpenSSL::X509 - Perl extension to OpenSSL's X509 API.

DESCRIPTION
  This implement a large majority of OpenSSL's useful X509 API.

  The email() method supports both certificates where the
  subject is of the form:
  "... CN=Firstname lastname/emailAddress=user@domain", and also
  certificates where there is a X509v3 Extension of the form
  "X509v3 Subject Alternative Name: email=user@domain".

  SUPPORTED OPENSSL VERSIONS
This module supports multiple versions of OpenSSL and maintains backward compatibility:

OpenSSL 1.0.x - Legacy support (1.0.2 and later)
OpenSSL 1.1.x - Full support
OpenSSL 3.x - Full support (current stable)
OpenSSL 4.x - Full support (with ASN1 opaque structure compatibility)
LibreSSL 2.x/3.x - Compatible

OpenSSL 4.0.0 introduced opaque ASN1 string types, requiring the use of accessor functions instead of direct structure member access. This module uses conditional compilation to maintain compatibility across all versions while supporting the new OpenSSL 4.x API requirements.

  EXPORT
None by default.

On request:

        FORMAT_UNDEF FORMAT_ASN1 FORMAT_TEXT FORMAT_PEM
        FORMAT_PKCS12 FORMAT_SMIME FORMAT_ENGINE FORMAT_IISSGC

FUNCTIONS

  X509 CONSTRUCTORS

new ( )
    Create a new X509 object.

new_from_string ( STRING [ FORMAT ] )
new_from_file ( FILENAME [ FORMAT ] )
    Create a new X509 object from a string or file. "FORMAT" should be "FORMAT_ASN1" or "FORMAT_PEM".

  X509 ACCESSORS

subject
    Subject name as a string.

issuer
    Issuer name as a string.

issuer_hash
    Issuer name hash as a string.

serial
    Serial number as a string.

hash
    Alias for subject_hash

subject_hash
    Subject name hash as a string.

notBefore
    "notBefore" time as a string.

notAfter
    "notAfter" time as a string.

email
    Email addresses as string, if multiple addresses found, they are separated by a space (' ').

version
    Certificate version as a string.

sig_alg_name
    Signature algorithm name as a string.

key_alg_name
    Public key algorithm name as a string.

curve
    Name of the EC curve used in the public key.

  X509 METHODS

subject_name ( )
issuer_name ( )
    Return a Name object for the subject or issuer name. Methods for handling Name objects are given below.

is_selfsigned ( )
    Return Boolean value if subject and issuer name are the same.

as_string ( [ FORMAT ] )
    Return the certificate as a string in the specified format. "FORMAT" can be one of "FORMAT_PEM" (the default) or "FORMAT_ASN1".

modulus ( )
    Return the modulus for an RSA public key as a string of hex digits. For DSA and EC return the public key. Other algorithms are not supported.

bit_length ( )
    Return the length of the modulus as a number of bits.

fingerprint_md5 ( )
fingerprint_sha1 ( )
fingerprint_sha224 ( )
fingerprint_sha256 ( )
fingerprint_sha384 ( )
fingerprint_sha512 ( )
    Return the specified message digest for the certificate.

checkend( OFFSET )
    Given an offset in seconds, will the certificate be expired? Returns True if the certificate will be expired. False otherwise.

pubkey ( )
    Return the RSA, DSA, or EC public key.

num_extensions ( )
    Return the number of extensions in the certificate.

extension ( INDEX )
    Return the Extension specified by the integer "INDEX". Methods for handling Extension objects are given below.

extensions_by_oid ( )
extensions_by_name ( )
extensions_by_long_name ( )
    Return a hash of Extensions indexed by OID or name.

has_extension_oid ( OID )
    Return true if the certificate has the extension specified by "OID".

subjectaltname ( )
    Uses Convert::ASN1 to extract the Subject Alternative Names from the X509 object. subjectaltname ( ) returns an array of objects, each object representing a SAN.

    These could be of the following types (as defined in the embedded ASN.1 schema):

    •   rfc822Name — email address (IA5String)

    •   dNSName — DNS hostname (IA5String)

    •   x400Address — X.400 address (ANY)

    •   directoryName — Distinguished Name (RDNSequence)

    •   ediPartyName — EDI party name (EDIPartyName)

    •   uniformResourceIdentifier — URI (IA5String)

    •   iPAddress — IP address (OCTET STRING; 4 bytes IPv4, 16 bytes IPv6)

    •   registeredID — OID (OBJECT IDENTIFIER)

    Note: "otherName" (tag [0] in RFC 5280) is not implemented and will never appear in the output.

        [
            {
                'rfc822Name' => 'altuser@mpi-sws.org'
            },
            {
                'rfc822Name' => 'user@mpi-sws.org'
            },
        ]

  X509::Extension METHODS

critical ( )
    Return a value indicating if the extension is critical or not. FIXME: the value is an ASN.1 BOOLEAN value.

object ( )
    Return the ObjectID of the extension. Methods for handling ObjectID objects are given below.

value ( )
    Return the value of the extension as an asn1parse(1) style hex dump.

as_string ( )
    Return a human-readable version of the extension as formatted by X509V3_EXT_print. Note that this will return an empty string for OIDs with unknown ASN.1 encodings.

  X509::ObjectID METHODS

name ( )
    Return the long name of the object as a string.

oid ( )
    Return the numeric dot-separated form of the object identifier as a string.

  X509::Name METHODS

as_string ( )
    Return a string representation of the Name

entries ( )
    Return an array of Name_Entry objects. Methods for handling Name_Entry objects are given below.

has_entry ( TYPE [ LASTPOS ] )
has_long_entry ( TYPE [ LASTPOS ] )
has_oid_entry ( TYPE [ LASTPOS ] )
    Return true if a name has an entry of the specified "TYPE". Depending on the function the "TYPE" may be in the short form (e.g. "CN"), long form ("commonName") or OID (2.5.4.3). If "LASTPOS" is specified then the search is made from that index rather than from the start.

get_index_by_type ( TYPE [ LASTPOS ] )
get_index_by_long_type ( TYPE [ LASTPOS ] )
get_index_by_oid_type ( TYPE [ LASTPOS ] )
    Return the index of an entry of the specified "TYPE" in a name. Depending on the function the "TYPE" may be in the short form (e.g. "CN"), long form ("commonName") or OID (2.5.4.3). If "LASTPOS" is specified then the search is made from that index rather than from the start.

get_entry_by_type ( TYPE [ LASTPOS ] )
get_entry_by_long_type ( TYPE [ LASTPOS ] )
    These methods work similarly to get_index_by_* but return the Name_Entry rather than the index.

  X509::Name_Entry METHODS

as_string ( [ LONG ] )
    Return a string representation of the Name_Entry of the form "typeName=Value". If "LONG" is 1, the long form of the type is used.

type ( [ LONG ] )
    Return a string representation of the type of the Name_Entry. If "LONG" is 1, the long form of the type is used.

value ( )
    Return a string representation of the value of the Name_Entry.

is_printableString ( )
is_ia5string ( )
is_utf8string ( )
is_asn1_type ( [ASN1_TYPE] )
    Return true if the Name_Entry value is of the specified type. The value of "ASN1_TYPE" should be as listed in OpenSSL's "asn1.h".

ISSUE REPORTING
Please report any bugs or feature requests using GitHub.

•   GitHub Issues <https://github.com/dsully/perl-crypt-openssl-x509/issues>

SEE ALSO

•   OpenSSL website <https://www.openssl.org/>

•   Crypt::OpenSSL::RSA <https://metacpan.org/pod/Crypt::OpenSSL::RSA>

•   Crypt::OpenSSL::Bignum <https://metacpan.org/pod/Crypt::OpenSSL::Bignum>

•   Crypt::OpenSSL::Guess <https://metacpan.org/pod/Crypt::OpenSSL::Guess>

AUTHOR

•   Dan Sully, original author

•   Jonas Brømsø, current maintainer

•   Please see the "ACKNOWLEDGEMENTS" section for a list of contributors.

ACKNOWLEDGEMENTS
In alphabetical order.

•   @eserte

•   @kmx

•   @stphnlyd

•   Ashley Hindmarsh @bestscarper

•   Bernhard M. Wiedemann @bmwiedemann

•   Brad Davidson @brandond

•   Daniel Kahn Gillmor

•   Daniel Risacher

•   David O'Callaghan

•   David Steinbrunner @dsteinbrunner

•   dsteinwand

•   Florian Schlichting @fschlich

•   IKEDA Soji @ikedas

•   James Hunt @jhunt

•   James Rouzier @jrouzierinverse

•   Johanna @0xxon

•   Jonas Brømsø @jonasbn

•   Louise Doran

•   Michael McClimon @mmcclimon

•   Michal Josef Špaček @michal-josef-spacek

•   Neil Bowers @neilb

•   Nicholas Harteau

•   Otmar Lendl

•   Patrick C. @errror

•   Patrick Cernko

•   Petr Pisar @ppisar

•   pi-rho

•   Salvador Fandiño @salva

•   Sebastian Andrzej Siewior

•   Sho Nakatani @laysakura

•   Shoichi Kaji @skaji

•   Timothy Legge @timlegge

•   Todd Rinaldo @toddr

•   Uli Scholler

COPYRIGHT AND LICENSE
Copyright 2004 by Dan Sully

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