orange-yourdev-login/Notes_pkcs11.md

Configuration pam-pkcs11
------------------------

Thierry Tallagrand à la rescousse !

Installation:

```
# apt install libpam-pkcs11
```

Ajouts des certificats Orange, parce que pam-pcs11 utilise son propre trousseau:
```
# mkdir /etc/pki/nssdb
# orange-certupdate /etc/pki/nssdb
# cp /usr/share/ca-certificates/orange/* /etc/pam_pkcs11/cacerts
# (cd /etc/pam_pkcs11/cacerts && pkcs11_make_hash_link)
```

Création d'une configuration spécifique  `/etc/pam_pkcs11/pam_pkcs11.conf`
pour le dongle Safenet, en s'inspirant du fichier d'exemple de la documentation
dans `/usr/share/doc/libpam-pkcs11/examples/pam_pkcs11.conf.example`. 
Il y a trois parties dans ce fichier:

  - les paramètres globaux de pam-pkcs11
  - la description du module Safenet
  - la définition du (des) mapper(s) certificat -> utilisateur.

Pour bien comprendre le rôle des différentes propriétés top-level et des 
modules, voir le fichier `/usr/share/doc/libpam-pkcs11/README.gz`. Pour 
une présentation de ce qu'est un mapper, les deux processus de login 
quand on utilise un mapper (important), et la description des mappers
fournis, voir `/usr/share/doc/libpam-pkcs11/README.mappers.gz`.

On utilise le mapper `uid` parce que cette propriété est présente dans 
le champ 'Subject' du certificat `Auth`, elle est reconnue automatiquement.
On aura besoin d'un fichier de mapping qui fait correspondre la valeur
de l'UID du certificat avec le nom d'un utilisateur local sur la machine.
La correspondance est triviale, les UID sont en majuscule et les utilisateurs
en minuscules:

```
$ cat /etc/pam_pkcs11/uid_mapping 
ABCD1234 -> abcd1234
```

Voir le script `/usr/bin/pkcs11_generate_uids` pour générer ce fichier 
automatiquement à partir de la définition des utilisateur locaux dans 
`/etc/passwd`.

Une fois le fichier de mapping en place, on peut le tester avec la 
commande `pklogin_finder` après avoir inséré le dongle:

```
$ pklogin_finder
[...]
DEBUG:mapper_mgr.c:213: unloading mapper module list
DEBUG:mapper_mgr.c:137: calling mapper_module_end() uid
DEBUG:mapper_mgr.c:148: Module uid is static: don’t remove
DEBUG:pkcs11_lib.c:1490: logout user
DEBUG:pkcs11_lib.c:1497: closing the PKCS #11 session
DEBUG:pkcs11_lib.c:1503: releasing keys and certificates
DEBUG:pklogin_finder.c:169: releasing pkcs #11 module…
DEBUG:pklogin_finder.c:172: Process completed
[...]
DEBUG:pklogin_finder.c:151: Certificate is valid and maps to user tmzf5455
```

Le module pam-pkcs11 est maintenant configuré, il reste à le faire
prendre en compte par GDM:
```
# update-alternatives --config gdm-smartcard

There are 3 choices for the alternative gdm-smartcard (providing /etc/pam.d/gdm-smartcard).
Selection Path Priority Status

    0 /etc/pam.d/gdm-smartcard-sssd-exclusive 50 auto mode
    1 /etc/pam.d/gdm-smartcard-pkcs11-exclusive 30 manual mode
    2 /etc/pam.d/gdm-smartcard-sssd-exclusive 50 manual mode
    3 /etc/pam.d/gdm-smartcard-sssd-or-password 40 manual mode

Press to keep the current choice[*], or type selection number:
```

Choisir 1) pour `gdm-smartcard-pkcs11-exclusive` et valider. Important: il faut 
aussi que GDM permette le login par smartcard, voir les notes concernant GDM.


Voir [l'article original sur le wiki](
https://yourdev.tech.orange/linux-article/login-with-pki/) avec screenshots.


Saisie du compte avec GDM
-------------------------

Avec la première tentative de configuration issue directement de
`pam_pkcs11.conf.example`, on constate lorsque le dongle PKI est inséré
que GDM demande la saisie explicite du nom de l'utilisateur avant de
demander le PIN. C'est différent du mode habituel sans PKCS#11 où 
GDM propose l'utilisateur (liste), et il n'y a que le mot de passe
à saisir.

Le comportement observé correspond au premier mode de fonctionnement
décrit dans `/usr/share/doc/libpam-pkcs11/README.mappers.gz`:
```
Normal pam-pkcs11 login process involves the following procedures
    - Enter login
    - Ask for PIN
    - Open and validate certificate
    - Map certificate into an user (*)
    - Check if login and user matches (**)
```

alors que ce qu'on voudrait c'est le deuxième mode:
```
An alternate way of working is by mean of not providing user name:
    - Detect if a card is inserted
    - Ask for PIN
    - Open and validate certificate
    - Map certificate into an user (*)
    - open session for deduced login
```

On passe de l'un a l'autre avec la propriétés top-level `card_only` qui
est décrité dans `/usr/share/doc/libpam-pkcs11/README.gz`:
```
  card_only
    Always try to get the userid from the certificate, don't prompt for the
    user name if the card is present, and if the token is present, then we
    must use it to authenticate.

  wait_for_card
    This option needs card_only to be set. This will make the system wait
    for the token to be inserted on login, or after login it will require
    the same token  be inserted to unlock the system.
```

La documentation dit aussi que dans le deuxième mode il faut aussi le
module `pam-mkhomedir.so` pour créer dynamiquement le compte utilisateur,
ce n'est pas forcément ce qu'on veut, à voir si ça marche sans avec
un compte existant.

Néanmoins, avec `card_only = true;` dans `pam_pkcs11.conf`, GDM continue à 
demander un identifiant, bref il semble que cela ne fonctionne pasn au moins
sur Hirsute ... Bug dans GDM ? Fonctionnalité non prise en compte ?  


Activer PKCS#11 dans GDM
------------------------

Trois opérations à faire:

  - basculer l'alternative `gdm-smartcard` sur `gdm-smartcard-pkcs11-exclusive`
  - activer l'authentification par smartcard dans `dconf` pour GDM
  - redémarrer le service

soit:

```
# update-alternatives --set gdm-smartcard /etc/pam.d/gdm-smartcard-pkcs11-exclusive
# sed -Ei 's/(enable-smartcard-authentication)=.*/\1=true/' /etc/dconf/db/gdm.d/03-smartcard
# dconf update
# systemctl restart gdm3
```

Il faudrait un script pour automatiser cela ...

Limitations
-----------

Le paquet `libpam-pkcs11` ne fournit pas de configuration pour `pam-auth-update`
 dans `/usr/share/pam-configs`, donc l'authentification PKCS#11 ne peut pas 
être ajoutée automatiquement dans `/etc/pam.d/common-auth`. Par conséquent, elle 
ne sera disponible que dans GDM via `/etc/pam.d/gdm-smartcard`, si on la voulait 
aussi en mode console il faudrait bricoler dans la configuration PAM ...  

Dans `gdm-smartcard-pkcs11-exclusive`, il n'y a que le module `pam_pkcs11.so`,
donc après authentification par token on n'obtiendra pas de TGT Kerberos. Il 
faudrait bricoler pour rajouter `pam_krb5.so`, sans aucune garantie que ça 
marche, le problème étant 1) faire circuler le PIN et 2) faire comprendre à 
`pam_krb5.so` qu'il s'agit d'un PIN et pas d'un mot de passe... Autant essayer
de faire cela avec SSSD.

Contrairement à ce que `pkcs11-exclusive` laisse entendre, si le dongle n'est
pas présent dans le port USB, on peut toujours se connecter par login/password
(mais Kerberos foonctionnera-t'il si `pam_krb5.so` est présent ?)

Références
----------

  - [PAM-PKCS11 Login Tools]
  - [PAM-PKCS11 User Manual]
  - [PAM-PKCS11 Mappers API]
  - [Local PAM-PKCS11 documentation]


[PAM-PKCS11 Login Tools]: https://github.com/OpenSC/pam_pkcs11
[PAM-PKCS11 User Manual]: http://opensc.github.io/pam_pkcs11/doc/pam_pkcs11.html
[PAM-PKCS11 Mappers API]: http://opensc.github.io/pam_pkcs11/doc/mappers_api.html
[Local PAM-PKCS11 documentation]: file:///usr/share/doc/libpam-pkcs11