This file is automatically generated by pod2readme from PKCS10.pm and Changes.

NAME
    Crypt::PKCS10 - parse PKCS #10 certificate requests

RELEASE NOTES
    Version 1.4 has several API changes. Most users should have a painless
    migration.

    ALL users must call Crypt::PKCS10->setAPIversion. If not, a warning will
    be generated by the first class method called. This warning will be made
    a fatal exception in a future release.

    Other than that requirement, the legacy mode is compatible with previous
    versions.

    Users are encouraged to migrate to the version 1 API. It is much easier
    to use, and does not require the application to navigate internal data
    structures.

INSTALLATION
    To install this module type the following:
           perl Makefile.PL
           make
           make test
           make install

REQUIRES
    Convert::ASN1

SYNOPSIS
        use Crypt::PKCS10;

        Crypt::PKCS10->setAPIversion( 1 );
        my $decoded = Crypt::PKCS10->new( $csr );

        my @names;
        @names = $decoded->extensionValue('subjectAltName' );
        @names = $decoded->subject unless( @names );

        my %extensions = map { $_ => $decoded->extensionValue( $_ ) } $decoded->extensions

DESCRIPTION
    Crypt::PKCS10 parses PKCS #10 certificate requests (CSRs) and provides
    accessor methods to extract the data in usable form.

    Common object identifiers will be translated to their corresponding
    names. Additionally, accessor methods allow extraction of single data
    fields. Bit Strings like signatures will be returned in their
    hexadecimal representation.

    The access methods return the value corresponding to their name. If
    called in scalar context, they return the first value (or an empty
    string). If called in array context, they return all values.

METHODS
    Access methods may exist for subject name components that are not listed
    here. To test for these, use code of the form:

      $locality = $decoded->localityName if( $decoded->can('localityName') );

    If a name component exists in a CSR, the method will be present. The
    converse is not (always) true.

  class method setAPIversion( $version )
    Selects the API version expected.

    Must be called before calling any other method.

    o   Version 0 = Some OID names have spaces and descriptions - DEPRECATED

        This is the format used for Crypt::PKCS10 version 1.3 and lower. The
        attributes method returns legacy data.

    o   Version 1 = OID names from RFCs - or at least compatible with
        OpenSSL and ASN.1 notation. The attributes method conforms to
        version 1.

    If not called, a warning will be generated and the API will default to
    version 0.

    In a future release, the warning will be changed to a fatal exception.

    To ease migration, both old and new names are accepted by the API.

    Every program should call setAPIversion(1).

  class method new
    Constructor, creates a new object containing the parsed PKCS #10 request
    It takes the request itself as an argument. PEM and DER encoding is
    supported.

    If PEM, other data (such as mail headers) may precede or follow the CSR.

        my $decoded = Crypt::PKCS10->new( $csr );

  class method name2oid( $oid )
    Returns the OID corresponding to a name returned by an access method.

    Not in API v0;

  csrRequest( $format )
    Returns the binary (ASN.1) request (after conversion from PEM and
    removal of any data beyond the length of the ASN.1 structure.

    If $format is true, the request is returned as a PEM CSR. Otherwise as a
    binary string.

  Access methods for the subject's distinguished name
    Note that subjectAltName is prefered, and modern certificate users will
    ignore the subject if subjectAltName is present.

    subject(format)
    Returns the entire subject of the CSR.

    In scalar context, returns the subject as a string in the form
    /componentName=value,value. If format is true, long component names are
    used. By default, abbreviations are used when known.

      e.g. /countryName=AU/organizationalUnitName=Big org/organizationalUnitName=Smaller org
      or     /C=AU/OU=Big org/OU=Smaller org

    In array context, returns an array of (componentName, [values]) pairs.
    Abbreviations are not used.

    Note that the order of components in a name is significant.

    commonName
    Returns the common name(s) from the subject.

        my $cn = $decoded->commonName();

    organizationalUnitName
    Returns the organizational unit name(s) from the subject

    organizationName
    Returns the organization name(s) from the subject.

    emailAddress
    Returns the email address from the subject.

    stateOrProvinceName
    Returns the state or province name(s) from the subject.

  countryName
    Returns the country name(s) from the subject.

  subjectAltName($type)
    Convenience method.

    When $type is specified: returns the subject alternate name values of
    the specified type in list context, or the first value of the specified
    type in scalar context.

    Returns undefined/empty list if no values of the specified type are
    present, or if the subjectAltName extension is not present.

    Types can be any of:

       otherName
     * rfc822Name
     * dNSName
       x400Address
       directoryName
       ediPartyName
     * uniformResourceIdentifier
     * iPAddress
     * registeredID

    The types marked with '*' are the most common.

    If $type is not specified: In list context returns the types present in
    the subjectAlternate name. In scalar context, returns the SAN as a
    string.

  version
    Returns the structure version as a string, e.g. "v1" "v2", or "v3"

  pkAlgorithm
    Returns the public key algorithm according to its object identifier.

  subjectPublicKey( $format )
    If $format is true, the public key will be returned in PEM format.

    Otherwise, the public key will be returned in its hexadecimal
    representation

  signatureAlgorithm
    Returns the signature algorithm according to its object identifier.

  signature
    The signature will be returned in its hexadecimal representation

  attributes( $name )
    A request may contain a set of attributes. The attributes are OIDs with
    values. The most common is a list of requested extensions, but other
    OIDs can also occur. Of those, challengePassword is typical.

    For API version 0, this method returns a hash consisting of all
    attributes in an internal format. This usage is deprecated.

    For API version 1:

    If $name is not specified, a list of attribute names is returned. The
    list does not include the requestedExtensions attribute. For that, use
    extensions();

    If no attributes are present, the empty list (undef in scalar context)
    is returned.

    If $name is specified, the value of the extension is returned. (Only
    string values are currently supported.) In scalar context, a single
    string is returned with multiple values separated by ',' or '+'. In
    array context, the value(s) are returned.

     print "$_: ", scalar $decoded->attributes($_), "\n"
                                         foreach ($decoded->attributes);

  extensions
    Returns an array containing the names of all extensions present in the
    CSR. If no extensions are present, the empty list is returned.

    The names vary depending on the API version; however, the returned names
    are acceptable to extensionValue and extensionPresent.

    The values of extensions vary, however the following code fragment will
    dump most extensions and their value(s).

     foreach my $ext ($decoded->extensions) {
         my $val = $decoded->extensionValue($ext);
         $val = join( ',', map { ref $_ eq 'HASH'?
                      join( ':', (keys %$_)[0], (values %$_)[0] ): $_} @$val )
                if( ref $val eq 'ARRAY' );
         print( "$ext: ", $val, "\n" );
     }

    The sample code fragment is not guaranteed to handle all cases.
    Realistic code needs to select the extensions that it understands.

  extensionValue
    Returns the value of an extension by name, e.g. extensionValue(
    'keyUsage' ). The name SHOULD be an API v1 name, but API v0 names are
    accepted for compatibility.

    To interpret the value, you need to know the structure of the OID.

    Depending on the extension, the value may be a string, an array of
    strings, or an array of hashes.

  extensionPresent
    Returns true if a named extension is present: If the extension is
    'critical', returns 2. Otherwise, returns 1, indicating 'not critical',
    but present.

    If the extension is not present, returns undef.

    See the module documentation for a list of known OID names.

  registerOID
    Class method.

    Register a custom OID, or a public OID that has not been added to
    Crypt::PKCS10 yet.

    The OID may be an extension identifier or an RDN component.

    The oid is specified as a string in numeric form, e.g. '1.2.3.4'

    registerOID( $oid )
    Returns true if the specified OID is registered, false otherwise.

    registerOID( $oid, $longname, $shortname )
    Registers the specified OID with the associated long name. The long name
    should be Hungarian case (commonName), but this is not currently
    enforced.

    Optionally, specify the short name used for extracting the subject. The
    short name should be upper-case (and will be upcased).

    E.g. built-in are $oid => '2.4.5.3', $longname => 'commonName',
    $shortname => 'CN'

    Generates an exception if any argument is not valid, or is in use.

    Returns true otherwise.

  certificateTemplate
    CertificateTemplate is an attribute widely used by Windows certification
    authorities.

CHANGES
    1.0 2014-08-20
    
     - Initial Version
    
    1.1 2015-10-09
    
     - Allow same OID elements in RDNs
         - Support for all DirectoryStrings
         - New accessor method: organizationName 
    
    1.2 2015-11-13
    
     - Add generic method extensionValue
         - Ommit unknown or damaged extensions
    
    1.3 2015-11-17
    
     - Experimental Perl features removed
         - Refactored building process
    
    1.4_01 2016-01-14
    
    - Find PEM anywhere
        - Support repeated attributes
        - Various crashes, internal optimizations
        - More OIDs
        - Access methods: subject, subjectAltName, extensions
        - Generate access methods for unknown OIDs in DNs at runtime
        - Add extractCSR method to get CSR in binary or PEM
        - subjectPublicKey option to extract in PEM format
        - Convert IP addresses to strings
        - Convert basicConstraints to string
        - Add registerOID to allow extraction of simple custom OIDs
        - More tests
        - Improve documentation
        - Add setAPIversion, regularize OID names in V1
        - For API V1, attributes method returns names or values of attributes (except extensions)
        - Improve build: Use Dist::Zilla, autogenerate README,LICENE,META,Makefile.PL
        - Generate & ship Commitlog from git
    
    1.4_02
    
    - For API V1, omit space in key usage list
        - Look for policy identifier names in all tables
        - Decode certificatePolicyIdentifier, add related OIDs
        - Avoid building un-necessary ASN.1 parsers
        - Fully decode ApplicationCertPolicies for API V1
        - Check enhanced key usage before registering OID
        - Add name2oid to API
        - Internal cleanup  & error reporting improvements

    For detailed change listing, see Commitlog.

AUTHORS
    Gideon Knocke

    Timothe Litt made most of the changes for V1.4

    Crypt::PKCS10 is based on the generic ASN.1 module by Graham Barr and on
    the x509decode example by Norbert Klasen. It is also based upon the
    works of Duncan Segrest's Crypt-X509-CRL module.

COPYRIGHT
    This software is copyright (c) 2014 by Gideon Knocke.

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

    Terms of the Perl programming language system itself

    a) the GNU General Public License as published by the Free Software
    Foundation; either version 1, or (at your option) any later version, or

    b) the "Artistic License"

