NAME

App::CamelPKI::CADB - Store App::CamelPKI::CA datas in a SQLite database

SYNOPSIS

    use App::CamelPKI::CADB;

    my $cadb = load App::CamelPKI::CADB($dir);

    my $serial = $cadb->next_serial("certificate");

    # ... making a $certificate with $serial ...

    $cadb->add($cert, foo => "bar", baz => [ "quux", "bloggs" ]);

    $cadb->revoke($certificate, -revocation_reason => "keyCompromise",
                  -compromise_time => "20070313104800Z");

    $cadb->commit();

    for(my $cursor = $cadb->search(-initially_valid_at => "now",
                                   -revoked => 1);
        $cursor->has_more; $cursor->next) {
          my $cert = $cursor->certificate;
          my %infos = $cursor->infos;
          my $revocation_time = $cursor->revocation_time;
          my $revocation_reason = $cursor->revocation_reason;
          my $compromise_time = $cursor->compromise_time;

          # ... making the CRL ...
    }

DESCRIPTION

This class modelizes a CA database; this database store issued certificates, nominative datas used for their creation, revocation status of these certificates, and some incremental series for CRL and certificates serial numbers.

For now, Camel-PKI only knows howto store certificates in an SQLite database.

CAPABILITY DISCIPLINE

Possessing an App::CamelPKI::CADB instance equates privilege to perform all non-destructive write operations on this database; however, no deletion of certificates is possible.

The "facet_readonly" method returns a read-only version on this database.

The "debug_statements" method is restricted (see App::CamelPKI::RestrictedClassMethod), despite it not being a class method; the result is that it cannot be called at all when App::CamelPKI::RestrictedClassMethod is active, which is what we want (debug_statements() is not meant to be called at all in production).

METHODS

initdb($dir)

Populates $dir, a string containing the name of a directory, with an empty database. Returns immediately if $dir already exists.

load($dir)

Restricted constructor (see App::CamelPKI::RestrictedClassMethod). Loads the database from the $dir directory and returns a read-write object.

add($cert, %infos)

Add a certificate to the database. $cert is an instance of App::CamelPKI::Certificate which must not be already existing.

%infos is a table of nominative informations, dealt as an opaque chain, where keys must been validaded by the regular expression qr/[a-z0-9_]+/, and values are character chains or references to a character chains table.

Semantics on these informations is at the caller's choice; from the App::CamelPKI::CADB point of view, these informations can be used as search expression in "search", and be consulted using "infos" in "App::CamelPKI::CADB::Cursor".

search(%criteria)

Search certificates that were added ("add") precedently, using %criteria criteria in a conjonctive way (ie, dealt with the "AND" operator).

If %criteria does not contain any key -initially_valid_at and -revoked, then %criteria is supposed to implicitly contain

    -initially_valid_at => "now", -revoked => 0

to make search() returns only valid certificates (in the RFC3280 way), if not stated otherwise.

In a more general way, keys and values for %criteria are:

-certificate => $cert

Renvoie uniquement le certificat identique à $cert, une instance de App::CamelPKI::Certificate.

-initially_valid_at => $time

Returns only certificates that were initially scheduled to be valid at $time date, regardless of whether they have been revoked (but see also -revoked). In other words, returns certificates that match

  notBefore <= $time && $time <= notAfter

$time is either an object of class App::CamelPKI::Time, a date in the "zulu" format (yyyymmddhhmmssZ), or the special string "now".

-revoked => 1

Returns only revoked certificates, ie those for which the most recent call to "revoke" did not specify -reason => "removeFromCRL".

-revoked => 0

Returns only valid certificates, or those that were un-revoked by passing -reason => "removeFromCRL" to "revoke".

-revoked => undef

Search certificates without consideration for their revocation status. Used to cancel the effect of the implicit value mentioned above.

-serial => serial

Search certificates for the certifiate serial.

$infokey => $infoval

where $infokey doesn't start by a hyphen (-): returns only certificate(s) that had $infokey and $infoval among their %infos at the time they where added using "add". $infoval may be undef, indicating that any value for $infokey in %infos is acceptable.

The return value in list context is a list of App::CamelPKI::Certificate object class. In scalar context, a cursor object of the "App::CamelPKI::CADB::Cursor" class is returned.

revoke($cert, %options)

Mark a certificate as revoked, for the CA to know it must been included in the next CRLs. $cert is an instance of App::CamelPKI::Certificate. Known Named options are:

-revocation_time => $time

The revocation date, in "zulu" format (yyyymmddhhmmssZ). By default, the current date is used.

-revocation_reason => $reason

-hold_instruction => $oid (NOT IMPLEMENTED YET)

-hold_instruction => $string (NOT IMPLEMENTED YET)

-compromise_time => $time

Values of the extensions of the same name in the CRL, as documented in "add_entry" in Crypt::OpenSSL::CA. By default, these extensions are omitted. Using removeFromCRL as $reason cancels the revocation of this certificate. Please note that values for keys -hold_instruction and -revocation_reason undergo canonicalization, so that they may read out differently from the "App::CamelPKI::CADB::Cursor" when fetched again.

next_serial($seqname)

Increments the sequence named $seqname and returns its new value. $seqname may be any string matching m/^[a-z]+$/i, at the caller's choice. Sequences start at 2.

commit()

Commits all modifications made with "add", "revoke" and "next_serial" since the construction of this object, or the previous call to commit(), whichever is latest. If commit() is not called, no write will be made to the file system, and all modifications will be lost!.

max_serial($seqname)

Returns (an approximation of) the current status of the sequence named $seqname, ie an integer which is guaranteed to be superior or equal to all previous values previously returned by "next_serial", and strictly inferior to all values that will be returned in the future.

facet_readonly()

Returns a read-only copy of the database object: only "search" and "max_serial" methods are available.

debug_statements($debugsub)

This restricted method (see App::CamelPKI::RestrictedClassMethod) installs $debugsub as the SQL request observer on all App::CamelPKI::CADB objects constructed later. This method will be called thusly for each SQL request:

   $debugsub->($sql, @bind_values);

This mecanism is only destined for testing purposes; it should not be used in production.

App::CamelPKI::CADB::Cursor

This class models a read only SQL cursor equivalent; instancies may be constructed using "search".

An attentive reader will probably understand that's a fairly trivial derivation of the DBIx::Class API; However there is no reason to return directly an instance of DBIx::Class in "search" because it will violate the encapsulation of App::CamelPKI::CADB. Consequence could be a induced coupling (it should be impossible to refactor the scheme without breaking the whole calling code), and worse, a privilege escape leading to a security breach (because it's also possible to write with a DBIx::Class cursor).

count

Returns the total number of entries in this cursor, independently of the number of times "next" has already been called.

has_more

Returns true if, and only if, the cursor has still some results to propose. All methods hereafter have an undef behavior when has_more returns false.

next

Makes the cursor advance one position.

certificate

Returns the certificate currently under the cursor, in a App::CamelPKI::Certificate object.

infos

Returns a table of structures and contents simliar to the table %infos passed to "add" at the time of the certiticate insertion in database. In a scalar context, returns a reference on a hash which contains references on lists; In a list context, returns this same hash "flat" (a list alternating scalar keys and values which are references on lists).

The order of the %info keys, and the order of values contained in when more than on key provided, is not preserved.

revocation_time

revocation_reason

compromise_time

hold_instruction

Returns the canonical form of the revocation informations corresponding to the certificate present under the cursor at that time: time stamps are in "zulu" format; revocation_reason() returns a symbolic character chains among the one listed in RFC3280 section 5.3.1; hold_instruction() returns an OID in decimal notation separated by dots (for example 1.2.840.10040.2.1).

cpanm App::CamelPKI

perl -MCPAN -e shell
install App::CamelPKI