File Coverage

blib/lib/Config/Apple/Profile/Payload/WiFi.pm
Criterion Covered Total %
statement 39 39 100.0
branch 13 14 92.8
condition 12 12 100.0
subroutine 10 10 100.0
pod 1 1 100.0
total 75 76 98.6


line stmt bran cond sub pod time code
1             # This is the code for Config::Apple::Profile::Payload::WiFi.
2             # For Copyright, please see the bottom of the file.
3              
4             package Config::Apple::Profile::Payload::WiFi;
5              
6 2     2   1382 use 5.10.1;
  2         6  
  2         69  
7 2     2   9 use strict;
  2         2  
  2         51  
8 2     2   8 use warnings FATAL => 'all';
  2         31  
  2         61  
9 2     2   7 use base qw(Config::Apple::Profile::Payload::Common);
  2         3  
  2         549  
10              
11             our $VERSION = '0.87.1';
12              
13 2     2   358 use Config::Apple::Profile::Config;
  2         3  
  2         81  
14 2     2   8 use Config::Apple::Profile::Payload::Common;
  2         3  
  2         42  
15 2     2   8 use Config::Apple::Profile::Payload::Types qw(:all);
  2         3  
  2         302  
16 2     2   11 use Config::Apple::Profile::Targets qw(:all);
  2         2  
  2         173  
17 2     2   10 use Readonly;
  2         2  
  2         1277  
