Name

OpenXPKI::Server::NICE

Description

NICE ist the Nice Interface for Certificate Enrollment. This class is just a stub to be inherited by your specialised backend class.

The mandatory input parameters are directly passed to the methods while the mandatory return values should be returned as a hash ref by the method call and are written to the context by the surrounding activity functions. The implementations are free to access the context to transport internal parameters.

If the expected operation could not be completed, the method MUST return undef, it is recommended to set a verbose error in the last_error class attribute (this might also show up on the UI).

The methods should NOT use workflow controls as pause or retry, this should be left to the activity classes. Methods should throw exceptions only on final errors (such that will not succeed when called again with the same input data).

API Functions

issueCertificate

Submit a certificate request for a new certificate. The certificate request entry from the database is passed in as hashref.

Note that it highly depends on the implementation what properties are taken from the pkcs10 container and what can be overridden by other means. PKCS10 is the default format which should be supported by any backend. You might implement any own format. See documentation of the used backend for details.

In case the backend has processed the request but needs extra time to process it, the response should be a hash with cert_identifier set to undef. The backend should support pickup of the certificate by fetch certificate in this case and keep information in the context to process this call.

Parameters

csr - hashref containing the database entry from the csr table
ca_alias - name of the ca-token to use

Return values

cert_identifier - the identifier of the issued certificate

csr attributes

Besides the properties of the csr, following attributes should be processed where applicable.

custom_requester_{name|gname|email} - information about the requester
cert_subject_alt_name - Nested Array with attributes for SAN section
notbefore|notafter - special validity

renewCertificate

Submit a certificate renewal request. Same as issueCertificate but receives the certificate identifier of the originating certificate as second parameter.

fetchCertificate

This is only valid if issueCertificate or renewCertificate returned with a pending request and tries to fetch the requested certificate. If successful, the cert_identifier context parameter is populated with the identifier, otherwise the pending marker remains in the context. If the fetch finally failed, it should unset the cert_identifier.

Output

cert_identifier - the identifier of the issued certificate

revokeCertificate

Request the ca to add this certificate to its revocation list. Expects the serial of the certificate revocation request. If the given reason is not supported by the backend, "unspecified" should be used.

Parameters

cert_identifier - the certificate identifier of the cert to revoke
reason_code
invalidity_time

Return Values

Boolean, true if the request was processed. Should throw an exception if revocation is not possible.

checkForRevocation

Might only valid after calling revokeCertificate.

Check if the certificate revocation request was processed and set the status field in the certificate table to REVOKED/HOLD. The special state HOLD must be used only if the certificate is marked as "certificateHold" on the issued CRL or OCSP.

Parameters

cert_identifier

Return Values

true if the certificate is revoked, false if not.

unrevokeCertificate

Remove a formerly revoked certifiate from the revocation list. Expects the certificate identifier. Only allowed after "certificateHold", sets the status field of the certificate status table back to ISSUED immediately.

Input

cert_identifier

issueCRL

Trigger issue of the crl and write it into the "crl" parameter. The parameter ca_alias contains the alias name of the ca token.

In case the backend has processed the request but needs extra time to process it, the response should be a hash with csr_serial set to undef. The backend should support pickup of the certificate by fetchCrl in this case and keep information in the context to process this call.

Parameters

ca_alias

Return values

crl_serial - the serial number (key of the crl database)

fetchCRL

Only valid after calling issueCRL, tries to fetch the new CRL. See issue/fetchCertificate how to use the pending marker.

generateKey

Generate and return a private key according to the parameters passed. Supported modes and parameter sets depend on the backend, some backends might even not implement this method.

Input

mode - can be used to switch between different modes, see backend
key_alg - name of the algorithm, as used in the profile definitions
key_params - key generation parameters, hash with pkey options
key_transport - hash with key password and algorithm, determines settings for the used transport encryption

Output

Return value is a hash, the encrypted key must be returned in the key pkey.

Additional arguments might be returned by the backend.

fetchKey

Fetch a key created by with generateKey from the backend. Usage of the password and key_transport settings might differ between implementations.

Input

key_identifier - the identifier of the key
password - password / secret to fetch the key
key_transport - hash with key password and algorithm, determines settings for the used transport encryption

internal helper functions

_get_context_param

Expect the name of the context field as parameter and returns the appropriate context value. Does not deserialize the content.

_set_context_param

Expect the name of the context field, and its new value. Does not serialize the content.

__persistCertificateInformation

Persist a certificate into the certificate table and store implementation specific information in the datapool. The first parameter is mandatory with all fields given below. The second parameter is serialized "as is" and stored in the datapool and can be retrieved later using "__fetchPersistedCertificateInformation".

certificate_information

certificate - the PEM encoded certificate
ca_identifier - the identifier of the issuing ca
csr_serial - serial number of the processed csr

The certificate is expected to be a x509 structure. A pkcs7 container with the entity certificate and its chain is also accepted.

If the ca_identifier is not set, we try to autodetect it by searching the certificate table for a certificate which matches the authority key identifier. If the certificate has no authority key identifier set, the lookup is done on the the issuer dn.

__fetchPersistedCertificateInformation

Return the hashref for a given certificate identifiere stored within the datapool using "__persistCertificateInformation".

Implementors Guide

The NICE API implements every operation in two individual steps to support asynchronus operating backends. If you are building a synchronus backend, you can ommit the implementation of the second steps.

The activity definitions in OpenXPKI::Server::Workflow::Activity::NICE::* show the expected usage of the API functions.

issue/renew Certificate

The request information must be taken from the csr and csr_attributes t

The method must persist the certificate by calling __persistCertificateInformation and write the certificates identifier into the context parameter cert_identifier.

If the request was dispatched but is still pending, the must be written into the cert_identifier context value. If cert_identifier is not set after execution, the workflow will call this method again.