WifiEnterpriseConfig


public class WifiEnterpriseConfig
extends Object implements Parcelable

java.lang.Object
   ↳ android.net.wifi.WifiEnterpriseConfig


Enterprise configuration details for Wi-Fi. Stores details about the EAP method and any associated credentials.

Summary

Nested classes

class WifiEnterpriseConfig.Eap

The Extensible Authentication Protocol method used 

class WifiEnterpriseConfig.Phase2

The inner authentication method used 

Constants

String EXTRA_WAPI_AS_CERTIFICATE_DATA

Intent extra: data for WAPI AS certificates

String EXTRA_WAPI_AS_CERTIFICATE_NAME

Intent extra: name for WAPI AS certificates

String EXTRA_WAPI_USER_CERTIFICATE_DATA

Intent extra: data for WAPI USER certificates

String EXTRA_WAPI_USER_CERTIFICATE_NAME

Intent extra: name for WAPI USER certificates

int TLS_V1_0

Constant definition for TLS v1.0 which is used in setMinimumTlsVersion(int)

int TLS_V1_1

Constant definition for TLS v1.1 which is used in setMinimumTlsVersion(int)

int TLS_V1_2

Constant definition for TLS v1.2 which is used in setMinimumTlsVersion(int)

int TLS_V1_3

Constant definition for TLS v1.3 which is used in setMinimumTlsVersion(int)

String WAPI_AS_CERTIFICATE

Key prefix for WAPI AS certificates.

String WAPI_USER_CERTIFICATE

Key prefix for WAPI user certificates.

Inherited constants

Fields

public static final Creator<WifiEnterpriseConfig> CREATOR

Public constructors

WifiEnterpriseConfig()
WifiEnterpriseConfig(WifiEnterpriseConfig source)

Copy constructor.

Public methods

int describeContents()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.

void enableTrustOnFirstUse(boolean enable)

Enable Trust On First Use.

String getAltSubjectMatch()

Get alternate subject match

String getAnonymousIdentity()

Get the anonymous identity

X509Certificate getCaCertificate()

Get CA certificate.

X509Certificate[] getCaCertificates()

Get CA certificates.

X509Certificate getClientCertificate()

Get client certificate

X509Certificate[] getClientCertificateChain()

Get the complete client certificate chain in the same order as it was last supplied.

String getClientKeyPairAlias()

Get KeyChain alias to use for client authentication.

PrivateKey getClientPrivateKey()

Get the client private key as supplied in setClientKeyEntryWithCertificateChain(PrivateKey, X509Certificate), or null if unset.

String getDecoratedIdentityPrefix()

Get the decorated identity prefix.

String getDomainSuffixMatch()

Get the domain_suffix_match value.

int getEapMethod()

Get the eap method.

String getIdentity()

Get the identity

int getMinimumTlsVersion()

Get the minimum TLS version for TLS-based EAP methods.

String getPassword()

Get the password.

int getPhase2Method()

Get the phase 2 authentication method.

String getPlmn()

Get plmn (Public Land Mobile Network) for Passpoint credential; see (java.lang.String) for more information

String getRealm()

Get realm for Passpoint credential; see setRealm(java.lang.String) for more information

String getSubjectMatch()

This method was deprecated in API level 23. in favor of altSubjectMatch

boolean hasCaCertificate()

Indicates whether or not this enterprise config has a CA certificate configured.

boolean isAuthenticationSimBased()

Utility method to determine whether the configuration's authentication method is SIM-based.

boolean isEapMethodServerCertUsed()

Determines whether an Enterprise configuration's EAP method requires a Root CA certification to validate the authentication server i.e.

boolean isServerCertValidationEnabled()

Determines whether an Enterprise configuration enables server certificate validation.

boolean isTrustOnFirstUseEnabled()

Indicates whether or not Trust On First Use (TOFU) is enabled.

void setAltSubjectMatch(String altSubjectMatch)

Set alternate subject match.

void setAnonymousIdentity(String anonymousIdentity)

Set anonymous identity.

void setCaCertificate(X509Certificate cert)

Specify a X.509 certificate that identifies the server.

void setCaCertificates(X509Certificate[] certs)

Specify a list of X.509 certificates that identifies the server.

void setClientKeyEntry(PrivateKey privateKey, X509Certificate clientCertificate)

Specify a private key and client certificate for client authorization.

void setClientKeyEntryWithCertificateChain(PrivateKey privateKey, X509Certificate[] clientCertificateChain)

Specify a private key and client certificate chain for client authorization.

void setClientKeyPairAlias(String alias)

Specify a key pair via KeyChain alias for client authentication.

void setDecoratedIdentityPrefix(String decoratedIdentityPrefix)

Set a prefix for a decorated identity as per RFC 7542.

void setDomainSuffixMatch(String domain)

Set the domain_suffix_match directive on wpa_supplicant.

void setEapMethod(int eapMethod)

Set the EAP authentication method.

void setIdentity(String identity)

Set the identity

void setMinimumTlsVersion(int tlsVersion)

Set the minimum TLS version for TLS-based EAP methods.

void setPassword(String password)

Set the password.

void setPhase2Method(int phase2Method)

Set Phase 2 authentication method.

void setPlmn(String plmn)

Set plmn (Public Land Mobile Network) of the provider of Passpoint credential

void setRealm(String realm)

Set realm for Passpoint credential; realm identifies a set of networks where your Passpoint credential can be used

void setSubjectMatch(String subjectMatch)

This method was deprecated in API level 23. in favor of altSubjectMatch

String toString()

Returns a string representation of the object.

void writeToParcel(Parcel dest, int flags)

Flatten this object in to a Parcel.

Inherited methods

Constants

EXTRA_WAPI_AS_CERTIFICATE_DATA

Added in API level 30
public static final String EXTRA_WAPI_AS_CERTIFICATE_DATA

Intent extra: data for WAPI AS certificates

Constant Value: "android.net.wifi.extra.WAPI_AS_CERTIFICATE_DATA"

EXTRA_WAPI_AS_CERTIFICATE_NAME

Added in API level 30
public static final String EXTRA_WAPI_AS_CERTIFICATE_NAME

Intent extra: name for WAPI AS certificates

Constant Value: "android.net.wifi.extra.WAPI_AS_CERTIFICATE_NAME"

EXTRA_WAPI_USER_CERTIFICATE_DATA

Added in API level 30
public static final String EXTRA_WAPI_USER_CERTIFICATE_DATA

Intent extra: data for WAPI USER certificates

Constant Value: "android.net.wifi.extra.WAPI_USER_CERTIFICATE_DATA"

EXTRA_WAPI_USER_CERTIFICATE_NAME

Added in API level 30
public static final String EXTRA_WAPI_USER_CERTIFICATE_NAME

Intent extra: name for WAPI USER certificates

Constant Value: "android.net.wifi.extra.WAPI_USER_CERTIFICATE_NAME"

TLS_V1_0

Added in API level 34
public static final int TLS_V1_0

Constant definition for TLS v1.0 which is used in setMinimumTlsVersion(int)

Constant Value: 0 (0x00000000)

TLS_V1_1

Added in API level 34
public static final int TLS_V1_1

Constant definition for TLS v1.1 which is used in setMinimumTlsVersion(int)

Constant Value: 1 (0x00000001)

TLS_V1_2

Added in API level 34
public static final int TLS_V1_2

Constant definition for TLS v1.2 which is used in setMinimumTlsVersion(int)

Constant Value: 2 (0x00000002)

TLS_V1_3

Added in API level 34
public static final int TLS_V1_3

Constant definition for TLS v1.3 which is used in setMinimumTlsVersion(int)

Constant Value: 3 (0x00000003)

WAPI_AS_CERTIFICATE

Added in API level 30
public static final String WAPI_AS_CERTIFICATE

Key prefix for WAPI AS certificates.

Constant Value: "WAPIAS_"

WAPI_USER_CERTIFICATE

Added in API level 30
public static final String WAPI_USER_CERTIFICATE

Key prefix for WAPI user certificates.

Constant Value: "WAPIUSR_"

Fields

CREATOR

Added in API level 18
public static final Creator<WifiEnterpriseConfig> CREATOR

Public constructors

WifiEnterpriseConfig

Added in API level 18
public WifiEnterpriseConfig ()

WifiEnterpriseConfig

Added in API level 18
public WifiEnterpriseConfig (WifiEnterpriseConfig source)

Copy constructor. This copies over all the fields verbatim (does not ignore masked password fields).

Parameters
source WifiEnterpriseConfig: Source WifiEnterpriseConfig object.

Public methods

describeContents

Added in API level 18
public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

enableTrustOnFirstUse

Added in API level 33
public void enableTrustOnFirstUse (boolean enable)

Enable Trust On First Use. Trust On First Use (TOFU) simplifies manual or partial configurations of TLS-based EAP networks. TOFU operates by installing the Root CA cert which is received from the server during an initial connection to a new network. Such installation is gated by user approval. Use only when it is not possible to configure the Root CA cert for the server.
Note: If a Root CA cert is already configured, this option is ignored, e.g. if setCaCertificate(java.security.cert.X509Certificate), or setCaCertificates(java.security.cert.X509Certificate[]) is called.

Parameters
enable boolean: true to enable; false otherwise (the default if the method is not called).

getAltSubjectMatch

Added in API level 23
public String getAltSubjectMatch ()

Get alternate subject match

Returns
String the alternate subject match string

getAnonymousIdentity

Added in API level 18
public String getAnonymousIdentity ()

Get the anonymous identity

Returns
String anonymous identity

getCaCertificate

Added in API level 18
public X509Certificate getCaCertificate ()

Get CA certificate. If multiple CA certificates are configured previously, return the first one.

Returns
X509Certificate X.509 CA certificate This value may be null.

getCaCertificates

Added in API level 24
public X509Certificate[] getCaCertificates ()

Get CA certificates.

Returns
X509Certificate[] This value may be null.

getClientCertificate

Added in API level 18
public X509Certificate getClientCertificate ()

Get client certificate

Returns
X509Certificate X.509 client certificate

getClientCertificateChain

Added in API level 26
public X509Certificate[] getClientCertificateChain ()

Get the complete client certificate chain in the same order as it was last supplied.

If the chain was last supplied by a call to setClientKeyEntry(java.security.PrivateKey, java.security.cert.X509Certificate) with a non-null * certificate instance, a single-element array containing the certificate will be * returned. If setClientKeyEntryWithCertificateChain(java.security.PrivateKey, java.security.cert.X509Certificate[]) was last called with a non-empty array, this array will be returned in the same order as it was supplied. Otherwise, null will be returned.

Returns
X509Certificate[] X.509 client certificates

getClientKeyPairAlias

Added in API level 31
public String getClientKeyPairAlias ()

Get KeyChain alias to use for client authentication.

Returns
String This value may be null.

getClientPrivateKey

Added in API level 30
public PrivateKey getClientPrivateKey ()

Get the client private key as supplied in setClientKeyEntryWithCertificateChain(PrivateKey, X509Certificate), or null if unset.

Returns
PrivateKey

getDecoratedIdentityPrefix

Added in API level 31
public String getDecoratedIdentityPrefix ()

Get the decorated identity prefix.

Returns
String The decorated identity prefix This value may be null.

getDomainSuffixMatch

Added in API level 23
public String getDomainSuffixMatch ()

Get the domain_suffix_match value. See setDomSuffixMatch.

Returns
String The domain value.

getEapMethod

Added in API level 18
public int getEapMethod ()

Get the eap method.

Returns
int eap method configured

getIdentity

Added in API level 18
public String getIdentity ()

Get the identity

Returns
String the identity

getMinimumTlsVersion

Added in API level 34
public int getMinimumTlsVersion ()

Get the minimum TLS version for TLS-based EAP methods.

Returns
int the TLS version Value is TLS_V1_0, TLS_V1_1, TLS_V1_2, or TLS_V1_3

getPassword

Added in API level 18
public String getPassword ()

Get the password. Returns locally set password value. For networks fetched from framework, returns "*".

Returns
String

getPhase2Method

Added in API level 18
public int getPhase2Method ()

Get the phase 2 authentication method.

Returns
int a phase 2 method defined at Phase2

getPlmn

Added in API level 23
public String getPlmn ()

Get plmn (Public Land Mobile Network) for Passpoint credential; see (java.lang.String) for more information

Returns
String the plmn

getRealm

Added in API level 23
public String getRealm ()

Get realm for Passpoint credential; see setRealm(java.lang.String) for more information

Returns
String the realm

getSubjectMatch

Added in API level 18
Deprecated in API level 23
public String getSubjectMatch ()

This method was deprecated in API level 23.
in favor of altSubjectMatch

Get subject match (deprecated)

Returns
String the subject match string

hasCaCertificate

Added in API level 33
public boolean hasCaCertificate ()

Indicates whether or not this enterprise config has a CA certificate configured.

Returns
boolean

isAuthenticationSimBased

Added in API level 30
public boolean isAuthenticationSimBased ()

Utility method to determine whether the configuration's authentication method is SIM-based.

Returns
boolean true if the credential information requires SIM card for current authentication method, otherwise it returns false.

isEapMethodServerCertUsed

Added in API level 31
public boolean isEapMethodServerCertUsed ()

Determines whether an Enterprise configuration's EAP method requires a Root CA certification to validate the authentication server i.e. PEAP, TLS, UNAUTH_TLS, or TTLS.

Returns
boolean True if configuration requires a CA certification, false otherwise.

isServerCertValidationEnabled

