trust/headers/SecCertificate.h

   1 /*
   2  * Copyright (c) 2002-2017 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.h implement and manage a
  27     particular type of keychain item that represents a X.509 public key
  28     certificate. You can store a certificate in a keychain, but a
  29     certificate can also be a transient object.
  30
  31      You can use a certificate as a keychain item in most functions.
  32 */
  33
  34 #ifndef _SECURITY_SECCERTIFICATE_H_
  35 #define _SECURITY_SECCERTIFICATE_H_
  36
  37 #include <CoreFoundation/CFBase.h>
  38 #include <CoreFoundation/CFArray.h>
  39 #include <CoreFoundation/CFData.h>
  40 #include <CoreFoundation/CFDate.h>
  41 #include <CoreFoundation/CFError.h>
  42 #include <Availability.h>
  43 #include <AvailabilityMacros.h>
  44
  45 #include <Security/SecBase.h>
  46
  47 #if SEC_OS_OSX
  48 #define _SECURITY_VERSION_GREATER_THAN_57610_
  49
  50 #include <Security/cssmtype.h>
  51 #include <Security/x509defs.h>
  52 #endif // SEC_OS_OSX
  53
  54 __BEGIN_DECLS
  55
  56 CF_ASSUME_NONNULL_BEGIN
  57 CF_IMPLICIT_BRIDGING_ENABLED
  58
  59 /*!
  60  @function SecCertificateGetTypeID
  61  @abstract Returns the type identifier of SecCertificate instances.
  62  @result The CFTypeID of SecCertificate instances.
  63  */
  64 CFTypeID SecCertificateGetTypeID(void)
  65     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
  66
  67 /*!
  68  @function SecCertificateCreateWithData
  69  @abstract Create a certificate given it's DER representation as a CFData.
  70  @param allocator CFAllocator to allocate the certificate with.
  71  @param data DER encoded X.509 certificate.
  72  @result Return NULL if the passed-in data is not a valid DER-encoded
  73  X.509 certificate, return a SecCertificateRef otherwise.
  74  */
  75 __nullable
  76 SecCertificateRef SecCertificateCreateWithData(CFAllocatorRef __nullable allocator, CFDataRef data)
  77     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
  78
  79 /*!
  80  @function SecCertificateCopyData
  81  @abstract Return the DER representation of an X.509 certificate.
  82  @param certificate SecCertificate object created with
  83  SecCertificateCreateWithData().
  84  @result DER encoded X.509 certificate.
  85  */
  86 CFDataRef SecCertificateCopyData(SecCertificateRef certificate)
  87     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
  88
  89 /*!
  90  @function SecCertificateCopySubjectSummary
  91  @abstract Return a simple string which hopefully represents a human
  92  understandable summary.
  93  @param certificate  A reference to the certificate from which to derive
  94  the subject summary string.
  95  @discussion All the data in this string comes from the certificate itself
  96  and thus it's in whatever language the certificate itself is in.
  97  @result A CFStringRef which the caller should CFRelease() once it's no
  98  longer needed.
  99  */
 100 __nullable
 101 CFStringRef SecCertificateCopySubjectSummary(SecCertificateRef certificate)
 102     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 103
 104 /*!
 105  @function SecCertificateCopyCommonName
 106  @abstract Retrieves the common name of the subject of a given certificate.
 107  @param certificate A reference to the certificate from which to retrieve the common name.
 108  @param commonName On return, a reference to the common name. Your code must release this reference by calling the CFRelease function.
 109  @result A result code. See "Security Error Codes" (SecBase.h).
 110  @discussion All the data in this string comes from the certificate itself, and thus it's in whatever language the certificate itself is in.
 111  Note that the certificate's common name field may not be present, or may be inadequate to describe the certificate; for display purposes,
 112  you should consider using SecCertificateCopySubjectSummary instead of this function.
 113  */
 114 OSStatus SecCertificateCopyCommonName(SecCertificateRef certificate, CFStringRef * __nonnull CF_RETURNS_RETAINED commonName)
 115     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_10_3);
 116
 117 /*!
 118  @function SecCertificateCopyEmailAddresses
 119  @abstract Returns an array of zero or more email addresses for the subject of a given certificate.
 120  @param certificate A reference to the certificate from which to retrieve the email addresses.
 121  @param emailAddresses On return, an array of zero or more CFStringRef elements corresponding to each email address found.
 122  Your code must release this array reference by calling the CFRelease function.
 123  @result A result code. See "Security Error Codes" (SecBase.h).
 124  */
 125 OSStatus SecCertificateCopyEmailAddresses(SecCertificateRef certificate, CFArrayRef * __nonnull CF_RETURNS_RETAINED emailAddresses)
 126     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_10_3);
 127
 128 /*!
 129  @function SecCertificateCopyNormalizedIssuerSequence
 130  @abstract Return the certificate's normalized issuer
 131  @param certificate The certificate from which to get values
 132  @discussion The issuer is a sequence in the format used by SecItemCopyMatching.  The content returned is a DER-encoded X.509 distinguished name. For a display version of the issuer, call SecCertificateCopyValues. The caller must CFRelease the value returned.
 133  */
 134 __nullable
 135 CFDataRef SecCertificateCopyNormalizedIssuerSequence(SecCertificateRef certificate)
 136     __OSX_AVAILABLE_STARTING(__MAC_10_12_4, __IPHONE_10_3);
 137
 138 /*!
 139  @function SecCertificateCopyNormalizedSubjectSequence
 140  @abstract Return the certificate's normalized subject
 141  @param certificate The certificate from which to get values
 142  @discussion The subject is a sequence in the format used by SecItemCopyMatching. The content returned is a DER-encoded X.509 distinguished name. For a display version of the subject, call SecCertificateCopyValues. The caller must CFRelease the value returned.
 143  */
 144 __nullable
 145 CFDataRef SecCertificateCopyNormalizedSubjectSequence(SecCertificateRef certificate)
 146     __OSX_AVAILABLE_STARTING(__MAC_10_12_4, __IPHONE_10_3);
 147
 148 /*!
 149  @function SecCertificateCopyKey
 150  @abstract Retrieves the public key for a given certificate.
 151  @param certificate A reference to the certificate from which to retrieve the public key.
 152  @result A reference to the public key for the specified certificate. Your code must release this reference by calling the CFRelease function. If the public key has an encoding issue or uses an unsupported algorithm, the returned reference will be null.
 153  @discussion RSA and ECDSA public keys are supported. All other public key algorithms are unsupported.
 154  */
 155 __nullable CF_RETURNS_RETAINED
 156 SecKeyRef SecCertificateCopyKey(SecCertificateRef certificate)
 157     API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0));
 158
 159 #if TARGET_OS_IPHONE
 160 /*!
 161  @function SecCertificateCopyPublicKey
 162  @abstract Retrieves the public key for a given certificate.
 163  @param certificate A reference to the certificate from which to retrieve the public key.
 164  @result A reference to the public key for the specified certificate. Your code must release this reference by calling the CFRelease function.
 165  @discussion NOTE: Deprecated in iOS 12.0; use SecCertificateCopyKey instead for cross-platform availability.
 166  */
 167 __nullable
 168 SecKeyRef SecCertificateCopyPublicKey(SecCertificateRef certificate)
 169     API_DEPRECATED_WITH_REPLACEMENT("SecCertificateCopyKey", ios(10.3, 12.0)) API_UNAVAILABLE(macos, iosmac);
 170 #endif
 171
 172 #if TARGET_OS_OSX
 173 /*!
 174  @function SecCertificateCopyPublicKey
 175  @abstract Retrieves the public key for a given certificate.
 176  @param certificate A reference to the certificate from which to retrieve the public key.
 177  @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.
 178  @result A result code. See "Security Error Codes" (SecBase.h).
 179  @discussion NOTE: Deprecated in macOS 10.14; use SecCertificateCopyKey instead for cross-platform availability.
 180  */
 181 OSStatus SecCertificateCopyPublicKey(SecCertificateRef certificate, SecKeyRef * __nonnull CF_RETURNS_RETAINED key)
 182     API_DEPRECATED_WITH_REPLACEMENT("SecCertificateCopyKey", macos(10.3, 10.14)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos, iosmac);
 183 #endif
 184
 185 /*!
 186  @function SecCertificateCopySerialNumberData
 187  @abstract Return the certificate's serial number.
 188  @param certificate The certificate from which to get values.
 189  @param error An optional pointer to a CFErrorRef which will be set on return from the function if an error occurred. If not NULL, the caller is responsible for releasing the CFErrorRef.
 190  @discussion Return the content of a DER-encoded integer (without the tag and length fields) for this certificate's serial number. The caller must CFRelease the value returned.
 191  */
 192 __nullable
 193 CFDataRef SecCertificateCopySerialNumberData(SecCertificateRef certificate, CFErrorRef *error)
 194     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 195
 196 #if TARGET_OS_IPHONE
 197 /*!
 198  @function SecCertificateCopySerialNumber
 199  @abstract Return the certificate's serial number.
 200  @param certificate The certificate from which to get values.
 201  @discussion Return the content of a DER-encoded integer (without the tag and length fields) for this certificate's serial number. The caller must CFRelease the value returned. NOTE: Deprecated in iOS 11.0; use SecCertificateCopySerialNumberData instead for cross-platform availability.
 202  */
 203 __nullable
 204 CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate)
 205     API_DEPRECATED_WITH_REPLACEMENT("SecCertificateCopySerialNumberData", ios(10.3, 11.0)) API_UNAVAILABLE(macos, iosmac);
 206 #endif
 207
 208 #if TARGET_OS_OSX
 209 /*!
 210  @function SecCertificateCopySerialNumber
 211  @abstract Return the certificate's serial number.
 212  @param certificate The certificate from which to get values.
 213  @param error An optional pointer to a CFErrorRef which will be set on return from the function if an error occurred. If not NULL, the caller is responsible for releasing the CFErrorRef.
 214  @discussion Return the content of a DER-encoded integer (without the tag and length fields) for this certificate's serial number. The caller must CFRelease the value returned. NOTE: Deprecated in macOS 10.13; use SecCertificateCopySerialNumberData instead for cross-platform availability.
 215  */
 216 __nullable
 217 CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate, CFErrorRef *error)
 218     API_DEPRECATED_WITH_REPLACEMENT("SecCertificateCopySerialNumberData", macos(10.7, 10.13)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos, iosmac);
 219 #endif
 220
 221 /*
 222  * Legacy functions (OS X only)
 223  */
 224 #if SEC_OS_OSX
 225 /*!
 226     @enum CertificateItemAttributes
 227     @abstract Indicates the type of a certificate item attribute.
 228     @constant kSecSubjectItemAttr Indicates a DER-encoded subject distinguished name.
 229     @constant kSecIssuerItemAttr Indicates a DER-encoded issuer distinguished name.
 230     @constant kSecSerialNumberItemAttr Indicates a DER-encoded certificate serial number (without the tag and length).
 231     @constant kSecPublicKeyHashItemAttr Indicates a public key hash.
 232     @constant kSecSubjectKeyIdentifierItemAttr Indicates a subject key identifier.
 233     @constant kSecCertTypeItemAttr Indicates a certificate type.
 234     @constant kSecCertEncodingItemAttr Indicates a certificate encoding.
 235 */
 236 enum
 237 {
 238     kSecSubjectItemAttr              = 'subj',
 239     kSecIssuerItemAttr               = 'issu',
 240     kSecSerialNumberItemAttr         = 'snbr',
 241     kSecPublicKeyHashItemAttr        = 'hpky',
 242     kSecSubjectKeyIdentifierItemAttr = 'skid',
 243     kSecCertTypeItemAttr             = 'ctyp',
 244     kSecCertEncodingItemAttr         = 'cenc'
 245 } /*DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER*/;
 246
 247 #pragma mark ---- Certificate Operations ----
 248
 249 /*!
 250     @function SecCertificateCreateFromData
 251     @abstract Creates a certificate based on the input data, type, and encoding.
 252     @param data A pointer to the certificate data.
 253     @param type The certificate type as defined in cssmtype.h.
 254     @param encoding The certificate encoding as defined in cssmtype.h.
 255     @param certificate On return, a reference to the newly created certificate.
 256     @result A result code. See "Security Error Codes" (SecBase.h).
 257     @discussion This API is deprecated in 10.7  Please use the SecCertificateCreateWithData API instead.
 258 */
 259 OSStatus SecCertificateCreateFromData(const CSSM_DATA *data, CSSM_CERT_TYPE type, CSSM_CERT_ENCODING encoding, SecCertificateRef * __nonnull CF_RETURNS_RETAINED certificate)
 260     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 261
 262 /*!
 263     @function SecCertificateAddToKeychain
 264     @abstract Adds a certificate to the specified keychain.
 265     @param certificate A reference to a certificate.
 266     @param keychain A reference to the keychain in which to add the certificate. Pass NULL to add the certificate to the default keychain.
 267     @result A result code. See "Security Error Codes" (SecBase.h).
 268     @discussion This function is successful only if the certificate was created using the SecCertificateCreateFromData or
 269     SecCertificateCreateWithData functions, and the certificate has not yet been added to the specified keychain.
 270 */
 271 OSStatus SecCertificateAddToKeychain(SecCertificateRef certificate, SecKeychainRef __nullable keychain)
 272     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
 273
 274 /*!
 275     @function SecCertificateGetData
 276     @abstract Retrieves the data for a given certificate.
 277     @param certificate A reference to the certificate from which to retrieve the data.
 278     @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.
 279     @result A result code. See "Security Error Codes" (SecBase.h).
 280     @discussion This API is deprecated in 10.7. Please use the SecCertificateCopyData API instead.
 281 */
 282 OSStatus SecCertificateGetData(SecCertificateRef certificate, CSSM_DATA_PTR data)
 283     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 284
 285 /*!
 286     @function SecCertificateGetType
 287     @abstract Retrieves the type for a given certificate.
 288     @param certificate A reference to the certificate from which to obtain the type.
 289     @param certificateType On return, the certificate type of the certificate. Certificate types are defined in cssmtype.h.
 290     @result A result code. See "Security Error Codes" (SecBase.h).
 291     @discussion This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 292 */
 293 OSStatus SecCertificateGetType(SecCertificateRef certificate, CSSM_CERT_TYPE *certificateType)
 294     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 295
 296 /*!
 297     @function SecCertificateGetSubject
 298     @abstract Retrieves the subject name for a given certificate.
 299     @param certificate A reference to the certificate from which to obtain the subject name.
 300     @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.
 301     @result A result code. See "Security Error Codes" (SecBase.h).
 302     @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.
 303         For example:
 304         const CSSM_X509_NAME *subject = NULL;
 305         OSStatus status = SecCertificateGetSubject(certificate, &subject);
 306         if ( (status == errSecSuccess) && (subject != NULL) ) {
 307             // subject is valid
 308         }
 309        This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 310 */
 311 OSStatus SecCertificateGetSubject(SecCertificateRef certificate, const CSSM_X509_NAME * __nullable * __nonnull subject)
 312     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 313
 314 /*!
 315     @function SecCertificateGetIssuer
 316     @abstract Retrieves the issuer name for a given certificate.
 317     @param certificate A reference to the certificate from which to obtain the issuer name.
 318     @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.
 319     @result A result code. See "Security Error Codes" (SecBase.h).
 320     @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.
 321         For example:
 322         const CSSM_X509_NAME *issuer = NULL;
 323         OSStatus status = SecCertificateGetIssuer(certificate, &issuer);
 324         if ( (status == errSecSuccess) && (issuer != NULL) ) {
 325             // issuer is valid
 326         }
 327         This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 328 */
 329 OSStatus SecCertificateGetIssuer(SecCertificateRef certificate, const CSSM_X509_NAME * __nullable * __nonnull issuer)
 330     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 331
 332 /*!
 333     @function SecCertificateGetCLHandle
 334     @abstract Retrieves the certificate library handle for a given certificate.
 335     @param certificate A reference to the certificate from which to obtain the certificate library handle.
 336     @param clHandle On return, the certificate library handle of the given certificate. This handle remains valid at least as long as the certificate does.
 337     @result A result code. See "Security Error Codes" (SecBase.h).
 338     @discussion This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 339 */
 340 OSStatus SecCertificateGetCLHandle(SecCertificateRef certificate, CSSM_CL_HANDLE *clHandle)
 341     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 342
 343 /*!
 344     @function SecCertificateGetAlgorithmID
 345     @abstract Retrieves the algorithm identifier for a given certificate.
 346     @param certificate A reference to the certificate from which to retrieve the algorithm identifier.
 347     @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.
 348     @result A result code. See "Security Error Codes" (SecBase.h).
 349     discussion This API is deprecated in 10.7. Please use the SecCertificateCopyValues API instead.
 350 */
 351 OSStatus SecCertificateGetAlgorithmID(SecCertificateRef certificate, const CSSM_X509_ALGORITHM_IDENTIFIER * __nullable * __nonnull algid)
 352     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 353
 354 /*!
 355     @function SecCertificateCopyPreference
 356     @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.
 357     @param name A string containing an email address (RFC822) or other name for which a preferred certificate is requested.
 358     @param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to ignore this parameter.
 359     @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.
 360     @result A result code. See "Security Error Codes" (SecBase.h).
 361     @discussion This function will typically be used to obtain the preferred encryption certificate for an email recipient.
 362     This API is deprecated in 10.7. Please use the SecCertificateCopyPreferred API instead.
 363 */
 364 OSStatus SecCertificateCopyPreference(CFStringRef name, uint32 keyUsage, SecCertificateRef * __nonnull CF_RETURNS_RETAINED certificate)
 365     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 366
 367 /*!
 368     @function SecCertificateCopyPreferred
 369     @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.
 370     @param name A string containing an email address (RFC822) or other name for which a preferred certificate is requested.
 371     @param keyUsage A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
 372     @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.
 373     @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
 374     for the supplied name, the returned reference will be NULL. Your code should then perform a search for possible certificates, using the SecItemCopyMatching API.
 375  */
 376 __nullable
 377 SecCertificateRef SecCertificateCopyPreferred(CFStringRef name, CFArrayRef __nullable keyUsage)
 378     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 379
 380 /*!
 381     @function SecCertificateSetPreference
 382     @abstract Sets the preferred certificate for a specified name, key usage, and date.
 383     @param certificate A reference to the certificate which will be preferred.
 384     @param name A string containing an email address (RFC822) or other name for which a preferred certificate will be associated.
 385     @param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to avoid specifying a particular key usage.
 386     @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.
 387     @result A result code. See "Security Error Codes" (SecBase.h).
 388     @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.
 389     This API is deprecated in 10.7. Plese use the SecCertificateSetPreferred API instead.
 390 */
 391 OSStatus SecCertificateSetPreference(SecCertificateRef certificate, CFStringRef name, uint32 keyUsage, CFDateRef __nullable date)
 392     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 393
 394 /*!
 395     @function SecCertificateSetPreferred
 396     @abstract Sets the preferred certificate for a specified name and optional key usage.
 397     @param certificate A reference to the preferred certificate. If NULL is passed, any existing preference for the specified name is cleared instead.
 398     @param name A string containing an email address (RFC822) or other name for which a preferred certificate will be associated.
 399     @param keyUsage A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
 400     @result A result code. See "Security Error Codes" (SecBase.h).
 401     @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)
 402     or automatically upon receipt of encrypted email.
 403 */
 404 OSStatus SecCertificateSetPreferred(SecCertificateRef __nullable certificate, CFStringRef name, CFArrayRef __nullable keyUsage)
 405     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 406
 407 /*!
 408  @typedef SecKeyUsage
 409  @abstract Flags to indicate key usages in the KeyUsage extension of a certificate
 410  @constant kSecKeyUsageUnspecified No KeyUsage extension in certificate.
 411  @constant kSecKeyUsageDigitalSignature DigitalSignature bit set in KeyUsage extension.
 412  @constant kSecKeyUsageNonRepudiation NonRepudiation bit set in KeyUsage extension.
 413  @constant kSecKeyUsageContentCommitment ContentCommitment bit set in KeyUsage extension.
 414  @constant kSecKeyUsageKeyEncipherment KeyEncipherment bit set in KeyUsage extension.
 415  @constant kSecKeyUsageDataEncipherment DataEncipherment bit set in KeyUsage extension.
 416  @constant kSecKeyUsageKeyAgreement KeyAgreement bit set in KeyUsage extension.
 417  @constant kSecKeyUsageKeyCertSign KeyCertSign bit set in KeyUsage extension.
 418  @constant kSecKeyUsageCRLSign CRLSign bit set in KeyUsage extension.
 419  @constant kSecKeyUsageEncipherOnly EncipherOnly bit set in KeyUsage extension.
 420  @constant kSecKeyUsageDecipherOnly DecipherOnly bit set in KeyUsage extension.
 421  @constant kSecKeyUsageCritical KeyUsage extension is marked critical.
 422  @constant kSecKeyUsageAll For masking purposes, all SecKeyUsage values.
 423  */
 424 typedef CF_OPTIONS(uint32_t, SecKeyUsage) {
 425     kSecKeyUsageUnspecified      = 0u,
 426     kSecKeyUsageDigitalSignature = 1u << 0,
 427     kSecKeyUsageNonRepudiation   = 1u << 1,
 428     kSecKeyUsageContentCommitment= 1u << 1,
 429     kSecKeyUsageKeyEncipherment  = 1u << 2,
 430     kSecKeyUsageDataEncipherment = 1u << 3,
 431     kSecKeyUsageKeyAgreement     = 1u << 4,
 432     kSecKeyUsageKeyCertSign      = 1u << 5,
 433     kSecKeyUsageCRLSign          = 1u << 6,
 434     kSecKeyUsageEncipherOnly     = 1u << 7,
 435     kSecKeyUsageDecipherOnly     = 1u << 8,
 436     kSecKeyUsageCritical         = 1u << 31,
 437     kSecKeyUsageAll              = 0x7FFFFFFFu
 438 };
 439
 440 /*!
 441  @enum kSecPropertyKey
 442  @abstract Constants used to access dictionary entries returned by SecCertificateCopyValues
 443  @constant kSecPropertyKeyType The type of the entry
 444  @constant kSecPropertyKeyLabel The label of the entry
 445  @constant kSecPropertyKeyLocalizedLabel The localized label of the entry
 446  @constant kSecPropertyKeyValue The value of the entry
 447  */
 448
 449 extern const CFStringRef kSecPropertyKeyType __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 450 extern const CFStringRef kSecPropertyKeyLabel __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 451 extern const CFStringRef kSecPropertyKeyLocalizedLabel __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 452 extern const CFStringRef kSecPropertyKeyValue __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 453
 454 /*!
 455     @enum kSecPropertyType
 456     @abstract Public Constants for property list values returned by SecCertificateCopyValues
 457     @discussion Note that kSecPropertyTypeTitle and kSecPropertyTypeError are defined in SecTrust.h
 458 */
 459 extern const CFStringRef kSecPropertyTypeWarning __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 460 extern const CFStringRef kSecPropertyTypeSuccess __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 461 extern const CFStringRef kSecPropertyTypeSection __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 462 extern const CFStringRef kSecPropertyTypeData __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 463 extern const CFStringRef kSecPropertyTypeString __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 464 extern const CFStringRef kSecPropertyTypeURL __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 465 extern const CFStringRef kSecPropertyTypeDate __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 466 extern const CFStringRef kSecPropertyTypeArray API_AVAILABLE(macos(10.15)) SPI_AVAILABLE(ios(13.0), watchos(6.0), tvos(13.0), iosmac(13.0));
 467 extern const CFStringRef kSecPropertyTypeNumber API_AVAILABLE(macos(10.15)) SPI_AVAILABLE(ios(13.0), watchos(6.0), tvos(13.0), iosmac(13.0));
 468
 469 /*!
 470     @function SecCertificateCopyValues
 471     @abstract        Creates a dictionary that represents a certificate's contents.
 472     @param certificate The certificate from which to get values
 473     @param keys        An array of string OID values, or NULL. If present, this is
 474                     the subset of values from the certificate to return. If NULL,
 475                     all values will be returned. Only OIDs that are top level keys
 476                     in the returned dictionary can be specified. Unknown OIDs are
 477                     ignored.
 478     @param error    An optional pointer to a CFErrorRef. This value is
 479                     set if an error occurred.  If not NULL the caller is
 480                     responsible for releasing the CFErrorRef.
 481     @discussion        The keys array will contain all of the keys used in the
 482                     returned dictionary. The top level keys in the returned
 483                     dictionary are OIDs, many of which are found in SecCertificateOIDs.h.
 484                     Each entry that is returned is itself a dictionary with four
 485                     entries, whose keys are kSecPropertyKeyType, kSecPropertyKeyLabel,
 486                     kSecPropertyKeyLocalizedLabel, kSecPropertyKeyValue. The label
 487                     entries may contain a descriptive (localized) string, or an
 488                     OID string. The kSecPropertyKeyType describes the type in the
 489                     value entry. The value entry may be any CFType, although it
 490                     is usually a CFStringRef, CFArrayRef or a CFDictionaryRef.
 491 */
 492 __nullable
 493 CFDictionaryRef SecCertificateCopyValues(SecCertificateRef certificate, CFArrayRef __nullable keys, CFErrorRef *error)
 494     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 495
 496 /*!
 497     @function             SecCertificateCopyLongDescription
 498     @abstract            Return the long description of a certificate
 499     @param alloc         The CFAllocator which should be used to allocate
 500                         memory for the dictionary and its storage for values. This
 501                         parameter may be NULL in which case the current default
 502                         CFAllocator is used. If this reference is not a valid
 503                         CFAllocator, the behavior is undefined.
 504     @param certificate    The certificate from which to retrieve the long description
 505     @param    error        An optional pointer to a CFErrorRef. This value is
 506                         set if an error occurred.  If not NULL the caller is
 507                         responsible for releasing the CFErrorRef.
 508     @result                A CFStringRef of the long description or NULL. If NULL and the error
 509                         parameter is supplied the error will be returned in the error parameter
 510     @discussion            Note that the format of this string may change in the future
 511 */
 512
 513 __nullable
 514 CFStringRef SecCertificateCopyLongDescription(CFAllocatorRef __nullable alloc, SecCertificateRef certificate, CFErrorRef *error)
 515     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 516
 517 /*!
 518     @function             SecCertificateCopyShortDescription
 519     @abstract            Return the short description of a certificate
 520     @param alloc         The CFAllocator which should be used to allocate
 521                         memory for the dictionary and its storage for values. This
 522                         parameter may be NULL in which case the current default
 523                         CFAllocator is used. If this reference is not a valid
 524                         CFAllocator, the behavior is undefined.
 525     @param certificate    The certificate from which to retrieve the short description
 526     @param    error        An optional pointer to a CFErrorRef. This value is
 527                         set if an error occurred.  If not NULL the caller is
 528                         responsible for releasing the CFErrorRef.
 529     @result                A CFStringRef of the short description or NULL. If NULL and the error
 530                         parameter is supplied the error will be returned in the error parameter
 531  @discussion            Note that the format of this string may change in the future
 532 */
 533
 534 __nullable
 535 CFStringRef SecCertificateCopyShortDescription(CFAllocatorRef __nullable alloc, SecCertificateRef certificate, CFErrorRef *error)
 536         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 537
 538 /*!
 539     @function            SecCertificateCopyNormalizedIssuerContent
 540     @abstract            Return the certificate's normalized issuer
 541     @param certificate    The certificate from which to get values
 542     @param error        An optional pointer to a CFErrorRef. This value is
 543                         set if an error occurred.  If not NULL the caller is
 544                         responsible for releasing the CFErrorRef.
 545     @discussion            The issuer is a sequence in the format used by
 546                         SecItemCopyMatching.  The content returned is a DER-encoded
 547                         X.509 distinguished name. For a display version of the issuer,
 548                         call SecCertificateCopyValues. The caller must CFRelease
 549                         the value returned.
 550 */
 551
 552 __nullable
 553 CFDataRef SecCertificateCopyNormalizedIssuerContent(SecCertificateRef certificate, CFErrorRef *error)
 554         __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_7, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateCopyNormalizedIssuerContent is deprecated. Use SecCertificateCopyNormalizedIssuerSequence instead.");
 555
 556 /*!
 557     @function           SecCertificateCopyNormalizedSubjectContent
 558     @abstract           Return the certificate's normalized subject
 559     @param certificate  The certificate from which to get values
 560     @param error        An optional pointer to a CFErrorRef. This value is
 561                         set if an error occurred.  If not NULL the caller is
 562                         responsible for releasing the CFErrorRef.
 563     @discussion         The subject is a sequence in the format used by
 564                         SecItemCopyMatching. The content returned is a DER-encoded
 565                         X.509 distinguished name. For a display version of the subject,
 566                         call SecCertificateCopyValues. The caller must CFRelease
 567                         the value returned.
 568 */
 569
 570 __nullable
 571 CFDataRef SecCertificateCopyNormalizedSubjectContent(SecCertificateRef certificate, CFErrorRef *error)
 572         __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_7, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateCopyNormalizedSubjectContent is deprecated. Use SecCertificateCopyNormalizedSubjectSequence instead.");
 573
 574
 575 #endif /* SEC_OS_OSX */
 576
 577 CF_IMPLICIT_BRIDGING_DISABLED
 578 CF_ASSUME_NONNULL_END
 579
 580 __END_DECLS
 581
 582 #endif /* !_SECURITY_SECCERTIFICATE_H_ */