Firebird OO API | Interfaces De A À Z | Interfaces Principales | Plugin D’Authentification Côté Client

IServer

L`interface IServer est l`interface principale du plugin d`authentification.

authenticate
```
int authenticate(StatusType* status,
                 IServerBlock* sBlock,
                 IWriter* writerInterface)
```
Effectue une seule étape d’authentification. L’échange de données avec le client s’effectue à l’aide de l’interface sBlock. Lorsqu’un élément d’authentification est créé, il doit être ajouté au bloc d’authentification à l’aide de writerInterface. Les valeurs de retour possibles sont définies dans l’interface IAuth.
setDbCryptCallback
```
void setDbCryptCallback(StatusType* status, ICryptKeyCallback* cryptCallback)
```
Définit l’interface de rappel de chiffrement de base de données qui sera utilisée pour les connexions ultérieures à la base de données etServices.

plugin d’authentification côté client

IClientBlock

L’interface IClientBlock est utilisée par le côté client du module d’authentification pour communiquer avec le serveur.

getLogin
```
const char* getLogin()
```
Renvoie le nom d’utilisateur s’il est présent dans le DPB.
getPassword
```
const char* getPassword()
```
Renvoie le mot de passe s`il est présent dans le DPB.
getData
```
const unsigned char* getData(unsigned* length)
```
Renvoie les données d`authentification envoyées par le serveur.

putData

void putData(StatusType* status, unsigned length, const void* data)

Transmet les données d’authentification au serveur.

newKey
```
ICryptKey* newKey(StatusType* status)
```
Crée une nouvelle clé de chiffrement et l’ajoute à la liste des plugins de chiffrement du trafic réseau disponibles

getAuthBlock

IAuthBlock* getAuthBlock(StatusType* status)

IClient

L’interface IClient est l’interface principale côté client du module d’authentification.

authenticate
```
int authenticate(StatusType* status,
                 IClientBlock* cBlock)
```
Effectue une seule étape d’authentification. L’échange de données avec le serveur s’effectue à l’aide de l’interface cBlock. Les valeurs de retour possibles sont définies dans l’interface IAuth.AUTH_SUCCESS est traité par le côté client comme AUTH_MORE_DATA (c’est-à-dire que le client envoie les données générées au serveur et attend une réponse de celui-ci).

Plugin de gestion des utilisateurs

Ce plugin est activement lié au backend d’authentification – il prépare une liste d’utilisateurs pour le plugin d’authentification. Chaque plugin d’authentification nécessite un gestionnaire d’utilisateurs – certains d’entre eux peuvent accéder à une liste d’utilisateurs créés à l’aide d’un logiciel autre que Firebird (par exemple, AuthSspi). Un enregistrement de description utilisateur se compose de plusieurs champs et peut prendre en charge plusieurs opérations telles que l’ajout d’un utilisateur, la modification d’un utilisateur, la récupération d’une liste d’utilisateurs, etc. Le plugin doit être capable d’interpréter les commandes reçues dans l’interface IUser.

IUserField

L’interface IUserField n’est pas utilisée comme une interface autonome, c’est l’interface de base pour ICharUserField et IIntUserField.

entered
```
int entered()
```
Renvoie une valeur différente de zéro si une valeur a été saisie (affectée) au champ.
specified
```
int specified()
```
Renvoie une valeur différente de zéro si la valeur du champ a été affectée à NULL.
setEntered
```
void setEntered(StatusType* status, int newValue)
```
Définit l’indicateur saisi sur 0 ou une valeur différente de zéro pour le champ. Il n’y a aucun moyen d’assigner NULL à un champ car ce n’est jamais obligatoire.

NULL, S’ils sont utilisés, ils sont désignés par les implémentations comme des interfaces et ont donc un accès complet à leurs composants internes.

ICharUserField

Interface ICharUserField:

get
```
const char* get()
```
renvoie la valeur du champ sous la forme d’une chaîne C (borne \0).
set
```
void set(StatusType* status, const char* newValue)
```
Attribue une valeur au champ. Définit l’indicateur entré sur true.

IIntUserField

Interface IIntUserField:

get
```
int get()
```
Renvoie la valeur du champ.
set
```
void set(StatusType* status, int newValue)
```
Attribue une valeur au champ. Définit l’indicateur entré sur true.

IUser

L’interface IUser est une liste de méthodes permettant d’accéder aux champs inclus dans un enregistrement utilisateur.

operation
```
unsigned operation()
```
Opcode (voir la liste ci-dessous)
userName
```
ICharUserField* userName()
```
Nom d’utilisateur
password
```
ICharUserField* password()
```
mot de passe.
firstName
```
ICharUserField* firstName()
```
Ceci et les 2 composants suivants du nom d’utilisateur complet.
lastName
```
ICharUserField* lastName()
```
middleName
```
ICharUserField* middleName()
```
comment
```
ICharUserField* comment()
```
Commentaire (à partir de l’instruction SQL COMMENT ON USER IS…).
attributes
```
ICharUserField* attributes()
```
sous la forme tag1=val1, tag2=val2, …, tagN=valN. Val peut être vide, ce qui signifie que la balise sera supprimée.
active
```
IIntUserField* active()
```
Modifie le paramètre ACTIVE/INACTIVE pour l’utilisateur.
admin
```
IIntUserField* admin()
```
Définit/supprime les droits d’administrateur de l’utilisateur.
clear
```
void clear(StatusType* status)
```
Spécifie que tous les champs ne sont pas saisis ou spécifiés.

Les constantes définies par l’interface utilisateur sont les opcodes effectifs.

OP_USER_ADD — Ajouter un utilisateur.
OP_USER_MODIFY — Modifiez l’utilisateur.
OP_USER_DELETE — Supprimer un utilisateur.
OP_USER_DISPLAY — Affichage de l’utilisateur.
OP_USER_SET_MAP — Activez les administrateurs Windows pour mapper au rôle « RDB$ADMIN ».
OP_USER_DROP_MAP — désactivation de l`affichage des administrateurs Windows sur le rôle RDB$ADMIN.

IListUsers

Interface IListUsers — Il s’agit du callback utilisé par le plugin d’authentification lors de la demande d’une liste d’utilisateurs. Le plugin remplit l’interface IUser pour tous les éléments de la liste d’utilisateurs un par un, et appelle la méthode list() de l’interface pour chaque utilisateur.

list
```
void list(StatusType* status, IUser* user)
```
fonction de rappel. L’implémentation peut faire ce qu’elle veut avec les données reçues. Par exemple, il peut placer les données du paramètre utilisateur dans le flux de sortie du service, ou il peut les placer dans des tables spéciales SEC$ du groupe.

ILogonInfo

L’interface ILogonInfo contient les données transmises au plugin de gestion des utilisateurs pour se connecter à la base de données de sécurité avec des informations d’identification valides.

name
```
const char* name()
```
Renvoie le nom d’utilisateur de la connexion actuelle.
role
```
const char* role()
```
Renvoie le rôle actif de la connexion actuelle.
networkProtocol
```
const char* networkProtocol()
```
Renvoie le journal réseau de la connexion en cours. Non utilisé actuellement par les plugins.
remoteAddress
```
const char* remoteAddress()
```
Renvoie l’adresse distante de la connexion actuelle. Non utilisé actuellement par les plugins.
authBlock
```
const unsigned char* authBlock(unsigned* length)
```
Renvoie le bloc d’authentification de la connexion en cours. S’il n’est pas NULL, réécrit le nom d’utilisateur.

IConfig

Interface IConfig — L’interface générale du fichier de configuration.

find

IConfigEntry* find(StatusType* status, const char* name)

Recherche un enregistrement par son nom.

findValue

IConfigEntry* findValue(StatusType* status, const char* name, const char* value)

Recherche un enregistrement par son nom et sa valeur

findPos
```
IConfigEntry* findPos(StatusType* status, const char* name, unsigned pos)
```
Recherche un enregistrement par son nom et sa position. Si le fichier de configuration contient les lignes suivantes :
```
Db=DBA
Db=DBB
Db=DBC
```
l’appel de findPos(status, « Db », 2) renverra une entrée avec la valeur DBB.

IManagement

L’interface IManagement est l’interface principale du plugin de gestion des utilisateurs.

