The manakai project

Web::Transport::PKI::Generator

Factory methods of PKIX objects

DESCRIPTION

The Web::Transport::PKI::Generator module has factory methods to create various PKIX related objects.

METHODS

There are following methods:

$gen = Web::Transport::PKI::Generator->new

Create a new instance of the generator.

$gen->create_rsa_key ($name => $value, ...)->then (sub { $rsa = shift })

Create a new RSA key pair, using OpenSSL via Net::SSLeay. The Web::Transport::PKI::RSAKey object representing the created key is returned.

Following option can be specified as name/value pair:

bits => $int (Default: auto)

The bit length of the created key, as an integer. In this version, the default is 2048.

$gen->create_ec_key ($name => $value, ...)->then (sub { $ec = shift })

Create a new EC key pair, using OpenSSL via Net::SSLeay. The Web::Transport::PKI::ECKey object representing the created key is returned.

Following option can be specified as name/value pair:

curve => $string (Default: auto)

The curve of the created key. Either prime256v1, secp384r1, or secp521r1. In this version, the default is prime256v1.

$gen->create_certificate ($name => $value, ...)->then (sub { $cert = shift })

Create a new X.509 certificate, using OpenSSL via Net::SSLeay. The Web::Transport::PKI::Certificate object representing the created certificate is returned.

Following options can be specified as name/value pairs:

version => $int? (Default: 2)

The version of the certifcate. The value must be one of 0 (v1), 1 (v2), or 2 (v3).

serial_number => $bigint? (Default: 0)

The serial number of the certificate. The value must be an integer or a Math::BigInt object.

not_before => $dt (Required)

The not before of the validity of the certificate. The value must be a Unix time number or a Web::DateTime object. Any fractional part of the second of the time is ignored.

not_after => $dt (Required)

The not after of the validity of the certificate. The value must be a Unix time number or a Web::DateTime object. Any fractional part of the second of the time is ignored.

issuer => $name (Required if root CA)

The issuer of the certificate. The value must be a value that is valid as the argument to the create method of the Web::Transport::PKI::Name class. Defaulted to the ca_cert's subject.

subject => $name (Required)

The subject of the certificate. The value must be a value that is valid as the argument to the create method of the Web::Transport::PKI::Name class.

san_hosts => [$value1, $value2, ...]

The subject alternative names of the certificate. The value, if specified, must be an array reference of hosts.

A host can be represented in two forms: If a character string is specified, it is interpreted as a dNSName, i.e. a domain or a wildcard domain, serialized in ASCII (A-labels). If a Web::Host object is specified, it is interpreted as a dNSName or an iPAddress depending on its is_domain and is_ip method values.

ca => $boolean

If true, certificate fields are configured for typical CA certificates.

ee => $boolean

If true, certificate fields are configured for typical EE certificates.

path_len_constraint => $integer?

The pathLenConstraint value of the basic constraints extension of the certificate, if any, or undef.

crl_urls => [$string1, $string2, ...]

The CRL distribution point URLs of the certificate. If specified, the value must be an array reference of character strings representing the URLs.

aia_ocsp_url => $string?

The OCSP URL of the Authority Information Access extension of the certificate as a character string, if any, or undef.

aia_ca_issuers_url => $string?

The CA issuers URL of the Authority Information Access extension of the certificate as a character string, if any, or undef.

dv => $boolean

Whether it is a DV certificate or not.

ov => $boolean

Whether it is an OV certificate or not.

ev => $string?

The OID of the EV CA's certification policy in the dotted notaion, if it is an EV certificate. If the EV OID is specified, the certification policy identifier of EV is also added as well as the EV OID.

policy_oids => [$string1, $string2, ...]

The additional policy identifiers of the certifciation policy extension of the certificate, as an array reference of OIDs in the dotted notation.

cps_url => $string?

The CPS URL specified as a policy qualifer of a certifciation policy of the certificate as a character string, if any, or undef. If this option is specified but there is no other option specifying a certification policy OID, the anyPolicy OID is added.

policy_user_notice_text => $string?

The display text of the user notice of a policy qualifier of a certification policy of the certifcate as a character string, if any, or undef. If this option is specified but there is no other option specifying a certification policy OID, the anyPolicy OID is added.

name_constraints_permitted => [$item1, $item2, ...]
name_constraints_excluded => [$item1, $item2, ...]

The host ranges in the certifciate's name constraints extension's permitted or excluded subtrees, if any.

A host range can be represented in three forms: If a character string is specified, it is interpreted as a dNSName, i.e. a domain or a . character followed by a domain, serialized in ASCII (A-labels). If a Web::Host object is specified, it is interpreted as a dNSName or an iPAddress depending on its is_domain and is_ip method values. If it is an IP address, the CIDR address range (subnet mask) is set to the full length of the address. If an array reference which has exactly two Web::Host objects whose is_ipv4 are true or whose is_ipv6 are true, the zeroth item is interpreted as an iPAddress's IP address and the first item is interpreted as an iPAddress's CIDR address range (subnet mask).

must_staple => $boolean

Whether the must-staple flag in the TLS feature extension of the certificate is set or not.

digest => $string (Default: auto)

The certificate's signature's digest algorithm. The value must be one of: sha1, sha256, or sha384. In this version, the default is sha256.

ca_rsa => $rsa (Required)
ca_ec => $ec (Required)

The RSA or EC key of the CA that signs the certificate. The value must be a Web::Transport::PKI::RSAKey object. The value can be same as rsa or ec when this is a root CA. Exactly one of ca_rsa and ca_ec must be specified.

ca_cert => $cert (Required unless root CA)

The certificate (a Web::Transport::PKI::Certificate object) of the CA that signs the certificate. This option can be omitted if this is a root CA certificate and rsa's value is equal to ca_rsa's value.

rsa => $rsa (Required)
ec => $ec (Required)

The RSA key of the certifciate. The value must be a Web::Transport::PKI::RSAKey object. Exactly one of rsa and ec must be specified.

SEE ALSO

Web::Transport::PKI::Parser.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

Copyright 2018 Wakaba <wakaba@suikawiki.org>.

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