Default actions for all events of a hash (e.g., all requests) can be set using the '*' wildcard as the event. (Most hashes have default actions configured by default, these can be found in the description of the proxy classes.) It is important to note that setting the action using the '*' wildcard does NOT override an action explicitly defined for an event, even if the explicit setting precedes the general one in the Python code. This feature is illustrated in the example below.

class MyFtp1(FtpProxy):
	def config(self):
		self.request["APPE"] = (FTP_REQ_REJECT)
		self.request["*"] = (FTP_REQ_ACCEPT)

class MyFtp2(FtpProxy):
	def config(self):
		self.request["*"] = (FTP_REQ_ACCEPT)
		self.request["APPE"] = (FTP_REQ_REJECT)

Responses in certain protocols include numeric response codes, e.g., in the FTP protocol responses start with a three-digit code. In Zorp it is possible to filter these codes as well, furthermore, to filter them based on the command to which the response arrives to. In these cases the hash contains both the command and the answer, and an action as well. The '*' wildcard character can be used to match for every command or response code.

class MyFtp1(FtpProxy):
	def config(self):
		self.response["DELE", "250"] = (FTP_RSP_ACCEPT)
		self.response["*", "250"] = (FTP_RSP_REJECT)
		self.response["LIST", "*"] = (FTP_RSP_ACCEPT)

It is not necessary to specify the full response code, it is also possible to specify only the first, or the first two digits.

For example, all three response codes presented below are valid, but have different effects:

This kind of response code lookup is available in the following proxies: FTP, HTTP, NNTP, and SMTP. The precedence how the hash table entries are processed is the following:

Proxy stacking is mainly used to inspect embedded protocols, or perform virus filtering: e.g., to inspect HTTPS traffic, the external SSL protocol is examined with a Pssl proxy, and then a HTTP proxy is stacked to inspect the internal protocol. It is possible to stack several layers of proxies into each other if needed, e.g., in the above example, a further virus filtering solution (like a CF module) could be stacked into the HTTP proxy.

Stacking a proxy to inspect the embedded protocol is possible via the self.request_stack attribute; if another attribute has to be used, it is noted in the description of the given proxy. The HTTP proxy is special in the sense that it is possible to stack different proxies into the requests and the responses.

The parameters of the stack attribute has to specify the following:

The use of proxy stacking is illustrated in the following example:

class HttpsPsslProxy(PsslProxy):
	def config(self):
		PsslProxy.config(self)
		self.stack_proxy=(Z_STACK_PROXY, HttpProxy)

For additional information on proxy stacking, see Section 6.6.3, Analyzing embedded traffic in Proxedo Network Security Suite 1.0 Administrator Guide, and the various tutorials available at the Documentation Page.

When stacking a program, the data received by a proxy within a protocol is directed to the standard input. Arbitrary commands (including command line scripts, or applications) working from the standard input can be run on this data stream. The original proxy obtains the processed data back from the standard output. When stacking a command, the command to be called has to be included in the proper stack attribute of the proxy between double-quotes. This is illustrated in the following example.

class MyHttp(HttpProxy):
	def config(self):
		HttpProxy.config(self)
		self.response_stack["GET"] = /
		(HTTP_STK_DATA, (Z_STACK_PROGRAM, "/bin/sed '/http:/s//https:/g'"))

The SSL framework inspects SSL/TLS connections, and also any other connections embedded into the encrypted SSL/TLS channel. SSL/TLS connections initiated from the client are terminated on the firewall, and two separate SSL/TLS connections are built: one between the client and the firewall, and one between the firewall and the server. If both connections match the configuration settings of Application-level Gateway (for example, the certificates are valid, and only the allowed encryption algorithms are used), Application-level Gateway inspects the protocol embedded into the secure channel as well. Note that the configuration settings can be different for the two connections, for example, it is possible to permit different protocol versions and encryption settings.

When a firewall rule matches an incoming connection, Application-level Gateway starts the Service specified in the firewall rule to inspect the connection. The Encryption policy set in the Service determines the encryption settings used in the connection.

