Avanpost FAM/MFA+ : 10.3. Разработка плагина аппаратной аутентификации (Linux Logon, Windows Logon, Agent)

10.3. Разработка плагина аппаратной аутентификации (Linux Logon, Windows Logon, Agent)

Описание интерфейса плагина

Заголовочный .h-файл предоставляет интерфейс для работы с устройствами смарт-карт.

Макросы 

МакросНазначение

PLUGINTOKENS_LIBRARY_H

Предпроцессорный макрос для условной компиляции.

Служит для обеспечения единственного включения кода из заголовочного файла и предотвращения проблем с повторным определением типов, функций и переменных


#ifndef PLUGINTOKENS_LIBRARY_H
#define PLUGINTOKENS_LIBRARY_H
<...>
#endif //PLUGINTOKENS_LIBRARY_H


_WINDOWS

Если макрос _WINDOWS определен (компилируется под Windows), то будет выполнено следующее условие внутри блока #ifdef. Если же макрос не определен (компилируется не под Windows), то будет выполнено условие после блока #else.

Правильный атрибут экспорта/импорта функций определяется с помощью __declspec(dllexport) или __declspec(dllimport)

#ifdef _WINDOWS
    #ifdef PLUGINTOKENS_EXPORTS
        #define PLUGINTOKENS_API extern "C" __declspec(dllexport)
    #else
        #define PLUGINTOKENS_API extern "C" __declspec(dllimport)
    #endif
#else
    #define PLUGINTOKENS_API extern "C"
#endif
PLUGINTOKENS_EXPORTS

Управляет экспортом или импортом функций

PLUGINTOKENS_API

Определяет атрибуты экспорта или импорта функций при работе с динамическими библиотеками (DLL) в зависимости от компиляционных настроек

CP_TRACE_ERROR			
CP_TRACE_INFO			
CP_TRACE_DEBUG			
CP_TRACE_HARD_DEBUG
Определяют уровни логирования
#define CP_TRACE_ERROR			3
#define CP_TRACE_INFO			5
#define CP_TRACE_DEBUG			7
#define CP_TRACE_HARD_DEBUG		10
MAX_DEVICE_COUNT

Определяет максимальное количество устройств

#define MAX_DEVICE_COUNT 20


Структуры

СтруктураНазначение
SPluginInfoСодержит информацию о плагине, включая его версию, официальный сайт и название компании
typedef struct {
	char version[100];
	char site[1024];
	char company[256];
} SPluginInfo;
SDeviceInfoСодержит информацию об устройстве смарт-карты, включая его идентификатор, серийный номер, идентификатор производителя, модель, метку, флаги, максимальную длину PIN-кода, минимальную длину PIN-кода и требование PIN-кода
typedef struct {
	char  id[32];

	char  serialNumber[100];
	char  manufacturerID[100];
	char  model[100];
	char  label[100];
	long  flags;

	int	  nlMaxPinLen;
	int   nlMinPinLen;
	bool  pin_required;

} SDeviceInfo;
SCertInfoСодержит информацию о сертификате, включая его представление в формате base64 и флаг, указывающий, является ли сертификат секретным ключом
typedef struct {
	const char *certBase64;
	bool isSecretKey;
} SCertInfo;
SDevicesСодержит список устройств в виде массива структур SDeviceInfo, а также количество устройств в массиве
typedef struct {
	SDeviceInfo* devices;
	int  count;
} SDevices;
SCertsСодержит список сертификатов в виде массива структур SCertInfo, а также количество сертификатов в массиве
typedef struct {
	SCertInfo* certs;
	int  count;
} SCerts;

Перечисление FactorsTypeПеречисляет поддерживаемые факторы для аутентификации
enum FactorsType : int {
	EMPTY = 0,
	PASSWORD = 1,
	TOTP = 2,
	SMS = 3,
	KERBEROS = 4,
	SMARTCARD = 5,
	EMAIL = 6,
	TELEGRAM = 7,
	PAYCONTROL = 8,
	AUTHENTICATOR = 9,
	QRSIGNIN = 10
};


Функции

Все функции объявлены с использованием макроса PLUGINTOKENS_API

ФункцияНазначениеПример  вызова
get_LastError()Возвращает код ошибки последней выполненной операции
PLUGINTOKENS_API int get_LastError();


get_PluginInfo()Возвращает информацию о плагине, включая его версию и другие сведения
PLUGINTOKENS_API SPluginInfo get_PluginInfo();


PluginInit()

Инициализирует плагин и принимает в качестве параметров уровень журналирования (LogLevel) и данные устройства или имя библиотеки PKCS11 с полным путем.

ETOKEN, RUTOKEN, RUTOKEN_ECP

Возвращает код лога


PLUGINTOKENS_API int PluginInit(int LogLevel, const char* data);


PluginFinalize()

Завершает работу плагина.

Нет возвращаемого значения.

PLUGINTOKENS_API void PluginFinalize();


get_PluginFactor()

Возвращает тип поддерживаемого фактора авторизации.

В данном случае SMARTCARD (5)

PLUGINTOKENS_API int get_PluginFactor();


get_DeviceInfo()

Возвращает информацию об указанном устройстве.

Принимает аргумент const char* id, представляющий идентификатор устройства

PLUGINTOKENS_API SDeviceInfo get_DeviceInfo(const char* id);


get_Devices()Возвращает список доступных устройств
PLUGINTOKENS_API SDevices get_Devices();


WaitDevice()Ожидает активности устройств с заданными параметрами, переданными в аргументе
PLUGINTOKENS_API SDevices WaitDevice(SDevices info);


DeviceAuth()

Выполняет авторизацию на устройстве.

Принимает два аргумента: const char* id и const char* pin, представляющие идентификатор и PIN-код для аутентификации устройства соответственно. Предназначена для аутентификации устройства и возвращает true, если аутентификация прошла успешно, и false в противном случае

PLUGINTOKENS_API bool DeviceAuth(const char* id, const char* pin);


GetCertificates()Возвращает список сертификатов с указанной карты
PLUGINTOKENS_API SCerts GetCertificates(const char* id, const char* pin);


AuthByCertificate()Выполняет подпись данных секретным ключом на карте в связке с сертификатом
PLUGINTOKENS_API char* AuthByCertificate(const char* id, const char* pin, SCerts certs, const char* data);


get_IsSupportData()

Выполняет проверку поддержки данных на устройстве.

Возвращает результат проверки (true или false)

PLUGINTOKENS_API bool get_IsSupportData(string id);



Обсуждение