File Coverage

blib/lib/Config/Apple/Profile/Payload/Email.pm
Criterion Covered Total %
statement 48 49 97.9
branch 21 22 95.4
condition 11 12 91.6
subroutine 11 11 100.0
pod 1 1 100.0
total 92 95 96.8


line stmt bran cond sub pod time code
1             # This is the code for Config::Apple::Profile::Payload::Email.
2             # For Copyright, please see the bottom of the file.
3              
4             package Config::Apple::Profile::Payload::Email;
5              
6 2     2   39687 use 5.10.1;
  2         7  
  2         86  
7 2     2   10 use strict;
  2         3  
  2         65  
8 2     2   10 use warnings FATAL => 'all';
  2         3  
  2         88  
9 2     2   10 use base qw(Config::Apple::Profile::Payload::Common);
  2         9  
  2         725  
10              
11             our $VERSION = '0.87';
12              
13 2     2   1161 use Email::Valid;
  2         167548  
  2         89  
14 2     2   23 use Readonly;
  2         4  
  2         121  
15 2     2   10 use Regexp::Common;
  2         4  
  2         25  
16 2     2   1103 use Config::Apple::Profile::Targets qw(:all);
  2         3  
  2         284  
17 2     2   12 use Config::Apple::Profile::Payload::Common;
  2         3  
  2         47  
18 2     2   8 use Config::Apple::Profile::Payload::Types qw(:all);
  2         3  
  2         1857  
