en-US/SecretManagement.DpapiNG.Module.dll-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>Add-DpapiNGDescriptor</command:name> <command:verb>Add</command:verb> <command:noun>DpapiNGDescriptor</command:noun> <maml:description> <maml:para>Adds a new protection descriptor clause.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Adds a new protection descriptor clause to an existing protection descriptor created by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md). Each new clause will be added with an `AND` unless `-Or` is specified. The protection descriptor is used to descibe what entities are allowed to decrypt the secret it protects. The following descriptor types are supported:</maml:para> <maml:para>+ `LOCAL`</maml:para> <maml:para>+ `SID`</maml:para> <maml:para>+ `CERTIFICATE`</maml:para> <maml:para>+ `WEBCREDENTIALS`</maml:para> <maml:para>See about_DpapiNGProtectionDescriptor (./about_DpapiNGProtectionDescriptor.md)for more details.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Add-DpapiNGDescriptor</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The `X509Certificate2` to use when encrypting the data. The decryptor needs to have the associated private key of the certificate used to decrypt the value. This method will set the protection descriptor `CERTIFICATE=CertBlob:$certBase64String`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The protection descriptor object generated by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Or</maml:name> <maml:description> <maml:para>Adds the new descriptor clause with an `OR` rather than an `AND`. How this is treated by DPAPI-NG depends on the existing clauses that have already been added.</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:syntaxItem> <maml:name>Add-DpapiNGDescriptor</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>The thumbprint for a certificate stored inside `Cert:\CurrentUser\My` to use for encryption. Only the public key needs to be present to encrypt the value but the decryption process requires the associated private key to be present. This method will set the protection descriptor `CERTIFICATE=HashID:$CertificateThumbprint`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The protection descriptor object generated by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Or</maml:name> <maml:description> <maml:para>Adds the new descriptor clause with an `OR` rather than an `AND`. How this is treated by DPAPI-NG depends on the existing clauses that have already been added.</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:syntaxItem> <maml:name>Add-DpapiNGDescriptor</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CurrentSid</maml:name> <maml:description> <maml:para>Adds the clause `SID=$UserSid` where `$UserSid` represents the current user's SecurityIdentifier. A secret protected by this value can be decrypted by this user on any machine in the domain.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The protection descriptor object generated by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Or</maml:name> <maml:description> <maml:para>Adds the new descriptor clause with an `OR` rather than an `AND`. How this is treated by DPAPI-NG depends on the existing clauses that have already been added.</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:syntaxItem> <maml:name>Add-DpapiNGDescriptor</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The protection descriptor object generated by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Local</maml:name> <maml:description> <maml:para>Adds the `LOCAL` descriptor clause to either `User`, `Machine`, `Logon`. The `User` value protects the secret to just this user on the current host. The `Machine` value protects the secret to the current computer. The `Logon` value protects the secret to just this user's logon session. This is slightly different to `User` in that the same user logged on through another session will be unable to decrypt the secret.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">User</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Machine</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Or</maml:name> <maml:description> <maml:para>Adds the new descriptor clause with an `OR` rather than an `AND`. How this is treated by DPAPI-NG depends on the existing clauses that have already been added.</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:syntaxItem> <maml:name>Add-DpapiNGDescriptor</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The protection descriptor object generated by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Or</maml:name> <maml:description> <maml:para>Adds the new descriptor clause with an `OR` rather than an `AND`. How this is treated by DPAPI-NG depends on the existing clauses that have already been added.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Sid</maml:name> <maml:description> <maml:para>Adds the `SID` descriptor clause to the SecurityIdentifier specified. The SecurityIdentifier can be the SID of a domain user or group. If a group SID is specified, any user who is a member of that group can decrypt the secret it applies to.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringOrAccount</command:parameterValue> <dev:type> <maml:name>StringOrAccount</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-DpapiNGDescriptor</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The protection descriptor object generated by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Or</maml:name> <maml:description> <maml:para>Adds the new descriptor clause with an `OR` rather than an `AND`. How this is treated by DPAPI-NG depends on the existing clauses that have already been added.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WebCredential</maml:name> <maml:description> <maml:para>The credential manager to protect the secret with. The string value is in the format `username,resource`, for example a web credential for `dpapi-ng.com` with the user `MyUser` would be `-WebCredential 'MyUser,dpapi-ng.com'`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</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="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The `X509Certificate2` to use when encrypting the data. The decryptor needs to have the associated private key of the certificate used to decrypt the value. This method will set the protection descriptor `CERTIFICATE=CertBlob:$certBase64String`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>The thumbprint for a certificate stored inside `Cert:\CurrentUser\My` to use for encryption. Only the public key needs to be present to encrypt the value but the decryption process requires the associated private key to be present. This method will set the protection descriptor `CERTIFICATE=HashID:$CertificateThumbprint`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CurrentSid</maml:name> <maml:description> <maml:para>Adds the clause `SID=$UserSid` where `$UserSid` represents the current user's SecurityIdentifier. A secret protected by this value can be decrypted by this user on any machine in the domain.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</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="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The protection descriptor object generated by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Local</maml:name> <maml:description> <maml:para>Adds the `LOCAL` descriptor clause to either `User`, `Machine`, `Logon`. The `User` value protects the secret to just this user on the current host. The `Machine` value protects the secret to the current computer. The `Logon` value protects the secret to just this user's logon session. This is slightly different to `User` in that the same user logged on through another session will be unable to decrypt the secret.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Or</maml:name> <maml:description> <maml:para>Adds the new descriptor clause with an `OR` rather than an `AND`. How this is treated by DPAPI-NG depends on the existing clauses that have already been added.</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="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Sid</maml:name> <maml:description> <maml:para>Adds the `SID` descriptor clause to the SecurityIdentifier specified. The SecurityIdentifier can be the SID of a domain user or group. If a group SID is specified, any user who is a member of that group can decrypt the secret it applies to.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringOrAccount</command:parameterValue> <dev:type> <maml:name>StringOrAccount</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WebCredential</maml:name> <maml:description> <maml:para>The credential manager to protect the secret with. The string value is in the format `username,resource`, for example a web credential for `dpapi-ng.com` with the user `MyUser` would be `-WebCredential 'MyUser,dpapi-ng.com'`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>ProtectionDescriptor</maml:name> </dev:type> <maml:description> <maml:para>The ProtectionDescriptor object created by New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md).</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> </dev:type> <maml:description> <maml:para>The modified ProtectionDescriptor object with the new clause.</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 - Adds the Local user clause ------------</maml:title> <dev:code>PS C:\> $desc = New-DpapiNGDescriptor | Add-DpapiNGDescriptor -Local User PS C:\> Set-Secret -Vault MyVault -Name MySecret -Secret foo @desc</dev:code> <dev:remarks> <maml:para>Creates a new protection descriptor for `LOCAL=user` which will protect the secret for the current user. The descriptor is then used with `Set-Secret` to define how to protect the secret stored in the vault. It is important to use the descriptor output using the splat syntax when provided ith `Set-Secret`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------- Example 2 - Adds the SID specified --------------</maml:title> <dev:code>PS C:\> $desc = New-DpapiNGDescriptor | Add-DpapiNGDescriptor -CurrentSid PS C:\> ConvertTo-DpapiNGSecret secret -ProtectionDescriptor $desc</dev:code> <dev:remarks> <maml:para>Creates a DPAPI-NG secret that is protected by the current user. This secret can be decrypted on any host in the domain running under the same user.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---------------- Example 3 - Adds multiple SIDs ----------------</maml:title> <dev:code>PS C:\> $domainAdmins = [System.Security.Principal.NTAccount]'DOMAIN\Domain Admins' PS C:\> $desc = New-DpapiNGDescriptor | Add-DpapiNGDescriptor -CurrentSid | Add-DpapiNGDescriptor -Sid $domainAdmins PS C:\> ConvertTo-DpapiNGSecret secret -ProtectionDescriptor $desc</dev:code> <dev:remarks> <maml:para>Creates a DPAPI-NG secret that is protected by the current user when a `Domain Admins` member.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/SecretManagement.DpapiNG/blob/main/docs/en-US/Add-DpapiNGDescriptor.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>DPAPI NG Protection Descriptors</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/seccng/protection-descriptors</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_DpapiNGProtectionDescriptor</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </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>ConvertFrom-DpapiNGSecret</command:name> <command:verb>ConvertFrom</command:verb> <command:noun>DpapiNGSecret</command:noun> <maml:description> <maml:para>Decrypts a DPAPI-NG secret.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Decrypts a DPAPI-NG secret created by ConvertTo-DpapiNGSecret (./ConvertTo-DpapiNGSecret.md). The input data is a base64 encoded string of the raw DPAPI-NG blob. The output object is dependent on the `-As*` switch specified and defaults as a `SecureString`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The base64 encoded DPAPI-NG blob to decrypt.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsByteArray</maml:name> <maml:description> <maml:para>Outputs the decrypted value as a `byte[]` object.</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:syntaxItem> <maml:name>ConvertFrom-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The base64 encoded DPAPI-NG blob to decrypt.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsSecureString</maml:name> <maml:description> <maml:para>Outputs the decrypted value as a `SecureString`. This is the default output if no switch is specified.</maml:para> </maml:description> <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="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding to use when decoding the bytes to a `String` or `SecureString`. Defaults to UTF8 if no encoding is specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertFrom-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The base64 encoded DPAPI-NG blob to decrypt.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsString</maml:name> <maml:description> <maml:para>Outputs the decrypted value as a `String`.</maml:para> </maml:description> <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="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding to use when decoding the bytes to a `String` or `SecureString`. Defaults to UTF8 if no encoding is specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsByteArray</maml:name> <maml:description> <maml:para>Outputs the decrypted value as a `byte[]` object.</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="named" aliases="none"> <maml:name>AsSecureString</maml:name> <maml:description> <maml:para>Outputs the decrypted value as a `SecureString`. This is the default output if no switch is specified.</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="named" aliases="none"> <maml:name>AsString</maml:name> <maml:description> <maml:para>Outputs the decrypted value as a `String`.</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="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding to use when decoding the bytes to a `String` or `SecureString`. Defaults to UTF8 if no encoding is specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The base64 encoded DPAPI-NG blob to decrypt.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Byte[]</maml:name> </dev:type> <maml:description> <maml:para>The decrypted value as a `byte[]` when `-AsByteArray` is specified.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> </dev:type> <maml:description> <maml:para>The decrypted value as a `SecureString` when no `-As*` switch or `-AsSecureString` is specified.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The decrypted value as a `String` when `-AsString` is specified.</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 - Decrypts a DPAPI-NG secret ------------</maml:title> <dev:code>PS C:\> $secret = ConvertTo-DpapiNGSecret secret PS C:\> $secret | ConvertFrom-DpapiNGSecret</dev:code> <dev:remarks> <maml:para>Decrypts a DPAPI-NG encoded secret into a `SecureString`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 2 - Decrypts a DPAPI-NG secret to bytes -------</maml:title> <dev:code>PS C:\> $secret | ConvertFrom-DpapiNGSecret -AsByteArray</dev:code> <dev:remarks> <maml:para>Decrypts a DPAPI-NG encoded secret into a `byte[]`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3 - Decrypts a DPAPI-NG secret to a string with specific encoding</maml:title> <dev:code>PS C:\> $secret | ConvertFrom-DpapiNGSecret -AsString -Encoding windows-1252</dev:code> <dev:remarks> <maml:para>Decrypts a DPAPI-NG encoded secret into a `string` using the `windows-1252` encoding.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/SecretManagement.DpapiNG/blob/main/docs/en-US/ConvertFrom-DpapiNGSecret.md</maml:uri> </maml:navigationLink> </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>ConvertTo-DpapiNGSecret</command:name> <command:verb>ConvertTo</command:verb> <command:noun>DpapiNGSecret</command:noun> <maml:description> <maml:para>Encrypts data as a DPAPI-NG secret.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Encrypts the input data into a base64 encoded string. The encrypted data is protected using the protection descriptor specified. Use ConvertFrom-DpapiNGSecret (./ConvertFrom-DpapiNGSecret.md)to decrypt the secret data back into a usable object. By default the secret will be protected with the `LOCAL=user` protection descriptor which only allows the current user on the current host the ability to decrypt the secret.</maml:para> <maml:para>See about_DpapiNGProtectionDescriptor (./about_DpapiNGProtectionDescriptor.md)for more details.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The `X509Certificate2` to use when encrypting the data. The decryptor needs to have the associated private key of the certificate used to decrypt the value. This method will set the protection descriptor `CERTIFICATE=CertBlob:$certBase64String`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>The thumbprint for a certificate stored inside `Cert:\CurrentUser\My` to use for encryption. Only the public key needs to be present to encrypt the value but the decryption process requires the associated private key to be present. This method will set the protection descriptor `CERTIFICATE=HashID:$CertificateThumbprint`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CurrentSid</maml:name> <maml:description> <maml:para>Protects the secret with the current domain user's identity. The encrypted secret can be decrypted by this user on any other host in the domain. This is the equivalent of doing `-ProtectionDescriptor "SID=$([System.Security.Principal.WindowsIdentity]::GetCurrent().User)"`.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</maml:para> </maml:description> <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="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Local</maml:name> <maml:description> <maml:para>Protects the secret using the `LOCAL=machine`, `LOCAL=user`, or `LOCAL=logon` protection descriptor. The `User` value protects the secret to just this user on the current host and is the default value. The `Machine` value protects the secret to the current computer. The `Logon` value protects the secret to just this user's logon session. This is slightly different to `User` in that the same user logged on through another session will be unable to decrypt the secret.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>ProtectionDescriptor</maml:name> <maml:description> <maml:para>The protection descriptor string to use to protect the value. The New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md) and [Add-DpapiNGDescriptor](./Add-DpapiNGDescriptor.md)can be used to build the protection descriptor value. A string can also be provided here as the protection descriptor using the rules defined by DPAPI-NG.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringOrProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>StringOrProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Sid</maml:name> <maml:description> <maml:para>Allows only the domain user or domain group specified by this SID to be able to decrypt the DPAPI-NG secret. If a group SID is specified, any user who is a member of that group can decrypt the secret it applies to. The value can either by a SecurityIdentifier string in the format `S-1-...` or as a System.Security.Principal.NTAccount (https://learn.microsoft.com/en-us/dotnet/api/system.security.principal.ntaccount?view=net-8.0)object which will automatically be translated to a SID.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringOrAccount</command:parameterValue> <dev:type> <maml:name>StringOrAccount</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-DpapiNGSecret</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WebCredential</maml:name> <maml:description> <maml:para>The credential manager to protect the secret with. The string value is in the format `username,resource`, for example a web credential for `dpapi-ng.com` with the user `MyUser` would be `-WebCredential 'MyUser,dpapi-ng.com'`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</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="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The `X509Certificate2` to use when encrypting the data. The decryptor needs to have the associated private key of the certificate used to decrypt the value. This method will set the protection descriptor `CERTIFICATE=CertBlob:$certBase64String`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>The thumbprint for a certificate stored inside `Cert:\CurrentUser\My` to use for encryption. Only the public key needs to be present to encrypt the value but the decryption process requires the associated private key to be present. This method will set the protection descriptor `CERTIFICATE=HashID:$CertificateThumbprint`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CurrentSid</maml:name> <maml:description> <maml:para>Protects the secret with the current domain user's identity. The encrypted secret can be decrypted by this user on any other host in the domain. This is the equivalent of doing `-ProtectionDescriptor "SID=$([System.Security.Principal.WindowsIdentity]::GetCurrent().User)"`.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</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="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>The encoding used to encode the string into bytes before it is encrypted. The encoding default to `UTF-8` if not specified.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>+ `UTF8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>+ `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>+ `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>+ `OEM` - The value of `[System.Console]::OutputEncoding`</maml:para> <maml:para>+ `Unicode` - UTF-16-LE</maml:para> <maml:para>+ `UTF8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>+ `UTF8NoBom` - Same as Utf8</maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a BOM like `UTF8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The data to encrypt. The value can be on of the following types</maml:para> <maml:para>+ `String`</maml:para> <maml:para>+ `SecureString`</maml:para> <maml:para>+ `byte[]`</maml:para> <maml:para>When a `String` or `SecureString` is used, the `-Encoding` argument is used to convert the value to bytes before it is encrypted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringSecureStringOrByteArray[]</command:parameterValue> <dev:type> <maml:name>StringSecureStringOrByteArray[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Local</maml:name> <maml:description> <maml:para>Protects the secret using the `LOCAL=machine`, `LOCAL=user`, or `LOCAL=logon` protection descriptor. The `User` value protects the secret to just this user on the current host and is the default value. The `Machine` value protects the secret to the current computer. The `Logon` value protects the secret to just this user's logon session. This is slightly different to `User` in that the same user logged on through another session will be unable to decrypt the secret.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>ProtectionDescriptor</maml:name> <maml:description> <maml:para>The protection descriptor string to use to protect the value. The New-DpapiNGDescriptor (./New-DpapiNGDescriptor.md) and [Add-DpapiNGDescriptor](./Add-DpapiNGDescriptor.md)can be used to build the protection descriptor value. A string can also be provided here as the protection descriptor using the rules defined by DPAPI-NG.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringOrProtectionDescriptor</command:parameterValue> <dev:type> <maml:name>StringOrProtectionDescriptor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Sid</maml:name> <maml:description> <maml:para>Allows only the domain user or domain group specified by this SID to be able to decrypt the DPAPI-NG secret. If a group SID is specified, any user who is a member of that group can decrypt the secret it applies to. The value can either by a SecurityIdentifier string in the format `S-1-...` or as a System.Security.Principal.NTAccount (https://learn.microsoft.com/en-us/dotnet/api/system.security.principal.ntaccount?view=net-8.0)object which will automatically be translated to a SID.</maml:para> <maml:para>Using a `SID` protection descriptor requires the host to be joined to a domain with a forest level of 2012 or newer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StringOrAccount</command:parameterValue> <dev:type> <maml:name>StringOrAccount</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WebCredential</maml:name> <maml:description> <maml:para>The credential manager to protect the secret with. The string value is in the format `username,resource`, for example a web credential for `dpapi-ng.com` with the user `MyUser` would be `-WebCredential 'MyUser,dpapi-ng.com'`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>StringSecureStringOrByteArray</maml:name> </dev:type> <maml:description> <maml:para>The `-InputObject` to encrypt.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The encrypted DPAPI-NG blob as a base64 encoded string.</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 - Encrypt a string for the current domain user ---</maml:title> <dev:code>PS C:\> ConvertTo-DpapiNGSecret secret -CurrentSid</dev:code> <dev:remarks> <maml:para>Encrypts the string `secret` as a DPAPI-NG blob protected by the current domain user. The same user can decrypt the encrypted blob on any host in the domain.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Exapmle 2 - Encrypt bytes for the local machine -------</maml:title> <dev:code>PS C:\> $bytes = [System.IO.File]::ReadAllBytes($path) # Example using pipeline PS C:\> , $bytes | ConvertTo-DpapiNGSecret -Local Machine # Exapmle using parameters PS C:\> ConvertTo-DpapiNGSecret -InputObject $bytes -Local Machine</dev:code> <dev:remarks> <maml:para>Encrypts the provided bytes as a DPAPI-NG blob protected by the current local machine. The same machine can decrypt the encrypted blob.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--- Example 3 - Encrypt a secret for a specific domain group ---</maml:title> <dev:code>PS C:\> $da = [System.Security.Principal.NTAccount]'DOMAIN\Domain Admins' PS C:\> ConvertTo-DpapiNGSecret secret -Sid $da</dev:code> <dev:remarks> <maml:para>Encrypts the provided string as a DPAPI-NG blob protected by membership to the `Domain Admins` group. Any other member of that group will be able to decrypt that secret.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 4 - Encrypt a secret using a complex protection descriptor</maml:title> <dev:code>PS C:\> $da = [System.Security.Principal.NTAccount]'DOMAIN\Domain Admins' PS C:\> $desc = New-DpapiNGDescriptor | Add-DpapiNGDescriptor -CurrentSid | Add-DpapiNGDescriptor -Sid $da -Or PS C:\> ConvertTo-DpapiNGSecret secret -ProtectionDescriptor $desc</dev:code> <dev:remarks> <maml:para>Builds a more complex protection descriptor that allows a member of the `Domain Admins` group or the current domain user the ability to decrypt the DPAPI-NG secret. It is also possible to provide a string to `-ProtectionDescriptor` if crafting it manually.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/SecretManagement.DpapiNG/blob/main/docs/en-US/ConvertTo-DpapiNGSecret.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>DPAPI NG Protection Descriptors</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/seccng/protection-descriptors</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_DpapiNGProtectionDescriptor</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </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-DpapiNGDescriptor</command:name> <command:verb>New</command:verb> <command:noun>DpapiNGDescriptor</command:noun> <maml:description> <maml:para>Creates a DPAPI-NG protection descriptor used to encrypt data with DPAPI-NG.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This is used to create the DPAPI-NG protection descriptor string. Use with Add-DpapiNGDescriptor (./Add-DpapiNGDescriptor.md)to add descriptor elements to the protection string.</maml:para> <maml:para>See about_DpapiNGProtectionDescriptor (./about_DpapiNGProtectionDescriptor.md)for more details.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-DpapiNGDescriptor</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>ProtectionDescriptor</maml:name> </dev:type> <maml:description> <maml:para>The ProtectionDescriptor object that can be piped to Add-DpapiNGDescriptor (./Add-DpapiNGDescriptor.md).</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>PS C:\> $desc = New-DpapiNGDescriptor | Add-DpapiNGDescriptor -Local User PS C:\> Set-Secret -Vault MyVault -Name MySecret -Secret foo @desc</dev:code> <dev:remarks> <maml:para>Creates a new protection descriptor for `LOCAL=user` which will protect the secret for the current user. The descriptor is then used with `Set-Secret` to define how to protect the secret stored in the vault. It is important to use the descriptor output using the splat syntax when provided ith `Set-Secret`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/SecretManagement.DpapiNG/blob/main/docs/en-US/New-DpapiNGDescriptor.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>DPAPI NG Protection Descriptors</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/seccng/protection-descriptors</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_DpapiNGProtectionDescriptor</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |