path: root/common/moduleutils/src/android/net/shared/ProvisioningConfiguration.java

/*
 * Copyright (C) 2019 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.net.shared;

import static android.net.shared.ParcelableUtil.fromParcelableArray;
import static android.net.shared.ParcelableUtil.toParcelableArray;

import android.annotation.NonNull;
import android.annotation.Nullable;
import android.net.INetd;
import android.net.InformationElementParcelable;
import android.net.Network;
import android.net.ProvisioningConfigurationParcelable;
import android.net.ScanResultInfoParcelable;
import android.net.StaticIpConfiguration;
import android.net.apf.ApfCapabilities;
import android.net.ip.IIpClient;
import android.util.Log;

import java.nio.BufferUnderflowException;
import java.nio.ByteBuffer;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
import java.util.StringJoiner;

/**
 * This class encapsulates parameters to be passed to
 * IpClient#startProvisioning(). A defensive copy is made by IpClient
 * and the values specified herein are in force until IpClient#stop()
 * is called.
 *
 * Example use:
 *
 *     final ProvisioningConfiguration config =
 *             new ProvisioningConfiguration.Builder()
 *                     .withPreDhcpAction()
 *                     .withProvisioningTimeoutMs(36 * 1000)
 *                     .build();
 *     mIpClient.startProvisioning(config.toStableParcelable());
 *     ...
 *     mIpClient.stop();
 *
 * The specified provisioning configuration will only be active until
 * IIpClient#stop() is called. Future calls to IIpClient#startProvisioning()
 * must specify the configuration again.
 * @hide
 */
public class ProvisioningConfiguration {
    private static final String TAG = "ProvisioningConfiguration";

    // TODO: Delete this default timeout once those callers that care are
    // fixed to pass in their preferred timeout.
    //
    // We pick 18 seconds so we can send DHCP requests at
    //
    //     t=0, t=1, t=3, t=7, t=16
    //
    // allowing for 10% jitter.
    private static final int DEFAULT_TIMEOUT_MS = 18 * 1000;

    /**
     * Builder to create a {@link ProvisioningConfiguration}.
     */
    public static class Builder {
        protected ProvisioningConfiguration mConfig = new ProvisioningConfiguration();

        /**
         * Specify that the configuration should not enable IPv4. It is enabled by default.
         */
        public Builder withoutIPv4() {
            mConfig.mEnableIPv4 = false;
            return this;
        }

        /**
         * Specify that the configuration should not enable IPv6. It is enabled by default.
         */
        public Builder withoutIPv6() {
            mConfig.mEnableIPv6 = false;
            return this;
        }

        /**
         * Specify that the configuration should not use a MultinetworkPolicyTracker. It is used
         * by default.
         */
        public Builder withoutMultinetworkPolicyTracker() {
            mConfig.mUsingMultinetworkPolicyTracker = false;
            return this;
        }

        /**
         * Specify that the configuration should not use a IpReachabilityMonitor. It is used by
         * default.
         */
        public Builder withoutIpReachabilityMonitor() {
            mConfig.mUsingIpReachabilityMonitor = false;
            return this;
        }

        /**
         * Identical to {@link #withPreDhcpAction(int)}, using a default timeout.
         * @see #withPreDhcpAction(int)
         */
        public Builder withPreDhcpAction() {
            mConfig.mRequestedPreDhcpActionMs = DEFAULT_TIMEOUT_MS;
            return this;
        }

        /**
         * Specify that {@link IpClientCallbacks#onPreDhcpAction()} should be called. Clients must
         * call {@link IIpClient#completedPreDhcpAction()} when the callback called. This behavior
         * is disabled by default.
         * @param dhcpActionTimeoutMs Timeout for clients to call completedPreDhcpAction().
         */
        public Builder withPreDhcpAction(int dhcpActionTimeoutMs) {
            mConfig.mRequestedPreDhcpActionMs = dhcpActionTimeoutMs;
            return this;
        }

        /**
         * Specify that preconnection feature would be enabled. It's not used by default.
         */
        public Builder withPreconnection() {
            mConfig.mEnablePreconnection = true;
            return this;
        }

        /**
         * Specify the initial provisioning configuration.
         */
        public Builder withInitialConfiguration(InitialConfiguration initialConfig) {
            mConfig.mInitialConfig = initialConfig;
            return this;
        }

        /**
         * Specify a static configuration for provisioning.
         */
        public Builder withStaticConfiguration(StaticIpConfiguration staticConfig) {
            mConfig.mStaticIpConfig = staticConfig;
            return this;
        }

        /**
         * Specify ApfCapabilities.
         */
        public Builder withApfCapabilities(ApfCapabilities apfCapabilities) {
            mConfig.mApfCapabilities = apfCapabilities;
            return this;
        }

        /**
         * Specify the timeout to use for provisioning.
         */
        public Builder withProvisioningTimeoutMs(int timeoutMs) {
            mConfig.mProvisioningTimeoutMs = timeoutMs;
            return this;
        }

        /**
         * Specify that IPv6 address generation should use a random MAC address.
         */
        public Builder withRandomMacAddress() {
            mConfig.mIPv6AddrGenMode = INetd.IPV6_ADDR_GEN_MODE_EUI64;
            return this;
        }

        /**
         * Specify that IPv6 address generation should use a stable MAC address.
         */
        public Builder withStableMacAddress() {
            mConfig.mIPv6AddrGenMode = INetd.IPV6_ADDR_GEN_MODE_STABLE_PRIVACY;
            return this;
        }

        /**
         * Specify the network to use for provisioning.
         */
        public Builder withNetwork(Network network) {
            mConfig.mNetwork = network;
            return this;
        }

        /**
         * Specify the display name that the IpClient should use.
         */
        public Builder withDisplayName(String displayName) {
            mConfig.mDisplayName = displayName;
            return this;
        }

        /**
         * Specify the information elements included in wifi scan result that was obtained
         * prior to connecting to the access point, if this is a WiFi network.
         *
         * <p>The scan result can be used to infer whether the network is metered.
         */
        public Builder withScanResultInfo(ScanResultInfo scanResultInfo) {
            mConfig.mScanResultInfo = scanResultInfo;
            return this;
        }

        /**
         * Specify the L2 information(bssid, l2key and cluster) that the IpClient should use.
         */
        public Builder withLayer2Information(Layer2Information layer2Info) {
            mConfig.mLayer2Info = layer2Info;
            return this;
        }

        /**
         * Build the configuration using previously specified parameters.
         */
        public ProvisioningConfiguration build() {
            return new ProvisioningConfiguration(mConfig);
        }
    }

    /**
     * Class wrapper of {@link android.net.wifi.ScanResult} to encapsulate the SSID and
     * InformationElements fields of ScanResult.
     */
    public static class ScanResultInfo {
        @NonNull
        private final String mSsid;
        @NonNull
        private final String mBssid;
        @NonNull
        private final List<InformationElement> mInformationElements;

       /**
        * Class wrapper of {@link android.net.wifi.ScanResult.InformationElement} to encapsulate
        * the specific IE id and payload fields.
        */
        public static class InformationElement {
            private final int mId;
            @NonNull
            private final byte[] mPayload;

            public InformationElement(int id, @NonNull ByteBuffer payload) {
                mId = id;
                mPayload = convertToByteArray(payload.asReadOnlyBuffer());
            }

           /**
            * Get the element ID of the information element.
            */
            public int getId() {
                return mId;
            }

           /**
            * Get the specific content of the information element.
            */
            @NonNull
            public ByteBuffer getPayload() {
                return ByteBuffer.wrap(mPayload).asReadOnlyBuffer();
            }

            @Override
            public boolean equals(Object o) {
                if (o == this) return true;
                if (!(o instanceof InformationElement)) return false;
                InformationElement other = (InformationElement) o;
                return mId == other.mId && Arrays.equals(mPayload, other.mPayload);
            }

            @Override
            public int hashCode() {
                return Objects.hash(mId, mPayload);
            }

            @Override
            public String toString() {
                return "ID: " + mId + ", " + Arrays.toString(mPayload);
            }

            /**
             * Convert this InformationElement to a {@link InformationElementParcelable}.
             */
            public InformationElementParcelable toStableParcelable() {
                final InformationElementParcelable p = new InformationElementParcelable();
                p.id = mId;
                p.payload = mPayload != null ? mPayload.clone() : null;
                return p;
            }

            /**
             * Create an instance of {@link InformationElement} based on the contents of the
             * specified {@link InformationElementParcelable}.
             */
            @Nullable
            public static InformationElement fromStableParcelable(InformationElementParcelable p) {
                if (p == null) return null;
                return new InformationElement(p.id,
                        ByteBuffer.wrap(p.payload.clone()).asReadOnlyBuffer());
            }
        }

        public ScanResultInfo(@NonNull String ssid, @NonNull String bssid,
                @NonNull List<InformationElement> informationElements) {
            Objects.requireNonNull(ssid, "ssid must not be null.");
            Objects.requireNonNull(bssid, "bssid must not be null.");
            mSsid = ssid;
            mBssid = bssid;
            mInformationElements =
                    Collections.unmodifiableList(new ArrayList<>(informationElements));
        }

        /**
         * Get the scanned network name.
         */
        @NonNull
        public String getSsid() {
            return mSsid;
        }

        /**
         * Get the address of the access point.
         */
        @NonNull
        public String getBssid() {
            return mBssid;
        }

        /**
         * Get all information elements found in the beacon.
         */
        @NonNull
        public List<InformationElement> getInformationElements() {
            return mInformationElements;
        }

        @Override
        public String toString() {
            StringBuffer str = new StringBuffer();
            str.append("SSID: ").append(mSsid);
            str.append(", BSSID: ").append(mBssid);
            str.append(", Information Elements: {");
            for (InformationElement ie : mInformationElements) {
                str.append("[").append(ie.toString()).append("]");
            }
            str.append("}");
            return str.toString();
        }

        @Override
        public boolean equals(Object o) {
            if (o == this) return true;
            if (!(o instanceof ScanResultInfo)) return false;
            ScanResultInfo other = (ScanResultInfo) o;
            return Objects.equals(mSsid, other.mSsid)
                    && Objects.equals(mBssid, other.mBssid)
                    && mInformationElements.equals(other.mInformationElements);
        }

        @Override
        public int hashCode() {
            return Objects.hash(mSsid, mBssid, mInformationElements);
        }

        /**
         * Convert this ScanResultInfo to a {@link ScanResultInfoParcelable}.
         */
        public ScanResultInfoParcelable toStableParcelable() {
            final ScanResultInfoParcelable p = new ScanResultInfoParcelable();
            p.ssid = mSsid;
            p.bssid = mBssid;
            p.informationElements = toParcelableArray(mInformationElements,
                    InformationElement::toStableParcelable, InformationElementParcelable.class);
            return p;
        }

        /**
         * Create an instance of {@link ScanResultInfo} based on the contents of the specified
         * {@link ScanResultInfoParcelable}.
         */
        public static ScanResultInfo fromStableParcelable(ScanResultInfoParcelable p) {
            if (p == null) return null;
            final List<InformationElement> ies = new ArrayList<InformationElement>();
            ies.addAll(fromParcelableArray(p.informationElements,
                    InformationElement::fromStableParcelable));
            return new ScanResultInfo(p.ssid, p.bssid, ies);
        }

        private static byte[] convertToByteArray(@NonNull final ByteBuffer buffer) {
            final byte[] bytes = new byte[buffer.limit()];
            final ByteBuffer copy = buffer.asReadOnlyBuffer();
            try {
                copy.position(0);
                copy.get(bytes);
            } catch (BufferUnderflowException e) {
                Log.wtf(TAG, "Buffer under flow exception should never happen.");
            } finally {
                return bytes;
            }
        }
    }

