You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
322 lines
13 KiB
322 lines
13 KiB
/* |
|
* Copyright (c) 2006,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@ |
|
*/ |
|
|
|
/* |
|
* SecTrustSettings.h - Public interface for manipulation of certificate |
|
* Trust Settings. |
|
*/ |
|
|
|
#ifndef _SECURITY_SEC_TRUST_SETTINGS_H_ |
|
#define _SECURITY_SEC_TRUST_SETTINGS_H_ |
|
|
|
#include <CoreFoundation/CoreFoundation.h> |
|
#include <Security/cssmtype.h> |
|
#include <Security/SecKeychain.h> |
|
#include <Security/SecPolicy.h> |
|
#include <Security/SecCertificate.h> |
|
|
|
#ifdef __cplusplus |
|
extern "C" { |
|
#endif |
|
|
|
CF_ASSUME_NONNULL_BEGIN |
|
|
|
/* |
|
* 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. |
|
*/ |
|
typedef CF_OPTIONS(uint32, 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 |
|
}; |
|
|
|
/* |
|
* The effective Trust Setting result. |
|
*/ |
|
typedef CF_ENUM(uint32, 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, SecTrustSettingsDomain) { |
|
kSecTrustSettingsDomainUser = 0, |
|
kSecTrustSettingsDomainAdmin, |
|
kSecTrustSettingsDomainSystem |
|
}; |
|
|
|
/* |
|
* 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) |
|
|
|
/* |
|
* 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 |
|
|
|
#ifdef __cplusplus |
|
} |
|
#endif |
|
|
|
#endif /* _SECURITY_SEC_TRUST_SETTINGS_H_ */ |
|
|
|
|