surfer/openssl-act-engine/USING_ENGINE_act.txt

Benutzung der engine_act OpenSSL engine

Abgesehen von den Engine-Befehlen "ENUM_CERTS" und "PIN" (s.u.) läuft die Benutzung dieser Engine über OpenSSL selbst ab.

1) Laden/Einbinden

SO_PATH gibt den absoluten Pfad zur Engine an.

#include <openssl/engine.h>

	ENGINE *e;

    ENGINE_load_dynamic();
    e = ENGINE_by_id("dynamic");

    int r= ENGINE_ctrl_cmd_string(e, "SO_PATH", "C:\\Windows\\System32\\engine_act.dll", 0);
    r= ENGINE_ctrl_cmd_string(e, "ID", "act", 0);
    r= ENGINE_ctrl_cmd_string(e, "LIST_ADD", "1", 0);
    r= ENGINE_ctrl_cmd_string(e, "LOAD", NULL, 0);

2) Entfernen der Engine und abschliessende Operationen

    ENGINE_finish(e);
    ENGINE_cleanup();


3) Enumerierung der erreichbaren Smartcard-Zertifikate und Schlüssel

#include <openssl/engine.h>
#include "engine_sct.h"

	enum_certs_s* certs_found = NULL;
	
	int r = ENGINE_ctrl_cmd(e, "ENUM_CERTS", 0, &certs_found, NULL, 0);
	

enum_certs_s ist eine Struktur von der folgenden Form:

struct enum_cert_s
{
	const char*		id;				// ID which can be passed as key ID for crypto operations
	const char*		name;			// Alternatively one can use the name, provided it's unique for the token.
	X509*			cert;			// Decoded certificate
};

struct enum_certs_s
{
	unsigned int	num_certs;			// Number of certificates present
	enum_cert_s		certificate[];		// Array of identifiers and certificates
};


So kann man dann mit einer for-Schleife über die einzelnen Zertifikate/Schlüsselidentifikationen iterieren
	
	for(int i=0;i<certs_found->num_certs;i++)
	{
		enum_cert_s* cert_data = &(certs_found->certificate[i]);
	
		....
	}

4) Laden eines Schlüssels zur Benutzung

Sowohl cert_data.id als auch cert_data.name können als Parameter für ENGINE_load_public_key() oder ENGINE_load_private_key() verwendet werden.
cert_data.name hat das Format "slot-<x>-name-<name>", der Authenthisierungsschlüssel im ersten (oder einzigen) Slot wäre dann

"slot-0-name-SwissSign_digSig"

ENGINE_load_private_key() versucht gleich schon ein Login auf der Karte. Man kann ein Pin-Dialog per Callback übergeben, aber man kann auch
die PIN von vornherein setzen, und zwar mit

	ENGINE_ctrl_cmd_string(e, "PIN", pin_str, 0);

/!\ pin_str ist ein nullterminierter String (char *) und wird in der Funktion überschrieben! Wird die PIN also später anderswo noch gebraucht, muss man
hier eine Kopie des Strings übergeben.