Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OpenXPKI::Server::API2User Contributed Perl DocumentaOpenXPKI::Server::API2(3)

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".

   Create a plugin class
       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	the given "command => package" mappings	to the list of known
       API 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

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

   dispatch
       Dispatches an API command call to the responsible plugin	instance.

       Named parameters

       o   "command" - API command name

       o   "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

       o   $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

       o   $command - API command name

       o   $rules - HashRef containing the parameter rules

       o   $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

       o   $command - API command name

   _list_modules
       Lists all modules below the given namespace.

       Parameters

       o   $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:

       o   force

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

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

       o   default

	   Default value if none was given.

			       default:	ISSUED

       o   match

	   Match parameter against regular expression. The Regex is executed
	   using the modifiers "/msx", so please escape	spaces.

			       match: \A (ISSUED|REVOKED) \z

       o   block

	   Block parameter so that an exception	will be	thrown if the caller
	   tries to set	it.

			       block: 1

INTERNALS
   Design principles
       o   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.

       o   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.

       o   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.

       o   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.

perl v5.32.0			  2020-08-29	     OpenXPKI::Server::API2(3)

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | METHODS | ACLs | INTERNALS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OpenXPKI::Server::API2&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help