9.0:documentation:modules_crt:dev:certificate_manager

Certificate manager

Certificate manager is the main point through which you can execute active operations on managed certification authorities. The most important method is execute, which accepts CrtRequestDo. This method invokes (in a new transaction) the RequestEventType.EXECUTE event.

Synchronous case

By default, the following processors are called after execute method was invoked:

  1. RequestApproveProcessor - Ensures the start of the approval workflow process.
  2. After approval, is called a processor for call the certification authority. Depending on the type of operation in the request, the appropriate processor is called.
    • To generate the certificate RequestGenerateProcessor.
    • To extend the validity of the certificate RequestRenewProcessor.
    • To revocate the certificate RequestRevocateProcessor.
  3. If certificate atuhority works synchronously, the next "check state" processor is called (if works asynchronously, the event will be suppended). This processor ensures check of the request state. If request on the CA is already executed, then only sets state of the request to Executed. If request on the CA is not executed (asynchronouse case), calls the certificate authority again (for check current state). Depending on the type of operation in the request, the appropriate "check state" processor is called.
    • To generate the certificate RequestCheckStateGenerateProcessor.
    • To extend the validity of the certificate RequestCheckStateRenewProcessor.
    • To revocate the certificate RequestCheckStateRevocateProcessor.
  4. On the end is calls "after action" processor. This processor ensures save results of the action (parse, save certificates, change of the state). Depending on the type of operation in the request, the appropriate "after action" processor is called.
    • To generate the certificate RequestAfterGenerateProcessor.
    • To extend the validity of the certificate RequestAfterRenewProcessor.
    • To revocate the certificate RequestAfterRevocateProcessor.

Asynchronous case

By default, the following processors are called after execute method was invoked:

  1. RequestApproveProcessor - Ensures the start of the approval workflow process.
  2. After approval, is called a processor for call the certification authority. Depending on the type of operation in the request, the appropriate processor is called.
    • To generate the certificate RequestGenerateProcessor.
    • To extend the validity of the certificate RequestRenewProcessor.
    • To revocate the certificate RequestRevocateProcessor.
  3. If certificate authority works asynchronously, the event will be suppended.

Because the request was not executed yet (is in the state In progress), the we have to invoke the refresh method on the CertificateManager.

Refresh method works just like the execute method, event only start on the "check state" processor.

By default, the following processors are called after refresh method was invoked:

  1. If request on the CA is not executed (asynchronouse case), calls the certificate authority again (for check current state). If request is still not executed, the event will be suspended again. Depending on the type of operation in the request, the appropriate "check state" processor is called.
    • To generate the certificate RequestCheckStateGenerateProcessor.
    • To extend the validity of the certificate RequestCheckStateRenewProcessor.
    • To revocate the certificate RequestCheckStateRevocateProcessor.
  2. On the end is calls "after action" processor. This processor ensures save results of the action (parse, save certificates, change of the state). Depending on the type of operation in the request, the appropriate "after action" processor is called.
    • To generate the certificate RequestAfterGenerateProcessor.
    • To extend the validity of the certificate RequestAfterRenewProcessor.
    • To revocate the certificate RequestAfterRevocateProcessor.

