android: Encode connection settings as single Java string argument
[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 App to configure and control connections (under strongSwan)
8 * A privileged helper daemon, controlled using XPC (under 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 charon-xpc and the App sources are currently not part of the official strongSwan
17 distribution. Build the charon-xpc tarball with:
18
19     git archive -o osx-sources-$(grep AC_INIT configure.ac | \
20                                 cut -d '[' -f3 | cut -d ']' -f1).tar.bz2 \
21         HEAD src/frontends/osx
22
23 ## Building strongSwan ##
24
25 Before building the Xcode project, the strongSwan base tree must be built using
26 a monolithic and static build. This can be achieved on OS X by using:
27
28     CFLAGS="-O2 -g -Wall -Wno-format -Wno-pointer-sign -Wno-deprecated-declarations" \
29     ./configure --enable-monolithic --disable-shared --enable-static \
30         --disable-defaults \
31         --enable-openssl --enable-kernel-libipsec --enable-kernel-pfroute \
32         --enable-eap-mschapv2 --enable-eap-identity --enable-eap-md5 \
33         --enable-eap-gtc --enable-pkcs1 --enable-socket-default --enable-osx-attr \
34         --enable-xauth-generic --enable-gcm --enable-ccm --enable-ctr \
35         --enable-keychain --enable-nonce --enable-charon \
36         --enable-ikev1 --enable-ikev2
37
38 followed by calling make (no need to make install).
39
40 Building charon-xpc using the Xcode project yields a single binary without
41 any non OS X dependencies. The strongSwan target in the same project builds
42 the App and integrates charon-xpc for the deployment.
43
44 Both charon-xpc and the App must be code-signed to allow the installation of
45 the privileged helper. By default both targets use the _Developer ID: *_
46 wildcard to use the first usable code signing identity. Both the App and
47 charon-xpc require a hardcoded certificate subject under
48 _strongSwan/strongSwan-Info.plist_ respectively
49 _charon-xpc/charon-xpc-Info.plist_. Update the _org.strongswan.charon-xpc_
50 _SMPrivilegedExecutables_ in the App and _SMAuthorizedClients_ in charon-xpc
51 with your code signing certificate identity.
52
53 ## XPC application protocol ##
54
55 charon-xpc provides a Mach service under the name _org.strongswan.charon-xpc_.
56 Clients can connect to this service to control the daemon. All messages
57 on all connections use the following string dictionary keys/values:
58
59 * _type_: XPC message type, currently either
60         * _rpc_ for a remote procedure call, expects a response
61         * _event_ for application specific event messages
62 * _rpc_: defines the name of the RPC function to call (for _type_ = _rpc_)
63 * _event_: defines a name for the event (for _type_ = _event_)
64
65 Additional arguments and return values are specified by the call and can have
66 any type. Keys are directly attached to the message dictionary.
67
68 On the Mach service connection, the following RPC messages are currently
69 defined:
70
71 * string version = get_version()
72         * _version_: strongSwan version of charon-xpc
73 * bool success = start_connection(string name, string host, string id,
74                                                                   endpoint channel)
75         * _success_: TRUE if initiation started successfully
76         * _name_: connection name to initiate
77         * _host_: server hostname (and identity)
78         * _id_: client identity to use
79         * _channel_: XPC endpoint for this connection
80
81 The start_connection() RPC returns just after the initiation of the call and
82 does not wait for the connection to establish. Nonetheless does it have a
83 return value to indicate if connection initiation could be triggered.
84
85 The App passes an (anonymous) XPC endpoint to start_connection(). If the call
86 succeeds, charon-xpc connects to this endpoint to establish a channel used for
87 this specific IKE connection.
88
89 On this channel, the following RPC calls are currently defined from charon-xpc
90 to the App:
91
92 * string password = get_password(string username)
93         * _password_: user password returned
94         * _username_: username to query a password for
95
96 And the following from the App to charon-xpc:
97
98 * bool success = stop_connection()
99         * _success_: TRUE if termination of connection initiated
100
101 The following events are currently defined from charon-xpc to the App:
102
103 * up(): IKE_SA has been established
104 * down(): IKE_SA has been closed or failed to establish
105 * child_up(string local_ts, string remote_ts): CHILD_SA has been established
106 * child_down(string local_ts, string remote_ts): CHILD_SA has been closed
107 * log(string message): debug log message for this connection