Differences
This shows you the differences between the selected revisions of the page.
| library_sessionoptions 2014-06-03 | library_sessionoptions 2023-09-28 (current) | ||
| Line 1: | Line 1: | ||
| ====== SessionOptions Class ====== | ====== SessionOptions Class ====== | ||
| - | Defines information to allow an automatic connection and authentication of the session. Is used with ''[[library_session_open|Session.Open]]'' method. | + | Defines information to allow an automatic connection and authentication of the session. Is used with the ''[[library_session_open|Session.Open]]'' and ''[[library_session_scanfingerprint|Session.ScanFingerprint]]'' methods. |
| + | |||
| + | You can have WinSCP [[ui_generateurl|generate a code template]] for ''SessionOptions'' for you. | ||
| ~~AD~~ | ~~AD~~ | ||
| Line 19: | Line 21: | ||
| | SessionOptions() | Default constructor. | | | SessionOptions() | Default constructor. | | ||
| - | ===== Properties ===== | + | ===== [[properties]] Properties ===== |
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| - | | FtpMode FtpMode | FTP mode. Possible values are ''FtpMode.Passive'' (default) and ''FtpMode.Active''. | | + | | FtpMode ==FtpMode== | [[ftp_modes|FTP mode]]. Possible values are ''FtpMode.Passive'' (default) and ''FtpMode.Active''. | |
| - | | FtpSecure FtpSecure | [[ftps|FTPS]] mode. Possible values are ''FtpSecure.None'' (default), ''FtpSecure.Implicit'', ''FtpSecure.ExplicitTls'' and ''FtpSecure.ExplicitSsl''. | | + | | FtpSecure ==FtpSecure== | [[ftps#methods|FTPS mode]]. Possible values are ''FtpSecure.None'' (default), ''FtpSecure.Implicit'' and ''FtpSecure.Explicit''. | |
| - | | bool GiveUpSecurityAndAcceptAnySshHostKey | Give up security and accept any [[ssh#verifying_the_host_key|SSH host key]]. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. To maintain security, use ''SshHostKeyFingerprint''. | | + | | <del>bool ==GiveUpSecurityAndAcceptAnySshHostKey==</del> | Give up security and accept any [[ssh_verifying_the_host_key|SSH host key]]. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. To maintain security, use [[#sshhostkeyfingerprint|''SshHostKeyFingerprint'']]. //Obsoleted, use [[#sshhostkeypolicy|''SshHostKeyPolicy.GiveUpSecurityAndAcceptAny'']] instead.// | |
| - | | bool GiveUpSecurityAndAcceptAnyTlsHostCertificate | Give up security and accept any FTPS server [[ftps#certificate|TLS/SSL certificate]]. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. To maintain security, use ''TlsHostCertificateFingerprint''. | | + | | bool ==GiveUpSecurityAndAcceptAnyTlsHostCertificate== | Give up security and accept any FTPS/WebDAVS server [[tls#certificate|TLS/SSL certificate]]. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. To maintain security, use [[#tlshostcertificatefingerprint|''TlsHostCertificateFingerprint'']]. | |
| - | | string HostName | Name of the host to connect to. Mandatory property. | | + | | string ==HostName== | Name or IP of the host to connect to. Mandatory property. In a form of ''example.com'' or ''192.0.2.0''. | |
| - | | string Password | Password for authentication. | | + | | string ==Name== | Returns a generated name of a session, based on available information -- typically ''UserName@HostName''. Read-only. | |
| - | | int PortNumber | Port number to connect to. Keep default ''0'' to use the default port for the protocol. | | + | | string ==NewPassword== | When set, tries to [[task_change_password|change password]] to the new one. | |
| - | | Protocol Protocol | Protocol to use for the session. Possible values are ''Protocol.Sftp'' (default), ''Protocol.Scp'' and ''Protocol.Ftp''. | | + | | string ==Password== | Password for authentication. | |
| - | | string SshHostKeyFingerprint | Fingerprint of SSH server [[ssh#verifying_the_host_key|host key]] (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|accept host key]] with the fingerprint. Mandatory for SFTP/SCP protocol.((You can leave the property ''null'', if you set ''GiveUpSecurityAndAcceptAnySshHostKey''; or if you set ''[[library_session#properties|Session.DefaultConfiguration]]'' to ''false'' and make sure the host key is already accepted in the [[config|configuration]], only (not recommended).)) //Learn how to [[faq_script_hostkey|obtain host key fingerprint]]//. | | + | | int ==PortNumber== | Port number to connect to. Keep default ''0'' to use the default port for the protocol. | |
| - | | string SshPrivateKeyPath | Full path to private key file. The key has to be passphrase-less or [[ui_pageant|Pageant]] has to be running with the key loaded (''SshPrivateKeyPath'' then serves only to select, what private key Pageant should use, in case more keys are loaded). | | + | | string ==PrivateKeyPassphrase== | Passphrase for encrypted private keys and client certificates. | |
| - | | string TlsHostCertificateFingerprint | Fingerprint of FTPS server [[ftps#certificate|TLS/SSL certificate]] to be automatically accepted (useful for certificates signed by untrusted authority). | | + | | Protocol ==Protocol== | Protocol to use for the session. Possible values are ''Protocol.Sftp'' (default), ''Protocol.Scp'', ''Protocol.Ftp'', ''Protocol.Webdav'' and ''Protocol.%%S3%%''. \\ When set to ''%%S3%%'', and [[#hostname|''HostName'']] is not set yet, it is set to ''s3.amazonaws.com'' and [[#secure|''Secure'']] is enabled. | |
| - | | TimeSpan Timeout | Server response timeout. Defaults to 15 seconds. | | + | | string ==RootPath== | WebDAV root path or S3 bucket path. Set, when the HTTP server root or S3 bucket list is not accessible. | |
| - | | string UserName | Username for authentication. Mandatory property. | | + | | bool ==Secure== | Use encrypted connection (TLS/SSL) with WebDAV or S3. Default is ''false''. | |
| + | | [[dotnet>system.security.securestring|SecureString]] ==SecureNewPassword== | When set, tries to [[task_change_password|change password]] to the new one. Use instead of [[#newpassword|''NewPassword'']] to reduce a number of unencrypted copies of the password in memory. | | ||
| + | | [[dotnet>system.security.securestring|SecureString]] ==SecurePassword== | Encrypted password for authentication. Use instead of [[#password|''Password'']] to reduce a number of unencrypted copies of the password in memory. | | ||
| + | | [[dotnet>system.security.securestring|SecurePrivateKeyPassphrase]] ==SecurePrivateKeyPassphrase== | Encrypted passphrase for encrypted private keys and client certificates. Use instead of [[#privatekeypassphrase|''PrivateKeyPassphrase'']] to reduce a number of unencrypted copies of the passphrase in memory. | | ||
| + | | string ==SshHostKeyFingerprint== | Fingerprint of SSH server [[ssh_verifying_the_host_key|host key]] (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically [[scripting#hostkey|accept host key]] with the fingerprint. Use SHA-256 fingerprint of the host key. Mandatory for SFTP/SCP protocol.((You can leave the property ''null'', if you set [[#sshhostkeypolicy|''SshHostKeyPolicy'']] to a different value than ''SshHostKeyPolicy.Check''.)) //Learn how to [[faq_hostkey|obtain host key fingerprint]]//. | | ||
| + | | SshHostKeyPolicy ==SshHostKeyPolicy== | SSH host key policy. Use the default ''SshHostKeyPolicy.Check'' to [[ssh_verifying_the_host_key|verify the host key]] against [[#sshhostkeyfingerprint|''SshHostKeyFingerprint'']]. Use ''SshHostKeyPolicy.GiveUpSecurityAndAcceptAny'' to give up a security and accept any SSH host key. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. Use ''SshHostKeyPolicy.AcceptNew'' to automatically accept host key of new hosts. The known keys are cached in registry. | | ||
| + | | string ==SshPrivateKey== | SSH [[public_key#private|Private key file]] contents. | | ||
| + | | string ==SshPrivateKeyPath== | Full path to SSH [[public_key#private|private key file]]. | | ||
| + | | string ==TlsClientCertificatePath== | Full path to [[tls#client_certificate|TLS/SSL client certificate]]. | | ||
| + | | string ==TlsHostCertificateFingerprint== | Fingerprint of FTPS/WebDAVS server [[tls#certificate|TLS/SSL certificate]] to be automatically accepted (useful for certificates signed by an untrusted authority). Use SHA-256 fingerprint of the certificate. | | ||
| + | | TimeSpan ==Timeout== | Server response timeout. Defaults to 15 seconds. | | ||
| + | | int ==TimeoutInMilliseconds== | Alternative to [[#timeout|''Timeout'']]. Particularly useful for COM hosts, that cannot use ''TimeSpan'', such as Visual Basic. | | ||
| + | | string ==UserName== | Username for authentication. Mandatory property. | | ||
| + | | <del>bool ==WebdavSecure==</del> | Obsolete. Use [[#secure|''Secure'']]. | | ||
| ===== Methods ===== | ===== Methods ===== | ||
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| - | | void AddRawSettings(string setting, string value) | Allows configuring any site settings using [[rawsettings|raw format]] as in an INI file. \\ E.g. to enable SSH compression and agent forwarding use ''%%AddRawSettings("Compression", "1")%%'' and ''%%AddRawSettings("AgentFwd", "1")%%''. | | + | | [[library_sessionoptions_addrawsettings|AddRawSettings]] | Allows configuring any site settings using raw format as in an INI file. | |
| + | | [[library_sessionoptions_parseurl|ParseUrl]] | Parses session URL into its components. | | ||
| + | | ToString | Returns [[#name|''Name'']]. (Overrides ''Object.ToString()''.) | | ||
| ===== Remarks ===== | ===== Remarks ===== | ||
| - | You need to fill in all properties required to connect and authenticate your session automatically. | + | When using the ''SessionOptions'' instance with the ''[[library_session_open|Session.Open]]'', you need to fill in all properties required to connect and authenticate your session automatically. |
| - | You always need to fill in ''Protocol'', ''HostName'' and ''UserName''·((Except for very rare occasions that the server does not require username.)). | + | You always need to fill in ''Protocol'', ''HostName'' and ''UserName''.((Except for very rare occasions that the server does not require username.)) |
| In most cases you need to fill in ''Password''. Exceptions are: | In most cases you need to fill in ''Password''. Exceptions are: | ||
| - | * You use different authentication method than a password authentication, such as [[public_key|public key authetication]] (with passphrase-less private key or with use of [[ui_pageant|Pageant]]) for SSH session; | + | * You use different authentication method than a password authentication, such as [[public_key|public key authentication]] for SSH session; |
| * The server does not require password. | * The server does not require password. | ||
| - | For SSH (SFTP/SCP) session you need to fill in the ''SshHostKeyFingerprint'' to verify the expected [[ssh#verifying_the_host_key|server host key]]. | + | For SSH (SFTP/SCP) session you need to fill in the ''SshHostKeyFingerprint'' to verify the expected [[ssh_verifying_the_host_key|server host key]]. |
| ===== Example ===== | ===== Example ===== | ||