File Coverage

blib/lib/Config/Apple/Profile/Payload/WiFi/EAPClientConfiguration.pm
Criterion Covered Total %
statement 40 40 100.0
branch 17 18 94.4
condition 30 30 100.0
subroutine 10 10 100.0
pod 1 1 100.0
total 98 99 98.9


line stmt bran cond sub pod time code
1             # This is the code for Config::Apple::Profile::Payload::WiFi::EAPClientConfiguration.
2             # For Copyright, please see the bottom of the file.
3              
4             package Config::Apple::Profile::Payload::WiFi::EAPClientConfiguration;
5              
6 3     3   2158 use 5.10.1;
  3         7  
  3         109  
7 3     3   12 use strict;
  3         4  
  3         85  
8 3     3   13 use warnings FATAL => 'all';
  3         4  
  3         88  
9 3     3   11 use base qw(Config::Apple::Profile::Payload::Common);
  3         7  
  3         685  
10              
11             our $VERSION = '0.87';
12              
13 3     3   433 use Config::Apple::Profile::Config;
  3         5  
  3         136  
14 3     3   12 use Config::Apple::Profile::Payload::Common;
  3         6  
  3         61  
15 3     3   12 use Config::Apple::Profile::Payload::Types qw(:all);
  3         3  
  3         522  
16 3     3   16 use Config::Apple::Profile::Targets qw(:all);
  3         4  
  3         259  
17 3     3   15 use Readonly;
  3         3  
  3         1756  
