--- /dev/null
+/*
+ * Copyright (c) 2008-2010 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 SecTrustPriv
+ The functions and data types in SecTrustPriv implement trust computation and allow the user to apply trust decisions to the trust configuration.
+*/
+
+#ifndef _SECURITY_SECTRUSTPRIV_H_
+#define _SECURITY_SECTRUSTPRIV_H_
+
+#include <Security/SecTrust.h>
+#include <CoreFoundation/CFData.h>
+#include <CoreFoundation/CFDictionary.h>
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/* Constants used as keys in property lists. See
+ SecTrustCopySummaryPropertiesAtIndex for more information. */
+extern CFStringRef kSecPropertyKeyType;
+extern CFStringRef kSecPropertyKeyLabel;
+extern CFStringRef kSecPropertyKeyLocalizedLabel;
+extern CFStringRef kSecPropertyKeyValue;
+
+extern CFStringRef kSecPropertyTypeWarning;
+extern CFStringRef kSecPropertyTypeError;
+extern CFStringRef kSecPropertyTypeSuccess;
+extern CFStringRef kSecPropertyTypeTitle;
+extern CFStringRef kSecPropertyTypeSection;
+extern CFStringRef kSecPropertyTypeData;
+extern CFStringRef kSecPropertyTypeString;
+extern CFStringRef kSecPropertyTypeURL;
+extern CFStringRef kSecPropertyTypeDate;
+
+/* Constants used as keys in the dictionary returned by SecTrustCopyInfo. */
+extern CFStringRef kSecTrustInfoExtendedValidationKey;
+extern CFStringRef kSecTrustInfoCompanyNameKey;
+extern CFStringRef kSecTrustInfoRevocationKey;
+extern CFStringRef kSecTrustInfoRevocationValidUntilKey;
+
+/*!
+ @function SecTrustCopySummaryPropertiesAtIndex
+ @abstract Return a property array for the certificate.
+ @param trust A reference to the trust object to evaluate.
+ @param ix The index of the requested certificate. Indices run from 0
+ (leaf) to the anchor (or last certificate found if no anchor was found).
+ @result A property array. It is the caller's responsibility to CFRelease
+ the returned array when it is no longer needed. This function returns a
+ short summary description of the certificate in question. The property
+ at index 0 of the array might also include general information about the
+ entire chain's validity in the context of this trust evaluation.
+
+ @discussion Returns a property array for this trust certificate. A property
+ array is an array of CFDictionaryRefs. Each dictionary (we call it a
+ property for short) has the following keys:
+
+ kSecPropertyKeyType This key's value determines how this property
+ should be displayed. Its associated value is one of the
+ following:
+ kSecPropertyTypeWarning
+ The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
+ set. The kSecPropertyKeyValue is a CFStringRef which should
+ be displayed in yellow with a warning triangle.
+ kSecPropertyTypeError
+ The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
+ set. The kSecPropertyKeyValue is a CFStringRef which should
+ be displayed in red with an error X.
+ kSecPropertyTypeSuccess
+ The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
+ set. The kSecPropertyKeyValue is a CFStringRef which should
+ be displayed in green with a checkmark in front of it.
+ kSecPropertyTypeTitle
+ The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
+ set. The kSecPropertyKeyValue is a CFStringRef which should
+ be displayed in a larger bold font.
+ kSecPropertyTypeSection
+ The optional kSecPropertyKeyLocalizedLabel is a CFStringRef with the name
+ of the next section to display. The value of the
+ kSecPropertyKeyValue key is a CFArrayRef which is a property
+ array as defined here.
+ kSecPropertyTypeData
+ The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
+ the localized label for the value for the kSecPropertyKeyValue.
+ The type of this value is a CFDataRef. Its contents should be
+ displayed as: "bytes length_of_data : hexdump_of_data". Ideally
+ the UI will only show one line of hex dump data and have a
+ disclosure arrow to see the remainder.
+ kSecPropertyTypeString
+ The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
+ the localized label for the value for the kSecPropertyKeyValue.
+ The type of this value is a CFStringRef. It's contents should be
+ displayed in the normal font.
+ kSecPropertyTypeURL
+ The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
+ the localized label for the value for the kSecPropertyKeyValue.
+ The type of this value is a CFURLRef. It's contents should be
+ displayed as a hyperlink.
+ kSecPropertyTypeDate
+ The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
+ the localized label for the value for the kSecPropertyKeyValue.
+ The type of this value is a CFDateRef. It's contents should be
+ displayed in human readable form (probably in the current
+ timezone).
+ kSecPropertyKeyLocalizedLabel
+ Human readable localized label for a given property.
+ kSecPropertyKeyValue
+ See description of kSecPropertyKeyType to determine what the value
+ for this key is.
+ kSecPropertyKeyLabel
+ Non localized key (label) for this value. This is only
+ present for properties with fixed label names.
+ @param certificate A reference to the certificate to evaluate.
+ @result A property array. It is the caller's responsability to CFRelease
+ the returned array when it is no longer needed.
+*/
+CFArrayRef SecTrustCopySummaryPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
+
+/*!
+ @function SecTrustCopyDetailedPropertiesAtIndex
+ @abstract Return a property array for the certificate.
+ @param trust A reference to the trust object to evaluate.
+ @param ix The index of the requested certificate. Indices run from 0
+ (leaf) to the anchor (or last certificate found if no anchor was found).
+ @result A property array. It is the caller's responsibility to CFRelease
+ the returned array when it is no longer needed.
+ See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
+ Unlike that function call this function returns a detailed description
+ of the certificate in question.
+*/
+CFArrayRef SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
+
+/*!
+ @function SecTrustCopyProperties
+ @abstract Return a property array for this trust evaluation.
+ @param trust A reference to the trust object to evaluate.
+ @result A property array. It is the caller's responsibility to CFRelease
+ the returned array when it is no longer needed. See
+ SecTrustCopySummaryPropertiesAtIndex for a detailed description of this array.
+ Unlike that function, this function returns a short text string suitable for
+ display in a sheet explaining to the user why this certificate chain is
+ not trusted for this operation. This function may return NULL if the
+ certificate chain was trusted.
+*/
+CFArrayRef SecTrustCopyProperties(SecTrustRef trust);
+
+/*!
+ @function SecTrustCopyInfo
+ @abstract Return a dictionary with additional information about the
+ evaluated certificate chain for use by clients.
+ @param trust A reference to an evaluated trust object.
+ @discussion Returns a dictionary for this trust evaluation. This
+ dictionary may have the following keys:
+
+ kSecTrustInfoExtendedValidationKey this key will be present and have
+ a value of kCFBooleanTrue if this chain was validated for EV.
+ kSecTrustInfoCompanyNameKey Company name field of subject of leaf
+ certificate, this field is meant to be displayed to the user
+ if the kSecTrustInfoExtendedValidationKey is present.
+ kSecTrustInfoRevocationKey this key will be present iff this chain
+ had its revocation checked. The value will be a kCFBooleanTrue
+ if revocation checking was successful and none of the
+ certificates in the chain were revoked.
+ The value will be kCFBooleanFalse if no current revocation status
+ could be obtained for one or more certificates in the chain due
+ to connection problems or timeouts etc. This is a hint to a
+ client to retry revocation checking at a later time.
+ kSecTrustInfoRevocationValidUntilKey this key will be present iff
+ kSecTrustInfoRevocationKey has a value of kCFBooleanTrue.
+ The value will be a CFDateRef representing the earliest date at
+ which the revocation info for one of the certificates in this chain
+ might change.
+
+ @result A dictionary with various fields that can be displayed to the user,
+ or NULL if no additional info is available or the trust has not yet been
+ validated. The caller is responsible for calling CFRelease on the value
+ returned when it is no longer needed.
+*/
+CFDictionaryRef SecTrustCopyInfo(SecTrustRef trust);
+
+/* For debugging purposes. */
+CFArrayRef SecTrustGetDetails(SecTrustRef trust);
+
+#if defined(__cplusplus)
+}
+#endif
+
+#endif /* !_SECURITY_SECTRUSTPRIV_H_ */
projects / apple / security.git / blobdiff