2 * Copyright (c) 2006-2012 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
25 @header SecCertificatePriv
26 The functions provided in SecCertificatePriv.h implement and manage a particular
27 type of keychain item that represents a certificate. You can store a
28 certificate in a keychain, but a certificate can also be a transient
31 You can use a certificate as a keychain item in most functions.
32 Certificates are able to compute their parent certificates, and much more.
35 #ifndef _SECURITY_SECCERTIFICATEPRIV_H_
36 #define _SECURITY_SECCERTIFICATEPRIV_H_
38 #include <Security/SecCertificate.h>
39 #include <CoreFoundation/CFArray.h>
40 #include <CoreFoundation/CFData.h>
41 #include <CoreFoundation/CFDate.h>
42 #include <CoreFoundation/CFDictionary.h>
43 #include <CoreFoundation/CFError.h>
49 typedef uint32_t SecKeyUsage
;
51 kSecKeyUsageUnspecified
= 0,
52 kSecKeyUsageDigitalSignature
= 1 << 0,
53 kSecKeyUsageNonRepudiation
= 1 << 1,
54 kSecKeyUsageContentCommitment
= 1 << 1,
55 kSecKeyUsageKeyEncipherment
= 1 << 2,
56 kSecKeyUsageDataEncipherment
= 1 << 3,
57 kSecKeyUsageKeyAgreement
= 1 << 4,
58 kSecKeyUsageKeyCertSign
= 1 << 5,
59 kSecKeyUsageCRLSign
= 1 << 6,
60 kSecKeyUsageEncipherOnly
= 1 << 7,
61 kSecKeyUsageDecipherOnly
= 1 << 8,
62 kSecKeyUsageCritical
= 1 << 31,
63 kSecKeyUsageAll
= 0x7FFFFFFF
66 typedef uint32_t SecCertificateEscrowRootType
;
68 kSecCertificateBaselineEscrowRoot
= 0,
69 kSecCertificateProductionEscrowRoot
= 1,
72 /* The names of the files that contain the escrow certificates */
73 extern CFTypeRef kSecCertificateProductionEscrowKey
;
74 extern CFTypeRef kSecCertificateEscrowFileName
;
77 /* Return a certificate for the DER representation of this certificate.
78 Return NULL if the passed-in data is not a valid DER-encoded X.509
80 SecCertificateRef
SecCertificateCreateWithBytes(CFAllocatorRef allocator
,
81 const UInt8
*bytes
, CFIndex length
);
83 /* Return the length of the DER representation of this certificate. */
84 CFIndex
SecCertificateGetLength(SecCertificateRef certificate
);
86 /* Return the bytes of the DER representation of this certificate. */
87 const UInt8
*SecCertificateGetBytePtr(SecCertificateRef certificate
);
90 // MARK: Certificate Accessors
92 CFDataRef
SecCertificateGetSHA1Digest(SecCertificateRef certificate
);
94 CFDataRef
SecCertificateCopyIssuerSHA1Digest(SecCertificateRef certificate
);
96 CFDataRef
SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate
);
99 @function SecCertificateCopyIssuerSummary
100 @abstract Return a simple string which hopefully represents a human understandable issuer.
101 @param certificate SecCertificate object created with SecCertificateCreateWithData().
102 @discussion All the data in this string comes from the certificate itself
103 and thus it's in whatever language the certificate itself is in.
104 @result A CFStringRef which the caller should CFRelease() once it's no longer needed.
106 CFStringRef
SecCertificateCopyIssuerSummary(SecCertificateRef certificate
);
109 @function SecCertificateCopyProperties
110 @abstract Return a property array for this trust certificate.
111 @param certificate A reference to the certificate to evaluate.
112 @result A property array. It is the caller's responsability to CFRelease
113 the returned array when it is no longer needed.
114 See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
115 Unlike that function call this function returns a detailed description
116 of the certificate in question.
118 CFArrayRef
SecCertificateCopyProperties(SecCertificateRef certificate
);
120 CFMutableArrayRef
SecCertificateCopySummaryProperties(
121 SecCertificateRef certificate
, CFAbsoluteTime verifyTime
);
123 /* Return the content of a DER-encoded integer (without the tag and length
124 fields) for this certificate's serial number. The caller must CFRelease
125 the value returned. */
126 CFDataRef
SecCertificateCopySerialNumber(SecCertificateRef certificate
);
128 /* Return an array of CFStringRefs representing the ip addresses in the
129 certificate if any. */
130 CFArrayRef
SecCertificateCopyIPAddresses(SecCertificateRef certificate
);
132 /* Return an array of CFStringRefs representing the dns addresses in the
133 certificate if any. */
134 CFArrayRef
SecCertificateCopyDNSNames(SecCertificateRef certificate
);
136 /* Return an array of CFStringRefs representing the email addresses in the
137 certificate if any. */
138 CFArrayRef
SecCertificateCopyRFC822Names(SecCertificateRef certificate
);
140 /* Return an array of CFStringRefs representing the common names in the
141 certificates subject if any. */
142 CFArrayRef
SecCertificateCopyCommonNames(SecCertificateRef certificate
);
144 /* Return an array of CFStringRefs representing the organization in the
145 certificate's subject if any. */
146 CFArrayRef
SecCertificateCopyOrganization(SecCertificateRef certificate
);
148 /* Return an array of CFStringRefs representing the organizational unit in the
149 certificate's subject if any. */
150 CFArrayRef
SecCertificateCopyOrganizationalUnit(SecCertificateRef certificate
);
152 /* Return an array of CFStringRefs representing the NTPrincipalNames in the
153 certificate if any. */
154 CFArrayRef
SecCertificateCopyNTPrincipalNames(SecCertificateRef certificate
);
156 /* Return a string formatted according to RFC 2253 representing the complete
157 subject of certificate. */
158 CFStringRef
SecCertificateCopySubjectString(SecCertificateRef certificate
);
160 /* Return a string with the company name of an ev leaf certificate. */
161 CFStringRef
SecCertificateCopyCompanyName(SecCertificateRef certificate
);
163 /* X.509 Certificate Version: 1, 2 or 3. */
164 CFIndex
SecCertificateVersion(SecCertificateRef certificate
);
165 CFAbsoluteTime
SecCertificateNotValidBefore(SecCertificateRef certificate
);
166 CFAbsoluteTime
SecCertificateNotValidAfter(SecCertificateRef certificate
);
168 /* Return true iff certificate is self signed and has a basic constraints
169 extension indicating that it's a certificate authority. */
170 bool SecCertificateIsSelfSignedCA(SecCertificateRef certificate
);
172 SecKeyUsage
SecCertificateGetKeyUsage(SecCertificateRef certificate
);
174 /* Returns an array of CFDataRefs for all extended key usage oids or NULL */
175 CFArrayRef
SecCertificateCopyExtendedKeyUsage(SecCertificateRef certificate
);
177 /* Returns a certificate from a pem blob */
178 SecCertificateRef
SecCertificateCreateWithPEM(CFAllocatorRef allocator
,
179 CFDataRef pem_certificate
);
181 /* Append certificate to xpc_certificates. */
182 bool SecCertificateAppendToXPCArray(SecCertificateRef certificate
, xpc_object_t xpc_certificates
, CFErrorRef
*error
);
184 /* Decode certificate from xpc_certificates[index] as encoded by SecCertificateAppendToXPCArray(). */
185 SecCertificateRef
SecCertificateCreateWithXPCArrayAtIndex(xpc_object_t xpc_certificates
, size_t index
, CFErrorRef
*error
);
187 /* Retrieve the array of valid Escrow certificates for a given root type */
188 CFArrayRef
SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType
);
190 /* Return an xpc_array of data from an array of SecCertificateRefs. */
191 xpc_object_t
SecCertificateArrayCopyXPCArray(CFArrayRef certificates
, CFErrorRef
*error
);
193 /* Return an array of SecCertificateRefs from a xpc_object array of datas. */
194 CFArrayRef
SecCertificateXPCArrayCopyArray(xpc_object_t xpc_certificates
, CFErrorRef
*error
);
198 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */