aprsc/src/aprsis2.proto

/*
 *	A server sends a ServerSignature to all new clients.
 *
 *	Future expansion space: the server may signal support for
 *	optional future extensions by providing a list of string IDs
 *	of supported features.
 */

message ServerSignature {
	required string username = 1; // callsign-SSID
	required string app_name = 2;
	required string app_version = 3;
	repeated string features = 4; // list of supported optional features
}

/*
 *	Clients can then request a login with a LoginRequest.
 *	
 *	features_req contains a list of features the client would like
 *	to enable for the connection (may only contain features
 *	listed supported by the server).
 */

message LoginRequest {
	required string username = 1; // callsign-SSID
	optional string password = 2; // passcode or password
	required string app_name = 3;
	required string app_version = 4;
	optional string filter_string = 5; // traditional filter string
	repeated string features_req = 6; // list of requested optional features
}

/*
 *	Server will verify the login credentials of the client, and
 *	signal result to the client (and possibly other servers)
 *	using a VerificationStatus enum.
 */

enum VerificationStatus {
	NONE = 0;	// None at all, client may only receive data
	WEAK = 1;	// "APRS passcode"
	MEDIUM = 2;
	STRONG = 3;	// Certificate authentication or equivalent
}

/*
 *	Server replies to a LoginRequest with a LoginReply.
 *
 *	features_ack contains a list of optional features accepted
 *	by the server (may only contain features requested in features_req).
 *	The server may ignore feature requests from some clients,
 *	even if it would technically support them.
 */

message LoginReply {
	enum LoginResult {
		FAIL = 0; // Login rejected, the client will be thrown out
		OK = 1;
	}
	
	/* Login result reason codes, provided in machine-readable codes
	 * so that localized error messages can be displayed to users.
	 * Login failure result code might also affect client actions.
	 */
	enum LoginResultReason {
		// Nothing to say
		NONE = 0;
		// Password or passcode provided by client is not valid.
		INVALID_PASSWORD = 1;
		// Server requires certificate authentication, client did not
		// provide one.
		CERT_REQUIRED = 2;
		// Server could not verify certificate (chain incomplete or
		// root not trusted)
		CERT_VERIFICATION_FAIL = 3;
		// Certificate is not valid for username. OH7LZB's certificate is
		// good for OH7LZB-9 and other SSIDs, but not for OH7AA or some other
		// callsign.
		CERT_MISMATCH = 4;
		// Certificate has expired.
		CERT_EXPIRED = 5;
	}
	
	required LoginResult result = 1;
	required VerificationStatus verified = 2;
	optional LoginResultReason result_code = 3;
	optional string result_message = 4; // english descriptive
	repeated string features_ack = 5; // list of agreed optional features
}

/*
 *	Ping/pong message to check if the peer in the other end is
 *	still there, and to measure the round-trip time.
 *
 *	When you get a ping request, you're supposed to change the
 *	request to a reply, and send it back otherwise unmodified,
 *	using the same request ID and data contents.
 *
 *	request_data can optionally be used to transmit, for example,
 *	the local transmit timestamp at the requesting node, using
 *	whichever convenient local format and accuracy.
 */

message KeepalivePing {
	enum PingType {
		REQUEST = 1;
		REPLY = 2;
	}
	
	required PingType ping_type = 1;
	required uint32 request_id = 2;
	optional bytes request_data = 3;
}

/*
 *	APRS-IS packet
 */

message ISPacket {
	enum Type {
		// Traditional APRS-IS format with embedded Q construct
		IS_PACKET = 2;
	}
	
	// Identifies which message is filled in.
	required Type type = 1;
	
	// packet data in traditional APRS-IS format, without CRLF
	optional bytes is_packet_data = 2;
}

/*
 *	This is the main link-level container message being transmitted
 *	between peers (or clients and servers).
 *
 *	All of the above messages are embedded in one of these.
 *
 *	Just one message per container, so that in the most common case the
 *	container can simply be retransmitted as-is by the servers.
 */

message IS2Message {
	enum Type {
		SERVER_SIGNATURE = 2;
		LOGIN_REQUEST = 3;
		LOGIN_REPLY = 4;
		KEEPALIVE_PING = 5;
		IS_PACKET = 6;
	}
	
	// Identifies which message is filled in.
	required Type type = 1;
	
	// One of the following will be filled in. Just one.
	optional ServerSignature server_signature = 2;
	optional LoginRequest login_request = 3;
	optional LoginReply login_reply = 4;
	optional KeepalivePing keepalive_ping = 5;
	optional ISPacket is_packet = 6;
}