pam_cr_setup.8

   1 .\"Copyright (c) 2013 Eugene Crosser
   2 .\"
   3 .\"This software is provided 'as-is', without any express or implied
   4 .\"warranty. In no event will the authors be held liable for any damages
   5 .\"arising from the use of this software.
   6 .\"
   7 .\"Permission is granted to anyone to use this software for any purpose,
   8 .\"including commercial applications, and to alter it and redistribute it
   9 .\"freely, subject to the following restrictions:
  10 .\"
  11 .\"    1. The origin of this software must not be misrepresented; you must
  12 .\"    not claim that you wrote the original software. If you use this
  13 .\"    software in a product, an acknowledgment in the product documentation
  14 .\"    would be appreciated but is not required.
  15 .\"
  16 .\"    2. Altered source versions must be plainly marked as such, and must
  17 .\"    not be misrepresented as being the original software.
  18 .\"
  19 .\"    3. This notice may not be removed or altered from any source
  20 .\"    distribution.
  21 .\"
  22 .TH PAM_CR_SETUP 8 "18 Dec 2013" PAM_PCSC_CR PAM_PCSC_CR
  23 .SH NAME
  24 pam_cr_setup \- manipulate user auth file for pam_pcsc_cr
  25 .SH SYNOPSYS
  26 .B pam_cr_setup
  27 [options] [username]
  28 .SH DESCRIPTION
  29 .B pam_cr_setup
  30 creates and modifies the file with the shared secret that is used by
  31 .B pam_pcsc_cr
  32 PAM module for crypto-token based authentication. To initially create
  33 the file, you must provide the shared secret that is also installed in
  34 the token. Later on, the command may be used to update the payload
  35 which may be the keyring unlock key. If used in the latter mode, and
  36 if the crypto-token is present, specifying the shared secret is not
  37 necessary.
  38 .SH OPTIONS
  39 .B \-h
  40 \- show short description and exit.
  41 .PP
  42 .B \-o backend-option
  43 \- option specific to the crypto-token.
  44 The format is
  45 .B backend:key=value.
  46 At present, only Yubikey Neo
  47 crypto-token is supported, and the only option is
  48 .B ykneo:slot=[1|2].
  49 .PP
  50 .B \-f template
  51 \- template for the auth file path. It may contain one character
  52 .B '~'
  53 which, if in the first position, is replaced with the userid's
  54 home directory path, and if in any other position - with the userid
  55 itself.
  56 .PP
  57 .B \-a secret
  58 or
  59 .B \-A file-with-secret
  60 or
  61 .B \-A -
  62 \- 40-character hexadecimal representation of the shared secret.
  63 It must be provided when first creating the file, and when updating
  64 the payload in the absense of the crypto-token.
  65 .B \-A -
  66 means that the 40-character string is read from
  67 .B stdin.
  68 .PP
  69 .B \-n nonce
  70 \- initial nonce. Currently this must be a decimal representation of an
  71 integer. It is subsequently incremented by one on every successful
  72 authentication session.
  73 .PP
  74 .B \-l payload
  75 \- a string that will be injected into the PAM framework as
  76 .B AUTH_TOKEN
  77 upon successful authentication. It is useful to have the keyring
  78 unlock password there. The payload is encrypted in the file, and only
  79 exists in memory in decrypted form for a short period (unless leaked
  80 by other PAM modules).
  81 .PP
  82 .B \-p password
  83 \- login password that is used to create the challenge (not the one
  84 from
  85 .BR /etc/shadow ").
  86 If not specified, an empty string is used, which is the same as the
  87 .B pam_pcsc_cr
  88 module uses when invoked with
  89 .B noaskpass
  90 argument. With empty password, login process requires only the presence
  91 of the crypto-token, and does not involve any input from the user.
  92 .PP
  93 .B \-v
  94 \- output the userid and payload from the auth file. Note that displaying
  95 the payload on screen to be seen by passers by may not be a good idea.
  96 .PP
  97
  98 .SH COPYRIGHT
  99 2013 Eugene G. Crosser
 100 .br
 101 Released under zlib Open Source license.
 102 .SH SEE ALSO
 103 .BR pam "(3), "ykpersonalize "(1), "pam_pcsc_cr "(8)