Merge pull request coturn#48 from misi/oauth

OAuth utility

ChangeLog

@@ -4,6 +4,7 @@ Version 4.5.0.5 'dan Eider':
 	- LibreSSL compatibility fixed.
 	- "read_timeout" option support for MySQL.
 	- new NAT behavior discovery utilty. 
+	- new OAuth access_token encrypt/decrypt utilty. 
 
 08/20/2016 Oleg Moskalenko <[email protected]>
 Version 4.5.0.4 'dan Eider':

Makefile.in

@@ -34,7 +34,7 @@ SERVERAPP_HEADERS = src/apps/relay/userdb.h src/apps/relay/tls_listener.h src/ap
 SERVERAPP_MODS = src/apps/relay/mainrelay.c src/apps/relay/netengine.c src/apps/relay/libtelnet.c src/apps/relay/turn_admin_server.c src/apps/relay/userdb.c src/apps/relay/tls_listener.c src/apps/relay/dtls_listener.c ${HIREDIS_MODS} ${USERDB_MODS}
 SERVERAPP_DEPS = ${SERVERTURN_MODS} ${SERVERTURN_DEPS} ${SERVERAPP_MODS} ${SERVERAPP_HEADERS} ${COMMON_DEPS} ${IMPL_DEPS} lib/libturnclient.a
 
-TURN_BUILD_RESULTS = bin/turnutils_natdiscovery bin/turnutils_stunclient bin/turnutils_rfc5769check bin/turnutils_uclient bin/turnserver bin/turnutils_peer lib/libturnclient.a include/turn/ns_turn_defs.h sqlite_empty_db
+TURN_BUILD_RESULTS = bin/turnutils_oauth bin/turnutils_natdiscovery bin/turnutils_stunclient bin/turnutils_rfc5769check bin/turnutils_uclient bin/turnserver bin/turnutils_peer lib/libturnclient.a include/turn/ns_turn_defs.h sqlite_empty_db
 
 all:	${TURN_BUILD_RESULTS}
 
@@ -59,6 +59,11 @@ bin/turnutils_natdiscovery:	${COMMON_DEPS} lib/libturnclient.a src/apps/natdisco
 	${MKBUILDDIR} bin
 	${CC} ${CPPFLAGS} ${CFLAGS} src/apps/natdiscovery/natdiscovery.c ${COMMON_MODS} -o $@ -Llib -lturnclient -Llib ${LDFLAGS}
 
+bin/turnutils_oauth:	${COMMON_DEPS} lib/libturnclient.a src/apps/oauth/oauth.c
+	pwd
+	${MKBUILDDIR} bin
+	${CC} ${CPPFLAGS} ${CFLAGS} src/apps/oauth/oauth.c ${COMMON_MODS} -o $@ -Llib -lturnclient -Llib ${LDFLAGS}
+
 bin/turnutils_stunclient:	${COMMON_DEPS} lib/libturnclient.a src/apps/stunclient/stunclient.c 
 	pwd
 	${MKBUILDDIR} bin

README.turnutils

@@ -37,6 +37,17 @@ according RFC5780. This utility discovers the actual NAT Mapping and Filtering
 behavior. Be aweare that at least two different listening IP addresses should 
 be configured to be able to work properly!
 
+6.	turnutils_oauth: a utility that provides OAuth access_token 
+generation(AEAD encryption), validation and decryption. This utility inputs 
+all the keys and lifetimes and any related informations that needed for 
+creation and validationi of an access_token. It outputs a JSON with all OAuth 
+PoP parameters that need to pass to the client. Output is generated accoriding 
+RFC7635 Appendix B, Figure 8. 
+
+For more details, and for the access_token structure, read rfc7635, and see
+script in examples/scripts/oauth.sh.
+
+
 =====================================
 
   NAME
@@ -271,6 +282,74 @@ Usage:
 
 $ turnutils_natdiscovery -m -f stun.example.com
 
