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)