1/*
2 * Copyright (c) 2006-2010 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 SecCodeSigner
26	SecCodeSigner represents an object that can sign code.
27*/
28#ifndef _H_SECCODESIGNER
29#define _H_SECCODESIGNER
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35#include <Security/CSCommon.h>
36
37/*!
38	@typedef SecCodeSignerRef
39	This is the type of a reference to a code requirement.
40*/
41typedef struct __SecCodeSigner *SecCodeSignerRef;	/* code signing object */
42
43
44/*!
45	@function SecCodeGetTypeID
46	Returns the type identifier of all SecCodeSigner instances.
47*/
48CFTypeID SecCodeSignerGetTypeID(void);
49
50
51/*!
52	The following CFString constants can be used as keys in the parameters argument
53	of SecCodeSignerCreate to specify various modes and options of the signing operation.
54	Passing any keys not specified here may lead to undefined behavior and is not supported.
55	The same applies to passing objects of types not explicitly allowed here.
56
57	@constant kSecCodeSignerDetached Determines where the signature is written.
58		If this key is absent, the code being signed is modified to contain the signature,
59		replacing any signature already embedded there.
60		If the value is kCFNull, the signature is written to the system-wide detached
61		signature database. (You must have root privileges to write there.)
62		If the value of this key is a CFURL, the signature is written to a file at that location,
63		replacing any data there.
64		If the value is a CFMutableData, the signature is appended to that data.
65	@constant kSecCodeSignerDryRun A boolean value. If present and true, the actual writing
66		of the signature is inhibited, and the code is not modified, but all operations
67		leading up to this are performed normally, including the cryptographic access to
68		the signing identity (if any).
69	@constant kSecCodeSignerFlags A CFNumber specifying which flags to set in the code signature.
70		Note that depending on circumstances, this value may be augmented or modified
71		as part of the signing operation.
72	@constant kSecCodeSignerIdentifier If present, a CFString that explicitly specifies
73		the unique identifier string sealed into the code signature. If absent, the identifier
74		is derived implicitly from the code being signed.
75	@constant kSecCodeSignerIdentifierPrefix If the unique identifier string of the code signature
76		is implicitly generated, and the resulting string does not contain any "." (dot)
77		characters, then the (string) value of this parameter is prepended to the identifier.
78		By convention, the prefix is usually of the form "com.yourcompany.", but any value
79		is acceptable. If the kSecCodeSignerIdentifier parameter is specified, this parameter
80		is ineffective (but still allowed).
81	@constant kSecCodeSignerIdentity A SecIdentityRef describing the signing identity
82		to use for signing code. This is a mandatory parameter for signing operations.
83		Its value must be either a SecIdentityRef specifying a cryptographic identity
84		valid for Code Signing, or the special value kCFNull to indicate ad-hoc signing.
85	@constant kSecCodeSignerOperation The type of operation to be performed. Valid values
86		are kSecCodeSignerOperationSign to sign code, and kSecCodeSignerOperationRemove
87		to remove any existing signature from code. The default operation is to sign code.
88	@constant kSecCodeSignerPageSize An integer value explicitly specifying the page size
89		used to sign the main executable. This must be a power of two. A value of zero indicates
90		infinite size (no paging).
91		Only certain page sizes are allowed in most circumstances, and specifying an inappropriate
92		size will lead to spurious verification failures. This is for expert use only.
93	@constant kSecCodeSignerRequirements Specifies the internal requirements to be sealed into
94		the code signature. Must be either a CFData containing the binary (compiled) form of
95		a requirements set (SuperBlob), or a CFString containing a valid text form to be
96		compiled into binary form. Default requirements are automatically generated if this
97		parameter is omitted, and defaults may be applied to particular requirement types
98		that are not specified; but any requirement type you specify is sealed exactly as
99		specified.
100	@constant kSecCodeSignerResourceRules A CFDictionary containing resource scanning rules
101		determining what resource files are sealed into the signature (and in what way).
102		A situation-dependent default is applied if this parameter is not specified.
103	@constant kSecCodeSignerSDKRoot A CFURLRef indicating an alterate directory root
104		where signing operations should find subcomponents (libraries, frameworks, modules, etc.).
105		The default is the host system root "/".
106	@constant kSecCodeSignerSigningTime Specifies what date and time is sealed into the
107		code signature's CMS data. Can be either a CFDate object specifying a date, or
108		the value kCFNull indicating that no date should be included in the signature.
109		If not specified, the current date is chosen and sealed.
110		Since an ad-hoc signature has no CMS data, this argument is ineffective
111		for ad-hoc signing operations.
112	@constant kSecCodeSignerRequireTimestamp A CFBoolean indicating (if kCFBooleanTrue) that
113		the code signature should be certified by a timestamp authority service. This option
114		requires access to a timestamp server (usually over the Internet). If requested and
115		the timestamp server cannot be contacted or refuses service, the signing operation fails.
116		The timestamp value is not under the caller's control.
117		If the value is kCFBooleanFalse, no timestamp service is contacted and the resulting signature
118		has no certified timestamp.
119		If this key is omitted, a default is used that may vary from release to release.
120		Note that when signing multi-architectural ("fat") programs, each architecture will
121		be signed separately, and thus each architecture will have a slightly different timestamp.
122	@constant kSecCodeSignerTimestampServer A CFURL specifying which timestamp authority service
123		to contact for timestamping if requested by the kSecCodeSignerRequireTimestamp argument.
124		If omitted (and timestamping is performed), a system-defined default value is used, referring
125		to an Apple-operated timestamp service. Note that this service may not freely serve all requests.
126	@constant kSecCodeSignerTimestampAuthentication A SecIdentityRef describing the identity
127        used to authenticate to the timestamp authority server, if the server requires client-side
128		(SSL/TLS) authentication. This will not generally be the identity used to sign the actual
129		code, depending on the requirements of the timestamp authority service used.
130		If omitted, the timestamp server is contacted using unauthenticated HTTP requests.
131	@constant kSecCodeSignerTimestampOmitCertificates A CFBoolean indicating (if kCFBooleanTrue)
132		that the timestamp embedded in the signature, if requested, not contain the full certificate chain
133		of the timestamp service used. This will make for a marginally smaller signature, but may not
134		verify correctly unless all such certificates are available (through the keychain system)
135		on the verifying system.
136		The default is to embed enough certificates to ensure proper verification of Apple-generated
137		timestamp signatures.
138 */
139extern const CFStringRef kSecCodeSignerApplicationData;
140extern const CFStringRef kSecCodeSignerDetached;
141extern const CFStringRef kSecCodeSignerDigestAlgorithm;
142extern const CFStringRef kSecCodeSignerDryRun;
143extern const CFStringRef kSecCodeSignerEntitlements;
144extern const CFStringRef kSecCodeSignerFlags;
145extern const CFStringRef kSecCodeSignerIdentifier;
146extern const CFStringRef kSecCodeSignerIdentifierPrefix;
147extern const CFStringRef kSecCodeSignerIdentity;
148extern const CFStringRef kSecCodeSignerPageSize;
149extern const CFStringRef kSecCodeSignerRequirements;
150extern const CFStringRef kSecCodeSignerResourceRules;
151extern const CFStringRef kSecCodeSignerSDKRoot;
152extern const CFStringRef kSecCodeSignerSigningTime;
153extern const CFStringRef kSecCodeSignerTimestampAuthentication;
154extern const CFStringRef kSecCodeSignerRequireTimestamp;
155extern const CFStringRef kSecCodeSignerTimestampServer;
156extern const CFStringRef kSecCodeSignerTimestampOmitCertificates;
157extern const CFStringRef kSecCodeSignerPreserveMetadata;
158extern const CFStringRef kSecCodeSignerTeamIdentifier;
159
160enum {
161    kSecCodeSignerPreserveIdentifier = 1 << 0,		// preserve signing identifier
162    kSecCodeSignerPreserveRequirements = 1 << 1,	// preserve internal requirements (including DR)
163    kSecCodeSignerPreserveEntitlements = 1 << 2,	// preserve entitlements
164    kSecCodeSignerPreserveResourceRules = 1 << 3,	// preserve resource rules (and thus resources)
165    kSecCodeSignerPreserveFlags = 1 << 4,			// preserve signing flags
166    kSecCodeSignerPreserveTeamIdentifier = 1 << 5,  // preserve team identifier flags
167};
168
169
170/*!
171	@function SecCodeSignerCreate
172	Create a (new) SecCodeSigner object to be used for signing code.
173
174	@param parameters An optional CFDictionary containing parameters that influence
175		signing operations with the newly created SecCodeSigner. If NULL, defaults
176		are applied to all parameters; note however that some parameters do not have
177		useful defaults, and will need to be set before signing is attempted.
178	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
179		The kSecCSRemoveSignature flag requests that any existing signature be stripped
180		from the target code instead of signing.
181	@param staticCode On successful return, a SecStaticCode object reference representing
182	the file system origin of the given SecCode. On error, unchanged.
183	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
184	CSCommon.h or certain other Security framework headers.
185*/
186enum {
187	kSecCSRemoveSignature = 1 << 0,		// strip existing signature
188	kSecCSSignPreserveSignature = 1 << 1, // do not (re)sign if an embedded signature is already present
189	kSecCSSignNestedCode = 1 << 2,		// recursive (deep) signing
190	kSecCSSignOpaque = 1 << 3,			// treat all files as resources (no nest scan, no flexibility)
191	kSecCSSignV1 = 1 << 4,				// sign ONLY in V1 form
192	kSecCSSignNoV1 = 1 << 5,			// do not include V1 form
193	kSecCSSignBundleRoot = 1 << 6,		// include files in bundle root
194	kSecCSSignStrictPreflight = 1 << 7, // fail signing operation if signature would fail strict validation
195};
196
197
198OSStatus SecCodeSignerCreate(CFDictionaryRef parameters, SecCSFlags flags,
199	SecCodeSignerRef *signer);
200
201
202/*!
203	@function SecCodeSignerAddSignature
204	Create a code signature and add it to the StaticCode object being signed.
205
206	@param signer A SecCodeSigner object containing all the information required
207	to sign code.
208	@param code A valid SecStaticCode object reference representing code files
209	on disk. This code will be signed, and will ordinarily be modified to contain
210	the resulting signature data.
211	@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
212	@param errors An optional pointer to a CFErrorRef variable. If the call fails
213	(and something other than errSecSuccess is returned), and this argument is non-NULL,
214	a CFErrorRef is stored there further describing the nature and circumstances
215	of the failure. The caller must CFRelease() this error object when done with it.
216	@result Upon success, errSecSuccess. Upon error, an OSStatus value documented in
217	CSCommon.h or certain other Security framework headers.
218*/
219OSStatus SecCodeSignerAddSignature(SecCodeSignerRef signer,
220	SecStaticCodeRef code, SecCSFlags flags);
221
222OSStatus SecCodeSignerAddSignatureWithErrors(SecCodeSignerRef signer,
223	SecStaticCodeRef code, SecCSFlags flags, CFErrorRef *errors);
224
225
226#ifdef __cplusplus
227}
228#endif
229
230#endif //_H_SECCODESIGNER
231