18              
19              
20             =encoding utf8
21              
22             =head1 NAME
23              
24             Config::Apple::Profile::Payload::Wi-Fi::EAPClientConfiguration - Class for the
25             EAPClientConfiguration payload key in the Wi-Fi payload.
26              
27             =head1 DESCRIPTION
28              
29             This class implements part of the Wi-Fi payload. Specifically, this class
30             implements the C dictionary. This contains all of the
31             EAP configuration when WPA-Enterprise or WPA2-Enterprise is being used on a
32             Wi-Fi network.
33              
34             Even though this class is not a payload in its own right, it can be treated as
35             a payload.
36              
37              
38             =head1 INSTANCE METHODS
39              
40             The following instance methods are provided by this class.
41              
42              
43             =head2 validate_key($key, $value)
44              
45             Performs additional validation for certain payload keys in this class:
46              
47             =over 4
48              
49             =item * C
50              
51             This must be C<13>, C<17>, C<18>, C<21>, C<23>, C<25>, or C<43>.
52              
53             =item * C
54              
55             Only valid host and domain names are allowed, although the asterisk (C<*>) is
56             acceptable as a wildcard.
57              
58             =item * C
59              
60             This must be either C<2> or C<3>.
61              
62             =item * C
63              
64             This must be C, C, C, or C.
65              
66             =back
67              
68             All other payload keys will be checked as usual by the parent class.
69              
70             See also the documentation in L.
71              
72             =cut
73              
74             # $TLSTrustedServerNames_regex matches hostnames, but allows * as a wildcard
75             # character. It is based on $RE{net}{domain}{-keep}{-nospace} from
76             # Regexp::Common by Damien Conway and Abigail, but rewritten because that
77             # module's code is not available under the GPL2, which we are.
78             Readonly my $TLSTrustedServerNames_hostname => qr/
79             [A-Z0-9*] # First character can be a letter or a digit
80             (?: # We don't have to have more than 1 character, but...
81             [-A-Z0-9*]{0,253} # Middle characters allow hyphens
82             [A-Z0-9*] # End character is a letter or a digit
83             )?
84             /ix;
85             Readonly my $TLSTrustedServerNames_regex => qr/
86             ^( # Match the whole string; capture the match
87             $TLSTrustedServerNames_hostname # We need at least 1 hostname
88             (?:
89             \. # Domains require a dot before subsequent
90             $TLSTrustedServerNames_hostname # hostnames, but…
91             )* # We don't have to have a domain name.
92             )$
93             /isx;
94              
95             sub validate_key {
96 41     41 1 47 my ($self, $key, $value) = @_;
97            
98             # Let's start by letting the parent do the generic validation.
99 41         166 my $parent_value = $self->SUPER::validate_key($key, $value);
100 41 100       247 return $parent_value if !defined $parent_value;
101            
102             # Let's check over some of our keys
103             # Only allow EAP-type values for AcceptEAPTypes
104 39 100       101 if ($key eq 'AcceptEAPTypes') {
    100          
    100          
    50          
105 18 100 100     189 unless ( ($value == 13)
      100        
      100        
      100        
      100        
      100        
106             || ($value == 17)
107             || ($value == 18)
108             || ($value == 21)
109             || ($value == 23)
110             || ($value == 25)
111             || ($value == 43)
112             ) {
113             ## no critic (ProhibitExplicitReturnUndef)
114 11         37 return undef;
115             ## use critic
116             }
117             }
118            
119             # TLSTrustedServerNames allows hostnames and domains, but also allows * as
120             # a wildcard character.
121             elsif ($key eq 'TLSTrustedServerNames') {
122 10 100       34 if ($value =~ $TLSTrustedServerNames_regex) {
123 5         64 return $1;
124             }
125             else {
126             ## no critic (ProhibitExplicitReturnUndef)
127 5         59 return undef;
128             ## use critic
129             }
130             }
131            
132             # Only allow certain values for TTLSInnerAuthentication
133             elsif ($key eq 'TTLSInnerAuthentication') {
134 7 100 100     47 unless ( ($value eq 'PAP')
      100        
      100        
135             || ($value eq 'CHAP')
136             || ($value eq 'MSCHAP')
137             || ($value eq 'MSCHAPv2')
138             ) {
139             ## no critic (ProhibitExplicitReturnUndef)
140 3         10 return undef;
141             ## use critic
142             }
143             }
144            
145             # EAPSIMNumberOfRANDs must be 2 or 3
146             elsif ($key eq 'EAPSIMNumberOfRANDs') {
147             ## no critic (ProhibitExplicitReturnUndef)
148 4 100 100     21 return undef unless (($value == 2) || ($value == 3));
149             ## use critic
150             }
151            
152             # At this point, we've checked all of our special keys and we're good!
153 13         34 return $value;
154             }
155              
156              
157             =head1 PAYLOAD KEYS
158              
159             This payload has the following keys:
160              
161              
162             =head2 C
163              
164             This is an I, where each number represents one type of EAP
165             method to use.
166              
167             At least one EAP method must be specified. The following EAP methods are
168             supported:
169              
170             =over 4
171              
172             =item C<13> = EAP-TLS
173              
174             As defined in RFC 5216, available at L.
175             The client is authenticated using an identity certificate.
176              
177             =item C<17> = LEAP
178              
179             The Cisco-developed protocol. This should not be used for new environments.
180              
181             =item C<18> = EAP-SIM
182              
183             As defined in RFC 4186, available at L.
184             The client is authenticated using their phone's SIM, using challenge-response.
185              
186             =item C<21> = EAP-TTLS
187              
188             As defined in RFC 5281, available at L.
189             The client is authenticated using a username & password, but that authentication
190             takes place inside of a TLS connection.
191              
192             =item C<23> = EAP-AKA
193              
194             As defined in RFC 5448, available at L.
195             The client is authenticated using their phone's USIM, using challenge-response.
196              
197             =item C<25> = PEAP
198              
199             =item C<43> = EAP-FAST
200              
201             As defined in RFC 4581, available at L.
202             The client is authenticated using a pre-shared credential, or (if none is
203             available) some other EAP method, embedded in a TLS connection.
204              
205             =back
206              
207             If multiple EAP types are listed, Apple's documentataion does not specify the
208             order that they will be used.
209              
210              
211             =head2 Basic Authentication Parameters
212              
213             =head3 C
214              
215             I
216              
217             A I. This is the exact username to use. If not provided, the user will
218             be asked to enter this information during authentication.
219              
220              
221             =head3 C
222              
223             I, relevent only to TTLS, PEAP, and FAST.
224              
225             A I. If present, the value of this string will be used as the username
226             outside of the encrypted tunnel; the real username will only be passed inside
227             the encrypted tunnel.
228              
229              
230             =head3 C
231              
232             I
233              
234             A I. If a password is used during authentication, it will be taken from
235             here. If a password is needed, but not already provided, then the user will
236             be prompted.
237              
238              
239             =head3 C
240              
241             I
242              
243             A I. If C, then the user will be asked for a password every time
244             the device connects to the wireless network. If C, the password will be
245             saved for future connections to the wireless network.
246              
247             Default is C.
248              
249              
250             =head2 TLS Configuration
251              
252             =head3 C
253              
254             I, used by authentication methods that provide a TLS certificate.
255              
256             An I. The UUIDs point to I payloads that have
257             been loaded onto the device, either as part of this profile or via an already-
258             installed profile.
259              
260             When the EAP server provides their TLS certificate, the
261             device must confirm that the server's certificate is trusted. If this array is
262             provided, the device will use it as the list of trusted certificates, for the
263             purposes of certificate verification and trust.
264              
265             The EAP server's certificate must pass this test, as well as the test defined in
266             L>, before the certificate will be trusted.
267              
268             See L for more information on the
269             certificate payload types. See also L>.
270              
271              
272             =head3 C
273              
274             I, used by authentication methods that provide a TLS certificate.
275              
276             An I. Each string is a domain name, with the C<*> wildcard
277             allowed. When the EAP server presents its certificate, the certificate's
278             common name will be checked against this list; if the common name does not
279             match any of the patterns in the list, the certificate will not be trusted.
280              
281             The EAP server's certificate must pass this test, as well as the test defined in
282             L>, before the certificate will be trusted.
283              
284             See also L>.
285              
286              
287             =head3 C
288              
289             I, used by authentication methods that provide a TLS certificate.
290              
291             A I.
292              
293             Certificate trust is automatically determined using the payload keys
294             C and C. If both keys are
295             undefined, then automatic validation fails. If both keys are defined, and
296             either test failed, the automatic validation fails. If only one key is defined,
297             then automatic validation fails if that one test fails.
298              
299             If this key is true, and automatic validation had failed, then the user will be
300             given the option to explicitly trust the certificate, or to cancel the
301             connection attempt. If this key is false, then the user will not be given any
302             option; if automatic validation fails, then the connection fails.
303              
304             The default value is not fixed: If either C or
305             C is defined, then the default value is C. If
306             both C and C are undefined,
307             then the default value is C.
308              
309              
310             =head3 C
311              
312             I, relevent only to PEAP, EAP-TTLS, EAP-FAST, and EAP-TLS.
313             I.
314              
315             If C, allows for two-factor authentication for PEAP, EAP-TTLS, and
316             EAP-FAST. If C, allowes for zero-factor authentication for EAP-TLS.
317              
318             The default value is not fixed. If EAP-TLS is being used, then the default is
319             C. For all other EAP types, the default is C.
320              
321              
322             =head2 EAP-TTLS Configruation
323              
324             The key in this section is only used with EAP-TTLS.
325              
326              
327             =head3 C
328              
329             I
330              
331             A I. This the the authentication method used inside the tunnel. Valid
332             values are:
333              
334             =over 4
335              
336             =item C
337              
338             =item C
339              
340             =item C
341              
342             =item C
343              
344             =back
345              
346             The default is C.
347              
348              
349             =head2 EAP-FAST Configuration
350              
351             The keys in this section are only used with EAP-FAST.
352              
353              
354             =head3 C
355              
356             I
357              
358             A I. If an existing PAC is present, and this key is C, then
359             use the existing PAC. Otherwise, the server must use a certificate to prove
360             its identity.
361              
362             Default is C.
363              
364              
365             =head3 C
366              
367             I
368              
369             A I. If C, allow PAC provisioning. This key has no effect
370             unless C is C.
371              
372             Default is C.
373              
374              
375             =head3 C
376              
377             I
378              
379             A I. If C, the PAC may be provisioned anonymously.
380              
381             B Anonymous PAC provisioning has known man-in-the-middle attacks. If
382             PAC provisioning is used, this key shoudl be set to C.
383              
384             Default is C.
385              
386              
387             =head3 C
388              
389             I
390              
391             A I, either C<2> or C<3>. This is the number of RANDs expected for
392             EAP-SIM.
393              
394             Default is C<3>.
395              
396             =cut
397              
398             Readonly our %payloadKeys => (
399             # We are NOT using the common keys. We are just defining our own.
400             # Since we are not a separate payload, we will not be defining basic keys.
401            
402             # Basic configuration
403             'AcceptEAPTypes' => {
404             type => $ProfileArray,
405             subtype => $ProfileNumber,
406             description => 'The list of EAP types to accept.',
407             targets => {
408             $TargetIOS => '5.0',
409             $TargetMACOSX => '10.7',
410             },
411             },
412            
413             # Authentication information
414             'UserName' => {
415             type => $ProfileString,
416             description => 'The exact user name. If not present, the user is '
417             . 'prompted when they authenticate.',
418             optional => 1,
419             targets => {
420             $TargetIOS => '5.0',
421             $TargetMACOSX => '10.7',
422             },
423             },
424             'OuterIdentity' => {
425             type => $ProfileString,
426             description => 'The outer identity to use in TTLS, PEAP, and EAP-FAST.',
427             optional => 1,
428             targets => {
429             $TargetIOS => '5.0',
430             $TargetMACOSX => '10.7',
431             },
432             },
433             'UserPassword' => {
434             type => $ProfileString,
435             description => 'The password. If not present, the user is prompted '
436             . 'when they authenticate.',
437             optional => 1,
438             private => 1,
439             targets => {
440             $TargetIOS => '5.0',
441             $TargetMACOSX => '10.7',
442             },
443             },
444             'OneTimePassword' => {
445             type => $ProfileBool,
446             description => 'Prompt for password whenever connecting to the '
447             . 'wireless network. Default is false.',
448             optional => 1,
449             targets => {
450             $TargetIOS => '5.0',
451             $TargetMACOSX => '10.7',
452             },
453             },
454            
455             # TLS configuration
456             'PayloadCertificateAnchorUUID' => {
457             type => $ProfileArray,
458             subtype => $ProfileUUID,
459             description => 'A list of server certificate UUIDs to trust.',
460             optional => 1,
461             targets => {
462             $TargetIOS => '5.0',
463             $TargetMACOSX => '10.7',
464             },
465             },
466             'TLSTrustedServerNames' => {
467             type => $ProfileArray,
468             subtype => $ProfileString,
469             description => 'A list of common names to explicitly trust.',
470             optional => 1,
471             targets => {
472             $TargetIOS => '5.0',
473             $TargetMACOSX => '10.7',
474             },
475             },
476             'TLSAllowTrustExceptions' => {
477             type => $ProfileBool,
478             description => 'Allow the user to choose to trust the server cert.',
479             optional => 1,
480             targets => {
481             $TargetIOS => '5.0',
482             $TargetMACOSX => '10.7',
483             },
484             },
485             'TLSCertificateIsRequired' => {
486             type => $ProfileBool,
487             description => 'Varies depending on the EAP type used.',
488             optional => 1,
489             targets => {
490             $TargetIOS => '7.0',
491             $TargetMACOSX => '10.7',
492             },
493             },
494            
495             # TTLS Configuration
496             'TTLSInnerAuthentication' => {
497             type => $ProfileString,
498             description => 'The inner authentication method to use with TTLS.',
499             optional => 1,
500             targets => {
501             $TargetIOS => '5.0',
502             $TargetMACOSX => '10.7',
503             },
504             },
505            
506             # EAP-FAST Configuration
507             'EAPFASTUsePAC' => {
508             type => $ProfileBool,
509             description => 'If trust, use a PAC if available. Default is false.',
510             optional => 1,
511             targets => {
512             $TargetIOS => '5.0',
513             $TargetMACOSX => '10.7',
514             },
515             },
516             'EAPFASTProvisionPAC' => {
517             type => $ProfileBool,
518             description => 'Allow PAC provisioning.',
519             optional => 1,
520             targets => {
521             $TargetIOS => '5.0',
522             $TargetMACOSX => '10.7',
523             },
524             },
525             'EAPFASTProvisionPACAnonymously' => {
526             type => $ProfileBool,
527             description => '[UNSAFE] Provision PAC anonymously. Defaults to false.',
528             optional => 1,
529             targets => {
530             $TargetIOS => '5.0',
531             $TargetMACOSX => '10.7',
532             },
533             },
534             'EAPSIMNumberOfRANDs' => {
535             type => $ProfileNumber,
536             description => 'The number of expected RANDs for EAP-SIM. Default is 3.',
537             optional => 1,
538             targets => {
539             $TargetIOS => '5.0',
540             $TargetMACOSX => '10.7',
541             },
542             },
543             ); # End of %payloadKeys
544              
545              
546             =head1 ACKNOWLEDGEMENTS
547              
548             Refer to L for acknowledgements.
549              
550              
551             =head1 AUTHOR
552              
553             A. Karl Kornel, C<< >>
554              
555              
556             =head1 COPYRIGHT AND LICENSE
557              
558             Copyright © 2014 A. Karl Kornel.
559              
560             This program is free software; you can redistribute it and/or modify it
561             under the terms of either: the GNU General Public License as published
562             by the Free Software Foundation; or the Artistic License.
563              
564             See L for more information.
565              
566             =cut
567              
568             1;