(#1074) Add docs for Assert-ValidChecksum

astro.config.mjs

@@ -209,8 +209,8 @@ export default defineConfig({
         '/docs/CreatePackages': '/en-us/create/create-packages/',
         '/docs/helpers-format-file-size': '/en-us/create/functions/format-filesize/',
         '/docs/helpersformatfilesize': '/en-us/create/functions/format-filesize/',
-        '/docs/helpers-get-checksum-valid': '/en-us/create/functions/get-checksumvalid/',
-        '/docs/helpersgetchecksumvalid': '/en-us/create/functions/get-checksumvalid/',
+        '/docs/helpers-get-checksum-valid': '/en-us/create/cmdlets/assert-validchecksum',
+        '/docs/helpersgetchecksumvalid': '/en-us/create/cmdlets/assert-validchecksum',
         '/docs/helpers-get-chocolatey-config-value': '/en-us/create/functions/get-chocolateyconfigvalue/',
         '/docs/helpersgetchocolateyconfigvalue': '/en-us/create/functions/get-chocolateyconfigvalue/',
         '/docs/helpers-get-chocolatey-path': '/en-us/create/functions/get-chocolateypath/',
@@ -347,6 +347,7 @@ export default defineConfig({
         '/docs/roadmap': '/en-us/roadmap/',
         '/docs/troubleshooting': '/en-us/troubleshooting/',
         '/docs/why': '/en-us/why/',
+        '/en-us/create/functions/get-checksumvalid/': '/en-us/create/cmdlets/assert-validchecksum',
         '/en-us/create/functions/get-environmentvariable': '/en-us/create/cmdlets/get-environmentvariable/',
         '/en-us/create/functions/get-environmentvariablenames': '/en-us/create/cmdlets/get-environmentvariablenames/',
         '/en-us/create/functions/install-chocolateypath': '/en-us/create/cmdlets/install-chocolateyPath/',

src/content/docs/en-us/create/cmdlets/Assert-ValidChecksum.mdx

@@ -0,0 +1,164 @@
+---
+description: Information on Assert-ValidChecksum cmdlet
+external help file: Chocolatey.PowerShell.dll-Help.xml
+Module Name: Chocolatey.PowerShell
+online version: https://docs.chocolatey.org/en-us/create/cmdlets/assert-validchecksum
+order: 20
+schema: 2.0.0
+title: Assert-ValidChecksum
+xref: assert-validchecksum
+---
+import Xref from '@components/Xref.astro';
+
+# Assert-ValidChecksum
+
+## SYNOPSIS
+Checks a file's checksum versus a passed checksum and checksum type.
+
+## SYNTAX
+
+```
+Assert-ValidChecksum [-Path] <String> [[-Checksum] <String>] [[-ChecksumType] <ChecksumType>] [[-Url] <String>]
+ [-IgnoredArguments <Object[]>] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Makes a determination if a file meets an expected checksum signature.
+This function is usually used when comparing a file that is downloaded from an official distribution point.
+If the checksum fails to match the expected output, this function throws an error.
+
+Checksums have been used for years as a means of verification. A checksum hash is a unique value or signature that corresponds to the contents of a file.
+File names and extensions can be altered without changing the checksum signature.
+However if you changed the contents of the file, even one character, the checksum will be different.
+
+Checksums are used to provide as a means of cryptographically ensuring the contents of a file have not been changed.
+While some cryptographic algorithms, including MD5 and SHA1, are no longer considered secure against attack, the goal of a checksum algorithm is to make it extremely difficult (near impossible with better algorithms) to alter the contents of a file (whether by accident or for malicious reasons) and still result in the same checksum signature.
+
+When verifying a checksum using a secure algorithm, if the checksum matches the expected signature, the contents of the file are identical to what is expected.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+PS C:\> Assert-ValidChecksum -Path $fileFullPath -Checksum $checksum -ChecksumType $checksumType
+```
+
+Calculates the `$checksumType` checksum of the file at `$fileFullPath` and compares it to the provided `$checksum` value.
+If the checksums do not match, or the `checksum.exe` is missing, this will throw an error.
+
+## PARAMETERS
+
+### -Checksum
+The checksum value that the file is expected to match.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ChecksumType
+The type of checksum algorithm to use.
+
+```yaml
+Type: ChecksumType
+Parameter Sets: (All)
+Aliases:
+Accepted values: Md5, Sha1, Sha256, Sha512
+
+Required: False
+Position: 2
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -IgnoredArguments
+Allows splatting with arguments that do not apply. Do not use directly.
+
+```yaml
+Type: Object[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Path
+The path to the file to verify the checksum for.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: File, FilePath
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Url
+The original URL that the file was downloaded from, if any.
+This is primarily for internal use, and will only matter if certain Chocolatey CLI features are enabled and there is no `-Checksum` value provided.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: OriginalUrl
+
+Required: False
+Position: 3
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+This uses the checksum.exe tool available separately at https://community.chocolatey.org/packages/checksum.
+
+Chocolatey CLI options that affect checksum verification:
+
+- `--ignore-checksums` - skips checksumming
+- `--allow-empty-checksums` - skips checksumming when the package is missing a checksum
+- `--allow-empty-checksums-secure` - skips checksumming when the package is missing a checksum for secure (HTTPS) locations
+- `--require-checksums` - requires checksums for both non-secure and secure locations
+- `--download-checksum`, `--download-checksum-type` - allows user to pass their own checksums
+- `--download-checksum-x64`, `--download-checksum-type-x64` - allows user to pass their own checksums
+
+Chocolatey CLI features that affect checksum verification:
+
+- `checksumFiles` - when turned off, skips checksumming
+- `allowEmptyChecksums` - when turned on, skips checksumming when the package is missing a checksum
+- `allowEmptyChecksumsSecure` - when turned on, skips checksumming when the package is missing a checksum for secure (HTTPS) locations
+
+This command is also aliased to `Get-ChecksumValid` for compatibility with packages designed for Chocolatey CLI v2.x and earlier.
+
+## RELATED LINKS
+
+<Xref title="Get-ChocolateyWebFile" value="get-chocolateywebfile" classes="mb-3 d-block" />
+
+<Xref title="Install-ChocolateyPackage" value="install-chocolateypackage" classes="mb-3 d-block" />
+
+<Xref title="Cmdlet Reference" value="powershell-cmdlet-reference" classes="mb-3 d-block" />
+
+<Xref title="Function Reference" value="powershell-reference" />

src/content/docs/en-us/create/cmdlets/index.mdx

@@ -21,6 +21,7 @@ Keep in mind Chocolatey's automation scripts are just PowerShell, so you can do
 
 ## Complete List (alphabetical order)
 
+ * <Xref title='Assert-ValidChecksum' value='assert-validchecksum' />
  * <Xref title="Get-EnvironmentVariable" value="get-environmentvariable" />
  * <Xref title="Get-EnvironmentVariableNames" value="get-environmentvariablenames" />
  * <Xref title="Install-ChocolateyPath" value="get-environmentvariable" />

src/content/docs/en-us/create/functions/index.mdx

@@ -64,7 +64,7 @@ These are the functions from above as one list.
 ## Complete List (alphabetical order)
 
  * <Xref title='Format-FileSize' value='format-filesize' />
- * <Xref title='Get-ChecksumValid' value='get-checksumvalid' />
+ * <Xref title='Assert-ValidChecksum' value='assert-validchecksum' />
  * <Xref title='Get-ChocolateyConfigValue' value='get-chocolateyconfigvalue' />
  * <Xref title='Get-ChocolateyPath' value='get-chocolateypath' />
  * <Xref title='Get-ChocolateyUnzip' value='get-chocolateyunzip' />