From a1935513a5b58b794b73c44587e2555d60eb2b3b Mon Sep 17 00:00:00 2001 From: Rain Sallow Date: Fri, 4 Oct 2024 14:59:38 -0400 Subject: [PATCH] (#1074) Add documentation for Assert-ValidChecksum --- astro.config.mjs | 5 +- .../create/cmdlets/Assert-ValidChecksum.mdx | 84 ++++++---- .../docs/en-us/create/cmdlets/index.mdx | 1 + .../create/functions/get-checksumvalid.mdx | 156 ------------------ .../docs/en-us/create/functions/index.mdx | 2 +- 5 files changed, 60 insertions(+), 188 deletions(-) delete mode 100644 src/content/docs/en-us/create/functions/get-checksumvalid.mdx diff --git a/astro.config.mjs b/astro.config.mjs index c0dd7476ab3..653774877e5 100644 --- a/astro.config.mjs +++ b/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/', diff --git a/src/content/docs/en-us/create/cmdlets/Assert-ValidChecksum.mdx b/src/content/docs/en-us/create/cmdlets/Assert-ValidChecksum.mdx index 395429f0719..21742063452 100644 --- a/src/content/docs/en-us/create/cmdlets/Assert-ValidChecksum.mdx +++ b/src/content/docs/en-us/create/cmdlets/Assert-ValidChecksum.mdx @@ -1,39 +1,56 @@ --- +description: Information on Assert-ValidChecksum cmdlet external help file: Chocolatey.PowerShell.dll-Help.xml Module Name: Chocolatey.PowerShell -online version: +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 -{{ Fill in the Synopsis }} +Checks a file's checksum versus a passed checksum and checksum type. ## SYNTAX ``` Assert-ValidChecksum [-Path] [[-Checksum] ] [[-ChecksumType] ] [[-Url] ] - [-IgnoredArguments ] [-ProgressAction ] [] + [-IgnoredArguments ] [] ``` ## DESCRIPTION -{{ Fill in the 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:\> {{ Add example code here }} +PS C:\> Assert-ValidChecksum -Path $fileFullPath -Checksum $checksum -ChecksumType $checksumType ``` -{{ Add example description here }} +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 -{{ Fill Checksum Description }} +The checksum value that the file is expected to match. ```yaml Type: String @@ -48,7 +65,7 @@ Accept wildcard characters: False ``` ### -ChecksumType -{{ Fill ChecksumType Description }} +The type of checksum algorithm to use. ```yaml Type: ChecksumType @@ -64,7 +81,7 @@ Accept wildcard characters: False ``` ### -IgnoredArguments -{{ Fill IgnoredArguments Description }} +Allows splatting with arguments that do not apply. Do not use directly. ```yaml Type: Object[] @@ -79,7 +96,7 @@ Accept wildcard characters: False ``` ### -Path -{{ Fill Path Description }} +The path to the file to verify the checksum for. ```yaml Type: String @@ -94,7 +111,8 @@ Accept wildcard characters: False ``` ### -Url -{{ Fill Url Description }} +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 @@ -108,31 +126,39 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -ProgressAction -{{ Fill ProgressAction Description }} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -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 -### System.Object[] - ## OUTPUTS -### System.Object ## 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 + + + + + + + + diff --git a/src/content/docs/en-us/create/cmdlets/index.mdx b/src/content/docs/en-us/create/cmdlets/index.mdx index 437840774a1..a770302c066 100644 --- a/src/content/docs/en-us/create/cmdlets/index.mdx +++ b/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) + * * * * diff --git a/src/content/docs/en-us/create/functions/get-checksumvalid.mdx b/src/content/docs/en-us/create/functions/get-checksumvalid.mdx deleted file mode 100644 index 8159f765671..00000000000 --- a/src/content/docs/en-us/create/functions/get-checksumvalid.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -order: 20 -xref: get-checksumvalid -title: Get-ChecksumValid -description: Information on Get-ChecksumValid function ---- -import Xref from '@components/Xref.astro'; - -# Get-ChecksumValid - -{/* This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChecksumValid.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). */} - -Checks a file's checksum versus a passed checksum and checksum type. - -## Syntax - -~~~powershell -Get-ChecksumValid ` - -File ` - [-Checksum ] ` - [-ChecksumType ] ` - [-OriginalUrl ] ` - [-IgnoredArguments ] [] -~~~ - -## 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. - -## Notes - -This uses the checksum.exe tool available separately at -https://community.chocolatey.org/packages/checksum. - -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 - -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 - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell -Get-ChecksumValid -File $fileFullPath -CheckSum $checksum -ChecksumType $checksumType - -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -File <String> -Property | Value ----------------------- | ----- -Aliases | -Required? | true -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Checksum [<String>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -ChecksumType [<String>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | md5 -Accept Pipeline Input? | false - -### -OriginalUrl [<String>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * - * - - - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ChecksumValid -Full`. - -View the source for [Get-ChecksumValid](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChecksumValid.ps1) diff --git a/src/content/docs/en-us/create/functions/index.mdx b/src/content/docs/en-us/create/functions/index.mdx index ae11cedc5c7..e6ad3128193 100644 --- a/src/content/docs/en-us/create/functions/index.mdx +++ b/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) * - * + * * * *