signoAPI Android – Zertifikatsverwaltung – Klassenübersicht

Klasse STCertificateManager

Die Klasse STCertificateManager ist zuständig für die Übergabe von Schlüsseln und Zertifikaten zur Verschlüsselung der Biometrie und zur Signatur von Dokumenten. Die Zertifikate und Schlüssel können mithilfe verschiedener Methoden flexibel in unterschiedlichen Formaten übergeben werden (z. B. als Byte-Array, Certificate-Objekt oder PrivateKey-Objekt). Die Klasse ist Bestandteil der libSignoPDFSigner.

Die Methoden dieser Klasse ersetzen die veralteten Methoden STSignoSigner.setCertificates() und STSignoViewer.setCertificates().

Methode getCertificateManager

Von der Klasse STCertificateManager existiert nur eine einzige Instanz (Singletoninstanz), auf die durch diese statische Methode zugegriffen werden kann.

Java

public static STCertificateManager getCertificateManager();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
STCertificateManager	Die Singletoninstanz der STCertificateManager-Klasse.

Anwendung:

Java

STCertificateManager certificateManager = STCertificateManager.getCertificateManager();

Methode setCertificates

Mit den folgenden Methoden können die Schlüssel und Zertifikate zum Verschlüsseln der Biometrie und zum Signieren des Dokuments Methoden flexibel in unterschiedlichen Formaten übergeben werden.

Java

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

Parameter	Bedeutung
byte[] signingCertificateAsPKCS12	PKCS#12-Datei als Byte-Array mit dem privaten Schlüssel und dem öffentlichen Zertifikat zum Signieren des Dokuments.
String pkcs12Password	Passwort der PKCS#12-Datei. Wird ignoriert, wenn für signingCertificateAsPKCS12 null übergeben wird.
byte[] biometricCertificate	X.509-Zertifikat als Byte-Array mit dem öffentlichen Schlüssel zum Verschlüsseln der Biometrie.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse.

Anwendung:

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	Bedeutung
byte[] signingKey	Privater Schlüssel als Byte-Array zum Signieren des Dokuments.
byte[] signingCertificate	X.509-Zertifikat als Byte-Array zum Signieren des Dokuments.
byte[] biometricCertificate	X.509-Zertifikat als Byte-Array mit dem öffentlichen Schlüssel zum Verschlüsseln der Biometrie.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Java

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

Parameter	Bedeutung
PrivateKey signingKey	Privater Schlüssel in Form eines java.security.PrivateKey-Objekts zum Signieren des Dokuments.
byte[] signingCertificate	X.509-Zertifikat als Byte-Array zum Signieren des Dokuments.
byte[] biometricCertificate	X.509-Zertifikat als Byte-Array mit dem öffentlichen Schlüssel zum Verschlüsseln der Biometrie.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Java

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

Parameter	Bedeutung
PrivateKey signingKey	Privater Schlüssel in Form eines java.security.PrivateKey-Objekts zum Signieren des Dokuments.
Certificate signingCertificate	X.509-Zertifikat in Form eines java.security.cert.Certificate-Objekts zum Signieren des Dokuments.
byte[] biometricCertificate	X.509-Zertifikat als Byte-Array mit dem öffentlichen Schlüssel zum Verschlüsseln der Biometrie.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Anwendung:

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());
}

Methode setSigningCertificate

Mit diesen Methoden können der private Schlüssel und das Zertifikat zum Signieren des Dokuments Methoden übergeben werden.

Java

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

Parameter	Bedeutung
PrivateKey signingKey	Privater Schlüssel in Form eines java.security.PrivateKey-Objekts zum Signieren des Dokuments.
Certificate signingCertificate	X.509-Zertifikat in Form eines java.security.cert.Certificate-Objekts zum Signieren des Dokuments.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Java

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

Parameter	Bedeutung
PrivateKey signingKey	Privater Schlüssel in Form eines java.security.PrivateKey-Objekts zum Signieren des Dokuments.
byte[] signingCertificate	X.509-Zertifikat als Byte-Array zum Signieren des Dokuments.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Java

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

Parameter	Bedeutung
byte[] signingKey	Privater Schlüssel als Byte-Array zum Signieren des Dokuments.
byte[] signingCertificate	X.509-Zertifikat als Byte-Array zum Signieren des Dokuments.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Anwendung:

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	Bedeutung
byte[] signingCertificateAsPKCS12	PKCS#12-Datei als Byte-Array mit dem privaten Schlüssel und dem öffentlichen Zertifikat zum Signieren des Dokuments.
String pkcs12Password	Passwort der PKCS#12-Datei. Wird ignoriert, wenn für signingCertificateAsPKCS12 null übergeben wird.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Anwendung:

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());
}

