/*
- * Copyright (c) 2006 Apple Computer, Inc. All Rights Reserved.
+ * Copyright (c) 2006-2010 Apple Inc. All Rights Reserved.
*
* @APPLE_LICENSE_HEADER_START@
*
/*!
@header SecCodeSigner
- SecCodeSigner represents an object that signs code.
+ SecCodeSigner represents an object that can sign code.
*/
#ifndef _H_SECCODESIGNER
#define _H_SECCODESIGNER
/*!
@function SecCodeGetTypeID
- Returns the type identifier of all SecCode instances.
+ Returns the type identifier of all SecCodeSigner instances.
*/
CFTypeID SecCodeSignerGetTypeID(void);
/*!
+ The following CFString constants can be used as keys in the parameters argument
+ of SecCodeSignerCreate to specify various modes and options of the signing operation.
+ Passing any keys not specified here may lead to undefined behavior and is not supported.
+ The same applies to passing objects of types not explicitly allowed here.
+
+ @constant kSecCodeSignerDetached Determines where the signature is written.
+ If this key is absent, the code being signed is modified to contain the signature,
+ replacing any signature already embedded there.
+ If the value is kCFNull, the signature is written to the system-wide detached
+ signature database. (You must have root privileges to write there.)
+ If the value of this key is a CFURL, the signature is written to a file at that location,
+ replacing any data there.
+ If the value is a CFMutableData, the signature is appended to that data.
+ @constant kSecCodeSignerDryRun A boolean value. If present and true, the actual writing
+ of the signature is inhibited, and the code is not modified, but all operations
+ leading up to this are performed normally, including the cryptographic access to
+ the signing identity (if any).
+ @constant kSecCodeSignerFlags A CFNumber specifying which flags to set in the code signature.
+ Note that depending on circumstances, this value may be augmented or modified
+ as part of the signing operation.
+ @constant kSecCodeSignerIdentifier If present, a CFString that explicitly specifies
+ the unique identifier string sealed into the code signature. If absent, the identifier
+ is derived implicitly from the code being signed.
+ @constant kSecCodeSignerIdentifierPrefix If the unique identifier string of the code signature
+ is implicitly generated, and the resulting string does not contain any "." (dot)
+ characters, then the (string) value of this parameter is prepended to the identifier.
+ By convention, the prefix is usually of the form "com.yourcompany.", but any value
+ is acceptable. If the kSecCodeSignerIdentifier parameter is specified, this parameter
+ is ineffective (but still allowed).
@constant kSecCodeSignerIdentity A SecIdentityRef describing the signing identity
- to use for signing code. This is a mandatory parameter.
- @constant kSecCodeSignerDetached If present, a detached code signature is generated.
- If absent, code signature data is written into the target code (which must
- be writable). The value is a CFURL identifying the file that is replaced with
- the detached signature data.
- @constant kSecCodeSignerRequirements Internal code requirements.
- @constant kSecCodeSignerFlags Signature flags.
+ to use for signing code. This is a mandatory parameter for signing operations.
+ Its value must be either a SecIdentityRef specifying a cryptographic identity
+ valid for Code Signing, or the special value kCFNull to indicate ad-hoc signing.
+ @constant kSecCodeSignerOperation The type of operation to be performed. Valid values
+ are kSecCodeSignerOperationSign to sign code, and kSecCodeSignerOperationRemove
+ to remove any existing signature from code. The default operation is to sign code.
+ @constant kSecCodeSignerPageSize An integer value explicitly specifying the page size
+ used to sign the main executable. This must be a power of two. A value of zero indicates
+ infinite size (no paging).
+ Only certain page sizes are allowed in most circumstances, and specifying an inappropriate
+ size will lead to spurious verification failures. This is for expert use only.
+ @constant kSecCodeSignerRequirements Specifies the internal requirements to be sealed into
+ the code signature. Must be either a CFData containing the binary (compiled) form of
+ a requirements set (SuperBlob), or a CFString containing a valid text form to be
+ compiled into binary form. Default requirements are automatically generated if this
+ parameter is omitted, and defaults may be applied to particular requirement types
+ that are not specified; but any requirement type you specify is sealed exactly as
+ specified.
+ @constant kSecCodeSignerResourceRules A CFDictionary containing resource scanning rules
+ determining what resource files are sealed into the signature (and in what way).
+ A situation-dependent default is applied if this parameter is not specified.
+ @constant kSecCodeSignerSDKRoot A CFURLRef indicating an alterate directory root
+ where signing operations should find subcomponents (libraries, frameworks, modules, etc.).
+ The default is the host system root "/".
+ @constant kSecCodeSignerSigningTime Specifies what date and time is sealed into the
+ code signature's CMS data. Can be either a CFDate object specifying a date, or
+ the value kCFNull indicating that no date should be included in the signature.
+ If not specified, the current date is chosen and sealed.
+ Since an ad-hoc signature has no CMS data, this argument is ineffective
+ for ad-hoc signing operations.
+ @constant kSecCodeSignerRequireTimestamp A CFBoolean indicating (if kCFBooleanTrue) that
+ the code signature should be certified by a timestamp authority service. This option
+ requires access to a timestamp server (usually over the Internet). If requested and
+ the timestamp server cannot be contacted or refuses service, the signing operation fails.
+ The timestamp value is not under the caller's control.
+ If the value is kCFBooleanFalse, no timestamp service is contacted and the resulting signature
+ has no certified timestamp.
+ If this key is omitted, a default is used that may vary from release to release.
+ Note that when signing multi-architectural ("fat") programs, each architecture will
+ be signed separately, and thus each architecture will have a slightly different timestamp.
+ @constant kSecCodeSignerTimestampServer A CFURL specifying which timestamp authority service
+ to contact for timestamping if requested by the kSecCodeSignerRequireTimestamp argument.
+ If omitted (and timestamping is performed), a system-defined default value is used, referring
+ to an Apple-operated timestamp service. Note that this service may not freely serve all requests.
+ @constant kSecCodeSignerTimestampAuthentication A SecIdentityRef describing the identity
+ used to authenticate to the timestamp authority server, if the server requires client-side
+ (SSL/TLS) authentication. This will not generally be the identity used to sign the actual
+ code, depending on the requirements of the timestamp authority service used.
+ If omitted, the timestamp server is contacted using unauthenticated HTTP requests.
+ @constant kSecCodeSignerTimestampOmitCertificates A CFBoolean indicating (if kCFBooleanTrue)
+ that the timestamp embedded in the signature, if requested, not contain the full certificate chain
+ of the timestamp service used. This will make for a marginally smaller signature, but may not
+ verify correctly unless all such certificates are available (through the keychain system)
+ on the verifying system.
+ The default is to embed enough certificates to ensure proper verification of Apple-generated
+ timestamp signatures.
*/
extern const CFStringRef kSecCodeSignerApplicationData;
extern const CFStringRef kSecCodeSignerDetached;
+extern const CFStringRef kSecCodeSignerDigestAlgorithm;
extern const CFStringRef kSecCodeSignerDryRun;
+extern const CFStringRef kSecCodeSignerEntitlements;
extern const CFStringRef kSecCodeSignerFlags;
extern const CFStringRef kSecCodeSignerIdentifier;
extern const CFStringRef kSecCodeSignerIdentifierPrefix;
extern const CFStringRef kSecCodeSignerPageSize;
extern const CFStringRef kSecCodeSignerRequirements;
extern const CFStringRef kSecCodeSignerResourceRules;
+extern const CFStringRef kSecCodeSignerSDKRoot;
extern const CFStringRef kSecCodeSignerSigningTime;
+extern const CFStringRef kSecCodeSignerTimestampAuthentication;
+extern const CFStringRef kSecCodeSignerRequireTimestamp;
+extern const CFStringRef kSecCodeSignerTimestampServer;
+extern const CFStringRef kSecCodeSignerTimestampOmitCertificates;
+
+// temporary add-back to bridge B&I build dependencies -- remove soon
+extern const CFStringRef kSecCodeSignerTSAUse;
+extern const CFStringRef kSecCodeSignerTSAURL;
+extern const CFStringRef kSecCodeSignerTSAClientAuth;
+extern const CFStringRef kSecCodeSignerTSANoCerts;
/*!
are applied to all parameters; note however that some parameters do not have
useful defaults, and will need to be set before signing is attempted.
@param flags Optional flags. Pass kSecCSDefaultFlags for standard behavior.
+ The kSecCSRemoveSignature flag requests that any existing signature be stripped
+ from the target code instead of signing.
@param staticCode On successful return, a SecStaticCode object reference representing
the file system origin of the given SecCode. On error, unchanged.
@result Upon success, noErr. Upon error, an OSStatus value documented in
CSCommon.h or certain other Security framework headers.
*/
+enum {
+ kSecCSRemoveSignature = 1 << 0, // strip existing signature
+};
+
+
OSStatus SecCodeSignerCreate(CFDictionaryRef parameters, SecCSFlags flags,
SecCodeSignerRef *signer);
projects / apple / libsecurity_codesigning.git / blobdiff