GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  OPENXPKI::SERVER::API::OBJECT (3)

.ds Aq ’

Name

OpenXPKI::Server::API::Object

CONTENTS

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_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 PKCS7 - without the usual hash mark
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 }
        ]
    }



    get_crl

returns a CRL. The possible parameters are SERIAL, FORMAT and PKI_REALM. SERIAL 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 and HASH. HASH returns the result of OpenXPKI::Crypto::CRL::get_parsed_ref.

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.

    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)
o VALID_AT
o NOTBEFORE/NOTAFTER (less/greater to match other side of validity)
o CERT_ATTRIBUTES list of conditions to search in attributes (KEY, VALUE, OPERATOR)
o ENTITY_ONLY (show only certificates issued by this ca)
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) 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.

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.

<B>NOTE:B> 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. <B>This method does not modify the value of the entryB>.
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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 OPENXPKI::SERVER::API::OBJECT (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.