X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/5dd5f9ec28f304ca377c42fd7f711d6cf12b90e1..5c19dc3ae3bd8e40a9c028b0deddd50ff337692c:/OSX/include/security_keychain/TrustSettings.h diff --git a/OSX/include/security_keychain/TrustSettings.h b/OSX/include/security_keychain/TrustSettings.h new file mode 100644 index 00000000..ffebdd33 --- /dev/null +++ b/OSX/include/security_keychain/TrustSettings.h @@ -0,0 +1,256 @@ +/* + * Copyright (c) 2005,2011,2014 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@ + */ + +/* + * TrustSettings.h - class to manage trusted certs. + */ + +#ifndef _TRUST_SETTINGS_H_ +#define _TRUST_SETTINGS_H_ + +#include "SecTrust.h" +#include +#include + +/* + * Clarification of the bool arguments to our main constructor. + */ +#define CREATE_YES true +#define CREATE_NO false +#define TRIM_YES true +#define TRIM_NO false + +namespace Security +{ + +namespace KeychainCore +{ + +/* + * Additional values for the SecTrustSettingsDomain enum. + */ +enum { + /* + * This indicates a TrustSettings that exists only in memory; it + * can't be written to disk. + */ + kSecTrustSettingsDomainMemory = 100 +}; + +class TrustSettings +{ +private: + TrustSettings(SecTrustSettingsDomain domain); + +public: + + /* + * Normal constructor, from disk. + * If create is true, the absence of an on-disk TrustSettings file + * results in the creation of a new empty TrustSettings. If create is + * false and no on-disk TrustSettings exists, errSecItemNotFound is + * thrown. + * If trim is true, the components of the on-disk TrustSettings not + * needed for cert evaluation are discarded. This is for TrustSettings + * that will be cached in memory long-term. + */ + static OSStatus CreateTrustSettings( + SecTrustSettingsDomain domain, + bool create, + bool trim, + TrustSettings*& ts); + + /* + * Create from external data, obtained by createExternal(). + * If externalData is NULL, we'll create an empty mTrustDict. + */ + static OSStatus CreateTrustSettings( + SecTrustSettingsDomain domain, + CFDataRef externalData, + TrustSettings*& ts); + + ~TrustSettings(); + + /* + * Evaluate specified cert. Returns true if we found a matching + * record for the cert. + */ + bool evaluateCert( + CFStringRef certHashStr, + const CSSM_OID *policyOID, /* optional */ + const char *policyString, /* optional */ + SecTrustSettingsKeyUsage keyUsage, /* optional */ + bool isRootCert, /* for checking default setting */ + CSSM_RETURN **allowedErrors, /* mallocd and RETURNED */ + uint32 *numAllowedErrors, /* RETURNED */ + SecTrustSettingsResult *resultType, /* RETURNED */ + bool *foundAnyEntry); /* RETURNED - there is SOME entry for + * this cert */ + + /* + * Only certs with a SecTrustSettingsResult of kSecTrustSettingsResultTrustRoot + * or kSecTrustSettingsResultTrustAsRoot will be returned. + */ + void findQualifiedCerts( + StorageManager::KeychainList &keychains, + /* + * If findAll is true, all certs are returned and the subsequent + * qualifiers are ignored + */ + bool findAll, + /* if true, only return root (self-signed) certs */ + bool onlyRoots, + const CSSM_OID *policyOID, /* optional */ + const char *policyString, /* optional */ + SecTrustSettingsKeyUsage keyUsage, /* optional */ + CFMutableArrayRef certArray); /* certs appended here */ + + /* + * Find all certs in specified keychain list which have entries in this trust record. + * Certs already in the array are not added. + */ + void findCerts( + StorageManager::KeychainList &keychains, + CFMutableArrayRef certArray); + + /* + * Obtain trust settings for the specified cert. Returned settings array + * is in the public API form; caller must release. Returns NULL + * (does not throw) if the cert is not present in this TrustRecord. + * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting. + */ + CFArrayRef copyTrustSettings( + SecCertificateRef certRef); + + /* + * Obtain the mod date for the specified cert's trust settings. + * Returns NULL (does not throw) if the cert is not present in this + * TrustRecord. + * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting. + */ + CFDateRef copyModDate( + SecCertificateRef certRef); + + /* + * Modify cert's trust settings, or add a new cert to the record. + * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting. + */ + void setTrustSettings( + SecCertificateRef certRef, + CFTypeRef trustSettingsDictOrArray); + + /* + * Delete a certificate's trust settings. + * Throws errSecItemNotFound if there currently are no settings. + * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting. + */ + void deleteTrustSettings( + SecCertificateRef certRef); + + /* + * Flush property list data out to disk if dirty. + */ + void flushToDisk(); + + /* + * Obtain external representation of TrustSettings data. + */ + CFDataRef createExternal(); + +private: + /* common code to init mPropList from raw data */ + void initFromData( + CFDataRef trustSettingsData); + + /* + * Find a given cert's entry in mTrustDict. + * Returned dictionary is not refcounted. + */ + CFDictionaryRef findDictionaryForCert( + SecCertificateRef certRef); + + /* + * Find entry in mTrustDict given cert hash string. + */ + CFDictionaryRef findDictionaryForCertHash( + CFStringRef certHashStr); + + /* + * Validate incoming API-style trust settings, which may be NULL, a + * dictionary, or an array of dictionaries. We return a deep-copied, + * refcounted CFArray, in internal format, in any case as long as the + * incoming parameter is good. + */ + CFArrayRef validateApiTrustSettings( + CFTypeRef trustSettingsDictOrArray, + Boolean isSelfSigned); + + /* + * Validate an usage constraint array from disk as part of our mPropDict + * array. Returns true if OK, else returns false. + */ + bool validateTrustSettingsArray( + CFArrayRef trustSettings); + + /* + * Obtain issuer and serial number for specified cert, both + * returned as CFDataRefs owned by caller. + */ + void copyIssuerAndSerial( + SecCertificateRef cert, + CFDataRef *issuer, /* optional, RETURNED */ + CFDataRef *serial); /* RETURNED */ + + /* + * Validate mPropDict after it's read from disk. Allows subsequent use of + * mPropDict and mTrustDict to proceed with relative impunity. + * If trim is true, we remove fields in the per-cert dictionaries which + * are not needed for cert evaluation. We also release the top-level + * mPropList, which serves as a "this is trimmed" indicator if NULL. + */ + void validatePropList(bool trim); + + /* fatal error abort */ + void abort( + const char *why, + OSStatus err); + + /* the overall parsed TrustSettings - may be NULL if this is trimmed */ + CFMutableDictionaryRef mPropList; + + /* and the main thing we work with, the dictionary of per-cert trust settings */ + CFMutableDictionaryRef mTrustDict; + + /* version number of mPropDict */ + SInt32 mDictVersion; + + SecTrustSettingsDomain mDomain; + bool mDirty; /* we've changed mPropDict since creation */ +}; + +} /* end namespace KeychainCore */ + +} /* end namespace Security */ + +#endif /* _TRUST_SETTINGS_H_ */ +