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 cert_identifer (mandatory) and optional additional information about the revocation. Some backends can handle an extra parameter hash at the end of the list.

Parameters

cert_identifier - the certificate identifier of the cert to revoke

reason_code - the reason code (depends on the backend)

revocation_time - time of revocation, epoch

invalidity_time - invalidity time (for keyCompromise), epoch

hold_instruction_code - depends on the backend

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

_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 a hash with the fields explained below. The second parameter is serialized "as is" and stored in the datapool and can be retrieved later using "__fetchPersistedCertificateInformation".

Mandatory Keys

certificate - the PEM encoded certificate

The PEM encoded certificate.

csr_serial - serial number of the processed csr

Optional Keys

ca_identifier - the identifier of the issuing ca

Identifier of the issuer certificate, if not set the method tries to autodetect it by searching the certificate table for a certificate matching the authority key identifier. If the certificate has no authority key identifier set, the lookup is done on the the issuer dn.

If no match is found, the chain parameter is evaluated.

If no issuer identifier can be found, it is set to unknown.

chain - array ref holding the chain as PEM blocks

For implementations working with external issuers, this provides an alternative to complete the issuer chain. Passes the parameter as input to the "__import_chain" method.

__fetchPersistedCertificateInformation

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

__import_chain

Expects a list of PEM encoded certificates to import. The first item must be the entity certificate. Import must be activated by setting the import_chain parameter, imported entities can be registered as a new alias setting the register_issuer parameter.

Class Attributes

The following class attributes can to be set from the implementing class to modify internal behaviour.

import_chain

Default is none which deactivates any import of chain certificates, valid values are all which also imports missing root certificates and chain which requires the root exist in the database.

register_issuer

Default is empty, needs to be set to the name of an alias group.

If a new entity is imported into the database by "import_chain", it is added to the alias group given as register_issuer.

Note: auto registration of a "new" issuer is not run if the certificate already exists in the database.

issue/renew Certificate

The request information must be taken from the csr and csr_attributes tables.

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