signoAPI Android – Certificate management – Class overview

STCertificateManager class

The STCertificateManager class is responsible for transferring keys and certificates for encrypting biometric data and signing documents. The certificates and keys can be transferred flexibly in different formats using various methods (e.g. as a byte array, Certificate object or PrivateKey object). The class is part of libSignoPDFSigner.

The methods of this class replace the deprecated STSignoSigner.setCertificates() and STSignoViewer.setCertificates() methods.

getCertificateManager method

There is only one instance of the STCertificateManager class (singleton instance), which can be accessed using this static method.

Java

public static STCertificateManager getCertificateManager();

Parameter	Description
-	-
Return value	Description
STCertificateManager	The singleton instance of the STCertificateManager class.

Usage:

Java

STCertificateManager certificateManager = STCertificateManager.getCertificateManager();

setCertificates method

With the following methods, the keys and certificates for encrypting the biometric data and for signing the document can be transferred flexibly in different formats.

Java

void setCertificates(byte[] signingCertificateAsPKCS12, String pkcs12Password, byte[] biometricCertificate) throws STCerticateException;

Parameter	Description
byte[] signingCertificateAsPKCS12	PKCS#12 file as a byte array, with the private key and the public certificate for signing the document.
String pkcs12Password	Password for PKCS#12 file. Is ignored if null is transferred for signingCertificateAsPKCS12.
byte[] biometricCertificate	X.509 certificate as a byte array, with the public key for encrypting the biometrics.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class.

Usage:

Java

try {
    certificateManager.setCertificates(signCertificate, @"Password", bioCertificate);
} catch (STCertificateException certException) {
    STCertificateError certError = certException.getCertificateError();
    if (certError == STCertificateError.EXPIRED_SIGNING_CERTIFICATE) {
      // Certificate is expired. Show user message here.
    } else if (certError == STCertificateError.INVALID_KEYSTORE_PASSWORD) {
      // Password is wrong. Show user message here.
    }
    Log.d("CertificateError", certException.getLocalizedMessage());
}

Java

void setCertificates(byte[] signingKey, byte[] signingCertificate, byte[] biometricCertificate) throws STCerticateException;

Parameter	Description
byte[] signingKey	Private key as a byte array for signing the document.
byte[] signingCertificate	X.509 certificate as a byte array for signing the document.
byte[] biometricCertificate	X.509 certificate as a byte array, with the public key for encrypting the biometrics.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Java

void setCertificates(PrivateKey signingKey, byte[] signingCertificate, byte[] biometricCertificate) throws STCerticateException;

Parameter	Description
PrivateKey signingKey	Private key in the form of a java.security.PrivateKey object for signing the document.
byte[] signingCertificate	X.509 certificate as a byte array for signing the document.
byte[] biometricCertificate	X.509 certificate as a byte array, with the public key for encrypting the biometrics.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Java

void setCertificates(PrivateKey signingKey, Certificate signingCertificate, byte[] biometricCertificate) throws STCerticateException;

Parameter	Description
PrivateKey signingKey	Private key in the form of a java.security.PrivateKey object for signing the document.
Certificate signingCertificate	X.509 certificate in the form of a java.security.cert.Certificate object for signing the document.
byte[] biometricCertificate	X.509 certificate as a byte array, with the public key for encrypting the biometrics.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Usage:

Java

try {
    certificateManager.setCertificates(signingKey, signingCertificate, biometricCertificate);
} catch (STCertificateException certException) {
    STCertificateError certError = certException.getCertificateError();
    if (certError == STCertificateError.EXPIRED_SIGNING_CERTIFICATE) {
      // Certificate is expired. Show user message here.
    } else if (certError == STCertificateError.INVALID_KEYSTORE_PASSWORD) {
      // Password is wrong. Show user message here.
    }
    Log.d("CertificateError", certException.getLocalizedMessage());
}

setSigningCertificate method

These methods can be used to transfer the private key and the certificate for signing the document.

Java

void setSigningCertificate(PrivateKey signingKey, Certificate signingCertificate) throws STCerticateException;

Parameter	Description
PrivateKey signingKey	Private key in the form of a java.security.PrivateKey object for signing the document.
Certificate signingCertificate	X.509 certificate in the form of a java.security.cert.Certificate object for signing the document.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Java

void setSigningCertificate(PrivateKey signingKey, byte[] signingCertificate) throws STCerticateException;

Parameter	Description
PrivateKey signingKey	Private key in the form of a java.security.PrivateKey object for signing the document.
byte[] signingCertificate	X.509 certificate as a byte array for signing the document.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Java

void setSigningCertificate(byte[] signingKey, byte[] signingCertificate) throws STCerticateException;

Parameter	Description
byte[] signingKey	Private key as a byte array for signing the document.
byte[] signingCertificate	X.509 certificate as a byte array for signing the document.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Usage:

Java

try {
    certificateManager.setSigningCertificate(signingKey, signingCertificate);
} catch (STCertificateException certException) {
    STCertificateError certError = certException.getCertificateError();
    if (certError == STCertificateError.CERTIFICATE_KEY_VALIDATION_ERROR) {
      // Signing certificate and private key mismatch or invalid.
      // Show user message here.
    } else if (certError == STCertificateError.INVALID_PRIVATE_KEY) {
      // Private key is invalid. Show user message here.
    }
    Log.d("CertificateError", certException.getLocalizedMessage());
}

