OSX/libsecurity_keychain/lib/SecCertificate.h

   1 /*
   2  * Copyright (c) 2002-2011,2013 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25         @header SecCertificate
  26         The functions provided in SecCertificate implement and manage a particular type of keychain item that represents a certificate.  You can store a certificate in a keychain, but a certificate can also be a transient object.
  27
  28         You can use a certificate as a keychain item in most functions.
  29 */
  30
  31 #ifndef _SECURITY_SECCERTIFICATE_H_
  32 #define _SECURITY_SECCERTIFICATE_H_
  33
  34 #define _SECURITY_VERSION_GREATER_THAN_57610_
  35
  36 #include <CoreFoundation/CFBase.h>
  37 #include <CoreFoundation/CFArray.h>
  38 #include <CoreFoundation/CFData.h>
  39 #include <CoreFoundation/CFDate.h>
  40 #include <CoreFoundation/CFError.h>
  41 #include <Security/SecBase.h>
  42 #include <Security/cssmtype.h>
  43 #include <Security/x509defs.h>
  44 #include <Availability.h>
  45 #include <AvailabilityMacros.h>
  46 /*
  47 #include <Security/SecTransform.h>
  48 #include <Security/SecIdentity.h>
  49 */
  50
  51 #if defined(__cplusplus)
  52 extern "C" {
  53 #endif
  54
  55 CF_ASSUME_NONNULL_BEGIN
  56 CF_IMPLICIT_BRIDGING_ENABLED
  57
  58 /*!
  59         @enum CertificateItemAttributes
  60         @abstract Indicates the type of a certificate item attribute.
  61         @constant kSecSubjectItemAttr Indicates a DER-encoded subject distinguished name.
  62         @constant kSecIssuerItemAttr Indicates a DER-encoded issuer distinguished name.
  63         @constant kSecSerialNumberItemAttr Indicates a DER-encoded certificate serial number (without the tag and length).
  64         @constant kSecPublicKeyHashItemAttr Indicates a public key hash.
  65         @constant kSecSubjectKeyIdentifierItemAttr Indicates a subject key identifier.
  66         @constant kSecCertTypeItemAttr Indicates a certificate type.
  67         @constant kSecCertEncodingItemAttr Indicates a certificate encoding.
  68 */
  69 enum
  70 {
  71     kSecSubjectItemAttr                          = 'subj',
  72     kSecIssuerItemAttr                           = 'issu',
  73     kSecSerialNumberItemAttr             = 'snbr',
  74     kSecPublicKeyHashItemAttr            = 'hpky',
  75     kSecSubjectKeyIdentifierItemAttr = 'skid',
  76         kSecCertTypeItemAttr                     = 'ctyp',
  77         kSecCertEncodingItemAttr                 = 'cenc'
  78 } /*DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER*/;
  79
  80 /*!
  81         @function SecCertificateGetTypeID
  82         @abstract Returns the type identifier of SecCertificate instances.
  83         @result The CFTypeID of SecCertificate instances.
  84 */
  85 CFTypeID SecCertificateGetTypeID(void)
  86         __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
  87
  88 #pragma mark ---- Certificate Operations ----
  89
  90 /*!
  91         @function SecCertificateCreateFromData
  92         @abstract Creates a certificate based on the input data, type, and encoding.
  93     @param data A pointer to the certificate data.
  94     @param type The certificate type as defined in cssmtype.h.
  95     @param encoding The certificate encoding as defined in cssmtype.h.
  96         @param certificate On return, a reference to the newly created certificate.
  97     @result A result code. See "Security Error Codes" (SecBase.h).
  98         @discussion This API is deprecated in 10.7  Please use the SecCertificateCreateWithData API instead.
  99 */
 100 OSStatus SecCertificateCreateFromData(const CSSM_DATA *data, CSSM_CERT_TYPE type, CSSM_CERT_ENCODING encoding, SecCertificateRef * __nonnull CF_RETURNS_RETAINED certificate)
 101         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 102
 103 /*!
 104         @function SecCertificateCreateWithData
 105         @abstract Create a certificate reference given its DER representation as a CFData.
 106     @param allocator CFAllocator to allocate the certificate data. Pass NULL to use the default allocator.
 107     @param data DER encoded X.509 certificate.
 108         @result On return, a reference to the certificate. Returns NULL if the passed-in data is not a valid DER-encoded X.509 certificate.
 109 */
 110 __nullable
 111 SecCertificateRef SecCertificateCreateWithData(CFAllocatorRef __nullable allocator, CFDataRef data)
 112         __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 113
 114 /*!
 115         @function SecCertificateAddToKeychain
 116         @abstract Adds a certificate to the specified keychain.
 117     @param certificate A reference to a certificate.
 118     @param keychain A reference to the keychain in which to add the certificate. Pass NULL to add the certificate to the default keychain.
 119     @result A result code. See "Security Error Codes" (SecBase.h).
 120         @discussion This function is successful only if the certificate was created using the SecCertificateCreateFromData or
 121         SecCertificateCreateWithData functions, and the certificate has not yet been added to the specified keychain.
 122 */
 123 OSStatus SecCertificateAddToKeychain(SecCertificateRef certificate, SecKeychainRef __nullable keychain)
 124         __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
 125
 126 /*!
 127         @function SecCertificateGetData
 128         @abstract Retrieves the data for a given certificate.
 129     @param certificate A reference to the certificate from which to retrieve the data.
 130     @param data On return, the CSSM_DATA structure pointed to by data is filled in. You must allocate the space for a CSSM_DATA structure before calling this function. This data pointer is only guaranteed to remain valid as long as the certificate remains unchanged and valid.
 131         @result A result code. See "Security Error Codes" (SecBase.h).
 132         @discussion This API is deprecated in 10.7. Please use the SecCertificateCopyData API instead.
 133 */
 134 OSStatus SecCertificateGetData(SecCertificateRef certificate, CSSM_DATA_PTR data)
 135         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 136
 137 /*!
 138         @function SecCertificateCopyData
 139         @abstract Returns the DER representation of an X.509 certificate.
 140     @param certificate A reference to a certificate.
 141         @result On return, a data reference containing the DER encoded representation of the X.509 certificate.
 142  */
 143 CFDataRef SecCertificateCopyData(SecCertificateRef certificate)
 144         __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 145
 146 /*!
 147         @function SecCertificateGetType
 148         @abstract Retrieves the type for a given certificate.
 149     @param certificate A reference to the certificate from which to obtain the type.
 150     @param certificateType On return, the certificate type of the certificate. Certificate types are defined in cssmtype.h.
 151         @result A result code. See "Security Error Codes" (SecBase.h).
 152         @discussion This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 153 */
 154 OSStatus SecCertificateGetType(SecCertificateRef certificate, CSSM_CERT_TYPE *certificateType)
 155         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 156
 157 /*!
 158     @function SecCertificateGetSubject
 159     @abstract Retrieves the subject name for a given certificate.
 160     @param certificate A reference to the certificate from which to obtain the subject name.
 161     @param subject On return, a pointer to a CSSM_X509_NAME struct which contains the subject's X.509 name (x509defs.h). This pointer remains valid until the certificate reference is released. The caller should not attempt to free this pointer.
 162     @result A result code. See "Security Error Codes" (SecBase.h).
 163     @discussion Prior to Mac OS X 10.5, this function did not return any output in the subject parameter. Your code should check the returned pointer value (in addition to the function result) before attempting to use it.
 164         For example:
 165         const CSSM_X509_NAME *subject = NULL;
 166         OSStatus status = SecCertificateGetSubject(certificate, &subject);
 167         if ( (status == errSecSuccess) && (subject != NULL) ) {
 168             // subject is valid
 169         }
 170            This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 171 */
 172 OSStatus SecCertificateGetSubject(SecCertificateRef certificate, const CSSM_X509_NAME * __nullable * __nonnull subject)
 173         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 174
 175 /*!
 176     @function SecCertificateGetIssuer
 177     @abstract Retrieves the issuer name for a given certificate.
 178     @param certificate A reference to the certificate from which to obtain the issuer name.
 179     @param issuer On return, a pointer to a CSSM_X509_NAME struct which contains the issuer's X.509 name (x509defs.h). This pointer remains valid until the certificate reference is released. The caller should not attempt to free this pointer.
 180     @result A result code. See "Security Error Codes" (SecBase.h).
 181     @discussion Prior to Mac OS X 10.5, this function did not return any output in the issuer parameter. Your code should check the returned pointer value (in addition to the function result) before attempting to use it.
 182         For example:
 183         const CSSM_X509_NAME *issuer = NULL;
 184         OSStatus status = SecCertificateGetIssuer(certificate, &issuer);
 185         if ( (status == errSecSuccess) && (issuer != NULL) ) {
 186             // issuer is valid
 187         }
 188                 This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 189 */
 190 OSStatus SecCertificateGetIssuer(SecCertificateRef certificate, const CSSM_X509_NAME * __nullable * __nonnull issuer)
 191         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 192
 193 /*!
 194     @function SecCertificateGetCLHandle
 195     @abstract Retrieves the certificate library handle for a given certificate.
 196     @param certificate A reference to the certificate from which to obtain the certificate library handle.
 197     @param clHandle On return, the certificate library handle of the given certificate. This handle remains valid at least as long as the certificate does.
 198     @result A result code. See "Security Error Codes" (SecBase.h).
 199         @discussion This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 200 */
 201 OSStatus SecCertificateGetCLHandle(SecCertificateRef certificate, CSSM_CL_HANDLE *clHandle)
 202         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 203
 204 /*!
 205     @function SecCertificateGetAlgorithmID
 206     @abstract Retrieves the algorithm identifier for a given certificate.
 207     @param certificate A reference to the certificate from which to retrieve the algorithm identifier.
 208     @param algid On return, a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER struct which identifies the algorithm for this certificate (x509defs.h). This pointer remains valid until the certificate reference is released. The caller should not attempt to free this pointer.
 209     @result A result code. See "Security Error Codes" (SecBase.h).
 210         discussion This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 211 */
 212 OSStatus SecCertificateGetAlgorithmID(SecCertificateRef certificate, const CSSM_X509_ALGORITHM_IDENTIFIER * __nullable * __nonnull algid)
 213         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 214
 215 /*!
 216     @function SecCertificateCopyPublicKey
 217     @abstract Retrieves the public key for a given certificate.
 218     @param certificate A reference to the certificate from which to retrieve the public key.
 219     @param key On return, a reference to the public key for the specified certificate. Your code must release this reference by calling the CFRelease function.
 220     @result A result code. See "Security Error Codes" (SecBase.h).
 221 */
 222 OSStatus SecCertificateCopyPublicKey(SecCertificateRef certificate, SecKeyRef * __nonnull CF_RETURNS_RETAINED key)
 223         __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
 224
 225 /*!
 226     @function SecCertificateCopyCommonName
 227     @abstract Retrieves the common name of the subject of a given certificate.
 228     @param certificate A reference to the certificate from which to retrieve the common name.
 229     @param commonName On return, a reference to the common name. Your code must release this reference by calling the CFRelease function.
 230     @result A result code. See "Security Error Codes" (SecBase.h).
 231     @discussion All the data in this string comes from the certificate itself, and thus it's in whatever language the certificate itself is in.
 232         Note that the certificate's common name field may not be present, or may be inadequate to describe the certificate; for display purposes,
 233         you should consider using SecCertificateCopySubjectSummary instead of this function.
 234 */
 235 OSStatus SecCertificateCopyCommonName(SecCertificateRef certificate, CFStringRef * __nonnull CF_RETURNS_RETAINED commonName)
 236         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 237
 238 /*!
 239         @function SecCertificateCopySubjectSummary
 240         @abstract Returns a simple string which hopefully represents a human understandable summary.
 241     @param certificate  A reference to the certificate from which to derive the subject summary string.
 242         @result On return, a reference to the subject summary string. Your code must release this reference by calling the CFRelease function.
 243     @discussion All the data in this string comes from the certificate itself, and thus it's in whatever language the certificate itself is in.
 244 */
 245 CFStringRef SecCertificateCopySubjectSummary(SecCertificateRef certificate)
 246         __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 247
 248 /*!
 249     @function SecCertificateCopyEmailAddresses
 250     @abstract Returns an array of zero or more email addresses for the subject of a given certificate.
 251     @param certificate A reference to the certificate from which to retrieve the email addresses.
 252     @param emailAddresses On return, an array of zero or more CFStringRef elements corresponding to each email address found.
 253         Your code must release this array reference by calling the CFRelease function.
 254     @result A result code. See "Security Error Codes" (SecBase.h).
 255 */
 256 OSStatus SecCertificateCopyEmailAddresses(SecCertificateRef certificate, CFArrayRef * __nonnull CF_RETURNS_RETAINED emailAddresses)
 257         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 258
 259 /*!
 260     @function SecCertificateCopyPreference
 261     @abstract Returns the preferred certificate for the specified name and key usage. If a preferred certificate does not exist for the specified name and key usage, NULL is returned.
 262     @param name A string containing an email address (RFC822) or other name for which a preferred certificate is requested.
 263     @param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to ignore this parameter.
 264     @param certificate On return, a reference to the preferred certificate, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.
 265     @result A result code. See "Security Error Codes" (SecBase.h).
 266     @discussion This function will typically be used to obtain the preferred encryption certificate for an email recipient.
 267         This API is deprecated in 10.7. Please use the SecCertificateCopyPreferred API instead.
 268 */
 269 OSStatus SecCertificateCopyPreference(CFStringRef name, uint32 keyUsage, SecCertificateRef * __nonnull CF_RETURNS_RETAINED certificate)
 270         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 271
 272 /*!
 273     @function SecCertificateCopyPreferred
 274     @abstract Returns the preferred certificate for the specified name and key usage. If a preferred certificate does not exist for the specified name and key usage, NULL is returned.
 275     @param name A string containing an email address (RFC822) or other name for which a preferred certificate is requested.
 276     @param keyUsage A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
 277     @result On return, a reference to the preferred certificate, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.
 278     @discussion This function will typically be used to obtain the preferred encryption certificate for an email recipient. If a preferred certificate has not been set
 279         for the supplied name, the returned reference will be NULL. Your code should then perform a search for possible certificates, using the SecItemCopyMatching API.
 280  */
 281 __nullable
 282 SecCertificateRef SecCertificateCopyPreferred(CFStringRef name, CFArrayRef __nullable keyUsage)
 283         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 284
 285 /*!
 286     @function SecCertificateSetPreference
 287     @abstract Sets the preferred certificate for a specified name, key usage, and date.
 288     @param certificate A reference to the certificate which will be preferred.
 289     @param name A string containing an email address (RFC822) or other name for which a preferred certificate will be associated.
 290     @param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to avoid specifying a particular key usage.
 291     @param date (optional) A date reference. If supplied, the preferred certificate will be changed only if this date is later than the currently saved setting. Pass NULL if this preference should not be restricted by date.
 292     @result A result code. See "Security Error Codes" (SecBase.h).
 293     @discussion This function will typically be used to set the preferred encryption certificate for an email recipient, either manually (when encrypting email to a recipient) or automatically upon receipt of encrypted email.
 294         This API is deprecated in 10.7. Plese use the SecCertificateSetPreferred API instead.
 295 */
 296 OSStatus SecCertificateSetPreference(SecCertificateRef certificate, CFStringRef name, uint32 keyUsage, CFDateRef __nullable date)
 297         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 298
 299 /*!
 300     @function SecCertificateSetPreferred
 301     @abstract Sets the preferred certificate for a specified name and optional key usage.
 302     @param certificate A reference to the preferred certificate. If NULL is passed, any existing preference for the specified name is cleared instead.
 303     @param name A string containing an email address (RFC822) or other name for which a preferred certificate will be associated.
 304     @param keyUsage A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
 305     @result A result code. See "Security Error Codes" (SecBase.h).
 306     @discussion This function will typically be used to set the preferred encryption certificate for an email recipient, either manually (when encrypting email to a recipient)
 307         or automatically upon receipt of encrypted email.
 308 */
 309 OSStatus SecCertificateSetPreferred(SecCertificateRef __nullable certificate, CFStringRef name, CFArrayRef __nullable keyUsage)
 310         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 311
 312 /*!
 313  @typedef SecKeyUsage
 314  @abstract Flags to indicate key usages in the KeyUsage extension of a certificate
 315  @constant kSecKeyUsageUnspecified No KeyUsage extension in certificate.
 316  @constant kSecKeyUsageDigitalSignature DigitalSignature bit set in KeyUsage extension.
 317  @constant kSecKeyUsageNonRepudiation NonRepudiation bit set in KeyUsage extension.
 318  @constant kSecKeyUsageContentCommitment ContentCommitment bit set in KeyUsage extension.
 319  @constant kSecKeyUsageKeyEncipherment KeyEncipherment bit set in KeyUsage extension.
 320  @constant kSecKeyUsageDataEncipherment DataEncipherment bit set in KeyUsage extension.
 321  @constant kSecKeyUsageKeyAgreement KeyAgreement bit set in KeyUsage extension.
 322  @constant kSecKeyUsageKeyCertSign KeyCertSign bit set in KeyUsage extension.
 323  @constant kSecKeyUsageCRLSign CRLSign bit set in KeyUsage extension.
 324  @constant kSecKeyUsageEncipherOnly EncipherOnly bit set in KeyUsage extension.
 325  @constant kSecKeyUsageDecipherOnly DecipherOnly bit set in KeyUsage extension.
 326  @constant kSecKeyUsageCritical KeyUsage extension is marked critical.
 327  @constant kSecKeyUsageAll For masking purposes, all SecKeyUsage values.
 328  */
 329 typedef CF_OPTIONS(uint32_t, SecKeyUsage) {
 330     kSecKeyUsageUnspecified      = 0,
 331     kSecKeyUsageDigitalSignature = 1 << 0,
 332     kSecKeyUsageNonRepudiation   = 1 << 1,
 333     kSecKeyUsageContentCommitment= 1 << 1,
 334     kSecKeyUsageKeyEncipherment  = 1 << 2,
 335     kSecKeyUsageDataEncipherment = 1 << 3,
 336     kSecKeyUsageKeyAgreement     = 1 << 4,
 337     kSecKeyUsageKeyCertSign      = 1 << 5,
 338     kSecKeyUsageCRLSign          = 1 << 6,
 339     kSecKeyUsageEncipherOnly     = 1 << 7,
 340     kSecKeyUsageDecipherOnly     = 1 << 8,
 341     kSecKeyUsageCritical         = 1 << 31,
 342     kSecKeyUsageAll              = 0x7FFFFFFF
 343 };
 344
 345 /*!
 346  @enum kSecPropertyKey
 347  @abstract Constants used to access dictionary entries returned by SecCertificateCopyValues
 348  @constant kSecPropertyKeyType The type of the entry
 349  @constant kSecPropertyKeyLabel The label of the entry
 350  @constant kSecPropertyKeyLocalizedLabel The localized label of the entry
 351  @constant kSecPropertyKeyValue The value of the entry
 352  */
 353
 354 extern const CFStringRef kSecPropertyKeyType __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 355 extern const CFStringRef kSecPropertyKeyLabel __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 356 extern const CFStringRef kSecPropertyKeyLocalizedLabel __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 357 extern const CFStringRef kSecPropertyKeyValue __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 358
 359 /*!
 360         @enum kSecPropertyType
 361         @abstract Public Constants for property list values returned by SecCertificateCopyValues
 362         @discussion Note that kSecPropertyTypeTitle and kSecPropertyTypeError are defined in SecTrust.h
 363 */
 364 extern const CFStringRef kSecPropertyTypeWarning __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 365 extern const CFStringRef kSecPropertyTypeSuccess __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 366 extern const CFStringRef kSecPropertyTypeSection __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 367 extern const CFStringRef kSecPropertyTypeData __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 368 extern const CFStringRef kSecPropertyTypeString __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 369 extern const CFStringRef kSecPropertyTypeURL __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 370 extern const CFStringRef kSecPropertyTypeDate __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 371
 372 /*!
 373     @function SecCertificateCopyValues
 374         @abstract               Creates a dictionary that represents a certificate's contents.
 375         @param certificate The certificate from which to get values
 376         @param keys             An array of string OID values, or NULL. If present, this is
 377                                         the subset of values from the certificate to return. If NULL,
 378                                         all values will be returned. Only OIDs that are top level keys
 379                                         in the returned dictionary can be specified. Unknown OIDs are
 380                                         ignored.
 381         @param error    An optional pointer to a CFErrorRef. This value is
 382                                         set if an error occurred.  If not NULL the caller is
 383                                         responsible for releasing the CFErrorRef.
 384         @discussion             The keys array will contain all of the keys used in the
 385                                         returned dictionary. The top level keys in the returned
 386                                         dictionary are OIDs, many of which are found in SecCertificateOIDs.h.
 387                                         Each entry that is returned is itself a dictionary with four
 388                                         entries, whose keys are kSecPropertyKeyType, kSecPropertyKeyLabel,
 389                                         kSecPropertyKeyLocalizedLabel, kSecPropertyKeyValue. The label
 390                                         entries may contain a descriptive (localized) string, or an
 391                                         OID string. The kSecPropertyKeyType describes the type in the
 392                                         value entry. The value entry may be any CFType, although it
 393                                         is usually a CFStringRef, CFArrayRef or a CFDictionaryRef.
 394 */
 395 __nullable
 396 CFDictionaryRef SecCertificateCopyValues(SecCertificateRef certificate, CFArrayRef __nullable keys, CFErrorRef *error)
 397         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 398
 399 /*!
 400     @enum Transform  Key Value Constants
 401     @discussion                 Predefined values for the kSecTransformAttrCertificateUsage attribute.
 402
 403
 404         kSecCertificateUsageSigning
 405         kSecCertificateUsageSigningAndEncrypting
 406         kSecCertificateUsageDeriveAndSign
 407
 408 */
 409
 410 extern const CFStringRef kSecCertificateUsageSigning __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 411 extern const CFStringRef kSecCertificateUsageSigningAndEncrypting __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 412 extern const CFStringRef kSecCertificateUsageDeriveAndSign __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 413
 414 /*!
 415     @function                   SecCertificateCopyLongDescription
 416         @abstract                       Return the long description of a certificate
 417         @param alloc            The CFAllocator which should be used to allocate
 418                                                 memory for the dictionary and its storage for values. This
 419                                                 parameter may be NULL in which case the current default
 420                                                 CFAllocator is used. If this reference is not a valid
 421                                                 CFAllocator, the behavior is undefined.
 422         @param certificate      The certificate from which to retrieve the long description
 423         @param  error           An optional pointer to a CFErrorRef. This value is
 424                                                 set if an error occurred.  If not NULL the caller is
 425                                                 responsible for releasing the CFErrorRef.
 426         @result                         A CFStringRef of the long description or NULL. If NULL and the error
 427                                                 parameter is supplied the error will be returned in the error parameter
 428         @discussion                     Note that the format of this string may change in the future
 429 */
 430
 431 __nullable
 432 CFStringRef SecCertificateCopyLongDescription(CFAllocatorRef __nullable alloc, SecCertificateRef certificate, CFErrorRef *error)
 433                                         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 434
 435 /*!
 436     @function                   SecCertificateCopyShortDescription
 437         @abstract                       Return the short description of a certificate
 438         @param alloc            The CFAllocator which should be used to allocate
 439                                                 memory for the dictionary and its storage for values. This
 440                                                 parameter may be NULL in which case the current default
 441                                                 CFAllocator is used. If this reference is not a valid
 442                                                 CFAllocator, the behavior is undefined.
 443         @param certificate      The certificate from which to retrieve the short description
 444         @param  error           An optional pointer to a CFErrorRef. This value is
 445                                                 set if an error occurred.  If not NULL the caller is
 446                                                 responsible for releasing the CFErrorRef.
 447         @result                         A CFStringRef of the short description or NULL. If NULL and the error
 448                                                 parameter is supplied the error will be returned in the error parameter
 449  @discussion                    Note that the format of this string may change in the future
 450 */
 451
 452 __nullable
 453 CFStringRef SecCertificateCopyShortDescription(CFAllocatorRef __nullable alloc, SecCertificateRef certificate, CFErrorRef *error)
 454                 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 455
 456 /*!
 457     @function                   SecCertificateCopySerialNumber
 458         @abstract                       Return the certificate's serial number.
 459         @param certificate      The certificate from which to get values
 460         @param  error           An optional pointer to a CFErrorRef. This value is
 461                                                 set if an error occurred.  If not NULL the caller is
 462                                                 responsible for releasing the CFErrorRef.
 463         @discussion                     Return the content of a DER-encoded integer (without the
 464                                                 tag and length fields) for this certificate's serial
 465                                                 number.   The caller must CFRelease the value returned.
 466 */
 467
 468 __nullable
 469 CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate, CFErrorRef *error)
 470                 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 471
 472 /*!
 473     @function                   SecCertificateCopyNormalizedIssuerContent
 474         @abstract                       Return the certificate's normalized issuer
 475         @param certificate      The certificate from which to get values
 476         @param error            An optional pointer to a CFErrorRef. This value is
 477                                                 set if an error occurred.  If not NULL the caller is
 478                                                 responsible for releasing the CFErrorRef.
 479         @discussion                     The issuer is a sequence in the format used by
 480                                                 SecItemCopyMatching.  The content returned is a DER-encoded
 481                                                 X.509 distinguished name. For a display version of the issuer,
 482                                                 call SecCertificateCopyValues. The caller must CFRelease
 483                                                 the value returned.
 484 */
 485
 486 __nullable
 487 CFDataRef SecCertificateCopyNormalizedIssuerContent(SecCertificateRef certificate, CFErrorRef *error)
 488                 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 489
 490 /*!
 491     @function                   SecCertificateCopyNormalizedSubjectContent
 492         @abstract                       Return the certificate's normalized subject
 493         @param certificate      The certificate from which to get values
 494         @param error            An optional pointer to a CFErrorRef. This value is
 495                                                 set if an error occurred.  If not NULL the caller is
 496                                                 responsible for releasing the CFErrorRef.
 497         @discussion                     The subject is a sequence in the format used by
 498                                                 SecItemCopyMatching. The content returned is a DER-encoded
 499                                                 X.509 distinguished name. For a display version of the subject,
 500                                                 call SecCertificateCopyValues. The caller must CFRelease
 501                                                 the value returned.
 502 */
 503
 504 __nullable
 505 CFDataRef SecCertificateCopyNormalizedSubjectContent(SecCertificateRef certificate, CFErrorRef *error)
 506                 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 507
 508 CF_IMPLICIT_BRIDGING_DISABLED
 509 CF_ASSUME_NONNULL_END
 510
 511 #if defined(__cplusplus)
 512 }
 513 #endif
 514
 515 #endif /* !_SECURITY_SECCERTIFICATE_H_ */