Depending on the scenario (TwoSidedEncryption, ClientOnlyEncryption, and so on) set in the Encryption policy, the SSL framework selects the first peer to perform the SSL handshake with.

As part of the handshake process, Application-level Gateway checks if encryption is required on the given side. It is not necessary for SSL to be enabled on both sides - Application-level Gateway can handle one-sided SSL connections as well (for example, the firewall communicates in an unencrypted channel with the client, but in a secure channel with the server). If SSL is not enabled, the handshake is skipped for that side.

When SSL is needed, the Service collects the required parameters (keys, certificates, and so on) from the Encryption policy.

The SSL handshake is slightly different for the client (in this case Application-level Gateway behaves as an SSL server) and the server (when Application-level Gateway behaves as an SSL client):

Starting with version 6.0, PNS supports session reuse in SSL and TLS connections. PNS supports both session identifiers (RFC 5246) and session tickets (RFC 5077). Note that session tickets can be used only in TLS connections. Unless explicitly disabled in the configuration of the Encryption policy (for details, see Section 5.5, Module Encryption), PNS attempts to use session tickets, and automatically falls back to using session identifiers if needed.

This section describes the configuration blocks of Encryption policies and objects used in Encryption policies. Encryption policies were designed to be flexible, and make encryption settings easy to re-use in different services.

An Encryption policy is an object that has a unique name, and references a fully-configured encryption scenario.

Encryption scenarios are actually Python classes that describe how encryption is used in a particular connection, for example, both the server-side and the client-side connection is encrypted, or the connection uses a one-sided SSL connection, and so on. Encryption scenarios also reference other classes that contain the actual settings for the scenario. Depending on the scenario, the following classes can be set for the client-side, the server-side, or both.

Application-level Gateway provides the following built-in encryption scenarios:

For examples on configuring Encryption policies, see How to configure SSL proxying in PNS 1.0. For details on HTTPS-specific problems and its solutions, see How to configure HTTPS proxying in PNS 1.0.

To configure Encryption policies, you have to create an Encryption policy, and derive and configure your own scenario from the available built-in scenarios. To configure a scenario, you have to derive and configure your own certificate generator, certificate verifier, and protocol settings classes. (Do not change the built-in classes directly, because that changes the default behavior of Application-level Gateway, and can have unexpected and unwanted effects on the configuration of Application-level Gateway.)

For a details on configuring Encryption Policies, see the following procedure, or the How to configure SSL proxying in PNS 1.0 tutorial.

Application-level Gateway is able to automatically verify the certificates received. The types of accepted certificates can be controlled separately on the client and the server side using the attributes of the ClientCertificateVerifier and ServerCertificateVerifier classes (or your own classes derived from these), respectively. These attributes offer an easy way to restrict encrypted access only to sites having trustworthy certificates. The available options are summarized in the following table. (The text in parentheses refers to the respective value in older PNS versions.)

To accept peers with invalid certificates, set the permit_invalid_certificates to TRUE.

By default (if the check_subject parameter is set to TRUE in the verifier), Application-level Gateway compares the domain name provided in the Subject field of the server certificate to application-level information about the server (that is, the domain name of the URL in HTTP and HTTPS connections).