18              
19              
20             =encoding utf8
21              
22             =head1 NAME
23              
24             Config::Apple::Profile::Payload::Wi-Fi - Class for the Wi-Fi payload type.
25              
26             =head1 DESCRIPTION
27              
28             This class implements the Wi-Fi payload.
29              
30              
31             =head1 INSTANCE METHODS
32              
33             The following instance methods are provided by this class.
34              
35             =head2 validate_key($key, $value)
36              
37             Performs additional validation for certain payload keys in this class:
38              
39             =over 4
40              
41             =item * C
42              
43             Only C, C, C, and C are accepted as values.
44              
45             =item * C
46              
47             Only six-digit numbers are accepted.
48              
49             =item * C
50              
51             This must be a number within the range 1 to 65,535, inclusive.
52              
53             =back
54              
55             This is done in addition to the validation performed by the parent class.
56              
57             See also the documentation in L.
58              
59             =cut
60              
61             sub validate_key {
62 24     24 1 29 my ($self, $key, $value) = @_;
63            
64             # Let the parent run the basic checks
65 24         111 my $validated_value = $self->SUPER::validate_key($key, $value);
66 24 100       279 return $validated_value if !defined $validated_value;
67            
68             # Let's check over some of our keys
69             # EncryptionType only accepts specific strings
70 22 100       58 if ($key eq 'EncryptionType') {
    100          
    50          
71 7         22 $validated_value =~ m/^(WEP|WPA|Any|None)$/s;
72            
73 7 100 100     51 unless ( ($validated_value eq 'WEP')
      100        
      100        
74             || ($validated_value eq 'WPA')
75             || ($validated_value eq 'Any')
76             || ($validated_value eq 'None')
77             ) {
78             ## no critic (ProhibitExplicitReturnUndef)
79 3         8 return undef;
80             ## use critic
81             }
82             }
83            
84             # MCCAndMNCs only accepts six-digit numbers
85             elsif ($key eq 'MCCAndMNCs') {
86 7 100       22 unless ($validated_value =~ m/^\d{6}$/s) {
87             ## no critic (ProhibitExplicitReturnUndef)
88 4         13 return undef;
89             ## use critic
90             }
91             }
92            
93             # Ports must be numbers from 1 to 65,534 inclusive.
94             elsif ($key eq 'ProxyPort') {
95 8 100 100     34 if ( ($validated_value < 1)
96             || ($validated_value > 65534)
97             ) {
98             ## no critic (ProhibitExplicitReturnUndef)
99 4         13 return undef;
100             ## use critic
101             }
102             }
103            
104             # At this point, we've checked all of our special keys. Over to the parent!
105 11         28 return $validated_value;
106             }
107              
108              
109             =head1 PAYLOAD KEYS
110              
111             All of the payload keys defined in L
112             are used by this payload.
113              
114             This payload has the following additional keys:
115              
116             =head2 General Configuration
117              
118              
119             =head3 C
120              
121             A I, this is the SSID (the name) of the Wi-Fi network.
122              
123              
124             =head3 C
125              
126             I
127              
128             If C, this Wi-Fi network does not broadcast itself, meaning that the SSID
129             and encryption information must be specified in this configuration.
130              
131             Defaults to C.
132              
133              
134             =head3 C
135              
136             I
137              
138             If C, the device will automatically join the Wi-Fi network if it is
139             detected. If the device sees multiple Wi-Fi networks that have auto-join
140             enabled, only one Wi-Fi network will be joined.
141              
142             Defaults to C.
143              
144              
145             =head3 C
146              
147             A I. The type of encryption to support. Valid values are C,
148             C, C, and C. C includes WPA and WPA2, the -Personal and
149             -Enterprise versions.
150              
151             The encryption type specified must exactly match what is configured on the
152             access point. For maximum flexibility, with the higher possibility of
153             connecting to an unexpected access point, use the value C.
154              
155              
156             =head2 Encryption Configuration
157              
158              
159             =head3 C
160              
161             I, for use with WPA- and WPA2-Enterprise encryption.
162              
163             An object of the class
164             C. This object
165             becomes a I containing the list of supported EAP types and all other
166             EAP-related configuration, except for a password or identity certificate.
167              
168             See L.
169              
170             =head3 C
171              
172             I
173              
174             A I. If password-based authentication is used (such as WEP,
175             WPA-Personal, WPA2-Personal, or -Enterprise with a password-based EAP), this is
176             the password to use. If no other authentication methods are available, the user
177             may be prompted for a password.
178              
179              
180             =head3 C
181              
182             I, for use with WPA- and WPA2-Enterprise encryption and EAP-TLS.
183              
184             A I. This is the UUID of an identity certificate that has already been
185             loaded onto the device, using a payload class of type
186             C. The identity
187             certificate may be included in the same configuration profile, or in a
188             previously-installed profile.
189              
190             See L.
191              
192              
193             =head2 Hotspot Configuration
194              
195             The payload keys in this section refer to Hotspot 2.0, also known as Wi-Fi
196             CERTIFIED Passpoint. More information on Hotspot 2.0 is available here:
197              
198             =over 4
199              
200             =item http://www.wi-fi.org/discover-wi-fi/wi-fi-certified-passpoint
201              
202             =item http://en.wikipedia.org/wiki/Hotspot_(Wi-Fi)#Hotspot_2.0
203              
204             =back
205              
206              
207             =head3 C
208              
209             I. Available in iOS starting with iOS 7.0.
210              
211             A I. If C, this Wi-Fi network is treated as a hotspot.
212              
213             Default is C.
214              
215              
216             =head3 C
217              
218             I. Available in iOS starting with iOS 7.0.
219              
220             A I. The domain name used in Hotspot 2.0 negotiation.
221              
222             If this payload key is present, the C payload key may be omitted.
223              
224              
225             =head3 C
226              
227             I. Available in iOS starting with iOS 7.0.
228              
229             A I. Used in Hotspot 2.0 negotation. If C, connection is
230             allowed to roaming service providers.
231              
232             The default value is not specified in the documentation (see issue #13).
233              
234              
235             =head3 C
236              
237             I. Available in iOS starting with iOS 7.0.
238              
239             An I of I. Used in Hotspot 2.0 negotation, this is a list of
240             Roaming Consortium Organization Identifiers.
241              
242              
243             =head3 C
244              
245             I. Available in iOS starting with iOS 7.0.
246              
247             An I of I. Used in Hotspot 2.0 negotiation, this is a list of
248             Network Access Identifier Realm names.
249              
250              
251             =head3 C
252              
253             I. Available in iOS starting with iOS 7.0.
254              
255             An I of I, where each string must be a six-digit number. Used
256             in Hotspot 2.0 negotiation, the first three digits of the string are the Mobile
257             Country Code (MCC) and the last three digits of the string are the Mobile
258             Network Code (MNC).
259              
260             B This is B an array of numbers, this is an array of strings. That
261             being said, thanks to the way Perl handles scalars, and how the pushed values
262             are validated, you can provide a six-digit number and it I be accepted.
263             If your MCC has any leading zeroes, though, treating it as a number will cause
264             a validation failure.
265              
266              
267             =head3 C
268              
269             Presumed I. Available in iOS starting with iOS 7.0.
270              
271             A I. No description is available (see issue #11).
272              
273              
274             =head2 Proxy Configuration
275              
276              
277             =head3 C
278              
279             I.
280              
281             A I. Valid values are C, C, and C.
282              
283              
284             =head3 C
285              
286             A I. The proxy server's network address.
287              
288              
289             =head3 C
290              
291             A I. The proxy server's port.
292              
293              
294             =head3 C
295              
296             I.
297              
298             A I. The username to use when authenticating to the proxy server.
299              
300              
301             =head3 C
302              
303             I.
304              
305             A I. The password to use when authenticating to the proxy server.
306              
307              
308             =head3 C
309              
310             I.
311              
312             A I. The URL of the PAC file containing the proxy configuration.
313              
314              
315             =head3 C
316              
317             I.
318              
319             A I. If the PAC file can not be loaded, and this payload key is
320             C, then this Wi-Fi connection will not be used. If C, the device
321             will attempt to connect directly to the destination.
322              
323             Defaults to C.
324              
325             =cut
326              
327             Readonly our %payloadKeys => (
328             # Bring in the common keys...
329             %Config::Apple::Profile::Payload::Common::payloadKeys,
330            
331             # ... and define our own!
332             # Start with basic network information
333             'SSID_STR' => {
334             type => $ProfileString,
335             description => 'The SSID of the Wi-Fi network.',
336             optional => 1,
337             targets => {
338             $TargetIOS => '5.0',
339             $TargetMACOSX => '10.7',
340             },
341             },
342             'HIDDEN_NETWORK' => {
343             type => $ProfileBool,
344             description => 'If false, the device expects the network to be '
345             . 'broadcasting. Default is false.',
346             optional => 1,
347             targets => {
348             $TargetIOS => '5.0',
349             $TargetMACOSX => '10.7',
350             },
351             },
352             'AutoJoin' => {
353             type => $ProfileBool,
354             description => 'If false, do not auto-join the network. Default true.',
355             optional => 1,
356             targets => {
357             $TargetIOS => '5.0',
358             $TargetMACOSX => '10.7',
359             },
360             },
361             'EncryptionType' => {
362             type => $ProfileString,
363             description => 'The encryption type for the Wi-Fi network.',
364             targets => {
365             $TargetIOS => '5.0',
366             $TargetMACOSX => '10.7',
367             },
368             },
369            
370             # Encryption Configuration
371             'Password' => {
372             type => $ProfileString,
373             description => 'If using password-based authentication, this is '
374             . "the user's password.",
375             optional => 1,
376             targets => {
377             $TargetIOS => '5.0',
378             $TargetMACOSX => '10.7',
379             },
380             },
381             'EAPClientConfiguration' => {
382             type => $ProfileClass,
383             description => 'If using EAP-based authentication, this provides '
384             . 'the EAP parameters for the connection.',
385             optional => 1,
386             targets => {
387             $TargetIOS => '5.0',
388             $TargetMACOSX => '10.7',
389             },
390             },
391             'PayloadCertificateUUID' => {
392             type => $ProfileUUID,
393             description => 'If using certificate-based authentication, this is '
394             . "the UUID of the user's identity certificate",
395             optional => 1,
396             targets => {
397             $TargetIOS => '5.0',
398             $TargetMACOSX => '10.7',
399             },
400             },
401            
402             # HotSpot Configuration
403             'IsHotspot' => {
404             type => $ProfileBool,
405             description => 'If true, treat the network as a hotspot. '
406             . 'Default false.',
407             optional => 1,
408             targets => {
409             $TargetIOS => '7.0',
410             $TargetMACOSX => '10.7',
411             },
412             },
413             'DomainName' => {
414             type => $ProfileString,
415             description => 'Domain name to use for Hotspot 2.0 negotiation.',
416             optional => 1,
417             targets => {
418             $TargetIOS => '7.0',
419             $TargetMACOSX => '10.7',
420             },
421             },
422             'ServiceProviderRoamingEnabled' => {
423             type => $ProfileBool,
424             description => 'Allow connection to roaming service providers.',
425             optional => 1,
426             targets => {
427             $TargetIOS => '7.0',
428             $TargetMACOSX => '10.7',
429             },
430             },
431             'RoamingConsortiumOIs' => {
432             type => $ProfileArray,
433             subtype => $ProfileString,
434             description => 'Array of Roaming Consortium OIs, used for '
435             . 'Hotspot 2.0 negotiation.',
436             optional => 1,
437             targets => {
438             $TargetIOS => '7.0',
439             $TargetMACOSX => '10.7',
440             },
441             },
442             'NAIRealmNames' => {
443             type => $ProfileArray,
444             subtype => $ProfileString,
445             description => 'List of Network Access Identifier realm names, used '
446             . 'for Hotspot 2.0 negotation.',
447             optional => 1,
448             targets => {
449             $TargetIOS => '7.0',
450             $TargetMACOSX => '10.7',
451             },
452             },
453             'MCCAndMNCs' => {
454             type => $ProfileArray,
455             subtype => $ProfileString,
456             description => 'List of Mobile Country Code (MCC) and Network '
457             . 'Country Code (NCC) pairs, used for Hotspot 2.0 '
458             . 'negotation.',
459             optional => 1,
460             targets => {
461             $TargetIOS => '7.0',
462             },
463             },
464             'DisplayedOperatorName' => {
465             type => $ProfileString,
466             optional => 1,
467             targets => {
468             $TargetIOS => '7.0',
469             $TargetMACOSX => '10.7',
470             },
471             },
472            
473             # Proxy configuration
474             'ProxyType' => {
475             type => $ProfileString,
476             description => 'The type of proxy to configure. Default is "None".',
477             optional => 1,
478             targets => {
479             $TargetIOS => '5.0',
480             $TargetMACOSX => '10.7',
481             },
482             },
483             'ProxyServer' => {
484             type => $ProfileString,
485             description => "The proxy server's network address",
486             targets => {
487             $TargetIOS => '5.0',
488             $TargetMACOSX => '10.7',
489             },
490             },
491             'ProxyPort' => {
492             type => $ProfileNumber,
493             description => "The proxy server's port number.",
494             optional => 1,
495             targets => {
496             $TargetIOS => '5.0',
497             $TargetMACOSX => '10.7',
498             },
499             },
500             'ProxyUsername' => {
501             type => $ProfileString,
502             description => 'An optional username to authenticate to the proxy.',
503             optional => 1,
504             targets => {
505             $TargetIOS => '5.0',
506             $TargetMACOSX => '10.7',
507             },
508             },
509             'ProxyPassword' => {
510             type => $ProfileString,
511             description => 'An optional password to authenticate to the proxy.',
512             optional => 1,
513             private => 1,
514             targets => {
515             $TargetIOS => '5.0',
516             $TargetMACOSX => '10.7',
517             },
518             },
519             'ProxyPACURL' => {
520             type => $ProfileString,
521             description => 'Optional proxy configuration PAC file URL.',
522             optional => 1,
523             targets => {
524             $TargetIOS => '5.0',
525             $TargetMACOSX => '10.7',
526             },
527             },
528             'ProxyPACFallbackAllowed' => {
529             type => $ProfileBool,
530             description => 'If false, device may not connect if PAC file can not '
531             . 'be downloaded. Default is true.',
532             optional => 1,
533             targets => {
534             $TargetIOS => '7.0',
535             $TargetMACOSX => '10.7',
536             },
537             },
538            
539             # Finish with basic payload information
540             'PayloadType' => {
541             type => $ProfileString,
542             value => 'com.apple.wifi.managed',
543             targets => {
544             $TargetIOS => '5.0',
545             $TargetMACOSX => '10.7',
546             },
547             },
548             'PayloadVersion' => {
549             type => $ProfileNumber,
550             value => 1,
551             targets => {
552             $TargetIOS => '5.0',
553             $TargetMACOSX => '10.7',
554             },
555             },
556             ); # End of %payloadKeys
557              
558              
559              
560             =head1 ACKNOWLEDGEMENTS
561              
562             Refer to L for acknowledgements.
563              
564             =head1 AUTHOR
565              
566             A. Karl Kornel, C<< >>
567              
568             =head1 COPYRIGHT AND LICENSE
569              
570             Copyright © 2014 A. Karl Kornel.
571              
572             This program is free software; you can redistribute it and/or modify it
573             under the terms of either: the GNU General Public License as published
574             by the Free Software Foundation; or the Artistic License.
575              
576             See L for more information.
577              
578             =cut
579              
580             1;