mobileconfig

Use mobileconfig.getSignedCardDAVConfig(options, callback) to generate a signed CardDAV configuration.

Options Object Properties:

• organization: (Optional) Name of the signing organization.
• identifier: (Required) Reverse-DNS style identifier.
• displayName: (Optional) Name for the profile.
• displayDescription: (Optional) Description for the profile.
• accountName: (Optional) Name for the CardDAV account.
• accountDescription: (Optional) Description for the CardDAV account.
• dav: CardDAV server configuration:
  • hostname: Server hostname.
  • port: (Optional) Server port.
  • secure: Boolean for TLS/SSL usage.
  • principalurl: URL for the authenticated user's principal resource.
  • username: Account username.
  • password: Account password.

Callback: (err, data) => void. data is the signed DER file as a Buffer.

mobileconfig.getSignedCardDAVConfig(options, callback);

Use mobileconfig.getSignedEmailConfig(options, callback) to generate a signed Email account configuration (IMAP only).

Options Object Properties:

• emailAddress: The address to be configured.
• organization: (Optional) Name of the signing organization.
• identifier: (Required) Reverse-DNS style identifier (e.g., com.example.myprofile).
• displayName: (Optional) Name for the profile.
• displayDescription: (Optional) Description for the profile.
• accountName: (Optional) Name for the email account.
• accountDescription: (Optional) Description for the email account.
• imap: Incoming IMAP configuration:
  • hostname: Server hostname.
  • port: (Optional) Server port.
  • secure: Boolean indicating if TLS/SSL should be used (does not affect STARTTLS).
  • username: Account username.
  • password: Account password.
• smtp: Outgoing SMTP configuration:
  • hostname: Server hostname.
  • port: (Optional) Server port.
  • secure: Boolean indicating if TLS/SSL should be used.
  • username: (Optional) SMTP username. If missing, no authentication is used.
  • password: (Optional) SMTP password. If missing, the IMAP password is used.
• keys: Object containing key and cert for signing (see Signing configuration).

Callback: (err, data) => void. err is an Error object; data is the signed DER file as a Buffer. Save data as name.mobileconfig to use it.

const options = {
    emailAddress: 'my-email-address@gmail.com',
    identifier: 'com.my.company',
    imap: {
        hostname: 'imap.gmail.com',
        secure: true,
        username: 'my-email-address@gmail.com',
        password: 'mypass'
    },
    smtp: {
        hostname: 'smtp.gmail.com',
        port: 587,
        secure: false,
        username: 'my-email-address@gmail.com',
        password: false // use the same password as for IMAP
    },
    keys: {
        key: '-----BEGIN PRIVATE KEY-----...',
        cert: '-----BEGIN CERTIFICATE-----...'
    }
};

mobileconfig.getSignedEmailConfig(options, function (err, data) {
    console.log(err || data);
});

Use mobileconfig.getSignedCalDAVConfig(options, callback) to generate a signed CalDAV configuration.

Options Object Properties:

• organization: (Optional) Name of the signing organization.
• identifier: (Required) Reverse-DNS style identifier.
• displayName: (Optional) Name for the profile.
• displayDescription: (Optional) Description for the profile.
• accountName: (Optional) Name for the CalDAV account.
• accountDescription: (Optional) Description for the CalDAV account.
• dav: CalDAV server configuration:
  • hostname: Server hostname.
  • port: (Optional) Server port.
  • secure: Boolean for TLS/SSL usage.
  • principalurl: URL for the authenticated user's principal resource.
  • username: Account username.
  • password: Account password.

Callback: (err, data) => void. data is the signed DER file as a Buffer.

mobileconfig.getSignedCalDAVConfig(options, callback);

Use getSignedConfig(plistData, keys, callback) to sign an existing JavaScript object representing a plist structure. This is useful when you have a custom configuration that doesn't fit the built-in templates.

Parameters:

• plistData: A JavaScript object representing the plist structure. This will be converted to a plist string using the plist library before signing.
• keys: An object containing signing credentials (see sign method).
• callback: A callback function receiving (err, signedDer).

const mobileconfig = require('mobileconfig');

const myCustomPlist = {
    PayloadContent: [],
    PayloadDisplayName: 'Custom Profile',
    PayloadIdentifier: 'com.example.custom',
    PayloadType: 'Configuration',
    PayloadUUID: '...',
    PayloadVersion: 1
};