EncryptionPolicy(
    name="MyTLSEncryption",
    encryption=TwoSidedEncryption(
        client_verify=None,
        server_verify=ServerCertificateVerifier(
            ca_directory="/etc/ca.d/certs/",
            crl_directory="/etc/ca.d/crls/",
            permit_invalid_certificates=TRUE,
            check_subject=FALSE)
            )

The following sections describe and show examples to common protocol-level TLS settings.

EncryptionPolicy(
    name="MyTLSEncryption",
    encryption=TwoSidedEncryption(
        client_verify=None,
        server_verify=ServerCertificateVerifier(
            ca_directory="/etc/ca.d/certs/",
            crl_directory="/etc/ca.d/crls/",
            )
        client_ssl_options=ServerSSLOptions(disable_proto_tlsv1=TRUE),
        server_ssl_options=ServerSSLOptions(disable_proto_tlsv1=TRUE),
            )
        )

Application-level Gateway supports the STARTTLS method for encrypting connections. STARTTLS support can be configured separately for the client- and server side. Currently, the following proxies support STARTTLS: Ftp proxy (to start FTPS sessions), Smtp proxy.

STARTTLS is enabled by default in the following encryption scenarios:

class FtpsProxy(FtpProxy):
    def config(self):
        FtpProxy.config(self)
        self.max_password_length=64

    EncryptionPolicy(name="ForwardSTARTTLS", encryption=ForwardStartTLSEncryption(client_verify=ClientCertificateVerifier(), client_ssl_options=ClientSSLOptions(), server_verify=ServerCertificateVerifier(), server_ssl_options=ServerSSLOptions(), client_certificate_generator=DynamicCertificate(private_key=PrivateKey.fromFile(key_file_path="/etc/key.d/ZMS_Engine/key.pem"), trusted_ca=Certificate.fromFile(certificate_file_path="/etc/ca.d/certs/my-trusted-ca-cert.pem", private_key=PrivateKey.fromFile("/etc/ca.d/keys/my-trusted-ca-cert.pem")), untrusted_ca=Certificate.fromFile(certificate_file_path="/etc/ca.d/certs/my-untrusted-ca-cert.pem", private_key=PrivateKey.fromFile("/etc/ca.d/keys/my-untrusted-ca-cert.pem")))))

    def demo() :
        Service(name='demo/MyFTPSService', router=TransparentRouter(), chainer=ConnectChainer(), proxy_class=FtpsProxy, max_instances=0, max_sessions=0, keepalive=Z_KEEPALIVE_NONE, encryption_policy="ForwardSTARTTLS")

    Rule(rule_id=2,
    proto=6,
    service='demo/MyFTPSService'
    )

A certificate name behaves as a string, and contains a DN in the following format (also known as one-line format):

/RDN=value/RDN=value/.../RDN=value/

The word RDN stands for relative distinguished name. For example, the DN cn=Root CA, ou=CA Group, o=Foo Ltd, l=Bar, st=Foobar State, c=US becomes /C=US/ST=Foobar State/L=Bar/O=Foo Ltd/OU=CA Group/CN=Root CA/

A certifying authority may revoke the issued certificates. A revocation means that the serial number and the revocation date is added to the list of revoked certificates. Revocations are published on a regular basis. This list is called the Certificate Revocation List, also known as CRL. A CRL always has an issuer, a date when the list was published, and the expected date of its next update.

The proxy stores trusted CA certificates in a Certificate hash. This hash can be indexed by two different types. If an integer index is used, the slot specified by this value is looked up; if a string index is used, it is interpreted as a one-line DN value, and the appropriate certificate is looked up. Each slot in this hash contains an X.509 certificate.

Similarly to the certificate hash, a separate hash for storing Certificate Revocation Lists was defined. A CRL contains revocation lists associated to CAs.

This class encapsulates AnyPy, a proxy module calling a Python function to do all of its work. It can be used for defining proxies for protocols not directly supported by Zorp.

This class encapsulates AnyPy, a proxy module calling a Python function to do all of its work. It can be used for defining proxies for protocols not directly supported by Zorp.

Finger is a request/response based User Information Protocol using port TCP/79. The client opens a connection to the remote machine to initiate a request. The client sends a one line query based on the Finger query specification and waits for the answer. A remote user information program (RUIP) processes the query, returns the result and closes the connection. The response is a series of lines consisting of printable ASCII closed carriage return-line feed (CRLF, ASCII13, ASCII10). After receiving the answer the client closes the connection as well.

The following queries can be used:

Finger is a module built for parsing messages of the Finger protocol. It reads the QUERY at the client side, parses it and - if the local security policy permits - sends it to the server. When the RESPONSE arrives it processes the RESPONSE and sends it back to the client. It is possible to prepend and/or append a string to the response. Requests can also be manipulated in various ways using the fingerRequest function, which is called by the proxy if it is defined.

Length of the username, the line and the hostname can be limited by setting various attributes. Finger proxy also has the capability of limiting the number of hosts in a request, e.g.: finger user@domain@server normally results in fingering 'user@domain' performed by the host 'server'. By default, the proxy removes everything after and including the first '@' character. This behavior can be modified by setting the max_hop_count attribute to a non-zero value.

def MyFingerProxy(FingerProxy):
        def config(self):
                FingerProxy.config(self)
                self.max_hop_count = 2
                self.timeout = 30

This proxy implements the Finger protocol as specified in RFC 1288.

Simple FingerProxy based on AbstractFingerProxy.

File Transfer Protocol (FTP) is a protocol to transport files via a reliable TCP connection between a client and a server. FTP uses two reliable TCP connections to transfer files: a simple TCP connection (usually referred to as the Control Channel) to transfer control information and a secondary TCP connection (usually referred to as the Data Channel) to perform the data transfer. It uses a command/response based approach, i.e. the client issues a command and the server responds with a 3-digit status code and associated status information in text format. The Data Channel can be initiated either from the client or the server; the Control Channel is always started from the client.

The client is required to authenticate itself before other commands can be issued. This is performed using the USER and PASS commands specifying username and password, respectively.

220 FTP server ready
USER account
331 Password required.
PASS password
230 User logged in.
SYST
215 UNIX Type: L8
PASV
227 Entering passive mode (192,168,1,1,4,0)
LIST
150 Opening ASCII mode data connection for file list
226-Transferring data in separate connection complete.
226 Quotas off
QUIT
221 Goodbye

FtpProxy is a module built for parsing commands of the Control Channel in the FTP protocol. It reads the REQUEST at the client side, parses it and - if the local security policy permits - sends it to the server. The proxy parses the arriving RESPONSES and sends them to the client if the policy permits that. FtpProxy uses a PlugProxy to transfer the data arriving in the Data Channel. The proxy is capable of manipulating commands and stacking further proxies into the Data Channel. Both transparent and non-transparent modes are supported.

The default low-level proxy implementation (AbstractFtpProxy) denies all requests by default. Different commands and/or responses can be enabled by using one of the several predefined proxy classes which are suitable for most tasks. Alternatively, use of the commands can be permitted individually using different attributes. This is detailed in the following two sections.

class AnonFtp(FtpProxy):
        def config(self):
                self.request["USER"] = (FTP_REQ_POLICY, self.pUser)
                self.request["*"] = (FTP_REQ_ACCEPT)

        def pUser(self,command):
                if self.request_parameter == "anonymous" or self.request_parameter == "Anonymous":
                        return FTP_REQ_ACCEPT
                return FTP_REQ_REJECT

class FtpsProxy(FtpProxy):
    def config(self):
        FtpProxy.config(self)
        self.max_password_length=64

    EncryptionPolicy(name="ForwardSTARTTLS", encryption=ForwardStartTLSEncryption(client_verify=ClientCertificateVerifier(), client_ssl_options=ClientSSLOptions(), server_verify=ServerCertificateVerifier(), server_ssl_options=ServerSSLOptions(), client_certificate_generator=DynamicCertificate(private_key=PrivateKey.fromFile(key_file_path="/etc/key.d/ZMS_Engine/key.pem"), trusted_ca=Certificate.fromFile(certificate_file_path="/etc/ca.d/certs/my-trusted-ca-cert.pem", private_key=PrivateKey.fromFile("/etc/ca.d/keys/my-trusted-ca-cert.pem")), untrusted_ca=Certificate.fromFile(certificate_file_path="/etc/ca.d/certs/my-untrusted-ca-cert.pem", private_key=PrivateKey.fromFile("/etc/ca.d/keys/my-untrusted-ca-cert.pem")))))

    def demo() :
        Service(name='demo/MyFTPSService', router=TransparentRouter(), chainer=ConnectChainer(), proxy_class=FtpsProxy, max_instances=0, max_sessions=0, keepalive=Z_KEEPALIVE_NONE, encryption_policy="ForwardSTARTTLS")

    Rule(rule_id=2,
    proto=6,
    service='demo/MyFTPSService'
    )

<ftp user>@<proxy user>@<remote site>[:<port>]

<ftp password>@<proxy password>

<ftp user>@<proxy user>@<remote site>[:<port>]:<ftp password>@<proxy password>

This proxy implements the FTP protocol as specified in RFC 959. All traffic and commands are denied by default. Consequently, either customized Ftp proxy classes derived from the abstract class should be used, or one of the predefined classes (e.g.: FtpProxy, FtpProxyRO, etc.).

A permitting Ftp proxy based on the AbstractFtpProxy, allowing all commands, responses, and features, including unknown ones. The connection is terminated if a response with the answer code 421 is received.

FTP proxy based on AbstractFtpProxy, enabling read-only access (i.e. only downloading) to anonymous users (uploads and usernames other than 'anonymous' or 'ftp' are disabled). Commands and return codes are strictly checked, unknown commands and responses are rejected. Every feature is accepted.

The ABOR; ACCT; AUTH; CDUP; CWD; EPRT; EPSV; FEAT; LIST; MODE; MDTM; NLST; NOOP; OPTS; PASV; PASS; PORT; PWD; QUIT; REST; RETR; SIZE; STAT; STRU; SYST; TYPE; and USER commands are permitted, the CLNT; XPWD; MACB commands are rejected.

FTP proxy based on AbstractFtpProxy, enabling full read-write access to anonymous users (the 'anonymous' and 'ftp' usernames are permitted). Commands and return codes are strictly checked, unknown commands and responses are rejected. Every feature is accepted.

The ABOR; ACCT; APPE; CDUP; CWD; DELE; EPRT; EPSV; LIST; MKD; MODE; MDTM; NLST; NOOP; OPTS; PASV; PASS; PORT; PWD; QUIT; RMD; RNFR; RNTO; REST; RETR; SIZE; STAT; STOR; STOU; STRU; SYST; TYPE; USER and FEAT commands are permitted, the AUTH; CLNT; XPWD; MACB commands are rejected.

FTP proxy based on AbstractFtpProxy, enabling read-only access to any user. Commands and return codes are strictly checked, unknown commands and responses are rejected. Every feature is accepted.

The ABOR; ACCT; AUTH; CDUP; CWD; EPRT; EPSV; FEAT; LIST; MODE; MDTM; NLST; NOOP; OPTS; PASV; PASS; PORT; PWD; QUIT; REST; RETR; SIZE; STAT; STRU; SYST; TYPE; and USER commands are permitted, the CLNT; XPWD; MACB commands are rejected.

FTP proxy based on AbstractFtpProxy, enabling full read-write access to any user. Commands and return codes are strictly checked, unknown commands and responses are rejected. Every feature is accepted.

The ABOR; ACCT; AUTH; CDUP; CWD; EPRT; EPSV; FEAT; LIST; MODE; MDTM; NLST; NOOP; OPTS; PASV; PASS; PORT; PWD; QUIT; REST; RETR; SIZE; STAT; STRU; SYST; TYPE; and USER commands are permitted, the CLNT; XPWD; MACB commands are rejected.

HTTP is an open application layer protocol for hypermedia information systems. It basically allows an open-ended set of methods to be applied to resources identified by Uniform Resource Identifiers (URIs).

GET /index.html HTTP/1.1
Host: www.example.com
Connection: keep-alive
User-Agent: My-Browser-Type 6.0

HTTP/1.1 200 OK
Connection: close
Content-Length: 14

<html>
</html>

The default low-level proxy implementation (AbstractHttpProxy) denies all requests by default. Different requests and/or responses can be enabled by using one of the several predefined proxy classes which are suitable for most tasks. Alternatively, a custom proxy class can be derived from AbstractHttpProxy and the requests and responses enabled individually using different attributes.

Several examples and considerations on how to enable virus filtering in the HTTP traffic are discussed in the Technical White Paper and Tutorial Virus filtering in HTTP, available at the BalaSys Documentation Page http://www.balasys.hu/documentation/.

GET http://www.example.com/index.html HTTP/1.1
Host: www.example.com
Connection: keep-alive
User-Agent: My-Browser-Type 6.0

HTTP/1.1 200 OK
Connection: close
Content-Length: 14

<html>
</html>

CONNECT www.example.com:443 HTTP/1.1
Host: www.example.com
User-agent: My-Browser-Type 6.0

HTTP/1.0 200 Connection established
Proxy-agent: My-Proxy/1.1

class DmzHTTP(HttpProxy):
        def config(self):
                HttpProxy.config(self)
                self.request["GET"] = (HTTP_REQ_POLICY, self.filterURL)

        def filterURL(self, method, url, version):
                if (url == "http://www.disallowedsite.com"):
                        self.error_info = 'Access of this content is denied by the local policy.'
                        return HTTP_REQ_REJECT
                return HTTP_REQ_ACCECT

class DmzHTTP(HttpProxy):
        def config(self):
                HttpProxy.config(self)
                self.response["GET", "404"] = (HTTP_RSP_POLICY, self.filter404)

        def filter404(self, method, url, version, response):
                self.error_status = 404
                self.error_info = "Requested page was not accessible."
                return HTTP_RSP_REJECT

class MyHttp(HttpProxy):
        def config(self):
                HttpProxy.config(self)
                self.request_header["User-Agent"] = (HTTP_HDR_CHANGE_VALUE, "Lynx 2.4.1")
                self.request_header["Cookie"] = (HTTP_HDR_POLICY, self.processCookies)
                self.response_header["Set-Cookie"] = (HTTP_HDR_DROP,)

        def processCookies(self, name, value):
                # You could change the current header in self.current_header_name
                # or self.current_header_value, the current request url is
                # in self.request_url
                return HTTP_HDR_DROP

class MyHttp(HttpProxy):
        def config(self):
                HttpProxy.config(self)
                self.request["GET"] = (HTTP_REQ_POLICY, self.filterURL)

        def filterURL(self, method, url, version):
                self.request_url = "http://www.example.com/"
                return HTTP_REQ_ACCEPT

class HttpProxyHttpsredirect(HttpProxy):
        def config(self):
                HttpProxy.config(self)
                self.error_silent = TRUE
                self.request["GET"] = (HTTP_REQ_POLICY, self.reqRedirect)

        def reqRedirect(self, method, url, version):
                self.error_status = 301
                #self.error_info = 'HTTP/1.0 301 Moved Permanently'
                self.error_headers="Location: https://%s/" % self.request_url_host
                return HTTP_REQ_REJECT

class MyHttp(HttpProxy):
        def config(self):
                HttpProxy.config(self)
                self.parent_proxy = "proxy.example.com"
                self.parent_proxy_port = 3128

def instance():
        Service("http", MyHttp, router=InbandRouter())
        Listener(SockAddrInet('10.0.0.1', 80), "http")

This class implements an abstract HTTP proxy - it serves as a starting point for customized proxy classes, but is itself not directly usable. Service definitions should refer to a customized class derived from AbstractHttpProxy, or one of the predefined proxy classes, such as HttpProxy or HttpProxyNonTransparent. AbstractHttpProxy denies all requests by default.

HttpProxy is a default HTTP proxy based on AbstractHttpProxy. It is transparent, and enables the most commonly used HTTP methods: "GET", "POST" and "HEAD".

HTTP proxy based on HttpProxy. This class is identical to HttpProxy with the only difference being that it is non-transparent (transparent_mode = FALSE). Consequently, clients must be explicitly configured to connect to this proxy instead of the target server and issue proxy requests. On the server side this proxy connects transparently to the target server.

For the correct operation the proxy must be able to set the server address on its own. This can be accomplished by using InbandRouter.

HTTP proxy based on HttpProxy, having URL filtering capability. The matcher attribute should be initialized to refer to a Matcher object. The initialization should be done in the class body as shown in the next example.

class MyHttp(HttpProxyURIFilter):
    matcher = RegexpFileMatcher('/etc/zorp/blacklist.txt',                                     '/etc/zorp/whitelist.txt')

HTTP proxy based on HttpProxyURIFilter, but operating in non-transparent mode (transparent_mode = FALSE).

HTTP proxy based on HttpProxy, also capable of inspecting WebDAV extensions of the HTTP protocol.

The following requests are permitted: PROPFIND; PROPPATCH; MKCOL; COPY; MOVE; LOCK; UNLOCK.

HTTP proxy based on HttpProxyNonTransparent, operating in non-transparent mode (transparent_mode = FALSE) and capable of inspecting WebDAV extensions of the HTTP protocol.

The following requests are permitted: PROPFIND; PROPPATCH; MKCOL; COPY; MOVE; LOCK; UNLOCK.

This class implements a general plug proxy, and is capable of optionally disabling data transfer in either direction. Plug proxy reads connection on the client side, then creates another connection at the server side. Arriving responses are sent back to the client. However, it is not a protocol proxy, therefore PlugProxy does not implement any protocol analysis. It offers protection to clients and servers from lower level (e.g.: IP) attacks. It is mainly used to allow traffic pass the firewall for which there is no protocol proxy available.

By default plug copies all data in both directions. To change this behavior, set the copy_to_client or copy_to_server attribute to FALSE.

Plug supports the use of secondary sessions. For details, see Section 2.2, Secondary sessions.

Plug proxy is not a protocol specific proxy module, therefore it is not specified in standards.

An abstract proxy class for transferring data.

A default PlugProxy based on AbstractPlugProxy.

Post Office Protocol version 3 (POP3) is usually used by mail user agents (MUAs) to download messages from a remote mailbox. POP3 supports a single mailbox only, it does not support advanced multi-mailbox operations offered by alternatives such as IMAP.

The POP3 protocol uses a single TCP connection to give access to a single mailbox. It uses a simple command/response based approach, the client issues a command and a server can respond either positively or negatively.

+OK POP3 server ready
USER account
+OK User name is ok
PASS password
+OK Authentication successful
LIST
+OK Listing follows
1 5758
2 232323
3 3434
.
RETR 1
+OK Mail body follows
From: sender@sender.com
To: account@receiver.com
Subject: sample mail

This is a sample mail message. Lines beginning with
..are escaped, another '.' character is perpended which
is removed when the mail is stored by the client.
.
DELE 1
+OK Mail deleted
QUIT
+OK Good bye

Pop3Proxy is a module built for parsing messages of the POP3 protocol. It reads and parses COMMANDs on the client side, and sends them to the server if the local security policy permits. Arriving RESPONSEs are parsed as well, and sent to the client if the local security policy permits. It is possible to manipulate both the requests and the responses.

class APop3(Pop3Proxy):
        def config(self):
                Pop3Proxy.config(self)
                self.request["USER"] = (POP3_REQ_REJECT)
                self.request["APOP"] = (POP3_REQ_ACCEPT)

class UToAPop3(Pop3Proxy):
        def config(self):
                Pop3Proxy.config(self)
                self.request["USER"] = (POP3_REQ_POLICY,self.DropUSER)
                self.request["PASS"] = (POP3_REQ_POLICY,self.UToA)

        def DropUSER(self,command):
                self.response_value = "+OK"
                self.response_param = "User ok Send Password"
                return POP3_REQ_REJECT

        def UToA(self,command):
                # Username is stored in self->username,
                # password in self->request_param,
                # and the server timestamp in self->timestamp,
                # consequently the digest can be calculated.
                # NOTE: This is only an example, calcdigest must be
                # implemented separately
                digest = calcdigest(self->timestamp+self->request_param)
                self->request_command = "APOP"
                self->request_param = name + " " + digest
                return POP3_REQ_ACCEPT

class NeutralPop3(Pop3Proxy):
        def config(self):
        Pop3Proxy.config(self)
        self.request["GREETING"] = (POP3_REQ_POLICY, None, self.rewriteBanner)

        def rewriteBanner(self, response)
                self.response_param = "Pop3 server ready"
                return POP3_RSP_ACCEPT

This class implements an abstract POP3 proxy - it serves as a starting point for customized proxy classes, but is itself not directly usable. Service definitions should refer to a customized class derived from AbstractPop3Proxy, or a predefined Pop3Proxy proxy class. AbstractPop3Proxy denies all requests by default.