Methode setBiometricCertificate

Mit dieser Methode kann das Zertifikat zum Verschlüsseln der Biometrie übergeben werden.

Java

void setBiometricCertificate(byte[] biometricCertificate) throws STCerticateException;

Parameter	Bedeutung
byte[] biometricCertificate	X.509-Zertifikat als Byte-Array mit dem öffentlichen Schlüssel zum Verschlüsseln der Biometrie.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Anwendung:

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());
}

Methode hasSigningCertificate

Mit dieser Methode kann überprüft werden, ob ein Zertifikat und der dazugehörige private Schlüssel zum Signieren des Dokuments über die dafür vorgesehenen Set-Methoden gesetzt wurde.

Java

public boolean hasSigningCertificate();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
boolean	true	Das Zertifikat und der dazugehörige private Schlüssel zum Signieren des Dokuments sind vorhanden.
	false	Das Zertifikat und der dazugehörige private Schlüssel zum Signieren des Dokuments sind nicht vorhanden.

Anwendung:

Java

boolean hasSigningCertificate = certificateManager.hasSigningCertificate();

Methode hasBiometricCertificate

Mit dieser Methode kann überprüft werden, ob ein Zertifikat zur Verschlüsselung der Biometrie über die dafür vorgesehenen Set-Methoden gesetzt wurde.

Java

public boolean hasBiometricCertificate();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
booelan	true	Das Zertifikat zum Verschlüsseln der Biometrie ist vorhanden.
	false	Das Zertifikat zum Verschlüsseln der Biometrie ist nicht vorhanden.

Anwendung:

Java

boolean hasBiometricCertificate = certificateManager.hasBiometricCertificate();

Klasse STCertificateException

Die Klasse STCertificateException wird typischerweise von Methoden geworfen, die Zertifikate entgegennehmen und signalisiert einen Fehler bei der Verarbeitung von Zertifikaten innerhalb der Signaturfunktionalität. Die Exception wird ausgelöst, wenn die übergebenen Zertifikate nicht korrekt verarbeitet werden können oder gegen die Validierungsregeln des API verstoßen.

Dies betrifft insbesondere Fehler bei der Übergabe, Validierung oder Konsistenzprüfung von Zertifikaten und stellt sicher, dass keine fehlerhafte oder unsichere Signatur verarbeitet wird. Der entsprechende Fehler und die Fehlermeldung können mit den Methoden STCertificateException.getCertificateError() und STCertificateException.getMessage() bzw. STCertificateException.getLocalizedMessage() abgefragt werden.

Typische Ursachen

Das Zertifikat ist ungültig, beschädigt oder falsch formatiert
Das Signierzertifikat passt nicht zum zugehörigen privaten Schlüssel
Das Signierzertifikat ist abgelaufen
Fehler bei biometrischen Zertifikaten (z. B. ungültiges Biometriezertifikat)

Methode getCertificateError

Diese Methode gibt den aufgetretenen Zertifikatfehler zurück, der während der Verarbeitung oder Validierung der Zertifikate festgestellt wurde.

Java

public STCertificateError getCertificateError();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
STCertificateError	Instanz der STCertificateError-Klasse

Anwendung:

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());
}

Klasse STCertificateError

Die Enumeration STCertificateError ist wie folgt definiert:

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,
}

Zertifikatfehler	Bedeutung
INVALID_KEYSTORE_PASSWORD	Das Passwort für den Keystore (PKCS12) ist ungültig oder falsch.
INVALID_KEYSTORE	Der Keystore (PKCS12) ist beschädigt oder nicht korrekt formatiert.
INVALID_PRIVATE_KEY	Der private Schlüssel ist ungültig oder fehlerhaft.
INVALID_SIGNING_CERTIFICATE	Das Signierzertifikat ist ungültig oder fehlerhaft.
INVALID_BIOMETRIC_CERTIFICATE	Das biometrische Zertifikat ist ungültig oder fehlerhaft.
EXPIRED_SIGNING_CERTIFICATE	Das Signierzertifikat ist abgelaufen.
CERTIFICATE_KEY_VALIDATION_ERROR	Das Signierzertifikat und der private Schlüssel passen nicht zusammen oder sind ungültig.
UNDEFINED	Unbekannter Fehler.