From e592d8bbf42b57205d3f9250fdd3a5abf7df906d Mon Sep 17 00:00:00 2001 From: Sumit Bose Date: Oct 04 2018 09:17:43 +0000 Subject: Adding design page for requiring certificate authentication Related to https://pagure.io/SSSD/sssd/issue/3650 --- diff --git a/design_pages/index.rst b/design_pages/index.rst index 2b85ade..e616db9 100644 --- a/design_pages/index.rst +++ b/design_pages/index.rst @@ -22,6 +22,7 @@ Implemented in 2.0.x :maxdepth: 1 certmaps_for_LDAP_AD_file + smartcard_authentication_require Implemented in 1.16.x --------------------- diff --git a/design_pages/smartcard_authentication_require.rst b/design_pages/smartcard_authentication_require.rst new file mode 100644 index 0000000..d4d57e2 --- /dev/null +++ b/design_pages/smartcard_authentication_require.rst @@ -0,0 +1,179 @@ +Require Smartcard authentication (for local users) +================================================== + +Related ticket(s): +------------------ + https://pagure.io/SSSD/sssd/issue/3650 + +Problem statement +----------------- +By default SSSD tries to determine what authentication methods are available +for a user and prompts accordingly. This is primarily done by figuring out the +supported authentication methods on the server. E.g. the ``krb5`` provider will +use the available pre-authentication methods to determine how the user can +authenticate. If a user should only and always use Smartcard authentication the +long term password can be removed on the server side so that the user can only +user PKINIT for authentication. For FreeIPA domains there are `authentication +indicators`_ to requires specific authentication methods for services. + +.. _authentication indicators: https://www.freeipa.org/page/V4/Authentication_Indicators + +Currently SSSD does not handle the general authentication of local user because +this is still done by ``pam_unix``. However SSSD offers the support for +Smartcard authentication for local user. To be flexible and offer the user the +most suitable prompting during authentication SSSD currently only prompt for a +Smartcard PIN if a Smartcard is inserted with certificates which can mapped to +the user trying to log in. This means that local users cannot easily be forced +to use Smartcard authentication where the user is prompted to insert a +Smartcard and SSSD waits until a suitable card is inserted. + +Use cases +--------- +Local users +^^^^^^^^^^^ +Force local users to use Smartcard authentication + +Active Directory +^^^^^^^^^^^^^^^^ +Although Active Directory offers the 'Smart card is required for interactive +logon' option it might not be suitable for all use cases because it disables +password based authentication which might still be needed for certain services. +Having an option on the client to require Smartcard authentication for specific +services would help here as well. + +Overview of the solution +------------------------ +There are two places where an option to enforce Smartcard authentication can be +set, the SSSD configuration file ``sssd.conf`` or the option list of the +``pam_sss`` PAM module. + +In general we try to avoid adding options to the PAM module to keep the PAM +module as dump and simple as possible and do all processing in SSSD's PAM +responder and the backends. But in the given case options for the PAM module +offer greater flexibility with a less complex configuration. To keep the +``pam_sss`` PAM module still simple, it will forward the provided option to +SSSD and check the reply if Smartcard authentication is possible or return an +error. + +Besides and option to require Smartcard authentication and option to only check +if Smartcard authentication is available will be added as well to allow more +flexible PAM configurations. + +Implementation details +---------------------- +``p11_child`` +^^^^^^^^^^^^^ +``p11_child`` needs a new option to wait until a card is available if no +suitable card is available. Since the PAM responder will kill ``p11_child`` if +a timeout expires an option is needed to let the PAM responder wait longer to +allow the child to wait longer. + +If a slot with with the ``CKF_REMOVABLE_DEVICE`` flag was found ``p11_child`` +can check if the PKCS#11 call ``C_WaitForSlotEvent`` is implemented and use it. +If the PKCS#11 does not implement this call ``p11_child`` can call +``C_GetSlotInfo`` in regular interval until a token is present or it is kill by +the PAM responder. NSS provides the ``PK11_WaitForTokenEvent`` call to handle +this. + +If there is no slot with the ``CKF_REMOVABLE_DEVICE`` flag set ``p11_child`` +has to run ``C_Finalize``-``C_Initialize`` cycles to be able to discover new +slots. This is e.g. needed for Yubikey USB devices which are from the PKCS#11 +perspective Smartcard (tokens) and reader (slot) in a single device. + +``pam_sss`` +^^^^^^^^^^^ +The PAM module ``pam_sss`` will get two new flag options: + +``try_cert_auth`` + Try to use certificate based authentication, i.e. + authentication with a Smartcard or similar devices. If a + Smartcard is available and the service is allowed for + Smartcard authentication the use will be prompted for a + PIN and the certificate based authentication will + continue. + + If no Smartcard is available or certificate based + authentication is not allowed for the current service + ``PAM_AUTHINFO_UNAVAIL`` is returned. + +``require_cert_auth`` + Wait until a Smartcard suitable for authentication is + available and ask the user to insert a Smartcard. + + If no Smartcard is available or certificate based + authentication is not allowed for the current service + ``PAM_AUTHINFO_UNAVAIL`` is returned. + +The PAM module will forward the flags to the PAM responder in a 32bit integer +which will handled the request accordingly. If the reply of the PAM responder +does not contain the needed information to prompt the user for a Smartcard PIN +the PAM module will return ``PAM_AUTHINFO_UNAVAIL``. + +PAM responder +^^^^^^^^^^^^^ +The PAM responder will get a new option to increase the waiting time for +``p11_child`` if the ``require_cert_auth`` flag was received from the client. +To receive the flags the PAM responder must be prepared to handle to 32bit +integer send by the client containing the flags. + +Configuration changes +--------------------- +``p11_child`` +^^^^^^^^^^^^^ +``p11_child`` is mentioned here for completeness, since it is an internal helper this change is not directly relevant for users. + +New option: + +``--wait_for_card`` + Wait until a Smartcard (token) is available in a reader (slot) + +``pam_sss`` +^^^^^^^^^^^ +New options: + +``try_cert_auth`` + see above + +``require_cert_auth`` + see above + +PAM responder: +^^^^^^^^^^^^^^ +New option: + +``p11_wait_for_card_timeout`` + If Smartcard authentication is required how many + extra seconds in addition to p11_child_timeout + should the PAM responder wait until a Smartcard is + inserted. + + Default: 60 (seconds) + + +How to test +----------- +To test the feature the PAM configuration ahd to be modified and ``pam_sss`` has to be added with the ``require_cert_auth`` or ``try_cert_auth`` option at a suitable place. + +Allow Smartcard authentication for local users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To allow Smartcard authentication for local user but use password authentication as a fallback if no Smartcard is available the following snippet might be added to the PAM configuration:: + + .... + auth [default=2 success=ok] pam_localuser.so + auth sufficient pam_sss.so try_cert_auth + auth [success=done ignore=ignore default=die] pam_unix.so try_first_pass + .... + +Require Smartcard authentication for local users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To require Smartcard authentication for local user the following snippet might be added to the PAM configuration:: + + .... + auth [default=2 success=ok] pam_localuser.so + auth required pam_sss.so require_cert_auth + auth required pam_deny.so + .... + +Authors +------- + * Sumit Bose ````