From e38f0999a0eaf878ad619d0bf5c20bab6f51ebfc Mon Sep 17 00:00:00 2001 From: Eugene Fox Date: Wed, 18 Sep 2024 16:56:27 +0300 Subject: [PATCH] Removed old pages --- Algorithm.md | 15 ---- Code-generation-or-validation.md | 68 -------------- Configuration.md | 104 ---------------------- OTPCode.GetCode.md | 15 ---- OTPCode.OTPCode.md | 34 ------- OTPCode.md | 25 ------ OTPCodeUpdatedEventHandler.md | 15 ---- OTPConfiguration.GenerateConfiguration.md | 27 ------ OTPConfiguration.GetConfiguration.md | 94 ------------------- OTPConfiguration.GetFancySecret.md | 17 ---- OTPConfiguration.GetQrImage.md | 19 ---- OTPConfiguration.GetUri.md | 11 --- OTPConfiguration.md | 33 ------- OTPFactory-overview.md | 61 ------------- OTPFactory.OTPFactory.md | 20 ----- OTPFactory.md | 38 -------- OTPService.GenerateCode.md | 61 ------------- OTPService.ValidateCode.md | 93 ------------------- OTPService.ValidateHotp.md | 39 -------- OTPService.ValidateTotp.md | 36 -------- OTPService.md | 21 ----- OTPType.md | 14 --- SecretGenerator.GenerateSecret.md | 22 ----- SecretGenerator.md | 13 --- index.md | 51 ----------- 25 files changed, 946 deletions(-) delete mode 100644 Algorithm.md delete mode 100644 Code-generation-or-validation.md delete mode 100644 Configuration.md delete mode 100644 OTPCode.GetCode.md delete mode 100644 OTPCode.OTPCode.md delete mode 100644 OTPCode.md delete mode 100644 OTPCodeUpdatedEventHandler.md delete mode 100644 OTPConfiguration.GenerateConfiguration.md delete mode 100644 OTPConfiguration.GetConfiguration.md delete mode 100644 OTPConfiguration.GetFancySecret.md delete mode 100644 OTPConfiguration.GetQrImage.md delete mode 100644 OTPConfiguration.GetUri.md delete mode 100644 OTPConfiguration.md delete mode 100644 OTPFactory-overview.md delete mode 100644 OTPFactory.OTPFactory.md delete mode 100644 OTPFactory.md delete mode 100644 OTPService.GenerateCode.md delete mode 100644 OTPService.ValidateCode.md delete mode 100644 OTPService.ValidateHotp.md delete mode 100644 OTPService.ValidateTotp.md delete mode 100644 OTPService.md delete mode 100644 OTPType.md delete mode 100644 SecretGenerator.GenerateSecret.md delete mode 100644 SecretGenerator.md delete mode 100644 index.md diff --git a/Algorithm.md b/Algorithm.md deleted file mode 100644 index abb01cb..0000000 --- a/Algorithm.md +++ /dev/null @@ -1,15 +0,0 @@ -Namespace: `SimpleOTP.Enums` - -Assembly: `SimpleOTP.dll` - -Available OTP encryption algorithms. -```csharp -public enum Algorithm -``` - -## Fields -| Field | Value | Description | -| ------ | ----- | ---------------------------------------------------------------------------------------------- | -| SHA1 | 0 | HMAC-SHA1 hasing algorithm (default) [RFC 3174](https://datatracker.ietf.org/doc/html/rfc3174) | -| SHA256 | 1 | HMAC-SHA256 hasing algorithm [RFC 4634](https://datatracker.ietf.org/doc/html/rfc4634) | -| SHA512 | 2 | HMAC-SHA512 hasing algorithm [RFC 4634](https://datatracker.ietf.org/doc/html/rfc4634) | \ No newline at end of file diff --git a/Code-generation-or-validation.md b/Code-generation-or-validation.md deleted file mode 100644 index ce9174a..0000000 --- a/Code-generation-or-validation.md +++ /dev/null @@ -1,68 +0,0 @@ -Here we will look at how to generate an OTP on client side and validate it on server side - -## Code generation -### Time-based OTP -For TOTP it's quite simple: you load your OTP configuration from your storage (in this example it's `Xamarin.Essentials.Preferences`) and then generate a new OTP code with `OTPService` -```csharp -OTPConfiguration totpConfig = JsonConvert.DeserializeObject(Preferences.Get("myTotpConfig", "")); - -OTPCode code = OTPService.GenerateCode(ref totpConfig); -Debug.WriteLine(code); // OTPasswordModel { Code = 350386, Expiring = 23-May-21 06:08:30 PM } -``` - -### HMAC-based OTP -For HOTPs it's important to update your configuration after code generation because it's based on a counter which should be incremented each time you generate a password: -```csharp -OTPConfiguration hotpConfig = JsonConvert.DeserializeObject(Preferences.Get("myHotpConfig", "")); - -OTPCode code = OTPService.GenerateCode(ref hotpConfig); -Debug.WriteLine(code); // OTPasswordModel { Code = 350386, Expiring = null } // Since HOTP isn't time related, it doesn't have expiration time -Preferences.Set("myHotpConfig", JsonConvert.SerializeObject(hotpConfig)); // It's important to update configuration to prevent desynchronization with server -``` -It's also recommended to not let user generate HOTP in one action. Make sure you've notified user that generating code for no reason can cause a desynchronization with the server, thus inability to log in - -## Code validation -### Time-based OTP -Code validation is quite like what we do with code generation. In this example as storage location, we will use an `DatabaseContext` from ASP.NET since usually validation occurs on server side -```csharp -[HttpGet] -public IActionResult Get(int code, Guid id) -{ - OTPConfiguration totpConfig = db.Configs.Find(id); - if (OTPService.ValidateTotp(code, totpConfig, TimeSpan.FromSeconds(30))) - return Ok(); - else - return Forbidden(); -} -``` -`TimeSpan.FromSeconds(30)` here is tolerance time which defines a set of periods, thus OTP codes which are valid at that moment. This is used to handle time desynchronization between server and client. If `OTPConfiguration.Period` is equal to 30 seconds, this tolerance time suggests that at that moment there're 3 valid OTP codes: current one, previous one and next one: -``` - t - 30 t t + 30 - | | | -| (n - 1)-th period | n-th period | (n + 1)-th period | -``` - -Recommended tolerance time: 30 seconds - -### HMAC-based OTP -Similar to code generation, after code validation you need to update configuration in your storage. Note that HOTP counter increments only on successful validation -```csharp -[HttpGet] -public IActionResult Get(int code, Guid id) -{ - OTPConfiguration hotpConfig = db.Configs.Find(id); - if (OTPService.ValidateHotp(code, ref hotpConfig, 1, true)) // 1 - toleranceSpan; true - resyncCounter - { - db.Update(hotpConfig); - db.SaveChanges(); - return Ok(); - } - else - return Forbidden(); -} -``` -For HOTP configuration tolerance span is presented in number of preceding and subsequent counters which should be treated as valid. Last parameter is `resyncCounter` and determines if `OTPService.ValidateHotp` should update counter according to provided OTP code - -Recommended tolerance span: 1-2 - -It is also recommended to dismiss validated code to prevent from using it second time \ No newline at end of file diff --git a/Configuration.md b/Configuration.md deleted file mode 100644 index b81ee6f..0000000 --- a/Configuration.md +++ /dev/null @@ -1,104 +0,0 @@ -Since you probably have multiple users on your service or multiple services on your device, you need to handle configurations for all the cases you have - -For list of configuration properties please refer to [OTPConfiguration - API reference](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) -## Generate configuration -To generate new configuration for user, simply call `OTPConfiguration.GenerateConfiguration`. It will generate new secret key for the instance and apply recommended settings (see below) -```csharp -OTPConfiguration config = OTPConfiguration.GenerateConfiguration("My service name", "target_username@or_an_email.com"); -``` -Default configuration -- OTP algorithm: Time-based OTP -- Key length: 160 bit (20 characters) -- Hashing algorithm: HMAC-SHA-1 -- OTP length: 6 digits -- Period: 30 seconds - -To override some of settings in generated configurations, you can set them manually: -```csharp -OTPConfiguration config = OTPConfiguration.GenerateConfiguration("My service name", "target_username@or_an_email.com"); -config.Digits = 8; -config.Algorithm = Algorithm.SHA512; -config.Period = TimeSpan.FromSeconds(60); -// etc. -``` -## Load configuration -To load existing configuration, you can call `GetConfiguration(string, string, string)` to load configuration with default settings. If you do so, you need to store only information about these three values. -```csharp -OTPConfiguration config = OTPConfiguration.GenerateConfiguration("MYSECRETKEY", "My service name", "target_username@or_an_email.com"); -Console.WriteLine(config); -// OTPModel { Id = af2358b0-3f69-4dd7-9537-32c07d6663aa, Type = TOTP, IssuerLabel = My service name, AccountName = target_username@or_an_email.com, Secret = MYSECRETKEY, Issuer = My service name, Algorithm = SHA1, Digits = 6, Counter = 0, Period = 00:00:30 } -``` -Alternatively, you can load configuration from [OTP AUTH URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). In this way, you need to store only array of URIs: -```csharp -string sample_config_uri = "otpauth://totp/FoxDev%20Studio:eugene@xfox111.net?secret=ESQVTYRM2CWZC3NX24GRRWIAUUWVHWQH&issuer=FoxDev%20Studio"; -OTPConfiguration config = OTPConfiguration.GetConfiguration(sample_config_uri); -// OTPConfiguration { Id = af2358b0-3f69-4dd7-9537-32c07d6663aa, Type = TOTP, IssuerLabel = FoxDev Studio, AccountName = eugene@xfox111.net, Secret = ESQVTYRM2CWZC3NX24GRRWIAUUWVHWQH, Issuer = FoxDev Studio, Algorithm = SHA1, Digits = 6, Counter = 0, Period = 00:00:30 } -``` -Or just fill in properties manually. Then you need to serialize and deserialize the whole object: -```csharp -OTPConfiguration config = new () -{ - Type = OTPType.TOTP, - IssuerLabel = "My service name", - AccountName = "target_username@or_an_email.com", - Secret = "MYSECRETKEY", // To generate new secret you can use SimpleOTP.Helpers.SecretGenerator.GenerateSecret() - Issuer = "My service name", - Algorithm = Algorithm.SHA1, - Digits = 6, - Period = TimeSpan.FromSeconds(30) -} -``` -## Store configuration -You can store data in three different ways: -### 1. Store whole object instance in database (suitable for server side): -```csharp -OTPConfiguration config = dbContenxt.Configs.Find("af2358b0-3f69-4dd7-9537-32c07d6663aa"); -dbContext.Configs.Update(config); -dbContext.SaveChanges(); -``` -Data in database `Configs` table: -| Id (PRIMARY_KEY) | Type | IssuerLabel | AccountName | Secret | Issuer | Algorithm | Digits | Counter | Period | -| ---------------- | ---- | ----------- | ----------- | ------ | ------ | --------- | ------ | ------- | ------ | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | -| af2358b0-3f69-4dd7-9537-32c07d6663aa | 0 | FoxDev Studio | eugene@xfox111.net | ESQVTYRM2CWZC3NX24GRRWIAUUWVHWQH | FoxDev Studio | 0 | 6 | 0 | 00:30:00.000 | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | - -### 2. Store serialized object as string in storage (e.g. `Xamarin.Essentials.Preferences`) -```csharp -List list = JsonConvert.DeserializeObject>(Preferences.Get("configs", "[]"); // [] - Empty JSON array for fallback value -list.Add(config); -Preferences.Set("configs", JsonConvert.SerializeObject(list)); -``` -Storage content: -```json -[ - { - "Id": "af2358b0-3f69-4dd7-9537-32c07d6663aa", - "Type": 0, - "IssuerLabel": "FoxDev Studio", - "AccountName": "eugene@xfox111.net", - "Secret": "ESQVTYRM2CWZC3NX24GRRWIAUUWVHWQH", - "Issuer": "FoxDev Studio", - "Algorithm": 0, - "Digits": 6, - "Counter": 0, - "Period": "00:30:00" - } -] -``` - -### 3. Store OTP AUTH URIs: -```csharp -List list = JsonConvert.DeserializeObject(Preferences.Get("configs", "[]").Select(i => OTPConfiguration.GetConfiguration(i)).ToList(); -list.Add(config); -Preferences.Set("configs", JsonConvert.SerializeObject(list.Select(i => i.GetUri().AbsoluteUri).ToArray())); -``` -Storage content: -```json -[ - "otpauth://totp/FoxDev%20Studio:eugene@xfox111.net?secret=ESQVTYRM2CWZC3NX24GRRWIAUUWVHWQH&issuer=FoxDev%20Studio", - "otpauth://totp/Service1:eugene@xfox111.net?secret=ESQ4GRRWIAUUWVHWQHVTYRM2CWZC3NX2&issuer=Service1", - "otpauth://totp/Service2:eugene@xfox111.net?secret=NX24GRRWIAUESQVTYRM2CWZC3UWVHWQH&issuer=Service2", - "otpauth://totp/Service3:eugene@xfox111.net?secret=WZCESQVTYRM2C3NX24GRRWIAUUWVHWQH&issuer=Service3" -] -``` \ No newline at end of file diff --git a/OTPCode.GetCode.md b/OTPCode.GetCode.md deleted file mode 100644 index 1f16d2f..0000000 --- a/OTPCode.GetCode.md +++ /dev/null @@ -1,15 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -Gets valid 6 digit or more OTP code. -```csharp -public string GetCode(string formatter = "000000"); -``` -### Parameters -`formatter` `string` - -String formatter. Other variation: `"000 000"` - -### Returns -Formatted OTP code string with 6 or more digits. \ No newline at end of file diff --git a/OTPCode.OTPCode.md b/OTPCode.OTPCode.md deleted file mode 100644 index ea23ada..0000000 --- a/OTPCode.OTPCode.md +++ /dev/null @@ -1,34 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -## Overloads -| Overload | Description | -| --- | --- | -| [OTPCode()](#OTPCode) | Initializes a new instance of the `OTPCode` class. | -| [OTPCode(int)](#OTPCodeint) | Initializes a new instance of the `OTPCode` class. | - -## OTPCode() -Initializes a new instance of the `OTPCode` class. -```csharp -public OTPCode(); -``` -### Returns -[OTPCode](https://github.com/XFox111/SimpleOTP/wiki/OTPCode). - ---- - -## OTPCode(int) -Initializes a new instance of the `OTPCode` class. -```csharp -public OTPCode(int code); -``` -### Parameters -`code` `Int32` - -OTP code. - -### Returns -[OTPCode](https://github.com/XFox111/SimpleOTP/wiki/OTPCode). -### Remarks -Use this constructor only for HOTP key. Otherwise, fill out all properties. \ No newline at end of file diff --git a/OTPCode.md b/OTPCode.md deleted file mode 100644 index 14b76ee..0000000 --- a/OTPCode.md +++ /dev/null @@ -1,25 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -OTP code object model. -```csharp -public record OTPCode -``` - -## Constructors -| Constructor | Description | -| --- | --- | -| [OTPCode()](https://github.com/XFox111/SimpleOTP/wiki/OTPCode.OTPCode) | Initializes a new instance of the `OTPCode` class. | -| [OTPCode(int)](https://github.com/XFox111/SimpleOTP/wiki/OTPCode.OTPCode#OTPCodeint) | Initializes a new instance of the `OTPCode` class. | - -## Properties -| Property | Type | Accessor | Description | -| --- | --- | --- | --- | -| `Code` | `Int32` | get/set | Gets or sets OTP code. | -| `Expiring` | [DateTime?](https://docs.microsoft.com/en-us/dotnet/api/system.datetime?view=net-5.0) | get/set | Gets or sets date-time until the code is valid. | - -## Methods -| Method | Description | -| --- | --- | -| [GetCode(string)](https://github.com/XFox111/SimpleOTP/wiki/OTPCode.GetCode) | Gets valid 6 digit or more OTP code. | \ No newline at end of file diff --git a/OTPCodeUpdatedEventHandler.md b/OTPCodeUpdatedEventHandler.md deleted file mode 100644 index 28b0a07..0000000 --- a/OTPCodeUpdatedEventHandler.md +++ /dev/null @@ -1,15 +0,0 @@ -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -Represents method that will be called when new OTP code is generated. -```csharp -public delegate void OTPCodeUpdatedEventHandler(OTPCode code); -``` -### Parameters -`code` [OTPCode](https://github.com/XFox111/SimpleOTP/wiki/OTPCode) - -New OTP code instance. - -### Remarks -For implementation examples please refer to [OTPFactory](https://github.com/XFox111/SimpleOTP/wiki/OTPFactory) \ No newline at end of file diff --git a/OTPConfiguration.GenerateConfiguration.md b/OTPConfiguration.GenerateConfiguration.md deleted file mode 100644 index 5242cf0..0000000 --- a/OTPConfiguration.GenerateConfiguration.md +++ /dev/null @@ -1,27 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -Generate a new OTP configuration to send it to client. -```csharp -public static OTPConfiguration GenerateConfiguration(string issuer, string accountName); -``` -### Parameters -`issuer` `string` - -Name of your application/service. - -`accountName` `string` - -Username/email of the user. - -### Returns -Valid `OTPConfiguration` configuraion. - -### Remarks -Default parameters for generated configuration: -- OTP algorithm: Time-based OTP -- Key length: 160 bit (20 characters) -- Hashing algorithm: HMAC-SHA-1 -- OTP length: 6 digits -- Period: 30 seconds \ No newline at end of file diff --git a/OTPConfiguration.GetConfiguration.md b/OTPConfiguration.GetConfiguration.md deleted file mode 100644 index 9498d3b..0000000 --- a/OTPConfiguration.GetConfiguration.md +++ /dev/null @@ -1,94 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -## Overloads -| Overload | Description | -| --- | --- | -| [GetConfiguration(string, string, string)](#GetConfigurationstring-string-string) | Load OTP configuraiton with default parameters. | -| [GetConfiguration(string)](#GetConfigurationstring) | Loads OTP configuration from OTP AUTH URI. | -| [GetConfiguration(Uri)](#GetConfigurationUri) | Loads OTP configuration from OTP AUTH URI. | - -## GetConfiguration(string, string, string) -Load OTP configuraiton with default parameters. -```csharp -public static OTPConfiguration GetConfiguration(string secret, string issuer, string accountName); -``` -### Parameters -`secret` `string` - -OTP generator secret key (Base32 encoded string). - -`issuer` `string` - -Name of your application/service. - -`accountName` `string` - -Username/email of the user. -### Returns -Valid `OTPConfiguration` configuraion. - -### Remarks -Default parameters for generated configuration: -- OTP algorithm: Time-based OTP -- Key length: 160 bit (20 characters) -- Hashing algorithm: HMAC-SHA-1 -- OTP length: 6 digits -- Period: 30 seconds - ---- - -## GetConfiguration(string) -Loads OTP configuration from OTP AUTH URI. -```csharp -public static OTPConfiguration GetConfiguration(string uri); -``` -### Parameters -`uri` `string` - -OTP Auth URI. Should be correctly formed. - -### Returns -Valid `OTPConfiguration` configuraion. -### Exceptions -[UriFormatException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`uri` is a malformed URI. See [here](https://docs.microsoft.com/en-us/dotnet/api/system.uri.-ctor?view=net-5.0#System_Uri__ctor_System_String_) for more info - -[ArgumentException](https://docs.microsoft.com/en-us/dotnet/api/system.ArgumentException?view=net-5.0) - -`uri` is a malformed OTP URI: some values are missing or incorrect. - -### Remarks -For more information on OTP URI format please refer to [Key Uri Format](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) - ---- - -## GetConfiguration(Uri) -Loads OTP configuration from OTP AUTH URI. -```csharp -public static OTPConfiguration GetConfiguration(Uri uri); -``` -### Parameters -`uri` [Uri](https://docs.microsoft.com/en-us/dotnet/api/system.uri?view=net-5.0) - -OTP Auth URI. Should be correctly formed. - -### Returns -Valid `OTPConfiguration` configuraion. -### Exceptions -[UriFormatException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`uri` is a malformed URI. See [here](https://docs.microsoft.com/en-us/dotnet/api/system.uri.-ctor?view=net-5.0#System_Uri__ctor_System_String_) for more info - -[ArgumentException](https://docs.microsoft.com/en-us/dotnet/api/system.ArgumentException?view=net-5.0) - -`uri` is a malformed OTP URI: some values are missing or incorrect. - -[ArgumentNullException](https://docs.microsoft.com/en-us/dotnet/api/system.ArgumentNullException?view=net-5.0) - -`uri` is `null` - -### Remarks -For more information on OTP URI format please refer to [Key Uri Format](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) \ No newline at end of file diff --git a/OTPConfiguration.GetFancySecret.md b/OTPConfiguration.GetFancySecret.md deleted file mode 100644 index 0b975ac..0000000 --- a/OTPConfiguration.GetFancySecret.md +++ /dev/null @@ -1,17 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -Returns secret key separated with whitespaces on groups of 4. -```csharp -public string GetFancySecret(); -``` - -### Returns -Formatted secret key string. - -### Example -```csharp -OTPConfiguration config = OTPConfiguration.GetConfiguration("ESQVTYRM2CWZC3NX24GRRWIAUUWVHWQH", "FoxDev Studio", "eugene@xfox111.net"); -Console.WriteLine(config.GetFancySecret()); // ESQV TYRM 2CWZ C3NX 24GR RWIA UUWV HWQH -``` \ No newline at end of file diff --git a/OTPConfiguration.GetQrImage.md b/OTPConfiguration.GetQrImage.md deleted file mode 100644 index 60bd076..0000000 --- a/OTPConfiguration.GetQrImage.md +++ /dev/null @@ -1,19 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -Generates QR code image for current configuration with Google Chart API. -```csharp -public async Task GetQrImage(int qrCodeSize = 300, int requestTimeout = 30); -``` -### Parameters -`qrCodeSize` `Int32` - -QR code image size in pixels. - -`requestTimeout` `Int32` - -Web request timeout in seconds. - -### Returns -string-encoded PNG image. \ No newline at end of file diff --git a/OTPConfiguration.GetUri.md b/OTPConfiguration.GetUri.md deleted file mode 100644 index 09fb111..0000000 --- a/OTPConfiguration.GetUri.md +++ /dev/null @@ -1,11 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -Gets URI from current configuration to reuse it somewhere else. -```csharp -public Uri GetUri(); -``` - -### Returns -Valid [OTP AUTH URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). \ No newline at end of file diff --git a/OTPConfiguration.md b/OTPConfiguration.md deleted file mode 100644 index ef8e750..0000000 --- a/OTPConfiguration.md +++ /dev/null @@ -1,33 +0,0 @@ -Namespace: `SimpleOTP.Models` - -Assembly: `SimpleOTP.dll` - -OTP generator configuration object. -```csharp -public record OTPConfiguration -``` - -## Properties -| Property | Type | Accessor | Description | -| --- | --- | --- | --- | -| `Id` | [Guid](https://docs.microsoft.com/en-us/dotnet/api/system.guid?view=net-5.0) | get/set | Gets or sets unique identifier of current configuration instance. [Default: [Guid.NewGuid()](https://docs.microsoft.com/en-us/dotnet/api/system.guid.newguid?view=net-5.0#System_Guid_NewGuid)] | -| `Type` | [OTPType](https://github.com/XFox111/SimpleOTP/wiki/OTPType) | get/set | Gets or sets OTP algorithm type. | -| `IssuerLabel` | `string` | get/set | Gets or sets name of config issuer/service. | -| `AccountName` | `string` | get/set | Gets or sets username or email of current config. | -| `Secret` | `string` | get/set | Gets or sets secret key for OTP code generation. | -| `Issuer` | `string` | get/set | Gets or sets internal issuer name for additional identification. Currently should be the same with `IssuerLabel`. | -| `Algorithm` | [Algorithm](https://github.com/XFox111/SimpleOTP/wiki/Algorithm) | get/set | Gets or sets OTP hashing algorithm. [Default: `Algorithm.SHA1`] | -| `Digits` | `Int32` | get/set | Gets or sets number of digits of OTP code. [Default: `6`] | -| `Counter` | `Int64` | get/set | Gets or sets counter for HOTP generation. Update each time password has been generated. HOTP only. [Default: `0`] | -| `Period` | [TimeSpan](https://docs.microsoft.com/en-us/dotnet/api/system.timespan?view=net-5.0) | get/set | Gets or sets time of OTP validity interval. Used to calculate TOTP counter. [Default: `TimeSpan.FromSeconds(30)`] | - -## Methods -| Method | Description | -| --- | --- | -| [GenerateConfiguration(string, string)](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration.GenerateConfiguration) | Generate a new OTP configuration to send it to client. | -| [GetConfiguration(string, string, string)](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration.GetConfiguration) | Load OTP configuraiton with default parameters. | -| [GetConfiguration(string)](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration.GetConfiguration#GetConfigurationstring) | Loads OTP configuration from OTP AUTH URI. | -| [GetConfiguration(Uri)](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration.GetConfiguration#GetConfigurationUri) | Loads OTP configuration from OTP AUTH URI. | -| [GetUri()](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration.GetUri) | Gets URI from current configuration to reuse it somewhere else. | -| [GetFancySecret()](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration.GetFancySecret) | Returns secret key separated with whitespaces on groups of 4. | -| [GetQrImage(int, int)](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration.GetQrImage) | Generates QR code image for current configuration with Google Chart API. | \ No newline at end of file diff --git a/OTPFactory-overview.md b/OTPFactory-overview.md deleted file mode 100644 index 3495ea8..0000000 --- a/OTPFactory-overview.md +++ /dev/null @@ -1,61 +0,0 @@ -In case you are working on an authenticator app, you can use `OTPFactory` to handle code re-generation and timer updates -## Configure factory -To configure factory just simply pass an `OTPConfiguration` object to constructor: -```csharp -OTPFactory factory = new (config); -``` -You can update configuration any time by updating `Configuration` property - -## Subscribe to events -To keep code up to date on the UI side, subscribe to `CodeUpdated` event: -```csharp -factory.CodeUpdated += (newCode) => -{ - // Update your data here - this.codeLabel.Text = newCode.GetCode(); -}; -``` -Also it could be useful to subscribe to `PropertyChanged` event, since it occurs every second to keep code countdown up to date (countdown update frequency is set on instance constructor by parameter `timeUpdateInterval` in milliseconds) -```csharp -OTPFactory factory = new (config); // use 'new (config, 100)' to update countdown every 100 milliseconds -factory.PropertyChanged += (s, e) => -{ - if (e.PropertyName == nameof(factory.TimeLeft)) - this.countdownLabel.Text = factory.TimeLeft.ToString(); -}; -``` - -## Use MVVM pattern with OTPFactory -`OTPFactory` object is MVVM ready, so you can use it as is in your ViewModel -```csharp -public class MyViewModel : ViewModelBase -{ - private OTPFactory _factory = new (OTPConfiguration.GenerateConfiguration("FoxDev Studio", "eugene@xfox111.net")); // Example value - public OTPFactory Factory - { - get => _factory; - set => SetProperty(ref _factory, value); - } -} -``` -```xaml - - - - - - - - - ... - -``` - -## Dispose OTPFactory -When you don't need `OTPFactory` anymore it is important to dispose it to prevent memory leaks. To do so just simply call `OTPFactory.Dispose()` or use it with `using keyword` \ No newline at end of file diff --git a/OTPFactory.OTPFactory.md b/OTPFactory.OTPFactory.md deleted file mode 100644 index cc777b2..0000000 --- a/OTPFactory.OTPFactory.md +++ /dev/null @@ -1,20 +0,0 @@ -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -Initializes a new instance of the `OTPFactory` class. -```csharp -public OTPFactory(OTPConfiguration configuration, int timerUpdateInterval = 1000); -``` -### Parameters -`configuration` [OTPConfiguration]() - -OTP configuration for codes producing. - -`timeUpdateInterval` `Int32` - -Interval for timer updates in milliseconds.
-Default: 1000 milliseconds (1 second) - -### Returns -[OTPFactory](https://github.com/XFox111/SimpleOTP/wiki/OTPFactory). \ No newline at end of file diff --git a/OTPFactory.md b/OTPFactory.md deleted file mode 100644 index 2c17d95..0000000 --- a/OTPFactory.md +++ /dev/null @@ -1,38 +0,0 @@ -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -Class used to streamline OTP code generation on client devices. -```csharp -public class OTPFactory : INotifyPropertyChanged, IDisposable -``` -Inheritance: [INotifyPropertyChanged](https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.inotifypropertychanged?view=net-5.0), [IDisposable](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable?view=net-5.0) - -## Constructors -| Constructor | Description | -| --- | --- | -| [OTPFactory(OTPConfiguration, int)](https://github.com/XFox111/SimpleOTP/wiki/OTPFactory.OTPFactory) | Initializes a new instance of the `OTPFactory` class. | - -## Properties -| Property | Type | Accessor | Description | -| --- | --- | --- | --- | -| `CurrentCode` | [OTPCode](https://github.com/XFox111/SimpleOTP/wiki/OTPCode) | get/set | Gets or sets current valid OTP code instance. | -| `Configuration` | [OTPConfiguration](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) | get/set | Gets or sets OTP configuration of the current instance. | -| `TimeLeft` | [TimeSpan?](https://docs.microsoft.com/en-us/dotnet/api/system.timespan?view=net-5.0) | get/set | Gets time left before current OTP code expires. | - -## Events -| Event | EventType | Description | -| --- | --- | --- | -| `CodeUpdated` | [OTPCodeUpdatedEventHandler](https://github.com/XFox111/SimpleOTP/wiki/OTPCodeUpdatedEventHandler) | Event is fired when new OTP code is generated. | -| `PropertyChanged` | [PropertyChangedEventHandler](https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.propertychangedeventhandler?view=net-5.0) | Occurs when a property value changes. | - -## Methods -| Method | Description | -| --- | --- | -| [Dispose()](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable.dispose?view=net-5.0#System_IDisposable_Dispose) | Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
(Inherited from [IDisposable](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable?view=net-5.0#events)) | - -## Example -```csharp -var factory = new (config); -factory.CodeUpdated += (newCode) => Console.WriteLine(newCode.Code); -``` \ No newline at end of file diff --git a/OTPService.GenerateCode.md b/OTPService.GenerateCode.md deleted file mode 100644 index c231b39..0000000 --- a/OTPService.GenerateCode.md +++ /dev/null @@ -1,61 +0,0 @@ -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -## Overloads -| Overload | Description | -| --- | --- | -| [GenerateCode(ref OTPConfiguration)](#GenerateCoderef-OTPConfiguration) | Generates a new OTP code with provided configuration. | -| [GenerateCode(ref OTPConfiguration, DateTime)](#GenerateCoderef-OTPConfiguration-DateTime) | Generates a new TOTP code with provided configuration and for specific interval. | - -## GenerateCode(ref OTPConfiguration) -Generates a new OTP code with provided configuration. -```csharp -public static OTPCode GenerateCode(ref OTPConfiguration target); -``` -### Parameters -`target` [OTPConfiguration](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) - -OTP configuration object. -### Returns -[OTPCode](https://github.com/XFox111/SimpleOTP/wiki/OTPCode) instance with generated code. -### Exceptions -[NullReferenceException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`target` is `null` -### Examples -See `OTPService` usage examples on [Code generation/validation](https://github.com/XFox111/SimpleOTP/wiki/Code-generation-or-validation) -### Remarks -If you're using HOTP algorithm, save `target` after calling the function. - -If OTP algorithm is HOTP, `target` counter is increased by 1. - ---- - -## GenerateCode(ref OTPConfiguration, DateTime) -Generates a new TOTP code with provided configuration and for specific interval. -```csharp -public static OTPCode GenerateCode(ref OTPConfiguration target, DateTime date); -``` -### Parameters -`target` [OTPConfiguration](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) - -OTP configuration object. - -`date` [DateTime](https://docs.microsoft.com/en-us/dotnet/api/system.datetime?view=net-5.0) - -`DateTime` for which the OTP should be generated. -### Returns -[OTPCode](https://github.com/XFox111/SimpleOTP/wiki/OTPCode) instance with generated code. -### Exceptions -[NullReferenceException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`target` is `null` -### Examples -See `OTPService` usage examples on [Code generation/validation](https://github.com/XFox111/SimpleOTP/wiki/Code-generation-or-validation) -### Remarks -If you're using HOTP algorithm, save `target` after calling the function. - -If you're using HOTP algorithm, `date` will be ignored. - -If OTP algorithm is HOTP, `target` counter is increased by 1. \ No newline at end of file diff --git a/OTPService.ValidateCode.md b/OTPService.ValidateCode.md deleted file mode 100644 index 99f0de3..0000000 --- a/OTPService.ValidateCode.md +++ /dev/null @@ -1,93 +0,0 @@ -> ## Note of deprecation -> Methods described in this article are deprecated and will be removed from future releases starting version 2.0. Please, use [OTPService.ValidateHotp](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateHotp) and [OTPService.ValidateTotp](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateTotp) instead - -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -## Overloads -| Overload | Description | -| --- | --- | -| [ValidateCode(int, ref OTPConfiguration, int, bool)](#ValidateCodeint-ref-OTPConfiguration-int-bool) | Generates a new OTP code with provided configuration. | -| [ValidateCode(int, OTPConfiguration, TimeSpan)](#ValidateCodeint-OTPConfiguration-TimeSpan) | Generates a new TOTP code with provided configuration and for specific interval. | - -## ValidateCode(int, ref OTPConfiguration, int, bool) -> ## Note of deprecation -> Methods described in this article are deprecated and will be removed from future releases starting version 2.0. Please, use [OTPService.ValidateHotp](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateHotp) and [OTPService.ValidateTotp](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateTotp) instead - -Validates provided HOTP code with provided parameters. -```csharp -[Obsolete("Use ValidateHotp() instead.")] -public static bool ValidateCode(int otp, ref OTPConfiguration target, int toleranceSpan, bool resyncCounter); -``` -### Parameters -`otp` `Int32` - -HOTP code to validate. - -`target` [OTPConfiguration](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) - -OTP configuration for check codes generation. - -`toleranceSpan` `Int32` - -Counter span from which OTP codes remain valid. - -`resyncCounter` `Boolean` - -Defines whether method should resync `OTPConfiguration.Counter` of the `target` or not after successful validation. -### Returns -`True` if code is valid, `False` if it isn't. - -### Exceptions -[ArgumentException](https://docs.microsoft.com/en-us/dotnet/api/system.ArgumentException?view=net-5.0) - -`target.Type` is `OTPType.TOTP` - -[NullReferenceException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`target` is `null` -### Examples -See `OTPService` usage examples on [Code generation/validation](https://github.com/XFox111/SimpleOTP/wiki/Code-generation-or-validation) -### Remarks -Use this method only with HOTP codes. - ---- - -## ValidateCode(int, OTPConfiguration, TimeSpan) -> ## Note of deprecation -> Methods described in this article are deprecated and will be removed from future releases starting version 2.0. Please, use [OTPService.ValidateHotp](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateHotp) and [OTPService.ValidateTotp](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateTotp) instead - -Validates provided TOTP code with provided parameters. -```csharp -[Obsolete("Use ValidateTotp() instead.")] -public static bool ValidateTotp(int otp, OTPConfiguration target, TimeSpan? toleranceTime = null); -``` -### Parameters -`otp` `Int32` - -OTP code to validate. - -`target` [OTPConfiguration](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) - -OTP configuration for check codes generation. - -`toleranceTime` [TimeSpan?](https://docs.microsoft.com/en-us/dotnet/api/system.timespan?view=net-5.0) - -Time span from which OTP codes remain valid. Default: 15 seconds. - -### Returns -`True` if code is valid, `False` if it isn't. - -### Exceptions -[ArgumentException](https://docs.microsoft.com/en-us/dotnet/api/system.ArgumentException?view=net-5.0) - -`target.Type` is `OTPType.HOTP` - -[NullReferenceException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`target` is `null` -### Examples -See `OTPService` usage examples on [Code generation/validation](https://github.com/XFox111/SimpleOTP/wiki/Code-generation-or-validation) -### Remarks -Use this method only with Time-based OTP codes. \ No newline at end of file diff --git a/OTPService.ValidateHotp.md b/OTPService.ValidateHotp.md deleted file mode 100644 index 902e40b..0000000 --- a/OTPService.ValidateHotp.md +++ /dev/null @@ -1,39 +0,0 @@ -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -Validates provided HOTP code with provided parameters. -```csharp -public static bool ValidateHotp(int otp, ref OTPConfiguration target, int toleranceSpan, bool resyncCounter); -``` -### Parameters -`otp` `Int32` - -HOTP code to validate. - -`target` [OTPConfiguration](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) - -OTP configuration for check codes generation. - -`toleranceSpan` `Int32` - -Counter span from which OTP codes remain valid. - -`resyncCounter` `Boolean` - -Defines whether method should resync `OTPConfiguration.Counter` of the `target` or not after successful validation. -### Returns -`True` if code is valid, `False` if it isn't. - -### Exceptions -[ArgumentException](https://docs.microsoft.com/en-us/dotnet/api/system.ArgumentException?view=net-5.0) - -`target.Type` is `OTPType.TOTP` - -[NullReferenceException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`target` is `null` -### Examples -See `OTPService` usage examples on [Code generation/validation](https://github.com/XFox111/SimpleOTP/wiki/Code-generation-or-validation) -### Remarks -Use this method only with HOTP codes. \ No newline at end of file diff --git a/OTPService.ValidateTotp.md b/OTPService.ValidateTotp.md deleted file mode 100644 index 1bfcf32..0000000 --- a/OTPService.ValidateTotp.md +++ /dev/null @@ -1,36 +0,0 @@ -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -Validates provided TOTP code with provided parameters. -```csharp -public static bool ValidateTotp(int otp, OTPConfiguration target, TimeSpan? toleranceTime = null); -``` -### Parameters -`otp` `Int32` - -OTP code to validate. - -`target` [OTPConfiguration](https://github.com/XFox111/SimpleOTP/wiki/OTPConfiguration) - -OTP configuration for check codes generation. - -`toleranceTime` [TimeSpan?](https://docs.microsoft.com/en-us/dotnet/api/system.timespan?view=net-5.0) - -Time span from which OTP codes remain valid. Default: 15 seconds. - -### Returns -`True` if code is valid, `False` if it isn't. - -### Exceptions -[ArgumentException](https://docs.microsoft.com/en-us/dotnet/api/system.ArgumentException?view=net-5.0) - -`target.Type` is `OTPType.HOTP` - -[NullReferenceException](https://docs.microsoft.com/en-us/dotnet/api/system.nullreferenceexception?view=net-5.0) - -`target` is `null` -### Examples -See `OTPService` usage examples on [Code generation/validation](https://github.com/XFox111/SimpleOTP/wiki/Code-generation-or-validation) -### Remarks -Use this method only with Time-based OTP codes. \ No newline at end of file diff --git a/OTPService.md b/OTPService.md deleted file mode 100644 index 6df285c..0000000 --- a/OTPService.md +++ /dev/null @@ -1,21 +0,0 @@ -Namespace: `SimpleOTP` - -Assembly: `SimpleOTP.dll` - -Service class for generating and validating OTP codes. -```csharp -public static class OTPService -``` - -## Examples -See `OTPService` usage examples on [Code generation/validation](https://github.com/XFox111/SimpleOTP/wiki/Code-generation-or-validation) - -## Methods -| Method | Description | -| --- | --- | -| [GenerateCode(ref OTPConfiguration)](https://github.com/XFox111/SimpleOTP/wiki/OTPService.GenerateCode) | Generates a new OTP code with provided configuration. | -| [GenerateCode(ref OTPConfiguration, DateTime)](https://github.com/XFox111/SimpleOTP/wiki/OTPService.GenerateCode#generatecoderef-otpconfiguration-datetime) | Generates a new TOTP code with provided configuration and for specific interval. | -| [ValidateHotp(int, ref OTPConfiguration, int, bool)](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateHotp) | Validates provided HOTP code with provided parameters. | -| [ValidateTotp(int, OTPConfiguration, TimeSpan)](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateTotp) | Validates provided TOTP code with provided parameters. | -| [ValidateCode(int, ref OTPConfiguration, int, bool)](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateCode) | Obsolete. Validates provided HOTP code with provided parameters. | -| [ValidateCode(int, OTPConfiguration, TimeSpan)](https://github.com/XFox111/SimpleOTP/wiki/OTPService.ValidateCode#validatecodeint-otpconfiguration-timespan) | Obsolete. Validates provided TOTP code with provided parameters. | \ No newline at end of file diff --git a/OTPType.md b/OTPType.md deleted file mode 100644 index d7a4edb..0000000 --- a/OTPType.md +++ /dev/null @@ -1,14 +0,0 @@ -Namespace: `SimpleOTP.Enums` - -Assembly: `SimpleOTP.dll` - -OTP algorithm types. -```csharp -public enum OTPType -``` - -## Fields -| Field | Value | Description | -| ----- | ----- | -------------------------------------------------------------------------------------- | -| TOTP | 0 | Time-based One-Time Password [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238) | -| HOTP | 1 | HMAC-based One-Time Password [RFC 4226](https://datatracker.ietf.org/doc/html/rfc4226) | \ No newline at end of file diff --git a/SecretGenerator.GenerateSecret.md b/SecretGenerator.GenerateSecret.md deleted file mode 100644 index 4ed43d9..0000000 --- a/SecretGenerator.GenerateSecret.md +++ /dev/null @@ -1,22 +0,0 @@ -Namespace: `SimpleOTP.Helpers` - -Assembly: `SimpleOTP.dll` - -Generate OTP secret key. -```csharp -public static string GenerateSecret(int length = 160); -``` -### Parameters -`length` `Int32` - -Length of the key in bits - -It should belong to [128-160] bit span - -Default is: 160 bits. - -### Returns -Base32 encoded alphanumeric string with length form 16 to 20 characters. - -### Remarks -Number of bits will be rounded down to the nearest number which divides by 8. \ No newline at end of file diff --git a/SecretGenerator.md b/SecretGenerator.md deleted file mode 100644 index 970acea..0000000 --- a/SecretGenerator.md +++ /dev/null @@ -1,13 +0,0 @@ -Namespace: `SimpleOTP.Helpers` - -Assembly: `SimpleOTP.dll` - -Helper class for OTP secret generation. -```csharp -public static class SecretGenerator -``` - -## Methods -| Method | Description | -| --- | --- | -| [GenerateSecret](https://github.com/XFox111/SimpleOTP/wiki/SecretGenerator.GenerateSecret) | Generate OTP secret key. | \ No newline at end of file diff --git a/index.md b/index.md deleted file mode 100644 index 41f30e4..0000000 --- a/index.md +++ /dev/null @@ -1,51 +0,0 @@ -# SimpleOTP - -## SimpleOTP - -[HashAlgorithmProviders](./simpleotp.hashalgorithmproviders) - -[Hotp](./simpleotp.hotp) - -[Otp](./simpleotp.otp) - -[OtpAlgorithm](./simpleotp.otpalgorithm) - -[OtpCode](./simpleotp.otpcode) - -[OtpConfig](./simpleotp.otpconfig) - -[OtpSecret](./simpleotp.otpsecret) - -[OtpType](./simpleotp.otptype) - -[OtpUriFormat](./simpleotp.otpuriformat) - -[ToleranceSpan](./simpleotp.tolerancespan) - -[Totp](./simpleotp.totp) - -## SimpleOTP.Converters - -[OtpAlgorithmJsonConverter](./simpleotp.converters.otpalgorithmjsonconverter) - -[OtpCodeJsonConverter](./simpleotp.converters.otpcodejsonconverter) - -[OtpConfigJsonConverter](./simpleotp.converters.otpconfigjsonconverter) - -[OtpSecretJsonConverter](./simpleotp.converters.otpsecretjsonconverter) - -## SimpleOTP.Encoding - -[Base32Encoder](./simpleotp.encoding.base32encoder) - -[IEncoder](./simpleotp.encoding.iencoder) - -## SimpleOTP.Fluent - -[OtpBuilder](./simpleotp.fluent.otpbuilder) - -[OtpConfigBuilder](./simpleotp.fluent.otpconfigbuilder) - -[OtpConfigFluentExtensions](./simpleotp.fluent.otpconfigfluentextensions) - -[OtpFluentExtensions](./simpleotp.fluent.otpfluentextensions)