en-US/PSSPI.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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SchannelCredential</command:name> <command:verb>Get</command:verb> <command:noun>SchannelCredential</command:noun> <maml:description> <maml:para>Creates a Schannel SSPI credential based on the legacy SCHANNEL_CRED structure.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets a Schannel SSPI credential for use with the `Microsoft Unified Security Protocol Provider` provider. The credential is retrieved using the `SCHANNEL_CRED` structure that is the older legacy Schannel credential structure. It has been deprected in favour of `SCH_CREDENTIALS` exposed by Get-SCHCredential (./Get-SCHCredential.md)which should be used if on a new enough Windows version.</maml:para> <maml:para>By default it allows all the system configured protocols and ciphers except for TLS 1.3. It also can be used to explicitly set the list of protocols and ciphers it will use with the `-Protocols` and `-SupportedAlgs` parameters.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SchannelCredential</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The certificate(s) to use when authenticating the caller. When passing an empty list, the client will depend on Schannel to find an approriate certificatefor the authentication process. For an inbound credential these are the certificates Schannel will use to present to the client. The certificate selected is based on the capabilities offered by the client and what fits best. At least one certificate must be specified when `-CredentialUse` has the `SECPKG_CRED_INBOUND` flag.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate[]</command:parameterValue> <dev:type> <maml:name>X509Certificate[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CredentialUse</maml:name> <maml:description> <maml:para>How the credential is to be used. Defaults to `SECPKG_CRED_OUTBOUND` which is used by a client. Set to `SECPKG_CRED_INBOUND` to create a credential for use by a server/acceptor.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_INBOUND</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_OUTBOUND</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_BOTH</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_DEFAULT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_AUTOLOGON_RESTRICTED</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_PROCESS_POLICY_ONLY</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CredentialUse</command:parameterValue> <dev:type> <maml:name>CredentialUse</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Flags to set which control the behaviour of the Schannel operation. These flags can control behaviour like how certificates are validated, client auth certificate lookups, and more.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_NO_SYSTEM_MAPPER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_NO_SERVERNAME_CHECK</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_MANUAL_CRED_VALIDATION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_NO_DEFAULT_CREDS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_AUTO_CRED_VALIDATION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_USE_DEFAULT_CREDS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_DISABLE_RECONNECTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_END_CERT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_CHAIN</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_IGNORE_NO_REVOCATION_CHECK</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_IGNORE_REVOCATION_OFFLINE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_RESTRICTED_ROOTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_CACHE_ONLY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_CACHE_ONLY_URL_RETRIEVAL</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_SNI_CREDENTIAL</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_MEMORY_STORE_CERT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_CACHE_ONLY_URL_RETRIEVAL_ON_CREATE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_SEND_ROOT_CERT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_SNI_ENABLE_OCSP</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_SEND_AUX_RECORD</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_USE_STRONG_CRYPTO</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_USE_PRESHAREDKEY_ONLY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_USE_DTLS_ONLY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_ALLOW_NULL_ENCRYPTION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_DEFERRED_CRED_VALIDATION</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SchannelCredFlags</command:parameterValue> <dev:type> <maml:name>SchannelCredFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaximumCipherStrength</maml:name> <maml:description> <maml:para>{{ Fill MaximumCipherStrength Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MinimumCipherStrength</maml:name> <maml:description> <maml:para>{{ Fill MinimumCipherStrength Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Protocols</maml:name> <maml:description> <maml:para>Explicitly set the TLS protocols that the credential can use. If omitted then all the protocols enabled system wide will be used. The system wide settings take precedence over this value, e.g. TLS1.0 cannot be used if disabled in the registry.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SP_PROT_NONE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_PCT1_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_PCT1_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_PCT1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL2_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL2_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL2</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_0_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3TLS1_SERVERS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3TLS1_CLIENTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_0_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_0</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3TLS1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_1_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_1_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_2_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_2_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_2</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_3_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_3_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_3</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_0_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_0_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_0</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_2_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_2_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_2</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_UNI_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SERVERS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_UNI_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_CLIENTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_UNI</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_ALL</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SchannelProtocols</command:parameterValue> <dev:type> <maml:name>SchannelProtocols</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RootStore</maml:name> <maml:description> <maml:para>Used for inbound/acceptor credentials and is the X509 store that contains the self-signed root certificate for certification authorities trusted by the application. This is used only be server-side applications that require client authentication.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Store</command:parameterValue> <dev:type> <maml:name>X509Store</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionLifespanMS</maml:name> <maml:description> <maml:para>The number of milliseconds that Schannel keeps the session in its session cache. After this time has passed, any new connections between the client and server require a new Schannel session. The default is `0` which is set to use the system wide configured default of 10 hours.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SupportedAlgs</maml:name> <maml:description> <maml:para>A list of algorithms that are available to the credential. It is used to have the credential only use the algorithms specified. This essentially controls the cipher suites that are available to the credential for use. Omitting this value will have the credential use the system defaults.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AlgorithmId[]</command:parameterValue> <dev:type> <maml:name>AlgorithmId[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The certificate(s) to use when authenticating the caller. When passing an empty list, the client will depend on Schannel to find an approriate certificatefor the authentication process. For an inbound credential these are the certificates Schannel will use to present to the client. The certificate selected is based on the capabilities offered by the client and what fits best. At least one certificate must be specified when `-CredentialUse` has the `SECPKG_CRED_INBOUND` flag.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate[]</command:parameterValue> <dev:type> <maml:name>X509Certificate[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CredentialUse</maml:name> <maml:description> <maml:para>How the credential is to be used. Defaults to `SECPKG_CRED_OUTBOUND` which is used by a client. Set to `SECPKG_CRED_INBOUND` to create a credential for use by a server/acceptor.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CredentialUse</command:parameterValue> <dev:type> <maml:name>CredentialUse</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Flags to set which control the behaviour of the Schannel operation. These flags can control behaviour like how certificates are validated, client auth certificate lookups, and more.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SchannelCredFlags</command:parameterValue> <dev:type> <maml:name>SchannelCredFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaximumCipherStrength</maml:name> <maml:description> <maml:para>{{ Fill MaximumCipherStrength Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MinimumCipherStrength</maml:name> <maml:description> <maml:para>{{ Fill MinimumCipherStrength Description }}</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Protocols</maml:name> <maml:description> <maml:para>Explicitly set the TLS protocols that the credential can use. If omitted then all the protocols enabled system wide will be used. The system wide settings take precedence over this value, e.g. TLS1.0 cannot be used if disabled in the registry.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SchannelProtocols</command:parameterValue> <dev:type> <maml:name>SchannelProtocols</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RootStore</maml:name> <maml:description> <maml:para>Used for inbound/acceptor credentials and is the X509 store that contains the self-signed root certificate for certification authorities trusted by the application. This is used only be server-side applications that require client authentication.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Store</command:parameterValue> <dev:type> <maml:name>X509Store</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionLifespanMS</maml:name> <maml:description> <maml:para>The number of milliseconds that Schannel keeps the session in its session cache. After this time has passed, any new connections between the client and server require a new Schannel session. The default is `0` which is set to use the system wide configured default of 10 hours.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SupportedAlgs</maml:name> <maml:description> <maml:para>A list of algorithms that are available to the credential. It is used to have the credential only use the algorithms specified. This essentially controls the cipher suites that are available to the credential for use. Omitting this value will have the credential use the system defaults.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AlgorithmId[]</command:parameterValue> <dev:type> <maml:name>AlgorithmId[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.Credential</maml:name> </dev:type> <maml:description> <maml:para>The generated credential handle. This object has the following properties:</maml:para> <maml:para>+ `SafeHandle`: The handle to the SSPI credentials generated.</maml:para> <maml:para>+ `Expiry`: The expiry of the credentials.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This credential even when used on newer systems that support TLS 1.3 will never use it. Te Get-SCHCredential (./Get-SCHCredential.md)cmdlet must be used to support TLS 1.3.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1 - Get client Schannel credential with system defaults</maml:title> <dev:code>PS C:\> Get-SchannelCredential</dev:code> <dev:remarks> <maml:para>Gets a Schannel credential for a client to use with `New-SecContext`. This Schannel credential is set to use the system defaults.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2 - Get client Schannel and disable weak protocols and ciphers</maml:title> <dev:code>PS C:\> Get-SchannelCredential -Flags SCH_USE_STRONG_CRYPTO</dev:code> <dev:remarks> <maml:para>Gets a Schannel credential with the `SCH_USE_STRONG_CRYPTO` flag specified which disables any weak protocols and cipher suites from being used.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 3 - Get server Schannel with certificate -------</maml:title> <dev:code>PS C:\> $thumbprint = '...' # This is dependent on your environment PS C:\> $cert = Get-Item Cert:\LocalMachine\My\$thumbprint PS C:\> Get-SchannelCredential -CredentialUse SECPKG_CRED_INBOUND -Certificate $cert</dev:code> <dev:remarks> <maml:para>Gets a Schannel credential for use as a server that is backed by the certificate requested.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Get-SchannelCredential.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SCHANNEL_CRED</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/schannel/ns-schannel-schannel_cred</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ALG_ID</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/seccrypto/alg-id</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SCHCredential</command:name> <command:verb>Get</command:verb> <command:noun>SCHCredential</command:noun> <maml:description> <maml:para>Creates an Schannel SSPI credential based on the newer SCH_CREDENTIALS structure.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets a Schannel SSPI credential for use with the `Microsoft Unified Security Protocol Provider` provider. The credential is retrieved using the `SCH_CREDENTIALS` structure added in Windows 10 Build 1809 and supports all the modern protocols and ciphers like TLS 1.3. The Get-SchannelCredential (./Get-SchannelCredential.md)is the older Schannel credential structure that can be used for Windows versions older than Windows 10 Build 1809.</maml:para> <maml:para>By default it allows all the system configured protocols and ciphers and utilises TLS Parameters to disable certain protocols and cipher suites. Use New-TlsParameter (./New-TlsParameter.md)to learn more about how to disable certain protocols and ciphers.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SCHCredential</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The certificate(s) to use when authenticating the caller. When passing an empty list, the client will depend on Schannel to find an approriate certificatefor the authentication process. For an inbound credential these are the certificates Schannel will use to present to the client. The certificate selected is based on the capabilities offered by the client and what fits best. At least one certificate must be specified when `-CredentialUse` has the `SECPKG_CRED_INBOUND` flag.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate[]</command:parameterValue> <dev:type> <maml:name>X509Certificate[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CredentialUse</maml:name> <maml:description> <maml:para>How the credential is to be used. Defaults to `SECPKG_CRED_OUTBOUND` which is used by a client. Set to `SECPKG_CRED_INBOUND` to create a credential for use by a server/acceptor.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_INBOUND</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_OUTBOUND</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_BOTH</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_DEFAULT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_AUTOLOGON_RESTRICTED</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_PROCESS_POLICY_ONLY</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CredentialUse</command:parameterValue> <dev:type> <maml:name>CredentialUse</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Flags to set which control the behaviour of the Schannel operation. These flags can control behaviour like how certificates are validated, client auth certificate lookups, and more.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_NO_SYSTEM_MAPPER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_NO_SERVERNAME_CHECK</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_MANUAL_CRED_VALIDATION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_NO_DEFAULT_CREDS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_AUTO_CRED_VALIDATION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_USE_DEFAULT_CREDS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_DISABLE_RECONNECTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_END_CERT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_CHAIN</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_IGNORE_NO_REVOCATION_CHECK</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_IGNORE_REVOCATION_OFFLINE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_RESTRICTED_ROOTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_REVOCATION_CHECK_CACHE_ONLY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_CACHE_ONLY_URL_RETRIEVAL</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_SNI_CREDENTIAL</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_MEMORY_STORE_CERT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_CACHE_ONLY_URL_RETRIEVAL_ON_CREATE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_SEND_ROOT_CERT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_SNI_ENABLE_OCSP</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_SEND_AUX_RECORD</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_USE_STRONG_CRYPTO</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_USE_PRESHAREDKEY_ONLY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_USE_DTLS_ONLY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_ALLOW_NULL_ENCRYPTION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SCH_CRED_DEFERRED_CRED_VALIDATION</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SchannelCredFlags</command:parameterValue> <dev:type> <maml:name>SchannelCredFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RootStore</maml:name> <maml:description> <maml:para>Used for inbound/acceptor credentials and is the X509 store that contains the self-signed root certificate for certification authorities trusted by the application. This is used only be server-side applications that require client authentication.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Store</command:parameterValue> <dev:type> <maml:name>X509Store</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionLifespanMS</maml:name> <maml:description> <maml:para>The number of milliseconds that Schannel keeps the session in its session cache. After this time has passed, any new connections between the client and server require a new Schannel session. The default is `0` which is set to use the system wide configured default of 10 hours.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TlsParameter</maml:name> <maml:description> <maml:para>A list of TLS parameters that indicate TLS parameter restrictions. Use New-TlsParameter (./New-TlsParameter.md)to build the parameters that can restrict the protocols and cipher suites this credential can use.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TlsParameter[]</command:parameterValue> <dev:type> <maml:name>TlsParameter[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The certificate(s) to use when authenticating the caller. When passing an empty list, the client will depend on Schannel to find an approriate certificatefor the authentication process. For an inbound credential these are the certificates Schannel will use to present to the client. The certificate selected is based on the capabilities offered by the client and what fits best. At least one certificate must be specified when `-CredentialUse` has the `SECPKG_CRED_INBOUND` flag.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate[]</command:parameterValue> <dev:type> <maml:name>X509Certificate[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CredentialUse</maml:name> <maml:description> <maml:para>How the credential is to be used. Defaults to `SECPKG_CRED_OUTBOUND` which is used by a client. Set to `SECPKG_CRED_INBOUND` to create a credential for use by a server/acceptor.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CredentialUse</command:parameterValue> <dev:type> <maml:name>CredentialUse</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Flags to set which control the behaviour of the Schannel operation. These flags can control behaviour like how certificates are validated, client auth certificate lookups, and more.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SchannelCredFlags</command:parameterValue> <dev:type> <maml:name>SchannelCredFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RootStore</maml:name> <maml:description> <maml:para>Used for inbound/acceptor credentials and is the X509 store that contains the self-signed root certificate for certification authorities trusted by the application. This is used only be server-side applications that require client authentication.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Store</command:parameterValue> <dev:type> <maml:name>X509Store</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionLifespanMS</maml:name> <maml:description> <maml:para>The number of milliseconds that Schannel keeps the session in its session cache. After this time has passed, any new connections between the client and server require a new Schannel session. The default is `0` which is set to use the system wide configured default of 10 hours.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TlsParameter</maml:name> <maml:description> <maml:para>A list of TLS parameters that indicate TLS parameter restrictions. Use New-TlsParameter (./New-TlsParameter.md)to build the parameters that can restrict the protocols and cipher suites this credential can use.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TlsParameter[]</command:parameterValue> <dev:type> <maml:name>TlsParameter[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.Credential</maml:name> </dev:type> <maml:description> <maml:para>The generated credential handle. This object has the following properties:</maml:para> <maml:para>+ `SafeHandle`: The handle to the SSPI credentials generated.</maml:para> <maml:para>+ `Expiry`: The expiry of the credentials.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1 - Get client Schannel credential with system defaults</maml:title> <dev:code>PS C:\> Get-SCHCredential</dev:code> <dev:remarks> <maml:para>Gets a Schannel credential for a client to use with `New-SecContext`. This Schannel credential is set to use the system defaults.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2 - Get client Schannel and disable weak protocols and ciphers</maml:title> <dev:code>PS C:\> Get-SCHCredential -Flags SCH_USE_STRONG_CRYPTO</dev:code> <dev:remarks> <maml:para>Gets a Schannel credential with the `SCH_USE_STRONG_CRYPTO` flag specified which disables any weak protocols and cipher suites from being used.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 3 - Get server Schannel with certificate -------</maml:title> <dev:code>PS C:\> $thumbprint = '...' # This is dependent on your environment PS C:\> $cert = Get-Item Cert:\LocalMachine\My\$thumbprint PS C:\> Get-SCHCredential -CredentialUse SECPKG_CRED_INBOUND -Certificate $cert</dev:code> <dev:remarks> <maml:para>Gets a Schannel credential for use as a server that is backed by the certificate requested.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Get-SCHCredential.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SCH_CREDENTIALS</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/schannel/ns-schannel-sch_credentials</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SecContextCipherInfo</command:name> <command:verb>Get</command:verb> <command:noun>SecContextCipherInfo</command:noun> <maml:description> <maml:para>Get TLS cipher information from a negotiated context.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets the TLS protocol, cipher suite, and cipher algorithm information that was negotiated in a Schannel TLS context.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SecContextCipherInfo</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The Schannel security context to query. This context must have completed the authentication stage until it has been marked as Ok from `Step-InitSecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext[]</command:parameterValue> <dev:type> <maml:name>SecurityContext[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The Schannel security context to query. This context must have completed the authentication stage until it has been marked as Ok from `Step-InitSecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext[]</command:parameterValue> <dev:type> <maml:name>SecurityContext[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSSPI.SecurityContext[]</maml:name> </dev:type> <maml:description> <maml:para>An array of security contexts can be piped into this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.Commands.CipherInfo</maml:name> </dev:type> <maml:description> <maml:para>The CipherInfo object contains the following properties</maml:para> <maml:para>+ `Protocol` - The TLS protocol that was negotiated, e.g. `TLS1_3`</maml:para> <maml:para>+ `CipherSuite` - The Cipher Suite negotiated as a string, e.g. `TLS_AES_256_GCM_SHA384`</maml:para> <maml:para>+ `Cipher` - The cipher/auth algorithm that was used, e.g. `AES`</maml:para> <maml:para>+ `CipherLength` - The length in bits of the cipher/auth algorithm that was used, e.g. `256</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> $cred = Get-SCHCredential PS C:\> $ctx = New-SecContext -Credential $cred PS C:\> ... # Set up the context PS C:\> Get-SecContextCipherInfo -Context $ctx</dev:code> <dev:remarks> <maml:para>Gets the cipher information of a negotiated TLS context.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Get-SCHCredential.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SecPkgContext_CipherInfo</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/schannel/ns-schannel-secpkgcontext_cipherinfo</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SecContextRemoteCert</command:name> <command:verb>Get</command:verb> <command:noun>SecContextRemoteCert</command:noun> <maml:description> <maml:para>Gets the certificate supplied by the peer.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets the X509 certificate that was supplied by the peer. For an outbound credential this is the server certificate. For an inbound credential this is the client authentication certificate if it was requested with `ASC_REQ_MUTUAL_AUTH`. If using an inbound credential andclient auth was not requested then the cmdlet will fail as there is no certificate from the peer to retrieve.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SecContextRemoteCert</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The Schannel security context to query. This context must have completed the authentication stage until it has been marked as Ok from `Step-InitSecContext` or `Step-AcceptSecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext[]</command:parameterValue> <dev:type> <maml:name>SecurityContext[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The Schannel security context to query. This context must have completed the authentication stage until it has been marked as Ok from `Step-InitSecContext` or `Step-AcceptSecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext[]</command:parameterValue> <dev:type> <maml:name>SecurityContext[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSSPI.SecurityContext[]</maml:name> </dev:type> <maml:description> <maml:para>An array of security contexts can be piped into this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Security.Cryptography.X509Certificates.X509Certificate2</maml:name> </dev:type> <maml:description> <maml:para>The X509Certificate2 object that represents the certificate retrieved from the server.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------- Example 1 - Get server certificate --------------</maml:title> <dev:code>PS C:\> $ctx = Get-SCHCredential PS C:\> ... Complete auth PS C:\> Get-SecContextRemoteCert -Context $ctx</dev:code> <dev:remarks> <maml:para>Gets the certificate given by the server.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Get-SecContextRemoteCert.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SecContextSizes</command:name> <command:verb>Get</command:verb> <command:noun>SecContextSizes</command:noun> <maml:description> <maml:para>Gets the sizes of important structures used in message support functions.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets the various message sizes of a security context, for example the size of a security token, header/trailer used in signatures/encryption, and more.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SecContextSizes</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The security context to query. This context must have completed the authentication stage until it has been marked as Ok from `Step-InitSecContext` or `Step-AcceptSecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext[]</command:parameterValue> <dev:type> <maml:name>SecurityContext[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The security context to query. This context must have completed the authentication stage until it has been marked as Ok from `Step-InitSecContext` or `Step-AcceptSecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext[]</command:parameterValue> <dev:type> <maml:name>SecurityContext[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSSPI.SecurityContext[]</maml:name> </dev:type> <maml:description> <maml:para>An array of security contexts can be piped into this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.Commands.ContextSizes</maml:name> </dev:type> <maml:description> <maml:para>The ContextSizes object contains the following properties</maml:para> <maml:para>+ `MaxToken` - Maximum size of the security token used in the authentication exchanges</maml:para> <maml:para>+ `MaxSignature` - Maximum size of the signatures created by this security context, will be 0 if integrity services are not negotiated</maml:para> <maml:para>+ `BlockSize` - Preferred integral size of the messages, e.g. 8 indicates messages should be of size zero mod eight for optimal performance</maml:para> <maml:para>+ `SecurityTrailer` - Size of the security trailer to be appended to messages</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>---------------- Example 1 - Get context sizes ----------------</maml:title> <dev:code>PS C:\> $ctx = New-SecContext PS C:\> ... Complete auth PS C:\> Get-SecContextSizes -Context $ctx</dev:code> <dev:remarks> <maml:para>Gets the sizes associated with the negotiated security context.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Get-SecContextSizes.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SecPkgContext_Sizes</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/sspi/ns-sspi-secpkgcontext_sizes</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SSPICredential</command:name> <command:verb>Get</command:verb> <command:noun>SSPICredential</command:noun> <maml:description> <maml:para>Get a SSPI credential handle.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Get a SSPI credential for use with a security context. Currently a credential can be for the current user context or for an explicit credential.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SSPICredential</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AllowPackage</maml:name> <maml:description> <maml:para>Specify security packages that can be used on a `Negotiate` credential. This is used to only allow the list of packages in a `Negotiate` context rather than the defaults used by SSPI.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PackageOrString[]</command:parameterValue> <dev:type> <maml:name>PackageOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Use the username/password of the credentials specified instead of the current user context.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CredentialUse</maml:name> <maml:description> <maml:para>How the credential is to be used. Defaults to `SECPKG_CRED_OUTBOUND` which is used by a client. Multiple values can be specified depending on the desired use.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_INBOUND</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_OUTBOUND</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_BOTH</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_DEFAULT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_AUTOLOGON_RESTRICTED</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECPKG_CRED_PROCESS_POLICY_ONLY</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CredentialUse</command:parameterValue> <dev:type> <maml:name>CredentialUse</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Package</maml:name> <maml:description> <maml:para>The SSPI package the credential is used for, like `Negotiate`, `Kerberos`, `NTLM`, and more. See Get-SSPIPackage (./Get-SSPIPackage.md)for more details.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PackageOrString</command:parameterValue> <dev:type> <maml:name>PackageOrString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Principal</maml:name> <maml:description> <maml:para>The principal to use with the credential, the purpose of this value depends on the package being used.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RejectPackage</maml:name> <maml:description> <maml:para>Specify security packages that cannot be used on a `Negotiate` credential. This is used to exclude a list of packages in a `Negotiate` context rather than the defaults used by SSPI. For example specify `-RejectPackage NTLM` when creating a `Negotiate` credential to disable NTLM negotiation.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PackageOrString[]</command:parameterValue> <dev:type> <maml:name>PackageOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AllowPackage</maml:name> <maml:description> <maml:para>Specify security packages that can be used on a `Negotiate` credential. This is used to only allow the list of packages in a `Negotiate` context rather than the defaults used by SSPI.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PackageOrString[]</command:parameterValue> <dev:type> <maml:name>PackageOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Use the username/password of the credentials specified instead of the current user context.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CredentialUse</maml:name> <maml:description> <maml:para>How the credential is to be used. Defaults to `SECPKG_CRED_OUTBOUND` which is used by a client. Multiple values can be specified depending on the desired use.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CredentialUse</command:parameterValue> <dev:type> <maml:name>CredentialUse</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Package</maml:name> <maml:description> <maml:para>The SSPI package the credential is used for, like `Negotiate`, `Kerberos`, `NTLM`, and more. See Get-SSPIPackage (./Get-SSPIPackage.md)for more details.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PackageOrString</command:parameterValue> <dev:type> <maml:name>PackageOrString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Principal</maml:name> <maml:description> <maml:para>The principal to use with the credential, the purpose of this value depends on the package being used.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RejectPackage</maml:name> <maml:description> <maml:para>Specify security packages that cannot be used on a `Negotiate` credential. This is used to exclude a list of packages in a `Negotiate` context rather than the defaults used by SSPI. For example specify `-RejectPackage NTLM` when creating a `Negotiate` credential to disable NTLM negotiation.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PackageOrString[]</command:parameterValue> <dev:type> <maml:name>PackageOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.SspiCredential</maml:name> </dev:type> <maml:description> <maml:para>The generated credential handle. This object has the following properties:</maml:para> <maml:para>+ `SafeHandle`: The handle to the SSPI credentials generated.</maml:para> <maml:para>+ `Expiry`: The expiry of the credentials.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Credentials aren't validated by SSPI when being generated. It is verified when being used by `InitializeSecurityContext` or `AcceptSecurityContext`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> Example 1: Get the Negotiate credentials for the current user </maml:title> <dev:code>PS C:\> Get-SSPICredential -Package Negotiate</dev:code> <dev:remarks> <maml:para>Gets the SSPI credential for the current user for the `Negotiate` package.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 2: Get the Kerberos credential with an explicit user -</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> Get-SSPICredential -Package Kerberos -Credential $cred</dev:code> <dev:remarks> <maml:para>Gets the SSPI credential with explicit credentials for the `Kerberos` package.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--- Example 3: Create Negotiate credential but disable NTLM ---</maml:title> <dev:code>PS C:\> Get-SSPICredential -Package Negotiate -RejectPackage NTLM</dev:code> <dev:remarks> <maml:para>Gets the SSPI credential for the current user for the `Negotiate` package but disables use of NTLM. This means that `Negotiate` will attempt to use `Kerberos` or `NegoEx` but will not attempt to use `NTLM` as a fallback.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Get-SSPICredential.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>AcquireCredentialsHandleW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/secauthn/acquirecredentialshandle--general</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SSPIPackage</command:name> <command:verb>Get</command:verb> <command:noun>SSPIPackage</command:noun> <maml:description> <maml:para>Gets security package information.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets information about the installed security packages that SSPI can use.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SSPIPackage</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Get the details of the security packages specified. If omitted then all security packages will be returned.</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:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Get the details of the security packages specified. If omitted then all security packages will be returned.</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:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>SSPI.SecPackageInfo</maml:name> </dev:type> <maml:description> <maml:para>The security package information. This object has the following properties:</maml:para> <maml:para>+ `Name`: The name of the security package.</maml:para> <maml:para>+ `Comment`: Additional information of the security package.</maml:para> <maml:para>+ `Capabilities`: Set of bit flags that describes the capabilities of the security package.</maml:para> <maml:para>+ `Version`: Specifies the version of the package protocol. Must be 1.</maml:para> <maml:para>+ `RPCID`: Specifies a DCE RPC identifier, if appropriate. If the package does not implement one of the DCE registered security systems, the reserved value SECPKG_ID_NONE is used.</maml:para> <maml:para>+ `MaxTokenSize`: Specifies the maximum size, in bytes, of the token.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------- Example 1: Get all installed security packages --------</maml:title> <dev:code>PS C:\> Get-SSPIPackage</dev:code> <dev:remarks> <maml:para>Get the details of all the installed security packages.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 2: Get information about a specific security package -</maml:title> <dev:code>PS C:\> Get-SSPIPackage -Name Negotiate, Kerberos</dev:code> <dev:remarks> <maml:para>Get the details of the `Negotiate` and `Kerberos` security package.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Get-SSPIPackage.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>EnumerateSecurityPackagesW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-enumeratesecuritypackagesw</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>QuerySecurityPackageInfoW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-querysecuritypackageinfow</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SecPkgInfoW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/ns-sspi-secpkginfow</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-ChannelBindingBuffer</command:name> <command:verb>New</command:verb> <command:noun>ChannelBindingBuffer</command:noun> <maml:description> <maml:para>Create channel binding structure for authentication.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates a security buffer that can be supplied when stepping through an security context that contains the channel binding data for a context.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-ChannelBindingBuffer</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Acceptor</maml:name> <maml:description> <maml:para>The acceptor address data. This is typically unusued.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AcceptorAddrType</maml:name> <maml:description> <maml:para>The acceptor address type. This is typically unused.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationData</maml:name> <maml:description> <maml:para>The application data of the channel binding. The value here depends on the channel binding being used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Initiator</maml:name> <maml:description> <maml:para>The initiator address data. This is typically unusued.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InitiatorAddrType</maml:name> <maml:description> <maml:para>The initiator address type. This is typically unused.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Acceptor</maml:name> <maml:description> <maml:para>The acceptor address data. This is typically unusued.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AcceptorAddrType</maml:name> <maml:description> <maml:para>The acceptor address type. This is typically unused.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationData</maml:name> <maml:description> <maml:para>The application data of the channel binding. The value here depends on the channel binding being used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Initiator</maml:name> <maml:description> <maml:para>The initiator address data. This is typically unusued.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InitiatorAddrType</maml:name> <maml:description> <maml:para>The initiator address type. This is typically unused.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.ChannelBindingBuffer</maml:name> </dev:type> <maml:description> <maml:para>The generated channel binding buffer. This object has the following properties:</maml:para> <maml:para>+ `InitiatorAddrType` - The initiator address type</maml:para> <maml:para>+ `Initiator` - The initiator address data</maml:para> <maml:para>+ `AcceptorAddrType` - The acceptor address type</maml:para> <maml:para>+ `Acceptor` - The acceptor address data</maml:para> <maml:para>+ `ApplicationData` - The application data</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--- Example 1: Create channel binding with application data ---</maml:title> <dev:code>PS C:\> $cb = New-ChannelBindingBuffer -ApplicationData $byteArray</dev:code> <dev:remarks> <maml:para>Creates the channel binding buffer with `ApplicationData` set to the byte array passed in.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/New-ChannelBindingBuffer.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SEC_CHANNEL_BINDINGS</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/ns-sspi-sec_channel_bindings</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-CryptoSetting</command:name> <command:verb>New</command:verb> <command:noun>CryptoSetting</command:noun> <maml:description> <maml:para>Creates a Crypto Setting object for use as a TLS Parameter to disable certain cipher suites.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Builds a Crypto Setting object that represents a cipher suite cryptography algorithm. It doesn't represent a single cipher suite but rather components of a cipher suite allowing you to disable weaker components by type rather than by name. It is used in TLS Parameters to restrict the cipher suites used in a TLS handshake. It is based off the `CRYPTO_SETTINGS` struct in `Schannel.h` and is used with the newer SCH style credentials added in Windows 10 Build 1809. Use these crypto settings as a value for `New-TlsParameter -CryptoSetting ...` which is used with `Get-SCHCredential`. Multiple crypto setting objects can be used with `-CryptoSetting` allowing the caller to block multiple algorithms.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-CryptoSetting</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Algorithm</maml:name> <maml:description> <maml:para>The identifier of the algorithm to restrict. The identifier is dependent on the `-Usage` option chosen and is used to identify a component of the TLS cipher suite to disable. For example `-Usage Cipher -Algorithm RC4` will disable and TLS cipher suite that uses `RC4` as the session/encryption cipher. This parameter supports tab completion for known algorithms.</maml:para> <maml:para>While the TLS Cipher Suite string uses `ECDHE` and `DHE`, they are represented by `ECDH` and `DH` as an algorithm in SSPI.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ChainingMode</maml:name> <maml:description> <maml:para>If the cipher algorithm specified is a block mode cipher this can be used to disable the algorithm when using a particular chaining/block mode. For example `-Usage Cipher -Algorithm AES -Chaining Mode ChainingModeCBC` will disable cipher suites that use the AES cipher in CBC mode. A maximum of 16 chaining modes can be specified for this parameter. A list of known chaining modes can be found under `BCRYPT_CHAINING_MODE` at https://learn.microsoft.com/en-us/windows/win32/seccng/cng-property-identifiers. This parameter supports tab completion for known algorithms.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxBitLength</maml:name> <maml:description> <maml:para>Specifies the maximum bit length of a cipher that is excluded from the ciphers specified by the crypto settings object. For example specifying `-MaxBitLength 128` will disable any ciphers that are greater than 128 bits, i.e. AES256.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MinBitLength</maml:name> <maml:description> <maml:para>Specifies the minimum bit length of a cipher that is excluded from the ciphers specified by the crypto settings object. For example specifying `-MinBitLength 256` will disable any ciphers that are less than 256 bites, i.e. AES128.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Usage</maml:name> <maml:description> <maml:para>The algorithm type/usage that this crypto setting represents. This can be set to the following values</maml:para> <maml:para>+ `KeyExchange` - Algorithm in the key exchange to disable</maml:para> <maml:para>+ `Signature` - Algorithm in the signature to disable</maml:para> <maml:para>+ `Cipher` - Algorithm in the cipher/authentication method to disable</maml:para> <maml:para>+ `Digest` - Algorithm in the cipher/authentication digest to disable</maml:para> <maml:para>+ `CertSig` - Algorithm and/or hash used to sign the certificate to disable, this is the `signature_algorithms` extension type in the TLS client hello</maml:para> <maml:para>The usage value and algorithm are used by the crypto settings object to define the cipher suites which are blocked from being used.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">KeyExchange</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Signature</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Cipher</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Digest</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">CertSig</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SchannelCryptoUsage</command:parameterValue> <dev:type> <maml:name>SchannelCryptoUsage</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Algorithm</maml:name> <maml:description> <maml:para>The identifier of the algorithm to restrict. The identifier is dependent on the `-Usage` option chosen and is used to identify a component of the TLS cipher suite to disable. For example `-Usage Cipher -Algorithm RC4` will disable and TLS cipher suite that uses `RC4` as the session/encryption cipher. This parameter supports tab completion for known algorithms.</maml:para> <maml:para>While the TLS Cipher Suite string uses `ECDHE` and `DHE`, they are represented by `ECDH` and `DH` as an algorithm in SSPI.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ChainingMode</maml:name> <maml:description> <maml:para>If the cipher algorithm specified is a block mode cipher this can be used to disable the algorithm when using a particular chaining/block mode. For example `-Usage Cipher -Algorithm AES -Chaining Mode ChainingModeCBC` will disable cipher suites that use the AES cipher in CBC mode. A maximum of 16 chaining modes can be specified for this parameter. A list of known chaining modes can be found under `BCRYPT_CHAINING_MODE` at https://learn.microsoft.com/en-us/windows/win32/seccng/cng-property-identifiers. This parameter supports tab completion for known algorithms.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxBitLength</maml:name> <maml:description> <maml:para>Specifies the maximum bit length of a cipher that is excluded from the ciphers specified by the crypto settings object. For example specifying `-MaxBitLength 128` will disable any ciphers that are greater than 128 bits, i.e. AES256.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MinBitLength</maml:name> <maml:description> <maml:para>Specifies the minimum bit length of a cipher that is excluded from the ciphers specified by the crypto settings object. For example specifying `-MinBitLength 256` will disable any ciphers that are less than 256 bites, i.e. AES128.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Usage</maml:name> <maml:description> <maml:para>The algorithm type/usage that this crypto setting represents. This can be set to the following values</maml:para> <maml:para>+ `KeyExchange` - Algorithm in the key exchange to disable</maml:para> <maml:para>+ `Signature` - Algorithm in the signature to disable</maml:para> <maml:para>+ `Cipher` - Algorithm in the cipher/authentication method to disable</maml:para> <maml:para>+ `Digest` - Algorithm in the cipher/authentication digest to disable</maml:para> <maml:para>+ `CertSig` - Algorithm and/or hash used to sign the certificate to disable, this is the `signature_algorithms` extension type in the TLS client hello</maml:para> <maml:para>The usage value and algorithm are used by the crypto settings object to define the cipher suites which are blocked from being used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SchannelCryptoUsage</command:parameterValue> <dev:type> <maml:name>SchannelCryptoUsage</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.CryptoSetting</maml:name> </dev:type> <maml:description> <maml:para>An object representing the crypto setting requested. It contains the following properties</maml:para> <maml:para>+ `Usage`</maml:para> <maml:para>+ `Algorithm`</maml:para> <maml:para>+ `ChainingModes`</maml:para> <maml:para>+ `MinBitLength`</maml:para> <maml:para>+ `MaxBitLength`</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------- Example 1 - Disable TLS_CHACHA20_POLY1305_SHA256 -------</maml:title> <dev:code>PS C:\> New-CryptoSetting -Usage Cipher -Algorithm CHACHA20_POLY1305</dev:code> <dev:remarks> <maml:para>Creates a crypto setting that applies to any cipher suites that use the CHACHA20_POLY1305 algorithm. When used with `New-TlsParameter -DisableCrypto $cs` it will disable the usage of the TLS 1.3 cipher suite `TLS_CHACHA20_POLY1305_SHA256`</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----------------- Example 2 - Disable AES 256 -----------------</maml:title> <dev:code>PS C:\> New-CryptoSetting -Usage Cipher -Algorithm AES -MaxBitLength 128</dev:code> <dev:remarks> <maml:para>Creates a crypto setting that applies to any cipher suites that use the AES algorithm and has a bit length greater than 128.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----------------- Example 3 - Disable AES 128 -----------------</maml:title> <dev:code>PS C:\> New-CryptoSetting -Usage Cipher -Algorithm AES -MinBitLength 256</dev:code> <dev:remarks> <maml:para>Creates a crypto setting that applies to any cipher suites that use the AES algorithm and has a bit length less than 256.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 4 - Disable SHA256 hashing algorithm ---------</maml:title> <dev:code>PS C:\> New-CryptoSetting -Usage Digest -Algorithm SHA256</dev:code> <dev:remarks> <maml:para>Creates a crypto setting that applies to any cipher suites that use the SHA256 digest/signature hashing algorithm. For TLS 1.3 this will disable `TLS_AES_128_GCM_SHA256 ` but not `TLS_AES_256_GCM_SHA384`</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/New-CryptoSetting.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>CRYPTO_SETTINGS</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/schannel/ns-schannel-crypto_settings</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>eTlsAlgorithmUsage</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/schannel/ne-schannel-etlsalgorithmusage</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Cipher Suites in TLS Schannel</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-SecBuffer</command:name> <command:verb>New</command:verb> <command:noun>SecBuffer</command:noun> <maml:description> <maml:para>Create an SSPI security buffer</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates an SSPI security buffer that can be used for SSPI functions. This buffer is typically used for stepping through a new security context or encrypting/decrypting a message.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-SecBuffer</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Data</maml:name> <maml:description> <maml:para>The raw byte array of the data the buffer represents or `$null` to use a buffer that should be populated by Windows during an SSPI call.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Custom flags to set on th security buffer.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">NONE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_READONLY_WITH_CHECKSUM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_RESERVED</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_READONLY</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SecBufferFlags</command:parameterValue> <dev:type> <maml:name>SecBufferFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Type</maml:name> <maml:description> <maml:para>The security buffer type that the data represents.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_EMPTY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_DATA</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_TOKEN</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_PKG_PARAMS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_MISSING</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_EXTRA</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_STREAM_TRAILER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_STREAM_HEADER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_NEGOTIATION_INFO</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_PADDING</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_STREAM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_MECHLIST</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_MECHLIST_SIGNATURE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_TARGET</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_CHANNEL_BINDINGS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_CHANGE_PASS_RESPONSE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_TARGET_HOST</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_ALERT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_APPLICATION_PROTOCOLS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_SRTP_PROTECTION_PROFILES</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_SRTP_MASTER_KEY_IDENTIFIER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_TOKEN_BINDING</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_PRESHARED_KEY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECBUFFER_PRESHARED_KEY_IDENTITY</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SecBufferType</command:parameterValue> <dev:type> <maml:name>SecBufferType</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Data</maml:name> <maml:description> <maml:para>The raw byte array of the data the buffer represents or `$null` to use a buffer that should be populated by Windows during an SSPI call.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Custom flags to set on th security buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecBufferFlags</command:parameterValue> <dev:type> <maml:name>SecBufferFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Type</maml:name> <maml:description> <maml:para>The security buffer type that the data represents.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecBufferType</command:parameterValue> <dev:type> <maml:name>SecBufferType</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.SecurityBuffer</maml:name> </dev:type> <maml:description> <maml:para>An SSPI security buffer. This contains the following properties:</maml:para> <maml:para>+ `Type` - The security buffer type</maml:para> <maml:para>+ `Flags` - Flags for the security buffer</maml:para> <maml:para>+ `Length` - The length of populated data, will be the length of `Data` on creation but may be modified by a call to SSPI</maml:para> <maml:para>+ `Data` - The raw bytes of the buffer, or `$null` if the data is to be set by SSPI</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>----------- Example 1: Create token security buffer -----------</maml:title> <dev:code>PS C:\> New-SecBuffer -Type SECBUFFER_TOKEN -Data $byteArray</dev:code> <dev:remarks> <maml:para>Creates a security buffer that stores a token used with authentication. The `$byteArray` is a byte array from an external source.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-- Example 2: Create token security buffer with no user value --</maml:title> <dev:code>PS C:\> New-SecBuffer -Type SECBUFFER_TOKEN</dev:code> <dev:remarks> <maml:para>Creates an empty security buffer without any data present. This type of security buffer is useful when calling an API that will populate the data based on the operation it performs.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/New-SecBuffer.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SecBuffer</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/ns-sspi-secbuffer</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-SecContext</command:name> <command:verb>New</command:verb> <command:noun>SecContext</command:noun> <maml:description> <maml:para>Creates an SSPI context.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates the initial SSPI context using an optional credential. This context needs to be stepped through to be usable and to produce the security tokens exchanged with a peer.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-SecContext</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The SSPI credential created by Get-SSPICredential (./Get-SSPICredential.md)to use for the context. If omitted then the current user context will be used with the security context.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Credential</command:parameterValue> <dev:type> <maml:name>Credential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The SSPI credential created by Get-SSPICredential (./Get-SSPICredential.md)to use for the context. If omitted then the current user context will be used with the security context.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Credential</command:parameterValue> <dev:type> <maml:name>Credential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.SecurityContext</maml:name> </dev:type> <maml:description> <maml:para>+ `Credential` - The credential associated with the context</maml:para> <maml:para>+ `SafeHandle` - The handle to the SSPI security context</maml:para> <maml:para>+ `Expiry` - The expiry of the security context</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-- Example 1: Create a security context for the current user --</maml:title> <dev:code>PS C:\> $cred = Get-SSPICredential -Package Negotiate PS C:\> $ctx = New-SecContext -Credential $cred</dev:code> <dev:remarks> <maml:para>Creates an SSPI context for the `Negotiate` provider using the user's current credentials.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/New-SecContext.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-TlsParameter</command:name> <command:verb>New</command:verb> <command:noun>TlsParameter</command:noun> <maml:description> <maml:para>Creates a TLS parameter object for use with an SCH credential (Schannel).</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Builds a TLS Parameter object that represents TLS parameter restrictions. It can be used to disable TLS protocols or with `New-CryptoSetting` to disable certain cipher suites. It is based off the `TLS_PARMETERS` struct in `Schannel.h` and is used with the newer SCH style credential added in Windows 10 Build 1809. Multiple TLS parmeter objects can be used with `Get-SCHCredential -TlsParameter`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-TlsParameter</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AlpnId</maml:name> <maml:description> <maml:para>The ALPN IDs the parameter applies to. When omitted, the parameter applies to any negotiated protocols.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisabledCrypto</maml:name> <maml:description> <maml:para>The crypto settings as created by New-CryptoSetting (./New-CryptoSetting.md)to disable. A maximum of 16 settings can be applied to a single TLS Parameter. This is used to disable cipher suite algorithms that are used in the connection rather than the full TLS protocol.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CryptoSetting[]</command:parameterValue> <dev:type> <maml:name>CryptoSetting[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisabledProtocol</maml:name> <maml:description> <maml:para>The TLS protocols to disable. Any protocols specified here will not be available for the Schannel credential to use. For example `-DisabledProtocol SP_PROT_TLS1_3` will disable TLS 1.3 on the handshake. The `-bnot` operator can be used to inverse the selection so that all the protocols but the one specified are disabled, effectively making it an allow list of protocols. For example `-DisableProtocol (-bnot ([PSSPI.Schannel]::SP_PROT_TLS1_3))` will disable all protocols but TLS 1.2.</maml:para> <maml:para>Multiple protocols can be specified for this parameter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SP_PROT_NONE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_PCT1_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_PCT1_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_PCT1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL2_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL2_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL2</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_0_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3TLS1_SERVERS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3TLS1_CLIENTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_0_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_0</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SSL3TLS1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_1_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_1_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_2_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_2_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_2</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_3_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_3_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_TLS1_3</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_0_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_0_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_0</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_2_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_2_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_DTLS1_2</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_UNI_SERVER</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_SERVERS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_UNI_CLIENT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_CLIENTS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_UNI</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SP_PROT_ALL</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SchannelProtocols</command:parameterValue> <dev:type> <maml:name>SchannelProtocols</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Optional</maml:name> <maml:description> <maml:para>Marks the parameter as optional. This is only used for the server/acceptor as a way to mark a parameter that can be ignored if it causes the handshake from the client to be rejected.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AlpnId</maml:name> <maml:description> <maml:para>The ALPN IDs the parameter applies to. When omitted, the parameter applies to any negotiated protocols.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisabledCrypto</maml:name> <maml:description> <maml:para>The crypto settings as created by New-CryptoSetting (./New-CryptoSetting.md)to disable. A maximum of 16 settings can be applied to a single TLS Parameter. This is used to disable cipher suite algorithms that are used in the connection rather than the full TLS protocol.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CryptoSetting[]</command:parameterValue> <dev:type> <maml:name>CryptoSetting[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisabledProtocol</maml:name> <maml:description> <maml:para>The TLS protocols to disable. Any protocols specified here will not be available for the Schannel credential to use. For example `-DisabledProtocol SP_PROT_TLS1_3` will disable TLS 1.3 on the handshake. The `-bnot` operator can be used to inverse the selection so that all the protocols but the one specified are disabled, effectively making it an allow list of protocols. For example `-DisableProtocol (-bnot ([PSSPI.Schannel]::SP_PROT_TLS1_3))` will disable all protocols but TLS 1.2.</maml:para> <maml:para>Multiple protocols can be specified for this parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SchannelProtocols</command:parameterValue> <dev:type> <maml:name>SchannelProtocols</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Optional</maml:name> <maml:description> <maml:para>Marks the parameter as optional. This is only used for the server/acceptor as a way to mark a parameter that can be ignored if it causes the handshake from the client to be rejected.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.TlsParameter</maml:name> </dev:type> <maml:description> <maml:para>An object representing the TLS parameter requested. It contains the following properties</maml:para> <maml:para>+ `AlpnIds`</maml:para> <maml:para>+ `DisabledProtocols`</maml:para> <maml:para>+ `DisabledCryptos`</maml:para> <maml:para>+ `Optional`</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1 - Create Parameter to only allow TLS 1.2 connections</maml:title> <dev:code>PS C:\> New-TlsParameter -DisableProtocol (-bnot [PSSPI.SchannelProtocols]::SP_PROT_TLS1_3)</dev:code> <dev:remarks> <maml:para>Creates a TLS Parameter that disables all protocols except for TLS 1.3</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 2 - Create Parameter to disable TLS 1.0 and TLS 1.1 -</maml:title> <dev:code>PS C:\> New-TlsParameter -DisableProtocol SP_PROT_TLS1_0, SP_PROT_TLS1_1</dev:code> <dev:remarks> <maml:para>Creates a TLS Parameter that disabled TLS 1.0 and TLS 1.1.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/New-TlsParameter.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>TLS_PARAMETERS</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/schannel/ns-schannel-tls_parameters</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-KdcProxy</command:name> <command:verb>Set</command:verb> <command:noun>KdcProxy</command:noun> <maml:description> <maml:para>Set the KDC proxy settings on an SSPI credential.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Sets the KDC proxy settings for a Kerberos exchange on the provided SSPI credential. This is used to either set a new proxy or override global wide settings for Kerberos exchanges. This cmdlet will fail if the credential was created for a security provider that was not `Kerberos` or `Negotiate`.</maml:para> <maml:para>The proxy settings will be used anytime the credential it was set on was used with a security context.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-KdcProxy</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The SSPI credential to set the proxy settings on.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Credential</command:parameterValue> <dev:type> <maml:name>Credential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ForceProxy</maml:name> <maml:description> <maml:para>Set the `KDC_PROXY_SETTINGS_FLAGS_FORCEPROXY` flag on the proxy settings. This forces SSPI to always use the proxy provided instead of only when the configured KDC was unreachable through normal means.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>The proxy server to set. This should be in the format `hostname` or `hostname:port:path`. If only the hostname is set then Windows will automatically use the the `port:path` or `443:KdcProxy`.</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="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The SSPI credential to set the proxy settings on.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Credential</command:parameterValue> <dev:type> <maml:name>Credential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ForceProxy</maml:name> <maml:description> <maml:para>Set the `KDC_PROXY_SETTINGS_FLAGS_FORCEPROXY` flag on the proxy settings. This forces SSPI to always use the proxy provided instead of only when the configured KDC was unreachable through normal means.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>The proxy server to set. This should be in the format `hostname` or `hostname:port:path`. If only the hostname is set then Windows will automatically use the the `port:path` or `443:KdcProxy`.</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="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------- Example 1: Set the proxy for an SSPI credential -------</maml:title> <dev:code>PS C:\> $cred = Get-SSPICredential -Package Kerberos PS C:\> Set-KdcProxy -Credential $cred -Server proxy-host</dev:code> <dev:remarks> <maml:para>Sets the KDC proxy to `proxy-host` for the provided SSPI credential.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Set-KdcProxy.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SetCredentialsAttributesW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-setcredentialsattributesw</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>SecPkgCredentials_KdcProxySettingsW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/ns-sspi-secpkgcredentials_kdcproxysettingsw</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Step-AcceptSecContext</command:name> <command:verb>Step</command:verb> <command:noun>AcceptSecContext</command:noun> <maml:description> <maml:para>Steps through a clients security context exchange.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Performs an exchange of security tokens required for a server to authenticate a client. This is the first operation that should be performed on a security context and is required before the context can be used for toehr operations, like encyrption.</maml:para> <maml:para>Because the number of calls required relies on the security provider being used, this function may need to be called multiple times. Check the `Result` value on the output object to see what needs to happen next. These are the following result values that can be returned:</maml:para> <maml:para>+ `Ok` - The context is complete no more stepping is required</maml:para> <maml:para>+ `CompleteAndContinue` - A call to `Complete-AuthToken` (TBD) is required and one final token from the peer should be passed to `Step-InitSecContext`</maml:para> <maml:para>+ `CompleteNeeded` - A call to `Complete-AuthToken` (TBD) is required</maml:para> <maml:para>+ `ContinueNeeded` - The output token should be exchanged with the peer and input passed back into `Step-InitSecContext`</maml:para> <maml:para>On the common security providers, NTLM, Kerberos, and Negotiate, the `Ok` and `ContinueNeeded` responses are expected.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Step-AcceptSecContext</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The SSPI security context created with `New-SecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext</command:parameterValue> <dev:type> <maml:name>SecurityContext</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ContextReq</maml:name> <maml:description> <maml:para>Request options to use when creating the context. Some options only work for certain security providers. Requesting one of these options isn't guaranteed to be set once the context is complete, check the `Flags` value on the output result to verify the requested options were set on the context.</maml:para> <maml:para>The `ASC_REQ_ALLOCATE_MEMORY` flag should be set if the output buffers need to be allocated by SSPI.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">NONE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_DELEGATE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_MUTUAL_AUTH</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_REPLAY_DETECT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_SEQUENCE_DETECT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_CONFIDENTIALITY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_USE_SESSION_KEY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_SESSION_TICKET</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_ALLOCATE_MEMORY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_USE_DCE_STYLE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_DATAGRAM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_CONNECTION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_CALL_LEVEL</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_FRAGMENT_SUPPLIED</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_EXTENDED_ERROR</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_STREAM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_INTEGRITY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_LICENSING</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_IDENTIFY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_ALLOW_NULL_SESSION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_ALLOW_NON_USER_LOGONS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_ALLOW_CONTEXT_REPLAY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_FRAGMENT_TO_FIT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_NO_TOKEN</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_PROXY_BINDINGS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ASC_REQ_ALLOW_MISSING_BINDINGS</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AcceptorContextRequestFlags</command:parameterValue> <dev:type> <maml:name>AcceptorContextRequestFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>NONE</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the input to the stepping call. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>The input buffers that are required are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the output to the stepping cal. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>When using the sec buffer type value, the context requirement flag `ASC_REQ_ALLOCATE_MEMORY` should be set which has SSPI allocate the memory for the output generated. Otherwise a pre-allocated byte array should be specified for any output buffers needed. Pre-allocated byte arrays should be large enough to contain the data that is needed.</maml:para> <maml:para>The output buffers specified are used directly by SSPI so the input byte value may be mutated as it is. The return value also contains the `Buffers` property which is another reference to the output buffers that were used with SSPI.</maml:para> <maml:para>The output buffers used are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TargetDataRep</maml:name> <maml:description> <maml:para>Controls how the output buffer data is to be aligned.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SECURITY_NETWORK_DREP</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECURITY_NATIVE_DREP</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">TargetDataRep</command:parameterValue> <dev:type> <maml:name>TargetDataRep</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>SECURITY_NATIVE_DREP</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The SSPI security context created with `New-SecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext</command:parameterValue> <dev:type> <maml:name>SecurityContext</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ContextReq</maml:name> <maml:description> <maml:para>Request options to use when creating the context. Some options only work for certain security providers. Requesting one of these options isn't guaranteed to be set once the context is complete, check the `Flags` value on the output result to verify the requested options were set on the context.</maml:para> <maml:para>The `ASC_REQ_ALLOCATE_MEMORY` flag should be set if the output buffers need to be allocated by SSPI.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AcceptorContextRequestFlags</command:parameterValue> <dev:type> <maml:name>AcceptorContextRequestFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>NONE</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the input to the stepping call. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>The input buffers that are required are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the output to the stepping cal. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>When using the sec buffer type value, the context requirement flag `ASC_REQ_ALLOCATE_MEMORY` should be set which has SSPI allocate the memory for the output generated. Otherwise a pre-allocated byte array should be specified for any output buffers needed. Pre-allocated byte arrays should be large enough to contain the data that is needed.</maml:para> <maml:para>The output buffers specified are used directly by SSPI so the input byte value may be mutated as it is. The return value also contains the `Buffers` property which is another reference to the output buffers that were used with SSPI.</maml:para> <maml:para>The output buffers used are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TargetDataRep</maml:name> <maml:description> <maml:para>Controls how the output buffer data is to be aligned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TargetDataRep</command:parameterValue> <dev:type> <maml:name>TargetDataRep</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>SECURITY_NATIVE_DREP</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.AcceptResult</maml:name> </dev:type> <maml:description> <maml:para>The result from the accept call. This object contains the following properties:</maml:para> <maml:para>+ `Result` - The current status of the stepping call, use this to determine what the next step should be</maml:para> <maml:para>+ `Buffers` - The output buffers from the stepping call, the buffer types correspond to the `-OutputBuffer` values specified</maml:para> <maml:para>+ `Flags` - The context attributes, these should be ignored until `Result` is `Ok`</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------- Example 1: Set up a Kerberos security context --------</maml:title> <dev:code>PS C:\> $cred = Get-SSPICredential -Package Kerberos -CredentialUse SECPKG_CRED_OUTBOUND PS C:\> $ctx = New-SecContext -Credential $cred PS C:\> $inToken = Receive-SecToken -Client client.domain.com PS C:\> $res = Step-AcceptSecContext -Context $ctx -InputBuffer $inToken -OutputBuffer SECBUFFER_TOKEN -ContextReq ISC_REQ_ALLOCATE_MEMORY PS C:\> if ($res.Buffers) { ... Send-SecToken -Client client.domain.com -Data $res.Buffers[0].Data ... } PS C:\> "done"</dev:code> <dev:remarks> <maml:para>Creates a servr context for Kerberos and exchanges the tokens with the client. The code also optionally sends the output token to the client if there was one for mutual authentication.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Step-AcceptSecContext.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>AcceptSecurityContext</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-acceptsecuritycontext</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Step-InitSecContext</command:name> <command:verb>Step</command:verb> <command:noun>InitSecContext</command:noun> <maml:description> <maml:para>Steps through a clients security context exchange.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Performs an exchange of security tokens required to set up a security context. This is the first operation that should be performed on a security context and is required before the context can be used for other operations, like encryption.</maml:para> <maml:para>Because the number of calls required relies on the security provider being used, this function may need to be called multiple times. Check the `Result` value on the output object to see what needs to happen next. These are the following result values that can be returned:</maml:para> <maml:para>+ `Ok` - The context is complete no more stepping is required</maml:para> <maml:para>+ `CompleteAndContinue` - A call to `Complete-AuthToken` (TBD) is required and one final token from the peer should be passed to `Step-InitSecContext`</maml:para> <maml:para>+ `CompleteNeeded` - A call to `Complete-AuthToken` (TBD) is required</maml:para> <maml:para>+ `ContinueNeeded` - The output token should be exchanged with the peer and input passed back into `Step-InitSecContext`</maml:para> <maml:para>On the common security providers, NTLM, Kerberos, and Negotiate, the `Ok` and `ContinueNeeded` responses are expected.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Step-InitSecContext</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The SSPI security context created with `New-SecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext</command:parameterValue> <dev:type> <maml:name>SecurityContext</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Target</maml:name> <maml:description> <maml:para>The service target name the client is authenticating against. The value that should be used here depends on the SSPI security provider being called. For `NTLM`, `Kerberos`, `Negotiate` this should be the Service Principal Name (`SPN`). For Schannel this is typically the server name used to validate the certificate.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ContextReq</maml:name> <maml:description> <maml:para>Request options to use when creating the context. Some options only work for certain security providers. Requesting one of these options isn't guaranteed to be set once the context is complete, check the `Flags` value on the output result to verify the requested options were set on the context.</maml:para> <maml:para>The `ISC_REQ_ALLOCATE_MEMORY` flag should be set if the output buffers need to be allocated by SSPI.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">NONE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_DELEGATE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_MUTUAL_AUTH</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_REPLAY_DETECT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_SEQUENCE_DETECT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_CONFIDENTIALITY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_USE_SESSION_KEY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_PROMPT_FOR_CREDS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_USE_SUPPLIED_CREDS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_ALLOCATE_MEMORY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_USE_DCE_STYLE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_DATAGRAM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_CONNECTION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_CALL_LEVEL</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_FRAGMENT_SUPPLIED</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_EXTENDED_ERROR</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_STREAM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_INTEGRITY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_IDENTIFY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_NULL_SESSION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_MANUAL_CRED_VALIDATION</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_RESERVED1</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_FRAGMENT_TO_FIT</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_FORWARD_CREDENTIALS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_NO_INTEGRITY</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_USE_HTTP_STYLE</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_UNVERIFIED_TARGET_NAME</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ISC_REQ_CONFIDENTIALITY_ONLY</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">InitiatorContextRequestFlags</command:parameterValue> <dev:type> <maml:name>InitiatorContextRequestFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>NONE</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the input to the stepping call. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>The input buffers that are required are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the output to the stepping cal. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>When using the sec buffer type value, the context requirement flag `ISC_REQ_ALLOCATE_MEMORY` should be set which has SSPI allocate the memory for the output generated. Otherwise a pre-allocated byte array should be specified for any output buffers needed. Pre-allocated byte arrays should be large enough to contain the data that is needed.</maml:para> <maml:para>The output buffers specified are used directly by SSPI so the input byte value may be mutated as it is. The return value also contains the `Buffers` property which is another reference to the output buffers that were used with SSPI.</maml:para> <maml:para>The output buffers used are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TargetDataRep</maml:name> <maml:description> <maml:para>Controls how the output buffer data is to be aligned.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">SECURITY_NETWORK_DREP</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SECURITY_NATIVE_DREP</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">TargetDataRep</command:parameterValue> <dev:type> <maml:name>TargetDataRep</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>SECURITY_NATIVE_DREP</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>The SSPI security context created with `New-SecContext`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityContext</command:parameterValue> <dev:type> <maml:name>SecurityContext</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ContextReq</maml:name> <maml:description> <maml:para>Request options to use when creating the context. Some options only work for certain security providers. Requesting one of these options isn't guaranteed to be set once the context is complete, check the `Flags` value on the output result to verify the requested options were set on the context.</maml:para> <maml:para>The `ISC_REQ_ALLOCATE_MEMORY` flag should be set if the output buffers need to be allocated by SSPI.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">InitiatorContextRequestFlags</command:parameterValue> <dev:type> <maml:name>InitiatorContextRequestFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>NONE</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the input to the stepping call. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>The input buffers that are required are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputBuffer</maml:name> <maml:description> <maml:para>The security buffers to use as the output to the stepping cal. This can be specified in 3 different ways</maml:para> <maml:para>+ A byte array which is used as a `SECBUFFER_TOKEN` input buffer</maml:para> <maml:para>+ A class that implements `ISecBuffer` that can be generated by `New-SecBuffer` or `New-ChannelBindingBuffer`</maml:para> <maml:para>+ A sec buffer type that generates an empty/null buffer for that type</maml:para> <maml:para>When using the sec buffer type value, the context requirement flag `ISC_REQ_ALLOCATE_MEMORY` should be set which has SSPI allocate the memory for the output generated. Otherwise a pre-allocated byte array should be specified for any output buffers needed. Pre-allocated byte arrays should be large enough to contain the data that is needed.</maml:para> <maml:para>The output buffers specified are used directly by SSPI so the input byte value may be mutated as it is. The return value also contains the `Buffers` property which is another reference to the output buffers that were used with SSPI.</maml:para> <maml:para>The output buffers used are dependent on the SSPI security provider being called.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ISecBuffer[]</command:parameterValue> <dev:type> <maml:name>ISecBuffer[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Target</maml:name> <maml:description> <maml:para>The service target name the client is authenticating against. The value that should be used here depends on the SSPI security provider being called. For `NTLM`, `Kerberos`, `Negotiate` this should be the Service Principal Name (`SPN`). For Schannel this is typically the server name used to validate the certificate.</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="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TargetDataRep</maml:name> <maml:description> <maml:para>Controls how the output buffer data is to be aligned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TargetDataRep</command:parameterValue> <dev:type> <maml:name>TargetDataRep</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>SECURITY_NATIVE_DREP</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSSPI.InitializeResult</maml:name> </dev:type> <maml:description> <maml:para>The result from the initialize call. This object contains the following properties:</maml:para> <maml:para>+ `Result` - The current status of the stepping call, use this to determine what the next step should be</maml:para> <maml:para>+ `Buffers` - The output buffers from the stepping call, the buffer types correspond to the `-OutputBuffer` values specified</maml:para> <maml:para>+ `Flags` - The context attributes, these should be ignored until `Result` is `Ok`</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------- Example 1: Set up a Kerberos security context --------</maml:title> <dev:code>PS C:\> $spn = "host/server.domain.com" PS C:\> $ctx = New-SecContext -Credential (Get-SSPICredential -Package Kerberos) PS C:\> $res = Step-InitSecContext -Context $ctx -Target $spn -OutputBuffer SECBUFFER_TOKEN -ContextReq ISC_REQ_ALLOCATE_MEMORY PS C:\> Send-SecToken -Server server.domain.com -Data $res.Buffers[0].Data PS C:\> $inToken = Receive-SecToken -Server server.domain.com PS C:\> if ($inToken) { ... $null = Step-InitSecContext -Context $ctx -Target $spn -InputBuffer $inToken ... } PS C:\> "done"</dev:code> <dev:remarks> <maml:para>Creates a client context for Kerberos and exchanges the tokens to the server. The code also optionally processes the input token from the server if there was one for mutual authentication.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSSPI/blob/main/docs/en-US/Step-InitSecContext.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>InitializeSecurityContext</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/sspi/nf-sspi-initializesecuritycontextw</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |