Configuring Linux PAM to use the MIRkey security key for authentication

In this How-To we will show you how to configure Linux PAM to use a MIRkey for password-less login

Prerequisites

1. The configuration we demonstrate here maps a key pair on the MIRkey to a log-in on Linux using the pam-pkcs11 OpenSSH mapper. This allows you access if the public key is authorized in the SSH user/.ssh/authorized_keys file. For other mappers, consult the user manual or contact us for support.

2. Follow the OpenSSH How-To to generate a key pair and ensure the public key is added to the user/.ssh/authorized_keys file

3. Download and install the PKCS#11 shared library:

    sudo apt install ./eHSM-pkcs11-x.x.deb
   

4. Install libpam-pkcs11:

    sudo apt-get install libpam-pkcs11
   

Configuring pam-pkcs11

1. Edit or create /etc/pam_pkcs11/pam_pkcs11.conf from the sample configuration we provide here.

   Modify the “use_pkcs11_module” entry to use the MIRkey module:

      use_pkcs11_module = MIRkey;
   

   and add this section:

      pkcs11_module MIRkey {
        module = /usr/lib/x86_64-linux-gnu/libehsm.so;
        description = "eHSM pkcs#11 module";
        slot_num = 0;
        support_threads = false;
        ca_dir = /etc/pam_pkcs11/cacerts;
        crl_dir = /etc/pam_pkcs11/crls;
        cert_policy = none;
      }
   

   Modify or add the “use_mappers” entry to use the openssh mapper:

      use_mappers = openssh, other mappers, ...;
   

   The complete sample config file should look something like this:

   pam_pkcs11 { # Allow empty passwords nullok = true; # Enable debugging support. debug = false; # Do not prompt the user for the passwords but take them from the # PAM_ items instead. use_first_pass = false; # Do not prompt the user for the passwords unless PAM_(OLD)AUTHTOK # is unset. try_first_pass = false; # Like try_first_pass, but fail if the new PAM_AUTHTOK has not been # previously set (intended for stacking password modules only). use_authtok = false; use_pkcs11_module = MIRkey; # eHSM pkcs11 module pkcs11_module MIRkey { module = /usr/lib/x86_64-linux-gnu/libehsm.so; description = "eHSM pkcs#11 module"; slot_num = 0; support_threads = false; ca_dir = /etc/pam_pkcs11/cacerts; crl_dir = /etc/pam_pkcs11/crls; cert_policy = none; } # Which mappers ( Cert to login ) to use? # you can use several mappers: # # subject - Cert Subject to login file based mapper # pwent - CN to getpwent() login or gecos fields mapper # ldap - LDAP mapper # opensc - Search certificate in ${HOME}/.eid/authorized_certificates # openssh - Search certificate public key in ${HOME}/.ssh/authorized_keys # mail - Compare email fields from certificate # ms - Use Microsoft Universal Principal Name extension # krb - Compare against Kerberos Principal Name # cn - Compare Common Name (CN) # uid - Compare Unique Identifier # digest - Certificate digest to login (mapfile based) mapper # generic - User defined certificate contents mapped # null - blind access/deny mapper # # You can select a comma-separated mapper list. use_mappers = openssh, digest, cn, pwent, uid, mail, subject, null; # # Generic certificate contents mapper mapper generic { debug = true; module = internal; # ignore letter case on match/compare ignorecase = false; # Use one of "cn" , "subject" , "kpn" , "email" , "upn" , "uid" or "serial" cert_item = cn; # Define mapfile if needed, else select "none" mapfile = file:///etc/pam_pkcs11/generic_mapping; # Decide if use getpwent() to map login use_getpwent = false; } # Certificate Subject to login based mapper # provided file stores one or more "Subject -> login" lines mapper subject { debug = false; module = internal; ignorecase = false; mapfile = file:///etc/pam_pkcs11/subject_mapping; } # Search public keys from $HOME/.ssh/authorized_keys to match users mapper openssh { debug = false; module = /lib/pam_pkcs11/openssh_mapper.so; } # Certificate Common Name ( CN ) to getpwent() mapper mapper pwent { debug = false; ignorecase = false; module = internal; } # Null ( no map ) mapper. when user as finder matches to NULL or "nobody" mapper null { debug = false; module = internal ; # select behavior: always match, or always fail default_match = false; # on match, select returned user default_user = nobody ; } # Assume common name (CN) to be the login mapper cn { debug = false; module = internal; ignorecase = true; # mapfile = file:///etc/pam_pkcs11/cn_map; mapfile = "none"; } # mail - Compare email field from certificate mapper mail { debug = false; module = internal; # Declare mapfile or # leave empty "" or "none" to use no map mapfile = file:///etc/pam_pkcs11/mail_mapping; # Some certs store email in uppercase. take care on this ignorecase = true; # Also check that host matches mx domain # when using mapfile this feature is ignored ignoredomain = false; } # ms - Use Microsoft Universal Principal Name extension # UPN is in format login@ADS_Domain. No map is needed, just # check domain name. mapper ms { debug = false; module = internal; ignorecase = false; ignoredomain = false; domainname = "domain.com"; } # krb - Compare against Kerberos Principal Name mapper krb { debug = false; module = internal; ignorecase = false; mapfile = "none"; } # uid - Maps Subject Unique Identifier field (if exist) to login mapper uid { debug = false; module = internal; ignorecase = false; mapfile = "none"; } # digest - elaborate certificate digest and map it into a file mapper digest { debug = false; module = internal; # algorithm used to evaluate certificate digest # Select one of: # "null","md2","md4","md5","sha","sha1","dss","dss1","ripemd160" algorithm = "sha1"; mapfile = file:///etc/pam_pkcs11/digest_mapping; # mapfile = "none"; } }

2. Test the configuration with sudo

   edit /etc/pam.d/sudo and add:

    auth sufficient pam_pkcs11.so
   

   to the file, then test sudo:

    sudo -i
   

   The output (with debugging enabled) should look like this:

    Smartcard authentication starts
    DEBUG:pam_pkcs11.c:335: username = [test]
    DEBUG:pam_pkcs11.c:346: loading pkcs #11 module...
    DEBUG:pkcs11_lib.c:973: PKCS #11 module = [/usr/lib/x86_64-linux-gnu/libehsm.so]
    DEBUG:pkcs11_lib.c:990: module permissions: uid = 0, gid = 0, mode = 644
    DEBUG:pkcs11_lib.c:999: loading module /usr/lib/x86_64-linux-gnu/libehsm.so
    DEBUG:pkcs11_lib.c:1007: getting function list
    DEBUG:pam_pkcs11.c:361: initialising pkcs #11 module...
    DEBUG:pkcs11_lib.c:1155: module information:
    DEBUG:pkcs11_lib.c:1156: - version: 2.40
    DEBUG:pkcs11_lib.c:1157: - manufacturer: ellipticSecure                  
    DEBUG:pkcs11_lib.c:1158: - flags: 0000
    DEBUG:pkcs11_lib.c:1159: - library description: ellipticSecure PKCS11 Library   
    DEBUG:pkcs11_lib.c:1160: - library version: 2.0
    DEBUG:pkcs11_lib.c:1050: number of slots (a): 1
    DEBUG:pkcs11_lib.c:1073: number of slots (b): 1
    DEBUG:pkcs11_lib.c:1086: slot 1:
    DEBUG:pkcs11_lib.c:1096: - description: MIRkey USB                                                        
    DEBUG:pkcs11_lib.c:1097: - manufacturer: USB                             
    DEBUG:pkcs11_lib.c:1098: - flags: 0001
    DEBUG:pkcs11_lib.c:1100: - token:
    DEBUG:pkcs11_lib.c:1106:   - label: Test                           
    DEBUG:pkcs11_lib.c:1107:   - manufacturer: ellipticSecure                  
    DEBUG:pkcs11_lib.c:1108:   - model: MIRkey            
    DEBUG:pkcs11_lib.c:1109:   - serial: 10A614E73BCB
    DEBUG:pkcs11_lib.c:1110:   - flags: 044d
    Smart card found.
    DEBUG:pkcs11_lib.c:1386: opening a new PKCS #11 session for slot 1
    Welcome Test!
    Smart card PIN: 
    DEBUG:pkcs11_lib.c:1405: login as user CKU_USER
    DEBUG:pkcs11_lib.c:1599: Saving Certificate #1:
    DEBUG:pkcs11_lib.c:1601: - type: 00
    DEBUG:pkcs11_lib.c:1602: - id:   68
    DEBUG:pkcs11_lib.c:1599: Saving Certificate #2:
    DEBUG:pkcs11_lib.c:1601: - type: 00
    DEBUG:pkcs11_lib.c:1602: - id:   63
    DEBUG:pkcs11_lib.c:1634: Found 2 certificates in token
    DEBUG:mapper_mgr.c:172: Retrieveing mapper module list
    DEBUG:mapper_mgr.c:95: Loading dynamic module for mapper 'openssh'
    DEBUG:mapper_mgr.c:196: Inserting mapper [openssh] into list
    DEBUG:pam_pkcs11.c:578: verifying the certificate #1
    verifying certificate
    DEBUG:cert_vfy.c:416: Neither CA nor CRL check requested. CertVrfy() skipped
    DEBUG:mapper_mgr.c:306: Mapper module openssh match() returns 1
    DEBUG:pam_pkcs11.c:664: certificate is valid and matches the user
    DEBUG:pam_pkcs11.c:746: Skipping signature check
    DEBUG:mapper_mgr.c:213: unloading mapper module list
    DEBUG:mapper_mgr.c:137: calling mapper_module_end() openssh
    DEBUG:mapper_mgr.c:145: unloading module openssh
    DEBUG:pkcs11_lib.c:1465: logout user
    DEBUG:pkcs11_lib.c:1472: closing the PKCS #11 session
    DEBUG:pkcs11_lib.c:1478: releasing keys and certificates
    DEBUG:pam_pkcs11.c:827: releasing pkcs #11 module...
    DEBUG:pam_pkcs11.c:830: authentication succeeded
    DEBUG:pam_pkcs11.c:846: pam_sm_setcred() called
   

3. If it works then you can enable this login method for all PAM login modules

   Modify /etc/pam.d/common-auth and add “auth [success=2 default=ignore] pam_pkcs11.so”

    auth    [success=2 default=ignore]      pam_pkcs11.so
    auth	[success=1 default=ignore]	pam_unix.so nullok_secure
    # here's the fallback if no module succeeds
    auth	requisite			pam_deny.so
   

4. When you are comfortable with the security key login method (and have a few backup keys in case of loss or damage), you can disable password login completely:

    sudo passwd -l `whoami`