/ 
App-CamelPKI-0.07
River stage one • 1 direct dependent • 1 total dependent
/ App::CamelPKI::CA

NAME

App::CamelPKI::CA - Model of a Certificate Authority in Camel-PKI.

SYNOPSIS

Supposing App::CamelPKI::CertTemplate::Foo is as described in "SYNOPSIS" in App::CamelPKI::CertTemplate:

my $ca = App::CamelPKI::CA->load($directory, $cadb)->facet_operational;
$ca->issue("App::CamelPKI::CertTemplate::Foo", $pubkey,
           name => "Joe", uid => 42);
$ca->issue("App::CamelPKI::CertTemplate::Foo", $pubkey,
           name => "Fred", uid => 43);
my ($joecert, $fredcert) = $ca->commit();
$ca->revoke("App::CamelPKI::CertTemplate::Foo", $joecert);
$ca->commit();
my $crl = $ca->issue_crl;

DESCRIPTION

The Certificate Authority defined in RFC3039 and following is a software component which issue and revoke X509 certificates. It's the master piece of any PKIX implementation. See "REFERENCES" for more informations.

App::CamelPKI::CA use Crypt::OpenSSL::CA for cyptographic operations, and Catalyst::Model::DBIC in a SQLite database for persistence. App::CamelPKI::CA is very flexible, and deleguates most of the certificate policy choices to the <App::CamelPKI::CertTemplate> subclass which can be freely coded.

Coherence

As any ACID database, App::CamelPKI::CA impose coherence checks to incomming transactions. Theses constraints are flexible, in the way that a part of their implementation is deleguated to the certificate templates; future extensions of Camel-PKI could extends this flexibility, deleguating more responsability on the templating part.

App::CamelPKI::CA impose the following coherence constraints:

It's prohibited to issue a certificate without commiting the transation

It's a security requirement, as any issued certificate may be revoked (which could be impossible if the database could lost its track). That's why "commit" and not "issue" which returns newly build certificates.

It's prohibited to certificate and revoke the same certificate in the same transaction

The template has no mean - yet - to bypass this restriction, and there is few (if no) rationale to change this behavior, as this operation has no sens in the PKIX context.

The certificate template may revoke old certificates when the CA creates new ones

By the means of the "test_certificate_conflict" in App::CamelPKI::CertTemplate method, the certificate template may indicate to the CA that some already issued certificates are conflicting with some of the newly asked ones in the current transaction. For now, the CA honors the template request revoking old certificates; Future version of this CA will be able to cancel the transaction albeith the said certificates are already revoked, or certify bypassing the template policy.

Note that certificates created during the same transaction are not concerned by test_certificate_conflict(), and will not be visible in the database facet used by this method. To test the internal coherence of the transaction, test_issued_certs_coherent() is used, as indicated hereafter.

the certificate template may block some certificate combinations

Using the "test_issued_certs_coherent" in App::CamelPKI::CertTemplate method, the certificate template has the right of veto to cancel the transaction if it detects than some certificates are conflicting with some others (for example because they contains the same nominative informations).

CAPABILITY DISCIPLINE

The ownership of one instance of App::CamelPKI::CA gives privilege to modify certificate an key, read certificate (but not the key), issue a CRL, issue and revoke certificates in any existing App::CamelPKI::CertTemplate, and to performs maintenance operations on the database.

The "facet_operational", "facet_certtemplate" and "facet_readonly" facets helps to restrict theses privileges.

CLASS CONSTRUCTORS AND METHODS

load($directory, $cadb)

Restricted constructor (See App::CamelPKI::RestrictedClassMethod). Load the cryptographic material (private keys and certificates) from $directory, creating it if needed, and use $cadb, an read-write instance of App::CamelPKI::CADB, as storage backend.

METHODS

set_keys(-certificate => $cert, -key => $key)

Install the certificate and private key passed in argument in the CA permanent storage space. The CA is unable to issue certificates and CRLs until this step is not completed. $cert is an App::CamelPKI::Certificate object, and $key is an App::CamelPKI::PrivateKey object.

is_operational()

Returns true only if a key and a certificate has been added to this CA using "set_keys".

database()

