plugin-network-security-config

The “plugin-network-security-config” package is an essential Flagship Code plugin designed to automate the generation and management of the Android Network Security Configuration file (network_security_config.xml). This configuration file is crucial for defining security policies related to network connections, including trusted certificate authorities, domain-specific certificate pinning, and cleartext traffic permissions.

Developers may leverage this plugin to ensure that their Android applications adhere to best practices in network security, and to enable network debugging during development and internal testing phases.

Install

Add @brandingbrand/code-plugin-network-security-config as a development dependency to your React Native project.

Caution

This package is included in @brandingbrand/code-preset-react-native.

If you are using this preset, skip this step and avoid installing this package directly.

yarn

yarn add --dev @brandingbrand/code-plugin-network-security-config

npm

npm install --save-dev @brandingbrand/code-plugin-network-security-config

pnpm

pnpm add --save-dev @brandingbrand/code-plugin-network-security-config

bun

bun add --dev @brandingbrand/code-plugin-network-security-config

Your package.json should now be updated, @brandingbrand/code-plugin-network-security-config should be listed as a devDependency.

package.json

{
  "name": "my-awesome-app",
  "version": "1.0.0",
  "author": "Your Name <email@example.com>",
  "dependencies": {
    "react": "^18.2.0",
    "react-native": "~0.72.0"
  },
  "devDependencies": {
    "@brandingbrand/code-plugin-network-security-config": "2.0.0"
  }
}

Configure

Flagship Code Configuration

Upon installing the dependency, it is imperative to update the flagship-code.config.ts file. Specifically, ensure that the plugins array includes the newly installed dependency. This step is crucial, as Flagship Code will only invoke the plugin if it is listed within this array. By including the dependency in the plugins array, you enable Flagship Code to recognize and utilize the functionality provided by the plugin during project execution.

Caution

This plugin is included in @brandingbrand/code-preset-react-native.

If you are using this preset, you should skip this step.

Standalone

flagship-code.config.ts

import { defineConfig } from "@brandingbrand/code-cli-kit";

export default defineConfig({
  buildPath: "./coderc/build",
  envPath: "./coderc/env",
  pluginPath: "./coderc/plugins",
  plugins: [
    // other plugins
    "@brandingbrand/code-plugin-network-security-config",
  ],
});

With code-preset-react-native

flagship-code.config.ts

import { defineConfig } from "@brandingbrand/code-cli-kit";

export default defineConfig({
  buildPath: "./coderc/build",
  envPath: "./coderc/env",
  pluginPath: "./coderc/plugins",
  preset: "@brandingbrand/code-preset-react-native",
  plugins: [
    // other plugins
  ],
});

For more detailed guidance and information, please refer to the Flagship Code Configuration guide. This resource offers comprehensive instructions and insights to assist you in configuring Flagship Code effectively.

Build Configuration

Depending on the plugin being utilized, additional configuration may be required. In the case of the plugin-network-security-config, additional configuration to generate a production-ready network_security_config.xml is not required.

Generating a debuggable network_security_config.xml in development or internal builds does require additional configuration.

Standalone

build.internal.ts

import { defineBuild } from "@brandingbrand/code-cli-kit";
import { type CodePluginNetworkSecurityConfig } from "@brandingbrand/code-plugin-network-security-config";

export default defineBuild<CodePresetReactNative & CodePluginNetworkSecurityConfig>({
  ios: {
    bundleId: "com.brandingbrand",
    displayName: "Branding Brand",
  },
  android: {
    packageName: "com.brandingbrand",
    displayName: "Branding Brand",
  },
  codePluginNetworkSecurityConfig: {
    plugin: {
      preset: 'debug', // or 'release' for production builds
    },
  },
});

With code-preset-react-native

build.internal.ts

import { defineBuild } from "@brandingbrand/code-cli-kit";
import { type CodePresetReactNative } from "@brandingbrand/code-preset-react-native";

export default defineBuild<CodePresetReactNative>({
  ios: {
    bundleId: "com.brandingbrand",
    displayName: "Branding Brand",
  },
  android: {
    packageName: "com.brandingbrand",
    displayName: "Branding Brand",
  },
  codePluginNetworkSecurityConfig: {
    plugin: {
      preset: 'debug', // or 'release' for production builds
    },
  },
});

Options

preset

type: 'debug' | 'release'

default: 'release'

Determines the base configuration for the generated network security config.

