Differences

This shows you the differences between two versions of the page.

--- userdoc:gitolite_2fa [2014-06-12 18:54]
korgadmin [Yubikeys]
+++ userdoc:gitolite_2fa [2020-05-08 14:01] (current)
mricon
@@ Line 1: / Line 1: @@
+~~REDIRECT>https://korg.docs.kernel.org/gitolite/2fa.html~~
 ====== 2-factor authentication with gitolite.kernel.org ======
-**Notice: opt-in beta**
+:!: The preferred mechanism for 2-factor authentication is via an SSH key stored on a smartcard device. If you have an account on kernel.org, you qualify for a free [[nitrokey]], so we strongly recommend that instead of setting up TOTP/HOTP you switch to using the Nitrokey for your ssh access instead.
+===== HOTP/TOTP ip-based push validation =====
+**Notice: opt-in**
-We are rolling out 2-factor authentication for access to gitolite.kernel.org. At this point, this feature is still in testing stage and will probably always remain opt-in instead of being required across the board.
+^Command^Summary^
+|**enroll** //[mode]//|Enroll with 2-factor authentication (mode=totp or yubikey)|
+|**val** //[token]//|Validate your current IP address for 24 hours|
+|**val-session** //[token]//|Validate your current ssh ControlMaster session|
+|**val-for-days** //[days]// //[token]//|Validate your current IP address for arbitrary number of days (max=30)|
+|**val-subnet** //[/cidr]// //[token]//|Validate a larger subnet for 8 hours|
+|**list-val** //[all]//|List current validations ("all" includes expired)|
+|**inval** //[ip-address]//|Invalidate specific IP address (can be "myip", "all" or "all purge")|
+|**isval**|Check if your current IP is validated|
+|**unenroll** //[token]//|Unenroll from 2-factor authentication|
 ===== Core concepts =====
@@ Line 9: / Line 24: @@
 Once 2-factor authentication is enabled for a git repository, any write operation from an IP address that hasn't been 2-factor validated will be rejected with a message like the following:
-  remote: User not enrolled with 2-factor authentication.
+<code>
-  remote: FATAL: W VREF/2fa: testing mricon DENIED by VREF/2fa
+remote: User not enrolled with 2-factor authentication.
-  remote: 2-factor verification failed
+remote: FATAL: W VREF/2fa: testing mricon DENIED by VREF/2fa
-  remote:
+remote: 2-factor verification failed
-  remote: You will need to enroll with 2-factor authentication
+remote:
-  remote: before you can push to this repository.
+remote: You will need to enroll with 2-factor authentication
-  remote:
+remote: before you can push to this repository.
-  remote: If you need more help, please see the following link:
+remote:
-  remote:     https://korg.wiki.kernel.org/index.php?title=Userdoc:gitolite_2fa
+remote: If you need more help, please see the following link:
-  remote:
+remote:     https://korg.wiki.kernel.org/index.php?title=Userdoc:gitolite_2fa
-  remote: error: hook declined to update refs/heads/master
+remote:
+remote: error: hook declined to update refs/heads/master
+</code>
 To allow the push to succeed, you will need to first validate the IP address with your 2-factor token, which will allow all pushes from that IP address to succeed -- until the validation expires. The default expiration time is 24 hours, but you may set it to be as long as 30 days.
@@ Line 45: / Line 62: @@
 The only HOTP devices currently tested and supported are yubikeys. Any of the currently listed products should support HOTP authentication:
-  * [[http://www.yubico.com/products/yubikey-hardware/yubikey/|Standard]] (cheapest)
+  * [[https://www.yubico.com/products/yubikey-hardware/yubikey4/|Yubikey 4]] either standard or Nano form-factors (also supports OpenPGP functionality)
-  * [[http://www.yubico.com/products/yubikey-hardware/yubikey-nano/|Nano]] (smallest)
-  * [[http://www.yubico.com/products/yubikey-hardware/yubikey-neo/|NEO]] (also works as an OpenPGP card)
-We recommend the NEO, as you can also configure it as an [[https://github.com/herlo/ssh-gpg-smartcard-config/blob/master/YubiKey_NEO.rst|OpenPGP card]], but laptop users may find that using the Nano is more comfortable.
+Laptop users may find that using the Nano form factor is more comfortable.
 ===== Provisioning your 2-factor token =====
@@ Line 61: / Line 76: @@
 This command outputs the following:
-  totp enrollment mode selected
+<code>
-  New token generated for user mricon
+totp enrollment mode selected
+New token generated for user mricon
+Please make sure "qrencode" is installed.
+Run the following commands to display your QR code:
+    unset HISTFILE
+    qrencode -tANSI -m1 -o- "otpauth://totp/mricon@gitolite.kernel.org?secret=ACHQKMJFHIXJDNRY"
-  Please make sure "qrencode" is installed.
+If that does not work or if you do not have access to
-  Run the following commands to display your QR code:
+qrencode or a similar QR encoding tool, then you may
-      unset HISTFILE
+open an INCOGNITO/PRIVATE MODE window in your browser
-      qrencode -tANSI -m1 -o- "otpauth://totp/mricon@gitolite.kernel.org?secret=ACHQKMJFHIXJDNRY"
+and paste the following URL:
+https://www.google.com/chart?chs=200x200&chld=M|0&cht=qr&chl=otpauth%3A%2F%2Ftotp%2Fmricon%40gitolite.kernel.org%3Fsecret%3DACHQKMJFHIXJDNRY
+Scan the resulting QR code with your TOTP app, such as
+FreeOTP (recommended), Google Authenticator, Authy, or others.
+Please write down/print the following 8-digit scratch tokens.
+If you lose your device or temporarily have no access to it, you
+will be able to use these tokens for one-time bypass.
+Scratch tokens:
+19489805
+36196876
+06341363
+70324458
+39448548
-  If that does not work or if you do not have access to
+Now run the following command to verify that all went well
-  qrencode or a similar QR encoding tool, then you may
+    ssh git@gitolite.kernel.org 2fa val [token]
-  open an INCOGNITO/PRIVATE MODE window in your browser
-  and paste the following URL:
-  https://www.google.com/chart?chs=200x200&chld=M|0&cht=qr&chl=otpauth%3A%2F%2Ftotp%2Fmricon%40gitolite.kernel.org%3Fsecret%3DACHQKMJFHIXJDNRY
-  Scan the resulting QR code with your TOTP app, such as
-  FreeOTP (recommended), Google Authenticator, Authy, or others.
-  Please write down/print the following 8-digit scratch tokens.
-  If you lose your device or temporarily have no access to it, you
-  will be able to use these tokens for one-time bypass.
-  Scratch tokens:
-  19489805
-  36196876
-  06341363
-  70324458
-  39448548
-  Now run the following command to verify that all went well
-      ssh git@gitolite.kernel.org 2fa val [token]
-  If you need more help, please see the following link:
+If you need more help, please see the following link:
-      https://korg.wiki.kernel.org/index.php?title=Userdoc:gitolite_2fa
+    https://korg.wiki.kernel.org/userdoc:gitolite_2fa
+</code>
 **Please remember to "unset HISTFILE" or your secret will be stored in your ~/.bash_history.**
@@ Line 100: / Line 117: @@
 ==== Yubikeys ====
-To initialize a yubikey, run the following command instead:
+To initialize a yubikey, run the following command instead. Note, that you will need [[https://developers.yubico.com/yubikey-personalization/|ykpersonalize]] to configure your key.
-  ssh git@example.com 2fa enroll yubikey
+  ssh git@gitolite.kernel.org 2fa enroll yubikey
 The output of the yubikey command is slightly different:
-  yubikey enrollment mode selected
+<code>
-  New token generated for user mricon
+yubikey enrollment mode selected
+New token generated for user mricon
+Please make sure "ykpersonalize" has been installed.
+Insert your yubikey and, as root, run the following command
+to provision the secret into slot 1 (use -2 for slot 2):
+    unset HISTFILE
+    ykpersonalize -1 -ooath-hotp -oappend-cr -a7fd554b1e4a711155d20e9f9615b0451152db3bb
-  Please make sure "ykpersonalize" has been installed.
+Please write down/print the following 8-digit scratch tokens.
-  Insert your yubikey and, as root, run the following command
+If you lose your device or temporarily have no access to it, you
-  to provision the secret into slot 1 (use -2 for slot 2):
+will be able to use these tokens for one-time bypass.
-      unset HISTFILE
-      ykpersonalize -1 -ooath-hotp -oappend-cr -a7fd554b1e4a711155d20e9f9615b0451152db3bb
-  Please write down/print the following 8-digit scratch tokens.
+Scratch tokens:
-  If you lose your device or temporarily have no access to it, you
+88989251
-  will be able to use these tokens for one-time bypass.
+08286736
+73163062
+90775064
+59235228
-  Scratch tokens:
+Now run the following command to verify that all went well
-  88989251
+    ssh git@gitolite.kernel.org 2fa val [yubkey button press]
-  08286736
-  73163062
+If you need more help, please see the following link:
-  90775064
+    https://korg.wiki.kernel.org/userdoc:gitolite_2fa
-  59235228
+</code>
-  Now run the following command to verify that all went well
-      ssh git@gitolite.kernel.org 2fa val [yubkey button press]
-  If you need more help, please see the following link:
-      https://korg.wiki.kernel.org/userdoc:gitolite_2fa
 **It is important to use "unset HISTFILE" to make sure the secret isn't saved in your ~/.bash_history.** Additionally, you may also omit the -a flag and "''ykpersonalize''" should prompt you for the secret, in which case paste the string that follows the "-a" (but not "-a" itself).
@@ Line 148: / Line 166: @@
 You should get the following back:
-  Counting objects: 7, done.
+<code>
-  Delta compression using up to 4 threads.
+Counting objects: 7, done.
-  Compressing objects: 100% (2/2), done.
+Delta compression using up to 4 threads.
-  Writing objects: 100% (3/3), 308 bytes | 0 bytes/s, done.
+Compressing objects: 100% (2/2), done.
-  Total 3 (delta 1), reused 0 (delta 0)
+Writing objects: 100% (3/3), 308 bytes | 0 bytes/s, done.
-  remote: IP address "x.x.x.x" has not been validated.
+Total 3 (delta 1), reused 0 (delta 0)
-  remote: FATAL: W VREF/2fa: testing mricon DENIED by VREF/2fa
+remote: IP address "x.x.x.x" has not been validated.
-  remote: 2-factor verification failed
+remote: FATAL: W VREF/2fa: testing mricon DENIED by VREF/2fa
-  remote:
+remote: 2-factor verification failed
-  remote: Please get your 2-factor authentication token and run:
+remote:
-  remote:     ssh git@gitolite.kernel.org 2fa val [token]
+remote: Please get your 2-factor authentication token and run:
-  remote:
+remote:     ssh git@gitolite.kernel.org 2fa val [token]
-  remote: If you need more help, please see the following link:
+remote:
-  remote:     https://korg.wiki.kernel.org/index.php/Userdoc:gitolite_2fa
+remote: If you need more help, please see the following link:
-  remote:
+remote:     https://korg.wiki.kernel.org/index.php/Userdoc:gitolite_2fa
-  remote: error: hook declined to update refs/heads/mricon
+remote:
-  To git@gitolite.kernel.org:testing
+remote: error: hook declined to update refs/heads/mricon
-   ! [remote rejected] mricon -> mricon (hook declined)
+To git@gitolite.kernel.org:testing
-  error: failed to push some refs to 'git@gitolite.kernel.org:testing'
+ ! [remote rejected] mricon -> mricon (hook declined)
+error: failed to push some refs to 'git@gitolite.kernel.org:testing'
+</code>
 As instructed, run the following:
-  $ ssh git@gitolite.kernel.org 2fa val [token]
+<code>
-  Valid TOTP token within window size used
+$ ssh git@gitolite.kernel.org 2fa val [token]
-  Adding IP address x.x.x.x until Wed May 28 20:29:31 2014 UTC
+Valid TOTP token within window size used
-  GeoIP information for x.x.x.x: Saint-laurent, Quebec, CA
+Adding IP address x.x.x.x until Wed May 28 20:29:31 2014 UTC
+GeoIP information for x.x.x.x: Saint-laurent, Quebec, CA
+</code>
 If you now try the push again, it will succeed:
-  $ git push origin mricon
+<code>
-  Counting objects: 7, done.
+$ git push origin mricon
-  Delta compression using up to 4 threads.
+Counting objects: 7, done.
-  Compressing objects: 100% (2/2), done.
+Delta compression using up to 4 threads.
-  Writing objects: 100% (3/3), 308 bytes | 0 bytes/s, done.
+Compressing objects: 100% (2/2), done.
-  Total 3 (delta 1), reused 0 (delta 0)
+Writing objects: 100% (3/3), 308 bytes | 0 bytes/s, done.
-  remote: Reading /var/lib/gitolite3/repositories/manifest.js.gz
+Total 3 (delta 1), reused 0 (delta 0)
-  remote: Updating /testing.git in the manifest
+remote: Reading /var/lib/gitolite3/repositories/manifest.js.gz
-  remote: Writing new /var/lib/gitolite3/repositories/manifest.js.gz
+remote: Updating /testing.git in the manifest
-  To git@gitolite.kernel.org:testing
+remote: Writing new /var/lib/gitolite3/repositories/manifest.js.gz
-ff91..87b27aa  mricon -> mricon
+To git@gitolite.kernel.org:testing
+ff91..87b27aa  mricon -> mricon
+</code>
 ===== Listing validations and invalidating IPs =====
 To list all allowed validations, run:
-<pre>
+<code>
 $ ssh git@gitolite.kernel.org 2fa list-val
 {
@@ Line 206: / Line 231: @@
 }
 Listed non-expired entries only. Run "list-val all" to list all.
-</pre>
+</code>
+Note: this command only works from a whitelisted IP address.
 To invalidate an IP, use the "inval" command, e.g.:
-<pre>
+  $ ssh git@gitolite.kernel.org 2fa inval 24.x.x.x
-$ ssh git@gitolite.kernel.org 2fa inval 24.x.x.x
+  Force-expired 24.x.x.x
-Force-expired 24.x.x.x
-</pre>
-Instead of the IP address, you may also use "myip" to invalidate the current IP you're connecting from, or "all" to force-expire all active IP validations.
+Instead of the IP address, you may also use "myip" to invalidate the current IP you're connecting from, or "all" to force-expire all active IP validations. If you run "inval all purge", this will additionally purge all your current and expired entries -- handy if you would like to leave no trace of your travel history.
-== Switching devices and Unenrolling ==
+===== SSH session validation =====
+If you are travelling and happen to be behind a single NAT exit point with a lot of other people, it is preferable to validate only your SSH session instead of the whole public exit point. This will also help if the exit point is not static but changes between tcp sessions (as is sometimes common in very large NAT-ed networks).
+Before you can use this feature, you will need to make sure you enabled **ssh multiplexing** in the client, by adding the following entries to your gitolite.kernel.org section:
+  ControlPath ~/.ssh/cm-%r@%h:%p
+  ControlMaster auto
+  ControlPersist 30m
+You can use longer than 30m if necessary -- the session will be validated for up to 8 hours. Please see [[userdoc:ssh_access]] for more ssh setup details.
+===== Using in scripts =====
+You can check if your current IP is valid from inside a script, by using the **isval** check, e.g. like so:
+<code bash>
+echo -n "Checking if 2fa validation is current: "
+if ! ssh git@gitolite.kernel.org 2fa isval; then
+    echo "Error: kernel.org 2fa validation expired"
+    exit 1
+fi
+</code>
+Note that there's an inherent race condition here: your validation may expire between this check and the actual git push.
+===== Switching devices and Unenrolling =====
 Usually you would need to unenroll only when switching devices. If you still have access to your current device or to the scratch-tokens, you can use them to unprovision your current device by using the "unenroll" command:
-<pre>
+<code>
 $ ssh git@gitolite.kernel.org 2fa unenroll [token]
 Valid TOTP token used
@@ Line 228: / Line 278: @@
 Force-expired 172.0.0.14.
 You have been successfully unenrolled.
-</pre>
+</code>
 You can then use the "enroll" command again in order to provision a new device.
-If you do NOT have access to your previous 2-factor device, send a signed email to [mailto:helpdesk@kernel.org helpdesk@kernel.org] and we'll work to re-provision you a new token (once a successfully thorough verification procedure is established and followed).
+If you do NOT have access to your previous 2-factor device, send a signed email to [[userdoc:support]] and we'll work to re-provision you a new token (once a successfully thorough verification procedure is established and followed).
-== Requesting 2-factor protection for your repository ==
-During this beta-testing period, send mail to [mailto:helpdesk@kernel.org helpdesk@kernel.org] to request that your repository is added to the 2fa list.
+===== Requesting 2-factor protection for your repository =====
+During this opt-in period, send mail to [[userdoc:support]] to request that your repository is added to the 2fa list.

Kernel.org metawiki

User Tools

Site Tools

Differences

Page Tools