FirebirdSQL logo
 Écriture de pluginsConclusion 

IPluginFactory

Interface IPluginFactory — doit être implémenté par l’auteur du plugin lors de l’écriture du plugin.

  1. createPlugin

    IPluginBase* createPlugin(StatusType* status, IPluginConfig* factoryParameter)

    Crée une nouvelle instance du plugin avec la configuration recommandée transmise.

IPluginManager

Interface IPluginManager — API du gestionnaire de plugins.

  1. registerPluginFactory

    void registerPluginFactory(unsigned pluginType,
                           const char* defaultName,
                           IPluginFactory* factory)

    Enregistre un constructeur de plugins nommée de ce type.

  2. registerModule

    void registerModule(IPluginModule* cleanup)

    Enregistre le module de plugin.

  3. unregisterModule

    void unregisterModule(IPluginModule* cleanup)

    Annule l’enregistrement du module plugin.

  4. getPlugins

    IPluginSet* getPlugins(StatusType* status,
                       unsigned pluginType,
                       const char* namesList,
                       IFirebirdConf* firebirdConf)

    Renvoie une interface IPluginSet qui permet d’accéder à une liste de plugins de ce type. Les noms des plugins inclus sont tirés de la namesList, s’ils sont absents (NULL), alors ils proviennent des paramètres de configuration de ce type donné pluginType. Si le paramètre firebirdConf est spécifié, il est utilisé à toutes fins de configuration (y compris l’obtention d’une liste de plugins et la navigation vers la méthode PluginFactory::createPlugin()), s’il est manquant (NULL), alors le paramètre par défaut (de firebird.conf) est utilisé.

  5. getConfig

    IConfig* getConfig(StatusType* status, const char* filename)

    Renvoie l’interface IConfig pour le nom de fichier de configuration spécifié.Peut être utilisé par les plugins pour accéder aux fichiers de configuration avec un format standard, mais pas avec un nom par défaut.

  6. releasePlugin

    void releasePlugin(IPluginBase* plugin)

    Libérez le plugin. Devrait être utilisé pour les plugins au lieu du simple release() en raison de la nécessité d’effectuer des actions supplémentaires avec le propriétaire du plugin avant de le publier.

Constantes définies par l’interface IPluginManager (types de plugins) :

  • TYPE_PROVIDER

  • TYPE_AUTH_SERVER

  • TYPE_AUTH_CLIENT

  • TYPE_AUTH_USER_MANAGEMENT

  • TYPE_EXTERNAL_ENGINE

  • TYPE_TRACE

  • TYPE_WIRE_CRYPT

  • TYPE_DB_CRYPT

  • TYPE_KEY_HOLDER

  • TYPE_REPLICATOR

IPluginModule

Interface IPluginModule — représente un module de plugin (bibliothèque dynamique). Doit être implémenté par l’auteur du plugin dans chaque module du plugin (une instance par module).

  1. doClean

    void doClean()

    Appelé par le gestionnaire de plugin avant que le module de plugin ne soit déchargé normalement.

IPluginSet

Interface IPluginSet — est un ensemble de plugins de ce type.Couramment utilisé par le code interne de Firebird, mais recommandé pour une utilisation dans les plugins qui chargent d’autres plugins.

  1. getName

    const char* getName()

    Renvoie le nom du plugin courant dans l’ensemble.

  2. getModuleName

    const char* getModuleName()

    Retourne le nom du module du plugin courant dans l’ensemble (dans le cas le plus simple, le même que le nom du plugin).

  3. getPlugin

    IPluginBase* getPlugin(StatusType* status)

    renvoie une instance du plugin courant, l’interface retournée doit être convertie en l’interface du plugin principal du type demandé dans la méthode IPluginManager::getPlugins(). Renvoie NULL s’il n’y a plus de plugins dans l’ensemble. Le nombre de liens du plugin renvoyé par cette fonction est incrémenté lorsqu’il est renvoyé — n’oubliez pas d’utiliser la méthode releasePlugin() de l’interface IPluginManager pour libérer les plugins retournés par cette méthode.

  4. next

    void next(StatusType* status)

    Définit un bouton bascule pour passer au plugin suivant dans la liste.

  5. set

    void set(StatusType* status, const char* list)

    Réinitialise l’interface : la fait fonctionner avec la liste des plugins fournie par le paramètre list. Le type de plugins reste le même.

IProvider

Interface IPluginModule — L’interface principale pour démarrer l’accès à la base de données/service.

  1. attachDatabase

    IAttachment* attachDatabase(StatusType* status,
                            const char* fileName,
                            unsigned dpbLength,
                            const unsigned char* dpb)

    Crée une connexion à une base de données existante. Remplace isc_attach_database().

  2. createDatabase

    IAttachment* createDatabase(StatusType* status,
                            const char* fileName,
                            unsigned dpbLength,
                            const unsigned char* dpb)

    Crée une nouvelle base de données et renvoie l’interface pour s’y connecter. Remplace isc_create_database().

  3. attachServiceManager

    IService* attachServiceManager(StatusType* status,
                               const char* service,
                               unsigned spbLength,
                               const unsigned char* spb)

    Remplace isc_service_attach().

  4. shutdown

    void shutdown(StatusType* status, unsigned timeout, const int reason)

    Remplace fb_shutdown().

  5. setDbCryptCallback

    void setDbCryptCallback(IStatus* status, ICryptKeyCallback* cryptCallback)

    Définit l’interface de retour de chiffrement de base de données qui sera utilisée pour les connexions ultérieures à la base de données et aux services.

