NAME

OpenXPKI::Server::API2 - Standardized internal and external access to sensitive functions

SYNOPSIS

Default usage:

    use OpenXPKI::Server::API2;

    my $api = OpenXPKI::Server::API2->new(
        acl_rule_accessor => sub { CTX('config')->get('acl.rules.' . CTX('session')->data->role ) },
    );
    printf "Available commands: %s\n", join(", ", keys %{$api->commands});

    my $api_direct = $api->autoloader;

    my $result = $api_direct->mycommand(myaction => "go");
    # same as: $result = $api->dispatch("mycommand", myaction => "go");

Disable ACL checks when executing a command:

    my $api = OpenXPKI::Server::API2->new(
        enable_acls => 0,
    );

Different plugin namespace for auto-discovery:

    my $api = OpenXPKI::Server::API2->new(
        namespace => "My::Command::Plugins",
    );

Disable plugin auto-discovery:

    my $api = OpenXPKI::Server::API2->new(
        commands => {},
    );

Manually register a plugin outside the default namespace:

    my @commands = $api->register_plugin("OpenXPKI::MyAlienplugin");

DESCRIPTION

Please note that all classes in the "OpenXPKI::Server::API2::" namespace are context free, i.e. do not use the "CTX" object.

Within the OpenXPKI server the API (or OpenXPKI::Server::API2::Autoloader, to be more precise) is available via "CTX('api2')".

Call API commands

This class acts as a dispatcher (single entrypoint) to execute API commands via dispatch.

It makes available all API commands defined in the "OpenXPKI::Server::API2::Plugin" namespace.

For easy access to the API commands you should use the autoloader instance returned by "autoloader".

Standard (and easy) way to define a new plugin class with API commands: create a new package in the "OpenXPKI::Server::API2::Plugin" namespace (any deeper hierarchy is okay) and in your package use OpenXPKI::Server::API2::EasyPlugin as described there.

ATTRIBUTES

log

Optional: Log::Log4perl::Logger.

Default: "OpenXPKI::Server::Log->new(CONFIG => undef)->system".

autoloader

Returns an instance of OpenXPKI::Server::API2::Autoloader that allows to directly call API commands:

    my $api = OpenXPKI::Server::API2->new( ... );
    my $api_direct = $api->autoloader;
    $api_direct->search_cert(pki_realm => ...)

enable_acls

Optional: set to FALSE to disable ACL checks when commands are executed.

Default: TRUE

Can only be set via constructor.

acl_rule_accessor

Only if "enable_acls = 1": callback that should return the ACL configuration HashRef for the current user (role).

Example:

    my $cfg = $api2->acl_rule_accessor->();

namespace

Optional: Perl package namespace that will be searched for the command plugins (classes).

Default: "OpenXPKI::Server::API2::Plugin"

Example:

    my $api = OpenXPKI::Server::API2->new(namespace => "My::App::Command");

command_role

Optional: role that all command classes are expected to have. This allows the API to distinct between command modules that shall be registered and helper classes.

Default: "OpenXPKI::Server::API2::PluginRole".

ATTENTION: if you change this make sure the role you specify requires at least the same methods as OpenXPKI::Server::API2::PluginRole.

commands

HashRef containing registered API commands and their Perl packages. The hash is built on first access, only manually set this if you want to disable the auto-discovery of plugin modules.

Structure:

    {
        "API command 1" => "Perl package name",
        "API command 2" => ...,
    }

METHODS

add_commands

register_plugin

Manually register a plugin class containing API commands.

This is usually not neccessary because plugin classes are auto-discovered as described above.

Returns a plain "list" of API commands that were found.

Parameters

•: $packages - class/package name Str or ArrayRef of package names

dispatch

Dispatches an API command call to the responsible plugin instance.

Named parameters

"command" - API command name
"params" - Parameter hash

my_caller

Returns informations about the caller of the code that invokes this method: a list (!) as returned by Perls caller.

This is like a wrapper for Perls "caller" that skips / steps over subroutines that are part of the API infrastructure (except plugins), so we get the "real" calling code.

E.g.

    package OpenXPKI::Server::API2::Plugin::test

    command "who_is_it" => { ... } => sub {
        my ($self, $params) = @_;
        return $self->get_info;
    }

    sub get_info {
        return $self->rawapi->my_caller(1); # who invoked API command "who_is_it"
    }

Parameters

•: $skip Int - how many callers to step over. Default: 0

_apply_acl_rules

Enforces the given ACL rules on the given API command parameters (e.g. applies defaults or checks ACL constraints).

Returns a HashRef containing the resulting parameters.

Throws an exception if the current user role is not permitted to access the given command.

Parameters

$command - API command name
$rules - HashRef containing the parameter rules
$params - HashRef of API command parameters as received by the caller

_get_acl_rules

Checks if the given current OpenXPKI user's role is allowed to execute the given command.

On success it returns the command configuration (might be an empty HashRef), e.g.:

    {
        param_a => {
            default => "lawn",
            match => "^la",
        }
        param_b => {
            force => "green",
        }
    }

On failure (if user role has no access) returns undef.

Parameters

•: $command - API command name

_list_modules

Lists all modules below the given namespace.

Parameters

•: $namespace - Perl namespace (e.g. "OpenXPKI::Server::API2::Plugin")

ACLs

ACLs for the API commands can be defined on a per-role basis in each OpenXPKI realm.

If ACLs are enabled (see "enable_acls") then the default is to forbid all API commands. Allowed commands have to be specified per role in the realm.

The structure of the configuration subtree (below the realm) is as follows:

    acl:
        <role name>:
            # "allow" or "deny"
            policy: allow
            commands:
                # deny access to this command
                <command1>: 0

                # allow unfiltered access to this command
                <command2>: 1

                # allow access and preprocess arguments
                <command3>:
                    <parameter>:
                        default: <string>
                        force:   <string>
                        match:   <regex>
                        block:   1

                <command4>:
                    ...

        <role name>:
            ...

The ACL processor first looks if the command name has a key in the commands tree, if no key is found the action given by policy is taken. If no policy is set, the default is deny.

To allow unfiltered access to a command, set a true scalar value.

To fully deny access to the command, set a false scalar value.

To grant access with some control over the parameters given, use a hash where the attribute names are the keys and the value is a hash with the rules to be applied on the parameter:

force

Enforce parameter to the given value (overwrites a given value).

    acl:
        CA Operator:
            search_cert:
                status:
                    force: ISSUED

default

Default value if none was given.

                    default: ISSUED

match
Match parameter against regular expression. The Regex is executed using the modifiers "/msx", so please escape spaces.
```
                    match: \A (ISSUED|REVOKED) \z
    
```
block
Block parameter so that an exception will be thrown if the caller tries to set it.
```
                    block: 1
    
```

INTERNALS

Design principles

One or more commands per class:
Each plugin class can specify one or more API commands. This allows to keep helper functions that are shared between several API commands close to the command code. It also helps reducing the number of individual Perl module files.
No base class:
When you use OpenXPKI::Server::API2::EasyPlugin to define a plugin class all functionality is added via Moose roles instead of a base class. This allows for plugin classes to be based on any other classes if needed.
Standard magic:
Syntactic sugar and helper functions only use Moose's standard way to e.g. customize meta classes or inject roles. No other black magic is used.
Breakout allowed:
Using OpenXPKI::Server::API2::EasyPlugin is not a must, API plugins might be implemented differently by manually adding the role OpenXPKI::Server::API2::PluginRole to a plugin class.