Xecrets.Sdk.Abstractions.md
May 26, 2026 · View on GitHub
Xecrets.Sdk
Xecrets.Sdk.Abstractions Namespace
Interfaces
IXfApi Interface
The main SDK interface to use when calling the command line for operations. Use XfApiFactory to create instances of the interface.
public interface IXfApi
Methods
IXfApi.CliToolInformationAsync() Method
Call the command line and request information as a CliToolInformation instance.
System.Threading.Tasks.Task<Xecrets.Sdk.Cli.Models.CliToolInformation> CliToolInformationAsync();
Returns
System.Threading.Tasks.Task<CliToolInformation>
The information requested by calling the command line.
IXfApi.CreateKeyPairAsync(string, string) Method
Create an asymmetric key pair XfEncryptedKeyPair as an encrypted blob, using the provided password.
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfEncryptedKeyPair> CreateKeyPairAsync(string password, string email);
Parameters
password System.String
The password to encrypt the key pair with.
email System.String
The email to associate the key pair with.
Returns
System.Threading.Tasks.Task<XfEncryptedKeyPair>
The XfEncryptedKeyPair
IXfApi.DecryptArmorAsync(XfCredentials, string) Method
Decrypt an arbitrary string from ASCII armor format.
System.Threading.Tasks.Task<(string text,string fileName)> DecryptArmorAsync(Xecrets.Sdk.Models.XfCredentials credentials, string armor);
Parameters
credentials XfCredentials
One or more passwords to decrypt with.
armor System.String
The ASCII armor string to decrypt.
Returns
System.Threading.Tasks.Task<<System.String,System.String>>
The decrypted text, and the original file name embedded in the encrypted data.
IXfApi.DecryptFilesInPlaceAsync(XfCredentials, IEnumerable, Action) Method
Decrypt files in their location, using the stored original file name.
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfFileResult[]> DecryptFilesInPlaceAsync(Xecrets.Sdk.Models.XfCredentials credentials, System.Collections.Generic.IEnumerable<Xecrets.Sdk.Models.XfFilePair> files, System.Action<Xecrets.Sdk.Models.XfMessage> progress);
Parameters
credentials XfCredentials
One or more passwords to encrypt with.
files System.Collections.Generic.IEnumerable<XfFilePair>
The list of files to decrypt. Only the SourceFullName is used.
progress System.Action<XfMessage>
An System.Action delegate called with progress.
Returns
System.Threading.Tasks.Task<XfFileResult[]>
An array of XfFileResult instances representing the resulting files.
IXfApi.DecryptKeyPairAsync(string, IEnumerable) Method
Attempt to decrypt key pairs using the provided password. The first one possible to decrypt in the given enumerable will be returned.
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfKeyPair?> DecryptKeyPairAsync(string password, System.Collections.Generic.IEnumerable<Xecrets.Sdk.Models.XfEncryptedKeyPair> encryptedKeyPairs);
Parameters
password System.String
The password to try to decrypt with.
encryptedKeyPairs System.Collections.Generic.IEnumerable<XfEncryptedKeyPair>
A list of key pairs to try to decrypt.
Returns
System.Threading.Tasks.Task<XfKeyPair>
The first key pair possible to decrypt, or null if none could be decrypted.
IXfApi.DecryptStreamAsync(XfCredentials, Stream, Stream) Method
Decrypt an arbitrary stream to another stream
System.Threading.Tasks.Task<string> DecryptStreamAsync(Xecrets.Sdk.Models.XfCredentials credentials, System.IO.Stream cipherStream, System.IO.Stream clearStream);
Parameters
credentials XfCredentials
One or more passwords to decrypt with.
cipherStream System.IO.Stream
A stream of data to decrypt.
clearStream System.IO.Stream
A stream to write the clear text to.
Returns
System.Threading.Tasks.Task<System.String>
A System.Threading.Tasks.Task to wait for and the original file name as a string, or an empty string if the
credentials were invalid.
IXfApi.DecryptToAndKeepFileAsync(XfCredentials, FileInfo, DirectoryInfo, Action) Method
Decrypt a file using the provided credentials, to a specified directory, returning the resulting original filename and decrypted file represented by a System.IO.FileInfo instance.
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfFileResult[]> DecryptToAndKeepFileAsync(Xecrets.Sdk.Models.XfCredentials credentials, System.IO.FileInfo file, System.IO.DirectoryInfo directory, System.Action<Xecrets.Sdk.Models.XfMessage> progress);
Parameters
credentials XfCredentials
One or more passwords to encrypt with.
file System.IO.FileInfo
The file to decrypt.
directory System.IO.DirectoryInfo
The location to decrypt to.
progress System.Action<XfMessage>
An System.Action delegate called with progress.
Returns
System.Threading.Tasks.Task<XfFileResult[]>
An array of results, with excactly 1 element.
IXfApi.EncryptFilesAsync(XfCredentials, bool, bool, IEnumerable, Action) Method
Encrypt plain text files as encrypted files, keeping or wiping the originals.
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<System.IO.FileInfo>> EncryptFilesAsync(Xecrets.Sdk.Models.XfCredentials credentials, bool overwrite, bool wipe, System.Collections.Generic.IEnumerable<Xecrets.Sdk.Models.XfFilePair> pairs, System.Action<Xecrets.Sdk.Models.XfMessage> progress);
Parameters
credentials XfCredentials
The credentials to use when encrypting the files.
overwrite System.Boolean
Set to 'false' if overwriting the target should be disallowed, and instead use an alternate non-colliding name.
wipe System.Boolean
Set to 'true' to also wipe the original plain text.
pairs System.Collections.Generic.IEnumerable<XfFilePair>
File name pairs, providing source and target names as well as original name to include in the encrypted file.
progress System.Action<XfMessage>
An System.Action delegate that will be called reporting progress of the operation.
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<System.IO.FileInfo>>
IXfApi.EncryptKeyPairAsync(XfKeyPair) Method
Encrypt a XfKeyPair into a XfEncryptedKeyPair using the provided password in the XfKeyPair instance.
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfEncryptedKeyPair> EncryptKeyPairAsync(Xecrets.Sdk.Models.XfKeyPair keyPair);
Parameters
keyPair XfKeyPair
The key pair to encrypt.
Returns
System.Threading.Tasks.Task<XfEncryptedKeyPair>
The encrypted key pair as a blob.
IXfApi.EncryptStreamAsync(XfCredentials, string, Stream, Stream) Method
Encrypt an arbitrary stream to another stream
System.Threading.Tasks.Task EncryptStreamAsync(Xecrets.Sdk.Models.XfCredentials credentials, string originalFileName, System.IO.Stream clearStream, System.IO.Stream cipherStream);
Parameters
credentials XfCredentials
One or more passwords to encrypt with.
originalFileName System.String
The original file name to embed into the encrypted file stream
clearStream System.IO.Stream
A stream of data to encrypt.
cipherStream System.IO.Stream
The stream to write the encrypted data to.
Returns
System.Threading.Tasks.Task
A System.Threading.Tasks.Task to wait for.
IXfApi.EncryptTextAsync(XfCredentials, string, string) Method
Encrypt an arbitrary string to ASCII armor format.
System.Threading.Tasks.Task<string> EncryptTextAsync(Xecrets.Sdk.Models.XfCredentials credentials, string text, string originalFileName);
Parameters
credentials XfCredentials
One or more passwords to encrypt with.
text System.String
The text to encrypt.
originalFileName System.String
The original file name to embed into the encrypted file stream.
Returns
System.Threading.Tasks.Task<System.String>
The string encrypted, packaged as an ASCII armor string.
IXfApi.IsSdkCompatibleWith(Version) Method
Determine if the consumer, using this version of the SDK and the provided cliApiVersion version are compatible, i.e. if the caller having a command line tool of the given version can use this version of the SDK.
bool IsSdkCompatibleWith(System.Version cliApiVersion);
Parameters
cliApiVersion System.Version
The version of the command line tool API to check.
Returns
System.Boolean
True if this SDK can work with the provided command line tool.
IXfApi.Slip39CombineAsync(IEnumerable) Method
Try to combine shares and recover the secret.
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfSlip39.ShareSet?> Slip39CombineAsync(System.Collections.Generic.IEnumerable<string> shares);
Parameters
shares System.Collections.Generic.IEnumerable<System.String>
Returns
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfSlip39.ShareSet>
The shares, grouped and interpreted as well as the secret if possible. Returns null if there's
something wrong with one or more of the shares.
IXfApi.Slip39SplitAsync(string, int, int) Method
Split a secret into shares using the SLIP39 scheme.
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfSlip39.ShareSet> Slip39SplitAsync(string secret, int shares, int threshold);
Parameters
secret System.String
The secret to split.
shares System.Int32
The number of shares to split it into.
threshold System.Int32
The number of shares required to recover the secret. Must be greater than 1 and less than or equal the number of shares.
Returns
System.Threading.Tasks.Task<Xecrets.Sdk.Models.XfSlip39.ShareSet>
The shares
IXfApi.UpdatePrivateKeysAsync(XfCredentials, string) Method
Load private keys for decryption, returning an updated version with the same keys.
System.Threading.Tasks.Task<string> UpdatePrivateKeysAsync(Xecrets.Sdk.Models.XfCredentials credentials, string json);
Parameters
credentials XfCredentials
One or more passwords to decrypt the private keys with.
json System.String
A json serialized instance with private keys.
Returns
System.Threading.Tasks.Task<System.String>
The updated encrypted keys json.
IXfApi.WipeFilesAsync(IEnumerable, Action) Method
Wipe files.
System.Threading.Tasks.Task WipeFilesAsync(System.Collections.Generic.IEnumerable<string> fullNames, System.Action<Xecrets.Sdk.Models.XfMessage> progress);
Parameters
fullNames System.Collections.Generic.IEnumerable<System.String>
The list of full path names to wipe.
progress System.Action<XfMessage>
An System.Action delegate called with progress.
Returns
System.Threading.Tasks.Task
A waitable task.
IXfApiFactory Interface
A factory for creating an IXfApi instance.
public interface IXfApiFactory
Derived
↳ XfApiFactory
Methods
IXfApiFactory.Create(Nullable, CancellationToken) Method
Create an IXfApi instance.
Xecrets.Sdk.Abstractions.IXfApi Create(System.Nullable<bool> debugOverride, System.Threading.CancellationToken ct);
Parameters
debugOverride System.Nullable<System.Boolean>
Override the global debug cli flag if non-null.
ct System.Threading.CancellationToken
A System.Threading.CancellationToken to cancel any long running operation.
Returns
IXfApi
An IXfApi instance.
IXfStart Interface
Provides start-up information for the application.
public interface IXfStart
Methods
IXfStart.StartArgs(string) Method
Get the start arguments necessary to start the program identified as fileNameWithoutExtension, assuming that if we're started with "dotnet", this program should also be started with "dotnet" fileNameWithoutExtension.dll, otherwise it's an executable with ".exe" or without depending on the current operating system.
string[] StartArgs(string fileNameWithoutExtension);
Parameters
fileNameWithoutExtension System.String