Returns a read only instance of App::CamelPKI::CADB> which modelise the CA database. (The read/write access is reserved to the only App::CamelPKI::CA class.)

certificate()

Returns the CA certificate, in the form of an App::CamelPKI::Certificate object.

issue($certtemplate, $pubkey, $key1 => $val1, ...)

Issue on to many new certificates. $pubkey is a public key, in the form of an App::CamelPKI::PublicKey object. $certtemplate is the name of a subclass of App::CamelPKI::CertTemplate; $key1 => $val1, ... are nominatives parameters to pass to $certtemplate for him to generate associated certificates (see details in "prepare_certificate" in App::CamelPKI::CertTemplate and "list_keys" in App::CamelPKI::CertTemplate).

Internally, sign control arguments, and the calls

$certtemplate->test_certificate_conflict($db, $key1 => $val1, ...)

to verify if the certificate to create is compliant to the existing certificates. If it's ok, sign invokes

$certtemplate->prepare_certificate($cacert, $newcert, $key1 => $val1, ...)

At last, sign fix the serial number, conforming to the current CA status, and records the certificate in database. The certificate may then be retrieved using "commit".

revoke($certtemplate, $certificate, %options)

Marks $certificate, an object of the App::CamelPKI::Certificate class, which has been certified via the $certtemplate template, as revoked. It's prohibited to revoke a certificate that has just been certified in the current transaction (see "Coherence"); If this situation is detected, triggers an exception. In the same way, the template may cause additional revocations following the revocation of $certificate (see "test_cascaded_revocation" in App::CamelPKI::CertTemplate).

This method is delegated to "revoke" in App::CamelPKI::CADB, and recognized named options are documented at this section.

commit()

Records all writes in database, and returns the certificate list issued with "sign" scince the creation of the object or scince the previous call to commit. Certificates are returned in the form of a list of App::CamelPKI::Certificate objects, in the same order as the corresponding call to "sign".

issue_crl(-option1 => $val1, ...)

Builds a CRL taking account of previously marked as revoked certificates in database, and returns it in the form of an App::CamelPKI::CRL object.

Recognized named options are:

-validity => $days

Allows to specify the validity duration of the CRL. Default value is 7 days.

-signature_hash => $hashname

Allows to specify the cryptographic algorithm to use for the CRL signing, on the form of a name (for example "sha256"). The default value is "sha256", as "md5" and "sha1" are not recommanded due to progress done in their cryptanalysis (http://www.win.tue.nl/~bdeweger/CollidingCertificates/).

get_certificates_issued()

Builds a list of certificates already issued by the CA and not revoked. Certificates are returned as an array of App::CamelPKI::Certificate.

get_certificates_revoked()

Builds a list of certificates already issued by the CA and not revoked. Certificates are returned as an array of App::CamelPKI::Certificate.

get_certificate_by_serial($serial)

Builds a list of certificates already issued by the CA and not revoked. Certificates are returned as an array of App::CamelPKI::Certificate.

rescind()

Cancels the ingoing transaction and let the object in an unusable status. Invoked automatically in case of a template exception.

FACETS

database_facet($certtemplate)

Returns a facet of the CA database (as passed to "load") resticted in read only and using a filter that only allow to consult certificates generated using $certtemplate as first parameters issued to "issue".

facet_readonly()

Returns a copy of this object in read only: only "certificate" and "database" methods can be invoked.

facet_crl_only()

Returns a copy of this object with restricted privileges: besides the read-only accessors (see "facet_readonly"), a holder of a reference to the returned object only has the right to issue a new CRL. This is an appropriate level of privilege to hand out to an unauthenticated user.

facet_certtemplate($certtemplate)

Returns a copy of this object with restricted privileges: among the methods that writes, only "certificate", "commit", "issue", "revoke" and "database" can be invoked, and for the last three methods, access is restricted to certificates belonging to $certtemplate. The returned object represents the right to generate and to revoke certificates in a specific template.

facet_operational()

Returns a copy of this object with restricted privileges: the "set_keys" cannot be revoked anymore. This facet is suitable to pass to a "regular" controller which has no rights to modify the CA keys.

Instead of returning an object which could do nothing, facet_operational throw an exception if "is_operational" is not true.