Yubikey – IV – Accès en VBA – 1 – Lecture du numéro de série

L’objectif dans cet article est de montrer comment il est possible d’accéder très facilement par programmation à la Yubikey grâce à la bibliothèque fournie par Yubico.

Pour ce faire je commencerais par un exemple très simples en VBA sous Excel :

  • Récupérer dans Excel le numéro de série de la Yubikey connectée.

Dans d’autres articles j’aborderai peut-être d’autres langages et d’autres OS.

Préparation du système

Pour accéder à la Yubikey par programmation sous Windows, il faut installer la bibliothèque COM-API cliente. L’installation est expliqué dans l’article « Protéger sa session Windows »  chapitre ‘Préparation de Windows’, lorsqu’il faut installer le client API 32 ou 64 bits.
ATTENTION : Pour Excel, si on est sur un système 64bits, il faut installer l’API 32bits Yubikey-Client-API-Installer_x86.msi (Excel est 32 bits). Si l’API 64 bits est déjà installée, ca n’est pas gênant.

Ensuite, il faut paramétrer Excel. Je pars sur la version 2007.
Il faut activer l’onglet développeur. On clique sur le bouton Office, puis sur ‘Options Excel’ :

prgyubikeyPuis, dans la rubrique ‘Standard’, on coche ‘Afficher l’onglet développeur dans le ruban’.

prgyubikey2On clique sur ‘Ok’, on dispose d’un nouveau menu sur le ruban, intitulé développeur :

prgyubikey3Ensuite on clique sur le bouton ‘Visual Basic’

prgyubikey4Dans le menu du mode Visual Basic, aller dans ‘Outils/Références’ :

prgyubikey5Dans la fenêtre qui liste les bibliothèques actives, cliquer sur le bouton ‘Parcourir’, puis aller chercher le dossier contenant la bibliothèque COM de Yubico :

  • Dans le dossier Program Files (x86)\Yubico\Yubikey Client API\Bin\x86

prgyubikey7Cliquer sur ‘Ouvir’, la bibliothèque de Yubico est maintenant disponible pour Excel :

prgyubikey8Gestion de la sécurité Excel

Comme nous allons manipuler des feuilles des calcul avec des programmes en VBA, lorsqu’on les ouvrira nous aurons un message d’alerte de sécurité qui sera le suivant :

prgyubikey9Pour activer le programme, il faut cliquer sur le bouton ‘Options…’ qui provoque l’affichage d’une nouvelle fenêtre :

prgyubikey10Il faut cocher ‘Activer le contenu’, puis cliquer sur OK pour que notre programme en VBA fonctionne.
C’est un petit peu lourd lorsque l’on développe et fait des tests. Je vais donc déclarer un Excel un emplacement de confiance, au sein duquel les fichiers ouverts ne provoqueront pas ces alertes de sécurité.

Je créé donc un dossier ‘Yubikey’ sous ‘Mes documents’. Mes feuilles Excel seront enregistrées dedans.
Ensuite, dans le menu ‘Développeur’, il y a une option ‘Sécurité des macros’ :

prgyubikey11Je clique dessus pour ouvrir le centre de gestion de la confidentialité, et je demande ‘Emplacements approuvés’ dans le bandeau de gauche :

prgyubikey12Une liste de dossiers de fiance est affichée. Dans le bas de la fenêtre on clique sur ‘Ajouter un nouvel emplacement…..’ :

prgyubikey13une fenêtre de choix s’affiche, cliquer sur parcourir et choisir le dossier de confiance, « Mes documents/Yubikey » en ce qui me concerne :

prgyubikey14Cliquer sur ‘Ok’, le nouvel emplacement apparaît dans a liste des emplacements approuvés :

prgyubikey15On ferme le centre de gestion de la confidentialité en cliquant sur le bouton ‘Ok’ en bas de la fenêtre. Désormais tous les documents Excel qui se trouveront à cet emplacement ne déclencherons plus une alerte de sécurité.

Programme de lecture du N° de série de la Yubikey

Ouvrir une feuille Excel vierge et la sauvegarder dans le dossier créé ci-dessus et faisant partie des emplacements de confiance.

Ensuite, dans le menu développeur, cliquer sur ‘Visual Basic’. L’environnement Visual Basic remplace la feuille de calcul Excel. Cliquer sur le bouton ‘Ajouter UserForm’

prgyubikey16afin d’avoir une fenêtre d’interaction :

prgyubikey17Disposer dessus

  • un bouton, nommé btnLecture
  • Un champs texte, qui affiche ‘N° de série’
  • Une zone de saisie nommée dfNumSerie

prgyubikey18Faire un clic droit dans la fenêtre d’interaction et demander ‘Code’ :

prgyubikey19Voici le code à entrer , que je vais expliquer plus bas.

Option Explicit
Dim WithEvents obj As YubiClientAPILib.YubiClient
 
Private Sub lecture()
    Dim retour As Integer
    Dim numserieh As String
 
    If obj.isInserted = ycRETCODE_OK Then
        retour = obj.readSerial(ycCALL_BLOCKING)
        obj.dataEncoding = ycENCODING_UINT32
        numserieh = obj.dataBuffer
        dfNumSerie.Value = numserieh
    Else
        dfNumSerie.Value = "Pas de Yubikey trouvé !"
    End If
End Sub
 
 
Private Sub btnLecture_Click()
    lecture
End Sub
 
Private Sub UserForm_Activate()
   Set obj = New YubiClient
   lecture
End Sub

On commence par indiquer à Excel que l’on va faire appel à la bibliothèque externe Yublicient :

Dim WithEvents obj As YubiClientAPILib.YubiClient

Lorsque la feuille Excel se charge, on crée l’objet obj, instance de Yubiclient :

  Set obj = New YubiClient

C’est en manipulant les propriétés et les méthodes de cet objet que l’on va pouvoir accéder à la Yubikey. On appelle ensuite la fonction lecture, qui peut aussi être appelée lorsque l’on appuis sur le bouton ‘Lecture’. C’est le contenu de cette fonction qui va réaliser les accès à la Yubikey pour en extraire le numéro de série.

La fonction lecture :

On a besoin de deux variables :

  • retour qui va contenir le code de retour lorsque l’on appelle une méthode permettant l’accès à la Yubikey. Cette variable permettra de savoir s’il y a eu erreur ou non.
  • numserieh, une chaine de caractère qui servira de dialogue avec la Yubikey. Dans notre fonction, c’est elle qui récupèrera le numéro de série de la clef.

On commence par tester si une Yubikey est insérée dans un port USB :

If obj.isInserted = ycRETCODE_OK

Si la propriété isInserted vaut ycRETCODE_OK, alors une Yubikey a été détectée, sinon il n’y a pas de Yubikey ou elle n’est pas vue. Les valeurs possibles sont :

  • ycRETCODE_OK – Une Yubikey est connectée.
  • ycRETCODE_MORE_THAN_ONE – Plusieurs Yubikey sont connectées.
  • ycRETCODE_NO_DEVICE – Pas de Yubikey connectée.

On demande ensuite à accéder au numéro de série de la Yubikey. Les dialogues entre notre programme et la Yubikey se font à travers une zone mémoire, nommée dataBuffer.

Voici schématiquement comment se passe l’interaction entre un programme et la Yubikey, lorsque l’on interroge la Yubikey.

LectureYubikeyDe plus, on a la possibilité de préciser sous quelle forme on souhaite récupérer les données dans le tampon. On dispose pour cela d’une propriété dataEncoding. Les valeurs possibles sont :

  • ycENCODING_BSTR_HEX – Hexadécimal en minuscules, sans espaces : 6b6c3132
  • ycENCODING_BSTR_HEX_SPACE : idem mais avec espaces : 6b 6c 31 32
  • ycENCODING_BSTR_MODHEX – Résultat au format Modhex de Yuco : hnhrebed
  • ycENCODING_BSTR_BASE64 – Chaine au format Base64 : a2wxMg==
  • ycENCODING_BSTR_ASCII – Chaine au format ASCII : k112
  • ycENCODING_UINT16 – Entier sur 2 octets
  • ycENCODING_UINT32 – Entier sur 4 octets
  • ycENCODING_BYTE_ARRAY – Tableau dynamique d’octets

Le tampon est accessible en permanence, et on peut demander une conversion à la volée. Ainsi, dans notre exemple on récupérera un numéro de série sous forme d’un entier 32 bits, mais si on souhaite aussi récupérer ce numéro sous forme Hexadécimale, il suffira de modifier la propriété dataEncoding et de relire de nouveau le tampon, sans avoir besoin d’interroger de nouveau la Yubikey.

Au niveau code :

        retour = obj.readSerial(ycCALL_BLOCKING)
        obj.dataEncoding = ycENCODING_UINT32
        numserieh = obj.dataBuffer
        dfNumSerie.Value = numserieh
  • On appelle la méthode de lecture du numéro de série (On verra son paramètre plus bas)
  • On spécifie qu’on veut lire le résultat sous forme d’un entier sur 2 octets
  • On lit le buffer et on stocke le résultat dans numserieh
  • On affiche la valeur dans la zone de saisie de texte.

Test du programme

On lance l’exécution du programme VBA en appuyant sur la touche F5, et s’il n’y a pas d’erreur le résultat devrait être :

prgyubikey20Le numéro de série affiché est celui de la Yubikey, qui est aussi gravé sur la clef sous le code-barres 2D. Si on change de Yubikey et que l’on clique sur le bouton lecture, le numéro de série de la nouvelle Yubikey remplace l’ancien. Pour fermer, cliquer sur la croix rouge.

Accès en mode bloquant/non bloquant

Lorsque l’on fait appel à la méthode de demande de lecture du numéro de série, on spécifie un paramètre : ycCALL_BLOCKING

obj.readSerial(ycCALL_BLOCKING)

Il y a deux modes d’accès à la Yubikey :

  • Le mode bloquant ou synchrone. Le plus simple à utiliser. Le programme est bloqué sur l’appel à la fonction tant que celle-ci n’a pas répondu. Ca peut figer le programme si la fonction ne fait pas de retour. Pour utiliser ce mode on spécifie dans le paramètre d’appel ycCALL_BLOCKING
  • Le mode non bloquant ou asynchrone. Plus complexe. L’exécution de la fonction se fait dans un thread séparé. Le programme appelant n’est pas interrompu mais poursuit ses traitements. Quand la réponse a été reçue, un appel asynchrone à une fonction est lancé par le thread qui exécutait la fonction de la Yubikey. Pour utiliser ce mode on spécifie dans le paramètre d’appel ycCALL_ASYNC

Voici le même programme d’affichage du numéro de série en version asynchrone :

Option Explicit
Dim WithEvents obj As YubiClientAPILib.YubiClient
 
Private Sub lecture()
    Dim retour As Integer
    Dim numserieh As String
 
    If obj.isInserted = ycRETCODE_OK Then
        retour = obj.readSerial(ycCALL_ASYNC)
    Else
        dfNumSerie.Value = "Pas de Yubikey trouvé !"
    End If
End Sub
Private Sub btnLecture_Click()
    lecture
End Sub
Private Sub obj_operationCompleted(ByVal rc As YubiClientAPILib.ycRETCODE)
    If rc = ycRETCODE_OK Then
         dfNumSerie.Value = obj.dataBuffer
    Else
        dfNumSerie.Value = "Erreur lecture !"
    End If
End Sub
Private Sub UserForm_Activate()
   Set obj = New YubiClient
   obj.dataEncoding = ycENCODING_UINT32
   lecture
End Sub

On remarque tout de suite la différence. Lorsque la fonction lecture est appelée, elle demande le transfert du numéro de série dans le buffer en mode asynchrone

obj.readSerial(ycCALL_ASYNC)

et de ce fait ne se charge plus de récupérer le résultat pour l’afficher. C’est une autre fonction, obj_operationCompleted qui s’en chargera. Cette fonction sera appelée automatiquement par le thread qui lit le numéro de série dès que le résultat sera disponible. Nous n’avons donc pas à craindre un blocage du programme, par contre il faudra bien à un moment s’assurer que le résultat est parvenu, surtout si on doit faire d’autres opérations. C’est en cela que c’est un peu plus compliqué.

Dans l’article suivant, nous verrons comment utiliser la fonction HMAC-SHA1 en VBA.

Posts relatifs

Laisser un commentaire


NOTE - Vous pouvez utiliser les éléments et attributs HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre lang="" line="" escaped="" cssfile="">