Security-55471.14.18.tar.gz

[apple/security.git] / libsecurity_keychain / lib / SecTrustSettings.h

/*
 * Copyright (c) 2006 Apple Computer, 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

/*
 * 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 SecTrustSettingsKeyUsage;

/*
 * The effective Trust Setting result.
 */
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 SecTrustSettingsResult;

/* 
 * Specify user, local administrator, or system domain Trust Settings. 
 * Note that kSecTrustSettingsDomainSystem settings are read-only, even by
 * root.  
 */
enum {
	kSecTrustSettingsDomainUser = 0,
	kSecTrustSettingsDomainAdmin,
	kSecTrustSettingsDomainSystem
};
typedef uint32 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)

/* 
 * 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				*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				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				*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				*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				*trustSettings);

/*
 * Import trust settings, obtained via SecTrustSettingsCreateExternalRepresentation,
 * into the specified domain. 
 */
OSStatus SecTrustSettingsImportExternalRepresentation(
	SecTrustSettingsDomain	domain,
	CFDataRef				trustSettings);

#ifdef __cplusplus
}
#endif

#endif	/* _SECURITY_SEC_TRUST_SETTINGS_H_ */