19              
20              
21             =encoding utf8
22              
23             =head1 NAME
24              
25             Config::Apple::Profile::Payload::Email - The Email payload type.
26              
27             =head1 SYNOPSIS
28              
29             use Config::Apple::Profile;
30             use Config::Apple::Profile::Payload::Email;
31            
32             my $email = new Config::Apple::Profile::Payload::Email;
33             my $payload = $email->payload;
34            
35             $payload->{EmailAccountDescription} = 'Example Email';
36             $payload->{EmailAccountName} = 'Simon Blarfingar';
37             $payload->{EmailAddress} = 'user@example.com';
38             $payload->{EmailAccountType} = 'EmailTypeIMAP';
39            
40             $payload->{IncomingMailServerHostName} = 'mail.example.com';
41             $payload->{OutgoingMailServerHostName} = $payload->{IncomingMailServerHostName};
42            
43             $payload->{IncomingMailServerAuthentication} = 'EmailAuthPassword';
44             $payload->{OutgoingMailServerAuthentication} = $payload->{IncomingMailServerAuthentication};
45            
46             $payload->{IncomingMailServerUsername} = $payload->{EmailAddress};
47             $payload->{OutgoingMailServerUsername} = $payload->{IncomingMailServerUsername};
48            
49             $payload->{OutgoingPasswordSameAsIncomingPassword} = 1;
50             $payload->{SMIMEEnabled} = 1;
51              
52             my $profile = new Config::Apple::Profile::Profile;
53             push @{$profile->content}, $email;
54            
55             print $profile->export;
56              
57             =head1 DESCRIPTION
58              
59             This class implements the Email payload, which is used to configure POP
60             and IMAP accounts. For Exchange accounts, refer to
61             L or
62             L.
63              
64             Each email account has basic information, information about how to fetch mail,
65             information about how to send mail, S/MIME configuration, and interaction.
66              
67             For fetching mail, either POP or IMAP can be used. Authentication is with
68             a password, or it can be turned off. SMTP is used for sending mail, either
69             with or without a username and password. SSL is supported for both sending
70             and receiving, and is enabled by default.
71              
72             B If the server(s) are only accessible on an internal network, you may
73             want to include a VPN payload as part of the profile, so that the user will
74             be able to access the server(s) while not on the internal Wi-Fi network.
75              
76             Passwords can be included in the payload, but then the payload should be
77             encrypted, or delivered in some secure manner. If passwords are not specified,
78             the user will be prompted to enter the password when the profile is installed.
79              
80             S/MIME can be configured for email signing and decryption. For S/MIME to work,
81             a .p12 file (a private key and certificate in a PKCS#12 container, also known
82             as an "identity certificate") must be on the device. The identity certificate
83             can be loaded using L,
84             and may be part of the same profile, or a different profile. If S/MIME is
85             enabled but no signing or decrypting certificates are specified in the payload,
86             the user will be able to choose which identity certificate to use.
87              
88             =head1 INSTANCE METHODS
89              
90             The following instance methods are provided, or overridden, by this class.
91              
92             =head2 validate_key($key, $value)
93              
94             Performs additional validation for certain payload keys in this class:
95              
96             =over 4
97              
98             =item * C
99              
100             This must be a properly-formed email address.
101              
102             =item * C
103              
104             This must be the string C or C.
105              
106             =item * C and C
107              
108             These must be properly-formed hostnames or IP addresses (IPv4 or IPv6).
109              
110             =item * C and C
111              
112             These must be positive numbers less than 65535.
113              
114             =item * C and
115             C
116              
117             These must be the string C or C.
118              
119             All other payload keys will be checked as usual by the parent class.
120              
121             =back
122              
123             See also the documentation in L.
124              
125             =cut
126              
127             sub validate_key {
128 140     140 1 190 my ($self, $key, $value) = @_;
129            
130             # Let's check over some of our keys
131             # Email addresses must match RFC822
132 140 100 100     836 if ($key eq 'EmailAddress') {
    100 100        
    100 66        
    100          
    50          
133             ## no critic (ProhibitExplicitReturnUndef)
134 8 100       20 return undef if !defined($value);
135             ## use critic
136            
137 7         27 $value = Email::Valid->address($value);
138 7         2637 return $value;
139             }
140            
141             # Email accounts must be POP or IMAP
142             elsif ($key eq 'EmailAccountType') {
143 4 100       17 if ($value =~ m/^(EmailTypePOP|EmailTypeIMAP)$/s) {
144 2         9 return $1;
145             }
146             ## no critic (ProhibitExplicitReturnUndef)
147 2         6 return undef;
148             ## use critic
149             }
150            
151             # Hostnames must be hostnames, or IP addresses
152             elsif ( ($key eq 'IncomingMailServerHostName')
153             || ($key eq 'OutgoingMailServerHostName')
154             ) {
155 106 100       431 if ($value =~ m/^( $RE{net}{domain}{-nospace}
156             |$RE{net}{IPv4}
157             |$RE{net}{IPv6}
158             )$
159             /isx) {
160 32         11112 return $1;
161             }
162             ## no critic (ProhibitExplicitReturnUndef)
163 74         28394 return undef;
164             ## use critic
165             }
166            
167             # Port numbers must be port numbers
168             elsif ( ($key eq 'IncomingMailServerPortNumber')
169             || ($key eq 'OutgoingMailServerPortNumber')
170             ) {
171 14 100       81 if ($value =~ m/^(\d+)$/s) {
172 8         17 my $number = $1;
173 8 100 100     44 return $number if ($number > 0) && ($number < 65535);
174             }
175             ## no critic (ProhibitExplicitReturnUndef)
176 8         22 return undef;
177             ## use critic
178             }
179            
180             # Authentication must be by password or not at all
181             elsif ( ($key eq 'IncomingMailServerAuthentication')
182             || ($key eq 'OutgoingMailServerAuthentication')
183             ) {
184 8 100       28 if ($value =~ m/^(EmailAuthPassword|EmailAuthNone)$/s) {
185 4         17 return $1;
186             }
187             ## no critic (ProhibitExplicitReturnUndef)
188 4         13 return undef;
189             ## use critic
190             }
191            
192             # At this point, we've checked all of our special keys. Over to the parent!
193 0           return $self->SUPER::validate_key($key, $value);
194             }
195              
196              
197             =head1 PAYLOAD KEYS
198              
199             All of the payload keys defined in L
200             are used by this payload.
201              
202             This payload has the following additional keys:
203              
204             =head2 Basic account information
205              
206             =head3 C
207              
208             I
209              
210             A string. This is the account description shown in the Mail and Settings apps.
211              
212             =head3 C
213              
214             I
215              
216             The sender's name, shown in outgoing email addresses.
217              
218             =head3 C
219              
220             I
221              
222             The sender's full email address. If not provided, the user will be asked for
223             it during installation.
224              
225             =head2 Fetching mail
226              
227             =head3 C
228              
229             The type of email account. This is a string, either C or
230             C.
231              
232             =head3 CI
233              
234             The host name or IP address used for fetching mail.
235              
236             =head3 C
237              
238             I
239              
240             The port number used for fetching mail. If not specified, the default port
241             will be used.
242              
243             =head3 C
244              
245             I
246              
247             A Boolean, which defaults to true. If true, use SSL when fetching mail.
248              
249             =head3 C
250              
251             The authentication method for fetching mail. Allowed strings are
252             C and C.
253              
254             =head3 C
255              
256             I
257              
258             The username to use when fetching mail. If a string is not provided, but
259             authentication is used, the user will be asked for it during installation.
260              
261             =head3 C
262              
263             I
264              
265             The password to use when fetching mail. If a string is not provided, but
266             authentication is used, the user may be asked for it during installation.
267              
268             B This is private information. If this payload key is set, then the
269             profile should be delivered to the user in a secure way.
270              
271             =head2 Sending Mail
272              
273             =head3 C
274              
275             The host name or IP address used for sending mail.
276              
277             =head3 C
278              
279             I
280              
281             The port number used for sending mail. If not specified, ports 25, 587, and
282             465, in that order, will be tried.
283              
284             =head3 C
285              
286             I
287              
288             A Boolean, which defaults to true. If true, use SSL when fetching mail.
289              
290             =head3 C
291              
292             The authentication method for sending mail. Allowed strings are
293             C and C.
294              
295             =head3 C
296              
297             I
298              
299             The username to use when sending mail. If a string is not provided, but
300             authentication is used, the user will be asked for it during installation.
301              
302             =head3 C
303              
304             I
305              
306             The password to use when sending mail. If a string is not provided, but
307             authentication is used, the user may be asked for it during installation.
308              
309             B This is private information. If this payload key is set, then the
310             profile should be delivered to the user in a secure way.
311              
312             =head3 C
313              
314             I
315              
316             A Boolean, defaults to false. If no passwords have been set in the profile,
317             but passwords are in use, and this key is true, then the user will be asked
318             for a password once, and that one password will be used for fetching and
319             sending mail.
320              
321             =head2 S/MIME
322              
323             =head3 C
324              
325             I
326              
327             A Boolean. If true, this account supports S/MIME. Defaults to false.
328              
329             =head3 C
330              
331             I
332              
333             The UUID of the PKCS12 Certificate payload used to sign emails.
334              
335             =head3 C
336              
337             I
338              
339             The UUID of the PKCS12 Certificate payload used to decrypt emails.
340              
341             =head3 C
342              
343             I
344              
345             A Boolean. If true, users will be able to disable S/MIME on emails they send.
346             If false, S/MIME signing will be used for all emails, and S/MIME encryption will
347             be used whenever possible.
348              
349             Default is false.
350              
351             I
352              
353             =head2 Application Interaction
354              
355             =head3 C
356              
357             I
358              
359             A Boolean. If true, messages may not be moved to other email accounts, and
360             forwarding/replying from other accounts is prohibited. Defaults to false.
361              
362             This payload key only applies to iOS 5.0 and later.
363              
364             =head3 C
365              
366             I
367              
368             A Boolean. If true, 3rd-party applications may not use this account to send
369             mail. Defaults to false.
370              
371             This payload key only applies to iOS 5.0 and later.
372              
373             =head3 C
374              
375             I
376              
377             A Boolean. If true, this account is excluded from syncing recently-used
378             addresses. Defaults to false.
379              
380             This payload key only applies to iOS 6.0 and later.
381              
382             =head2 C
383              
384             This is fixed to the string C.
385              
386             =head2 C
387              
388             This is fixed to the value C<1>.
389              
390             =cut
391              
392             Readonly our %payloadKeys => (
393             # Bring in the common keys...
394             %Config::Apple::Profile::Payload::Common::payloadKeys,
395            
396             # ... and define our own!
397             # Start with information about the user
398             'EmailAccountDescription' => {
399             type => $ProfileString,
400             description => 'Description shown in the Mail and Settings apps.',
401             optional => 1,
402             targets => {
403             $TargetIOS => '5.0',
404             $TargetMACOSX => '10.7',
405             },
406             },
407             'EmailAccountName' => {
408             type => $ProfileString,
409             description => "The sender's name, used in outgoing messages.",
410             optional => 1,
411             targets => {
412             $TargetIOS => '5.0',
413             $TargetMACOSX => '10.7',
414             },
415             },
416             'EmailAddress' => {
417             type => $ProfileString,
418             description => "The sender's full email address. If not provided, the"
419             . 'user will be asked for it during installation.',
420             optional => 1,
421             targets => {
422             $TargetIOS => '5.0',
423             $TargetMACOSX => '10.7',
424             },
425             },
426            
427             # Information on how to fetch mail
428             'EmailAccountType' => {
429             type => $ProfileString,
430             description => 'Either EmailTypePOP or EmailTypeIMAP.',
431             targets => {
432             $TargetIOS => '5.0',
433             $TargetMACOSX => '10.7',
434             },
435             },
436             'IncomingMailServerHostName' => {
437             type => $ProfileString,
438             description => 'The host name or IP for fetching mail.',
439             targets => {
440             $TargetIOS => '5.0',
441             $TargetMACOSX => '10.7',
442             },
443             },
444             'IncomingMailServerPortNumber' => {
445             type => $ProfileNumber,
446             description => 'The port number used for fetching mail.',
447             optional => 1,
448             targets => {
449             $TargetIOS => '5.0',
450             $TargetMACOSX => '10.7',
451             },
452             },
453             'IncomingMailserverUseSSL' => {
454             type => $ProfileBool,
455             description => 'If true, use SSL to fetch mail. Defaults to true.',
456             targets => {
457             $TargetIOS => '5.0',
458             $TargetMACOSX => '10.7',
459             },
460             },
461             'IncomingMailServerAuthentication' => {
462             type => $ProfileString,
463             description => 'The authentication method for fetching mail. Allowed '
464             . 'values are EmailAuthPassword and EmailAuthNone.',
465             targets => {
466             $TargetIOS => '5.0',
467             $TargetMACOSX => '10.7',
468             },
469             },
470             'IncomingMailServerUsername' => {
471             type => $ProfileString,
472             description => 'The username to use when fetching mail. If not '
473             . 'provided, the user may be asked for it during '
474             . 'installation.',
475             optional => 1,
476             targets => {
477             $TargetIOS => '5.0',
478             $TargetMACOSX => '10.7',
479             },
480             },
481             'IncomingPassword' => {
482             type => $ProfileString,
483             description => 'The password to use when fetching mail. If not '
484             . 'provided, the user may be asked for it during '
485             . 'installation.',
486             optional => 1,
487             private => 1,
488             targets => {
489             $TargetIOS => '5.0',
490             $TargetMACOSX => '10.7',
491             },
492             },
493            
494             # Information on how to send mail
495             'OutgoingMailServerHostName' => {
496             type => $ProfileString,
497             description => 'The host name or IP for sending mail.',
498             targets => {
499             $TargetIOS => '5.0',
500             $TargetMACOSX => '10.7',
501             },
502             },
503             'OutgoingMailServerPortNumber' => {
504             type => $ProfileNumber,
505             description => 'The port number used for sending mail. If not '
506             . 'specified, ports 25, 587, and 465 are checked.',
507             targets => {
508             $TargetIOS => '5.0',
509             $TargetMACOSX => '10.7',
510             },
511             optional => 1,
512             },
513             'OutgoingMailserverUseSSL' => {
514             type => $ProfileBool,
515             description => 'If true, use SSL to send mail. Defaults to true.',
516             targets => {
517             $TargetIOS => '5.0',
518             $TargetMACOSX => '10.7',
519             },
520             },
521             'OutgoingMailServerAuthentication' => {
522             type => $ProfileString,
523             description => 'The authentication method for sending mail. Allowed '
524             . 'values are EmailAuthPassword and EmailAuthNone.',
525             targets => {
526             $TargetIOS => '5.0',
527             $TargetMACOSX => '10.7',
528             },
529             },
530             'OutgoingMailServerUsername' => {
531             type => $ProfileString,
532             description => 'The username to use when sending mail. If not '
533             . 'provided, the user may be asked for it during '
534             . 'installation.',
535             optional => 1,
536             targets => {
537             $TargetIOS => '5.0',
538             $TargetMACOSX => '10.7',
539             },
540             },
541             'OutgoingPassword' => {
542             type => $ProfileString,
543             description => 'The password to use when sending mail. If not '
544             . 'provided, the user may be asked for it during '
545             . 'installation.',
546             optional => 1,
547             private => 1,
548             targets => {
549             $TargetIOS => '5.0',
550             $TargetMACOSX => '10.7',
551             },
552             },
553             'OutgoingPasswordSameAsIncomingPassword' => {
554             type => $ProfileBool,
555             description => 'If true, the user will be prompted for a password only '
556             . 'once, and it will be used for sending and '
557             . 'receiving mail.',
558             optional => 1,
559             targets => {
560             $TargetIOS => '5.0',
561             $TargetMACOSX => '10.7',
562             },
563             },
564            
565             # S/MIME
566             'SMIMEEnabled' => {
567             type => $ProfileBool,
568             description => 'If true, this account supports S/MIME. Default false.',
569             optional => 1,
570             targets => {
571             $TargetIOS => '5.0',
572             },
573             },
574             'SMIMESigningCertificateUUID' => {
575             type => $ProfileUUID,
576             description => 'The UUID of the PKCS12 payload used to sign emails.',
577             optional => 1,
578             targets => {
579             $TargetIOS => '5.0',
580             },
581             },
582             'SMIMEEncryptionCertificateUUID' => {
583             type => $ProfileUUID,
584             description => 'The UUID of the PKCS12 payload used to decrypt emails.',
585             optional => 1,
586             targets => {
587             $TargetIOS => '5.0',
588             },
589             },
590             'SMIMEEnablePerMessageSwitch' => {
591             type => $ProfileBool,
592             description => 'Allow users to disable use of S/MIME when they want.',
593             optional => 1,
594             targets => {
595             $TargetIOS => '8.0',
596             },
597             },
598            
599             # Application interaction
600             'PreventMove' => {
601             type => $ProfileBool,
602             description => 'If true, messages may not be moved to other email '
603             . 'accounts, and forwarding/replying from other '
604             . 'accounts is prohibited. Defaults to false.',
605             optional => 1,
606             targets => {
607             $TargetIOS => '5.0',
608             },
609             },
610             'PreventAppSheet' => {
611             type => $ProfileBool,
612             description => 'If true, 3rd-party applications may not use this '
613             . 'account to send mail. Defaults to false.',
614             optional => 1,
615             targets => {
616             $TargetIOS => '5.0',
617             },
618             },
619             'disableMailRecentsSyncing' => {
620             type => $ProfileBool,
621             description => 'If true, this account is excluded from syncing '
622             . 'recently-used addresses. Defaults to false.',
623             optional => 1,
624             targets => {
625             $TargetIOS => '6.0',
626             },
627             },
628            
629             # Finish with basic payload information
630             'PayloadType' => {
631             type => $ProfileString,
632             value => 'com.apple.mail.managed',
633             targets => {
634             $TargetIOS => '5.0',
635             $TargetMACOSX => '10.7',
636             },
637             },
638             'PayloadVersion' => {
639             type => $ProfileNumber,
640             value => 1,
641             targets => {
642             $TargetIOS => '5.0',
643             $TargetMACOSX => '10.7',
644             },
645             },
646             ); # End of %payloadKeys
647              
648              
649             =head1 ACKNOWLEDGEMENTS
650              
651             Refer to L for acknowledgements.
652              
653             =head1 AUTHOR
654              
655             A. Karl Kornel, C<< >>
656              
657             =head1 COPYRIGHT AND LICENSE
658              
659             Copyright © 2014 A. Karl Kornel.
660              
661             This program is free software; you can redistribute it and/or modify it
662             under the terms of either: the GNU General Public License as published
663             by the Free Software Foundation; or the Artistic License.
664              
665             See L for more information.
666              
667             =cut
668              
669             1;