/ 
Web-ID-1.927
River stage one • 2 direct dependents • 2 total dependents
/ Web::ID::Certificate::Generator

NAME

Web::ID::Certificate::Generator - role for Web::ID::Certificate

SYNOPSIS

use Web::ID::Certificate::Generator;

my %options = (
  cert_output       => '/home/alice/webid.p12',
  passphrase        => 's3cr3t s0urc3',
  rdf_output        => '/home/alice/public_html/foaf.rdf',
  subject_alt_names => [
    Web::ID::SAN::URI->new(
      value => 'http://example.com/~alice/foaf.rdf#me',
    ),
    Web::ID::SAN::Email->new(
      value => 'alice@example.com',
    ),
  ],
  subject_name      => 'Alice Jones',
  subject_locality  => 'Lewes',
  subject_region    => 'East Sussex',
  subject_country   => 'GB',   # ISO 3166-1 alpha-2 code
);

my $cert = Web::ID::Certificate->generate(%options);

DESCRIPTION

This is a role that may be applied to Web::ID::Certificate. It is not consumed by Web::ID::Certificate by default as I was trying to avoid tainting the class with the horror that's found in this role.

The import routine of this package applies the role to Web::ID::Certificate, so it is sufficient to do:

use Web::ID::Certificate::Generator;

You don't need to muck around with apply_all_roles yourself.

Constructor

generate(%options)

Generates a brand new WebID-enabled certificate.

Options

The following options can be passed to generator

  • cert_output

    A passphrase-protected PKCS12 certificate file is generated as part of the certificate generation process. The PKCS12 file is what you'd typically import into a browser.

    You can pass a scalar reference, in which case the PKCS12 data will be written to that scalar; or a file handle or string file name.

    This is a required option.

  • passphrase

    The password for the PKCS12 file.

    This is a required option.

  • rdf_output

    RDF data is also generated as part of the certificate generation process.

    Again a file handle or string file name can be passed, or an RDF::Trine::Model.

    This is a required option.

  • subject_alt_names

    List of Web::ID::SAN objects to generate the certificate's subjectAltNames field. You want at least one Web::ID::SAN::URI in there.

    This is a required option.

  • subject_name

    The name of the person who will hold the certificate. (e.g. "Alice Smith".)

    This is a required option.

  • subject_org

    The certificate holder's organisation.

    Not required.

  • subject_locality

    The locality (e.g. city) of the certificate holder's address.

    Not required.

  • subject_region

    The region (e.g. state or county) of the certificate holder's address.

    Not required.

  • subject_country

    Two letter ISO code for the country of the certificate holder's address.

    Not required.

  • openssl_path

    The path to the OpenSSL binary. Yes that's right, this role calls the OpenSSL binary via system calls. Defaults to automatic discovery via Web::ID::Util::FindOpenSSL.

  • key_size

    Key size in bits. Defaults to 1024. Bigger keys are more secure. Keys bigger than 2048 bits will take a ridiculously long time to generate. Keys less than 512 bits are pretty poor.

  • not_after

    Date when the certificate should expire, as a DateTime object. Defaults to 365 days.

BUGS AND LIMITATIONS

Generating the private key results in shedloads of nasty crud being spewed out on STDERR.

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Web-ID.

SEE ALSO

Web::ID, Web::ID::Certificate.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2012 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.