Creates a new guest and describes its initial properties.


OSStatus SecHostCreateGuest(SecGuestRef host, uint32_t status, CFURLRef path, CFDictionaryRef attributes, SecCSFlags flags, SecGuestRef *newGuest);



A guest code object identifying the code that is to be the direct host of the new guest. Pass kSecNoGuest if the process calling this function is to be the host. To create a guest of another guest (extending the hosting chain), pass the guest code object of the guest that is to act as the new guest’s host. If the specified host already has a dedicated guest, then that dedicated guest becomes the actual host of the new guest (unless the dedicated guest also has a dedicated guest, in which case the same algorithm is replied recursively). See kSecCSDedicatedHost for a discussion of dedicated hosts.


Code status flags for the new guest (see SecCodeStatus). Note that certain code status flags can be set only once, by the caller of the SecHostCreateGuest function when it creates the guest. In particular, if you do not set the kSecCodeStatusValid flag during creation of the guest, then the new guest is created dynamically invalid and can never become dynamically valid.


The canonical path to the guest’s code on disk. This is the path you would pass to the SecStaticCodeCreateWithPath function to make a static code object reference. You must use an absolute path.


A key-value dictionary of attributes that can be used to identify this particular guest among all of the caller’s guests. The kSecGuestAttributeCanonical attribute—containing the guest’s code object (that is, the SecGuestRef object returned in the newGuest parameter) is automatically added to the guest’s attributes. Pass NULL for this parameter if you do not want to establish any other attributes for this guest. Although you can specify any key-value pairs in this attributes dictionary, the keys in Guest Attribute Dictionary Keys are conventionally used for this purpose.


Optional flags; see SecCSFlags and Guest Creation Flags for possible values. Pass kSecCSDefaultFlags for standard behavior. Pass kSecCSDedicatedHost to make the code specified in the host parameter the dedicated host for the new guest.


On return, the guest code object that identifies the new guest.

Return Value


Code that calls this function becomes a code host operating in proxy hosting mode. Subsequently, Code Signing Services caches information about guest code provided by the host when it calls the SecHostCreateGuest, SecHostSetGuestStatus, and SecHostRemoveGuest functions. Code Signing Services uses this information to report hosting status to callers directly without consulting the host. A code host running in proxy hosting mode cannot switch to dynamic hosting mode.

See Also

Guest Code

Hosting Guest Code

Securely launch and manage plug-ins and other executable entities, known as guest code, from within your app acting as a host.


Updates the status and attributes of a particular guest.


Asks a code host to identify one of its guests given the type and value of specific attributes of the guest code.

Null Guest Handle

Use this special value to stand in for a null guest object.


Operational flags attached by code signing services to running code.

Guest Creation Flags

Use these supplemental flags to create a guest object.

Guest Attribute Dictionary Keys

Specify attributes of guest code.


A reference to a guest object, which identifies a particular block of guest code in the context of its code signing host.