Zorp GPL 7 Reference Guide

Balasys

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)

Linux™ is a registered trademark of Linus Torvalds.

Windows™ 10 is registered trademarks of Microsoft Corporation.

The Balasys™ name and the Balasys™ logo are registered trademarks of Balasys IT Zrt.

The Zorp™ name and the Zorp™ logo are registered trademarks of Balasys IT Zrt.

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

DISCLAIMER

Balasys is not responsible for any third-party websites mentioned in this document. Balasys 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. Balasys 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.

May 30, 2024


Table of Contents

Preface
1. Summary of contents
2. Terminology
3. Target audience and prerequisites
4. Products covered in this guide
5. Contact and support information
5.1. Sales contact
5.2. Support contact
5.3. Training
6. About this document
6.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 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 HttpProxyURLCategoryFilter
4.7.11. Class HttpWebdavProxy
4.7.12. 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.9.7. Class Pop3STLSProxy
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 AvailabilityChainer
5.3.5. Class ConnectChainer
5.3.6. Class FailoverChainer
5.3.7. Class MultiTargetChainer
5.3.8. Class RoundRobinAvailabilityChainer
5.3.9. Class RoundRobinChainer
5.3.10. Class SideStackChainer
5.3.11. Class StateBasedChainer
5.4. Module Detector
5.4.1. Classes in the Detector module
5.4.2. Class AbstractDetector
5.4.3. Class CertDetector
5.4.4. Class DetectorPolicy
5.4.5. Class HttpDetector
5.4.6. Class SniDetector
5.4.7. Class SshDetector
5.5. Module Encryption
5.5.1. SSL parameter constants
5.5.2. Classes in the Encryption module
5.5.3. Class AbstractVerifier
5.5.4. Class Certificate
5.5.5. Class CertificateCA
5.5.6. Class ClientCertificateVerifier
5.5.7. Class ClientNoneVerifier
5.5.8. Class ClientOnlyEncryption
5.5.9. Class ClientOnlyStartTLSEncryption
5.5.10. Class ClientSSLOptions
5.5.11. Class DHParam
5.5.12. Class DynamicCertificate
5.5.13. Class DynamicServerEncryption
5.5.14. Class EncryptionPolicy
5.5.15. Class FakeStartTLSEncryption
5.5.16. Class ForwardStartTLSEncryption
5.5.17. Class PrivateKey
5.5.18. Class SNIBasedCertificate
5.5.19. Class SSLOptions
5.5.20. Class ServerCertificateVerifier
5.5.21. Class ServerNoneVerifier
5.5.22. Class ServerOnlyEncryption
5.5.23. Class ServerSSLOptions
5.5.24. Class StaticCertificate
5.5.25. Class TwoSidedEncryption
5.6. Module Keybridge
5.6.1. Classes in the Keybridge module
5.6.2. Class X509KeyBridge
5.7. Module Matcher
5.7.1. Classes in the Matcher module
5.7.2. Class AbstractMatcher
5.7.3. Class CombineMatcher
5.7.4. Class DNSMatcher
5.7.5. Class MatcherPolicy
5.7.6. Class RegexpFileMatcher
5.7.7. Class RegexpMatcher
5.7.8. Class SmtpInvalidRecipientMatcher
5.7.9. Class WindowsUpdateMatcher
5.8. Module NAT
5.8.1. Classes in the NAT module
5.8.2. Class AbstractNAT
5.8.3. Class GeneralNAT
5.8.4. Class HashNAT
5.8.5. Class NAT46
5.8.6. Class NAT64
5.8.7. Class NATPolicy
5.8.8. Class OneToOneMultiNAT
5.8.9. Class OneToOneNAT
5.8.10. Class RandomNAT
5.8.11. Class StaticNAT
5.9. Module Notification
5.9.1. Classes in the Notification module
5.9.2. Class AbstractNotificationMethod
5.9.3. Class EmailNotificationMethod
5.9.4. Class NotificationPolicy
5.10. Module Proxy
5.10.1. Functions in module Proxy
5.10.2. Classes in the Proxy module
5.10.3. Functions
5.10.4. Class Proxy
5.11. Module Resolver
5.11.1. Classes in the Resolver module
5.11.2. Class AbstractResolver
5.11.3. Class DNSResolver
5.11.4. Class HashResolver
5.12. Module Router
5.12.1. The source address used in the server-side connection
5.12.2. Classes in the Router module
5.12.3. Class AbstractRouter
5.12.4. Class DirectedRouter
5.12.5. Class InbandRouter
5.12.6. Class TransparentRouter
5.13. Module Rule
5.13.1. Evaluating firewall rules
5.13.2. Sample rules
5.13.3. Adding metadata to rules: tags and description
5.13.4. Classes in the Rule module
5.13.5. Class PortRange
5.13.6. Class Rule
5.14. Module Service
5.14.1. Naming services
5.14.2. Classes in the Service module
5.14.3. Class AbstractService
5.14.4. Class DenyService
5.14.5. Class PFService
5.14.6. Class Service
5.15. Module Session
5.15.1. Classes in the Session module
5.15.2. Class StackedSession
5.16. Module SockAddr
5.16.1. Classes in the SockAddr module
5.16.2. Class SockAddrInet
5.16.3. Class SockAddrInet6
5.16.4. Class SockAddrInetHostname
5.16.5. Class SockAddrInetRange
5.16.6. Class SockAddrUnix
5.17. Module Stack
5.17.1. Classes in the Stack module
5.17.2. Class AbstractStackingBackend
5.17.3. Class RemoteStackingBackend
5.17.4. Class StackingProvider
5.18. Module Zone
5.18.1. Classes in the Zone module
5.18.2. Class Zone
5.19. Module Zorp
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 Stream
6.5.1. Classes in the Stream module
6.5.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 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 GPL 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. Disabling specific TLS protocols
3.2. 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 example
4.15. URL filtering HTTP proxy
4.16. POP3 protocol sample
4.17. Example for allowing only APOP authentication in POP3
4.18. Example for converting simple USER/PASS authentication to APOP in POP3
4.19. Rewriting the banner in POP3
4.20. SMTP protocol sample
4.21. Example for disabling the Telnet X Display Location option
4.22. Rewriting the DISPLAY environment variable
4.23. 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 DirectedRouter using AvailabilityChainer
5.12. A sample ConnectChainer
5.13. A DirectedRouter using FailoverChainer
5.14. A DirectedRouter using RoundRobinAvailabilityChainer
5.15. A DirectedRouter using RoundRobinChainer
5.16. CertDetector example
5.17. HttpDetector example
5.18. SNIDetector example
5.19. SshDetector example
5.20. Loading a certificate
5.21. Loading DH parameters
5.22. Loading a private key
5.23. Whitelisting e-mail recipients
5.24. DNSMatcher example
5.25. RegexpFileMatcher example
5.26. RegexpMatcher example
5.27. SmtpInvalidMatcher example
5.28. WindowsUpdateMatcher example
5.29. GeneralNat example
5.30. Using Natpolicies
5.31. A simple DNSResolver policy
5.32. A simple HashResolver policy
5.33. DirectedRouter example
5.34. InbandRouter example
5.35. TransparentRouter example
5.36. Sample rule definitions
5.37. Tagging rules
5.38. A simple DenyService
5.39. PFService example
5.40. Service example
5.41. SockAddrInet example
5.42. SockAddrInet example
5.43. SockAddrInetHostname example
5.44. SockAddrUnix example
5.45. A simple StackingProvider class
5.46. Using a StackingProvider in an FTP proxy
5.47. Finding IP networks
5.48. Zone examples
5.49. Determining the zone of an IP address
6.1. CSZoneDispatcher example
6.2. Dispatcher example