    public boolean mEnableIPv4 = true;
    public boolean mEnableIPv6 = true;
    public boolean mEnablePreconnection = false;
    public boolean mUsingMultinetworkPolicyTracker = true;
    public boolean mUsingIpReachabilityMonitor = true;
    public int mRequestedPreDhcpActionMs;
    public InitialConfiguration mInitialConfig;
    public StaticIpConfiguration mStaticIpConfig;
    public ApfCapabilities mApfCapabilities;
    public int mProvisioningTimeoutMs = DEFAULT_TIMEOUT_MS;
    public int mIPv6AddrGenMode = INetd.IPV6_ADDR_GEN_MODE_STABLE_PRIVACY;
    public Network mNetwork = null;
    public String mDisplayName = null;
    public ScanResultInfo mScanResultInfo;
    public Layer2Information mLayer2Info;

    public ProvisioningConfiguration() {} // used by Builder

    public ProvisioningConfiguration(ProvisioningConfiguration other) {
        mEnableIPv4 = other.mEnableIPv4;
        mEnableIPv6 = other.mEnableIPv6;
        mEnablePreconnection = other.mEnablePreconnection;
        mUsingMultinetworkPolicyTracker = other.mUsingMultinetworkPolicyTracker;
        mUsingIpReachabilityMonitor = other.mUsingIpReachabilityMonitor;
        mRequestedPreDhcpActionMs = other.mRequestedPreDhcpActionMs;
        mInitialConfig = InitialConfiguration.copy(other.mInitialConfig);
        mStaticIpConfig = other.mStaticIpConfig == null
                ? null
                : new StaticIpConfiguration(other.mStaticIpConfig);
        mApfCapabilities = other.mApfCapabilities;
        mProvisioningTimeoutMs = other.mProvisioningTimeoutMs;
        mIPv6AddrGenMode = other.mIPv6AddrGenMode;
        mNetwork = other.mNetwork;
        mDisplayName = other.mDisplayName;
        mScanResultInfo = other.mScanResultInfo;
        mLayer2Info = other.mLayer2Info;
    }

    /**
     * Create a ProvisioningConfigurationParcelable from this ProvisioningConfiguration.
     */
    public ProvisioningConfigurationParcelable toStableParcelable() {
        final ProvisioningConfigurationParcelable p = new ProvisioningConfigurationParcelable();
        p.enableIPv4 = mEnableIPv4;
        p.enableIPv6 = mEnableIPv6;
        p.enablePreconnection = mEnablePreconnection;
        p.usingMultinetworkPolicyTracker = mUsingMultinetworkPolicyTracker;
        p.usingIpReachabilityMonitor = mUsingIpReachabilityMonitor;
        p.requestedPreDhcpActionMs = mRequestedPreDhcpActionMs;
        p.initialConfig = mInitialConfig == null ? null : mInitialConfig.toStableParcelable();
        p.staticIpConfig = mStaticIpConfig == null
                ? null
                : new StaticIpConfiguration(mStaticIpConfig);
        p.apfCapabilities = mApfCapabilities; // ApfCapabilities is immutable
        p.provisioningTimeoutMs = mProvisioningTimeoutMs;
        p.ipv6AddrGenMode = mIPv6AddrGenMode;
        p.network = mNetwork;
        p.displayName = mDisplayName;
        p.scanResultInfo = mScanResultInfo == null ? null : mScanResultInfo.toStableParcelable();
        p.layer2Info = mLayer2Info == null ? null : mLayer2Info.toStableParcelable();
        return p;
    }

    /**
     * Create a ProvisioningConfiguration from a ProvisioningConfigurationParcelable.
     */
    public static ProvisioningConfiguration fromStableParcelable(
            @Nullable ProvisioningConfigurationParcelable p) {
        if (p == null) return null;
        final ProvisioningConfiguration config = new ProvisioningConfiguration();
        config.mEnableIPv4 = p.enableIPv4;
        config.mEnableIPv6 = p.enableIPv6;
        config.mEnablePreconnection = p.enablePreconnection;
        config.mUsingMultinetworkPolicyTracker = p.usingMultinetworkPolicyTracker;
        config.mUsingIpReachabilityMonitor = p.usingIpReachabilityMonitor;
        config.mRequestedPreDhcpActionMs = p.requestedPreDhcpActionMs;
        config.mInitialConfig = InitialConfiguration.fromStableParcelable(p.initialConfig);
        config.mStaticIpConfig = p.staticIpConfig == null
                ? null
                : new StaticIpConfiguration(p.staticIpConfig);
        config.mApfCapabilities = p.apfCapabilities; // ApfCapabilities is immutable
        config.mProvisioningTimeoutMs = p.provisioningTimeoutMs;
        config.mIPv6AddrGenMode = p.ipv6AddrGenMode;
        config.mNetwork = p.network;
        config.mDisplayName = p.displayName;
        config.mScanResultInfo = ScanResultInfo.fromStableParcelable(p.scanResultInfo);
        config.mLayer2Info = Layer2Information.fromStableParcelable(p.layer2Info);
        return config;
    }

    @Override
    public String toString() {
        return new StringJoiner(", ", getClass().getSimpleName() + "{", "}")
                .add("mEnableIPv4: " + mEnableIPv4)
                .add("mEnableIPv6: " + mEnableIPv6)
                .add("mEnablePreconnection: " + mEnablePreconnection)
                .add("mUsingMultinetworkPolicyTracker: " + mUsingMultinetworkPolicyTracker)
                .add("mUsingIpReachabilityMonitor: " + mUsingIpReachabilityMonitor)
                .add("mRequestedPreDhcpActionMs: " + mRequestedPreDhcpActionMs)
                .add("mInitialConfig: " + mInitialConfig)
                .add("mStaticIpConfig: " + mStaticIpConfig)
                .add("mApfCapabilities: " + mApfCapabilities)
                .add("mProvisioningTimeoutMs: " + mProvisioningTimeoutMs)
                .add("mIPv6AddrGenMode: " + mIPv6AddrGenMode)
                .add("mNetwork: " + mNetwork)
                .add("mDisplayName: " + mDisplayName)
                .add("mScanResultInfo: " + mScanResultInfo)
                .add("mLayer2Info: " + mLayer2Info)
                .toString();
    }

    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof ProvisioningConfiguration)) return false;
        final ProvisioningConfiguration other = (ProvisioningConfiguration) obj;
        return mEnableIPv4 == other.mEnableIPv4
                && mEnableIPv6 == other.mEnableIPv6
                && mEnablePreconnection == other.mEnablePreconnection
                && mUsingMultinetworkPolicyTracker == other.mUsingMultinetworkPolicyTracker
                && mUsingIpReachabilityMonitor == other.mUsingIpReachabilityMonitor
                && mRequestedPreDhcpActionMs == other.mRequestedPreDhcpActionMs
                && Objects.equals(mInitialConfig, other.mInitialConfig)
                && Objects.equals(mStaticIpConfig, other.mStaticIpConfig)
                && Objects.equals(mApfCapabilities, other.mApfCapabilities)
                && mProvisioningTimeoutMs == other.mProvisioningTimeoutMs
                && mIPv6AddrGenMode == other.mIPv6AddrGenMode
                && Objects.equals(mNetwork, other.mNetwork)
                && Objects.equals(mDisplayName, other.mDisplayName)
                && Objects.equals(mScanResultInfo, other.mScanResultInfo)
                && Objects.equals(mLayer2Info, other.mLayer2Info);
    }

    public boolean isValid() {
        return (mInitialConfig == null) || mInitialConfig.isValid();
    }
}