start
```
void start(StatusType* status, ILogonInfo* logonInfo)
```
exécute le plugin, si nécessaire, il se connecte à la base de données de sécurité pour gérer les utilisateurs (qu’il faille ou non utiliser cette solution dépend du plugin) en utilisant les informations d’identification de logonInfo.
execute
```
int execute(StatusType* status, IUser* user, IListUsers* callback)
```
Exécute la commande fournie par la méthode operation() du paramètre user.Si nécessaire, l’interface de rappel sera utilisée.Le paramètre callback peut être défini sur NULL pour les commandes qui ne nécessitent pas de liste d’utilisateurs.
commit
```
void commit(StatusType* status)
```
Prend en compte les modifications apportées par les appels à la méthode execute().
rollback
```
void rollback(StatusType* status)
```
Annule les modifications apportées par les appels à la méthode execute().

plugin de chiffrement de base de données

La possibilité de chiffrer la base de données est présente dans Firebird depuis l’époque d’Interbase, mais les endroits correspondants dans le code ont été commentés. La mise en œuvre était discutable : la clé de chiffrement était toujours envoyée du client au DPB, aucune tentative n’était faite pour la cacher au monde extérieur et aucun chemin n’était proposé pour chiffrer les bases de données existantes. Firebird 3.0 résout la plupart des problèmes, à l’exception probablement du pire : comment gérer les clés de chiffrement. Nous proposons différents types de solutions, mais elles demandent des efforts dans les plugins, c’est-à-dire qu’il n’y a pas de façon agréable de travailler avec des clés comme, par exemple, pour les plugins pour crypter le trafic réseau.

