Zorp GPL 6 Reference Guide

This documentation and the product it describes are considered protected by copyright according to the applicable laws.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

The BalaBit™ name and the BalaBit™ logo are registered trademarks of BalaBit IT Security Ltd..

Hadoop™ and the Hadoop elephant logo are trademarks of the Apache Software Foundation.

Linux™ is a registered trademark of Linus Torvalds.

The syslog-ng™ name and the syslog-ng™ logo are registered trademarks of BalaBit.

Windows™ 95, 98, ME, 2000, XP, Server 2003, Vista, Server 2008, 7, 8, and Server 2013 are registered trademarks of Microsoft Corporation.

All other product names mentioned herein are the trademarks of their respective owners.

DISCLAIMER

BalaBit is not responsible for any third-party Web sites mentioned in this document. BalaBit does not endorse and is not responsible or liable for any content, advertising, products, or other material on or available from such sites or resources. BalaBit will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through any such sites or resources.

April 17, 2015


Table of Contents

Preface
1. Summary of contents
2. Terminology
3. Target audience and prerequisites
4. Products covered in this guide
5. Typographical conventions
6. Contact and support information
6.1. Sales contact
6.2. Support contact
6.3. Training
7. About this document
7.1. Feedback
1. How Zorp works
1.1. Zorp startup and initialization
1.2. Handling incoming connections
1.2.1. Handling packet-filtering services
1.2.2. Handling application-level services
1.3. Proxy startup and the server-side connection
2. Configuring Zorp proxies
2.1. Policies for requests and responses
2.1.1. Default actions
2.1.2. Response codes
2.2. Secondary sessions
2.3. Embedded protocol analysis
2.3.1. Proxy stacking
2.3.2. Program stacking
3. The Zorp SSL framework
3.1. The SSL protocol
3.1.1. The SSL handshake
3.2. Configuring TLS and SSL encrypted connections
3.2.1. Behavior of the SSL framework
3.2.2. Handshake callbacks
3.2.3. X.509 Certificates
3.2.4. Setting the allowed SSL/TLS protocol
3.2.5. SSL cipher selection
3.2.6. Enabling STARTTLS
3.2.7. Keybrigding certificates
3.3. Related standards
3.4. SSL options reference
4. Proxies
4.1. General information on the proxy modules
4.2. Attribute values
4.3. Examples
4.4. Module AnyPy
4.4.1. Related standards
4.4.2. Classes in the AnyPy module
4.4.3. Class AbstractAnyPyProxy
4.4.4. Class AnyPyProxy
4.5. Module Finger
4.5.1. The Finger protocol
4.5.2. Proxy behavior
4.5.3. Related standards
4.5.4. Classes in the Finger module
4.5.5. Class AbstractFingerProxy
4.5.6. Class FingerProxy
4.6. Module Ftp
4.6.1. The FTP protocol
4.6.2. Proxy behavior
4.6.3. Related standards
4.6.4. Classes in the Ftp module
4.6.5. Class AbstractFtpProxy
4.6.6. Class FtpProxy
4.6.7. Class FtpProxyAnonRO
4.6.8. Class FtpProxyAnonRW
4.6.9. Class FtpProxyRO
4.6.10. Class FtpProxyRW
4.7. Module Http
4.7.1. The HTTP protocol
4.7.2. Proxy behavior
4.7.3. Related standards
4.7.4. Classes in the Http module
4.7.5. Class AbstractHttpProxy
4.7.6. Class HttpProxy
4.7.7. Class HttpProxyNonTransparent
4.7.8. Class HttpProxyURIFilter
4.7.9. Class HttpProxyURIFilterNonTransparent
4.7.10. Class HttpWebdavProxy
4.7.11. Class NontransHttpWebdavProxy
4.8. Module Plug
4.8.1. Proxy behavior
4.8.2. Related standards
4.8.3. Classes in the Plug module
4.8.4. Class AbstractPlugProxy
4.8.5. Class PlugProxy
4.9. Module Pop3
4.9.1. The POP3 protocol
4.9.2. Proxy behavior
4.9.3. Related standards
4.9.4. Classes in the Pop3 module
4.9.5. Class AbstractPop3Proxy
4.9.6. Class Pop3Proxy
4.10. Module Smtp
4.10.1. The SMTP protocol
4.10.2. Proxy behavior
4.10.3. Related standards
4.10.4. Classes in the Smtp module
4.10.5. Class AbstractSmtpProxy
4.10.6. Class SmtpProxy
4.11. Module Telnet
4.11.1. The Telnet protocol
4.11.2. Proxy behavior
4.11.3. Related standards
4.11.4. Classes in the Telnet module
4.11.5. Class AbstractTelnetProxy
4.11.6. Class TelnetProxy
4.11.7. Class TelnetProxyStrict
4.12. Module Whois
4.12.1. The Whois protocol
4.12.2. Proxy behavior
4.12.3. Related standards
4.12.4. Classes in the Whois module
4.12.5. Class AbstractWhoisProxy
4.12.6. Class WhoisProxy
5. Core
5.1. Module Auth
5.1.1. Authentication and authorization basics
5.1.2. Authentication and authorization in Zorp
5.1.3. Classes in the Auth module
5.1.4. Class AbstractAuthentication
5.1.5. Class AbstractAuthorization
5.1.6. Class AuthCache
5.1.7. Class AuthenticationPolicy
5.1.8. Class AuthorizationPolicy
5.1.9. Class BasicAccessList
5.1.10. Class InbandAuthentication
5.1.11. Class NEyesAuthorization
5.1.12. Class PairAuthorization
5.1.13. Class PermitGroup
5.1.14. Class PermitTime
5.1.15. Class PermitUser
5.1.16. Class SatyrAuthentication
5.1.17. Class ServerAuthentication
5.1.18. Class ZAAuthentication
5.2. Module AuthDB
5.2.1. Classes in the AuthDB module
5.2.2. Class AbstractAuthenticationBackend
5.2.3. Class AuthenticationProvider
5.2.4. Class ZAS2AuthenticationBackend
5.3. Module Chainer
5.3.1. Selecting the network protocol
5.3.2. Classes in the Chainer module
5.3.3. Class AbstractChainer
5.3.4. Class ConnectChainer
5.3.5. Class FailoverChainer
5.3.6. Class MultiTargetChainer
5.3.7. Class RoundRobinChainer
5.3.8. Class SideStackChainer
5.3.9. Class StateBasedChainer
5.4. Module Config.py
5.5. Module Detector
5.5.1. Classes in the Detector module
5.5.2. Class AbstractDetector
5.5.3. Class CertDetector
5.5.4. Class DetectorPolicy
5.5.5. Class HttpDetector
5.5.6. Class SshDetector
5.6. Module Encryption
5.6.1. SSL parameter constants
5.6.2. Classes in the Encryption module
5.6.3. Class AbstractVerifier
5.6.4. Class Certificate
5.6.5. Class ClientCertificateVerifier
5.6.6. Class ClientOnlyEncryption
5.6.7. Class ClientOnlyStartTLSEncryption
5.6.8. Class ClientSSLOptions
5.6.9. Class DynamicCertificate
5.6.10. Class EncryptionPolicy
5.6.11. Class FakeStartTLSEncryption
5.6.12. Class ForwardStartTLSEncryption
5.6.13. Class PrivateKey
5.6.14. Class SNIBasedCertificate
5.6.15. Class SSLOptions
5.6.16. Class ServerCertificateVerifier
5.6.17. Class ServerOnlyEncryption
5.6.18. Class ServerSSLOptions
5.6.19. Class StaticCertificate
5.6.20. Class TwoSidedEncryption
5.7. Module Keybridge
5.7.1. Classes in the Keybridge module
5.7.2. Class X509KeyBridge
5.8. Module Matcher
5.8.1. Classes in the Matcher module
5.8.2. Class AbstractMatcher
5.8.3. Class CombineMatcher
5.8.4. Class DNSMatcher
5.8.5. Class MatcherPolicy
5.8.6. Class RegexpFileMatcher
5.8.7. Class RegexpMatcher
5.8.8. Class SmtpInvalidRecipientMatcher
5.8.9. Class WindowsUpdateMatcher
5.9. Module NAT
5.9.1. Classes in the NAT module
5.9.2. Class AbstractNAT
5.9.3. Class BalanceNAT
5.9.4. Class GeneralNAT
5.9.5. Class HashNAT
5.9.6. Class NAT46
5.9.7. Class NAT64
5.9.8. Class NATPolicy
5.9.9. Class OneToOneMultiNAT
5.9.10. Class OneToOneNAT
5.9.11. Class RandomNAT
5.9.12. Class StaticNAT
5.10. Module Notification
5.10.1. Classes in the Notification module
5.10.2. Class AbstractNotificationMethod
5.10.3. Class EmailNotificationMethod
5.10.4. Class NotificationPolicy
5.11. Module Proxy
5.11.1. Functions in module Proxy
5.11.2. Classes in the Proxy module
5.11.3. Functions
5.11.4. Class Proxy
5.12. Module Resolver
5.12.1. Classes in the Resolver module
5.12.2. Class AbstractResolver
5.12.3. Class DNSResolver
5.12.4. Class HashResolver
5.12.5. Class ResolverPolicy
5.13. Module Router
5.13.1. The source address used in the server-side connection
5.13.2. Classes in the Router module
5.13.3. Class AbstractRouter
5.13.4. Class DirectedRouter
5.13.5. Class InbandRouter
5.13.6. Class TransparentRouter
5.14. Module Rule
5.14.1. Evaluating firewall rules
5.14.2. Sample rules
5.14.3. Adding metadata to rules: tags and description
5.14.4. Classes in the Rule module
5.14.5. Class PortRange
5.14.6. Class Rule
5.15. Module Service
5.15.1. Naming services
5.15.2. Classes in the Service module
5.15.3. Class AbstractService
5.15.4. Class DenyService
5.15.5. Class PFService
5.15.6. Class Service
5.16. Module Session
5.16.1. Classes in the Session module
5.16.2. Class StackedSession
5.17. Module SockAddr
5.17.1. Classes in the SockAddr module
5.17.2. Class SockAddrInet
5.17.3. Class SockAddrInet6
5.17.4. Class SockAddrInetHostname
5.17.5. Class SockAddrInetRange
5.17.6. Class SockAddrUnix
5.18. Module Stack
5.18.1. Classes in the Stack module
5.18.2. Class AbstractStackingBackend
5.18.3. Class RemoteStackingBackend
5.18.4. Class StackingProvider
5.19. Module Stream
5.19.1. Classes in the Stream module
5.19.2. Class Stream
5.20. Module Zone
5.20.1. Classes in the Zone module
5.20.2. Class Zone
5.21. Module Zorp
5.21.1. Functions in module Zorp
5.21.2. Classes in the Zorp module
5.21.3. Functions
5.21.4. Class ConnectionVerdict
6. Core-internal
6.1. Module Cache
6.2. Module Core
6.3. Module Dispatch
6.3.1. Zone-based service selection
6.3.2. Classes in the Dispatch module
6.3.3. Class CSZoneDispatcher
6.3.4. Class Dispatcher
6.4. Module Globals
6.5. Module Proxy
6.5.1. Functions in module Proxy
6.5.2. Classes in the Proxy module
6.5.3. Functions
6.5.4. Class Proxy
6.6. Module Stream
6.6.1. Classes in the Stream module
6.6.2. Class Stream
A. Additional proxy information
A.1. TELNET appendix
B. Global options of Zorp
B.1. Setting global options of Zorp
blob
audit
options
C. Zorp GPL manual pages
instances.conf zorp(8) instances database
policy.py zorp(8) policy file.
zorp — Zorp Firewall Suite
zorpctl — Start and stop zorp instances.
zorpctl.conf zorpctl(8) configuration file.
D. Zorp Application Level Gateway End-User License Agreement
D.1. 1. SUBJECT OF THE LICENSE CONTRACT
D.2. 2. DEFINITIONS
D.3. 3. LICENSE GRANTS AND RESTRICTIONS
D.4. 4. SUBSIDIARIES
D.5. 5. INTELLECTUAL PROPERTY RIGHTS
D.6. 6. TRADE MARKS
D.7. 7. NEGLIGENT INFRINGEMENT
D.8. 8. INTELLECTUAL PROPERTY INDEMNIFICATION
D.9. 9. LICENSE FEE
D.10. 10. WARRANTIES
D.11. 11. DISCLAIMER OF WARRANTIES
D.12. 12. LIMITATION OF LIABILITY
D.13. 13.DURATION AND TERMINATION
D.14. 14. AMENDMENTS
D.15. 15. WAIVER
D.16. 16. SEVERABILITY
D.17. 17. NOTICES
D.18. 18. MISCELLANEOUS
E. Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License
Index of Proxy attributes
Index of Core attributes
Index of all attributes

List of Examples

2.1. Customizing FTP commands
2.2. Using the POLICY action
2.3. Default and explicit actions
2.4. Customizing response codes
2.5. Example PlugProxy allowing secondary sessions
2.6. HTTP proxy stacked into an HTTPS connection
2.7. Program stacking in HTTP
3.1. Configuring FTPS support
4.1. Controlling the number of max hops
4.2. FTP protocol sample
4.3. Customizing FTP to allow only anonymous sessions
4.4. Configuring FTPS support
4.5. Example HTTP transaction
4.6. Proxy style HTTP query
4.7. Data tunneling with connect method
4.8. Implementing URL filtering in the HTTP proxy
4.9. 404 response filtering in HTTP
4.10. Header filtering in HTTP
4.11. URL redirection in HTTP proxy
4.12. Redirecting HTTP to HTTPS
4.13. Using parent proxies in HTTP
4.14. URL filtering HTTP proxy
4.15. POP3 protocol sample
4.16. Example for allowing only APOP authentication in POP3
4.17. Example for converting simple USER/PASS authentication to APOP in POP3
4.18. Rewriting the banner in POP3
4.19. SMTP protocol sample
4.20. Example for disabling the Telnet X Display Location option
4.21. Rewriting the DISPLAY environment variable
4.22. Example WhoisProxy logging all whois requests
5.1. A simple authentication policy
5.2. Caching authentication decisions
5.3. A simple authorization policy
5.4. BasicAccessList example
5.5. A simple PairAuthorization policy
5.6. A simple PermitGroup policy
5.7. PermitTime example
5.8. A simple PermitUser policy
5.9. Outband authentication example
5.10. A sample authentication provider
5.11. A sample ConnectChainer
5.12. A DirectedRouter using FailoverChainer
5.13. A DirectedRouter using RoundRobinChainer
5.14. CertDetector example
5.15. HttpDetector example
5.16. SshDetector example
5.17. Loading a certificate
5.18. Loading a private key
5.19. Whitelisting e-mail recipients
5.20. DNSMatcher example
5.21. RegexpFileMatcher example
5.22. RegexpMatcher example
5.23. SmtpInvalidMatcher example
5.24. WindowsUpdateMatcher example
5.25. GeneralNat example
5.26. Using Natpolicies
5.27. A simple DNSResolver policy
5.28. A simple HashResolver policy
5.29. DirectedRouter example
5.30. InbandRouter example
5.31. TransparentRouter example
5.32. Sample rule definitions
5.33. Tagging rules
5.34. A simple DenyService
5.35. PFService example
5.36. Service example
5.37. SockAddrInet example
5.38. SockAddrInet example
5.39. SockAddrUnix example
5.40. A simple StackingProvider class
5.41. Using a StackingProvider in an FTP proxy
5.42. Finding IP networks
5.43. Zone examples
5.44. Determining the zone of an IP address
6.1. CSZoneDispatcher example
6.2. Dispatcher example