/* * Copyright (c) 2006,2007,2011,2012,2014-2016 Apple Inc. All Rights Reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /*! @header SecTrustSettings The functions and data types in SecTrustSettings implement a way to set and retrive trustability of certificates. */ #ifndef _SECURITY_SECTRUSTSETTINGS_H_ #define _SECURITY_SECTRUSTSETTINGS_H_ #include <CoreFoundation/CoreFoundation.h> #include <CoreFoundation/CFArray.h> #include <Security/SecBase.h> #include <Security/SecCertificate.h> #if SEC_OS_OSX #include <Security/SecKeychain.h> #include <Security/SecPolicy.h> #include <Security/cssmtype.h> #endif /* SEC_OS_OSX */ __BEGIN_DECLS #if SEC_OS_OSX_INCLUDES CF_ASSUME_NONNULL_BEGIN #endif /* * Any certificate (cert) which resides in a keychain can have associated with * it a set of Trust Settings. Trust Settings specify conditions in which a * given cert can be trusted or explicitly distrusted. A "trusted" cert is * either a root (self-signed) cert that, when a cert chain verifies back to that * root, the entire cert chain is trusted; or a non-root cert that does not need * to verify to a trusted root cert (which is normally the case when verifying a * cert chain). An "explicitly distrusted" cert is one which will, when encountered * during the evaluation of a cert chain, cause immediate and unconditional failure * of the verify operation. * * Trust Settings are configurable by the user; they can apply on three levels * (called domains): * * -- Per-user. * -- Locally administered, system-wide. Administrator privileges are required * to make changes to this domain. * -- System. These Trust Settings are immutable and comprise the set of trusted * root certificates supplied in Mac OS X. * * Per-user Trust Settings override locally administered Trust Settings, which * in turn override the System Trust Settings. * * Each cert's Trust Settings are expressed as a CFArray which includes any * number (including zero) of CFDictionaries, each of which comprises one set of * Usage Constraints. Each Usage Constraints dictionary contains zero or one of * each the following components: * * key = kSecTrustSettingsPolicy On OSX, value = SecPolicyRef On iOS, value = policy OID as CFString * * key = kSecTrustSettingsApplication value = SecTrustedApplicationRef * key = kSecTrustSettingsPolicyString value = CFString, policy-specific * key = kSecTrustSettingsKeyUsage value = CFNumber, an SInt32 key usage * * A given Usage Constraints dictionary applies to a given cert if *all* of the * usage constraint components specified in the dictionary match the usage of * the cert being evaluated; when this occurs, the value of the * kSecTrustSettingsResult entry in the dictionary, shown below, is the effective * trust setting for the cert. * * key = kSecTrustSettingsResult value = CFNumber, an SInt32 SecTrustSettingsResult * * The overall Trust Settings of a given cert are the sum of all such Usage * Constraints CFDictionaries: Trust Settings for a given usage apply if *any* * of the CFDictionaries in the cert's Trust Settings array satisfies * the specified usage. Thus, when a cert has multiple Usage Constraints * dictionaries in its Trust Settings array, the overall Trust Settings * for the cert are * * (Usage Constraint 0 component 0 AND Usage Constraint 0 component 1 ...) * -- OR -- * (Usage Constraint 1 component 0 AND Usage Constraint 1 component 1 ...) * -- OR -- * ... * * Notes on the various Usage Constraints components: * * kSecTrustSettingsPolicy Specifies a cert verification policy, e.g., SSL, * SMIME, etc, using Policy Constants * kSecTrustSettingsApplication Specifies the application performing the cert * verification. * kSecTrustSettingsPolicyString Policy-specific. For the SMIME policy, this is * an email address. * For the SSL policy, this is a host name. * kSecTrustSettingsKeyUsage A bitfield indicating key operations (sign, * encrypt, etc.) for which this Usage Constraint * apply. Values are defined below as the * SecTrustSettingsKeyUsage enum. * kSecTrustSettingsResult The resulting trust value. If not present this has a * default of kSecTrustSettingsResultTrustRoot, meaning * "trust this root cert". Other legal values are: * kSecTrustSettingsResultTrustAsRoot : trust non-root * cert as if it were a trusted root. * kSecTrustSettingsResultDeny : explicitly distrust this * cert. * kSecTrustSettingsResultUnspecified : neither trust nor * distrust; can be used to specify an "Allowed error" * (see below) without assigning trust to a specific * cert. * * Another optional component in a Usage Constraints dictionary is a CSSM_RETURN * which, if encountered during certificate verification, is ignored for that * cert. These "allowed error" values are constrained by Usage Constraints as * described above; a Usage Constraint dictionary with no constraints but with * an Allowed Error value causes that error to always be allowed when the cert * is being evaluated. * * The "allowed error" entry in a Usage Constraints dictionary is formatted * as follows: * * key = kSecTrustSettingsAllowedError value = CFNumber, an SInt32 CSSM_RETURN * * Note that if kSecTrustSettingsResult value of kSecTrustSettingsResultUnspecified * is *not* present for a Usage Constraints dictionary with no Usage * Constraints, the default of kSecTrustSettingsResultTrustRoot is assumed. To * specify a kSecTrustSettingsAllowedError without explicitly trusting (or * distrusting) the associated cert, specify kSecTrustSettingsResultUnspecified * for the kSecTrustSettingsResult component. * * Note that an empty Trust Settings array means "always trust this cert, * with a resulting kSecTrustSettingsResult of kSecTrustSettingsResultTrustRoot". * An empty Trust Settings array is definitely not the same as *no* Trust * Settings, which means "this cert must be verified to a known trusted cert". * * Note the distinction between kSecTrustSettingsResultTrustRoot and * kSecTrustSettingsResultTrustAsRoot; the former can only be applied to * root (self-signed) certs; the latter can only be applied to non-root * certs. This also means that an empty TrustSettings array for a non-root * cert is invalid, since the default value for kSecTrustSettingsResult is * kSecTrustSettingsResultTrustRoot, which is invalid for a non-root cert. * * Authentication * -------------- * * When making changes to the per-user Trust Settings, the user will be * prompted with an alert panel asking for authentication via user name a * password (or other credentials normally used for login). This means * that it is not possible to modify per-user Trust Settings when not * running in a GUI environment (i.e. the user is not logged in via * Loginwindow). * * When making changes to the system-wide Trust Settings, the user will be * prompted with an alert panel asking for an administrator's name and * password, unless the calling process is running as root in which case * no futher authentication is needed. */ /* * The keys in one Usage Constraints dictionary. */ #define kSecTrustSettingsPolicy CFSTR("kSecTrustSettingsPolicy") #define kSecTrustSettingsApplication CFSTR("kSecTrustSettingsApplication") #define kSecTrustSettingsPolicyString CFSTR("kSecTrustSettingsPolicyString") #define kSecTrustSettingsKeyUsage CFSTR("kSecTrustSettingsKeyUsage") #define kSecTrustSettingsAllowedError CFSTR("kSecTrustSettingsAllowedError") #define kSecTrustSettingsResult CFSTR("kSecTrustSettingsResult") /* * Key usage bits, the value for Usage Constraints key kSecTrustSettingsKeyUsage. */ typedef CF_OPTIONS(uint32_t, SecTrustSettingsKeyUsage) { /* sign/verify data */ kSecTrustSettingsKeyUseSignature = 0x00000001, /* bulk encryption */ kSecTrustSettingsKeyUseEnDecryptData = 0x00000002, /* key wrap/unwrap */ kSecTrustSettingsKeyUseEnDecryptKey = 0x00000004, /* sign/verify cert */ kSecTrustSettingsKeyUseSignCert = 0x00000008, /* sign/verify CRL and OCSP */ kSecTrustSettingsKeyUseSignRevocation = 0x00000010, /* key exchange, e.g., Diffie-Hellman */ kSecTrustSettingsKeyUseKeyExchange = 0x00000020, /* any usage (the default if this value is not specified) */ kSecTrustSettingsKeyUseAny = 0xffffffff }; /*! @enum SecTrustSettingsResult @abstract Result of a trust settings evaluation. */ typedef CF_ENUM(uint32_t, SecTrustSettingsResult) { kSecTrustSettingsResultInvalid = 0, /* Never valid in a Trust Settings array or * in an API call. */ kSecTrustSettingsResultTrustRoot, /* Root cert is explicitly trusted */ kSecTrustSettingsResultTrustAsRoot, /* Non-root cert is explicitly trusted */ kSecTrustSettingsResultDeny, /* Cert is explicitly distrusted */ kSecTrustSettingsResultUnspecified /* Neither trusted nor distrusted; evaluation * proceeds as usual */ }; /* * Specify user, local administrator, or system domain Trust Settings. * Note that kSecTrustSettingsDomainSystem settings are read-only, even by * root. */ typedef CF_ENUM(uint32_t, SecTrustSettingsDomain) { kSecTrustSettingsDomainUser = 0, kSecTrustSettingsDomainAdmin, kSecTrustSettingsDomainSystem }; /* * This constant is deprecated and ineffective as of macOS 10.12. * Please discontinue use. */ #define kSecTrustSettingsDefaultRootCertSetting ((SecCertificateRef)-1) #if SEC_OS_OSX_INCLUDES /* * Obtain Trust Settings for specified cert. * Caller must CFRelease() the returned CFArray. * Returns errSecItemNotFound if no Trust settings exist for the cert. */ OSStatus SecTrustSettingsCopyTrustSettings( SecCertificateRef certRef, SecTrustSettingsDomain domain, CFArrayRef * __nonnull CF_RETURNS_RETAINED trustSettings); /* RETURNED */ /* * Specify Trust Settings for specified cert. If specified cert * already has Trust Settings in the specified domain, they will * be replaced. * The trustSettingsDictOrArray parameter is either a CFDictionary, * a CFArray of them, or NULL. NULL indicates "always trust this * root cert regardless of usage". */ OSStatus SecTrustSettingsSetTrustSettings( SecCertificateRef certRef, SecTrustSettingsDomain domain, CFTypeRef __nullable trustSettingsDictOrArray); /* * Delete Trust Settings for specified cert. * Returns errSecItemNotFound if no Trust settings exist for the cert. */ OSStatus SecTrustSettingsRemoveTrustSettings( SecCertificateRef certRef, SecTrustSettingsDomain domain); /* * Obtain an array of all certs which have Trust Settings in the * specified domain. Elements in the returned certArray are * SecCertificateRefs. * Caller must CFRelease() the returned array. * Returns errSecNoTrustSettings if no trust settings exist * for the specified domain. */ OSStatus SecTrustSettingsCopyCertificates( SecTrustSettingsDomain domain, CFArrayRef * __nullable CF_RETURNS_RETAINED certArray); /* * Obtain the time at which a specified cert's Trust Settings * were last modified. Caller must CFRelease the result. * Returns errSecItemNotFound if no Trust Settings exist for specified * cert and domain. */ OSStatus SecTrustSettingsCopyModificationDate( SecCertificateRef certRef, SecTrustSettingsDomain domain, CFDateRef * __nonnull CF_RETURNS_RETAINED modificationDate); /* RETURNED */ /* * Obtain an external, portable representation of the specified * domain's TrustSettings. Caller must CFRelease the returned data. * Returns errSecNoTrustSettings if no trust settings exist * for the specified domain. */ OSStatus SecTrustSettingsCreateExternalRepresentation( SecTrustSettingsDomain domain, CFDataRef * __nonnull CF_RETURNS_RETAINED trustSettings); /* * Import trust settings, obtained via SecTrustSettingsCreateExternalRepresentation, * into the specified domain. */ OSStatus SecTrustSettingsImportExternalRepresentation( SecTrustSettingsDomain domain, CFDataRef trustSettings); CF_ASSUME_NONNULL_END #endif /* SEC_OS_OSX_INCLUDES */ __END_DECLS #endif /* _SECURITY_SECTRUSTSETTINGS_H_ */