xpc: support termination of IKE_SAs using XPC RPC on connection channel
[strongswan.git] / src / frontends / osx / README.md
1 # strongSwan OS X App #
2
3 ## Introduction ##
4
5 The strongSwan OS X App consists of two components:
6
7 * A frontend to configure and control connections
8 * A privileged helper daemon, controlled using XPC, called charon-xpc
9
10 The privileged helper daemon gets installed automatically using SMJobBless
11 functionality on its first use, and gets started automatically by Launchd when
12 needed.
13
14 charon-xpc is a special build linking statically against strongSwan components.
15
16 ## Building strongSwan ##
17
18 strongSwan on OS X requires the libvstr library. The simplest way to install
19 it is using MacPorts. It gets statically linked to charon-xpc, hence it is not
20 needed to run the built App.
21
22 Before building the Xcode project, the strongSwan base tree must be built using
23 a monolithic and static build. This can be achieved on OS X by using:
24
25 LDFLAGS="-all_load" \
26 CFLAGS="-I/usr/include -DOPENSSL_NO_CMS -O2 -Wall -Wno-format -Wno-pointer-sign" \
27 ./configure --prefix=/opt/local --disable-defaults --enable-openssl \
28   --enable-kernel-pfkey --enable-kernel-pfroute --enable-eap-mschapv2 \
29   --enable-eap-identity --enable-monolithic --enable-nonce --enable-random \
30   --enable-pkcs1 --enable-pem --enable-socket-default --enable-xauth-generic \
31   --enable-keychain --enable-ikev1 --enable-ikev2 --enable-charon \
32   --disable-shared --enable-static
33
34 followed by calling make (no need to make install).
35
36 Building charon-xpc using the Xcode project yields a single binary without
37 any non OS X dependencies.
38
39 Both charon-xpc and the App must be code-signed to allow the installation of
40 the privileged helper. git-grep for "Joe Developer" to change the signing
41 identity.
42
43 ## XPC application protocol ##
44
45 charon-xpc provides a Mach service under the name _org.strongswan.charon-xpc_.
46 Clients can connect to this service to control the daemon. All messages
47 on all connections use the following string dictionary keys/values:
48
49 * _type_: XPC message type, currently either
50  * _rpc_ for a remote procedure call, expects a response
51  * _event_ for application specific event messages
52 * _rpc_: defines the name of the RPC function to call (for _type_ = _rpc_)
53 * _event_: defines a name for the event (for _type_ = _event_)
54
55 Additional arguments and return values are specified by the call and can have
56 any type. Keys are directly attached to the message dictionary.
57
58 On the Mach service connection, the following RPC messages are currently
59 defined:
60
61 * string version = get_version()
62   * _version_: strongSwan version of charon-xpc
63 * bool success = start_connection(string name, string host, string id,
64                                   endpoint channel)
65   * _success_: TRUE if initiation started successfully
66   * _name_: connection name to initiate
67   * _host_: server hostname (and identity)
68   * _id_: client identity to use
69   * _channel_: XPC endpoint for this connection
70
71 The start_connection() RPC returns just after the initation of the call and
72 does not wait for the connection to establish. Nonetheless does it have a
73 return value to indicate if connection initiation could be triggered.
74
75 The App passes an (anonymous) XPC endpoint to start_connection(). If the call
76 succeeds, charon-xpc connects to this endpoint to establish a channel used for
77 this specific IKE connection.
78
79 On this channel, the following RPC calls are currently defined from charon-xpc
80 to the App:
81
82 * string password = get_password(string username)
83   * _password_: user password returned
84   * _username_: username to query a password for
85
86 The following events are currently defined from charon-xpc to the App:
87 * _up_: connection has been established
88 * _down_: connection has been closed or failed to establish