Interface CertificateManagementService

All Known Implementing Classes:

CertificateManagementServiceImpl

public interface CertificateManagementService

Interface that encapsulates all certificate and key-related operations available within the XIMA formcycle certificate module. This service provides methods for generating, importing, exporting, and managing certificates and keys.

Since:

8.5.0

Method Summary

Modifier and Type	Method	Description
void	deleteCertificate(Long id, CertificateManagementUser user)	Deletes a certificate from the system.
void	exportCertificate(Long certificateId, OutputStream os, ECertificateFileType fileType, CertificateManagementUser user)	Exports a certificate to the specified output stream.
void	exportCSR(Long certificateId, OutputStream os, ECsrFileType fileType, CertificateManagementUser user)	Exports a Certificate Signing Request (CSR) to the specified output stream.
void	exportKeyPair(Long certificateId, OutputStream os, char[] password, EKeyPairFileType fileType, CertificateManagementUser user)	Exports a key pair (both public and private keys) of a certificate to the specified output stream.
void	exportPrivateKey(Long certificateId, OutputStream os, char[] password, EPrivateKeyFileType fileType, CertificateManagementUser user)	Exports the private key of a certificate to the specified output stream.
void	exportPublicKey(Long certificateId, OutputStream os, EPublicKeyFileType fileType, CertificateManagementUser user)	Exports the public key of a certificate to the specified output stream.
Optional<CertificateInfoDTO>	findById(Long certificateId, CertificateManagementUser user)	Retrieves the certificate with the specified ID.
@NotNull List<CertificateInfoDTO>	findValidCertificatesForSubject(CertificateSelectionBySubjectQuery query, CertificateManagementUser user)	Retrieves all valid certificates for a given subject within a defined scope.
@NotNull List<CertificateInfoDTO>	findValidCertificatesForUsageSubject(CertificateSelectionByUsageSubjectQuery query, CertificateManagementUser user)	Retrieves all valid client certificates for a given usage subject within a defined scope.
@NotNull CertificateInfoDTO	generateCertificate(X501DistinguishedName certificateSubject, Duration certificateValidity, IKeyPairGenerationSpec keyPairGenerationSpec, List<ICertificateUsageSpecification> certificateUsageSpecifications, KeyStoreSelector keyStoreSelector, boolean autoRenew, CertificateManagementUser user)	Generates a self-signed certificate with the given specifications.
@NotNull CertificateInfoDTO	generateCertificate(X501DistinguishedName certificateSubject, Duration certificateValidity, IKeyPairGenerationSpec keyPairGenerationSpec, List<ICertificateUsageSpecification> certificateUsageSpecifications, Long signingAuthorityId, KeyStoreSelector keyStoreSelector, boolean autoRenew, CertificateManagementUser user)	Generates a certificate with the given specifications.
@NotNull Optional<CertificateInfoDTO>	getCurrentValidCertificateForSubject(CertificateSelectionBySubjectQuery query, CertificateManagementUser user)	Retrieves the current valid certificate for the given subject within a defined scope.
@NotNull Optional<CertificateInfoDTO>	getCurrentValidCertificateForUsageSubject(CertificateSelectionByUsageSubjectQuery query, CertificateManagementUser user)	Retrieves the current valid certificate for the given usage subject within a defined scope.
static CertificateManagementService	getInstance()	Retrieves the singleton instance of the CertificateManagementService.
FileImportResult	importCryptographicCredentials(InputStream is, FileImportSpecification fileImportSpecification, KeyStoreSelector keyStoreSelector, CertificateManagementUser user)	Universal method to import a file into the keystore.
FileImportResult	importCryptographicCredentials(InputStream is, KeyStoreSelector keyStoreSelector, CertificateManagementUser user)	Universal method to import a file into the keystore.
CertificateInfoDTO	renewCertificate(Long certificateId, CertificateManagementUser user)	Renews a certificate by generating a new certificate with the same subject and key pair.
CertificateInfoDTO	update(CertificateInfoDTO certificate, CertificateManagementUser user)	Updates the metadata of a certificate.

Method Details

getInstance

static CertificateManagementService getInstance()

Retrieves the singleton instance of the CertificateManagementService. This method uses CDI to obtain the instance.

Returns:

The singleton instance of the CertificateManagementService.

deleteCertificate

void deleteCertificate(Long id,
 CertificateManagementUser user)
                throws FcCertificateManagementException

Deletes a certificate from the system.

Note: This method will also delete the keystore it is assigned to if it is the last entry in the keystore.

Parameters:

id - the ID of the certificate to delete.

user - the user deleting the certificate.

Throws:

FcCertificateManagementException - if an error occurs during certificate deletion or the user does not have permission to delete the certificate.

exportCSR

void exportCSR(Long certificateId,
 OutputStream os,
 ECsrFileType fileType,
 CertificateManagementUser user)
        throws IOException,
FcCertificateManagementException

Exports a Certificate Signing Request (CSR) to the specified output stream.

Parameters:

certificateId - the ID of the certificate for which the CSR will be exported.

os - the output stream to write the CSR data to.

fileType - the file type to export the CSR as.

user - the user who is exporting the CSR.

Throws:

IOException - if an I/O error occurs during export.

FcCertificateManagementException - if an error occurs during CSR export (e.g. the certificate could not be found or has no CSR, which is the case for externally imported certificates) or the user does not have permission to export the CSR.

exportCertificate

void exportCertificate(Long certificateId,
 OutputStream os,
 ECertificateFileType fileType,
 CertificateManagementUser user)
                throws IOException,
FcCertificateManagementException

Exports a certificate to the specified output stream.

Parameters:

certificateId - the ID of the certificate to export.

os - the output stream to write the certificate data to.

fileType - the file type to export the certificate as.

user - the user who is exporting the certificate.

Throws:

IOException - if an I/O error occurs during export.

FcCertificateManagementException - if an error occurs during certificate export (e.g. the certificate could not be found or the user does not have permission to export the certificate).

exportKeyPair

void exportKeyPair(Long certificateId,
 OutputStream os,
 char[] password,
 EKeyPairFileType fileType,
 CertificateManagementUser user)
            throws IOException,
FcCertificateManagementException

Exports a key pair (both public and private keys) of a certificate to the specified output stream.

Parameters:

certificateId - the ID of the certificate whose key pair will be exported.

os - the output stream to write the key pair data to.

password - the password to protect the exported key pair.

fileType - the file type to export the key pair as.

user - the user who is exporting the key pair.

Throws:

IOException - if an I/O error occurs during export.

FcCertificateManagementException - if an error occurs during key pair export (e.g. the certificate could not be found or the user does not have permission to export the key pair).

exportPrivateKey

void exportPrivateKey(Long certificateId,
 OutputStream os,
 char[] password,
 EPrivateKeyFileType fileType,
 CertificateManagementUser user)
               throws IOException,
FcCertificateManagementException

Exports the private key of a certificate to the specified output stream.

Parameters:

certificateId - the ID of the certificate whose private key will be exported.

os - the output stream to write the private key data to.

password - the password to protect the exported private key.

fileType - the file type to export the private key as.

user - the user who is exporting the private key.

Throws:

IOException - if an I/O error occurs during export.

FcCertificateManagementException - if an error occurs during private key export (e.g. the certificate could not be or the user does not have permission to export the private key).

exportPublicKey

void exportPublicKey(Long certificateId,
 OutputStream os,
 EPublicKeyFileType fileType,
 CertificateManagementUser user)
              throws IOException,
FcCertificateManagementException

Exports the public key of a certificate to the specified output stream.

Parameters:

certificateId - the ID of the certificate whose public key will be exported.

os - the output stream to write the public key data to.

fileType - the file type to export the public key as.

user - the user who is exporting the public key.

Throws:

IOException - if an I/O error occurs during export.

FcCertificateManagementException - if an error occurs during public key export (e.g. the certificate could not be found or the user does not have permission to export the public key).

findById

Optional<CertificateInfoDTO> findById(Long certificateId,
 CertificateManagementUser user)
                               throws FcCertificateManagementException

Retrieves the certificate with the specified ID.

Parameters:

certificateId - the ID of the certificate to retrieve.

user - the user who is requesting the certificate.

Returns:

an Optional containing the CertificateInfoDTO object with the specified ID.

Throws:

FcCertificateManagementException - if the user does not have permission to access the certificate.

IllegalArgumentException - if the certificateId is null or less than 1.

findValidCertificatesForSubject

@NotNull
@NotNull List<CertificateInfoDTO> findValidCertificatesForSubject(CertificateSelectionBySubjectQuery query,
 CertificateManagementUser user)
                                                           throws FcCertificateManagementException

Retrieves all valid certificates for a given subject within a defined scope.

Parameters:

query - the CertificateSelectionBySubjectQuery defining the subject, scope and optionally further criteria to filter the certificates (e.g. usage types, algorithms, etc.).

user - the user requesting the certificates.

Returns:

a list of CertificateInfoDTO objects representing the valid client certificates that match the given criteria.

Throws:

FcCertificateManagementException - if an error occurs during the search or the user does not have permission to access the certificates.

findValidCertificatesForUsageSubject

@NotNull
@NotNull List<CertificateInfoDTO> findValidCertificatesForUsageSubject(CertificateSelectionByUsageSubjectQuery query,
 CertificateManagementUser user)
                                                                throws FcCertificateManagementException

Retrieves all valid client certificates for a given usage subject within a defined scope. This is in contrast to findValidCertificatesForSubject(CertificateSelectionBySubjectQuery, CertificateManagementUser), which retrieves the certificates by their subject, and not by their usage subject.

Parameters:

query - the CertificateSelectionByUsageSubjectQuery defining the usage subject, scope and optionally further criteria to filter the certificates (e.g. key algorithm, private key presence, etc.).

user - the user requesting the certificates.

Returns:

a list of CertificateInfoDTO objects representing the valid client certificates that match the given criteria.

Throws:

FcCertificateManagementException - if an error occurs during the search or the user does not have permission to access the certificates.

generateCertificate

@NotNull
@NotNull CertificateInfoDTO generateCertificate(X501DistinguishedName certificateSubject,
 Duration certificateValidity,
 IKeyPairGenerationSpec keyPairGenerationSpec,
 List<ICertificateUsageSpecification> certificateUsageSpecifications,
 Long signingAuthorityId,
 KeyStoreSelector keyStoreSelector,
 boolean autoRenew,
 CertificateManagementUser user)
                                         throws FcCertificateManagementException

Generates a certificate with the given specifications.

Parameters:

certificateSubject - the subject information for the certificate.

certificateValidity - the validity period of the certificate.

keyPairGenerationSpec - the specifications for generating the key pair, including the algorithm and algorithm-specific settings.

certificateUsageSpecifications - the (optional) usage specification the certificate will be used (e.g. SMIME certificate with email addresses).

signingAuthorityId - the ID of the signing authority that will sign the certificate.

keyStoreSelector - the keystore selector, defining the keystore where the key pair will be stored.

autoRenew - whether the certificate should be automatically renewed before it expires.

user - the user generating the key pair and certificate.

Returns:

a CertificateInfoDTO object containing information about the generated certificate.

Throws:

FcCertificateManagementException - if an error occurs during certificate generation or the user does not have permission to generate the certificate.

generateCertificate

@NotNull
@NotNull CertificateInfoDTO generateCertificate(X501DistinguishedName certificateSubject,
 Duration certificateValidity,
 IKeyPairGenerationSpec keyPairGenerationSpec,
 List<ICertificateUsageSpecification> certificateUsageSpecifications,
 KeyStoreSelector keyStoreSelector,
 boolean autoRenew,
 CertificateManagementUser user)
                                         throws FcCertificateManagementException

Generates a self-signed certificate with the given specifications.

Parameters:

certificateSubject - the subject information for the certificate.

certificateValidity - the validity period of the certificate.

keyPairGenerationSpec - the specifications for generating the key pair, including the algorithm and algorithm-specific settings.

certificateUsageSpecifications - the (optional) usage specification the certificate will be used (e.g. SMIME certificate with email addresses).

keyStoreSelector - the keystore selector, defining the keystore where the key pair will be stored.

autoRenew - whether the certificate should be automatically renewed before it expires.

user - the user generating the key pair and certificate.

Returns:

a CertificateInfoDTO object containing information about the generated certificate.

Throws:

FcCertificateManagementException - if an error occurs during certificate generation or the user does not have permission to generate the certificate.

getCurrentValidCertificateForSubject

@NotNull
@NotNull Optional<CertificateInfoDTO> getCurrentValidCertificateForSubject(CertificateSelectionBySubjectQuery query,
 CertificateManagementUser user)
                                                                    throws FcCertificateManagementException

Retrieves the current valid certificate for the given subject within a defined scope.

CertificateSelectionBySubjectQuery.isPartialMatch() does not apply in this method; only exact matches are considered.

Parameters:

query - the CertificateSelectionBySubjectQuery defining the subject, scope and optionally further criteria to filter the certificates (e.g. usage types, algorithms, etc.).