const keys = {
    cert: '...', 
    key: '...'
};

mobileconfig.getSignedConfig(myCustomPlist, keys, (err, signedDer) => {
    if (err) throw err;
    // signedDer is the signed profile
});

Use getSignedCardDAVConfig(options, callback) to generate a signed iOS profile for CardDAV contacts. It uses getCardDAVConfig to build the plist and then signs it.

Options Object:

• emailAddress: The email address for the account.
• organization: Organization info.
• identifier: Profile identifier.
• displayName: Display name for the account.
• accountName: Name of the CardDAV account.
• dav: Object containing hostname, port, principalurl, secure (boolean), username, and password.
• keys: Signing options (see sign method for details).

const mobileconfig = require('mobileconfig');

const options = {
    dav: {
        hostname: 'dav.example.com',
        principalurl: 'https://dav.example.com/principals',
        secure: true,
        username: 'user',
        password: 'password'
    },
    keys: {
        cert: '...', 
        key: '...'
    }
};

mobileconfig.getSignedCardDAVConfig(options, (err, signedDer) => {
    if (err) throw err;
    // signedDer is the signed profile
});

The sign(value, options, callback) method is the core signing engine. It takes a raw string (the content to be signed) and wraps it in a CMS (Cryptographic Message Syntax) SignedData structure.

Parameters:

• value: The string content to sign (e.g., a plist string).
• options: Configuration for the signature:
  • cert: The signer's certificate (PEM string).
  • ca: A single certificate string or an array of certificate strings (the CA chain).
  • key: The private key (PEM string).
  • hashAlg: The hash algorithm (e.g., sha256, sha512, sha384, sha224, sha1, md5, ripemd160). Defaults to sha256.
  • sigAlg: The signature algorithm (e.g., SHA256withRSA, SHA512withRSA, SHA256withECDSA, etc.). Defaults to SHA256withRSA.
  • signingTime: If provided, includes the signingTime attribute in the signed attributes.
• callback: A callback function receiving (err, derBuffer) where derBuffer is the resulting signed DER-encoded CMS data.

const mobileconfig = require('mobileconfig');

const content = '<plist>...</plist>';
const options = {
    cert: '-----BEGIN CERTIFICATE-----\n...', 
    key: '-----BEGIN RSA PRIVATE KEY-----\n...',
    hashAlg: 'sha256',
    sigAlg: 'SHA256withRSA'
};

mobileconfig.sign(content, options, (err, der) => {
    if (err) throw err;
    // der is a Buffer of the signed CMS data
});

Use getSignedEmailConfig(options, callback) to generate a complete, signed iOS .mobileconfig profile for Email (IMAP/SMTP). This function internally generates the un-signed plist using getEmailConfig and then signs it using the provided keys.

Options Object:

• emailAddress: The email address for the account (defaults to admin@localhost).
• organization: Boolean or string for organization info.
• identifier: The profile identifier (defaults to com.kreata.anonymous).
• displayName: The name shown in Mail settings.
• displayDescription: Description for the account.
• accountName: Name of the account.
• accountDescription: Description of the account.
• emailAccountName: Specific account name.
• imap: Object containing hostname, port, secure (boolean), username, and password.
• smtp: Object containing hostname, port, secure (boolean), username, and password.
• contentUuid: Custom UUID for the content.
• plistUuid: Custom UUID for the plist.
• keys: An object passed to the sign method containing cert, ca (string or array of strings), key, hashAlg, and sigAlg.

const mobileconfig = require('mobileconfig');

const options = {
    emailAddress: 'user@example.com',
    imap: {
        hostname: 'imap.example.com',
        port: 993,
        secure: true,
        username: 'user@example.com',
        password: 'password123'
    },
    smtp: {
        hostname: 'smtp.example.com',
        port: 465,
        secure: true,
        username: 'user@example.com',
        password: 'password123'
    },
    keys: {
        cert: '-----BEGIN CERTIFICATE-----\n...', 
        key: '-----BEGIN RSA PRIVATE KEY-----\n...',
        hashAlg: 'sha256',
        sigAlg: 'SHA256withRSA'
    }
};

mobileconfig.getSignedEmailConfig(options, (err, signedDer) => {
    if (err) throw err;
    // signedDer is a Buffer containing the signed CMS data
});