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

FreeBSD Manual Pages

  
 
  

home | help
OpenXPKI::Server::API:UsereContributed Perl DoOpenXPKI::Server::API::Object(3)

Name
       OpenXPKI::Server::API::Object

Description
       This is the object interface which should be used by all	user
       interfaces of OpenXPKI.	A user interface MUST NOT access the server
       directly. The only allowed access is via	this API. Any function which
       is not available	in this	API is not for public use.  The	API gets
       access to the server via	the 'server' context object. This object must
       be set before instantiating the API.

Functions
   get_key_identifier_from_data
       returns the key identifier (sha1	hash of	the public key bit string) of
       the given data as string, uppercased hex	with colons.

       DATA
	   Data, encoded as given by FORMAT parameter.

       FORMAT
	   * PKCS10: PEM encoded PKCS10	block

   get_csr_info_hash_from_data
       return a	hash reference which includes all parsed informations from the
       CSR. The	only accepted parameter	is DATA	which includes the plain CSR.

   get_ca_cert
       returns the certificate of one CA. This is a wrapper around get_cert to
       make the	access control more fine granular if necessary.

   get_cert
       returns the requested certificate. The supported	arguments are
       IDENTIFIER and FORMAT. IDENTIFIER is required whilst FORMAT is
       optional. FORMAT	can have the following values:

       o   PEM

       o   DER

       o   TXT

       o   HASH	- the default value

       o   DBINFO - information	from the certificate and attributes table

   get_cert_attributes
       returns a hash with the attributes of the certificate. Requires the
       IDENTIFIER of the certificate.

   get_profile_for_cert
       returns the name	of the profile used during the certificate request.
       Supported argument is IDENTIFIER	which is required.

   get_cert_actions
       Requires	a certificate identifier (IDENTIFIER) and optional ROLE.
       Returns a list of actions that the given	role (defaults to current
       session role) can do with the given certificate.	The return value is a
       nested hash with	options	available for lifecyle actions.	The list of
       workflows is hardcoded for now, workflows which are not present or not
       accessible by the current user are remove from the result.

	   {
	       workflow	=> [
		   { label => I18N_OPENXPKI_UI_CERT_ACTION_REVOKE, workflow => certificate_revocation_request_v2 },
		   { label => I18N_OPENXPKI_UI_CERT_ACTION_RENEW, workflow => certificate_renewal_request_v2 },
		   { label => I18N_OPENXPKI_UI_CERT_ACTION_RENEW, workflow => certificate_renewal_request_v2 }
	       ]
	   }

   is_certificate_owner
       Requires	a certificate identifier (IDENTIFIER) and user (USER). User is
       optional	and will default to the	session	user if	not given. Checks if
       USER is the owner of the	certificate, based on the formerly recorded
       meta information.

       Returns true if the user	is the owner, false if not and undef if	the
       ownership could not be determined.

   get_crl
       returns a CRL. The possible parameters are CRL_KEY, FORMAT and
       PKI_REALM.  CRL_KEY is the serial of the	database table,	the realm
       defaults	to the current realm and the default format is PEM. Other
       formats are DER,	TXT HASH, FULLHASH or DBINFO. DBINFO returns the
       fields directly from the	database without parsing the CRL. HASH returns
       the result of OpenXPKI::Crypto::CRL::get_parsed_ref, FULLHASH also adds
       the list	of revocation entries (this might become a very	expensive task
       if your CRL is large!).

       If no serial is given, the most current CRL of the active signer	token
       is returned.

   get_crl_list( { PKI_REALM, ISSUER, FORMAT, LIMIT, VALID_AT }	)
       List all	CRL issued in the given	realm. If no realm is given, use the
       realm of	the current session. You can add an ISSUER (cert_identifier)
       in which	case you get only the CRLs issued by this issuer.  The result
       is an arrayref of matching entries ordered by last_update, newest
       first. LIMIT has	a default of 25.  VALID_AT accepts a single timestamp
       and will	match all crl which have been valid at this moment.  (this
       might crash your	server if used together	with a FORMAT!)

       The FORMAT parameter determines the return format:

       RAW Bare	lines from the database

       HASH
	   The result of OpenXPKI::Crypto::CRL::get_parsed_ref

       TXT|PEM|DER
	   The data blob in the	requested format.

   import_crl( { DATA }	)
       Import a	CRL into the current realm. This should	be used	only within
       realms that work	as a proxy to external CA system or use	external CRL
       signer tokens. Expects the PEM formated CRL in the DATA parameter.  The
       issuer is extracted from	the CRL. Note that the issuer must be defined
       as alias	in the certsign	group!

       A duplicate check is done based on issuer, last_update and next_update.

       The content of the CRL is NOT parsed, therefore the certificate status
       of revoked certificates is NOT changed in the database!

       DATA
	   PEM formated	CRL

   search_cert
       supports	a facility to search certificates. It supports the following
       parameters:

       o   CERT_SERIAL

       o   LIMIT

       o   LAST

       o   FIRST

       o   CSR_SERIAL

       o   SUBJECT

       o   ISSUER_DN

       o   ISSUER_IDENTIFIER

       o   PKI_REALM (default is the sessions realm, _any for global search)

       o   PROFILE

       o   VALID_AT

       o   NOTBEFORE/NOTAFTER (with SCALAR searches "other side" of validity
	   or pass HASH	with operator)

       o   CERT_ATTRIBUTES list	of conditions to search	in attributes (KEY,
	   VALUE, OPERATOR)

       o   ENTITY_ONLY (show only certificates issued by this ca)

       o   SUBJECT_KEY_IDENTIFIER

       o   AUTHORITY_KEY_IDENTIFIER

       The result is an	array of hashes. The hashes do not contain the data
       field of	the database to	reduce the transport costs an avoid parser
       implementations on the client.

   search_cert_count
       Same as cert_search, returns the	number of matching rows

   private_key_exists_for_cert
       Checks whether a	corresponding CA-generated private key exists for the
       given certificate identifier (named parameter IDENTIFIER).  Returns
       true if there is	a private key, false otherwise.

   __get_private_key_from_db
       Gets a private key from the database for	a given	certificate identifier
       by looking up the CSR serial of the certificate and extracting the
       private_key from	the datapool. Returns undef if no key is available.

   get_private_key_for_cert
       returns an ecrypted private key for a certificate if the	private	key
       was generated on	the CA during the certificate request process.
       Supports	the following parameters:

       o   IDENTIFIER -	the identifier of the certificate

       o   FORMAT - the	output format

	   One of PKCS8_PEM (PKCS#8 in PEM format), PKCS8_DER (PKCS#8 in DER
	   format), PKCS12 (PKCS#12 in DER format), OPENSSL_PRIVKEY (OpenSSL
	   native key format in	PEM), OPENSSL_RSA (OpenSSL RSA with DEK-Info
	   Header), JAVA_KEYSTORE (JKS including chain).

       o   PASSWORD - the private key password

	   Password that was used when the key was generated.

       o   PASSOUT - the password for the exported key,	default	is PASSWORD

	   The password	to encrypt the exported	key with, if empty the input
	   password is used.

	   This	option is only supported with format OPENSSL_PRIVKEY, PKCS12
	   and JKS!

       o   NOPASSWD

	   If set to a true value, the key is exported without a password!.
	   You must also set PASSOUT to	the empty string.

       o   KEEPROOT

	   Boolean, when set the root certifcate is included in	the keystore.
	   Obviously only useful with PKCS12 or	Java Keystore.

       The format can be either	The password has to match the one used during
       the generation or nothing is returned at	all.

   validate_certificate	( { PEM, PKCS7,	NOCRL, ANCHOR }	)
       Validate	a certificate by creating the chain. Input can be either a
       single PEM encoded certificate or a PKCS7 container or PEM array	with
       the entity certificate including	its chain.

       if NOCRL	is set to 1, no	crl checks are done (certificate is marked
       valid) -	*not implemented yet!*:

       ANCHOR is an optional list of trust anchors (cert identifiers). If
       given, the resulting chain is tested against the	list. If

       The return value	is a hashref:

       STATUS
	   The overall status of the validation	which is one of: VALID,
	   BROKEN, REVOKED, NOCRL, NOROOT, (incomplete chain/no	root found),
	   UNTRUSTED (got root certificate which is not	known).

	   If ANCHOR is	given the result is never VALID	but TRUSTED/UNTRUSTED
	   is returned.

       CHAIN
	   The full certifiacte	chain as array,	starting with the entity.

   get_data_pool_entry
       Searches	the specified key in the data pool and returns a data
       structure containing the	resulting value	and additional information.

       Named parameters:

       o   PKI_REALM - PKI Realm to address. If	the API	is called directly
	     from OpenXPKI::Server::Workflow only the PKI Realm	of the
	   currently active
	     session is	accepted. Realm	defaults to the	current	realm if
	   omitted.

       o   NAMESPACE

       o   KEY

       Example:
	$tmpval	=
	 CTX('api')->get_data_pool_entry(
	 {
	   PKI_REALM =>	$pki_realm,
	   NAMESPACE =>	'workflow.foo.bar',
	   KEY => 'myvariable',
	 });

       The resulting data structure looks like:
	{
	  PKI_REALM	  => # PKI Realm
	  NAMESPACE	  => # Namespace
	  KEY		  => # Data pool key
	  ENCRYPTED	  => # 1 or 0, depending on if it was encrypted
	  ENCRYPTION_KEY  => # encryption key id used (may not be available)
	  MTIME		  => # date of last modification (epoch)
	  EXPIRATION_DATE => # date of expiration (epoch)
	  VALUE		  => # value
	};

   set_data_pool_entry
       Writes the specified information	to the global data pool, possibly
       encrypting the value using the password safe defined for	the PKI	Realm.

       Named parameters:

       o   PKI_REALM - PKI Realm to address. If	the API	is called directly
	     from OpenXPKI::Server::Workflow only the PKI Realm	of the
	   currently active
	     session is	accepted. If no	realm is passed, the current realm is
	   used.

       o   NAMESPACE

       o   KEY

       o   VALUE - Value to store

       o   ENCRYPTED - optional, set to	1 if you wish the entry	to be
	   encrypted. Requires a properly set up password safe certificate in
	   the target realm.

       o   FORCE - optional, set to 1 in order to force	writing	entry to
	   database

       o   EXPIRATION_DATE

	   optional, seconds since epoch. If entry is older than this value
	   the server may delete the entry.  Default is	to keep	the value for
	   infinity.  If you call set_data_pool_entry with the FORCE option to
	   update an exisiting value, the (new)	expiry date must be passed
	   again or will be reset to inifity!  To prevent unwanted deletion, a
	   value of 0 is not accepted. Set value to undef to delete an entry.

       Side effect: this method	automatically wipes all	data pool entries
       whose expiration	date has passed.

       NOTE: Encryption	may work even though the private key for the password
       safe is not available (the symmetric encryption key is encrypted	for
       the password safe certificate). Retrieving encrypted information	will
       only work if the	password safe key is available during the first	access
       to the symmetric	key.

       Example:
	CTX('api')->set_data_pool_entry(
	{
	  PKI_REALM => $pki_realm,
	  NAMESPACE => 'workflow.foo.bar',
	  KEY => 'myvariable',
	  VALUE	=> $tmpval,
	  ENCRYPT => 1,
	  FORCE	=> 1,
	  EXPIRATION_DATE => time + 3600 * 24 *	7,
	});

   list_data_pool_entries
       List all	keys in	the datapool in	a given	namespace.

       o   NAMESPACE

       o   PKI_REALM, optional,	see get_data_pool_entry	for details.

       o   MAXCOUNT, optional, max number of entries returned

       Returns an arrayref of Namespace	and key	of all entries found.

   modify_data_pool_entry
       This method has two purposes, both require NAMESPACE and	KEY.  This
       method does not modify the value	of the entry.

       Change the entries key
	   Used	to update the key of entry. Pass the name of the new key in
	   NEWKEY.  Commonly used to deal with temporary keys

       Change expiration information
	   Set the new EXPIRATION_DATE,	if you set the parameter to undef, the
	   expiration date is set to infity.

   control_watchdog { ACTION =>	(START|STOP) }
       Start ot	stop the watchdog.

perl v5.24.1			  2017-07-03  OpenXPKI::Server::API::Object(3)

Name | Description | Functions

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

home | help