Swiftpack.co - trilemma-dev/SecureXPC as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by trilemma-dev.
trilemma-dev/SecureXPC 0.8.0
A simple and secure XPC framework for Swift
⭐️ 43
🕓 18 weeks ago
macOS
.package(url: "https://github.com/trilemma-dev/SecureXPC.git", from: "0.8.0")

Use pure Swift to easily and securely communicate with XPC services and 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 package can be used to communicate with any type of XPC service or Mach service, with customized support for:

It's built with security in mind, minimizing the opportunities for exploits. Security checks are performed against the actual calling process instead of relying on PIDs which are known to be insecure.

Usage

The envisioned pattern when using this package 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.forMachService()
    • For agents and daemons registered with SMAppService, SMJobBless helper tools, and SMLoginItemSetEnabled login items
  • XPCServer.forMachService(withCriteria:)
    • For any type of Mach service including "classic" agents and daemons; see documentation for details
  • XPCServer.makeAnonymous()
    • Typically used for testing purposes
  • XPCServer.makeAnonymous(withClientRequirements:)
    • Enables advanced scenarios including apps directly communicating with each other; see documentation for 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 three 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:withServerRequirement:)
    • For communicating with a Mach service
    • This corresponds to servers created with XPCServer.forMachService() or XPCServer.forMachService(withCriteria:)
  • XPCClient.forEndpoint(_:withServerRequirement:)
    • This is the only way to communicate with an anonymous server
    • This corresponds to servers created with XPCServer.makeAnonymous() or XPCServer.makeAnonymous(withClientRequirements:)
    • This type of client can also be used to communicate with any server via its endpoint property

Questions you may have

See the FAQ for answers to questions you may have or didn't even realize you wanted answered including topics such as using live file handles, sharing memory between processes, and working within sandbox restrictions.

GitHub

link
Stars: 43
Last commit: 3 days ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

0.8.0
18 weeks ago

This is a big release! Continued thanks to @amomchilov for his contributions and code reviews.

New functionality

  • Adds built-in support for macOS Ventura's new SMAppService's daemons & agents.
    • For simple configurations, just call XPCServer.forMachService() and an auto-configured server will be returned.
  • Experimental support for shared memory has been added. Shared memory is truly shared between processes, no encoding or decoding occurs like with typical XPC communication.
    • A friendly to use, although quite basic, data structure SharedTrivial demonstrates this functionality.
    • The building block pieces available through SharedSemaphore, SharedMemory, and SharedRawMemory should enable you to build your own custom multi-process data structures.
    • This support is experimental and while it remains experimental breaking changes to it will not be considered for SerVer purposes.
  • XPCClient now provides the unforgeable identity of the server it is connected to via its serverIdentity async property (or the equivalent callback function).
  • XPCClient now automatically verifies the identity of the server in common cases and this can be customized with XPCClient.ServerRequirement.
  • XPCServer instances now always have an endpoint property (previously only those also conforming to XPCNonBlockingServer had this property).
  • Send IOSurface instances over XPC connections using the IOSurfaceForXPC property wrapper.
  • Data instances and arrays of trivial types can optionally be more efficiently sent across XPC connections by using the DataOptimizedForXPC and ArrayOptimizedForXPC property wrappers.

Breaking changes

  • XPCServer retrieval has been simplified. There are now just three main entry points:
    • XPCServer.forThisXPCService()
    • XPCServer.forMachService()
    • XPCServer.makeAnonymous()
  • XPCServer retrieval is now more customizable.
    • To customize a Mach service use XPCServer.MachServiceCriteria then call XPCServer.forMachService(withCriteria:)
    • To customize an anonymous server use XPCServer.makeAnonymous(withClientRequirement:)
  • XPCServer's client requirements no longer require using SecRequirement directly (although that's still supported).
    • Requirements are now created using XPCServer.ClientRequirement and declarative in nature: XPCServer.makeAnonymous(withClientRequirement: try .sameTeamIdentifier || try .teamIdentifier("Q55ZG849VX"))
  • XPCClient's factory methods have been tweaked to now optionally take a XPCClient.ServerRequirement instance.
  • XPCFileDescriptorContainer has been replaced by the FileHandleForXPC and FileDescriptorForXPC property wrappers.
  • XPCRequestContext has been renamed to XPCServer.ClientIdentity.
  • Several XPCError cases have been removed and a few have been added.
  • The underlying interprocess communication protocol between the client and server has changed (to support the client's ability to verify the server's identity). This means if you update SecureXPC, you need to do so for both your client and server implementations at the same time.

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics