// // IMailService.cs // // Author: Jeffrey Stedfast // // Copyright (c) 2013-2020 .NET Foundation and Contributors // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to deal // in the Software without restriction, including without limitation the rights // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell // copies of the Software, and to permit persons to whom the Software is // furnished to do so, subject to the following conditions: // // The above copyright notice and this permission notice shall be included in // all copies or substantial portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // THE SOFTWARE. // using System; using System.IO; using System.Net; using System.Text; using System.Threading; using System.Net.Sockets; using System.Net.Security; using System.Threading.Tasks; using System.Collections.Generic; using System.Security.Cryptography.X509Certificates; using SslProtocols = System.Security.Authentication.SslProtocols; using MailKit.Net.Proxy; using MailKit.Security; namespace MailKit { /// /// An interface for message services such as SMTP, POP3, or IMAP. /// /// /// Implemented by /// and . /// public interface IMailService : IDisposable { /// /// Gets an object that can be used to synchronize access to the folder. /// /// /// Gets an object that can be used to synchronize access to the folder. /// /// The sync root. object SyncRoot { get; } /// /// Gets or sets the SSL and TLS protocol versions that the client is allowed to use. /// /// /// Gets or sets the SSL and TLS protocol versions that the client is allowed to use. /// By default, MailKit initializes this value to support only TLS v1.0 and greater and /// does not support any version of SSL due to those protocols no longer being considered /// secure. /// This property should be set before calling any of the /// Connect methods. /// /// The SSL and TLS protocol versions that are supported. SslProtocols SslProtocols { get; set; } /// /// Get or set the client SSL certificates. /// /// /// Some servers may require the client SSL certificates in order /// to allow the user to connect. /// This property should be set before calling any of the /// Connect methods. /// /// The client SSL certificates. X509CertificateCollection ClientCertificates { get; set; } /// /// Get or set whether connecting via SSL/TLS should check certificate revocation. /// /// /// Gets or sets whether connecting via SSL/TLS should check certificate revocation. /// Normally, the value of this property should be set to true (the default) for security /// reasons, but there are times when it may be necessary to set it to false. /// For example, most Certificate Authorities are probably pretty good at keeping their CRL and/or /// OCSP servers up 24/7, but occasionally they do go down or are otherwise unreachable due to other /// network problems between the client and the Certificate Authority. When this happens, it becomes /// impossible to check the revocation status of one or more of the certificates in the chain /// resulting in an being thrown in the /// Connect method. If this becomes a problem, /// it may become desirable to set to false. /// /// true if certificate revocation should be checked; otherwise, false. bool CheckCertificateRevocation { get; set; } /// /// Get or sets a callback function to validate the server certificate. /// /// /// Gets or sets a callback function to validate the server certificate. /// This property should be set before calling any of the /// Connect methods. /// /// /// /// /// The server certificate validation callback function. RemoteCertificateValidationCallback ServerCertificateValidationCallback { get; set; } /// /// Get or set the local IP end point to use when connecting to a remote host. /// /// /// Gets or sets the local IP end point to use when connecting to a remote host. /// /// The local IP end point or null to use the default end point. IPEndPoint LocalEndPoint { get; set; } /// /// Get or set the proxy client to use when connecting to a remote host. /// /// /// Gets or sets the proxy client to use when connecting to a remote host via any of the /// Connect methods. /// /// The proxy client. IProxyClient ProxyClient { get; set; } /// /// Get the authentication mechanisms supported by the message service. /// /// /// The authentication mechanisms are queried durring the /// Connect method. /// /// The supported authentication mechanisms. HashSet AuthenticationMechanisms { get; } /// /// Get whether or not the client is currently authenticated with the mail server. /// /// /// Gets whether or not the client is currently authenticated with the mail server. /// To authenticate with the mail server, use one of the /// Authenticate methods /// or any of the Async alternatives. /// /// true if the client is authenticated; otherwise, false. bool IsAuthenticated { get; } /// /// Get whether or not the service is currently connected. /// /// /// The state is set to true immediately after /// one of the Connect /// methods succeeds and is not set back to false until either the client /// is disconnected via or until a /// is thrown while attempting to read or write to /// the underlying network socket. /// When an is caught, the connection state of the /// should be checked before continuing. /// /// true if the service connected; otherwise, false. bool IsConnected { get; } /// /// Get whether or not the connection is secure (typically via SSL or TLS). /// /// /// Gets whether or not the connection is secure (typically via SSL or TLS). /// /// true if the connection is secure; otherwise, false. bool IsSecure { get; } /// /// Get or set the timeout for network streaming operations, in milliseconds. /// /// /// Gets or sets the underlying socket stream's /// and values. /// /// The timeout in milliseconds. int Timeout { get; set; } /// /// Establish a connection to the specified mail server. /// /// /// Establish a connection to the specified mail server. /// If a successful connection is made, the /// property will be populated. /// /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// true if the client should make an SSL-wrapped connection to the server; otherwise, false. /// The cancellation token. /// /// is null. /// /// /// is not between 0 and 65535. /// /// /// The is a zero-length string. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// void Connect (string host, int port, bool useSsl, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously establish a connection to the specified mail server. /// /// /// Asynchronously establishes a connection to the specified mail server. /// If a successful connection is made, the /// property will be populated. /// /// An asynchronous task context. /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// true if the client should make an SSL-wrapped connection to the server; otherwise, false. /// The cancellation token. /// /// The is null. /// /// /// is not between 0 and 65535. /// /// /// The is a zero-length string. /// /// /// The has been disposed. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// Task ConnectAsync (string host, int port, bool useSsl, CancellationToken cancellationToken = default (CancellationToken)); /// /// Establish a connection to the specified mail server. /// /// /// Establish a connection to the specified mail server. /// If a successful connection is made, the /// property will be populated. /// /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// The secure socket options to when connecting. /// The cancellation token. /// /// is null. /// /// /// is not between 0 and 65535. /// /// /// The is a zero-length string. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// void Connect (string host, int port = 0, SecureSocketOptions options = SecureSocketOptions.Auto, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously establish a connection to the specified mail server. /// /// /// Asynchronously establishes a connection to the specified mail server. /// If a successful connection is made, the /// property will be populated. /// /// An asynchronous task context. /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// The secure socket options to when connecting. /// The cancellation token. /// /// The is null. /// /// /// is not between 0 and 65535. /// /// /// The is a zero-length string. /// /// /// The has been disposed. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// Task ConnectAsync (string host, int port = 0, SecureSocketOptions options = SecureSocketOptions.Auto, CancellationToken cancellationToken = default (CancellationToken)); /// /// Establish a connection to the specified mail server using the provided socket. /// /// /// Establish a connection to the specified mail server using the provided socket. /// If a successful connection is made, the /// property will be populated. /// /// The socket to use for the connection. /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// The secure socket options to when connecting. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// is not between 0 and 65535. /// /// /// is not connected. /// -or- /// The is a zero-length string. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// void Connect (Socket socket, string host, int port = 0, SecureSocketOptions options = SecureSocketOptions.Auto, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously establish a connection to the specified mail server using the provided socket. /// /// /// Asynchronously establishes a connection to the specified mail server using the provided socket. /// If a successful connection is made, the /// property will be populated. /// /// An asynchronous task context. /// The socket to use for the connection. /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// The secure socket options to when connecting. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// is not between 0 and 65535. /// /// /// is not connected. /// -or- /// The is a zero-length string. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// Task ConnectAsync (Socket socket, string host, int port = 0, SecureSocketOptions options = SecureSocketOptions.Auto, CancellationToken cancellationToken = default (CancellationToken)); /// /// Establish a connection to the specified mail server using the provided stream. /// /// /// Establish a connection to the specified mail server using the provided stream. /// If a successful connection is made, the /// property will be populated. /// /// The stream to use for the connection. /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// The secure socket options to when connecting. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// is not between 0 and 65535. /// /// /// The is a zero-length string. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// void Connect (Stream stream, string host, int port = 0, SecureSocketOptions options = SecureSocketOptions.Auto, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously establish a connection to the specified mail server using the provided stream. /// /// /// Asynchronously establishes a connection to the specified mail server using the provided stream. /// If a successful connection is made, the /// property will be populated. /// /// An asynchronous task context. /// The stream to use for the connection. /// The host name to connect to. /// The port to connect to. If the specified port is 0, then the default port will be used. /// The secure socket options to when connecting. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// is not between 0 and 65535. /// /// /// The is a zero-length string. /// /// /// The is already connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// Task ConnectAsync (Stream stream, string host, int port = 0, SecureSocketOptions options = SecureSocketOptions.Auto, CancellationToken cancellationToken = default (CancellationToken)); /// /// Authenticate using the supplied credentials. /// /// /// Authenticates using the supplied credentials. /// If the server supports one or more SASL authentication mechanisms, then /// the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// /// The user's credentials. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// void Authenticate (ICredentials credentials, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously authenticate using the supplied credentials. /// /// /// Asynchronously authenticates using the supplied credentials. /// If the server supports one or more SASL authentication mechanisms, then /// the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// /// An asynchronous task context. /// The user's credentials. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// Task AuthenticateAsync (ICredentials credentials, CancellationToken cancellationToken = default (CancellationToken)); /// /// Authenticate using the supplied credentials. /// /// /// Authenticates using the supplied credentials. /// If the server supports one or more SASL authentication mechanisms, then /// the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// /// The encoding to use for the user's credentials. /// The user's credentials. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// void Authenticate (Encoding encoding, ICredentials credentials, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously authenticate using the supplied credentials. /// /// /// Asynchronously authenticates using the supplied credentials. /// If the server supports one or more SASL authentication mechanisms, then /// the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// /// An asynchronous task context. /// The encoding to use for the user's credentials. /// The user's credentials. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// Task AuthenticateAsync (Encoding encoding, ICredentials credentials, CancellationToken cancellationToken = default (CancellationToken)); /// /// Authenticate using the specified user name and password. /// /// /// If the server supports one or more SASL authentication mechanisms, /// then the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// To prevent the usage of certain authentication mechanisms, /// simply remove them from the hash set /// before calling this method. /// /// The encoding to use for the user's credentials. /// The user name. /// The password. /// The cancellation token. /// /// is null. /// -or- /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected or is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// void Authenticate (Encoding encoding, string userName, string password, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously authenticate using the specified user name and password. /// /// /// If the server supports one or more SASL authentication mechanisms, /// then the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// To prevent the usage of certain authentication mechanisms, /// simply remove them from the hash set /// before calling this method. /// /// An asynchronous task context. /// The encoding to use for the user's credentials. /// The user name. /// The password. /// The cancellation token. /// /// is null. /// -or- /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected or is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// Task AuthenticateAsync (Encoding encoding, string userName, string password, CancellationToken cancellationToken = default (CancellationToken)); /// /// Authenticate using the specified user name and password. /// /// /// If the server supports one or more SASL authentication mechanisms, /// then the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// To prevent the usage of certain authentication mechanisms, /// simply remove them from the hash set /// before calling this method. /// /// /// /// /// The user name. /// The password. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected or is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// void Authenticate (string userName, string password, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously authenticate using the specified user name and password. /// /// /// If the server supports one or more SASL authentication mechanisms, /// then the SASL mechanisms that both the client and server support are tried /// in order of greatest security to weakest security. Once a SASL /// authentication mechanism is found that both client and server support, /// the credentials are used to authenticate. /// If the server does not support SASL or if no common SASL mechanisms /// can be found, then the default login command is used as a fallback. /// To prevent the usage of certain authentication mechanisms, /// simply remove them from the hash set /// before calling this method. /// /// An asynchronous task context. /// The user name. /// The password. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected or is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// Task AuthenticateAsync (string userName, string password, CancellationToken cancellationToken = default (CancellationToken)); /// /// Authenticate using the specified SASL mechanism. /// /// /// Authenticates using the specified SASL mechanism. /// For a list of available SASL authentication mechanisms supported by the server, /// check the property after the service has been /// connected. /// /// The SASL mechanism. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected or is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// void Authenticate (SaslMechanism mechanism, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously authenticate using the specified SASL mechanism. /// /// /// Authenticates using the specified SASL mechanism. /// For a list of available SASL authentication mechanisms supported by the server, /// check the property after the service has been /// connected. /// /// An asynchronous task context. /// The SASL mechanism. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected or is already authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// Authentication using the supplied credentials has failed. /// /// /// A SASL authentication error occurred. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// Task AuthenticateAsync (SaslMechanism mechanism, CancellationToken cancellationToken = default (CancellationToken)); /// /// Disconnect the service. /// /// /// Disconnects from the service. /// If is true, a "QUIT" command will be issued in order to disconnect cleanly. /// /// If set to true, a "QUIT" command will be issued in order to disconnect cleanly. /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// void Disconnect (bool quit, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously disconnect the service. /// /// /// Asynchronously disconnects from the service. /// If is true, a "QUIT" command will be issued in order to disconnect cleanly. /// /// An asynchronous task context. /// If set to true, a logout/quit command will be issued in order to disconnect cleanly. /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// Task DisconnectAsync (bool quit, CancellationToken cancellationToken = default (CancellationToken)); /// /// Ping the message service to keep the connection alive. /// /// /// Mail servers, if left idle for too long, will automatically drop the connection. /// /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// void NoOp (CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously ping the mail server to keep the connection alive. /// /// /// Mail servers, if left idle for too long, will automatically drop the connection. /// /// An asynchronous task context. /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The command was rejected by the mail server. /// /// /// The server responded with an unexpected token. /// Task NoOpAsync (CancellationToken cancellationToken = default (CancellationToken)); /// /// Occurs when the client has been successfully connected. /// /// /// The event is raised when the client /// successfully connects to the mail server. /// event EventHandler Connected; /// /// Occurs when the client has been disconnected. /// /// /// The event is raised whenever the client /// has been disconnected. /// event EventHandler Disconnected; /// /// Occurs when the client has been successfully authenticated. /// /// /// The event is raised whenever the client /// has been authenticated. /// event EventHandler Authenticated; } }