IResultSet

Interface IResultSet — remplace (avec des fonctionnalités étendues) certaines des fonctions isc_stmt_handle. Cette interface est retournée en appelant openCursor() à partir de IAttachment ou IStatement. Tous les appels à fetch…​ à l’exception de fetchNext() ne fonctionnent que pour le curseur bidirectionnel (ouvert avec l’option CURSOR_TYPE_SCROLLABLE).

  1. fetchNext

    int fetchNext(StatusType* status, void* message)

    sélectionne l’entrée suivante, remplace isc_dsql_fetch(). Cette méthode (et d’autres méthodes de récupération) renvoie le code de complétion Status::RESULT_NO_DATA lorsque l’EOF est atteint, et le statut Status::RESULT_OK lorsqu’il réussit.

  2. fetchPrior

    int fetchPrior(StatusType* status, void* message)

    Sélectionne l’enregistrement précédent.

  3. fetchFirst

    int fetchFirst(StatusType* status, void* message)

    Sélectionne la première entrée.

  4. fetchLast

    int fetchLast(StatusType* status, void* message)

    Sélectionne la dernière entrée.

  5. fetchAbsolute

    int fetchAbsolute(StatusType* status, int position, void* message)

    Récupère l’enregistrement à la position absolue dans le jeu de résultats.

  6. fetchRelative

    int fetchRelative(StatusType* status, int offset, void* message)

    Récupère l’enregistrement par position par rapport à l’enregistrement actif.

  7. isEof

    FB_BOOLEAN isEof(StatusType* status)

    Vérification de l’état EOF.

  8. isBof

    FB_BOOLEAN isBof(StatusType* status)

    Vérification de l’état BOF.

  9. getMetadata

    IMessageMetadata* getMetadata(StatusType* status)

    renvoie les métadonnées des messages dans le jeu de résultats, particulièrement utile lorsque le jeu de résultats est ouvert en appelant IAttachment::openCursor() avec le paramètre de format de sortie des métadonnées défini sur NULL (c’est la seule façon d’obtenir le format du message dans ce cas).

  10. close

    void close(IStatus* status)

    Ferme le jeu de résultats, libère l’interface en cas de succès.

IService

Interface IService — Remplace isc_svc_handle.

  1. detach

    void detach(StatusType* status)

    Ferme la connexion au gestionnaire de services et, en cas de succès, libère l’interface. Remplace isc_service_detach().

  2. query

    void query(StatusType* status,
           unsigned sendLength,
           const unsigned char* sendItems,
           unsigned receiveLength,
           const unsigned char* receiveItems,
           unsigned bufferLength,
           unsigned char* buffer)

    Envoie et demande des informations vers/depuis le service, et receiveItems peut être utilisé à la fois pour exécuter des services et pour recevoir diverses informations sur le serveur. Remplace isc_service_query().

  3. start

    void start(StatusType* status,
           unsigned spbLength,
           const unsigned char* spb)

    Exécute l’utilitaire dans Service Manager. Remplace isc_service_start().

IStatement

Interface IStatement — remplace (partiellement) isc_stmt_handle.

  1. getInfo

    void getInfo(StatusType* status,
             unsigned itemsLength,
             const unsigned char* items,
             unsigned bufferLength,
             unsigned char* buffer)

    Remplace isc_dsql_sql_info().

  2. getType

    unsigned getType(StatusType* status)

    Le type d’opérateur ne se trouve actuellement que dans les sources Firebird dans dsql/dsql.h.

  3. getPlan

    const char* getPlan(StatusType* status, FB_BOOLEAN detailed)

    Renvoie le plan d’exécution de l’opérateur.

  4. getAffectedRecords

    ISC_UINT64 getAffectedRecords(StatusType* status)

    Renvoie le nombre d’enregistrements affectés par l’opérateur.

  5. getInputMetadata

    IMessageMetadata* getInputMetadata(StatusType* status)

    Renvoie les métadonnées des paramètres.

  6. getOutputMetadata

    IMessageMetadata* getOutputMetadata(StatusType* status)

    Renvoie les métadonnées des valeurs de sortie.

  7. execute

    ITransaction* execute(StatusType* status,
                      ITransaction* transaction,
                      IMessageMetadata* inMetadata,
                      void* inBuffer,
                      IMessageMetadata* outMetadata,
                      void* outBuffer)

    Exécute toutes les instructions SQL, à l’exception de celles qui renvoient plusieurs lignes de données. Analogique partiel de isc_dsql_execute2() — l’entrée et la sortie de XSLQDA ont été remplacées par des messages d’entrée et de sortie avec les tampons correspondants.

  8. openCursor

    IResultSet* openCursor(StatusType* status,
                       ITransaction* transaction,
                       IMessageMetadata* inMetadata,
                       void* inBuffer,
                       IMessageMetadata* outMetadata,
                       unsigned flags)

    Exécute une instruction SQL qui renvoie potentiellement plusieurs lignes de données. Renvoie l’interface IResultSet qui doit être utilisée pour récupérer ces données. Le format de la sortie est déterminé par le paramètre outMetadata, si NULL est spécifié, le format par défaut sera utilisé.

  9. setCursorName

    void setCursorName(StatusType* status, const char* name)

    Remplace isc_dsql_set_cursor_name().

  10. free

    void free(StatusType* status)

    Détruit l’opérateur, libère l’interface en cas de succès.

  11. getFlags

    unsigned getFlags(StatusType* status)

    Renvoie des indicateurs décrivant comment cette instruction doit être exécutée, un remplacement simplifié de la méthode getType().

  12. getTimeout

    unsigned getTimeout(StatusType* status)

    Renvoie le délai d’expiration de la requête SQL en millisecondes.

  13. setTimeout

    unsigned setTimeout(StatusType* status)

    Définit le délai d’exécution de la requête SQL en millisecondes.

  14. createBatch

    IBatch* createBatch(StatusType* status,
                    IMessageMetadata* inMetadata,
                    unsigned parLength,
                    const unsigned char* par)

    Crée une interface IBatch pour une instruction SQL avec des paramètres d’entrée, ce qui permet à cette instruction d’être exécutée avec plusieurs ensembles de paramètres. Le format des données d’entrée est déterminé par le paramètre inMetadata, le laissant NULL, le package utilise le format par défaut de cette interface. Un bloc de paramètres peut être passé à la fonction createBatch(), qui permet de configurer le comportement du paquet.

