База знаний FAM/MFA+ : Разработка плагина аппаратной аутентификации (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);