en-US/Posh-SecretSharing-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Join-SecretSharingSecret</command:name> <command:verb>Join</command:verb> <command:noun>SecretSharingSecret</command:noun> <maml:description> <maml:para>Reconstructs a secret from a quorum of SLIP-0039 mnemonic shares.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Accepts share mnemonics (as plain strings, or as objects with a Mnemonic property - the output of Split-SecretSharingSecret works directly), verifies each one's checksum, groups them by GroupIndex, reconstructs each resolvable group's share value (verifying that group's digest once its member threshold is met), then reconstructs the encrypted master secret from enough groups (verifying the group-level digest), and finally decrypts it.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Join-SecretSharingSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Share</maml:name> <maml:description> <maml:para>The shares to combine: mnemonic strings, or objects with a Mnemonic property (such as Split-SecretSharingSecret's output). Accepts pipeline input.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject[]</command:parameterValue> <dev:type> <maml:name>PSObject[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Passphrase</maml:name> <maml:description> <maml:para>The passphrase used when the shares were created, if any.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecureString</command:parameterValue> <dev:type> <maml:name>SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Share</maml:name> <maml:description> <maml:para>The shares to combine: mnemonic strings, or objects with a Mnemonic property (such as Split-SecretSharingSecret's output). Accepts pipeline input.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject[]</command:parameterValue> <dev:type> <maml:name>PSObject[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Passphrase</maml:name> <maml:description> <maml:para>The passphrase used when the shares were created, if any.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecureString</command:parameterValue> <dev:type> <maml:name>SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>A wrong -Passphrase cannot be detected here: per SLIP-0039's design, every passphrase decrypts to some value of the right length, correct or not, with no way to tell the difference - this is deliberate, and enables plausible deniability. This cmdlet throws a clear terminating error for corrupted, insufficient, or mismatched shares (checksum and digest verification both fail loudly), but a wrong passphrase with otherwise-valid shares returns silently with the wrong secret, not an error.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$shares | Join-SecretSharingSecret</dev:code> <dev:remarks> <maml:para>Reconstructs a secret from a set of Split-SecretSharingSecret output objects.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-SecretSharingPassword</command:name> <command:verb>New</command:verb> <command:noun>SecretSharingPassword</command:noun> <maml:description> <maml:para>Generates a random, typeable password at a given entropy level.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns a cryptographically random password as a SecureString, built with the same one-byte-per-character convention as New-SecretSharingSecret's output, so it can be split and reconstructed via Split-/Join-SecretSharingSecret exactly like any other secret - the value recovered from a quorum of shares is the literal original password, not a derived value.</maml:para> <maml:para>Unlike New-SecretSharingSecret's raw random bytes (values 0-255, not meant to be typed, displayed, or used outside this module), this password is built only from characters that are safe to type, paste, or store in a shell command, URL, CSV file, JSON document, or SQL statement without extra escaping - see Get-SecretSharingPasswordConstant for the exact alphabet and the reasoning behind each excluded character.</maml:para> <maml:para>Because that alphabet carries fewer than 8 bits of entropy per character (~6.23 bits/character for its 75-character alphabet, vs. 8 for a raw byte), the password is longer than New-SecretSharingSecret's 16/32 bytes - long enough that its total entropy is at least the requested Entropy value, rounded up to an even character count (Split-SecretSharingSecret requires an even byte count).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-SecretSharingPassword</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Entropy</maml:name> <maml:description> <maml:para>The minimum entropy of the generated password, in bits. Must be 128 or 256, matching New-SecretSharingSecret's supported levels.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Entropy</maml:name> <maml:description> <maml:para>The minimum entropy of the generated password, in bits. Must be 128 or 256, matching New-SecretSharingSecret's supported levels.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$password = New-SecretSharingPassword -Entropy 128</dev:code> <dev:remarks> <maml:para>PS> Split-SecretSharingSecret -Secret $password -Group @{ Threshold = 3; Count = 5 } Generates a typeable password with at least 128 bits of entropy and splits it into 5 shares, any 3 of which reconstruct the exact same password.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-SecretSharingSecret</command:name> <command:verb>New</command:verb> <command:noun>SecretSharingSecret</command:noun> <maml:description> <maml:para>Generates a new random master secret for Shamir secret sharing.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns a cryptographically random secret of the requested entropy, as a SecureString, suitable as input to Split-SecretSharingSecret. Per SLIP-0039, the only valid entropy values are 128 and 256 bits.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-SecretSharingSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Entropy</maml:name> <maml:description> <maml:para>The entropy of the generated secret, in bits. Must be 128 or 256.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Entropy</maml:name> <maml:description> <maml:para>The entropy of the generated secret, in bits. Must be 128 or 256.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$secret = New-SecretSharingSecret -Entropy 128</dev:code> <dev:remarks> <maml:para>Generates a new 128-bit secret.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Split-SecretSharingSecret</command:name> <command:verb>Split</command:verb> <command:noun>SecretSharingSecret</command:noun> <maml:description> <maml:para>Splits a secret into SLIP-0039 mnemonic shares under a group/member quorum scheme.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Encrypts Secret (optionally with a Passphrase) into an encrypted master secret, splits it across one or more groups via a GroupThreshold-of-Group.Count Shamir scheme, and splits each group's share across that group's members via its own Threshold-of-Count scheme. Returns one object per member share.</maml:para> <maml:para>For the common case - a single group, T-of-N - pass one -Group entry and leave -GroupThreshold at its default of 1: e.g. -Group @{ Threshold = 3; Count = 5 } for a classic 3-of-5 split. Multi-group hierarchical schemes are supported by passing more than one -Group entry and a -GroupThreshold greater than 1.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Split-SecretSharingSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Secret</maml:name> <maml:description> <maml:para>The secret to split, e.g. from New-SecretSharingSecret.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecureString</command:parameterValue> <dev:type> <maml:name>SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Passphrase</maml:name> <maml:description> <maml:para>An optional passphrase. An empty/omitted passphrase is a valid, deliberate SLIP-0039 input - see the .NOTES on Join-SecretSharingSecret for why a wrong passphrase cannot be detected.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecureString</command:parameterValue> <dev:type> <maml:name>SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Group</maml:name> <maml:description> <maml:para>One hashtable per group, each with Threshold and Count keys, e.g. @{ Threshold = 3; Count = 5 }. At least 1, at most 16 entries.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable[]</command:parameterValue> <dev:type> <maml:name>Hashtable[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>GroupThreshold</maml:name> <maml:description> <maml:para>The number of groups that must each meet their own member threshold to reconstruct the secret. Defaults to 1 (the whole secret needs only one group, the common single-group case).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>1</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>IterationExponent</maml:name> <maml:description> <maml:para>Controls the PBKDF2 iteration count for the master-secret cipher (10000 << IterationExponent, divided across 4 rounds). 0-15, default 0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Extendable</maml:name> <maml:description> <maml:para>Marks the backup as extendable: shares can be added to the set later without invalidating existing ones, at the cost of the encryption salt not being bound to this specific share set.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Secret</maml:name> <maml:description> <maml:para>The secret to split, e.g. from New-SecretSharingSecret.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecureString</command:parameterValue> <dev:type> <maml:name>SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Passphrase</maml:name> <maml:description> <maml:para>An optional passphrase. An empty/omitted passphrase is a valid, deliberate SLIP-0039 input - see the .NOTES on Join-SecretSharingSecret for why a wrong passphrase cannot be detected.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecureString</command:parameterValue> <dev:type> <maml:name>SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Group</maml:name> <maml:description> <maml:para>One hashtable per group, each with Threshold and Count keys, e.g. @{ Threshold = 3; Count = 5 }. At least 1, at most 16 entries.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable[]</command:parameterValue> <dev:type> <maml:name>Hashtable[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>GroupThreshold</maml:name> <maml:description> <maml:para>The number of groups that must each meet their own member threshold to reconstruct the secret. Defaults to 1 (the whole secret needs only one group, the common single-group case).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>1</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Extendable</maml:name> <maml:description> <maml:para>Marks the backup as extendable: shares can be added to the set later without invalidating existing ones, at the cost of the encryption salt not being bound to this specific share set.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>IterationExponent</maml:name> <maml:description> <maml:para>Controls the PBKDF2 iteration count for the master-secret cipher (10000 << IterationExponent, divided across 4 rounds). 0-15, default 0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSCustomObject, one per member share, with Identifier, Extendable,</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>IterationExponent, GroupIndex, GroupThreshold, GroupCount, MemberIndex,</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>MemberThreshold, and Mnemonic properties.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$secret = New-SecretSharingSecret -Entropy 128</dev:code> <dev:remarks> <maml:para>PS> Split-SecretSharingSecret -Secret $secret -Group @{ Threshold = 3; Count = 5 } Splits a 128-bit secret into 5 shares, any 3 of which reconstruct it.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> </helpItems> |