view release on metacpan or  search on metacpan

lib/App/CamelPKI/Model/CA.pm  view on Meta::CPAN

=head1 DESCRIPTION

The I<App::CamelPKI::Model::CA> object is a singleton owned by Catalyst to
construct instances of L<App::CamelPKI::CA> following the application
configuration, and distribute them to the controllers at the
L<App::CamelPKI/model> initiative.
I<App::CamelPKI::Model::CA> have some methods on its own like 
L</certification_chain> to modelise the Camel-PKI Operational CA in what
is particular.

=head1 CAPABILITY DISCIPLINE

An instance of I<App::CamelPKI::Model::CA> modelise nearly the same 
amount of privileges than an instance of L<App::CamelPKI::CA> that she
embeds (excepted for the L</certification_chain> that is a
I<App::CamelPKI::Model::CA> particularism). In the same way,
I<App::CamelPKI::Model::CA> have the same facet set as I<App::CamelPKI::CA>.

=cut

use base 'Catalyst::Model';
use Class::Facet;
use App::CamelPKI::RestrictedClassMethod qw(:Restricted);
use App::CamelPKI::PrivateKey;
use App::CamelPKI::Certificate;
use App::CamelPKI::CADB;
use App::CamelPKI::CA;

=head1 CONFIGURATION

The following variables are configurable in
I<App::CamelPKI::Model::CA>:

=over

=item I<db_dir>

The directory where the AC database and its cryptographic
material (certificates and keys) are to be installed.

=item I<keysize>

The size of keys used for the Key Ceremony.

=back

=cut


=head1 METHODS

=head2 new

Constuctor of the singleton called by Catalyst. Overloaded to use
L<App::CamelPKI::RestrictedClassMethod>, so that it cannot be called from
anywere, except from the application's initialization sequence.

=cut

sub new : Restricted { shift->SUPER::new(@_) }

=head2 set_brands($ca_brand, $cadb_brand)

Conveys authority to create instances of L<App::CamelPKI::CA> and
L<App::CamelPKI::CADB> to this class when the restricted class method
discipline is enabled (see L<App::CamelPKI::RestrictedClassMethod>). Called
by L<App::CamelPKI/setup> after restricting all the constructors in the
application .  $ca_brand and $cadb_brand are the respective brands for
classes B<App::CamelPKI::CA> and B<App::CamelPKI::CADB>, as created by
L<App::CamelPKI::RestrictedClassMethod/grab>.

This class method is in turn restricted, so that only the application
initialization code may call it.  By default (eg in tests),
B<App::CamelPKI::Model::CA> uses fake brands (see
L<App::CamelPKI::RestrictedClassMethod/fake_grab>).

=cut

{
    my ($cabrand, $cadbbrand) =
        map { App::CamelPKI::RestrictedClassMethod->fake_grab($_) }
            qw(App::CamelPKI::CA App::CamelPKI::CADB);
    sub set_brands : Restricted {
        (undef, $cabrand, $cadbbrand) = @_;
    }

    sub _invoke_on_CA   { $cabrand->invoke(@_) }
    sub _invoke_on_CADB { $cadbbrand->invoke(@_) }
}

=head2 instance

Verify this CA has already undergone its Key Ceremony, or else throw an
exception; then create and returns an App::CamelPKI::CA instance which has
all privileges and represents the (unique) Operational CA installed on
this host.

Note that I<instance> is B<not> idempotent, and returns different
instances at each invocation. Were it not the case, constructors could
construct a covert channel using the shared instance, which is
mutable, and so a malicious controller could hide some information for
constructors that will later run in the same UNIX process.

=cut

sub instance {
    my ($self) = @_;
    my $ca = $self->_make_ca;
    unless ($ca->is_operational) {
        throw App::CamelPKI::Error::State(<<"MESSAGE");
The AC is not operational, please run
script/camel_pki_keyceremony.pl
MESSAGE
    }
    return $ca;
}

=head2 db_dir()

Returns the directory where are stored the App-PKI Certificate