en-US/PSPasswordGenerator-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>New-RandomPassword</command:name> <command:verb>New</command:verb> <command:noun>RandomPassword</command:noun> <maml:description> <maml:para>Creates a random password.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This cmdlet creates a random password with the specified parameters. You can generate passwords with any length you want, and include or restrict characters depending on what constrains your password must abide by.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-RandomPassword</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsPlainText</maml:name> <maml:Description> <maml:para>By default, the password is returned as a [System.Security.SecureString]. Specify this parameter to return it as a regular, cleartext [System.String], where it can simply be printed to the output stream, saved into a varible, or copied and pasted in an interactive session.</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="Count, Size"> <maml:name>Length</maml:name> <maml:Description> <maml:para>The generated password will always be of the specified length. You can specify any length between 1 and 4,294,967,295 characters inclusive. Entropy tends to increases along with the value of this parameter.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">UInt32</command:parameterValue> <dev:type> <maml:name>UInt32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>16</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoSymbols</maml:name> <maml:Description> <maml:para>If this switch is specified, the resulting password will only contain letters and numbers. This might be useful for services that restrict or prohibit the use of special characters, or for situations where special characters may not be escaped correctly. Entropy decreases when this parameter is specified; this can be counteracted by increasing the -Length parameter.</maml:para> <maml:para>Using this parameter causes the -UseExtendedAscii parameter to have no effect.</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>StartWithLetter</maml:name> <maml:Description> <maml:para>If this switch is specified, the first character of the password will be either an uppercase or lowercase letter. This slightly decreases entropy, but decreases it further as the password length increases.</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>UseAmbiguousCharacters</maml:name> <maml:Description> <maml:para>By default, ambigious characters such as '1', 'I', 'l', and '|'; as well as '0' and 'O'; will not be used, so that the password is a little easier for a human to read and type. If you would like these similar-looking characters to be used in the password, specify this switch, and they will be returned to the character pool. Specifying this switch slightly increases entropy.</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>UseExtendedAscii</maml:name> <maml:Description> <maml:para>By default, the extended ASCII character set is not used. Specify this switch to make your passwords more random and contain far more entropy. However, you will no longer be able to type them on a standard keyboard. In addition, some services may not permit these special characters. However, specifying this switch greatly increases entropy, as the character pool is roughly doubled.</maml:para> <maml:para>If the -NoSymbols parameter is specified, then this parameter has no effect.</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="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsPlainText</maml:name> <maml:Description> <maml:para>By default, the password is returned as a [System.Security.SecureString]. Specify this parameter to return it as a regular, cleartext [System.String], where it can simply be printed to the output stream, saved into a varible, or copied and pasted in an interactive session.</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="Count, Size"> <maml:name>Length</maml:name> <maml:Description> <maml:para>The generated password will always be of the specified length. You can specify any length between 1 and 4,294,967,295 characters inclusive. Entropy tends to increases along with the value of this parameter.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">UInt32</command:parameterValue> <dev:type> <maml:name>UInt32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>16</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoSymbols</maml:name> <maml:Description> <maml:para>If this switch is specified, the resulting password will only contain letters and numbers. This might be useful for services that restrict or prohibit the use of special characters, or for situations where special characters may not be escaped correctly. Entropy decreases when this parameter is specified; this can be counteracted by increasing the -Length parameter.</maml:para> <maml:para>Using this parameter causes the -UseExtendedAscii parameter to have no effect.</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>StartWithLetter</maml:name> <maml:Description> <maml:para>If this switch is specified, the first character of the password will be either an uppercase or lowercase letter. This slightly decreases entropy, but decreases it further as the password length increases.</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>UseAmbiguousCharacters</maml:name> <maml:Description> <maml:para>By default, ambigious characters such as '1', 'I', 'l', and '|'; as well as '0' and 'O'; will not be used, so that the password is a little easier for a human to read and type. If you would like these similar-looking characters to be used in the password, specify this switch, and they will be returned to the character pool. Specifying this switch slightly increases entropy.</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>UseExtendedAscii</maml:name> <maml:Description> <maml:para>By default, the extended ASCII character set is not used. Specify this switch to make your passwords more random and contain far more entropy. However, you will no longer be able to type them on a standard keyboard. In addition, some services may not permit these special characters. However, specifying this switch greatly increases entropy, as the character pool is roughly doubled.</maml:para> <maml:para>If the -NoSymbols parameter is specified, then this parameter has no effect.</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:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet does not accept pipeline input.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> </dev:type> <maml:description> <maml:para>If the -AsPlainText parameter is not specified.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>If the -AsPlainText parameter is specified.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This cmdlet can generate passwords with very high entropy, but they might be longer or stronger than your service allows. For example, this cmdlet could generate a password with 4.2 billion characters, but Microsoft 365 passwords are limited to 256 characters. Make good passwords, but be aware of your service's limits.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> $secureStr = New-RandomPassword -Length 32</dev:code> <dev:remarks> <maml:para>Generates a 32-character password and saves it as a SecureString object. This can be used in PowerShell scripts. For one example, run Get-Help about_PSPasswordGenerator.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 2 --------------------------</maml:title> <dev:code>PS C:\> New-RandomPassword -AsPlainText -Length 16 \#aT*fAg]u5$):%a</dev:code> <dev:remarks> <maml:para>Generates a 16-character password and prints it to the output stream. You can then copy and paste it for use outside of PowerShell, or pipe it to a command such as Out-File to store it (probably insecurely).</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 3 --------------------------</maml:title> <dev:code>PS C:\> $svcAccountPassword = New-RandomPassword -Length 240 -UseAmbigiousCharacters -UseExtendedAscii</dev:code> <dev:remarks> <maml:para>Generates a 240-character password that can be as random as possible. This is good practice for making service accounts in Active Directory Domain Services, where a human will never need to type the password by hand.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/rhymeswithmogul/PSPasswordGenerator/blob/main/man/en-US/New-RandomPassword.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_PSPasswordGenerator</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |