antonioribeiro / recovery

Create recovery/backup codes for 2FA

Recovery Codes

Generate recovery/backup codes to provide a way for your users to recover from a lost two factor auth, or any problem with it.

Install

Via Composer

$ composer require pragmarx/recovery

Usage

Basic array usage

$this->recovery = new PragmaRX\Recovery();

$this->recovery->toArray();

Collection

If you are using Laravel or install a package like Collect, you can:

$this->recovery->toCollection();

You can also define a different collection function to be used:

$this->recovery->collectionFunction('alternateCollection');

$this->recovery->setCount(8)->toCollection();

Json result

$this->recovery->toJson();

Should give you

[  
   "C0r2Xp4o1v-oG3pteKXw3",
   "oLuSmVeJ7D-t4wnJVwkuC",
   "XdPXXJy3J6-Gl3d0EwWt7",
   "Bn8twjUJRt-Lv3KaAFwjR",
   "SrnMagyGRg-eC7WPyFQ17",
   "mRO4WPJpRN-hgfrUZqqZd",
   "xBZtyFOrJZ-Tbpg0pSvzf",
   "eiPFmwvJp0-oSqdNKclDH"
]

Changing the result values/sizes

$this->recovery
     ->setCount(8)     // Generate 8 codes
     ->setBlocks(5)    // Every code must have 7 blocks
     ->setChars(16)    // Each block must have 16 chars
     ->toArray();

Should give you

[  
   "0ldZb4vhamHEd8B3-Tmri54Lb0t52wefR-gbJaHTN44O9C1igf-HRdF185SXxDwcdRf",
   "sFyrtezhjbFhCube-MszCKzvdsNL7QEY1-IY5OtpsFqM5d7jA7-t2mjCViRMHcMDdNZ",
   "bjKMlcsPhNrpFpSN-IbJR2ebOeXCxXVVb-omZLu3Ki9ImIEqZh-1sK74zOADl86GGRs",
   "wpa23eFj8PJcPdMG-E8A4LCwmd8iF8jt4-bVi2ltUEv29zoPJJ-pSetq2GD6euvZ9RA",
   "EJ3SRDQlddr2e2hT-eF79n1lqndwhRM7G-HrjHEVyA9zHSLi8g-TrHzl5oaqPi1NgCT",
   "lL7p4zjFxhQLND24-MEV1lmmyEKObjhhT-ldRWbOEnJLjBHmuc-Iex10bYAZ3NBljo2",
   "uomVxkrjGYqOqmdm-AtI9MiqFEJjTlSRi-AUNEwwUfrJVP5iaH-uyrsFCrqzC3WcaAa"
]

Numeric or alpha?

$this->recovery
     ->numeric()       // Generate numeric only codes
     ->toArray();
     
$this->recovery
     ->alpha()        // Get back to default alpha generation
     ->toArray();

Upper, lower and mixed case

$this->recovery
     ->lowercase()    // All lower
     ->toArray();
     
$this->recovery
     ->uppercase()    // All upper
     ->toArray();
     
$this->recovery
     ->mixedcase()    // Get back to default mixed case
     ->toArray();

Block separator

Usually - is used as a block separator, but you can change it with:

$this->recovery->setBlockSeparator('|')->toJson();

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer update
$ vendor/bin/phpunit

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Antonio Carlos Ribeiro

License

The MIT License (MIT). Please see License File for more information.

recovery's Issues

How can I validate a recovery code?

To me is not clear the workflow of using recovery codes.

Must I generate recovery codes and save it in db, related to the user?

Then If user loose access, I must simply ask a recovery code and the if it's in db then re-show the original qr (or a different one to invalidate the previous one)?

PHP 8 Compatibility

Seems to work fine with PHP 8, possible to bump the version requirement in composer.json?

Thanks

How would this be automated in the worklow?

It looks very cool, but where would you store these backup codes for users to validate it too? Storing it in the database might become very large right?

How to Test one 2FA backup-code

how can I test this Test one 2FA backup-code is it auto accepted by 2fa or I need to create different method to test

Register or Logged in
User asks to enable 2FA
Show 2FA qr-code
Show 2FA backup codes
Test the 2FA qr-code
Test one 2FA backup-code
System enables 2FA

How to use this with Laravel?

Sorry, I'm using

https://github.com/antonioribeiro/google2fa-laravel

and i'm interested in using this package in laravel.

how ?

Generated code character patterns

Curiosity more than anything else.

Using:

$this->recovery
     ->lowercase()    // All lower case
     ->setCount(16)   // Generate 16 codes
     ->setBlocks(2)   // Every code must have 2 blocks
     ->setChars(5)    // Each block must have 5 chars
     ->toJson();

generates the following codes:

lzlql-waa3q     a7hlw-7ru14
lo6rj-ht6zn     6j7dj-3sxvq
gf4sl-iqhli     mb69u-5efip
vk7mq-fhwdt     nekcu-ftttj
njque-oj2mb     eurp9-d7hl4
wtuhj-incwq     pyegs-hlhhx
7ivx7-8nvpg     dxycg-culzj
2cuae-kajhq     kte5r-ha4vi

Is it possible to generate codes similar in pattern to GitHub's recovery codes (higher number of numeric characters)?

Example GitHub Recovery codes:

270a5-c024d     7fa60-52864
3930b-df559     9cd02-0199c
f4127-98309     1129d-671b7
60c30-564c7     a7806-bfe1b
17518-6474e     88e75-72444
c3d05-f37fc     f524c-16150
642f4-82a7d     4d687-4c5ce
433ad-fe188     4b4a1-78d26