X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/5dd5f9ec28f304ca377c42fd7f711d6cf12b90e1..5c19dc3ae3bd8e40a9c028b0deddd50ff337692c:/OSX/sec/Security/SecTrustSettings.h diff --git a/OSX/sec/Security/SecTrustSettings.h b/OSX/sec/Security/SecTrustSettings.h new file mode 100644 index 00000000..eb9a3d5c --- /dev/null +++ b/OSX/sec/Security/SecTrustSettings.h @@ -0,0 +1,247 @@ +/* + * Copyright (c) 2007,2012 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 +#include + +#ifdef __cplusplus +extern "C" { +#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 value = SecPolicyRef + * 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. + * 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. + */ +enum { + /* 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 +}; +typedef uint32_t SecTrustSettingsKeyUsage; + +/*! + @enum SecTrustSettingsResult + @abstract Result of a trust settings evaluation. +*/ +enum { + 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 */ +}; +typedef uint32_t SecTrustSettingsResult; + +/* + * Specify user, local administrator, or system domain Trust Properties. + * Note that kSecTrustSettingsDomainSystem settings are read-only, even by + * root. + */ +enum { + kSecTrustSettingsDomainUser = 0, + kSecTrustSettingsDomainAdmin, + kSecTrustSettingsDomainSystem +}; +typedef uint32_t SecTrustSettingsDomain; + +/* + * SecCertificateRef value indicating the default Root Certificate Trust Settings + * for a given domain. When evaluating Trust Settings for a root cert in + * a given domain, *and* no matching explicit Trust Settings exists for the + * root cert in questions, *and* default Root Cert Trust Settings exist + * in that domain which matches the evaluation condition, then the + * SecTrustSettingsResult for that default Trust Setting (if not + * kSecTrustSettingsResultUnspecified) will apply. + * + * This can be used e.g. by a system administrator to explicilty distrust all + * of the root certs in the (immutable) system domain for a specific policy. + * + * This const is passed as the 'SecCertificateRef certRef' argument to + * SecTrustSettingsCopyTrustSettings(), SecTrustSettingsSetTrustSettings(), + * and SecTrustSettingsRemoveTrustSettings(), and + * SecTrustSettingsCopyModificationDate(). + */ +#define kSecTrustSettingsDefaultRootCertSetting ((SecCertificateRef)-1) + +#ifdef __cplusplus +} +#endif + +#endif /* _SECURITY_SECTRUSTSETTINGS_H_ */