NAME

Crypt::NSS::X509::Certificate - NSS Certificate functions

SYNOPSIS

  use 5.10.1;
  use Perl6::Slurp;

  use Crypt::NSS::X509;

  my $cert = Crypt::NSS::X509::Certificate->new(slurp('derfile'));

  say $cert->subject();
  say $cert->issuer();

  my $valid = $cert->verify_cert();

  if ( ! $cert->match_name('www.testdomain') ) {
    # Domain does not match certificate information
    exit(1);
  }

ABSTRACT

Perl interface for the certificate access parts of the NSS API.

DESCRIPTION

This class gives access to most of the certificate handling functions of NSS. For information on how to load and initialize the NSS library, please refer to Crypt::NSS::X509.

FUNCTIONS

CONSTRUCTORS

new ( DERSTRING )

Creates a new NSS::Certificate object from the provided der-encoded certificate string.

The function croaks with the NSS error in case NSS cannot parse or import the certificate

new_from_pem ( STRING )

Creates a new NSS::Certificate object from the pem-encoded certificate string. Behaves exactly as new ( ).

new_from_nick ( STRING )

Creates a new NSS::Certificate object from the certificate database given a certificate nickname. Returns undef if no fitting certificate could be found.

ACCESSORS

subject

Returns the certificate subject as string.

issuer

Returns the certificate issuer as string.

serial

Returns the hex-encoded serial number of the certificate.

notBefore

Returns the not before time as a string.

notAfter

Returns the notAfter tine as a string.

subj_alt_name

Returns the certificate subject alternative name (if present). May croak if the extension field in the certificate is invalid.

version

Returns the certificate version number.

common_name

Returns the most specific common name specified in the certificate subject.

country_name

Returns the country name specified in the certificate subject.

business_category

Returns the business category of the certificate if present.

ev_incorporation_country

Returns the extended validation country if present.

ev_incorporation_locality

Returns the extended validation locality if present.

ev_incorporation_state

Returns the extended validation incorporation state if present.

extension_oids

Returns the oids of the present extension

locality

Locality given in certificate subject.

locality_name

Locality name given in certificate subject.

org_name

Organization name given in certificate subject.

org_unit_name

Organizational unit name given in certificate subject.

policy

Returns the certificate policy.

postal_code

Returns the postal code from the subject, if present.

state_name

Returns the name of the state from the subject if present.

street_address

Returns the street address from the subject is present.

subject_serial

Returns the serial from the subject. Note this does not necessarily have to be the same as the serial given outside the subject of the certificate.

is_root

Returns true if NSS thinks that the certificate is a root (selfsigned) certificate and false otherwise.

sig_alg_name

Returns the name of the signature algorithm.

key_alg_name

Returns the name of the encryption algorithm.

bit_length

Bit length of the certificate key

public_key

Hex representation of the public key of the certificate (also available under the name modulus, for historical reasons

modulus

Alias for public_key.

nickname

Return the NSS certificate nickname.

dbnickname

Return the NSS certificate database nickname.

raw_spki

Return the encoded subject public key info part of the certificate. Can be used for uniquely identifying a public key (after hashing).

exponent

RSA exponent of the public key of the certificate. Croaks, if the certificate does not contain an RSA key, so check first using key_alg_name.

curve

Name of the EC-curve used in the certificate. Croaks if the certificate is not an EC-certificate.

fingerprint_md5

Hex-encoded md5 fingerprint of the certificate

fingerprint_sha1

Hex-encoded sha1 fingerprint of the certificate

fingerprint_sha256

Hex-encoded sha256 fingerprint of the certificate

der

Return the der-encoded certificate

VERIFICATION FUNCTIONS

These functions allow verification of certificate chains. Please note that for most of them a database has to be used and a root-certificate list has to be loaded. See Crypt::NSS::X509.

There are several different verification functions, because the NSS library offers a variety of methods to validate certificates. You probably want to either use verify_certificate or verify_pkix.

match_name ( HOSTNAME )

Return true is NSS considers the hostname to be valid for the certificate. Returns false otherwise.

verify_certificate( [TIME], [USAGE] )

Returns 1 if the certificate can be validated up to a root-certificate. Otherwise returns the numeric NSS error code. Time can contain the unix timestamp of the verification time. Usage can contain a the certificate usage - usually certUsageSSLServer is assumed.

verify_cert ( [TIME], [USAGE] )

Same as verify_certificate, just using the verify_cert NSS function instead of the verify_certificate NSS function.

This is (basically) the verification function that is used by Firefox at the moment (they add a few more special checks in the Firefox codebase).

verify_certificate_pkix( [TIME], [USAGE] )

Same as verify_certificate, just using the PKIX library for validation by using CERT_SetUsePKIXForValidation.

verify_certificate_log( [TIME], [USAGE] )

Same verification as in verify_certificate; however this function returns an empty list in case of success. In case of error, a list of hashes is returned. The hash contains the certificate that generated the error and the error code.

This allows to see which certificate in a certificate chain was responsible for preventing the validation of the chain. If several errors occur, the list may contain several hashes with differing error codes.

verify_certificate_pkix_log( [TIME], [USAGE] )

Like verify_certificate_log, just using the PKIX library for validation by using CERT_SetUsePKIXForValidation.

verify_cert_log ( [TIME], [USAGE] )

Same as verify_certificate_log, just using the verify_cert NSS function instead of the verify_certificate NSS function.

verify_pkix ( [TIME], [USAGE], [TRUSTED CERT LIST )

Returns 1 if the certificate can be validated up to a root-certificate using the CERT_PKIXVerifyCert function. Otherwise returns the numeric NSS error code. This function is (basically) used by Chrome to validate certificates.

Trusted cert list can contain a NSS::CertList, of trusted certificates. Please note that it is not a good idea to just load all root-certificates into a NSS::CertList and try to validate using this function, without using a NSS database backend; chain validation does not work correctly in that case.

verify_pkix_aia ( [TIME], [USAGE], [TRUSTED CERT LIST )

Same as verify_pkix, but tries to retrieve missing intermediate certificates using the Authority Information Access (AIA) field in the certificate (if present).

get_cert_chain_from_cert( [TIME], [USAGE] )

Get a Crypt::NSS::X509::CertList containing the certificate chain up to a root-certificate for the current certificate.

AUTHOR

Johanna Amann, <johanna@icir.org>

COPYRIGHT AND LICENSE

Copyright 2012 by Johanna Amann

This Library Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

The library contains source code of the Mozilla Network Security Services; for NSS license information please see http://www.mozilla.org/projects/security/pki/ nss/.