Constantes définies par l’interface IStatement

Flag IAttachment::prepare():

  • PREPARE_PREFETCH_NONE — constante pour ignorer les flags, valeur 0.

Les flags suivants peuvent être combinés avec OU pour produire l’effet souhaité :

  1. PREPARE_PREFETCH_TYPE

  2. PREPARE_PREFETCH_INPUT_PARAMETERS

  3. PREPARE_PREFETCH_OUTPUT_PARAMETERS

  4. PREPARE_PREFETCH_LEGACY_PLAN

  5. PREPARE_PREFETCH_DETAILED_PLAN

  6. PREPARE_PREFETCH_AFFECTED_RECORDS

  7. PREPARE_PREFETCH_FLAGS (flag renvoyés par le getFlags())

Pour les combinaisons d’indicateurs les plus couramment utilisées, vous pouvez utiliser les constantes suivantes :

  1. PREPARE_PREFETCH_METADATA

  2. PREPARE_PREFETCH_ALL

Les valeurs renvoyées par l’attribut getFlags():

  1. FLAG_HAS_CURSOR — Utiliser openCursor() pour exécuter cette instruction plutôt que execute()

  2. FLAG_REPEAT_EXECUTE — Lorsqu’une instruction préparée peut être exécutée plusieurs fois avec des paramètres différents.

Les flags passés à openCursor():

  1. CURSOR_TYPE_SCROLLABLE — Ouvre un curseur bidirectionnel.

IStatus