Certificate manager interface

	/**
	 * Execute given persisted request - saves request and publish event
	 * 
	 * @param request
	 *            persisted requests
	 * @return persisted request - with appropriate state
	 */
        CrtRequestDto execute(CrtRequestDto request);
 
	/**
	 * Refresh given persisted request - saves request and publish event
	 * 
	 * @param request
	 *            persisted requests
	 * @return persisted request - with appropriate state
	 */
	CrtRequestDto refresh(CrtRequestDto request);
 
	/**
	 * Generate certificate from the request
	 * 
	 * @param request
	 * @return
	 */
	CrtDriverResponseDto generate(CrtRequestDto request);
 
	/**
	 * Method generate certificate by CSR (connected to the given request)
	 * 
	 * @param request
	 * @return
	 */
	CrtDriverResponseDto generateByCsr(CrtRequestDto request);
 
	/**
	 * Revocate certificate by given request. Request must have filled serial
	 * number, revocation reason and request type must be
	 * CertficateRequestType.REVOCATION.
	 * 
	 * @param serialNumber
	 * @return
	 */
	CrtDriverResponseDto revocate(CrtRequestDto request);
 
	/**
	 * Renew certificate. Request must have filled serial number and request type
	 * must be CertficateRequestType.RENEW.
	 * 
	 * @param serialNumber
	 * @return
	 */
	CrtDriverResponseDto renew(CrtRequestDto request);
 
	/**
	 * Validate certificate. Request must have filled serial number and request type
	 * must be CertficateRequestType.VALIDATE. If certificate isn't valid, then
	 * exception is throws.
	 * 
	 * @param validateRequest
	 * @return
	 */
	void validate(CrtRequestDto request);
 
	/**
	 * Return pair of certificate keys and certificate
	 * 
	 * @param request
	 * @return
	 */
	CrtKeyPairWithCertDto getKeyPairByRequest(CrtRequestDto request);
 
	/**
	 * Find certificate. Result may be filter by parameters.
	 * 
	 * @param parameters
	 * @param pageable
	 * @return
	 */
	Page<CrtCertificateDto> findCertificate(CrtCertificateFilter filter, Pageable pageable, CrtAuthorityDto authority);
 
	/**
	 * Return all supported drivers
	 * 
	 * @return
	 */
	List<CrtDriverDto> supportedDrivers();
 
	/**
	 * Find and return default instance of BaseDriver. This instance is not
	 * initialized (without setting configuration)
	 * 
	 * @param driverDto
	 * @return
	 */
	BaseDriver<DriverConfigurationClass> getDriver(CrtDriverDto driverDto);
 
	/**
	 * Upload public certificate
	 * 
	 * @param ownerId
	 * @param type
	 * @param fileName
	 * @param data
	 *            PEM data
	 * @return
	 */
	CrtCertificateDto upload(UUID ownerId, CertificateType type, String fileName, InputStream data);
 
	/**
	 * CSR file preview
	 * 
	 * @param requestId
	 * @return
	 */
	CsrPreviewDto getCsrPreview(UUID requestId);
 
	/**
	 * Check if was generate request already processed.
	 * 
	 * @param request
	 * @return
	 */
	CrtDriverResponseDto checkGenerateRequest(CrtRequestDto request);
 
	/**
	 * Check if was generate request already processed.
	 * 
	 * @param request
	 * @return
	 */
	CrtDriverResponseDto checkGenerateByCsrRequest(CrtRequestDto request);
 
	/**
	 * Check if was renew request already processed.
	 * 
	 * @param request
	 * @return
	 */
	CrtDriverResponseDto checkRenewRequest(CrtRequestDto request);
 
	/**
	 * Check if was revocate request already processed.
	 * 
	 * @param request
	 * @return
	 */
	CrtDriverResponseDto checkRevocateRequest(CrtRequestDto request);
 
	/**
	 * Parse and persist certificate (pem) and private key (pkcs12) to attachments
	 * 
	 * @param certificate
	 * @param keys
	 * @param request
	 */
	void uploadKeys(CrtCertificateDto certificate, CrtKeyPairWithCertDto keys, CrtRequestDto request);
 
	/**
	 * Upload certificate. Given certificate transforms to PEM format and persist
	 * him as certificate attachment.
	 * 
	 * @param certificate
	 * @param keys
	 * @return
	 */
	CrtCertificateDto uploadCertificate(CrtCertificateDto certificateDto, Certificate certificate);
 
	/**
	 * Return state of the certificate from the external CA.
	 * 
	 * @param request
	 * @param certificate
	 * @return
	 */
	CertificateState status(CrtRequestDto request, CrtCertificateDto certificate);
 
	/**
	 * Find initialised driver by certificate request
	 * 
	 * @param request
	 * @return
	 */
	BaseDriver<DriverConfigurationClass> findDriver(CrtRequestDto request);
 
	/**
	 * Find and return all approvers with a roles defined in the CA configuration.
	 * 
	 * @param request
	 * @return
	 */
	List<IdmIdentityDto> findApprovers(CrtRequestDto request);
 
	/**
	 * Validate certificate. First find the authority with same issuer, then check
	 * if is certificate signed by that authority and if is valid. Only if is
	 * certificate trusted and valid and is not revoked isn't throw exception.
	 * 
	 * @param data
	 */
	void validateByInputStream(InputStream data);
 
 
	/**
	 * Validate certificate. First find the authority with same issuer, then check
	 * if is certificate signed by that authority and if is valid. Only if is
	 * certificate trusted and valid and is not revoked isn't throw exception.
	 * 
	 * @param cert
	 *            Certificate to validate
	 * @param validateOnAuthority
	 *            If true, then will be call validate on the authority. Generally
	 *            it means, the validity will be check and CRL too. It means, if the
	 *            certificate is expired or is revocated, then exception will be
	 *            throw.
	 * @param validateValidity 
	 * 			  If true and certificate is expired, then exception will be throws.
	 */
	void validateByX509Certificate(X509Certificate cert, boolean validateOnAuthority, boolean validateValidity);
 
	/**
	 * Get certificate from the authority.
	 * @param authority
	 * @return
	 */
	InputStream getAuthorityCertificate(CrtAuthorityDto authority);