Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Migrated \"Network Security Configuration\" page on DAC (N OTA).

Browse Source 
am: 78747a1164

Change-Id: I095a1e37838e325f7b10146cde3efb271a315ed2
This commit is contained in:
Kevin Hufnagle
2016-07-26 19:04:18 +00:00
committed by android-build-merger
parent 1c2845238a 78747a1164
commit 1d7a40b34d
3 changed files with 82 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/html/_redirects.yaml
View File

@@ -1206,3 +1206,5 @@ redirects:
- from: /preview/features/key-attestation.html
to: /training/articles/security-key-attestation.html
- from: /preview/features/security-config.html
to: /training/articles/security-config.html

5
docs/html/training/_book.yaml
View File

@@ -1363,6 +1363,11 @@ toc:
path_attributes:
- name: description
value: How to ensure that your app is secure when performing network transactions.
- title: Network Security Configuration
path: /training/articles/security-config.html
path_attributes:
- name: description
value: Customize the behavior of your app's secure network connections safely.
- title: Updating Your Security Provider to Protect Against SSL Exploits
path: /training/articles/security-gms-provider.html
path_attributes:

148
docs/html/preview/features/security-config.jd → docs/html/training/articles/security-config.jd
View File

@@ -1,11 +1,12 @@
page.title=Network Security Configuration
page.keywords=androidn,security,network
page.keywords=security,network,config
page.metaDescription=Feature that allows app developers to customize network security settings in a safe configuration file.
page.image=images/cards/card-nyc_2x.jpg
@jd:body
<div id="qv-wrapper">
<div id="qv">
<div id="tb-wrapper">
<div id="tb">
<h2>In this document</h2>
<ol>
@@ -28,11 +29,10 @@ page.image=images/cards/card-nyc_2x.jpg
<p>
Android N includes a Network Security Configuration
feature that lets apps customize their network security settings in a safe,
declarative configuration file without modifying app code. These settings can
be configured for specific domains and for a specific app. The key
capabilities of this feature are as follows:
The Network Security Configuration feature lets apps customize their network
security settings in a safe, declarative configuration file without modifying
app code. These settings can be configured for specific domains and for a
specific app. The key capabilities of this feature are as follows:
</p>
<ul>
@@ -49,7 +49,7 @@ page.image=images/cards/card-nyc_2x.jpg
</li>
<li>
<b>Cleartext traffic opt-out:</b> Protect apps from from
<b>Cleartext traffic opt-out:</b> Protect apps from
accidental usage of cleartext traffic.
</li>
@@ -72,10 +72,10 @@ page.image=images/cards/card-nyc_2x.jpg
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest ... &gt;
&lt;application android:networkSecurityConfig="@xml/network_security_config"
... &gt;
...
&lt;/application&gt;
&lt;application android:networkSecurityConfig="@xml/network_security_config"
... &gt;
...
&lt;/application&gt;
&lt;/manifest&gt;
</pre>
@@ -87,12 +87,12 @@ page.image=images/cards/card-nyc_2x.jpg
</p>
<ul>
<li>Connecting to a host with a custom certificate authority(self-signed,
issued by an internal corporate CA, etc).
<li>Connecting to a host with a custom certificate authority, such as a
CA that is self-signed or is issued internally within a company.
</li>
<li>Limiting the set of CAs to only the CAs you trust instead of every
preinstalled CA.
pre-installed CA.
</li>
<li>Trusting additional CAs not included in the system.
@@ -100,12 +100,11 @@ page.image=images/cards/card-nyc_2x.jpg
</ul>
<p>
By default secure (e.g. TLS, HTTPS) connections from all apps trust
the pre-installed system CAs, and apps targeting API level 23
(Android M) and below also trust the user-added CA store by default. An
app can customize its own connections using {@code base-config} (for
app-wide customization) or {@code domain-config} (for per-domain
customization).
By default, secure connections (using protocols like TLS and HTTPS) from all
apps trust the pre-installed system CAs, and apps targeting Android 6.0 (API
level 23) and lower also trust the user-added CA store by default. An app can
customize its own connections using {@code base-config} (for app-wide
customization) or {@code domain-config} (for per-domain customization).
</p>
@@ -147,8 +146,8 @@ page.image=images/cards/card-nyc_2x.jpg
</p>
<p>
The config to limit the set of trusted CAs is similar to <a href=
"#TrustingACustomCa">trusting a custom CA</a> for a specific domain except
The configuration to limit the set of trusted CAs is similar to <a href=
"#ConfigCustom">trusting a custom CA</a> for a specific domain except
that multiple CAs are provided in the resource.
</p>
@@ -207,14 +206,14 @@ elements instead of one.
<h2 id="TrustingDebugCa">Configuring CAs for Debugging</h2>
<p>
When debugging an app that connects over HTTPS you may want to
When debugging an app that connects over HTTPS, you may want to
connect to a local development server, which does not have the SSL
certificate for your production server. In order to support this without any
modification to your app's code you can specify debug-only CAs that
are <i>only</i> trusted when <a href=
modification to your app's code, you can specify debug-only CAs, which
are trusted <i>only</i> when <a href=
"{@docRoot}guide/topics/manifest/application-element.html#debug">
android:debuggable</a>
is {@code true} by using {@code debug-overrides}. Normally IDEs and build
is {@code true}, by using {@code debug-overrides}. Normally, IDEs and build
tools set this flag automatically for non-release builds.
</p>
@@ -243,7 +242,7 @@ android:debuggable</a>
<p>
Applications intending to connect to destinations using only secure
connections can opt-out of supporting cleartext (using unencrypted HTTP
connections can opt-out of supporting cleartext (using the unencrypted HTTP
protocol instead of HTTPS) to those destinations. This option helps prevent
accidental regressions in apps due to changes in URLs provided by external
sources such as backend servers.
@@ -273,29 +272,30 @@ android:debuggable</a>
<h2 id="CertificatePinning">Pinning Certificates</h2>
<p>
Normally an app trusts all preinstalled CAs. If any of these CAs were
to issue a fradulent certificate the app would be at risk from a MiTM
attack. Some apps choose to limit the set of certificates they accept
by either limiting the set of CAs they trust or by certificate pinning.
Normally, an app trusts all pre-installed CAs. If any of these CAs were to
issue a fradulent certificate, the app would be at risk from a
man-in-the-middle attack. Some apps choose to limit the set of certificates
they accept by either limiting the set of CAs they trust or by certificate
pinning.
</p>
<p>
Certificate pinning is done by providing a set of certificates by hash of the
public key (SubjectPublicKeyInfo of the X.509 certificate). A certificate
chain is then only valid if the certificate chain contains at least one of
the pinned public keys.
public key (<code>SubjectPublicKeyInfo</code> of the X.509 certificate). A
certificate chain is then valid only if the certificate chain contains at
least one of the pinned public keys.
</p>
<p>
Note that when using certificate pinning you should always include a backup
key so that if you are forced to switch to new keys, or change CAs (when
Note that, when using certificate pinning, you should always include a backup
key so that if you are forced to switch to new keys or change CAs (when
pinning to a CA certificate or an intermediate of that CA), your
app's connectivity is unaffected. Otherwise you must to push out
app's connectivity is unaffected. Otherwise, you must push out
an update to the app to restore connectivity.
</p>
<p>
Additionally it is possible to set an expiration time for pins after which
Additionally, it is possible to set an expiration time for pins after which
pinning is not performed. This helps prevent connectivity issues in
apps which have not been updated. However, setting an expiration time
on pins may enable pinning bypass.
@@ -322,24 +322,24 @@ android:debuggable</a>
<h2 id="ConfigInheritance">Configuration Inheritance Behavior</h2>
<p>
Values not set in a specific config are inherited. This behavior allows more
complex configurations while keeping the configuration file readable.
Values not set in a specific configuration are inherited. This behavior allows
more complex configurations while keeping the configuration file readable.
</p>
<p>
If a value is not set in a specific entry then value from the next more
general entry is used. Values not set in a {@code domain-config} is
taken from the parent {@code domain-config}, if nested, or from the {@code
base-config} if not. Values not set in the {@code base-config} uses the
If a value is not set in a specific entry, then the value from the more
general entry is used. For example, values not set in a {@code domain-config}
are taken from the parent {@code domain-config}, if nested, or from the {@code
base-config} if not. Values not set in the {@code base-config} use the
platform default values.
</p>
<p>
For example consider, where all connections to subdomains of {@code
example.com} must use a custom set of CAs. Additonally cleartext traffic to
For example, consider where all connections to subdomains of {@code
example.com} must use a custom set of CAs. Additonally, cleartext traffic to
these domains is permitted <em>except</em> when connecting to {@code
secure.example.com}. By nesting the configuration for {@code
secure.example.com} inside the configuration for {@code example.com} the
secure.example.com} inside the configuration for {@code example.com}, the
{@code trust-anchors} does not need to be duplicated.
</p>
@@ -458,7 +458,8 @@ android:debuggable</a>
<p>
Any values that are not set use the platform default values. The default
configuration for apps targeting above API level 24 and above:
configuration for apps targeting Android 7.0 (API level 24) and higher is as
follows:
</p>
<pre>
@@ -468,7 +469,8 @@ android:debuggable</a>
&lt;/trust-anchors&gt;
&lt;/base-config&gt;
</pre>
The default configuration for apps targeting API level 23 and below is:
The default configuration for apps targeting Android 6.0 (API level 23) and
lower is as follows:
<pre>
&lt;base-config cleartextTrafficPermitted="true"&gt;
&lt;trust-anchors&gt;
@@ -499,13 +501,14 @@ The default configuration for apps targeting API level 23 and below is:
<br/>Any number of nested <code>&lt;domain-config&gt;</code></dd>
<dt>Description</dt>
<dd>Configuration used for connections to specific destinations as the defined by {@code domain} elements.
<dd>Configuration used for connections to specific destinations, as defined by
the {@code domain} elements.
<p>Note that if multiple {@code domain-config} elements cover a destination the config with the most specific (longest)
matching domain rule is used.</p></dd>
<p>Note that if multiple {@code domain-config} elements cover a destination, the
configuration with the most specific (longest) matching domain rule is
used.</p></dd>
</dl>
<h3 id="domain">&lt;domain&gt;</h3>
<dl class="xml">
@@ -530,8 +533,8 @@ matching domain rule is used.</p></dd>
</dt>
<dd>
If {@code "true"} then this domain rule matches the domain and all
subdomains, including subdomains of subdomains, otherwise the rule only
If {@code "true"}, then this domain rule matches the domain and all
subdomains, including subdomains of subdomains. Otherwise, the rule only
applies to exact matches.
</dd>
</dl>
@@ -572,13 +575,13 @@ matching domain rule is used.</p></dd>
<dd>
Overrides to be applied when <a href=
"{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>
is {@code "true"} which is normally the case for non-release builds
is {@code "true"}, which is normally the case for non-release builds
generated by IDEs and build tools. Trust anchors specified in {@code
debug-overrides} are added to all other configurations and certificate
debug-overrides} are added to all other configurations, and certificate
pinning is not performed when the server's certificate chain uses one of
these debug-only trust anchors. If <a href=
"{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>
is {@code "false"} then this section is completely ignored.
is {@code "false"}, then this section is completely ignored.
</dd>
</dl>
@@ -627,11 +630,11 @@ matching domain rule is used.</p></dd>
<dd><dl class="attr">
<dt>{@code src}</dt>
<dd>
The source of CA certificates, can be one of
The source of CA certificates. Each certificate can be one of the following:
<ul>
<li>a raw resource id pointing to a file containing X.509 certificates.
<li>a raw resource ID pointing to a file containing X.509 certificates.
Certificates must be encoded in DER or PEM format. In the case of PEM
certificates the file <em>must not</em> contain extra non-PEM data such as
certificates, the file <em>must not</em> contain extra non-PEM data such as
comments.
</li>
@@ -647,9 +650,9 @@ The source of CA certificates, can be one of
<dd>
<p>
Specifies if the CAs from this source bypass certificate pinning. If {@code
"true"} then certificate chains which chain through one of the CAs from this
source then pinning is not be performed. This can be useful for debug CAs
or to support letting the user MiTM your app's secure traffic.
"true"}, then pinning is not performed on certificate chains which are
signed by one of the CAs from this source. This can be useful for debugging
CAs or for testing man-in-the-middle attacks on your app's secure traffic.
</p>
<p>
@@ -705,13 +708,12 @@ The source of CA certificates, can be one of
</dt>
<dd>
The date, in {@code yyyy-MM-dd} format, at and after which the pins
expire, thus disabling pinning. If the attribute is not set then the
pins do not expire.
The date, in {@code yyyy-MM-dd} format, on which the pins expire, thus
disabling pinning. If the attribute is not set, then the pins do not
expire.
<p>
Expiration helps prevent connectivity issues in apps which do
not get updates to their pin set, for example because the user
disabled app updates.
Expiration helps prevent connectivity issues in apps which do not get
updates to their pin set, such as when the user disables app updates.
</p>
</dd>
</dl>
@@ -742,7 +744,7 @@ The source of CA certificates, can be one of
</dt>
<dd>
The digest algorithm used to generate the pin. Currently only
The digest algorithm used to generate the pin. Currently, only
{@code "SHA-256"} is supported.
</dd>
</dl>