This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
userdoc:gitolite_2fa [2014-08-26 15:09] mricon |
userdoc:gitolite_2fa [2017-05-23 20:59] mricon |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== 2-factor authentication with gitolite.kernel.org ====== | ====== 2-factor authentication with gitolite.kernel.org ====== | ||
- | **Notice: opt-in beta** | + | **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. | 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. | ||
Line 8: | Line 8: | ||
|**enroll** //[mode]//|Enroll with 2-factor authentication (mode=totp or yubikey)| | |**enroll** //[mode]//|Enroll with 2-factor authentication (mode=totp or yubikey)| | ||
|**val** //[token]//|Validate your current IP address for 24 hours| | |**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-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)| | |**list-val** //[all]//|List current validations ("all" includes expired)| | ||
- | |**inval** //[ip-address]//|Invalidate specific IP address (can be "myip" or "all")| | + | |**inval** //[ip-address]//|Invalidate specific IP address (can be "myip", "all" or "all purge")| |
|**isval**|Check if your current IP is validated| | |**isval**|Check if your current IP is validated| | ||
|**unenroll** //[token]//|Unenroll from 2-factor authentication| | |**unenroll** //[token]//|Unenroll from 2-factor authentication| | ||
Line 56: | Line 58: | ||
The only HOTP devices currently tested and supported are yubikeys. Any of the currently listed products should support HOTP authentication: | 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 ===== | ===== Provisioning your 2-factor token ===== | ||
Line 113: | Line 113: | ||
==== Yubikeys ==== | ==== 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: | The output of the yubikey command is slightly different: | ||
Line 229: | Line 228: | ||
Listed non-expired entries only. Run "list-val all" to list all. | Listed non-expired entries only. Run "list-val all" to list all. | ||
</code> | </code> | ||
+ | |||
+ | Note: this command only works from a whitelisted IP address. | ||
To invalidate an IP, use the "inval" command, e.g.: | To invalidate an IP, use the "inval" command, e.g.: | ||
Line 235: | Line 236: | ||
Force-expired 24.x.x.x | Force-expired 24.x.x.x | ||
- | 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. |
+ | |||
+ | ===== 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 ===== | ===== Switching devices and Unenrolling ===== | ||
Line 255: | Line 270: | ||
===== Requesting 2-factor protection for your repository ===== | ===== Requesting 2-factor protection for your repository ===== | ||
- | During this beta-testing period, send mail to [[userdoc:support]] to request that your repository is added to the 2fa list. | + | During this opt-in period, send mail to [[userdoc:support]] to request that your repository is added to the 2fa list. |