L’interface IStatus remplace ISC_STATUS_ARRAY. La fonctionnalité a été étendue : l’état a un accès séparé aux vecteurs d’erreur et d’avertissement, peut contenir des vecteurs de longueur illimitée, stocke indépendamment les chaînes utilisées dans les vecteurs et n’a pas besoin d’un tampon de chaînes de caractères. Dans C++, IStatus est toujours utilisé dans le wrapper d’état, l’API C++ fournit deux wrappers différents qui ont un comportement différent lorsqu’une erreur est renvoyée par un appel d’API. L’interface a été réduite au minimum (des méthodes telles que la conversion en ext ont été déplacées vers l’interface IUtil pour la rendre plus facile à implémenter par les utilisateurs en cas de besoin.

  1. init

    void init()

    Nettoie l’interface et la réinitialise à son état d’origine.

  2. getState

    unsigned getState()

    Renvoie l’état actuel de l’interface, les flags retournés peuvent être combinés avec OR.

  3. setErrors2

    void setErrors2(unsigned length, const intptr_t* value)

    Définit le contenu du vecteur d’erreur avec la longueur explicitement spécifiée dans l’appel.

  4. setWarnings2

    void setWarnings2(unsigned length, const intptr_t* value)

    Définit le contenu du vecteur d’alerte avec la longueur explicitement spécifiée dans l’appel.

  5. setErrors

    void setErrors(const intptr_t* value)

    définit le contenu du vecteur d’erreur, la longueur est déterminée par le contexte de valeur.

  6. setWarnings

    void setWarnings(const intptr_t* value)

    définit le contenu du vecteur d’alerte, la longueur est déterminée par le contexte de valeur.

  7. getErrors

    const intptr_t* getErrors()

    Renvoie un vecteur d’erreur.

  8. getWarnings

    const intptr_t* getWarnings()

    Renvoie un vecteur d’alerte.

  9. clone

    IStatus* clone()

    Crée un clone de l’interface courante.

Les constantes définies dans IStatus

Les flags renvoyés par l’attribut getState():

  • STATE_WARNINGS

  • STATE_ERRORS

Codes d’achèvement :

  • RESULT_ERROR

  • RESULT_OK

  • RESULT_NO_DATA

  • RESULT_SEGMENT

IBatchCompletionState

IBatchCompletionState — Une interface à usage unique, toujours retournée par la méthode execute() de l’interface IBatch.Il contient plus ou moins (en fonction des paramètres passés lors de la création de l’IBatch) des informations détaillées sur les résultats de l’exécution du lot.

  1. getSize

    unsigned getSize(StatusType* status)

    Renvoie le nombre total de messages traités.

  2. getState

    int getState(StatusType* status, unsigned pos)

    Renvoie le résultat d’un message avec le numéro pos. Pour toute erreur avec le message, il s’agit d’une constante EXECUTE_FAILED, la valeur de retour en cas de succès dépend de la présence du paramètre RECORD_COUNTS lors de la création du paquet.Lorsqu’elle est présente et qu’elle a une valeur différente de zéro, le nombre d’enregistrements insérés, mis à jour ou supprimés lors du traitement d’un message particulier est renvoyé, sinon la constante SUCCESS_NO_INFO est renvoyée.

  3. findError

    unsigned findError(StatusType* status, unsigned pos)

    Recherche le message suivant (commençant par pos) à l’origine de l’erreur.En l’absence d’un tel message, la constante NO_MORE_ERRORS est renvoyée. Le nombre de vecteurs d’état renvoyés dans cette interface est limité par la valeur du paramètre DETAILED_ERRORS lors de la création du package.

  4. getStatus

    void getStatus(StatusType* status, IStatus* to, unsigned pos)

    Renvoie des informations détaillées (vecteur d’état complet) sur l’erreur qui s’est produite lors du traitement du message pos.Pour faire la distinction entre les erreurs (dans IBatch::execute() ou dans IBatchCompletionState::getStatus()), cet état est renvoyé dans un paramètre to séparé, par opposition aux erreurs dans cet appel, qui sont placées dans le paramètre status.

Valeurs spéciales renvoyées par getState() :

  • EXECUTE_FAILED — Une erreur s’est produite lors du traitement de ce message.

  • SUCCESS_NO_INFO — Aucune information sur la mise à jour des dossiers n’a été recueillie.

La valeur spéciale renvoyée par findError() est :

  • NO_MORE_ERRORS – Il n’y a plus de messages d’erreur dans ce package.

ITimer

Interface ITimer — Minuterie personnalisée. Une interface de rappel qui doit être implémentée par l’utilisateur pour utiliser le minuteur Firebird.

  1. handler

    void handler()

    La méthode est appelée lorsque le minuteur sonne (ou lorsque le serveur s’arrête).

ITimerControl

L’interface ITimerControl est une implémentation très simple et peu précise du timer. Nous en sommes arrivés là parce que les minuteries existantes sont très dépendantes du système d’exploitation et peuvent être utilisées dans des programmes qui nécessitent une portabilité et ne nécessitent pas une minuterie de très haute précision. De plus, l’exécution d’une minuterie donnée peut être reportée si l’autre minuterie n’a pas été terminée au moment où cette minuterie devrait être signalée.

  1. start

    void start(StatusType* status, ITimer* timer, ISC_UINT64 microSeconds)

    Lancez ITimer après le signal (en microsecondes, 10-6 secondes). La minuterie ne se réveillera qu’une seule fois après cet appel.

  2. stop

    void stop(StatusType* status, ITimer* timer)

    stop ITimer. N’arrêtez pas un chronomètre qui n’est pas en cours d’exécution, ce qui évitera les problèmes de conflit entre le signal stop() et le signal du minuteur.

ITransaction

Interface ITransaction — Remplace isc_tr_handle.

  1. getInfo

    void getInfo(StatusType* status,
             unsigned itemsLength,
             const unsigned char* items,
             unsigned bufferLength,
             unsigned char* buffer)

    Remplace isc_transaction_info().

  2. prepare

    void prepare(StatusType* status,
             unsigned msgLength,
             const unsigned char* message)

    Remplace isc_prepare_transaction2().

  3. commit

    void commit(StatusType* status)

    Remplace isc_commit_transaction().

  4. commitRetaining

    void commitRetaining(StatusType* status)

    Remplace isc_commit_retaining().

  5. rollback

    void rollback(StatusType* status)

    Remplace isc_rollback_transaction().

  6. rollbackRetaining

    void rollbackRetaining(StatusType* status)

    Remplace isc_rollback_retaining().

  7. disconnect

    void disconnect(StatusType* status)

    Remplace fb_disconnect_transaction().

  8. join

    ITransaction* join(StatusType* status, ITransaction* transaction)

    connecte la transaction en cours et la transaction passée en paramètre en une seule transaction distribuée (à l’aide de Dtc). En cas de réussite, la transaction en cours et la transaction passée en paramètre sont libérées et ne doivent plus être utilisées.

  9. validate

    ITransaction* validate(StatusType* status, IAttachment* attachment)

    Cette méthode est utilisée pour soutenir le coordinateur des transactions distribuées.

  10. enterDtc

    ITransaction* enterDtc(StatusType* status)

    Cette méthode est utilisée pour prendre en charge le coordinateur des transactions distribuées.

IVersionCallback

Interface IVersionCallback — Rappel pour IUtil::getFbVersion().

  1. callback

    void callback(StatusType* status, const char* text)

    Appelé par le moteur Firebird pour chaque ligne de la version multiligne du rapport. Permet d’imprimer ces lignes une par une, de les placer dans le champ de message de n’importe quelle interface graphique, etc.

IUtil

Interface IUtil — Diverses méthodes d’aide.

  1. getFbVersion

    void getFbVersion(StatusType* status,
                  IAttachment* att,
                  IVersionCallback* callback)

    Construit un rapport de version pour firebird. Cela peut être vu dans ISQL lorsqu’il est appelé avec l’option -Z.

  2. loadBlob

    void loadBlob(StatusType* status,
              ISC_QUAD* blobId,
              IAttachment* att,
              ITransaction* tra,
              const char* file,
              FB_BOOLEAN txt)

    Chargez un BLOB à partir d’un fichier.

  3. dumpBlob

    void dumpBlob(StatusType* status,
              ISC_QUAD* blobId,
              IAttachment* att,
              ITransaction* tra,
              const char* file,
              FB_BOOLEAN txt)

    Enregistre le BLOB dans un fichier.

  4. getPerfCounters

    void getPerfCounters(StatusType* status,
                     IAttachment* att,
                     const char* countersSet,
                     ISC_INT64* counters)

    Obtient des statistiques pour la connexion.

  5. executeCreateDatabase

    IAttachment* executeCreateDatabase(StatusType* status,
                                   unsigned stmtLength,
                                   const char* creatDBstatement,
                                   unsigned dialect,
                                   FB_BOOLEAN* stmtIsCreateDb)

    Exécute l’instruction CREATE DATABASE…​ - l’astuce ISC avec le handle d’opérateur NULL ne fonctionne pas avec les interfaces.

  6. decodeDate

    void decodeDate(ISC_DATE date,
                unsigned* year,
                unsigned* month,
                unsigned* day)

    Remplace isc_decode_sql_date().

  7. decodeTime

    void decodeTime(ISC_TIME time,
                unsigned* hours,
                unsigned* minutes,
                unsigned* seconds,
                unsigned* fractions)

    Remplace isc_decode_sql_time().

  8. encodeDate

    ISC_DATE encodeDate(unsigned year, unsigned month, unsigned day)

    Remplace isc_encode_sql_date().

  9. encodeTime

    ISC_TIME encodeTime(unsigned hours,
                    unsigned minutes,
                    unsigned seconds,
                    unsigned fractions)

    Remplace isc_encode_sql_time().

  10. formatStatus

    unsigned formatStatus(char* buffer, unsigned bufferSize, IStatus* status)

    Remplace fb_interpret(). La taille de la mémoire tampon passée à cette méthode ne doit pas être inférieure à 50 octets.

  11. getClientVersion

    unsigned getClientVersion()

    Renvoie un entier contenant la version majeure dans l’octet 0 et la version mineure dans l’octet 1.

  12. getXpbBuilder

    IXpbBuilder* getXpbBuilder(StatusType* status,
                           unsigned kind,
                           const unsigned char* buf,
                           unsigned len)

    Renvoie le lien d’interface :#fbapi-interfaces-ixpbbuilder[IXpbBuilder].Les kind valides sont listés dans IXpbBuilder.

  13. setOffsets

    unsigned setOffsets(StatusType* status,
                    IMessageMetadata* metadata,
                    IOffsetsCallback* callback)

    Définit les décalages autorisés sur IMessageMetadata. Effectue des appels de rappel à IOffsetsCallback pour chaque champ/paramètre.

  14. getDecFloat16

    IDecFloat16* getDecFloat16(StatusType* status)

    Renvoie l’interface IDecFloat16.

  15. getDecFloat34

    IDecFloat34* getDecFloat34(StatusType* status)

    Renvoie l’interface IDecFloat34.

  16. decodeTimeTz

    void decodeTimeTz(StatusType* status,
                  const ISC_TIME_TZ* timeTz,
                  unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned* fractions,
                  unsigned timeZoneBufferLength, char* timeZoneBuffer)

    Décode l’heure avec le fuseau horaire.

  17. decodeTimeStampTz

    void decodeTimeStampTz(StatusType* status,
                       const ISC_TIMESTAMP_TZ* timeStampTz,
                       unsigned* year, unsigned* month, unsigned* day,
                       unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned* fractions,
                       unsigned timeZoneBufferLength, char* timeZoneBuffer)

    Décode un horodatage (date-heure) avec un fuseau horaire.

  18. encodeTimeTz

    void encodeTimeTz(StatusType* status,
                  ISC_TIME_TZ* timeTz,
                  unsigned hours, unsigned minutes, unsigned seconds, unsigned fractions,
                  const char* timeZone)

    Encode l’heure avec le fuseau horaire.

  19. encodeTimeStampTz

    void encodeTimeStampTz(StatusType* status,
                       ISC_TIMESTAMP_TZ* timeStampTz,
                       unsigned year, unsigned month, unsigned day,
                       unsigned hours, unsigned minutes, unsigned seconds, unsigned fractions,
                       const char* timeZone)

    Encode un horodatage (date-heure) avec un fuseau horaire.

  20. getInt128

    IInt128* getInt128(StatusType* status)

    Renvoie l’interface IInt128.

  21. decodeTimeTzEx

    void decodeTimeTzEx(StatusType* status,
                    const ISC_TIME_TZ_EX* timeTz,
                    unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned* fractions,
                    unsigned timeZoneBufferLength, char* timeZoneBuffer)

    Décode l`heure dans un format de fuseau horaire étendu.

  22. decodeTimeStampTzEx

    void decodeTimeStampTzEx(StatusType* status,
                         const ISC_TIMESTAMP_TZ_EX* timeStampTz,
                         unsigned* year, unsigned* month, unsigned* day, unsigned* hours,
                         unsigned* minutes, unsigned* seconds, unsigned* fractions,
                         unsigned timeZoneBufferLength, char* timeZoneBuffer)

    Décode un horodatage (date-heure) dans un format de fuseau horaire étendu.

IXpbBuilder

Interface IXpbBuilder

  1. clear

    void clear(StatusType* status)

    Réinitialise le constructeur à un état vide.

  2. removeCurrent

    void removeCurrent(StatusType* status)

    Supprime le clumplet en cours.

  3. insertInt

    void insertInt(StatusType* status, unsigned char tag, int value)

    Insère un agrégat avec une valeur qui représente un entier dans le format réseau.

  4. insertBigInt

    void insertBigInt(StatusType* status, unsigned char tag, ISC_INT64 value)

    Insère un agrégat avec une valeur qui représente un entier 64 bits au format réseau.

  5. insertBytes

    void insertBytes(StatusType* status, unsigned char tag, const void* bytes, unsigned length)

    Insère un clumpet avec une valeur qui contient les octets passés.

  6. insertTag

    void insertTag(StatusType* status, unsigned char tag)

    Insère un clumpet sans valeur.

  7. isEof

    FB_BOOLEAN isEof(StatusType* status)

    Vérifie s`il y a un clumpet actuelle.

  8. moveNext

    void moveNext(StatusType* status)

    Passe au clumpet suivant.

  9. rewind

    void rewind(StatusType* status)

    Se positionne sur le premier clumpet

  10. findFirst

    FB_BOOLEAN findFirst(StatusType* status, unsigned char tag)

    Trouve le premier clumpet avec cette balise.

  11. findNext

    FB_BOOLEAN findNext(StatusType* status)

    Recherche le clumpet suivant avec la balise spécifiée.

  12. getTag

    unsigned char getTag(StatusType* status)

    Renvoie la balise du clumpet courant.

  13. getLength

    unsigned getLength(StatusType* status)

    Renvoie la longueur de la valeur actuel du clumpet.

  14. getInt

    int getInt(StatusType* status)

    Renvoie la valeur du clumpet courant sous forme d’un entier.

  15. getBigInt

    SC_INT64 getBigInt(StatusType* status)

    Renvoie la valeur du clumpet courant sous forme d’un 64 bits.

  16. getString

    const char* getString(StatusType* status)

    Renvoie la valeur de l’agrégat courant sous la forme d’un pointeur vers une chaîne de terminaisons null (le pointeur est valide jusqu’au prochain appel de cette méthode).

  17. getBytes

    const unsigned char* getBytes(StatusType* status)

    Renvoie la valeur du clumpet courant sous la forme d’un pointeur vers unsigned char.

  18. getBufferLength

    unsigned getBufferLength(StatusType* status)

    Renvoie la longueur du bloc de paramètres.

  19. getBuffer

    const unsigned char* getBuffer(StatusType* status)

    Renvoie un pointeur vers le bloc de paramètres.

Constantes définies par l’interface IXpbBuilder

Types de constructeurs valides :

  • BATCH (IBatch parameters block)

  • BPB (BLOB parameters block)

  • DPB (database attachment parameters block)

  • SPB_ATTACH (service attachment parameters block)

  • SPB_START (start service parameters)

  • SPB_SEND (send items in IService::query())

  • SPB_RECEIVE (receive items in IService::query())

  • SPB_RESPONSE (response from IService::query())

  • TPB (transaction parameters block)

Plugin pour le cryptage des données transmises sur le réseau

Les algorithmes permettant de crypter des données à différentes fins sont bien connus depuis de nombreuses années. Le seul "petit" problème typique qui subsiste est de savoir où obtenir la clé top secrète utilisée par cet algorithme. Heureusement, pour le cryptage du trafic réseau, il existe une bonne solution : une clé de cryptage unique doit être générée par le plugin d’authentification. Au moins, le plugin SRP par défaut peut produire une telle clé. Et cette clé est résistante aux attaques, y compris celles de type "man-in-the-middle". C’est pourquoi une méthode a été choisie pour fournir des clés au plugin wire crypt : les obtenir du plugin d’authentification. (Dans le cas où le plugin d’authentification utilisé ne peut pas fournir de clé, un pseudo-plugin peut être ajouté dans les listes AuthClient et AuthServer pour produire des clés, quelque chose comme deux paires privées/publiques asymétriques).

ICryptKey

L’interface ICryptKey est utilisée pour stocker la clé fournie par le plugin d’authentification et la transmettre au plugin de chiffrement du trafic réseau. Cette interface doit être utilisée de la manière suivante : lorsque le plugin d’authentification du serveur ou du client est prêt à fournir une clé, il demande IServerBlock ou IClientBlock pour créer une nouvelle interface ICryptKey et y stocke la clé. Un type de clé adapté à IWireCryptPlugin sera sélectionné par Firebird et passé à cette interface.

  1. setSymmetric

    void setSymmetric(StatusType* status,
                  const char* type,
                  unsigned keyLength,
                  const void* key)

    Stocke une clé symétrique du type spécifié.

  2. setAsymmetric

    void setAsymmetric(StatusType* status,
                   const char* type,
                   unsigned encryptKeyLength,
                   const void* encryptKey,
                   unsigned decryptKeyLength,
                   const void* decryptKey)

    Stocke une paire de clés asymétriques du type spécifié.

  3. getEncryptKey

    const void* getEncryptKey(unsigned* length)

    Renvoie la clé de chiffrement.

  4. getDecryptKey

    const void* getDecryptKey(unsigned* length))

    renvoie la clé à déchiffrer (dans le cas d’une clé symétrique, le résultat est le même que getEncryptKey()).