user - the user requesting the certificate.

Returns:

an Optional containing the CertificateInfoDTO object if the certificate exists.

Throws:

FcCertificateManagementException - if an error occurs during the search or the user does not have permission to access the certificate.

getCurrentValidCertificateForUsageSubject

@NotNull
@NotNull Optional<CertificateInfoDTO> getCurrentValidCertificateForUsageSubject(CertificateSelectionByUsageSubjectQuery query,
 CertificateManagementUser user)
                                                                         throws FcCertificateManagementException

Retrieves the current valid certificate for the given usage subject within a defined scope. This is in contrast to getCurrentValidCertificateForSubject(CertificateSelectionBySubjectQuery, CertificateManagementUser), which retrieves the certificate by its subject, and not by its usage subject.

CertificateSelectionByUsageSubjectQuery.isPartialMatch() does not apply in this method; only exact matches are considered.

Parameters:

query - the CertificateSelectionByUsageSubjectQuery defining the usage subject, scope and optionally further criteria to filter the certificates (e.g. key algorithm, private key presence, etc.).

user - the user requesting the certificate.

Returns:

an Optional containing the CertificateInfoDTO object if the certificate exists.

Throws:

FcCertificateManagementException - if an error occurs during the search or the user does not have permission to access the certificate.

importCryptographicCredentials

FileImportResult importCryptographicCredentials(InputStream is,
 KeyStoreSelector keyStoreSelector,
 CertificateManagementUser user)
                                         throws IOException,
FcCertificateManagementException

Universal method to import a file into the keystore. The method will automatically detect the type of the file and import it accordingly. It is capable of importing all file types specified in the enum ECryptoFileFormat

Parameters:

is - the input stream containing the file data

keyStoreSelector - the selector, defining the keystore to import the file into

user - the user who is importing the file

Returns:

a FileImportResult object containing information about the imported file

Throws:

IOException - if an I/O error occurs during import

FcCertificateManagementException - if the file data has an invalid or unknown format or if a custom keystore could not be created

importCryptographicCredentials

FileImportResult importCryptographicCredentials(InputStream is,
 FileImportSpecification fileImportSpecification,
 KeyStoreSelector keyStoreSelector,
 CertificateManagementUser user)
                                         throws IOException,
FcCertificateManagementException

Universal method to import a file into the keystore. The method will automatically detect the type of the file and import it accordingly. It is capable of importing all file types specified in the enum ECryptoFileFormat

Parameters:

is - the input stream containing the file data

fileImportSpecification - the credentials for the import (e.g. in case of an encrypted file, where the file itself and/or the entries from the files are protected)

keyStoreSelector - the selector, defining the keystore to import the file into

user - the user who is importing the file

Returns:

a FileImportResult object containing information about the imported file

Throws:

IOException - if an I/O error occurs during import

IllegalArgumentException - if the fileImportSpecification is null and file data is in a keystore format

FcCertificateManagementException - if the file data has an invalid or unknown format or if a custom keystore could not be created

renewCertificate

CertificateInfoDTO renewCertificate(Long certificateId,
 CertificateManagementUser user)
                             throws FcCertificateManagementException

Renews a certificate by generating a new certificate with the same subject and key pair. This method will only succeed if the certificate has a private key associated with it!

If the certificate to be renewed is expired already, the new certificate will become the new default certificate for the associated key. Otherwise, the new certificate will be listed as the prepared replacement certificate.

Parameters:

certificateId - the ID of the certificate to renew.

user - the user renewing the certificate.

Returns:

a CertificateInfoDTO object containing information about the renewed certificate.

Throws:

FcCertificateManagementException - if an error occurs during certificate renewal (e.g. the certificate has no private key or could not be found in the database) or the user does not have permission to renew the certificate.

update

CertificateInfoDTO update(CertificateInfoDTO certificate,
 CertificateManagementUser user)
                   throws FcCertificateManagementException

Updates the metadata of a certificate. Only certain fields can be updated, such as the renewal strategy.

Parameters:

certificate - the CertificateInfoDTO object containing the updated certificate information. The ID field must be set to identify the certificate to update.

user - the user updating the certificate.

Returns:

a CertificateInfoDTO object containing information about the updated certificate.

Throws:

FcCertificateManagementException - if an error occurs during certificate update (e.g. the certificate could not be found in the database) or the user does not have permission to update the certificate.

IllegalArgumentException - if the certificate is null or its ID is null.