ipaccess 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. checksums.yaml +5 -13
  2. checksums.yaml.gz.sig +0 -0
  3. data.tar.gz.sig +0 -0
  4. data/.yardopts +2 -0
  5. data/ChangeLog +66 -0
  6. data/Manifest.txt +5 -10
  7. data/README.md +2 -2
  8. data/Rakefile +1 -1
  9. data/docs/HISTORY +11 -0
  10. data/docs/TODO +1 -1
  11. data/docs/yard-tpl/default/fulldoc/html/css/common.css +5 -0
  12. data/examples/open-uri.rb +14 -0
  13. data/examples/telnet.rb +1 -1
  14. data/ipaccess.gemspec +62 -0
  15. data/lib/ipaccess.rb +2 -566
  16. data/lib/ipaccess/arm_sockets.rb +0 -1
  17. data/lib/ipaccess/core.rb +523 -0
  18. data/lib/ipaccess/ghost_doc/ghost_doc.rb +1 -1
  19. data/lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc +54 -0
  20. data/lib/ipaccess/ghost_doc/ghost_doc_net_ftp.rb +35 -19
  21. data/lib/ipaccess/ghost_doc/ghost_doc_net_http.rb +34 -18
  22. data/lib/ipaccess/ghost_doc/ghost_doc_net_smtp.rb +35 -19
  23. data/lib/ipaccess/ghost_doc/ghost_doc_net_telnet.rb +35 -19
  24. data/lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc +65 -0
  25. data/lib/ipaccess/ghost_doc/ghost_doc_sockets.rb +353 -125
  26. data/lib/ipaccess/ip_access_check.rb +2 -2
  27. data/lib/ipaccess/ip_access_errors.rb +2 -2
  28. data/lib/ipaccess/ip_access_list.rb +3 -3
  29. data/lib/ipaccess/patches/generic.rb +150 -183
  30. data/lib/ipaccess/patches/net_ftp.rb +1 -2
  31. data/lib/ipaccess/patches/net_http.rb +10 -14
  32. data/lib/ipaccess/patches/net_imap.rb +1 -2
  33. data/lib/ipaccess/patches/net_pop.rb +2 -4
  34. data/lib/ipaccess/patches/net_smtp.rb +2 -4
  35. data/lib/ipaccess/patches/net_telnet.rb +1 -2
  36. data/lib/ipaccess/patches/sockets.rb +67 -69
  37. data/lib/ipaccess/socket.rb +0 -17
  38. metadata +70 -100
  39. metadata.gz.sig +0 -0
  40. data/lib/ipaccess/ghost_doc/ghost_doc_acl.rb +0 -54
  41. data/lib/ipaccess/ghost_doc/ghost_doc_p_blacklist.rb +0 -36
  42. data/lib/ipaccess/ghost_doc/ghost_doc_p_blacklist_e.rb +0 -7
  43. data/lib/ipaccess/ghost_doc/ghost_doc_p_unblacklist.rb +0 -36
  44. data/lib/ipaccess/ghost_doc/ghost_doc_p_unblacklist_e.rb +0 -7
  45. data/lib/ipaccess/ghost_doc/ghost_doc_p_unwhitelist.rb +0 -36
  46. data/lib/ipaccess/ghost_doc/ghost_doc_p_unwhitelist_e.rb +0 -7
  47. data/lib/ipaccess/ghost_doc/ghost_doc_p_whitelist.rb +0 -36
  48. data/lib/ipaccess/ghost_doc/ghost_doc_p_whitelist_e.rb +0 -7
  49. data/lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rb +0 -64
@@ -10,7 +10,7 @@
10
10
  #
11
11
  #--
12
12
  #
13
- # Copyright (C) 2009 by Paweł Wilk. All Rights Reserved.
13
+ # Copyright (C) 2009-2014 by Paweł Wilk. All Rights Reserved.
14
14
  #
15
15
  # This program is free software; you can redistribute it and/or modify
16
16
  # it under the terms of either: 1) the GNU Lesser General Public License
@@ -0,0 +1,54 @@
1
+ This member selects IPAccess::Set object that will be used to
2
+ control IP access for a socket.
3
+
4
+ === Setting an access set
5
+
6
+ You may assign global access set,
7
+ create local access set or use shared set.
8
+
9
+ - If an argument is +:global+ it uses global access set.
10
+ - If an argument is +:private+ it creates an empty, private access set.
11
+ - If an argument is an IPAccess::Set object then it is used as external, shared set.
12
+
13
+ ==== Global access set
14
+
15
+ Global access set is an IPAccess::Set object referenced by contant IPAccess::Set.Global
16
+ It cannot be modified by calling +acl+ attribute. To add or remove rules
17
+ use mentioned constant. By default all sockets with enabled IP access control
18
+ are using this set.
19
+
20
+ ==== Private access set
21
+
22
+ Private access set is an IPAccess::Set object created for socket object.
23
+ You may modify it by referencing to +acl+ member of the socket object.
24
+
25
+ Under some circumstances it is possible to share private access set
26
+ – you just have to pass the +acl+ member of a socket to initializer
27
+ of new socket object as shared access set.
28
+
29
+ ==== Shared access set
30
+
31
+ Shared access set is an IPAccess::Set object that more than one socket
32
+ may use to control IP access. It differs from private access set
33
+ only by operation used to create. The private access set is created
34
+ automatically and shared access set exists before socket object is
35
+ formed.
36
+
37
+ === Using an access set
38
+
39
+ This member keeps the information about currently
40
+ used access set. You may use it to do low-level
41
+ operations on IPAccess::Set object associated
42
+ with instance. You cannot however call any
43
+ of global access set operations – to do that
44
+ use IPAccess::Set.Global contant referencing to
45
+ global ACL.
46
+
47
+ ==== Manipulating access lists
48
+
49
+ You should avoid manipulating an access set directly to add
50
+ or remove rules in lists. It works fine but under some circumstances
51
+ changes made on working (connected) network object may
52
+ not be noticed immediately. You should use direct methods
53
+ (like blacklist, whitelist, blacklist! and whitelist!)
54
+ to control access for existing network objects.
@@ -28,7 +28,7 @@
28
28
  # class but provides special member called +acl+ and a few new
29
29
  # instance methods for controlling IP access.
30
30
  #
31
- #:include:ghost_doc_patched_usage.rb
31
+ # {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
32
32
  #
33
33
  # This documentation doesn't cover description of all
34
34
  # class and instance methods of the original
@@ -92,29 +92,45 @@
92
92
 
93
93
  class IPAccess::Net::FTP
94
94
 
95
- #:include:ghost_doc_p_whitelist_e.rb
96
- def whitelist!; end
95
+ # {include:IPAccess::Socket#whitelist!}
96
+ # @overload whitelist!(*addresses)
97
+ # @overload whitelist!(list, *addresses)
98
+ def whitelist!(*addresses); end
97
99
 
98
- #:include:ghost_doc_p_whitelist.rb
99
- def whitelist; end
100
+ # {include:IPAccess::Socket#whitelist}
101
+ # @overload whitelist(*addresses)
102
+ # @overload whitelist(list, *addresses)
103
+ def whitelist(*addresses); end
100
104
 
101
- #:include:ghost_doc_p_blacklist_e.rb
102
- def blacklist!; end
105
+ # {include:IPAccess::Socket#blacklist!}
106
+ # @overload blacklist!(*addresses)
107
+ # @overload blacklist!(list, *addresses)
108
+ def blacklist!(*addresses); end
103
109
 
104
- #:include:ghost_doc_p_blacklist.rb
105
- def blacklist; end
110
+ # {include:IPAccess::Socket#blacklist}
111
+ # @overload blacklist(*addresses)
112
+ # @overload blacklist(list, *addresses)
113
+ def blacklist(*addresses); end
106
114
 
107
- #:include:ghost_doc_p_unwhitelist.rb
108
- def unwhitelist; end
109
-
110
- #:include:ghost_doc_p_unwhitelist_e.rb
111
- def unwhitelist!; end
115
+ # {include:IPAccess::Socket#unwhitelist!}
116
+ # @overload unwhitelist!(*addresses)
117
+ # @overload unwhitelist!(list, *addresses)
118
+ def unwhitelist!(*addresses); end
119
+
120
+ # {include:IPAccess::Socket#unwhitelist}
121
+ # @overload unwhitelist(*addresses)
122
+ # @overload unwhitelist(list, *addresses)
123
+ def unwhitelist(*addresses); end
112
124
 
113
- #:include:ghost_doc_p_unblacklist_e.rb
114
- def unblacklist!; end
125
+ #{include:IPAccess::Socket#unblacklist!}
126
+ # @overload unblacklist!(*addresses)
127
+ # @overload unblacklist!(list, *addresses)
128
+ def unblacklist!(*addresses); end
115
129
 
116
- #:include:ghost_doc_p_unblacklist.rb
117
- def unblacklist; end
130
+ #{include:IPAccess::Socket#unblacklist}
131
+ # @overload unblacklist(*addresses)
132
+ # @overload unblacklist(list, *addresses)
133
+ def unblacklist(*addresses); end
118
134
 
119
135
  alias_method :unblock!, :unblacklist!
120
136
  alias_method :del_black!, :unblacklist!
@@ -145,7 +161,7 @@ class IPAccess::Net::FTP
145
161
  # allows to set reason.
146
162
  def blacklist_reasonable(reason, *addresses); end
147
163
 
148
- #:include:ghost_doc_acl.rb
164
+ #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
149
165
  #
150
166
  # === Example
151
167
  #
@@ -28,7 +28,7 @@
28
28
  # provides special member called +acl+ and a few new
29
29
  # instance methods for controlling IP access.
30
30
  #
31
- #:include:ghost_doc_patched_usage.rb
31
+ # {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
32
32
  #
33
33
  # This documentation doesn't cover description of all
34
34
  # class and instance methods of the original
@@ -133,29 +133,45 @@
133
133
 
134
134
  class IPAccess::Net::HTTP
135
135
 
136
- #:include:ghost_doc_p_whitelist_e.rb
137
- def whitelist!; end
136
+ # {include:IPAccess::Socket#whitelist!}
137
+ # @overload whitelist!(*addresses)
138
+ # @overload whitelist!(list, *addresses)
139
+ def whitelist!(*addresses); end
138
140
 
139
- #:include:ghost_doc_p_whitelist.rb
140
- def whitelist; end
141
+ # {include:IPAccess::Socket#whitelist}
142
+ # @overload whitelist(*addresses)
143
+ # @overload whitelist(list, *addresses)
144
+ def whitelist(*addresses); end
141
145
 
142
- #:include:ghost_doc_p_blacklist_e.rb
143
- def blacklist!; end
146
+ # {include:IPAccess::Socket#blacklist!}
147
+ # @overload blacklist!(*addresses)
148
+ # @overload blacklist!(list, *addresses)
149
+ def blacklist!(*addresses); end
144
150
 
145
- #:include:ghost_doc_p_blacklist.rb
146
- def blacklist; end
151
+ # {include:IPAccess::Socket#blacklist}
152
+ # @overload blacklist(*addresses)
153
+ # @overload blacklist(list, *addresses)
154
+ def blacklist(*addresses); end
147
155
 
148
- #:include:ghost_doc_p_unwhitelist_e.rb
149
- def unwhitelist!; end
156
+ # {include:IPAccess::Socket#unwhitelist!}
157
+ # @overload unwhitelist!(*addresses)
158
+ # @overload unwhitelist!(list, *addresses)
159
+ def unwhitelist!(*addresses); end
150
160
 
151
- #:include:ghost_doc_p_unwhitelist.rb
152
- def unwhitelist; end
161
+ # {include:IPAccess::Socket#unwhitelist}
162
+ # @overload unwhitelist(*addresses)
163
+ # @overload unwhitelist(list, *addresses)
164
+ def unwhitelist(*addresses); end
153
165
 
154
- #:include:ghost_doc_p_unblacklist_e.rb
155
- def unblacklist!; end
166
+ #{include:IPAccess::Socket#unblacklist!}
167
+ # @overload unblacklist!(*addresses)
168
+ # @overload unblacklist!(list, *addresses)
169
+ def unblacklist!(*addresses); end
156
170
 
157
- #:include:ghost_doc_p_unblacklist.rb
158
- def unblacklist; end
171
+ #{include:IPAccess::Socket#unblacklist}
172
+ # @overload unblacklist(*addresses)
173
+ # @overload unblacklist(list, *addresses)
174
+ def unblacklist(*addresses); end
159
175
 
160
176
  alias_method :unblock!, :unblacklist!
161
177
  alias_method :del_black!, :unblacklist!
@@ -186,7 +202,7 @@ class IPAccess::Net::HTTP
186
202
  # allows to set reason.
187
203
  def blacklist_reasonable(reason, *addresses); end
188
204
 
189
- #:include:ghost_doc_acl.rb
205
+ #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
190
206
  #
191
207
  # === Example
192
208
  #
@@ -28,7 +28,7 @@
28
28
  # class but provides special member called +acl+ and a few new
29
29
  # instance methods for controlling IP access.
30
30
  #
31
- #:include:ghost_doc_patched_usage.rb
31
+ # {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
32
32
  #
33
33
  # This documentation doesn't cover description of all
34
34
  # class and instance methods of the original
@@ -58,29 +58,45 @@
58
58
 
59
59
  class IPAccess::Net::SMTP
60
60
 
61
- #:include:ghost_doc_p_whitelist_e.rb
62
- def whitelist!; end
61
+ # {include:IPAccess::Socket#whitelist!}
62
+ # @overload whitelist!(*addresses)
63
+ # @overload whitelist!(list, *addresses)
64
+ def whitelist!(*addresses); end
63
65
 
64
- #:include:ghost_doc_p_whitelist.rb
65
- def whitelist; end
66
+ # {include:IPAccess::Socket#whitelist}
67
+ # @overload whitelist(*addresses)
68
+ # @overload whitelist(list, *addresses)
69
+ def whitelist(*addresses); end
66
70
 
67
- #:include:ghost_doc_p_blacklist_e.rb
68
- def blacklist!; end
71
+ # {include:IPAccess::Socket#blacklist!}
72
+ # @overload blacklist!(*addresses)
73
+ # @overload blacklist!(list, *addresses)
74
+ def blacklist!(*addresses); end
69
75
 
70
- #:include:ghost_doc_p_blacklist.rb
71
- def blacklist; end
76
+ # {include:IPAccess::Socket#blacklist}
77
+ # @overload blacklist(*addresses)
78
+ # @overload blacklist(list, *addresses)
79
+ def blacklist(*addresses); end
72
80
 
73
- #:include:ghost_doc_p_unwhitelist.rb
74
- def unwhitelist; end
75
-
76
- #:include:ghost_doc_p_unwhitelist_e.rb
77
- def unwhitelist!; end
81
+ # {include:IPAccess::Socket#unwhitelist!}
82
+ # @overload unwhitelist!(*addresses)
83
+ # @overload unwhitelist!(list, *addresses)
84
+ def unwhitelist!(*addresses); end
85
+
86
+ # {include:IPAccess::Socket#unwhitelist}
87
+ # @overload unwhitelist(*addresses)
88
+ # @overload unwhitelist(list, *addresses)
89
+ def unwhitelist(*addresses); end
78
90
 
79
- #:include:ghost_doc_p_unblacklist_e.rb
80
- def unblacklist!; end
91
+ #{include:IPAccess::Socket#unblacklist!}
92
+ # @overload unblacklist!(*addresses)
93
+ # @overload unblacklist!(list, *addresses)
94
+ def unblacklist!(*addresses); end
81
95
 
82
- #:include:ghost_doc_p_unblacklist.rb
83
- def unblacklist; end
96
+ #{include:IPAccess::Socket#unblacklist}
97
+ # @overload unblacklist(*addresses)
98
+ # @overload unblacklist(list, *addresses)
99
+ def unblacklist(*addresses); end
84
100
 
85
101
  alias_method :unblock!, :unblacklist!
86
102
  alias_method :del_black!, :unblacklist!
@@ -111,7 +127,7 @@ class IPAccess::Net::SMTP
111
127
  # allows to set reason.
112
128
  def blacklist_reasonable(reason, *addresses); end
113
129
 
114
- #:include:ghost_doc_acl.rb
130
+ #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
115
131
  #
116
132
  # === Example
117
133
  #
@@ -28,7 +28,7 @@
28
28
  # provides provides special member called +acl+ and a few new
29
29
  # instance methods for controlling IP access.
30
30
  #
31
- #:include:ghost_doc_patched_usage.rb
31
+ # {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
32
32
  #
33
33
  # This documentation doesn't cover description of all
34
34
  # class and instance methods of the original
@@ -117,29 +117,45 @@
117
117
 
118
118
  class IPAccess::Net::Telnet
119
119
 
120
- #:include:ghost_doc_p_whitelist_e.rb
121
- def whitelist!; end
120
+ # {include:IPAccess::Socket#whitelist!}
121
+ # @overload whitelist!(*addresses)
122
+ # @overload whitelist!(list, *addresses)
123
+ def whitelist!(*addresses); end
122
124
 
123
- #:include:ghost_doc_p_whitelist.rb
124
- def whitelist; end
125
+ # {include:IPAccess::Socket#whitelist}
126
+ # @overload whitelist(*addresses)
127
+ # @overload whitelist(list, *addresses)
128
+ def whitelist(*addresses); end
125
129
 
126
- #:include:ghost_doc_p_blacklist_e.rb
127
- def blacklist!; end
130
+ # {include:IPAccess::Socket#blacklist!}
131
+ # @overload blacklist!(*addresses)
132
+ # @overload blacklist!(list, *addresses)
133
+ def blacklist!(*addresses); end
128
134
 
129
- #:include:ghost_doc_p_blacklist.rb
130
- def blacklist; end
135
+ # {include:IPAccess::Socket#blacklist}
136
+ # @overload blacklist(*addresses)
137
+ # @overload blacklist(list, *addresses)
138
+ def blacklist(*addresses); end
131
139
 
132
- #:include:ghost_doc_p_unwhitelist.rb
133
- def unwhitelist; end
134
-
135
- #:include:ghost_doc_p_unwhitelist_e.rb
136
- def unwhitelist!; end
140
+ # {include:IPAccess::Socket#unwhitelist!}
141
+ # @overload unwhitelist!(*addresses)
142
+ # @overload unwhitelist!(list, *addresses)
143
+ def unwhitelist!(*addresses); end
144
+
145
+ # {include:IPAccess::Socket#unwhitelist}
146
+ # @overload unwhitelist(*addresses)
147
+ # @overload unwhitelist(list, *addresses)
148
+ def unwhitelist(*addresses); end
137
149
 
138
- #:include:ghost_doc_p_unblacklist_e.rb
139
- def unblacklist!; end
150
+ #{include:IPAccess::Socket#unblacklist!}
151
+ # @overload unblacklist!(*addresses)
152
+ # @overload unblacklist!(list, *addresses)
153
+ def unblacklist!(*addresses); end
140
154
 
141
- #:include:ghost_doc_p_unblacklist.rb
142
- def unblacklist; end
155
+ #{include:IPAccess::Socket#unblacklist}
156
+ # @overload unblacklist(*addresses)
157
+ # @overload unblacklist(list, *addresses)
158
+ def unblacklist(*addresses); end
143
159
 
144
160
  alias_method :unblock!, :unblacklist!
145
161
  alias_method :del_black!, :unblacklist!
@@ -170,7 +186,7 @@ class IPAccess::Net::Telnet
170
186
  # allows to set reason.
171
187
  def blacklist_reasonable(reason, *addresses); end
172
188
 
173
- #:include:ghost_doc_acl.rb
189
+ #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
174
190
  #
175
191
  # === Example
176
192
  #
@@ -0,0 +1,65 @@
1
+ Access checks are lazy,
2
+ which means they are performed when
3
+ a real connection is going to happend.
4
+
5
+ Instances of this class will also
6
+ internally use patched versions of Ruby's network
7
+ socket objects to avoid access leaks.
8
+
9
+ You can pass access set in various ways: while
10
+ creating a new object or while a communication is
11
+ already started. You can also rely on a global
12
+ access set, which is used by default.
13
+
14
+ === Usage
15
+
16
+ There are 3 ways to enable access control:
17
+
18
+ * by patching original class (see IPAccess.arm) – use it in code that you cannot modify
19
+ * by patching single instance (see IPAccess.arm) – use it occasionally
20
+ * by using instances of this class directly – use it in your own code
21
+
22
+ There are also 4 ways to manage access rules:
23
+
24
+ * by using direct methods like blacklist and whitelist – preferred
25
+ * by using +acl+ member – low-level
26
+ * by using <tt>IPAccess::Set.Global</tt> constant – controls a global access set
27
+ * by using methods of an external IPAccess::Set object associated with an instance
28
+
29
+ ==== Using direct methods
30
+
31
+ Patched network objects and variants have methods to control access.
32
+ You should use them since they are most reliable way to perform
33
+ modifications on an working instance. These methods (documented
34
+ below) are: whitelist, blacklist, whitelist! and blacklist!.
35
+ Each of the methods ensures that needed safety checks are made
36
+ when detecting some change in access lists.
37
+
38
+ ==== Using +acl+ member
39
+
40
+ The +acl+ member gives you direct access to internal IPAccess::Set
41
+ instance that an object uses to control an access. However,
42
+ by accessing this member you may only modify private and shared
43
+ access sets, and you have to manually re-check connection against lists
44
+ (e.g. by using method acl_recheck).
45
+
46
+ ==== Using IPAccess::Set.Global
47
+
48
+ You may use IPAccess::Set.Global to add or remove rules
49
+ conatined in lists of a global access set. You should use
50
+ it before some network objects are created and if it's not
51
+ possible call acl_recheck for any object that is using it
52
+ when some changes in rules are made. It is also possible
53
+ to manipulate global access set from object's scope using
54
+ whitelist! and blacklist! methods. For working
55
+ objects you should use them.
56
+
57
+ ==== Using external access set
58
+
59
+ External access sets are simply IPAccess::Set objects
60
+ that were associated with an instance during initialization
61
+ or by assigning it to +acl+ member. You may manipulate their
62
+ access rules safely before a networking object is in
63
+ a connected state. After it happens it is safer to use
64
+ direct controlling methods that network object provides.
65
+