[pve-devel] applied: [PATCH docs] pveum: improve tfa section

[Thomas Lamprecht]

On 11/29/19 3:17 PM, Oguz Bektas wrote:
> * s/two-factor/two factor

applied, fixed above to "s/two factor/two-factor" though ;) Thanks!

> * add explicit mention of TOTP (Time-based One-time Password)
> * wrap lines/paragraphs
> * minor edits on wording or punctuation
> 
> Signed-off-by: Oguz Bektas <o.bektas at proxmox.com>
> ---
>  pveum.adoc | 67 +++++++++++++++++++++++++++---------------------------
>  1 file changed, 34 insertions(+), 33 deletions(-)
> 
> diff --git a/pveum.adoc b/pveum.adoc
> index 3f21078..59a2824 100644
> --- a/pveum.adoc
> +++ b/pveum.adoc
> @@ -54,7 +54,7 @@ Each user entry in this file contains the following information:
>  * An optional Expiration date
>  * A comment or note about this user
>  * Whether this user is enabled or disabled
> -* Optional two factor authentication keys
> +* Optional two-factor authentication keys
>  
>  
>  System administrator
> @@ -148,44 +148,44 @@ encryption can be configured.
>  
>  
>  [[pveum_tfa_auth]]
> -Two factor authentication
> +Two-factor authentication
>  -------------------------
>  
> -There are two ways to use two factor authentication:
> +There are two ways to use two-factor authentication:
>  
> -It can be required by the authentication realm, either via 'TOTP' or
> -'YubiKey OTP'. In this case a newly created user needs their keys added
> -immediately as there is no way to log in without the second factor. In the case
> -of 'TOTP' a user can also change the 'TOTP' later on provided they can log in
> -first.
> +It can be required by the authentication realm, either via 'TOTP'
> +(Time-based One-Time Password) or 'YubiKey OTP'. In this case a newly
> +created user needs their keys added immediately as there is no way to
> +log in without the second factor. In the case of 'TOTP', users can
> +also change the 'TOTP' later on, provided they can log in first.
>  
> -Alternatively a user can choose to opt into two factor authentication via 'TOTP'
> -later on even if the realm does not enforce it. As another option, if the server
> -has an 'AppId' configured, a user can opt into 'U2F' authentication, provided
> -the realm does not enforce any other second factor.
> +Alternatively, users can choose to opt in to two-factor authentication
> +via 'TOTP' later on, even if the realm does not enforce it. As another
> +option, if the server has an 'AppId' configured, a user can opt into
> +'U2F' authentication, provided the realm does not enforce any other
> +second factor.
>  
> -Realm enforced two factor authentication
> +Realm enforced two-factor authentication
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -This can be done by selecting one of the available methods
> -via the 'TFA' dropdown box when adding or editing an Authentication Realm.
> -When a realm has TFA enabled it becomes a requirement and only users with
> -configured TFA will be able to login.
> +This can be done by selecting one of the available methods via the
> +'TFA' dropdown box when adding or editing an Authentication Realm.
> +When a realm has TFA enabled it becomes a requirement and only users
> +with configured TFA will be able to login.
>  
>  Currently there are two methods available:
>  
> -Time based OATH (TOTP)::
> -This uses the standard HMAC-SHA1 algorithm where the current time is hashed
> -with the user's configured key. The time step and password length
> -parameters are configured.
> +Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm
> +where the current time is hashed with the user's configured key. The
> +time step and password length parameters are configured.
>  +
> -A user can have multiple keys configured (separated by spaces), and the
> -keys can be specified in Base32 (RFC3548) or hexadecimal notation.
> +A user can have multiple keys configured (separated by spaces), and the keys
> +can be specified in Base32 (RFC3548) or hexadecimal notation.
>  +
> -{pve} provides a key generation tool (`oathkeygen`) which prints out a
> -random key in Base32 notation which can be used directly with various OTP
> -tools, such as the `oathtool` command line tool, the Google authenticator
> -or FreeOTP Android apps.
> +{pve} provides a key generation tool (`oathkeygen`) which prints out a random
> +key in Base32 notation which can be used directly with various OTP tools, such
> +as the `oathtool` command line tool, or on Android Google Authenticator,
> +FreeOTP, andOTP or similar applications.
>  
>  YubiKey OTP::
>  For authenticating via a YubiKey a Yubico API ID, API KEY and validation
> @@ -193,19 +193,20 @@ server URL must be configured, and users must have a YubiKey available. In
>  order to get the key ID from a YubiKey, you can trigger the YubiKey once
>  after connecting it to USB and copy the first 12 characters of the typed
>  password into the user's 'Key IDs' field.
> +
>  +
> -Please refer to the
> -https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
> +Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
> +documentation for how to use the
>  https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
> -https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
> -host your own verification server].
> +https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[host
> +your own verification server].
>  
>  [[pveum_user_configured_totp]]
>  User configured TOTP authentication
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -A user can choose to use 'TOTP' as a second factor on login via the 'TFA' button
> -in the user list, unless the realm enforces 'YubiKey OTP'.
> +Users can choose to enable 'TOTP' as a second factor on login via the 'TFA'
> +button in the user list (unless the realm enforces 'YubiKey OTP').
>  
>  [thumbnail="screenshot/gui-datacenter-users-tfa.png"]
>  
>