Java

void setSigningCertificate(byte[] signingCertificateAsPKCS12, String pkcs12Password) throws STCerticateException;

Parameter	Description
byte[] signingCertificateAsPKCS12	PKCS#12 file as a byte array, with the private key and the public certificate for signing the document.
String pkcs12Password	Password for PKCS#12 file. Is ignored if null is transferred for signingCertificateAsPKCS12.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Usage:

Java

try {
    certificateManager.setSigningCertificate(signCertificate, @"Password");
} catch (STCertificateException certException) {
    STCertificateError certError = certException.getCertificateError();
    if (certError == STCertificateError.EXPIRED_SIGNING_CERTIFICATE) {
      // Certificate is expired. Show user message here.
    } else if (certError == STCertificateError.INVALID_KEYSTORE_PASSWORD) {
      // Password is wrong. Show user message here.
    }
    Log.d("CertificateError", certException.getLocalizedMessage());
}

setBiometricCertificate method

This method can be used to transfer the certificate for encrypting the biometric data.

Java

void setBiometricCertificate(byte[] biometricCertificate) throws STCerticateException;

Parameter	Description
byte[] biometricCertificate	X.509 certificate as a byte array, with the public key for encrypting the biometrics.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Usage:

Java

try {
    certificateManager.setBiometricCertificate(bioCertificate);
} catch (STCertificateException certException) {
    STCertificateError certError = certException.getCertificateError();
    if (certError == STCertificateError.INVALID_BIOMETRIC_CERTIFICATE) {
      // Biometric certificate is invalid. Show user message here.
    }
    Log.d("CertificateError", certException.getLocalizedMessage());
}

hasSigningCertificate method

This method can be used to check whether a certificate and the corresponding private key for signing the document have been set using the set methods provided for this purpose.

Java

public boolean hasSigningCertificate();

Parameter	Description
-	-
Return value	Description
boolean	true	The certificate and the corresponding private key for signing the document are available.
	false	The certificate and the corresponding private key for signing the document are not available.

Usage:

Java

boolean hasSigningCertificate = certificateManager.hasSigningCertificate();

hasBiometricCertificate method

This method can be used to check whether a certificate has been set for encrypting biometric data using the set methods provided for this purpose.

Java

public boolean hasBiometricCertificate();

Parameter	Description
-	-
Return value	Description
booelan	true	The certificate for encrypting biometric data is available.
	false	The certificate for encrypting biometric data is not available.

Usage:

Java

boolean hasBiometricCertificate = certificateManager.hasBiometricCertificate();

STCertificateException class

The STCertificateException class is typically thrown by methods that accept certificates and signals an error in the processing of certificates within the signature functionality. The exception is triggered if the transferred certificates cannot be processed correctly or violate the API's validation rules.

This applies in particular to errors in the transfer, validation or consistency check of certificates and ensures that no incorrect or insecure signatures are processed. The corresponding error and error message can be queried using the STCertificateException.getCertificateError() and STCertificateException.getMessage() or STCertificateException.getLocalizedMessage() methods.

Common causes

The certificate is invalid, damaged or incorrectly formatted.
The signing certificate does not match the corresponding private key.
The signing certificate has expired.
Errors with biometric certificates (e.g. invalid biometric certificate)

getCertificateError method

This method returns the certificate error that occurred during the processing or validation of the certificates.

Java

public STCertificateError getCertificateError();

Parameter	Description
-	-
Return value	Description
STCertificateError	Instance of the STCertificateError class

Usage:

Java

try {
    certificateManager.setSigningCertificate(signCertificate, @"Password");
} catch (STCertificateException certException) {
    STCertificateError certError = certException.getCertificateError();
    if (certError == STCertificateError.EXPIRED_SIGNING_CERTIFICATE) {
      // Certificate is expired. Show user message here.
    } else if (certError == STCertificateError.INVALID_KEYSTORE_PASSWORD) {
      // Password is wrong. Show user message here.
    }
    Log.d("CertificateError", certException.getLocalizedMessage());
}

STCertificateError class

The enumeration STCertificateError is defined as follows:

Java

public enum STCertificateError {
    INVALID_KEYSTORE_PASSWORD,
    CERTIFICATE_KEY_VALIDATION_ERROR,
    INVALID_KEYSTORE,
    INVALID_PRIVATE_KEY,
    INVALID_SIGNING_CERTIFICATE,
    INVALID_BIOMETRIC_CERTIFICATE,
    EXPIRED_SIGNING_CERTIFICATE,
    UNDEFINED,
}

Certificate error	Description
INVALID_KEYSTORE_PASSWORD	The password for the keystore (PKCS12) is invalid or incorrect.
INVALID_KEYSTORE	The keystore (PKCS12) is damaged or incorrectly formatted.
INVALID_PRIVATE_KEY	The private key is invalid or incorrect.
INVALID_SIGNING_CERTIFICATE	The signature certificate is invalid or incorrect.
INVALID_BIOMETRIC_CERTIFICATE	The biometric certificate is invalid or incorrect.
EXPIRED_SIGNING_CERTIFICATE	The signature certificate has expired.
CERTIFICATE_KEY_VALIDATION_ERROR	The signing certificate and private key do not match or are invalid.
UNDEFINED	Unknown error.