+=====================================
+
+  NAME
+
+turnutils_oauth - a utility that helps OAuth access_token generation/encryption and validation/decyption
+
+  SYNOPSIS
+
+$ turnutils_oauth [options]
+
+  DESCRIPTION
+
+turnutils_oauth utilitiy provides help in OAuth access_token encryption and/or 
+decryption with AEAD (Atuthenticated Encryption with Associated Data). It helps 
+for an Auth Server in access_token creation, and also for debuging purposes it 
+helps the access_token validation and decryption. This utility inputs all the 
+keys and lifetimes and any related informations that are needed for encryption 
+or decryption of an access_token. It outputs a JSON with all OAuth PoP 
+parameters that need to pass to the client. Output is generated accoriding 
+RFC7635 Appendix B, Figure 8. This utility could help to build an Auth Server 
+service, but be awere that this utility does not generate "session key" / 
+"mac_key" and not verifies lifetime of "session key" / "mac_key" or "Auth key".
+For more details, and for the access_token structure, read rfc7635, and see
+the example in examples/scripts/oauth.sh.
+
+Use either -e and/or -d flag to encrypt or decrypt access_token.
+
+Flags:
+
+-h, --help     usage
+
+-v, --verbose  verbose mode
+
+-e, --encrypt  encrypt token
+
+-d, --decrypt  decrypt validate token
+
+Options with required values:
+
+-i, --server-name              server name (max. 255 char)
+
+-j, --auth-key-id              Auth key id (max. 32 char)
+
+-k, --auth-key                 base64 encoded Auth key
+
+-l  --auth-key-timestamp       Auth key timestamp (sec since epoch)
+
+-m, --auth-key-lifetime        Auth key lifetime in sec
+
+-n, --auth-key-as-rs-alg       Authorization Server(AS) - Resource Server(RS) encryption algorithm
+
+-o, --token-nonce              base64 encoded nonce base64(12 octet) = 16 char
+
+-p, --token-mac-key            base64 encoded MAC key base64(32 octet) = 44 char
+
+-q, --token-timestamp          timestamp in format 64 bit unsigned (Native format - Unix),
+                               so 48 bit for secs since epoch UTC + 16 bit for 1/64000 fractions of a second.
+                               e.g.: the actual unixtimestamp 16 bit left shifted. (Default: actual gmtime)
+-r, --token-lifetime           lifetime in sec (Default: 3600)
+
+-t, --token                    base64 encoded encrypted token for validation and decryption
+
+-u, --hmac-alg                 stun client hmac algorithm
+
+Usage:
+
+$ turnutils_natdiscovery
+
 ===================================
 
 DOCS

examples/scripts/oauth.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+OAUTH_UTILITY=bin/turnutils_oauth
+
+echo "--------------create an access_token---------------"
+$OAUTH_UTILITY -e --server-name example.com --auth-key-id 1234 --auth-key SEdrajMyS0pHaXV5MDk4c2RmYXFiTmpPaWF6NzE5MjM= --auth-key-timestamp 249213600 --auth-key-lifetime 21600 --token-mac-key WmtzanB3ZW9peFhtdm42NzUzNG0=  --token-timestamp 16333642137600 --token-lifetime=3600
+
+echo "---------------create and validate and print out the decoded access_token---------------"
+$OAUTH_UTILITY -v -d -e --server-name example.com --auth-key-id 1234 --auth-key SEdrajMyS0pHaXV5MDk4c2RmYXFiTmpPaWF6NzE5MjM= --auth-key-timestamp 249213600 --auth-key-lifetime 21600 --token-mac-key WmtzanB3ZW9peFhtdm42NzUzNG0=  --token-timestamp 16333642137600 --token-lifetime=3600
+
+echo -e "\n---------------just validate only the access_token---------------"
+$OAUTH_UTILITY -d --server-name example.com --auth-key-id 1234 --auth-key SEdrajMyS0pHaXV5MDk4c2RmYXFiTmpPaWF6NzE5MjM= --auth-key-timestamp 249213600 --auth-key-lifetime 21600 --token AAy1JBYVLo16iq9gFdHyyknmx5T/Lq9YlbxgUdLcStOFS0H8xhHceHOL2f49qxp4uBpGuuLeLqk+RcAa5uP2EQ== --token-lifetime=3600
+
+echo -e "\n---------------validate and print out the decoded access_token---------------"
+$OAUTH_UTILITY -v -d --server-name example.com --auth-key-id 1234 --auth-key SEdrajMyS0pHaXV5MDk4c2RmYXFiTmpPaWF6NzE5MjM= --auth-key-timestamp 249213600 --auth-key-lifetime 21600 --token AAy1JBYVLo16iq9gFdHyyknmx5T/Lq9YlbxgUdLcStOFS0H8xhHceHOL2f49qxp4uBpGuuLeLqk+RcAa5uP2EQ== --token-lifetime=3600
+
+

make-man.sh

