The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Config-Apple-Profile-v0.87.1-TRIAL
River stage zero No dependents
++
/ Config::Apple::Profile

NAME

Config::Apple::Profile - An OO interface to Apple Configuration Profiles.

SYNOPSIS

    use File::Temp;
    use Config::Apple::Profile;
    use Config::Apple::Profile::Payload::Certificate::PEM;
    use Config::Apple::Profile::Payload::Wireless;

    my $cert = new Config::Apple::Profile::Payload::Certificate::PEM;
    my $cert_payload = $cert->payload;
    $cert_payload->{PayloadIdentifier} = 'com.example.group15.payload.cert';
    $cert_payload->{PayloadCertificateFileName} = 'myCA.pem';
    $cert_payload->{PayloadContent} = <<END;
    ----- BEGIN CERTIFICATE -----
    dsfkldfsbnjksjkgnndbfjkdgnjdfkgjkndfg
    # snip
    dgkdfgldmklbgklmd==
    ----- END CERTIFICATE -----
    ENDCERT

    my $wifi = new Config::Apple::Profile::Payload::Wireless;
    my $wifi_payload = $wifi->payload;
    $wifi_payload->{PayloadIdentifier} = 'com.example.group15.payload.wireless';
    $wifi_payload->{SSID_STR} = 'CorpNet Public';
    $wifi_payload->{EncryptionType} = 'None';

    my $profile = new Config::Apple::Profile;
    my $profile_payload = $profile->payload;
    $profile_payload->{PayloadIdentifier} = 'com.example.group15.payload';
    $profile_payload->{PayloadDisplayName} = "My Group's Profile";
    push @{$profile_payload->{PayloadContent}}, $cert_payload, $wireless_payload;

    my ($fh, $file) = tempfile('CorpConfig',
                               SUFFIX => '.mobileconfig', UNLINK => 0);
    print $fh $profile->export;
    close $fh;
    print "Configuration Profile written to $file\n";

DESCRIPTION

Apple provides users with a way to configure Apple devices (running iOS or Mac OS X) using ready-made configuration files, which Apple calls Configuration Profiles. This suite of Perl modules is intended to aid people who would like to generate their own configuration profiles, without having to mess around with the XML themselves.

Configuration profiles can be used by iOS and Mac OS X to set a number of general and user-specific items. Examples include:

  • Configuring an LDAP server, for directory search in Mail and Contacts.

  • Specifying password requirements to match company policy (and common sense).

  • Configuring an email account, with or without a user's credentials.

  • Adding new certificate authorities.

