[DRAFT] update yubikey documenation

Question
1

Here are some updates I’ve been working on. Comments?

diff --git a/doc/configuration/tokenconfig/images/yubikey.png b/doc/configuration/tokenconfig/images/yubikey.png
new file mode 100644
index 0000000…502100c
Binary files /dev/null and b/doc/configuration/tokenconfig/images/yubikey.png differ
diff --git a/doc/configuration/tokenconfig/yubikey.rst b/doc/configuration/tokenconfig/yubikey.rst
new file mode 100644
index 0000000…8bd964e
— /dev/null
+++ b/doc/configuration/tokenconfig/yubikey.rst
@@ -0,0 +1,29 @@+
+… _yubikey_token_config:
+
+Yubikey AES mode
+…
+
+… index:: Yubikey AES mode
+
+The Yubico AES mode uses the same kind of token as the Yubico Cloud service,
+but validates the OTP in your local privacyidea server. So the secrets
+stay local to your system and are not stored in Yubico’s Cloud service.
+
+… figure:: images/yubikey.png

  • :width: 500
  • Configure the Yubikey AES mode

+You can have more than one Client with a Client ID connect to your server.
+The Client ID starts with yubikey.apiid. and is followed by the API ID,
+which you’ll need to configure your clients.
+With create new API key you generate a new API for that specific
+Client ID. The API key is used to sign the validation request sent to the
+server and the server signs the answer too. That way tampering or
+MITM attacks might be detected. It is possible to validate token without
+the API key, but then the request and answer can’t be verify against
+the key. It is useful to use HTTPS for your validation requests, but
+this is another kind of protection.
+
+
diff --git a/doc/configuration/tokens/yubikey.rst b/doc/configuration/tokens/yubikey.rst
index 5bd71c0…31549a4 100644
— a/doc/configuration/tokens/yubikey.rst
+++ b/doc/configuration/tokens/yubikey.rst
@@ -6,22 +6,17 @@ Yubikey
… index:: Yubikey, Yubico AES mode

The Yubikey is initialized with privacyIDEA and works in Yubicos own AES mode.
-It outputs a 44 digit OTP value. But in contrast to the :ref:yubico Cloud
+It outputs a 44 character OTP value, consisting of a 12 character prefix and
+a 32 character OTP. But in contrast to the :ref:yubico Cloud
mode, in this mode the secret key is contained within the token and your own
privacyIDEA installation.

If you have the time and care about privacy, you should prefer the
Yubikey AES mode over the :ref:yubico Cloud mode.

-… figure:: images/enroll_yubikey.png

  • :width: 500
    +There are three possible ways to enroll a Yubikey token.

  • Enroll a Yubikey AES mode token

-You can use this dialog to enroll a Yubikey AES mode token, if you have
-initialized the yubikey with the external ykpersonalize tool.

-… note:: However, we recommend that you use the privacyidea command line
+… note:: We recommend that you use the privacyidea command line
client, to initialize the Yubikeys. You can use the mass enrollment, which
eases the process of initializing a whole bunch of tokens.

@@ -30,4 +25,89 @@ Run the command like this::
privacyidea -U https://your.privacyidea.server -a admin token
yubikey_mass_enroll --yubimode YUBICO

+This command initializes the token and stores the AES secret and prefix
+in privacyidea, so the toen is immediatly useful. You can choose the slot
+with --yubislot For further help call
+privcyidea yubikey_mass_enroll with the --help option.
+
+The second way to enroll a yubikey token is also using yubikey_mass_enroll,
+but with the option --filename to write to token configuration into the
+specified file. The resulting file can then be imported into privacyidea:
+Select Tokens -> Import Tokens, Select “OATH CSV” and the file you just created.
+
+Third and last you can use this dialog to enroll a Yubikey AES mode token, if you have
+initialized the yubikey with the external ykpersonalize tool.
+
+… figure:: images/enroll_yubikey.png

  • :width: 500
  • Enroll a Yubikey AES mode token

+Remarks about using Yubikey token
+…
+
+You can use Yubikey tokens for two more or less distinct applications. The first
+is using privacyideas PAM module. In this case privacyidea handles the policies
+for user access and password validation. This works fine, when you only use
+privacyidea for token validation.
+
+The second mode is using the standard PAM module for yubikeys from Yubico
+pam_yubico to handle the token validation. The upside ist that you can
+use the PAM module included with you distribution, but there are downsides as
+well.
+
+* You can’t set a token PIN in privacyidea, because pam_yubico tries to

  • use the token PIN entered by the user as a system password (which is likely
  • to fail).

+* Setting the policy which tokens are valid for what users is done either in

  • ~/.yubico/authorized_keys or in the file given by the authfile option
  • in the PAM configuration.

+You can work around the restrictions by using a clever combination
+of tokentype yubikey and yubico as follows:
+
+* enroll a yubikey token with yubikey_mass_enroll --mode YUBICO.
+
+* do not set a token password.
+
+* do not assign the token to a user.
+
+* please make a note yubikey.prefix (12 characters starting with vv.
+
+Now the token can be used with pam_yubico, but will not allow any
+user access in privacyidea. If you want to use the token with
+pam_yubico see the manual page for details. You’ll want something like the
+following in your PAM config:
+

  • auth required pam_yubico.so id= key= \
  •    urllist=https://<privacyidea-server>/ttype/yubikey \

  •    authfile=/etc/yubikeys/authorized_yubikeys

+The file /etc/yubikeys/authorized_yubikeys contains a line
+for each user with the username and the allowed tokens delimited
+by “:”, for example:
+

  • :::

+… doc/configuration/tokenconfig, add yubikey.rst to describe
+how to configure Client ID/apiid and API key
+
+Now create a second token representing the Yubikey, but this time
+use the Yubico Cloud mode. Go to Tokens -> Enroll Token and select
+Yubico Cloud mode. Enter the 12 characters prefix you noted above
+and assign this token to a user and possibly set a token PIN. It would
+be nice to have the the serial number of the UBCM token correspond
+to the UBAM token, but this is right now not possible with the WebUI.
+
+Anyway in the WebUI, test the UBAM token without a Token PIN, test the UBCM token
+with the stored Token PIN, and check the token info afterwards.
+Check the yubikey token via /ttype/yubikey, for example with:
+
+ykclient --debug --url https:///ttype/yubikey --apikey “” “apiid”
+
+There should be successful authentications (count_auth_success),
+but no failures.
+

–
The only problem with troubleshooting is that the trouble shoots back.