Avant d’exécuter votre propre plugin de chiffrement de base de données, vous devez tenir compte des éléments suivants : Il existe deux cas principaux dans lesquels le chiffrement de base de données est utilisé : premièrement, il peut être nécessaire d’éviter les fuites de données si le serveur de base de données est physiquement volé, et deuxièmement, il peut être utilisé pour protéger les données d’une base de données distribuée avec une application spéciale accédant à ces données. Les exigences pour ces cas sont complètement différentes. Dans le premier cas, nous pouvons faire confiance au serveur de base de données qu’il n’est pas modifié pour voler les clés transmises au plugin de sécurité, c’est-à-dire que nous nous attendons à ce que cette clé ne soit pas envoyée au mauvais serveur. Dans le second cas, le serveur peut être modifié d’une manière ou d’une autre pour voler des clés (si elles sont transmises de l’application au plugin via le code du serveur) ou même des données (en tant que dernier endroit pour vider le cache, où elles ne sont pas chiffrées). Par conséquent, votre plugin doit s’assurer qu’il fonctionne avec les binaires Firebird non modifiés et votre application avant d’envoyer la clé au plugin, par exemple, le plugin peut nécessiter une sorte de signature numérique de leur part. De plus, si vous utilisez l’accès réseau au serveur, il est conseillé de vérifier que le canal réseau est chiffré (en analysant la sortie de IUtil::getFbVersion()) ou en utilisant votre propre clé de chiffrement.Tout ce travail doit être effectué dans le plugin (et dans l`application qui fonctionne avec), ce qui signifie que l`algorithme de chiffrement des blocs de base de données lui-même peut être la partie la plus simple du plugin de chiffrement de base de données, en particulier lorsqu`il utilise une bibliothèque standard.

ICryptKeyCallback

L’interface ICryptKeyCallback doit permettre à la clé de chiffrement d’être transmise au plugin de chiffrement de base de données ou au plugin du détenteur de la clé.

callback
```
unsigned callback(unsigned dataLength,
                  const void* data,
                  unsigned bufferLength,
                  void* buffer)
```
Lorsqu’un callback est exécuté, l’information est transmise dans les deux sens. La source de clé reçoit les octets de données dataLength et peut envoyer les octets bufferLength à la mémoire tampon. Renvoie le nombre réel d’octets mis en mémoire tampon.
dispose
```
void dispose()
```
Invoqué lorsque l’interface n’est plus nécessaire. Permet d’éviter les fuites de mémoire dans les interfaces à état plein.
afterAttach
```
unsigned afterAttach(StatusType* status, const char* dbName, const IStatus* attStatus)
```
Invoquée après l’attachement sur le système client. NULL dans attStatus signifie que l’attachement a réussi mais afterAttach() est quand même invoqué pour permettre au plugin d’effectuer le nettoyage nécessaire.

Les valeurs suivantes peuvent être renvoyées par cette fonction :

NO_RETRY - ne pas répéter les tentatives de connexion à la base de données.
DO_RETRY - réessayer l’attachement (ignoré si la fonction a été appelée sans attStatus).

IDbCryptInfo

L’interface IDbCryptInfo est passée au moteur IDbCryptPlugin. Le plugin peut enregistrer cette interface et l’utiliser en cas de besoin pour obtenir plus d’informations sur la base de données.

getDatabaseFullPath
```
const char* getDatabaseFullPath(StatusType* status)
```
Renvoie le nom complet (y compris le chemin d’accès) du fichier de base de données principal.

IDbCryptPlugin

L’interface IDbCryptPlugin est l’interface principale du plugin de chiffrement de base de données.

setKey
```
void setKey(StatusType* status,
            unsigned length,
            IKeyHolderPlugin** sources,
            const char* keyName)
```
est utilisé pour fournir des informations au plugin de chiffrement de base de données sur la clé de chiffrement. Firebird ne transmet jamais directement les clés de ce type de plugin. Au lieu de cela, le tableau IKeyHolderPlugins de la longueur spécifiée est passé au plugin de chiffrement, qui doit recevoir l’interface ICryptKeyCallback de l’un d’entre eux, puis récupérer la clé en l’utilisant. Le paramètre keyName est le nom de la clé qui a été saisie dans l’instruction ALTER DATABASE ENCRYPT ….

encrypt

void encrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

Chiffre les données avant d’écrire un bloc dans un fichier de base de données

decrypt

void decrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

Déchiffre les données après avoir lu le bloc à partir du fichier de base de données.

setInfo
```
void setInfo(StatusType* status,
             IDbCryptInfo* info)
```
Dans cette méthode, le plugin de cryptage enregistre généralement l’interface d’information pour une utilisation ultérieure.

Key Keeper pour le plugin de chiffrement de base de données

Ce type de plugin est nécessaire pour différencier la fonctionnalité – le plugin de cryptage de base de données s’occupe du cryptage proprement dit, le détenteur de la clé résout les problèmes liés à la fourniture de la clé de manière sécurisée. Le plugin peut récupérer la clé à partir de l’application ou la télécharger d’une autre manière (jusqu’à utiliser une clé USB insérée dans le serveur au démarrage de Firebird).

IKeyHolderPlugin

L’interface IKeyHolderPlugin est l’interface principale pour le plugin de stockage de clé de chiffrement.

keyCallback
```
int keyCallback(StatusType* status,
                ICryptKeyCallback* callback)
```
est utilisé pour passer l’interface ICryptKeyCallback à la connexion (si elle est fournie par l’utilisateur avec l’appel IProvider::setDbCryptCallback()). Cet appel est toujours effectué au moment de la connexion à la base de données, et certains détenteurs de clés peuvent rejeter la connexion si aucune clé satisfaisante n’a pas été fournie.
keyHandle
```
ICryptKeyCallback* keyHandle(StatusType* status,
                             const char* keyName)
```
est destiné à être directement invoqué par l’interface IDbCryptPlugin pour obtenir l’interface de rappel de la clé nommée auprès du détenteur de la clé.Cela vous permet d’utiliser le code Firebird open-source afin de ne jamais toucher aux touches réelles, évitant ainsi la possibilité de vol de clé en modifiant le code Firebird. Après avoir reçu l’interface ICryptKeyCallback, le plugin de chiffrement démarre la communication à l’aide de celle-ci. Le détenteur de la clé peut (par exemple) vérifier la signature numérique du plugin de chiffrement avant de lui envoyer la clé afin d’éviter d’utiliser un plugin de chiffrement modifié qui pourrait voler la clé privée.
useOnlyOwnKeys
```
FB_BOOLEAN useOnlyOwnKeys(StatusType* status)
```
informe Firebird si une clé fournie par un autre détenteur de clé sera utilisée ou non. Cela n’a de sens que pour SuperServer : seul SuperServer peut partager des clés de chiffrement de base de données entre les connexions. En renvoyant un FB_TRUE de cette méthode, il force Firebird à s’assurer que ce détenteur de clé particulier (et donc la connexion qui lui est associée) fournit la clé de chiffrement correcte avant de l’autoriser à fonctionner avec la base de données.
chainHandle
```
ICryptKeyCallback* chainHandle(StatusType* status)
```
Prise en charge du porte-clés. Dans certains cas, la clé doit passer par plusieurs détenteurs de clés avant d’atteindre le plugin de chiffrement de la base de données. Ceci est nécessaire (par exemple) pour prendre en charge EXECUTE STATEMENT dans une base de données chiffrée. Ce n’est qu’un exemple – les chaînes sont également utilisées dans d’autres cas. L’interface de rappel renvoyée par cette méthode peut différer de celle renvoyée par la fonction keyHandle() (voir ci-dessus). En règle générale, il devrait être capable de dupliquer les clés reçues de IKeyHolderPlugin lors de l’appel de la fonction keyCallback().

IConfigManager

Interface IConfigManager — Une interface commune pour accéder à divers objets de configuration.

getDirectory
```
const char* getDirectory(unsigned code)
```
Renvoie l’emplacement du répertoire correspondant dans l’instance courante de Firebird. Les codes d’annuaire de cet appel sont ci-dessous.
getFirebirdConf
```
IFirebirdConf* getFirebirdConf()
```
Renvoie une interface permettant d’accéder aux valeurs de configuration par défaut (à partir de firebird.conf).
getDatabaseConf
```
IFirebirdConf* getDatabaseConf(const char* dbName)
```
Renvoie une interface permettant d’accéder à une configuration spécifique à la base de données (prend en compte firebird.conf et la partie correspondante de database.conf).
getPluginConfig
```
IConfig* getPluginConfig(const char* configuredPlugin)
```
Renvoie une interface permettant d’accéder à la configuration du plugin nommé.
getInstallDirectory
```
const char* getInstallDirectory()
```
Renvoie le répertoire dans lequel Firebird est installé.
getRootDirectory
```
const char* getRootDirectory()
```
Renvoie le répertoire racine de l’instance courante, dans le cas d’une instance unique, généralement le même que le répertoire d’installation.
getDefaultSecurityDb
```
const char* getDefaultSecurityDb()
```
Renvoie le chemin d’accès par défaut (c’est-à-dire à l’exclusion des fichiers de configuration de compte) à la base de données de sécurité, utilisé principalement pour un usage interne, afin de garantir un accès correct à la base de données de sécurité sur un serveur avec plusieurs fournisseurs sans aucune configuration.

Catalogue des codes :

DIR_BIN — bin (utilitaires comme isql, gbak, gstat) ;
DIR_SBIN — sbin (fbguard et firebird serveur);
DIR_CONF — Répertoire des fichiers de configuration (firebird.conf, databases.conf, plugins.conf);
DIR_LIB — lib (fbclient, ib_util);
DIR_INC — include (ibase.h, firebird/Interfaces.h);
DIR_DOC — dossier de la documentation ;
DIR_UDF — UDF (ib_udf, fbudf);
DIR_SAMPLE — Dossier des exemples ;
DIR_SAMPLEDB — le répertoire où se trouve la base de données d’exemples (employee.fdb) ;
DIR_HELP — qli help (help.fdb);
DIR_INTL — Catalogue des bibliothèques d’internationalisation (fbintl) ;
DIR_MISC — divers fichiers (tels que le manifeste du programme de désinstallation, etc.) ;
DIR_SECDB — le répertoire dans lequel se trouve la base de données de sécurité (securityN.fdb) ;
DIR_MSG — le répertoire où se trouve le fichier de message (firebird.msg) ;
DIR_LOG — le répertoire dans lequel se trouve le fichier journal (firebird.log) ;
DIR_GUARD — répertoire dans lequel se trouve le service (fb_guard);
DIR_PLUGINS — Répertoire des plugins ([lib]Engine13.\{dll|so}).

IConfigEntry

Interface IConfigEntry — représente une entrée (Clé = Valeurs avec sous-titres possibles (sous-entrées)) dans le fichier de configuration de firebird.

getName
```
const char* getName()
```
Renvoie le nom de la clé.
getValue
```
const char* getValue()
```
Renvoie une valeur sous la forme d’une chaîne de caractères.
getIntValue
```
ISC_INT64 getIntValue()
```
Traite la valeur comme un entier et la renvoie.
getBoolValue
```
FB_BOOLEAN getBoolValue()
```
Traite la valeur comme booléenne et la renvoie.
getSubConfig
```
IConfig* getSubConfig(StatusType* status)
```
Traite les sous-en-têtes comme un fichier de configuration séparé et renvoie l’interface IConfig correspondante.

IDecFloat16

L’interface IDecFloat16 permet de travailler avec le type de données DECFLOAT(16).

toBcd

void toBcd(const FB_DEC16* from, int* sign, unsigned char* bcd, int* exp)

Convertit une valeur décimale à virgule flottante en BCD.

toString

void toString(StatusType* status, const FB_DEC16* from, unsigned bufferLength, char* buffer)

Convertit une valeur décimale à virgule flottante en chaîne.

fromBcd

void fromBcd(int sign, const unsigned char* bcd, int exp, FB_DEC16* to)

Collecte une valeur décimale à virgule flottante à partir de BCD.

fromString
```
void fromString(StatusType* status, const char* from, FB_DEC16* to)
```
Collecte une valeur décimale à virgule flottante à partir d’une chaîne.

IDecFloat34

L’interface IDecFloat34 permet de travailler avec le type de données DECFLOAT(34).

toBcd

void toBcd(const FB_DEC34* from, int* sign, unsigned char* bcd, int* exp)

Convertit une valeur décimale à virgule flottante en BCD.

toString

void toString(StatusType* status, const FB_DEC34* from, unsigned bufferLength, char* buffer)

Convertit une valeur décimale à virgule flottante en chaîne.

fromBcd

void fromBcd(int sign, const unsigned char* bcd, int exp, FB_DEC34* to)

Collecte une valeur décimale à virgule flottante à partir de BCD.

fromString
```
void fromString(StatusType* status, const char* from, FB_DEC34* to)
```
Collecte une valeur décimale à virgule flottante à partir d’une chaîne.

Objets non-frontaux utilisés dans l’API

Note	Ils se trouvent dans l’en-tête spécial `Message.h` C++

Les 3 classes suivantes sont utilisées pour représenter les types DATE, TIME et TIMESTAMP (datetime) lors de l’utilisation de la macro FB_MESSAGE. Les membres de la structure de données qui représentent un message statique correspondent aux champs des types FB_DATE/FB_TIME/FB_TIMESTAMP et auront le type de l’une de ces classes. Pour accéder aux champs de date et d’heure dans les messages statiques, vous devez connaître les méthodes et les membres de la classe (qui sont suffisamment auto-descriptifs pour ne pas être décrits ici).

FbDate

Méthodes de classe FbDate:

decode

void decode(IUtil* util,
            unsigned* year,
            unsigned* month,
            unsigned* day)

getYear
```
unsigned getYear(IUtil* util)
```
getMonth
```
unsigned getMonth(IUtil* util)
```
getDay
```
unsigned getDay(IUtil* util)
```

encode

void encode(IUtil* util,
            unsigned year,
            unsigned month,
            unsigned day)

FbTime

Méthodes de classe FbTime:

decode

void decode(IUtil* util,
            unsigned* hours,
            unsigned* minutes,
            unsigned* seconds,
            unsigned* fractions)

getHours
```
unsigned getHours(IUtil* util)
```
getMinutes
```
unsigned getMinutes(IUtil* util)
```
getSeconds
```
unsigned getSeconds(IUtil* util)
```
getFractions
```
unsigned getFractions(IUtil* util)
```

encode

void encode(IUtil* util,
            unsigned hours,
            unsigned minutes,
            unsigned seconds,
            unsigned fractions)

FbTimestamp

Membres du groupe `FbTimestamp `:

date
```
FbDate date;
```
time
```
FbTime time;
```

FbChar et FbVarChar

Les deux modèles suivants sont utilisés dans les messages statiques pour représenter les champs CHAR(N) et VARCHAR(N).

template <unsigned N>
struct FbChar
{
    char str[N];
};

template <unsigned N>
struct FbVarChar
{
    ISC_USHORT length;
    char str[N];
    void set(const char* s);
};

Conclusion

Trois types de plugins sont absents de ce document : ExternalEngine, Trace et Replicator.Des informations à leur sujet seront disponibles dans le prochain numéro.