Skip to content

Core API

Jump to bottom
Yassin Lokhat edited this page Mar 23, 2025 · 11 revisions

This section will cover all the API in detail.

Upsilon.Apps.PassKey.Core.Interfaces namespace

This namespace groups the essentials of the API. It contains some utilities interfaces (such as the serialization center or the cryptography center) and all the models used to represent the user's data.

Upsilon.Apps.PassKey.Core.Interfaces.ISerializationCenter

public interface ISerializationCenter;

This interface only specifies how objects are serialized and deserialized, mainly for a storage purpose.

Methods

Serialize

string Serialize<T>(T toSerialize) where T : notnull;

This method serializes the given object to a string.

  • T can be any not null type.
  • toSerialize is the object to serialize.
  • The method returns a string which is a serialized version of the given object.

Deserialize

T Deserialize<T>(string toDeserialize) where T : notnull;

This method deserializes the given string to the given type object.

  • T can be any not null type.
  • toDeserialize is the serialized version to deserialize.
  • The method returns the deserialized object.

Implementation

Although the user can implement this interface according to his needs and preferences, this repository already has an implementation under the type Upsilon.Apps.PassKey.Core.Utils.JsonSerializationCenter According to its name, this implementation uses json serialization.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter

public interface ICryptographyCenter;

This interface specifies all cryptographic methods such as the hashing algotithm, a symmetric encryption algotithm and an asymmetric encryption algotithm.

Properties

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.HashLength

int HashLength { get; }

This property indicate the constant length of the hashes provided by GetHash and GetSlowHash methods.

Methods

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.GetHash

string GetHash(string source);

This method returns a fast and length constant string hash of the given string.

  • source is the string to hash.
  • The method returns a string which is hash of the source parameter.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.GetSlowHash

string GetSlowHash(string source);

This method returns a slow and length constant string hash of the given string.

  • source is the string to hash.
  • The method returns a string which is hash of the source parameter.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.Sign

void Sign(ref string source);

This method signs a string.

  • source is the string to sign. The method will modify the string to add the signature.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.CheckSign

bool CheckSign(ref string source);

This method checks the signature of a given string.

  • source is the string to check. The method will modify the string to remove the signature.
  • The method returns true if the string is correctly signed, false otherwise.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.EncryptSymmetrically

string EncryptSymmetrically(string source, string[] passwords);

This method encrypts symmetrically a string with a set of passekeys in an onion structure.

  • source is the string to encrypt.
  • passwords is the set of passkeys used to encrypt the source.
  • The method returns the encrypted string.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.DecryptSymmetrically

string DecryptSymmetrically(string source, string[] passwords);

This method decrypts symmetrically a string with a set of passekeys in an onion structure.

  • source is the string to decrypt.
  • passwords is the set of passkeys used to decrypt the source.
  • The method returns the decrypted string.

Note that the implementation of this method should be able to detect :

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.GenerateRandomKeys

void GenerateRandomKeys(out string publicKey, out string privateKey);

This method generates a random public key and private key pair for the asymmetric encryption algorithm.

  • publicKey is the public key generated.
  • privateKey is the private key generated.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.EncryptAsymmetrically

string EncryptAsymmetrically(string source, string key);

This method encrypts asymmetrically a string with a public key.

  • source is the string to encrypt.
  • key is the public key used to encrypt the source.
  • The method returns the encrypted string.

Upsilon.Apps.PassKey.Core.Interfaces.ICryptographyCenter.DecryptAsymmetrically

string DecryptAsymmetrically(string source, string key);

This method decrypts asymmetrically a string with a private key.

  • source is the string to decrypt.
  • key is the private key used to decrypt the source.
  • The method returns the decrypted string.

Note that the implementation of this method should be able to detect :

Implementation

Although the user can implement this interface according to his needs and preferences, this repository already has an implementation under the type Upsilon.Apps.PassKey.Core.Utils.CryptographyCenter. This implementation uses a mix of MD5 and SHA1 for the hash, AES for the symmetric encryption and RSA for the asymmetric encryption.

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory

public interface IPasswordFactory;

This interface specifies how random passwords are generated and how to check if a password has been leaked.

Properties

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory.Alphabetic

string Alphabetic { get; }

This property indicate the alphabetic characters used to generate a password.

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory.Numeric

string Numeric { get; }

This property indicate the digit characters used to generate a password.

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory.SpecialChars

string SpecialChars { get; }

This property indicate the special characters used to generate a password.

Methods

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory.GeneratePassword

string GeneratePassword(int length,
   bool includeUpperCaseAlphabeticChars = true,
   bool includeLowerCaseAlphabeticChars = true,
   bool includeNumericChars = true,
   bool includeSpecialChars = true,
   string excludedChars = "",
   bool onlySafePasswords = true);

This method generates a random password.

  • length is the length of the password to generate.
  • includeUpperCaseAlphabeticChars tells if the upper alphabetic characters will used to build the password.
  • includeLowerCaseAlphabeticChars tells if the lower alphabetic characters will used to build the password.
  • includeNumericChars tells if the digit characters will used to build the password.
  • includeSpecialChars tells if the special characters will used to build the password.
  • excludedChars is the set of characters to exclude when building the password.
  • onlySafePasswords ensures that the generated password has not been already leaked.
  • The method returns a random password.

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory.GeneratePassword

string GeneratePassword(int length,
   string alphabet,
   bool onlySafePasswords = true);

This method generates a random password using the given alphabet.

  • length is the length of the password to generate.
  • alphabet is the set of characters to exclude when building the password.
  • onlySafePasswords ensures that the generated password has not been already leaked.
  • The method returns a random password.

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory.PasswordLeaked

