SecureXPC

0.7.0

A simple and secure XPC framework for Swift
trilemma-dev/SecureXPC

What's New

0.7.0

2022-05-12T19:07:45Z

This release adds numerous improvements that result in breaking changes.

Breaking changes

  • XPCServer's targetQueue property has been removed and replaced with a handlerQueue property with improved documentation. This queue is only used when running synchronous handlers. By default a concurrent queue is used to run synchronous handlers, but this can be set to a serial queue if desired.
  • XPCClient and XPCServer's serviceName property has been replaced by a connectionDescriptor property. This property returns a type of XPCConnectionDescriptor which describes the connection and for non-anonymous connections includes the name.
  • XPCServerEndpoint now also has a connectionDescriptor property which returns a value matching that of the XPCServer from which it was created.
  • Most of XPCError's cases now have named parameters for their associated values. For example XPCError.routeMismatch(routeName:description:).

Use pure Swift to easily and securely communicate with XPC services and XPC Mach services. A client-server model enables you to use your own Codable conforming types to send requests to routes you define and receive responses.

SecureXPC uses Swift concurrency on macOS 10.15 and later allowing clients to make non-blocking asynchronous requests to servers. A closure-based API is also available providing compatibility back to OS X 10.10.

This framework is ideal for communicating with helper tools installed via SMJobBless and login items installed via SMLoginItemSetEnabled. It's built with security in mind, minimizing the opportunities for exploits. Server-side security checks are performed against the actual calling process instead of relying on PIDs which are known to be insecure.

Recommendation: If you are using SMJobBless helper tools, also check out Blessed.

Usage

The envisioned pattern when using this framework is to define routes in a shared file, create a server in one program (such as a helper tool) and register these routes, then from another program (such as an app) create a client and send requests to these routes.

Routes

In a file shared by the client and server define one or more routes:

let route = XPCRoute.named("bedazzle")
                    .withMessageType(String.self)
                    .withReplyType(Bool.self)

Server

In one program retrieve a server, register those routes, and then start the server:

    ...
    let server = <# server retrieval here #>
    server.registerRoute(route, handler: bedazzle)
    server.startAndBlock()
}

private func bedazzle(message: String) throws -> Bool {
     <# implementation here #>
}

On macOS 10.15 and later async functions and closures can also be registered as the handler for a route.

There are multiple types of servers which can be retrieved:

  • XPCServer.forThisXPCService()
    • For an XPC service, which is a private helper tool available only to the main application that contains it
  • XPCServer.forThisBlessedHelperTool()
  • XPCServer.forThisLoginItem()
  • XPCServer.forThisMachService(named:clientRequirements:)
  • XPCServer.makeAnonymous()
    • Typically used for testing purposes
  • XPCServer.makeAnonymous(clientRequirements:)
    • Enables applications not managed by launchd to communicate with each other, see documentation for more details

Client

In another program retrieve a client, then send a request to a registered route:

let client = <# client retrieval here #>
let reply = try await client.sendMessage("Get Schwifty", to: route)

Closure-based variants are available for macOS 10.14 and earlier:

let client = <# client retrieval here #>
client.sendMessage("Get Schwifty", to: route, withResponse: { result in
    switch result {
        case .success(let reply):
            <# use the reply #>
        case .failure(let error):
            <# handle the error #>
    }
})

There are multiple types of clients which can be retrieved:

  • XPCClient.forXPCService(named:)
    • For communicating with an XPC service
    • This corresponds to servers created with XPCServer.forThisXPCService()
  • XPCClient.forMachService(named:)
    • For communicating with an XPC Mach service
    • This corresponds to servers created with XPCServer.forThisBlessedHelperTool(), XPCServer.forThisLoginItem(), and XPCServer.forThisMachService(named:clientRequirements:)
  • XPCClient.forEndpoint(_:)
    • This is the only way to communicate with an anonymous server
    • This corresponds to servers created with XPCServer.makeAnonymous() or XPCServer.makeAnonymous(clientRequirements:)
    • It can also be used with an XPC Mach service

Codable vs NSSecureCoding

SecureXPC uses types conforming to Swift's Codable protocol to serialize data across the XPC connection. Due to the nature of how Codable is defined, it is not possible for the same instance to be referenced from multiple other deserialized instances. This is in contrast to how NSSecureCoding behaves, which is used by NSXPCConnection for serialization.

While there are considerable similarities between these two serialization protocols, there is a significant difference in how deserialization occurs. A Codable conforming type is always decoded via its initializer with no possibility of substitution. In contrast, an NSSecureCoding conforming type may use awakeAfter(using:) to substitute in an already initialized instance.

While Codable can be implemented by any type, in practice value types such as struct and enum are the most natural fit. The aforementioned deserialization behavior is by definition not applicable to value types.

Description

  • Swift Tools 5.5.0
View More Packages from this Author

Dependencies

  • None
Last updated: Wed May 18 2022 02:05:08 GMT-0500 (GMT-05:00)