Seed portal: Difference between revisions
No edit summary |
No edit summary |
||
| (11 intermediate revisions by one other user not shown) | |||
| Line 3: | Line 3: | ||
==Seed Portal and Token Troubleshooting Guide== | ==Seed Portal and Token Troubleshooting Guide== | ||
Guide Version: 1.0 | Guide Version: 1.0 | ||
==Introduction== | ==Introduction== | ||
The UniOTP Seed portal located here: https://esecutech.com/seed_portal/index.php is used to download, convert and troubleshoot OTP secret key files and tokens. | |||
English and Chinese language option in the top left. | |||
[[File:seedportal.png|400px|thumb|center|UniOTP seed portal, "Choose File" operation does not upload the secret key files anywhere, it only loads them onto the browser of the local machine.]] | |||
The features are: | The features are: | ||
*[[#Download_tokens| Download tokens]] | *[[#Download_tokens| Download tokens]] | ||
*[[#Load_tokens| Load tokens]] | |||
*[[#Convert_tokens| Convert seedfile format]] | *[[#Convert_tokens| Convert seedfile format]] | ||
*[[#Synchronize_tokens| Synchronize seed file to token]] | *[[#Synchronize_tokens| Synchronize seed file to token]] | ||
*[[#Search_tokens| Search for lost serial number of a token]] | *[[#Search_tokens| Search for lost serial number of a token]] | ||
*[[#troubleshoot_tokens| Troubleshooting OTPs]] | |||
<div id="Download_tokens"> | <div id="Download_tokens"> | ||
== Download tokens from SecuTech == | == Download tokens from SecuTech == | ||
When a new token has been purchased from SecuTech, a link is provided, eg. https://esecutech.com/seed_portal/index.php?1234 | |||
[[File:secure_access.png|400px|thumb|center|Purchaser email check]] | |||
When this page is visited, it will request the purchaser's email address to confirm that the link user is the purchaser. This link will expire after 7 days or after downloading the tokens, the link can be force expired. IP addresses that repeatedly attempt to visit possible links will be blacklisted. Please email sales (at) esecutech.com for assistance or to re-enable the link if more than 7 days is needed. | |||
</div> | |||
<div id="Load_tokens"> | |||
== Load tokens from file == | |||
A uinf secret key file can be loaded into the UniOTP seed portal for testing and conversion purposes. See [[Virtual_OTP_token | virtual OTP token]] for creating a uinf file for testing purposes. | |||
In the "Upload tokens" tab, please use the "Choose Files" button to upload .uinf secret key files. | |||
XML and encrypted file support is planned for the future. | |||
</div> | </div> | ||
<div id="Convert_tokens"> | <div id="Convert_tokens"> | ||
== Convert seed file for different platforms == | == Convert seed file for different platforms == | ||
[[File:seedportal_Download.png|400px|thumb|center|Generate zip file with chosen formats]] | |||
The Seed portal page provides 4 file types for different platforms: | The Seed portal page provides 4 file types for different platforms: | ||
<div class="mw-collapsible mw-collapsed"> | <div class="mw-collapsible mw-collapsed"> | ||
CSV in base 16/Hex: commonly used by custom solutions | CSV in base 16/Hex: commonly used by custom solutions | ||
| Line 47: | Line 44: | ||
</div> | </div> | ||
</div> | </div> | ||
<div class="mw-collapsible mw-collapsed"> | <div class="mw-collapsible mw-collapsed"> | ||
CSV in base 32: Google authenticator | CSV in base 32: Google authenticator | ||
| Line 56: | Line 52: | ||
</div> | </div> | ||
</div> | </div> | ||
<div class="mw-collapsible mw-collapsed"> | <div class="mw-collapsible mw-collapsed"> | ||
XML in base 64: most commonly supported seed file format, eg. RCDev http://www.rcdevs.com/products/openotp/ | XML in base 64: most commonly supported seed file format, eg. RCDev http://www.rcdevs.com/products/openotp/ | ||
| Line 65: | Line 60: | ||
</div> | </div> | ||
</div> | </div> | ||
<div class="mw-collapsible mw-collapsed"> | <div class="mw-collapsible mw-collapsed"> | ||
UINF: SecuTech's proprietary seed format. | UINF: SecuTech's proprietary seed format. | ||
<div class="mw-collapsible-content"> | <div class="mw-collapsible-content"> | ||
*Encrypted export is not supported by the Seed portal yet. | *Encrypted export is not supported by the Seed portal yet. | ||
*Raw uinf file: Exports the secret key file in uinf format. Previously used by SecuTech's legacy management system, please retain this file for future use for token trouble shooting. | *Raw uinf file: Exports the secret key file in uinf format. Previously used by SecuTech's legacy management system, please retain this file for future use for token trouble shooting using the seed portal. | ||
</div> | </div> | ||
</div> | </div> | ||
</div> | </div> | ||
<div id="Synchronize_tokens"> | <div id="Synchronize_tokens"> | ||
== Test and Synchronize a token == | == Test and Synchronize a token == | ||
To test if a token is out of synch due to repeatedly pressing the button on the token or a time lag from the onboard clock, please use this feature. | To test if a token is out of synch due to repeatedly pressing the button on the token or a time lag from the onboard clock, please use this feature. | ||
[[File:seedportal_virtualtoken.png|400px|thumb|center|Token troubleshooting]] | |||
Please select a token from the list, it will be highlighted in a deep red and the serial name will appear next to: "Selected token:", the current OTP that the computer expects the OTP to be displaying based on the seed file is generated. | |||
To synchronize a token, input atleast 1 OTP. Note that whilst it is possible to input 1 OTP for this operation, a single OTP is not recommended to be used over 50 OTP's. When synchronizing over large ranges, please use 2 OTP's. Default synch range is 3000, please set this accordingly and press "Synchronize OTP". | |||
If successful, the seed for the synchronized token will be set to the current values found. | |||
</div> | </div> | ||
<div id="Search_tokens"> | <div id="Search_tokens"> | ||
== Search for a lost serial number == | == Search for a lost serial number == | ||
In the event that a token's serial number is lost, for example the sticker is worn out and the token itself has been returned, it can be identified. | In the event that a token's serial number is lost, for example the sticker is worn out and the token itself has been returned, it can be identified. | ||
| Line 95: | Line 88: | ||
As a rule of thumb, the "search range" should be approximately 3 * number of days the token has been in use. It would be unusual for users to have more uses then this. | As a rule of thumb, the "search range" should be approximately 3 * number of days the token has been in use. It would be unusual for users to have more uses then this. | ||
If thousands of tokens are used, multiple instances of the search can be run by splitting the secret key files using "Download tokens" tab, "Custom grouping". | If thousands of tokens are used, multiple instances of the search can be run by splitting the secret key files using "Download tokens" tab, "Custom grouping". | ||
| Line 101: | Line 93: | ||
Chrome pauses javascript operations on pages that are not open, when attempting to run multiple instances, make sure that the browser tabs the seed portal instances are in, have been dragged next to each other and are visible. | Chrome pauses javascript operations on pages that are not open, when attempting to run multiple instances, make sure that the browser tabs the seed portal instances are in, have been dragged next to each other and are visible. | ||
</div> | |||
<div id="troubleshoot_tokens"> | |||
== General troubleshooting for OTP servers and tokens == | |||
When setting up (or developing) OTP servers/authenticators and tokens, a common issue is with timezone conversions. | |||
On the Token test and synchronize tab is the current Unix time, timestamp, and manual counter incrementor/decrementor. | |||
The Unix time and "Check timestamp on external site" is useful for determining if the computer time is correct. A difference of more then a few seconds can cause issues with TOTP tokens. | |||
The manual counter feature is useful for anyone creating their own authenticator and wishes to quickly test OTP's of a token. | |||
It is possible to create your own UINF file for testing purposes, please navigate [[Virtual_OTP_token|here]] for more details. | |||
</div> | </div> | ||
Latest revision as of 15:38, 12 December 2019
Seed Portal and Token Troubleshooting Guide
Guide Version: 1.0
Introduction
The UniOTP Seed portal located here: https://esecutech.com/seed_portal/index.php is used to download, convert and troubleshoot OTP secret key files and tokens.
English and Chinese language option in the top left.
The features are:
- Download tokens
- Load tokens
- Convert seedfile format
- Synchronize seed file to token
- Search for lost serial number of a token
- Troubleshooting OTPs
Download tokens from SecuTech
When a new token has been purchased from SecuTech, a link is provided, eg. https://esecutech.com/seed_portal/index.php?1234
When this page is visited, it will request the purchaser's email address to confirm that the link user is the purchaser. This link will expire after 7 days or after downloading the tokens, the link can be force expired. IP addresses that repeatedly attempt to visit possible links will be blacklisted. Please email sales (at) esecutech.com for assistance or to re-enable the link if more than 7 days is needed.
Load tokens from file
A uinf secret key file can be loaded into the UniOTP seed portal for testing and conversion purposes. See virtual OTP token for creating a uinf file for testing purposes.
In the "Upload tokens" tab, please use the "Choose Files" button to upload .uinf secret key files.
XML and encrypted file support is planned for the future.
Convert seed file for different platforms
The Seed portal page provides 4 file types for different platforms:
CSV in base 16/Hex: commonly used by custom solutions
- DUO format CSV: This format is a secret key container type used by DUO security: https://duo.com/
"Token serial name" , "secret key (in hex)", "counter"
- Generic format CSV: This format is a nice format for viewing with Excel and can be used by a custom solution easily
First line is header which provides format: "serial", "secret key (in hex)", "counter", "type (HOTP/TOTP/OCRA)", "timestamp (time last synchronized)", "digits", "authwnd (authentication window)", "timestep".
Please note that the authentication window and timestep may not be needed, for example most authentication servers use a global default, and is not token specific. Timestep is provided as 60 even for HOTP tokens, as some servers have different behaviours to missing values, despite not been used.
CSV in base 32: Google authenticator
- Generic format CSV: This format is a nice format for viewing with Excel and can be used by a custom solution easily
First line is header which provides format: "serial", "secret key (in base32)", "counter", "type (HOTP/TOTP/OCRA)", "timestamp (time last synchronized)", "digits", "authwnd (authentication window)", "timestep".
Please note that the authentication window and timestep may not be needed, for example most authentication servers use a global default, and is not token specific. Timestep is provided as 60 even for HOTP tokens, as some servers have different behaviours to missing values, despite not been used.
XML in base 64: most commonly supported seed file format, eg. RCDev http://www.rcdevs.com/products/openotp/
- Encrypted export is not supported by the Seed portal yet.
- Raw XML: XML formatted secret key file that conforms to: https://tools.ietf.org/html/rfc6030
This format is supported by most OTP authentication servers.
UINF: SecuTech's proprietary seed format.
- Encrypted export is not supported by the Seed portal yet.
- Raw uinf file: Exports the secret key file in uinf format. Previously used by SecuTech's legacy management system, please retain this file for future use for token trouble shooting using the seed portal.
Test and Synchronize a token
To test if a token is out of synch due to repeatedly pressing the button on the token or a time lag from the onboard clock, please use this feature.
Please select a token from the list, it will be highlighted in a deep red and the serial name will appear next to: "Selected token:", the current OTP that the computer expects the OTP to be displaying based on the seed file is generated.
To synchronize a token, input atleast 1 OTP. Note that whilst it is possible to input 1 OTP for this operation, a single OTP is not recommended to be used over 50 OTP's. When synchronizing over large ranges, please use 2 OTP's. Default synch range is 3000, please set this accordingly and press "Synchronize OTP".
If successful, the seed for the synchronized token will be set to the current values found.
Search for a lost serial number
In the event that a token's serial number is lost, for example the sticker is worn out and the token itself has been returned, it can be identified.
This process is identical to a synchronization process, however the tool will search through the defined range to find the matching OTP sequences on all seeds loaded.
Open the original uinf file (note that multiple uinf secret key files can be loaded into the tool), input 2 OTP's from the device and press search. If the token has been in use for some time and it is HOTP based, the uinf files may be out of synch to the token.
As a rule of thumb, the "search range" should be approximately 3 * number of days the token has been in use. It would be unusual for users to have more uses then this. If thousands of tokens are used, multiple instances of the search can be run by splitting the secret key files using "Download tokens" tab, "Custom grouping".
Note that this process is time consuming, a minimum of 450 sequences are tested every second (more with a fast computer). For 1000 tokens with a search range of 1000 (roughly 1 year of HOTP token usage), it can take close to 1 hour to complete. In this event we recommend splitting the file into 4 parts and opening 4 different instances of the seed portal to quarter the time taken.
Chrome pauses javascript operations on pages that are not open, when attempting to run multiple instances, make sure that the browser tabs the seed portal instances are in, have been dragged next to each other and are visible.
General troubleshooting for OTP servers and tokens
When setting up (or developing) OTP servers/authenticators and tokens, a common issue is with timezone conversions.
On the Token test and synchronize tab is the current Unix time, timestamp, and manual counter incrementor/decrementor.
The Unix time and "Check timestamp on external site" is useful for determining if the computer time is correct. A difference of more then a few seconds can cause issues with TOTP tokens.
The manual counter feature is useful for anyone creating their own authenticator and wishes to quickly test OTP's of a token.
It is possible to create your own UINF file for testing purposes, please navigate here for more details.