bool PasswordLeaked(string password);

This method checks if the password has been leaked.

  • password is the password to check.
  • The method returns true if the password has been leaked, false otherwise.

Implementation

Although the user can implement this interface according to his needs and preferences, this repository already has an implementation under the type Upsilon.Apps.PassKey.Core.Utils.PasswordFactory. This implementation uses ABCDEFGHIJKLMNOPQRSTUVWXYZ as alphabetic characters, 0123456789 as digit characters and ~!@#$%^&*()_-+={[}]\|'";:,<.>/? as special characters. It also uses the ';--have i been pwned? API to checks if a password leaked or not.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase

public interface IDatabase : IDisposable;

This interface defines a database as the start point for all actions. It inherits from IDisposable.

Properties

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.DatabaseFile

string DatabaseFile { get; }

This property indicate the path to the database file.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.AutoSaveFile

string AutoSaveFile { get; }

This property indicate the path to the autosave file.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.LogFile

string LogFile { get; }

This property indicate the path to the log file.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.User

IUser? User { get; }

This property refers the IUser representing the logged user. While no user is logged in, this will be null. Use the Login method to login.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.Logs

ILog[]? Logs { get; }

This property gives the list of logs for the logged user as a list of ILog. Like for the User property, while no user is logged in, this will be null.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.Warnings

IWarning[]? Warnings { get; }

This property gives the list of all warnings detected for the logged user. Like for the User property, while no user is logged in, this will be null.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.SerializationCenter

ISerializationCenter SerializationCenter { get; }

This property refer to the ISerializationCenter used to serialize and deserialize data.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.CryptographyCenter

ICryptographyCenter CryptographyCenter { get; }

This property refer to the ICryptographyCenter used to encrypt and decrypt data.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.PasswordFactory

Upsilon.Apps.PassKey.Core.Interfaces.IPasswordFactory PasswordFactory { get; }

This property refer to the IPasswordFactory implementation.

Events

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.WarningDetected

event EventHandler<WarningDetectedEventArgs>? WarningDetected;

This event is raised when warnings are detected on successful login. The types of warnings detected here can be configured by the IUser.WarningsToNotify flag property. Note that if that user property is set to 0 (no warnings), this event will not be triggered even if warnings are effectively found. Though, the Warnings always gives all detected warnings and ignore the IUser.WarningsToNotify flag property.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.AutoSaveDetected

event EventHandler<AutoSaveDetectedEventArgs>? AutoSaveDetected;

This event is raised when an autosave file is detected.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.DatabaseSaved

event EventHandler? DatabaseSaved;

This event is raised when the database is saved. This happen on a Save call, a Create call or a AutoSaveDetected event rize with a Upsilon.Apps.PassKey.Core.Events.AutoSaveDetectedEventArgs.MergeBehavior set to Upsilon.Apps.PassKey.Core.Enums.AutoSaveMergeBehavior.MergeThenRemoveAutoSaveFile.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.DatabaseClosed

event EventHandler<LogoutEventArgs>? DatabaseClosed;

This event is raised when the database is closed. This happen on a IDatabase.Close call or when the IUser.LogoutTimeout is reached.

Methods

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.Login

IUser? Login(string passkey);

This method tries to log into a database using the given passkey. In practice, the user calls several times this method by giving it every password of its set of master password. On the last call, this method updates the User property by loading the decripted content.

  • passkey is the n-th passkey of the set of master password.
  • The method returns null if the set of previously given passwords don't match to the real master password set.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.Save

void Save();

This method saves the current user to database file and triger the DatabaseSaved event. The User must be loaded, else it will throw a NullReferenceException.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.Delete

void Delete();

This method deletes the current user with all its files. The User must be loaded, else it will throw a NullReferenceException.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.Create

static IDatabase Create(ICryptographyCenter cryptographicCenter,
   ISerializationCenter serializationCenter,
   IPasswordFactory passwordFactory,
   string databaseFile,
   string autoSaveFile,
   string logFile,
   string username,
   string[] passkeys);

This static method creates a new user database and returns it. After creating, the User should be loaded with the Login method.

  • cryptographicCenter is an implementation of ICryptographyCenter.
  • serializationCenter is an implementation of ISerializationCenter.
  • passwordFactory is an implementation of IPasswordFactory.
  • databaseFile is the path to the database file.
  • autoSaveFile is the path to the autosave file.
  • logFile is the path to the log file.
  • username is the username.
  • passkeys is the set of master password of the user.
  • The method returns the IDatabase corresponding to the user database created.

Upsilon.Apps.PassKey.Core.Interfaces.IDatabase.Open

static IDatabase Open(ICryptographyCenter cryptographicCenter,
   ISerializationCenter serializationCenter,
   IPasswordFactory passwordFactory,
   string databaseFile,
   string autoSaveFile,
   string logFile,
   string username);

This static method opens an user database and returns it. After opening, the User should be loaded with the Login method.

  • cryptographicCenter is an implementation of ICryptographyCenter.
  • serializationCenter is an implementation of ISerializationCenter.
  • passwordFactory is an implementation of IPasswordFactory.
  • databaseFile is the path to the database file.
  • autoSaveFile is the path to the autosave file.
  • logFile is the path to the log file.
  • username is the username.
  • The method returns the IDatabase corresponding to the user database opened.

Implementation

There is no public implementation for this interface since the intern logic and behavious should be closed to the API user. To effectively get an implemented instance, use IDatabase.Create and IDatabase.Open static methods.

Clone this wiki locally