IWireCryptPlugin

L’interface IWireCryptPlugin est l’interface principale du plugin de chiffrement réseau. Comme toute autre interface de ce type, elle doit être implémentée par l’auteur du plugin.

  1. getKnownTypes

    const char* getKnownTypes(StatusType* status)

    Renvoie une liste de clés valides séparées par des espaces/tabulations/virgules.

  2. setKey

    void setKey(StatusType* status, ICryptKey* key)

    Le plugin doit utiliser la clé qui lui est passée par cet appel.

  3. encrypt

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

    Chiffre le paquet qui doit être envoyé sur le réseau.

  4. decrypt

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

    Déchiffre le paquet reçu du réseau.

plugin d’authentification côté serveur

Le plugin d’authentification contient deux parties obligatoires, une partie client et une partie serveur, et peut également contenir une troisième partie qui lui est associée, le gestionnaire d’utilisateurs. Pendant le processus d’authentification, le client Firebird appelle le plugin client et envoie les données générées par celui-ci au serveur, puis le serveur appelle le plugin serveur et envoie les données qu’il a générées au client. Ce processus est répété jusqu’à ce que les deux plugins renvoient le code AUTH_MORE_DATA.AUTH_SUCCESS renvoyé côté serveur signifie une authentification réussie, AUTH_FAILED de part et d’autre signifie une interruption immédiate du processus itératif et un rejet signalé au client, AUTH_CONTINUE signifie que le plugin suivant de la liste des plugins d’authentification configurés doit être coché.

Il n`y a pas d`exemples dédiés de plugins d`authentification, mais dans le code source de firebird, dans le répertoire src/auth, vous pouvez trouver le plugin AuthDbg, avec lequel vous pouvez apprendre à partir d`un exemple trivial (sans calculs complexes comme dans Srp, par exemple, et sans appeler des fonctions WinAPI folles comme dans AuthSspi), comment le côté client et le côté serveur effectuent l`authentification (handshake).

IAuth

L’interface IAuth ne contient pas de méthodes, seules quelques constantes de définition de code sont renvoyées par la méthode authenticate() à IClient et IServer.

  • AUTH_FAILED

  • AUTH_SUCCESS

  • AUTH_MORE_DATA

  • AUTH_CONTINUE

IWriter

Interface IWriter — Enregistre le bloc Paramètre d’authentification.

  1. reset

    void reset()

    Efface le bloc cible.

  2. add

    void add(StatusType* status, const char* name)

    Ajoute un nom d’utilisateur.

  3. setType

    void setType(StatusType* status, const char* value)

    Définit le type de connexion à ajouter (utilisateur, rôle, groupe, etc.).

  4. setDb

    void setDb(StatusType* status, const char* value)

    Installe la base de données de sécurité sur laquelle l`authentification a été effectuée.