@@ -2,15 +2,16 @@
 
 rm -rf man/man1/*
 
-txt2man -s 1 -t TURN -I turnserver -I turnadmin -I turnutils -I turnutils_uclient -I turnutils_stunclient -I turnutils_rfc5769check -I turnutils_peer -I turnutils_natdiscovery -B "TURN Server" README.turnserver | sed -e 's/-/\\-/g' > man/man1/turnserver.1
+txt2man -s 1 -t TURN -I turnserver -I turnadmin -I turnutils -I turnutils_uclient -I turnutils_stunclient -I turnutils_rfc5769check -I turnutils_peer -I turnutils_natdiscovery -I turnutils_oauth -B "TURN Server" README.turnserver | sed -e 's/-/\\-/g' > man/man1/turnserver.1
 
-txt2man -s 1 -t TURN -I turnserver -I turnadmin -I turnutils -I turnutils_uclient -I turnutils_stunclient -I turnutils_rfc5769check -I turnutils_peer -I turnutils_natdiscovery -B "TURN Server" README.turnadmin | sed -e 's/-/\\-/g'> man/man1/turnadmin.1
+txt2man -s 1 -t TURN -I turnserver -I turnadmin -I turnutils -I turnutils_uclient -I turnutils_stunclient -I turnutils_rfc5769check -I turnutils_peer -I turnutils_natdiscovery -I turnutils_oauth -B "TURN Server" README.turnadmin | sed -e 's/-/\\-/g'> man/man1/turnadmin.1
 
-txt2man -s 1 -t TURN -I turnserver -I turnadmin -I turnutils -I turnutils_uclient -I turnutils_stunclient -I turnutils_rfc5769check -I turnutils_peer -I turnutils_natdiscovery -B "TURN Server" README.turnutils | sed -e 's/-/\\-/g' > man/man1/turnutils.1
+txt2man -s 1 -t TURN -I turnserver -I turnadmin -I turnutils -I turnutils_uclient -I turnutils_stunclient -I turnutils_rfc5769check -I turnutils_peer -I turnutils_natdiscovery -I turnutils_oauth -B "TURN Server" README.turnutils | sed -e 's/-/\\-/g' > man/man1/turnutils.1
 
 cd man/man1; ln -s turnutils.1 turnutils_uclient.1;cd ../..
 cd man/man1; ln -s turnutils.1 turnutils_peer.1;cd ../..
 cd man/man1; ln -s turnutils.1 turnutils_stunclient.1;cd ../..
 cd man/man1; ln -s turnutils.1 turnutils_natdiscovery.1;cd ../..
+cd man/man1; ln -s turnutils.1 turnutils_oauth.1;cd ../..
 cd man/man1; ln -s turnserver.1 coturn.1;cd ../..
 

man/man1/turnadmin.1

@@ -1,5 +1,5 @@
 .\" Text automatically generated by txt2man
-.TH TURN 1 "04 September 2016" "" ""
+.TH TURN 1 "07 September 2016" "" ""
 .SH GENERAL INFORMATION
 
 \fIturnadmin\fP is a TURN administration tool. This tool can be used to manage 

man/man1/turnserver.1

@@ -1,5 +1,5 @@
 .\" Text automatically generated by txt2man
-.TH TURN 1 "04 September 2016" "" ""
+.TH TURN 1 "07 September 2016" "" ""
 .SH GENERAL INFORMATION
 
 The \fBTURN Server\fP project contains the source code of a TURN server and TURN client 

man/man1/turnutils.1

@@ -1,5 +1,5 @@
 .\" Text automatically generated by txt2man
-.TH TURN 1 "04 September 2016" "" ""
+.TH TURN 1 "07 September 2016" "" ""
 .SH GENERAL INFORMATION
 
 A set of turnutils_* programs provides some utility functionality to be used
@@ -48,7 +48,22 @@ $ ./scripts/secure_relay.sh
 according RFC5780. This utility discovers the actual NAT Mapping and Filtering 
 behavior. Be aweare that at least two different listening IP addresses should 
 be configured to be able to work properly!
+.TP
+.B
+6.
+\fIturnutils_oauth\fP: a utility that provides OAuth access_token 
+\fBgeneration\fP(AEAD encryption), validation and decryption. This utility inputs 
+all the keys and lifetimes and any related informations that needed for 
+creation and validationi of an access_token. It outputs a JSON with all OAuth 
+PoP parameters that need to pass to the client. Output is generated accoriding 
+RFC7635 Appendix B, Figure 8. 
+.PP
+For more details, and for the access_token structure, read rfc7635, and see
+script in examples/scripts/oauth.sh.
+.RE
 .PP
+
+.RS
 =====================================
 .SS  NAME
 \fB
@@ -414,6 +429,112 @@ Usage:
 .PP
 $ \fIturnutils_natdiscovery\fP \fB\-m\fP \fB\-f\fP stun.example.com
 .PP
+=====================================
+.SS  NAME
+\fB
+\fBturnutils_oauth \fP\- a utility that helps OAuth access_token generation/encryption and validation/decyption
+\fB
+.SS  SYNOPSIS
+.nf
+.fam C
+
+$ \fIturnutils_oauth\fP [\fIoptions\fP]
+
+.fam T
+.fi
+.fam T
+.fi
+.SS  DESCRIPTION
+
+\fIturnutils_oauth\fP utilitiy provides help in OAuth access_token encryption and/or 
+decryption with AEAD (Atuthenticated Encryption with Associated Data). It helps 
+for an Auth Server in access_token creation, and also for debuging purposes it 
+helps the access_token validation and decryption. This utility inputs all the 
+keys and lifetimes and any related informations that are needed for encryption 
+or decryption of an access_token. It outputs a JSON with all OAuth PoP 
+parameters that need to pass to the client. Output is generated accoriding 
+RFC7635 Appendix B, Figure 8. This utility could help to build an Auth Server 
+service, but be awere that this utility does not generate "session key" / 
+"mac_key" and not verifies lifetime of "session key" / "mac_key" or "Auth key".
+For more details, and for the access_token structure, read rfc7635, and see
+the example in examples/scripts/oauth.sh.
+.PP
+Use either \fB\-e\fP and/or \fB\-d\fP flag to encrypt or decrypt access_token.
+.PP
+Flags:
+.TP
+.B
+\fB\-h\fP, \fB\-\-help\fP
+usage
+.TP
+.B
+\fB\-v\fP, \fB\-\-verbose\fP
+verbose mode
+.TP
+.B
+\fB\-e\fP, \fB\-\-encrypt\fP
+encrypt token
+.TP
+.B
+\fB\-d\fP, \fB\-\-decrypt\fP
+decrypt validate token
+.PP
+Options with required values:
+.TP
+.B
+\fB\-i\fP, \fB\-\-server\-name\fP
+server name (max. 255 char)
+.TP
+.B
+\fB\-j\fP, \fB\-\-auth\-key\-id\fP
+Auth key id (max. 32 char)
+.TP
+.B
+\fB\-k\fP, \fB\-\-auth\-key\fP
+base64 encoded Auth key
+.TP
+.B
+\fB\-l\fP
+\fB\-\-auth\-key\-timestamp\fP       Auth key timestamp (sec since epoch)
+.TP
+.B
+\fB\-m\fP, \fB\-\-auth\-key\-lifetime\fP
+Auth key lifetime in sec
+.TP
+.B
+\fB\-n\fP, \fB\-\-auth\-key\-as\-rs\-alg\fP
+Authorization \fBServer\fP(AS) \- Resource \fBServer\fP(RS) encryption algorithm
+.TP
+.B
+\fB\-o\fP, \fB\-\-token\-nonce\fP
+base64 encoded nonce \fBbase64\fP(12 octet) = 16 char
+.TP
+.B
+\fB\-p\fP, \fB\-\-token\-mac\-key\fP
+base64 encoded MAC key \fBbase64\fP(32 octet) = 44 char
+.TP
+.B
+\fB\-q\fP, \fB\-\-token\-timestamp\fP
+timestamp in format 64 bit unsigned (Native format \- Unix),
+so 48 bit for secs since epoch UTC + 16 bit for 1/64000 fractions of a second.
+e.g.: the actual unixtimestamp 16 bit left shifted. (Default: actual gmtime)
+.TP
+.B
+\fB\-r\fP, \fB\-\-token\-lifetime\fP
+lifetime in sec (Default: 3600)
+.TP
+.B
+\fB\-t\fP, \fB\-\-token\fP
+base64 encoded encrypted token for validation and decryption
+.TP
+.B
+\fB\-u\fP, \fB\-\-hmac\-alg\fP
+stun client hmac algorithm
+.PP
+Usage:
+.PP
+$ \fIturnutils_natdiscovery\fP
+.PP
 ===================================
 .SH DOCS
 

man/man1/turnutils_oauth.1

@@ -0,0 +1 @@
+turnutils.1