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

FreeBSD Manual Pages

  
 
  

home | help
OpenXPKI::Server::NICEUser Contributed Perl DocumentaOpenXPKI::Server::NICE(3)

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.

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

Name | Description | API Functions | internal helper functions | Implementors Guide | issue/renew Certificate

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

home | help