net10.0/en-US/SecureFetch.Shell.b646fad3644308f2.dll-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"><command:details><command:name>Invoke-SecureFetch</command:name><command:verb>Invoke</command:verb><command:noun>SecureFetch</command:noun><maml:description><maml:para>Sends a request to an https:// address with TLS from rustls inside the module and writes the response with what the handshake negotiated.</maml:para></maml:description></command:details><maml:description><maml:para>The request is a GET unless -Method names another method. -Headers adds header fields and may replace the User-Agent, Accept and Accept-Encoding fields the cmdlet sends; -Body sends a string, as UTF-8, or a byte array, as it is, framed by Content-Length, with -ContentType saying what it is. A header or body that cannot be sent is refused before any connection is made.</maml:para><maml:para>The TLS stack is the module's own, not the host's, and offers the X25519MLKEM768 hybrid post-quantum key exchange first; with -RequirePostQuantum it offers that and TLS 1.3 alone, so a server without them is refused during the handshake. The request is HTTP/1.1 and asks the server to close the connection after the response; with -KeepAlive the connection is kept instead and reused for the next request to the same host and port through the same proxy, whether a redirect or the next piped address. The body is read to the end its Content-Length or chunked framing gives, and chunked bodies are decoded, trailer fields included. It asks for gzip, deflate, br and zstd bodies and decodes them, up to -MaximumDecodedBytes of decoded bytes; -NoCompression asks for the identity encoding alone. A response to HEAD carries no body. A response whose status is 4xx or 5xx is an error record that carries the response, unless -SkipHttpErrorCheck is given; an address that cannot be sent, a connection or handshake that fails, and a response that cannot be read are error records too. A stop, such as Ctrl+C, ends a request at once, whatever it is waiting on.</maml:para><maml:para>A 301, 302, 303, 307 or 308 response with a Location is followed, up to -MaximumRedirection redirects, to https:// addresses only; a 303, and a 301 or 302 answering a POST, is followed with a GET without the body. Authorization and Cookie fields are not sent on to another host or port. The response written names the address it came from in FinalUri and each address followed in Redirects.</maml:para><maml:para>With -OutFile the body is written to that file as it arrives instead of being held in memory, through a temporary file that replaces it only once the whole body has arrived, and nothing is written to the pipeline unless -PassThru is given.</maml:para><maml:para>With -Proxy the request goes through that HTTP proxy, tunneled with CONNECT so TLS still runs between this module and the server; without it, the proxy the system names for the address is used, unless -NoProxy is given.</maml:para><maml:para>Server certificates are verified by rustls against the bundled Mozilla roots and, on Windows, the roots in the Windows certificate store, unless -TrustedRoots names others; -RootCertificate adds roots of the caller's own.</maml:para></maml:description><command:syntax><command:syntaxItem><maml:name>Invoke-SecureFetch</maml:name><command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="0" aliases=""><maml:name>Uri</maml:name><maml:description><maml:para>An https:// address.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Method</maml:name><maml:description><maml:para>The request method: GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS, in any case, sent upper-cased; GET when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Headers</maml:name><maml:description><maml:para>Header fields to send, as a dictionary of names and values; a value is a string, or an array of strings sent as one field line each. An entry named User-Agent, Accept or Accept-Encoding replaces the one the cmdlet sends.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">System.Collections.IDictionary</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Body</maml:name><maml:description><maml:para>The request body: a string, sent as UTF-8, or a byte array, sent as it is. Sent with every method that is given it, framed by Content-Length.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">object</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>ContentType</maml:name><maml:description><maml:para>The body's Content-Type, sent as given. Without it a string body is sent as text/plain; charset=utf-8 and a byte array as application/octet-stream.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>TimeoutSeconds</maml:name><maml:description><maml:para>Seconds to wait for name resolution, for the connection and for each read or write; 30 when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">ulong</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>SkipHttpErrorCheck</maml:name><maml:description><maml:para>Writes a response whose status is 4xx or 5xx as a response rather than raising it as an error record.</maml:para></maml:description></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>RequirePostQuantum</maml:name><maml:description><maml:para>Offers only TLS 1.3 with the X25519MLKEM768 key exchange, so a server that cannot negotiate it fails the handshake, before any request is sent, as SecureFetchNotPostQuantum.</maml:para></maml:description></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>KeepAlive</maml:name><maml:description><maml:para>Keeps each connection open after its response and reuses it for the next request to the same host and port through the same proxy, whether a redirect or the next piped address. When the server has closed the kept connection, a GET, HEAD, OPTIONS, PUT or DELETE is sent once more on a new connection, and a POST or PATCH fails as SecureFetchConnection rather than being sent twice.</maml:para></maml:description></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>NoCompression</maml:name><maml:description><maml:para>Asks for the body in the identity encoding only, instead of gzip, deflate, br or zstd.</maml:para></maml:description></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>MaximumDecodedBytes</maml:name><maml:description><maml:para>The most bytes a body sent with a content coding may decode to; past it the request fails as SecureFetchTooLarge. 256 MiB when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">ulong</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>MaximumRedirection</maml:name><maml:description><maml:para>The most redirects to follow, 0 to 50; past it the request fails as SecureFetchTooManyRedirects. 0 writes a redirect as the response it is. 5 when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">int</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>OutFile</maml:name><maml:description><maml:para>A file to write the body to as it arrives, instead of holding it in memory; a relative path is relative to the current location. The body goes to a temporary file beside it, which replaces the file only once the whole body has arrived. Nothing is written to the pipeline unless -PassThru is given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>PassThru</maml:name><maml:description><maml:para>With -OutFile, also writes the response, its Content and ContentBytes empty.</maml:para></maml:description></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Proxy</maml:name><maml:description><maml:para>An HTTP proxy to reach the server through, as http://host:port. The request is tunneled with CONNECT, so TLS and its key exchange run between this module and the server. Without it, the proxy the system names for the address is used, unless -NoProxy is given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>ProxyCredential</maml:name><maml:description><maml:para>The user name and password for the proxy, sent as Basic Proxy-Authorization.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">System.Management.Automation.PSCredential</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>NoProxy</maml:name><maml:description><maml:para>Connects to the server directly rather than through the proxy the system names for it.</maml:para></maml:description></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>TrustedRoots</maml:name><maml:description><maml:para>Where the roots a server's certificate must chain to come from: Bundled, the Mozilla roots compiled into the module; Windows, the roots in the current user's Root store (Cert:\CurrentUser\Root), which also shows the machine's; None, neither. When not given: Bundled and Windows on Windows, Bundled on a system without a Windows certificate store.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string[]</command:parameterValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>RootCertificate</maml:name><maml:description><maml:para>Certificates to trust as roots besides those -TrustedRoots names, as X509Certificate2 objects, such as those in the Cert: drive or one read with [X509Certificate2]::new('ca.cer').</maml:para></maml:description><command:parameterValue required="true" variableLength="false">System.Security.Cryptography.X509Certificates.X509Certificate2[]</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="0" aliases=""><maml:name>Uri</maml:name><maml:description><maml:para>An https:// address.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue><dev:type><maml:name>string</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Method</maml:name><maml:description><maml:para>The request method: GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS, in any case, sent upper-cased; GET when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue><dev:type><maml:name>string</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Headers</maml:name><maml:description><maml:para>Header fields to send, as a dictionary of names and values; a value is a string, or an array of strings sent as one field line each. An entry named User-Agent, Accept or Accept-Encoding replaces the one the cmdlet sends.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">System.Collections.IDictionary</command:parameterValue><dev:type><maml:name>System.Collections.IDictionary</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Body</maml:name><maml:description><maml:para>The request body: a string, sent as UTF-8, or a byte array, sent as it is. Sent with every method that is given it, framed by Content-Length.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">object</command:parameterValue><dev:type><maml:name>object</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>ContentType</maml:name><maml:description><maml:para>The body's Content-Type, sent as given. Without it a string body is sent as text/plain; charset=utf-8 and a byte array as application/octet-stream.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue><dev:type><maml:name>string</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>TimeoutSeconds</maml:name><maml:description><maml:para>Seconds to wait for name resolution, for the connection and for each read or write; 30 when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">ulong</command:parameterValue><dev:type><maml:name>ulong</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>SkipHttpErrorCheck</maml:name><maml:description><maml:para>Writes a response whose status is 4xx or 5xx as a response rather than raising it as an error record.</maml:para></maml:description><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>RequirePostQuantum</maml:name><maml:description><maml:para>Offers only TLS 1.3 with the X25519MLKEM768 key exchange, so a server that cannot negotiate it fails the handshake, before any request is sent, as SecureFetchNotPostQuantum.</maml:para></maml:description><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>KeepAlive</maml:name><maml:description><maml:para>Keeps each connection open after its response and reuses it for the next request to the same host and port through the same proxy, whether a redirect or the next piped address. When the server has closed the kept connection, a GET, HEAD, OPTIONS, PUT or DELETE is sent once more on a new connection, and a POST or PATCH fails as SecureFetchConnection rather than being sent twice.</maml:para></maml:description><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>NoCompression</maml:name><maml:description><maml:para>Asks for the body in the identity encoding only, instead of gzip, deflate, br or zstd.</maml:para></maml:description><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>MaximumDecodedBytes</maml:name><maml:description><maml:para>The most bytes a body sent with a content coding may decode to; past it the request fails as SecureFetchTooLarge. 256 MiB when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">ulong</command:parameterValue><dev:type><maml:name>ulong</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>MaximumRedirection</maml:name><maml:description><maml:para>The most redirects to follow, 0 to 50; past it the request fails as SecureFetchTooManyRedirects. 0 writes a redirect as the response it is. 5 when not given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">int</command:parameterValue><dev:type><maml:name>int</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>OutFile</maml:name><maml:description><maml:para>A file to write the body to as it arrives, instead of holding it in memory; a relative path is relative to the current location. The body goes to a temporary file beside it, which replaces the file only once the whole body has arrived. Nothing is written to the pipeline unless -PassThru is given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue><dev:type><maml:name>string</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>PassThru</maml:name><maml:description><maml:para>With -OutFile, also writes the response, its Content and ContentBytes empty.</maml:para></maml:description><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>Proxy</maml:name><maml:description><maml:para>An HTTP proxy to reach the server through, as http://host:port. The request is tunneled with CONNECT, so TLS and its key exchange run between this module and the server. Without it, the proxy the system names for the address is used, unless -NoProxy is given.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string</command:parameterValue><dev:type><maml:name>string</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>ProxyCredential</maml:name><maml:description><maml:para>The user name and password for the proxy, sent as Basic Proxy-Authorization.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">System.Management.Automation.PSCredential</command:parameterValue><dev:type><maml:name>System.Management.Automation.PSCredential</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>NoProxy</maml:name><maml:description><maml:para>Connects to the server directly rather than through the proxy the system names for it.</maml:para></maml:description><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>TrustedRoots</maml:name><maml:description><maml:para>Where the roots a server's certificate must chain to come from: Bundled, the Mozilla roots compiled into the module; Windows, the roots in the current user's Root store (Cert:\CurrentUser\Root), which also shows the machine's; None, neither. When not given: Bundled and Windows on Windows, Bundled on a system without a Windows certificate store.</maml:para></maml:description><command:parameterValue required="true" variableLength="false">string[]</command:parameterValue><dev:type><maml:name>string[]</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter><command:parameter required="false" variableLength="false" globbing="false" pipelineInput="False" position="named" aliases=""><maml:name>RootCertificate</maml:name><maml:description><maml:para>Certificates to trust as roots besides those -TrustedRoots names, as X509Certificate2 objects, such as those in the Cert: drive or one read with [X509Certificate2]::new('ca.cer').</maml:para></maml:description><command:parameterValue required="true" variableLength="false">System.Security.Cryptography.X509Certificates.X509Certificate2[]</command:parameterValue><dev:type><maml:name>System.Security.Cryptography.X509Certificates.X509Certificate2[]</maml:name><maml:uri /></dev:type><dev:defaultValue>None</dev:defaultValue></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>string</maml:name></dev:type><maml:description><maml:para>An https:// address.</maml:para></maml:description></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>SecureFetch.Response</maml:name></dev:type><maml:description><maml:para></maml:para></maml:description></command:returnValue></command:returnValues><command:examples><command:example><maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title><dev:code>Invoke-SecureFetch https://pq.cloudflareresearch.com/cdn-cgi/trace</dev:code><dev:remarks><maml:para></maml:para></dev:remarks></command:example><command:example><maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title><dev:code>'https://pq.cloudflareresearch.com/cdn-cgi/trace' | Invoke-SecureFetch -TimeoutSeconds 10 | Select-Object StatusCode, Protocol, KeyExchange, CipherSuite</dev:code><dev:remarks><maml:para></maml:para></dev:remarks></command:example><command:example><maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title><dev:code>Invoke-SecureFetch https://pq.cloudflareresearch.com/cdn-cgi/no-such-page -SkipHttpErrorCheck</dev:code><dev:remarks><maml:para></maml:para></dev:remarks></command:example><command:example><maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title><dev:code>Invoke-SecureFetch https://pq.cloudflareresearch.com/cdn-cgi/trace -RequirePostQuantum</dev:code><dev:remarks><maml:para></maml:para></dev:remarks></command:example><command:example><maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title><dev:code>Invoke-SecureFetch https://postman-echo.com/post -Method POST -Body '{"name":"value"}' -ContentType 'application/json' -Headers @{ 'X-Example' = '42' }</dev:code><dev:remarks><maml:para></maml:para></dev:remarks></command:example><command:example><maml:title>-------------------------- EXAMPLE 6 --------------------------</maml:title><dev:code>(Invoke-SecureFetch https://github.com/PowerShell/PowerShell/releases/latest).FinalUri</dev:code><dev:remarks><maml:para></maml:para></dev:remarks></command:example><command:example><maml:title>-------------------------- EXAMPLE 7 --------------------------</maml:title><dev:code>Invoke-SecureFetch https://speed.cloudflare.com/__down?bytes=1048576 -OutFile .\down.bin -PassThru</dev:code><dev:remarks><maml:para></maml:para></dev:remarks></command:example></command:examples></command:command> </helpItems> |