Added in API level 31
public boolean isServerCertValidationEnabled ()

Determines whether an Enterprise configuration enables server certificate validation.

The caller can determine, along with isEapMethodServerCertUsed(), if an Enterprise configuration enables server certificate validation, which is a mandatory requirement for networks that use TLS based EAP methods. A configuration that does not enable server certificate validation will be ignored and will not be considered for network selection. A network suggestion with such a configuration will cause an IllegalArgumentException to be thrown when suggested. Server validation is achieved by the following: - Either certificate or CA path is configured. - Either alternative subject match or domain suffix match is set.

Returns
boolean True for server certificate validation is enabled, false otherwise.

Throws
IllegalStateException on configuration which doesn't use server certificate.

isTrustOnFirstUseEnabled

Added in API level 33
public boolean isTrustOnFirstUseEnabled ()

Indicates whether or not Trust On First Use (TOFU) is enabled.

Returns
boolean Trust On First Use is enabled or not.

setAltSubjectMatch

Added in API level 23
public void setAltSubjectMatch (String altSubjectMatch)

Set alternate subject match. This is the substring to be matched against the alternate subject of the authentication server certificate. Note: If no alternate subject is set for an Enterprise configuration, either by not calling this API, or by calling it with null, or not setting domain suffix match using the setDomainSuffixMatch(java.lang.String), then the server certificate validation is incomplete - which means that the connection is not secure.

Parameters
altSubjectMatch String: substring to be matched, for example DNS:server.example.com;EMAIL:server@example.com

setAnonymousIdentity

Added in API level 18
public void setAnonymousIdentity (String anonymousIdentity)

Set anonymous identity. This is used as the unencrypted identity with certain EAP types

Parameters
anonymousIdentity String: the anonymous identity

setCaCertificate

Added in API level 18
public void setCaCertificate (X509Certificate cert)

Specify a X.509 certificate that identifies the server.

A default name is automatically assigned to the certificate and used with this configuration. The framework takes care of installing the certificate when the config is saved and removing the certificate when the config is removed. Note: If no certificate is set for an Enterprise configuration, either by not calling this API (or the setCaCertificates(java.security.cert.X509Certificate[]), or by calling it with null, then the server certificate validation is skipped - which means that the connection is not secure.

Parameters
cert X509Certificate: X.509 CA certificate This value may be null.

Throws
IllegalArgumentException if not a CA certificate

setCaCertificates

Added in API level 24
public void setCaCertificates (X509Certificate[] certs)

Specify a list of X.509 certificates that identifies the server. The validation passes if the CA of server certificate matches one of the given certificates.

Default names are automatically assigned to the certificates and used with this configuration. The framework takes care of installing the certificates when the config is saved and removing the certificates when the config is removed. Note: If no certificates are set for an Enterprise configuration, either by not calling this API (or the setCaCertificate(java.security.cert.X509Certificate), or by calling it with null, then the server certificate validation is skipped - which means that the connection is not secure.

Parameters
certs X509Certificate: X.509 CA certificates This value may be null.

Throws
IllegalArgumentException if any of the provided certificates is not a CA certificate, or if too many CA certificates are provided

setClientKeyEntry

Added in API level 18
public void setClientKeyEntry (PrivateKey privateKey, 
                X509Certificate clientCertificate)

Specify a private key and client certificate for client authorization.

A default name is automatically assigned to the key entry and used with this configuration. The framework takes care of installing the key entry when the config is saved and removing the key entry when the config is removed.

Parameters
privateKey PrivateKey: a PrivateKey instance for the end certificate.

clientCertificate X509Certificate: an X509Certificate representing the end certificate.

Throws
IllegalArgumentException for an invalid key or certificate.

setClientKeyEntryWithCertificateChain

Added in API level 26
public void setClientKeyEntryWithCertificateChain (PrivateKey privateKey, 
                X509Certificate[] clientCertificateChain)

Specify a private key and client certificate chain for client authorization.

A default name is automatically assigned to the key entry and used with this configuration. The framework takes care of installing the key entry when the config is saved and removing the key entry when the config is removed.

Parameters
privateKey PrivateKey: a PrivateKey instance for the end certificate.

clientCertificateChain X509Certificate: an array of X509Certificate instances which starts with end certificate and continues with additional CA certificates necessary to link the end certificate with some root certificate known by the authenticator.

Throws
IllegalArgumentException for an invalid key or certificate.

setClientKeyPairAlias

Added in API level 31
public void setClientKeyPairAlias (String alias)

Specify a key pair via KeyChain alias for client authentication. The alias should refer to a key pair in KeyChain that is allowed for WiFi authentication.

Parameters
alias String: key pair alias This value cannot be null.

setDecoratedIdentityPrefix

Added in API level 31
public void setDecoratedIdentityPrefix (String decoratedIdentityPrefix)

Set a prefix for a decorated identity as per RFC 7542. This prefix must contain a list of realms (could be a list of 1) delimited by a '!' character. e.g. homerealm.example.org! or proxyrealm.example.net!homerealm.example.org! A prefix of "homerealm.example.org!" will generate a decorated identity that looks like: homerealm.example.org!user@otherrealm.example.net Calling with a null parameter will clear the decorated prefix. Note: Caller must verify that the device supports this feature by calling WifiManager#isDecoratedIdentitySupported()

Parameters
decoratedIdentityPrefix String: The prefix to add to the outer/anonymous identity This value may be null.

setDomainSuffixMatch

Added in API level 23
public void setDomainSuffixMatch (String domain)

Set the domain_suffix_match directive on wpa_supplicant. This is the parameter to use for Hotspot 2.0 defined matching of AAA server certs per WFA HS2.0 spec, section 7.3.3.2, second paragraph.

From wpa_supplicant documentation:

Constraint for server domain name. If set, this FQDN is used as a suffix match requirement for the AAAserver certificate in SubjectAltName dNSName element(s). If a matching dNSName is found, this constraint is met.

Suffix match here means that the host/domain name is compared one label at a time starting from the top-level domain and all the labels in domain_suffix_match shall be included in the certificate. The certificate may include additional sub-level labels in addition to the required labels.

More than one match string can be provided by using semicolons to separate the strings (e.g., example.org;example.com). When multiple strings are specified, a match with any one of the values is considered a sufficient match for the certificate, i.e., the conditions are ORed ogether.

For example, domain_suffix_match=example.com would match test.example.com but would not match test-example.com. Note: If no domain suffix is set for an Enterprise configuration, either by not calling this API, or by calling it with null, or not setting alternate subject match using the setAltSubjectMatch(java.lang.String), then the server certificate validation is incomplete - which means that the connection is not secure.

Parameters
domain String: The domain value

setEapMethod

Added in API level 18
public void setEapMethod (int eapMethod)

Set the EAP authentication method.

Parameters
eapMethod int: is one of Eap, except for Eap#NONE

Throws
IllegalArgumentException on an invalid eap method

setIdentity

Added in API level 18
public void setIdentity (String identity)

Set the identity

setMinimumTlsVersion

Added in API level 34
public void setMinimumTlsVersion (int tlsVersion)

Set the minimum TLS version for TLS-based EAP methods. WifiManager#isTlsMinimumVersionSupported() indicates whether or not a minimum TLS version can be set. If not supported, the minimum TLS version is always TLS v1.0.

WifiManager#isTlsV13Supported() indicates whether or not TLS v1.3 is supported. If requested minimum is not supported, it will default to the maximum supported version.

Parameters
tlsVersion int: the TLS version Value is TLS_V1_0, TLS_V1_1, TLS_V1_2, or TLS_V1_3

Throws
IllegalArgumentException if the TLS version is invalid.

setPassword

Added in API level 18
public void setPassword (String password)

Set the password.

Parameters
password String: the password

setPhase2Method

Added in API level 18
public void setPhase2Method (int phase2Method)

Set Phase 2 authentication method. Sets the inner authentication method to be used in phase 2 after setting up a secure channel

Parameters
phase2Method int: is the inner authentication method and can be one of Phase2

Throws
IllegalArgumentException on an invalid phase2 method

setPlmn

Added in API level 23
public void setPlmn (String plmn)

Set plmn (Public Land Mobile Network) of the provider of Passpoint credential

Parameters
plmn String: the plmn value derived from mcc (mobile country code) & mnc (mobile network code)

setRealm

Added in API level 23
public void setRealm (String realm)

Set realm for Passpoint credential; realm identifies a set of networks where your Passpoint credential can be used

Parameters
realm String: the realm

setSubjectMatch

Added in API level 18
Deprecated in API level 23
public void setSubjectMatch (String subjectMatch)

This method was deprecated in API level 23.
in favor of altSubjectMatch

Set subject match (deprecated). This is the substring to be matched against the subject of the authentication server certificate.

Parameters
subjectMatch String: substring to be matched

toString

Added in API level 18
public String toString ()

Returns a string representation of the object.

Returns
String a string representation of the object.

writeToParcel

Added in API level 18
public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest Parcel: The Parcel in which the object should be written. This value cannot be null.

flags int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES