/*
 * Copyright (c) 2017 Apple Inc. All rights reserved.
 *
 * @APPLE_APACHE_LICENSE_HEADER_START@
 *
 * 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.
 *
 * @APPLE_APACHE_LICENSE_HEADER_END@
 */

#ifndef __OS_VARIANT_H__
#define __OS_VARIANT_H__

#include <stdbool.h>

#include <os/base.h>
#include <os/availability.h>

OS_ASSUME_PTR_ABI_SINGLE_BEGIN

/*! @header
 * OS Variant SPI
 *
 * Provides a mechanism to determine the currently running OS variant.
 *
 * Any of these APIs may be overridden to its non-internal behavior on a
 * device by creating on override file.  On macOS, the path of this file
 * is:
 *    /var/db/os_variant_override
 * On embedded platforms, the path of the override file is:
 *    /usr/share/misc/os_variant_override
 *
 * Individual internal behaviors can be selectively disabled (ie.
 * individual os_variant_has_internal_*() predicates can be overriden to
 * false) by writing the file with a comma- or newline-delimited list of
 * behaviors to disable.  To disable all internal behaviors, empty the file.
 *
 * There is currently no support for configuring per-subsystem overrides.
 *
 * Examples:
 *   This will disable internal diagnostics and UI on macOS:
 *     sudo sh -c 'echo "diagnostics,ui" > /var/db/os_variant_override'
 *   This will disable internal UI on iOS (assuming logged in as root):
 *     echo "ui" > /usr/share/misc/os_variant_override
 *   This will disable all internal behaviors on macOS:
 *     sudo sh -c '/bin/echo -n > /var/db/os_variant_override'
 *
 * Note that the values returned by these APIs are cached in the kernel at
 * system boot.  A reboot will be required after changing the overrides
 * before the new settings will take effect.
 *
 * Each of these functions takes a constant string argument for the requesting
 * subsystem.  This should be a reverse-DNS string describing the subsystem
 * performing the check.  This may be used in the future for auditing and
 * selective overriding of checks.
 *
 */

__BEGIN_DECLS

/*!
 * @function os_variant_has_internal_content
 *
 * @abstract returns whether this system variant has internal content installed
 * ("content")
 *
 * @result
 * Returns true if this build has this property.  False otherwise or upon error.
 */
API_AVAILABLE(macosx(10.13), ios(11.0), tvos(11.0), watchos(4.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_has_internal_content(const char *subsystem);

/*!
 * @function os_variant_has_internal_diagnostics
 *
 * @abstract returns whether this system variant has internal diagnostics
 * enabled ("diagnostics")
 *
 * @description
 *
 * Internal diagnostics include behaviors that emit extra diagnostic or
 * debugging information when an error occurs.
 *
 * On macOS, this check will look for presence of AppleInternal content or the
 * AppleInternalDiagnostics profile to be installed.
 *
 * On embedded platforms, this check will look for an internal install variant
 * in a manner similar to the MobileGestalt check for InternalBuild.
 *
 * @result
 * Returns true if this build has this property.  False otherwise or upon error.
 */
API_AVAILABLE(macosx(10.13), ios(11.0), tvos(11.0), watchos(4.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_has_internal_diagnostics(const char *subsystem);

/*!
 * @function os_variant_has_internal_ui
 *
 * @abstract returns whether this system variant has internal UI visible ("ui")
 *
 * @description
 *
 * Internal UI includes debug menus and internal settings.
 *
 * On macOS, this will check for the presence of AppleInternal content.  On
 * embedded platforms, this check will look for an internal install variant in
 * a manner similar to the MobileGestalt check for InternalBuild.
 *
 * @result
 * Returns true if this build has this property.  False otherwise or upon error.
 */
API_AVAILABLE(macosx(10.13), ios(11.0), tvos(11.0), watchos(4.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_has_internal_ui(const char *subsystem);

/*!
 * @function os_variant_allows_internal_security_policies
 *
 * @abstract returns whether this system variant allows internal security policies
 * ("security")
 *
 * @description
 *
 * On macOS, this will check the CSR status for whether AppleInternal policies
 * are enabled.
 *
 * On embedded platforms, this will check for a build/device combination that
 * allows for removal of codesigning and debugging restrictions.  This usually
 * returns whether the hardware is development fused and may return true on
 * such hardware even if a customer build is installed.
 *
 * n.b. The result of this API should /not/ be used to automatically enable
 * relaxed security policies, only to signal that other mechanisms to enable
 * them are allowed, e.g. a "defaults write".
 *
 * @result
 * Returns true if this build has this property.  False otherwise or upon error.
 */
API_AVAILABLE(macosx(10.13), ios(11.0), tvos(11.0), watchos(4.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_allows_internal_security_policies(const char *subsystem);

/*!
 * @function os_variant_has_factory_content
 *
 * @abstract returns whether this system has factory diagnostics content
 *
 * @description
 *
 * On macOS, this checks for a AppleFactoryVariant.plist that is present in the
 * factory diagnostics image.
 *
 * On embedded platforms, this will check for the NonUI variant.
 *
 * @result
 * Returns true if this build has this property.  False otherwise or upon error.
 */
API_AVAILABLE(macosx(10.14.4), ios(12.2), tvos(12.2), watchos(5.2))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_has_factory_content(const char *subsystem);

/*!
 * @function os_variant_is_darwinos
 *
 * @abstract returns whether this system variant is a darwinOS variant
 *
 * @result
 * Returns true if this variant is a darwinOS variant.
 */
API_AVAILABLE(macosx(10.15), ios(13.0), tvos(13.0), watchos(6.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_is_darwinos(const char *subsystem);

/*!
 * @function os_variant_uses_ephemeral_storage
 *
 * @abstract returns whether the system is booted from an ephemeral volume
 *
 * @result
 * Returns true if the system is booted with ephemeral storage for the data volume.
 */
API_AVAILABLE(macosx(10.15), ios(13.0), tvos(13.0), watchos(6.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_uses_ephemeral_storage(const char *subsystem);

/*!
 * @function os_variant_allows_security_research
 *
 * @abstract returns whether the host permits security research
 *
 * @result
 * Returns true if the system permits itself to be attacked by untrustworthy
 * code for the purposes of security research.
 */
API_AVAILABLE(macosx(12.0), ios(15.0), tvos(15.0), watchos(8.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_allows_security_research(const char *subsystem);

/*!
 * @function os_variant_is_basesystem
 *
 * @abstract returns whether this system variant is the macOS BaseSystem
 *
 * @description
 * On macOS, this returns whether the running environment is the BaseSystem.
 *
 * The macOS BaseSystem is used for Recovery, Installer, Diagnostics, FileVault
 * unlock, and more.  This will return true on all of these.
 *
 * @result
 * Returns true if this variant is BaseSystem
 */
API_AVAILABLE(macosx(10.16)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos)
OS_EXPORT OS_WARN_RESULT
bool
os_variant_is_basesystem(const char *subsystem);

/*!
 * @function os_variant_is_recovery
 *
 * @abstract returns whether this system variant is the recovery OS.
 *
 * @description
 * On macOS, this returns whether the running environment is the BaseSystem, in
 * a mode where it is independent of a running operating system.  This includes
 * the installer, local and internet recovery, and diagnostics.  It does not
 * include modes where the BaseSystem is acting as a mode of the primary OS,
 * such as FileVault unlock.
 *
 * NOTE: this is currently not implemented and simply returns
 * os_variant_is_basesystem() until it can be implemented.
 *
 * On embedded platforms, this returns whether this is the NeRD (Network
 * Recovery on Device) OS.  It returns false in the restore/OTA ramdisks.
 *
 * @result
 * Returns true if this variant is a recoveryOS
 */
API_AVAILABLE(macosx(10.15), ios(13.0), tvos(13.0), watchos(6.0), bridgeos(4.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_is_recovery(const char *subsystem);

/*!
 * @function os_variant_check
 *
 * @abstract returns whether the system is of the specified variant
 *
 * @description
 * This check checks against below known variants. False is returned if the
 * variant passed in is not in the list.
 *
 *     HasInternalContent
 *     HasInternalDiagnostics
 *     HasInternalUI
 *     AllowsInternalSecurityPolicies
 *     HasFactoryContent
 *     IsDarwinOS
 *     UsesEphemeralStorage
 *     IsRecovery
 *     AllowsSecurityResearch
 *
 * @result
 * Returns true if the system is of the specified variant.
 */
API_AVAILABLE(macosx(10.15), ios(13.0), tvos(13.0), watchos(6.0), bridgeos(4.0))
OS_EXPORT OS_WARN_RESULT
bool
os_variant_check(const char *subsystem, const char *variant);

/*!
 * @function os_variant_copy_description
 *
 * @abstract returns a string describing the current variants
 *
 * @description
 * This returns a string containing the variants of the current system.
 *
 * @result
 * Returns a string that must be freed by the caller if successful.  If an
 * error occurs, @c NULL is returned and @c errno will be set to indicate the
 * error.
 */
API_AVAILABLE(macosx(10.16), ios(14.0), tvos(13.0), watchos(7.0), bridgeos(4.0))
OS_EXPORT OS_WARN_RESULT
char *__unsafe_indexable
os_variant_copy_description(const char *subsystem);

/*!
 * @function os_variant_init_4launchd
 *
 * @abstract private initializer for launchd; do not use
 */
OS_EXPORT
void
os_variant_init_4launchd(const char *boot_mode);

__END_DECLS
OS_ASSUME_PTR_ABI_SINGLE_END

#endif // __os_variant_H__