NAME

App::CamelPKI::Controller::CA::Template::Base - Base class for all template controllers in Camel-PKI

DESCRIPTION

A template controller is an entry point into Camel-PKI : it consists of the code that responds to the JSON-RPC requests for issuing or revoking certificates. Other user-initiated Certification Authority operations in Camel-PKI are handled by App::CamelPKI::Controller::CA.

Template controllers are grouped in categories, just like the certificate templates in the App::CamelPKI::CertTemplate::* namespace. Each class in the App::CamelPKI::Controller::CA::Template::* namespace deals with one such category of templates, e.g. App::CamelPKI::Controller::CA::Template::SSL serves certification and revocation requests for templates App::CamelPKI::Controller::SSLServer and App::CamelPKI::Controller::SSLClient , both implemented within the App::CamelPKI::CertTemplate::SSL module.

All template controllers inherit from this class, App::CamelPKI::Controller::CA::Template::Base, which is abstract. They overload the "OVERLOADABLE METHODS", and wire up the certify and revoke actions.

ACTIONS

These actions are inherited by template controllers, and are mapped into their respective URL namespaces unless appropriate Catalyst counter-mojo is performed. However, these actions are not mapped in the base class (because they have no meaning there).

certifyJSON($reqdetails) : Local : ActionClass("+App::CamelPKI::Action::JSON")

Requests the issuance of a number of certificates in this template family. $reqdetails (passed as the JSON-RPC POST payload) is a reference to a structure like this (here for App::CamelPKI::Controller::CA::Template::SSL, other template groups would obviously use different values for template):

   {
     requests => [
      { template => "SSLServer",
        role     => "foo",
        dns      => "bar.example.com",
      },
      { template => "SSLClient",
        role     => "bar",
        dns      => "bar.example.com",
      },
      { template => "SSLClient",
        role     => "bar",
        dns      => "bar.example.com",
      },
      { template => "SSLClient",
        dns      => "bar.example.com",
      }
     ],
   }

$reqdetails->{requests} is a reference to list with one entry per certificate to issue.

According to the coherency requirements set forth in certificate template code, requesting a new certificate that collides with a pre-existing one results in the latter being revoked implicitly; requesting two colliding certificates within the same call to certify throws an exception.

The response is transmitted as an application/json HTTP document, with the following structure (again in Perl syntax):

  {
     keys => [
        [ $cert1, $key1 ],
        [ $cert2, $key2 ],
        [ $cert3, $key3 ],
        [ $cert4, $key4 ],
     ],
  }

where $cert1, ... are certificates in PEM formats; $key1, ... are private keys in PEM format; and the certificates and keys are in the same order as the $reqdetails->{requests} list outlined above.

certify works as a single transaction, and will therefore either complete in whole or fail in whole; in no case will the response contain a smaller number of certificates than the request list.

certifyForm : Local

This function is used to redirect the user to the right template depending on the url used to go to this functions, for example : http://127.0.0.1/ca/template/ssl/certifyForm will redirect on the appropriate form for SSL certificates.

This assumes that every certificate's template own a function named _form_certify_template that represents the url of the TT2 template starting from the App/CamelPKI/root directory.

certify

Requests the issuance of a certificate. Parameters are passed as form's requests. For example, for App::CamelPKI::Controller::CA::Template::SSLClient the request should be : $c->request->params->template="SSLClient" $c->request->params->dns="foo.bar.com" $c->request->params->role="administration"

The certificate and the key is returned as a PEM file containing the generated certificate and the private key.

revokeForm : Local

This function is used to redirect the user to the right template depending on the url used to go to this functions, for example : http://127.0.0.1/ca/template/ssl/revokeForm will redirect on the appropriate form for SSL certificates.

This assumes that every certificate's template own a function named _form_template and that represents the url of the TT2 template starting from the App/CamelPKI/root directory.

revoke

Revokes a set of certificates at once. The datas are passed by a form.

$c->request->params->{type}="dns" $c->request->params->{data}="foo.bar.com"

The effect is to revoke all certificates that have foo.bar.com as their DNS name in any of the templates that this controller class deals with.

revokeJSON($revocdetails)

Revokes a set of certificates at once. The $revocdetails structure is of the following form:

    {
        dns => $host
    }

The effect is to revoke all certificates that have $host as their DNS name in any of the templates that this controller class deals with.

view_operations

returns to the right view for listing possiblities with templates.

OVERLOADABLE METHODS

_list_template_shortnames

Shall return the list of the short names of the templates that this controller deals with. There is no base class implementation.

_revocation_keys

Shall return the list of nominative data keys that are allowed as criteria for batch revocation. The base class implementation is to use only dns.