Configuration profiles can be pre-made static files, or they can be dynamically-generated with configurations (such as usernames and passwords) that are specific to a user. Configuration profiles may be encrypted (so they may only be read on a specific device) and signed (to verify that they have not been modified by anyone other than the profile's creator).

A configuration profile contains one or more Payloads, in addition to some header information. In Perl terms, a payload can be thought of as a Hash. There are some keys of the "hash" that are common to all types of payloads, and of course other keys that are payload-specific. Some keys are optinal, and some keys are only optional on one platform or the other (iOS or Mac OS X). In addition, there are some payloads that are only valid on one platform. For example, the Config::Apple::Profile::Payload::FileVault payload can only be used with a Mac OS X configuration profile.

For a list of all payloads that Apple currently recognizes, refer to the Configuration Profile Reference linked below. Not all payloads are implemented in this release. If you are interested in seeing more payloads supported, please contribute! See the SOURCE section below for more info.

CLASS HIERARCHY

Classes are laid out in the following hierarchy:

 Config::Apple::
   Profile                  <-- This file
   Profile::
     Payload::              <-- All payload-related classes are in here
       Common.pm            <-- Common payload elements are here
       Certificate.pm       <-- The Certificate payload type
       Certificate::        <-- Certificate sub-types are here
       Email.pm             <-- The Email payload type
       Tie::                <-- Internal support code
     Encryption.pm          <-- Profile encryption (TBI)
     Signing.pm             <-- Profile signing (TBI)

Clients need only use the modules that directly provide the functionality they are looking for.

As an example, if you want to create a configuration profile that configures an IMAP email account, an LDAP server, and a passcode policy, you would need the following modules:

CLASS METHODS

new()

Returns a new object.

INSTANCE METHODS

INHERITED METHODS

Most of the methods, including critical ones such as keys and payload, are implemented in the module Config::Apple::Profile::Payload::Common, and are not reimplemented here. See Config::Apple::Profile::Payload::Common.

export()

    export([C<option1_name> => C<option1_value>, ...])

Return a string containing the profile, serialized as XML. The entire string will already be encoded as UTF-8. If any UUID or Identifier keys have not been filled in, they are filled in with random values.

This method is used when it is time to output a profile.

Several parameters can be provided, which will influence how this method runs.

target

If target (a value from Config::Apple::Profile::Targets) is provided, then this will be taken into account when exporting. Only payload keys that are used on the specified target will be included in the output.

The completeness option controls what happens if keys are excluded.

version

If version (a version string) is provided, then only payload keys that work on the specified version will be included in the output.

If version is provided, then target must also be set, but target can be set without setting version.

The completeness option controls what happens if keys are excluded.

completeness

If completeness is set to a true value, and keys are excluded because of target or version, then plist will throw an exception. If set to a false value, or if not set at all, then no exceptions will be thrown, and a less-than-complete (but still valid) plist will be returned.

The following exceptions may be thrown:

Config::Apple::Profile::Exception::KeyRequired

Thrown if a required key has not been set.

Config::Apple::Profile::Exception::Incomplete

Thrown if payload keys are being excluded from the output because of target or version.

PAYLOAD KEYS

Payload keys are the keys that you can use when manipulating the hash returned by payload.

All of the payload keys defined in Config::Apple::Profile::Payload::Common are used by this payload.

This payload has the following additional keys:

PayloadContent

Optional, but not really

An array of Config::Apple::Profile::Payload:: objects.

EncryptedPayloadContent

Optional

Payload contents that are encrypted, such that only a single device may decrypt and read it. This is a Data type, which is formed by first taking the contents of PayloadContent, and serializing them as a plist with an array as the root element. Next, the contents are CMS-encrypted as enveloped data, then finally DER-encoded.

Until Config::Apple::Profile::Encryption is implemented, the following OpenSSL command can be used to encrypt the plist.

    openssl cms -encrypt -in your.mobileconfig_fragment 
    -out your.mobileconfig_fragment.encrypted -outform der -cmsout
    your_recipients_cert.pem

OpenSSL 1 or later is required for the cms command.

PayloadScope

Optional

Applies to Mac OS X only.

Can be set to "System", in which case the profile will apply system-wide, or "User", in which case the profile will only apply to the user installing the profile.

If not set, the default is "User".

ConsentText

Optional

A dictionary of strings. The keys are locale identifiers, specifically canonicalized IETF BCP 47 locale strings. Each value is a localized text string containing a message that the user will see when installing the profile. This is a place to put warnings, agreements, etc..

An extra pair, with the key "default", may be included to provide a default consent message. If no default is set, the "en" localization will be used as a last resort.

PayloadRemovalDisallowed

Optional

A boolean. If set to true, then the profile may only be removed if a profile removal password is provided. To set such a password, include an object from Config::Apple::Profile::Payload::ProfileRemovalPassword as part of PayloadContents.

DurationUntilRemoval

Optional

A floating-point number, the number of seconds that the profile will remain on the device before it is automatically removed.

If RemovalDate is set, this value will be ignored.

RemovalDate

Optional

A date. Once past, the profile will be automatically removed from the device.

This value overrides DurationUntilRemoval.

PayloadExpirationDate

Optional

A date. This only applies to payloads delivered over-the-air, using a mobile device management (MDM) solution. Once past, this profile will be marked as "expired", and will be eligible for updating over-the-air.

SEE ALSO

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Config::Apple::Profile

All modules have some POD inside them. If you're not interested in using the command-line, your IDE may have PerlDoc support, or you can go here:

If you have found a bug, or want to request an enhancement of some sort, you may do so here:

Finally, feel free to rate the release!

SOURCE

This project is on GitHub:

https://github.com/akkornel/Config-Apple-Profile

The web site linked above has the most recently-pushed code, along with information on how to get a copy to your computer.

If you are interested in making a contribution, please make it in the form of a GitHub pull request.

ACKNOWLEDGEMENTS

Thanks are due to Brian D Foy (BDFOY) for the Mac::PropertyList module, which is relied on heavily by this code!

AUTHOR

A. Karl Kornel, <karl at kornel.us>

COPYRIGHT AND LICENSE

Copyright 2014 A. Karl Kornel.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.