/* * Copyright (c) 2002-2017 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@ */ #ifndef _SECURITY_SECTRUSTSETTINGSPRIV_H_ #define _SECURITY_SECTRUSTSETTINGSPRIV_H_ #include <Security/SecBase.h> #include <CoreFoundation/CoreFoundation.h> #include <Security/SecPolicy.h> #include <Security/SecCertificate.h> #include <Security/SecTrustSettings.h> #if SEC_OS_OSX #include <Security/cssmtype.h> #endif __BEGIN_DECLS /* * Private Keys in the Usage Contraints dictionary. * kSecTrustSettingsPolicyName Specifies a cert verification policy, e.g., * sslServer, eapClient, etc, using policy names. * This entry can be used to restrict the policy where * the same Policy Constant is used for multiple policyNames. * kSectrustSettingsPolicyOptions Specifies a dictionary of policy options (from * SecPolicyInternal.h). This entry can be used to require * a particular SecPolicyCheck whenever this certificate is * encountered during trust evaluation. */ #define kSecTrustSettingsPolicyName CFSTR("kSecTrustSettingsPolicyName") #define kSecTrustSettingsPolicyOptions CFSTR("kSecTrustSettingsPolicyOptions") #if SEC_OS_OSX /* * Fundamental routine used by TP to ascertain status of one cert. * * Returns true in *foundMatchingEntry if a trust setting matching * specific constraints was found for the cert. Returns true in * *foundAnyEntry if any entry was found for the cert, even if it * did not match the specified constraints. The TP uses this to * optimize for the case where a cert is being evaluated for * one type of usage, and then later for another type. If * foundAnyEntry is false, the second evaluation need not occur. * * Returns the domain in which a setting was found in *foundDomain. * * Allowed errors applying to the specified cert evaluation * are returned in a mallocd array in *allowedErrors and must * be freed by caller. */ OSStatus SecTrustSettingsEvaluateCert( CFStringRef certHashStr, /* parameters describing the current cert evalaution */ const CSSM_OID *policyOID, const char *policyString, /* optional */ uint32 policyStringLen, SecTrustSettingsKeyUsage keyUsage, /* optional */ bool isRootCert, /* for checking default setting */ /* RETURNED values */ SecTrustSettingsDomain *foundDomain, CSSM_RETURN **allowedErrors, /* mallocd and RETURNED */ uint32 *numAllowedErrors, /* RETURNED */ SecTrustSettingsResult *resultType, /* RETURNED */ bool *foundMatchingEntry, /* RETURNED */ bool *foundAnyEntry); /* RETURNED */ /* * Obtain trusted certs which match specified usage. * Only certs with a SecTrustSettingsResult of * kSecTrustSettingsResultTrustRoot or * or kSecTrustSettingsResultTrustAsRoot will be returned. * * To be used by SecureTransport for its (hopefully soon-to-be- * deprecated) SSLSetTrustedRoots() call; I hope nothing else has * to use this... * * Caller must CFRelease the returned CFArrayRef. */ OSStatus SecTrustSettingsCopyQualifiedCerts( const CSSM_OID *policyOID, const char *policyString, /* optional */ uint32 policyStringLen, SecTrustSettingsKeyUsage keyUsage, /* optional */ CFArrayRef *certArray); /* RETURNED */ /* * Obtain unrestricted root certificates from the specified domain(s). * Only returns root certificates with no usage constraints. * Caller must CFRelease the returned CFArrayRef. */ OSStatus SecTrustSettingsCopyUnrestrictedRoots( Boolean userDomain, Boolean adminDomain, Boolean systemDomain, CFArrayRef *certArray); /* RETURNED */ /* * Obtain a string representing a cert's SHA1 digest. This string is * the key used to look up per-cert trust settings in a TrustSettings record. */ CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromCert( SecCertificateRef certRef); CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromData( const void *cert, size_t certLen); /* * Add a cert's TrustSettings to a non-persistent TrustSettings record. * Primarily intended for use in creating a system TrustSettings record * (which is itself immutable via this module). * * The settingsIn argument is an external representation of a TrustSettings * record, obtained from this function or from * SecTrustSettingsCreateExternalRepresentation(). * If settingsIn is NULL, a new (empty) TrustSettings will be created. * * The certRef and trustSettingsDictOrArray arguments are as in * SecTrustSettingsSetTrustSettings(). May be NULL, when e.g. creating * a new and empty TrustSettings record. * * The external representation is written to the settingOut argument, * which must eventually be CFReleased by the caller. */ OSStatus SecTrustSettingsSetTrustSettingsExternal( CFDataRef settingsIn, /* optional */ SecCertificateRef certRef, /* optional */ CFTypeRef trustSettingsDictOrArray, /* optional */ CFDataRef *settingsOut); /* RETURNED */ /* * Add user trust settings for a SSL certificate and a given hostname. * This is a wrapper around the SecTrustSettingsSetTrustSettings API * and should be functionally equivalent to "Always trust" in the UI. * * When this function is called, the user will be prompted to authorize * the trust settings change. After they successfully authenticate, or * cancel the dialog, the result block will be called to indicate the * current trust status. If an error occurred (such as errUserCanceled), * the error reference provided to the block will be non-NULL. */ void SecTrustSettingsSetTrustedCertificateForSSLHost( SecCertificateRef certificate, CFStringRef hostname, void (^result)(SecTrustSettingsResult trustResult, CFErrorRef error)) __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_NA); /* * Purge the cache of User and Admin Certs */ void SecTrustSettingsPurgeUserAdminCertsCache(void); #endif // SEC_OS_OSX #if SEC_OS_OSX_INCLUDES /* * A wrapper around SecTrustSettingsCopyCertificates that combines user and admin * domain outputs. */ OSStatus SecTrustSettingsCopyCertificatesForUserAdminDomains( CFArrayRef CF_RETURNS_RETAINED *certArray); #endif /* SEC_OS_OSX_INCLUDES */ __END_DECLS #endif // _SECURITY_SECTRUSTSETTINGSPRIV_H_