IBlob

L’interface IBlob remplace l’interface isc_blob_handle.

  1. getInfo

    void getInfo(StatusType* status,
             unsigned itemsLength,
             const unsigned char* items,
             unsigned bufferLength,
             unsigned char* buffer)

    Remplace isc_blob_info().

  2. getSegment

    int getSegment(StatusType* status,
               unsigned bufferLength,
               void* buffer,
               unsigned* segmentLength)

    remplace isc_get_segment(). En revanche, les erreurs isc_segstr_eof et isc_segment (qui ne sont pas réellement des erreurs) ne sont jamais renvoyées, mais les codes de sortie IStatus::RESULT_NO_DATA et IStatus::RESULT_SEGMENT sont renvoyés, renvoyant généralement IStatus::RESULT_OK.

  3. putSegment

    void putSegment(StatusType* status,
                unsigned length,
                const void* buffer)

    remplace isc_put_segment().

  4. cancel

    void cancel(StatusType* status)

    remplace isc_cancel_blob(). En cas de succès, l’interface est libérée.

  5. close

    void close(StatusType* status)

    remplace isc_close_blob(). En cas de succès, l’interface est libérée.

  6. seek

    int seek(StatusType* status,
         int mode,
         int offset)

    remplace isc_seek_blob().

IServerBlock

L’interface IServerBlock est utilisée par le serveur du module d’authentification pour communiquer avec le client.

  1. getLogin

    const char* getLogin()

    Renvoie le nom d’utilisateur transmis par le client.

  2. getData

    const unsigned char* getData(unsigned* length)

    Renvoie les données d’authentification transmises par le client.

  3. putData

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

    transmet les données d’authentification au client.

  4. 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.

IServer

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

  1. 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.

  2. 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.

  1. getLogin

    const char* getLogin()

    Renvoie le nom d’utilisateur s’il est présent dans le DPB.

  2. getPassword

    const char* getPassword()

    Renvoie le mot de passe s`il est présent dans le DPB.

  3. getData

    const unsigned char* getData(unsigned* length)

    Renvoie les données d`authentification envoyées par le serveur.

  4. putData

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

    Transmet les données d’authentification au serveur.

  5. 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

  6. getAuthBlock

    IAuthBlock* getAuthBlock(StatusType* status)

IClient

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

  1. 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.

  1. entered

    int entered()

    Renvoie une valeur différente de zéro si une valeur a été saisie (affectée) au champ.

  2. specified

    int specified()

    Renvoie une valeur différente de zéro si la valeur du champ a été affectée à NULL.

  3. 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:

  1. get

    const char* get()

    renvoie la valeur du champ sous la forme d’une chaîne C (borne \0).

  2. set

    void set(StatusType* status, const char* newValue)

    Attribue une valeur au champ. Définit l’indicateur entré sur true.

IIntUserField

Interface IIntUserField:

  1. get

    int get()

    Renvoie la valeur du champ.

  2. 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.

  1. operation

    unsigned operation()

    Opcode (voir la liste ci-dessous)

  2. userName

    ICharUserField* userName()

    Nom d’utilisateur

  3. password

    ICharUserField* password()

    mot de passe.

  4. firstName

    ICharUserField* firstName()

    Ceci et les 2 composants suivants du nom d’utilisateur complet.

  5. lastName

    ICharUserField* lastName()

  6. middleName

    ICharUserField* middleName()

  7. comment

    ICharUserField* comment()

    Commentaire (à partir de l’instruction SQL COMMENT ON USER IS…​).

  8. 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.

  9. active

    IIntUserField* active()

    Modifie le paramètre ACTIVE/INACTIVE pour l’utilisateur.

  10. admin

    IIntUserField* admin()

    Définit/supprime les droits d’administrateur de l’utilisateur.

  11. 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.

  1. 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.

  1. name

    const char* name()

    Renvoie le nom d’utilisateur de la connexion actuelle.

  2. role

    const char* role()

    Renvoie le rôle actif de la connexion actuelle.

  3. networkProtocol

    const char* networkProtocol()

    Renvoie le journal réseau de la connexion en cours. Non utilisé actuellement par les plugins.

  4. remoteAddress

    const char* remoteAddress()

    Renvoie l’adresse distante de la connexion actuelle. Non utilisé actuellement par les plugins.

  5. 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.

  1. find

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

    Recherche un enregistrement par son nom.

  2. findValue

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

    Recherche un enregistrement par son nom et sa valeur

  3. 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.

  1. 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.

  2. 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.

  3. commit

    void commit(StatusType* status)

    Prend en compte les modifications apportées par les appels à la méthode execute().

  4. 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é.

  1. 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.

  2. 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.

  3. 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.

  1. 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.

  1. 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 …​.

  2. 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

  3. 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.

  4. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  1. 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.

  2. getFirebirdConf

    IFirebirdConf* getFirebirdConf()

    Renvoie une interface permettant d’accéder aux valeurs de configuration par défaut (à partir de firebird.conf).

  3. 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).

  4. getPluginConfig

    IConfig* getPluginConfig(const char* configuredPlugin)

    Renvoie une interface permettant d’accéder à la configuration du plugin nommé.

  5. getInstallDirectory

    const char* getInstallDirectory()

    Renvoie le répertoire dans lequel Firebird est installé.

  6. 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.

  7. 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.

  1. getName

    const char* getName()

    Renvoie le nom de la clé.

  2. getValue

    const char* getValue()

    Renvoie une valeur sous la forme d’une chaîne de caractères.

  3. getIntValue

    ISC_INT64 getIntValue()

    Traite la valeur comme un entier et la renvoie.

  4. getBoolValue

    FB_BOOLEAN getBoolValue()

    Traite la valeur comme booléenne et la renvoie.

  5. 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).

  1. toBcd

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

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

  2. toString

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

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

  3. fromBcd

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

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

  4. 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).

  1. toBcd

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

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

  2. toString

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

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

  3. fromBcd

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

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

  4. 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:

  1. decode

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

  2. getYear

    unsigned getYear(IUtil* util)

  3. getMonth

    unsigned getMonth(IUtil* util)

  4. getDay

    unsigned getDay(IUtil* util)

  5. encode

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

FbTime

Méthodes de classe FbTime:

  1. decode

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

  2. getHours

    unsigned getHours(IUtil* util)

  3. getMinutes

    unsigned getMinutes(IUtil* util)

  4. getSeconds

    unsigned getSeconds(IUtil* util)

  5. getFractions

    unsigned getFractions(IUtil* util)

  6. encode

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

FbTimestamp

Membres du groupe `FbTimestamp `:

  1. date

    FbDate date;

  2. 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.