Release

network_security_config.xml

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>
</network-security-config>

Debug

network_security_config.xml

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="user"/>
            <certificates src="system"/>
        </trust-anchors>
    </debug-overrides>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system"/>
            <certificates src="user"/>
        </trust-anchors>
    </base-config>
</network-security-config>

certificatesDir

type: string

Optional path to a directory, relative to the project root, which contains custom certificates to define within the network security config.

For more information on defining custom certificate authorities, see Android Developer Docs

Caution

Configuring this option will only copy the certificates to the res/raw directory.

To include the certificate in the network security config, you must also include the certificate through the certificates, debugCertificates, or domainConfig options.

certificates,

type: NetworkSecurityCertificates[]

certificates xml elements to append to the base-config section of the network security config.

This option will not overwrite the default configuration included by the preset option.

Elements are expressed as JSON objects. See the type definition below for more details.

debugCertificates,

type: NetworkSecurityCertificates[]

certificates xml elements to append to the debug-overrides section of the network security config.

This option will not overwrite the default configuration included by the preset option.

Elements are expressed as JSON objects. See the type definition below for more details.

domainConfig

type: NetworkSecurityDomainConfig[]

domain-config XML elements to append to the network security config.

This option allows for full customization of the domain-config section of the network security config.

Type Definitions

NetworkSecurityCertificates

The JSON representation of a certificates xml element, as defined in code-cli-kit.

export type NetworkSecurityCertificates = {
  $: {
    /** The source of the certificates. Can be 'system', 'user', or a raw resource path. */
    src: 'system' | 'user' | `@raw/${string}`;
    /** Indicates whether to override existing pins for the certificates. */
    overridePins?: boolean;
  }
};

Example:

Source

{ $: { src: 'system', overridePins: true, } };

Generated XML

<certificates src="system" overridePins="true"/>

NetworkSecurityDomainConfig

The JSON representation of a domain-config xml element, as defined in code-cli-kit.

Domain configurations allow for granular control over network security settings for specific domains, including cleartext traffic permissions, root certificate trust anchors, and server certificate pinning.

type NetworkSecurityDomainConfig = {
  $?: {
    /** Indicates whether cleartext traffic is permitted for the domain configuration. */
    cleartextTrafficPermitted?: boolean;
  }
  /** Array of domain entries. Must have at least one domain. */
  domain: {
    $?: {
      /** Indicates whether subdomains are included. */
      includeSubdomains?: boolean;
    };
    /** The domain string. */
    _: string;
  }[];
  /** Optional: Certificate transparency validation configuration. */
  certificateTransparency?: {
    /** Indicates whether certificate validation through Certificate Transparency logs is enabled. */
    $: { enabled: boolean; };
  };
  /** Optional: Trust anchors section in the domain configuration. */
  ['trust-anchors']?: {
    certificates: NetworkSecurityCertificates[];
  };
  /** Optional: Pin set in the domain configuration. Enables SSL certificate pinning */
  ['pin-set']?: {
    $?: {
      /** Optional: Expiration date for the pin set in ISO 8601 format (YYYY-MM-DD). */
      expiration?: string;
    }
    pin: {
      $: {
        /** The hash algorithm used for the pin. Currently, only SHA-256 is supported by Android */
        digest: 'SHA-256';
      };
      /** The public key pin value */
      _: string;
    }[]
  };
  /** Optional: Nested domain configurations. */
  ['domain-config']?: NetworkSecurityDomainConfig[];
};

Example:

Source

export const exampleDomainConfig = {
  $: { cleartextTrafficPermitted: true },
  'domain': [{ $: { includeSubdomains: true }, _: "example.com" }],
  'trust-anchors': {
    certificates: [
      { $: { src: 'system' } },
      { $: { src: 'user' } }
    ]
  },
  'pin-set': {
    $: { expiration: "2025-12-31" },
    pin: [
      { $: { digest: 'SHA-256' }, _: 'Base64EncodedPinValueHere==' }
    ]
  }
}

Generated XML

<domain-config
  cleartextTrafficPermitted="true">
  <domain includeSubdomains="true">example.com</domain>
  <trust-anchors>

    <certificates src="system"/>
    <certificates src="user"/>

  </trust-anchors>
  <pin-set
    expiration="2025-12-31">

    <pin digest="SHA-256">Base64EncodedPinValueHere==</pin>

  </pin-set>
</domain-config>