diff --git a/astro.config.mjs b/astro.config.mjs index c0dd7476ab..653774877e 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 new file mode 100644 index 0000000000..2174206345 --- /dev/null +++ b/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] [[-Checksum] ] [[-ChecksumType] ] [[-Url] ] + [-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. + +## 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 + + + + + + + + diff --git a/src/content/docs/en-us/create/cmdlets/index.mdx b/src/content/docs/en-us/create/cmdlets/index.mdx index 437840774a..a770302c06 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 8159f76567..0000000000 --- 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 ae11cedc5c..e6ad312819 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) * - * + * * * *