protocol/SecProtocolTypes.h

   1 /*
   2  * Copyright (c) 2018 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 #ifndef SecProtocolTypes_h
  25 #define SecProtocolTypes_h
  26
  27 #include <Security/SecProtocolObject.h>
  28 #include <Security/SecTrust.h>
  29 #include <Security/SecCertificate.h>
  30 #include <Security/SecIdentity.h>
  31
  32 #ifndef SEC_OBJECT_IMPL
  33 /*!
  34  * These are os_object compatible and ARC-able wrappers around existing CoreFoundation
  35  * Security types, including: SecTrustRef, SecIdentityRef, and SecCertificateRef. They allow
  36  * clients to use these types in os_object-type APIs and data structures. The underlying
  37  * CoreFoundation types may be extracted and used by clients as needed.
  38  */
  39 SEC_OBJECT_DECL(sec_trust);
  40 SEC_OBJECT_DECL(sec_identity);
  41 SEC_OBJECT_DECL(sec_certificate);
  42 #endif // !SEC_OBJECT_IMPL
  43
  44 SEC_ASSUME_NONNULL_BEGIN
  45
  46 /*!
  47  * @function sec_trust_create
  48  *
  49  * @abstract
  50  *      Create an ARC-able `sec_trust_t` instance from a `SecTrustRef`.
  51  *
  52  * @param trust
  53  *      A `SecTrustRef` instance.
  54  *
  55  * @return a `sec_trust_t` instance.
  56  */
  57 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  58 SEC_RETURNS_RETAINED _Nullable sec_trust_t
  59 sec_trust_create(SecTrustRef __nonnull trust);
  60
  61 /*!
  62  * @function sec_trust_copy_ref
  63  *
  64  * @abstract
  65  *      Copy a retained reference to the underlying `SecTrustRef` instance.
  66  *
  67  * @param trust
  68  *      A `sec_trust_t` instance.
  69  *
  70  * @return The underlying `SecTrustRef` instance.
  71  */
  72 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  73 SecTrustRef
  74 sec_trust_copy_ref(sec_trust_t __nonnull trust);
  75
  76 /*!
  77  * @function sec_identity_create
  78  *
  79  * @abstract
  80  *      Create an ARC-able `sec_identity_t` instance from a `SecIdentityRef`.
  81  *
  82  * @param identity
  83  *      A `SecIdentityRef` instance.
  84  *
  85  * @return a `sec_identity_t` instance.
  86  */
  87 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  88 SEC_RETURNS_RETAINED _Nullable sec_identity_t
  89 sec_identity_create(SecIdentityRef __nonnull identity);
  90
  91 /*!
  92  * @function sec_identity_create_with_certificates
  93  *
  94  * @abstract
  95  *      Create an ARC-able `sec_identity_t` instance from a `SecIdentityRef` and
  96  *      array of SecCertificateRef instances.
  97  *
  98  * @param identity
  99  *      A `SecIdentityRef` instance.
 100  *
 101  * @param certificates
 102  *      An array of `SecCertificateRef` instances.
 103  *
 104  * @return a `sec_identity_t` instance.
 105  */
 106 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 107 SEC_RETURNS_RETAINED _Nullable sec_identity_t
 108 sec_identity_create_with_certificates(SecIdentityRef __nonnull identity, CFArrayRef __nonnull certificates);
 109
 110 /*!
 111  * @function sec_identity_copy_ref
 112  *
 113  * @abstract
 114  *      Copy a retained reference to the underlying `SecIdentityRef` instance.
 115  *
 116  * @param identity
 117  *      A `sec_identity_t` instance.
 118  *
 119  * @return The underlying `SecIdentityRef` instance.
 120  */
 121 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 122 SecIdentityRef
 123 sec_identity_copy_ref(sec_identity_t __nonnull identity);
 124
 125 /*!
 126  * @function sec_identity_copy_certificates_ref
 127  *
 128  * @abstract
 129  *      Copy a retained reference to the underlying `CFArrayRef` container of `SecCertificateRef` types.
 130  *
 131  * @param identity
 132  *      A `sec_identity_t` instance.
 133  *
 134  * @return The underlying `CFArrayRef` container with `SecCertificateRef` instances.
 135  */
 136 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 137 CFArrayRef
 138 sec_identity_copy_certificates_ref(sec_identity_t __nonnull identity);
 139
 140 /*!
 141  * @function sec_certificate_create
 142  *
 143  * @abstract
 144  *      Create an ARC-able `sec_certificate_t` instance from a `SecCertificateRef`.
 145  *
 146  * @param certificate
 147  *      A `SecCertificateRef` instance.
 148  *
 149  * @return a `sec_certificate_t` instance.
 150  */
 151 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 152 SEC_RETURNS_RETAINED _Nullable sec_certificate_t
 153 sec_certificate_create(SecCertificateRef __nonnull certificate);
 154
 155 /*!
 156  * @function sec_certificate_copy_ref
 157  *
 158  * @abstract
 159  *      Copy a retained reference to the underlying `SecCertificateRef` instance.
 160  *
 161  * @param certificate
 162  *      A `sec_certificate_t` instance.
 163  *
 164  * @return The underlying `SecCertificateRef` instance.
 165  */
 166 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 167 SecCertificateRef
 168 sec_certificate_copy_ref(sec_certificate_t __nonnull certificate);
 169
 170 SEC_ASSUME_NONNULL_END
 171
 172 #endif // SecProtocolTypes_h