en-US/about_PSGemini.help.txt
|
TOPIC
about_psgemini SHORT DESCRIPTION Get resources with the Gemini protocol. LONG DESCRIPTION PSGemini is a PowerShell module that was designed to access, view, download, and interact with resources available over the Gemini protocol. Made to be "somewhere between Gopher and HTTP", Gemini is growing in popularity. It's time it had a PowerShell module. This module has a few cmdlets, but the biggest one is Invoke-GeminiRequest. Modeled after Invoke-WebRequest, it can be used similarly. The syntax and output are similar. Certificate Trust While the Gemini protocol requires TLS 1.2 or newer, it eschews the typical CA-based certificate validation with a TOFU (trust on first use) model. To keep track of this, PSGemini saves found certificates to a file. That file is saved at ${env:PSGeminiTOFUPath}. If that is not defined, it defaults to "${env:HOME}/.PSGemini_known_hosts.csv" While strongly discouraged, if you've managed to find this conceptual help, you might be the type who wants to mess with the trust store. You can do so by using one of these cmdlets: - Get-PSGeminiKnownCertificates - Add-PSGeminiKnownCertificate - Remove-PSGeminiKnownCertificate Even more strongly discouraged: you may open the file in a text editor, or Excel, LibreOffice Calc, or your favorite CSV editor. Aliases (or, Why Not `igr`?) You can use the aliases `Invoke-GemRequest` or `igemr`. (Why not `igr`? That's already used by my other module, PSGopher.) Client Certificates Client certificates are supported. Use the `-Certificate` parameter to specify one. This has not been throughly tested. FavIcons Why not have a little fun? Someone made a draft RFC to bring something like favicons to Gemini. In the spirit of the protocol, we're not going to make additional requests, so this is disabled by default. To request a resource's favicon, as well as the regular content or file, pass the -FavIcon parameter to Invoke-GeminiRequest. TLS 1.3 Support This cmdlet supports TLS 1.3. However, there may be issues using it with PowerShell 7 on some platforms. The Invoke-GeminiRequest cmdlet will make a best effort to use TLS 1.3 before falling back to TLS 1.2. Per the spec, no older protocols may or will be tried. EXAMPLES EXAMPLE 1: ACCESS RESOURCES PS> Invoke-GeminiRequest gemini://gemini.circumlunar.space StatusCode : 20 StatusDescription : text/gemini Content : # Project Gemini ## Overview Gemini is a new internet protocol which: * Is heavier than gopher * Is lighter than the web * Will not replace either * Strives for maximum power to weight ratio * Takes user privacy very seriously […] EXAMPLE 2: DOWNLOAD RESOURCES PS> Invoke-GeminiRequest gemini://colincogle.name/pgp/pgp.txt ` > -OutFile pgp.txt PS> Get-Item pgp.txt Directory: /Users/colin UnixMode User Group LastWriteTime Size Name -------- ---- ----- ------------- ---- ---- -rw-r--r-- colin wheel 2/8/2022 08:05 5218 pgp.txt NOTE The official Gemini protocol specification eschews the traditional CA-based certificate validation with a simple TOFU (trust on first use) model. To keep track of this, PSGemini saves found certificates to a file. That file is saved at $env:PSGeminiTOFUPath. If that is not defined, it defaults to ${env:HOME}/.PSGemini_known_hosts.csv. You may change the storage location simply by defining the former environment variable. TROUBLESHOOTING NOTE Client certificates have not been fully tested. If you encounter any issues, come complain on GitHub. The link follows. SEE ALSO Issues? Rants? Raves? Find this module on GitHub: => https://github.com/rhymeswithmogul/PSGemini If you'd like to know more about Gemini, check out its unofficial official site at either - https://gemini.circumlunar.space, or - gemini://gemini.circumlunar.space The Gemini protocol specification is here: => https://gemini.circumlunar.space/docs/specification.gmi If you like Web/WWW/HTTP alternatives, why not check out my other module: - PSGopher: https://github.com/rhymeswithmogul/PSGopher KEYWORDS Gemini, Gemlog, Gemblog, Geminispace, Gemtext, SSL, TLS, PowerShell Core |