From 14754ce43bf15910717ee1e41b66027fe6e3c3a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9sz=C3=A1ros=20Mih=C3=A1ly?= Date: Tue, 6 Sep 2016 11:19:51 +0200 Subject: [PATCH] Add turnutils_oauth to README.turnutils --- README.turnutils | 75 +++++++++++++++++++++++ make-man.sh | 7 ++- man/man1/turnadmin.1 | 2 +- man/man1/turnserver.1 | 2 +- man/man1/turnutils.1 | 119 ++++++++++++++++++++++++++++++++++++- man/man1/turnutils_oauth.1 | 1 + 6 files changed, 200 insertions(+), 6 deletions(-) create mode 120000 man/man1/turnutils_oauth.1 diff --git a/README.turnutils b/README.turnutils index 6024944..a5d7bdf 100644 --- a/README.turnutils +++ b/README.turnutils @@ -37,6 +37,16 @@ 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. + + ===================================== NAME @@ -271,6 +281,71 @@ 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. For more details, and for the access_token +structure, read rfc7635. + +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, --long-term-key-id long term key id (max. 32 char) + +-k, --long-term-key base64 encoded long term key + +-l --long-term-key-timestamp long term key timestamp (sec since epoch) + +-m, --long-term-key-lifetime long term key lifetime in sec + +-n, --long-term-key-as-rs-alg Authorization Server Resource Server 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. + An example: 16 bit left shift the unixtimestamp. (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 diff --git a/make-man.sh b/make-man.sh index 704c19e..185ae15 100755 --- a/make-man.sh +++ b/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 ../.. diff --git a/man/man1/turnadmin.1 b/man/man1/turnadmin.1 index f246a0d..746254a 100644 --- a/man/man1/turnadmin.1 +++ b/man/man1/turnadmin.1 @@ -1,5 +1,5 @@ .\" Text automatically generated by txt2man -.TH TURN 1 "04 September 2016" "" "" +.TH TURN 1 "06 September 2016" "" "" .SH GENERAL INFORMATION \fIturnadmin\fP is a TURN administration tool. This tool can be used to manage diff --git a/man/man1/turnserver.1 b/man/man1/turnserver.1 index 560a1c8..bd4d717 100644 --- a/man/man1/turnserver.1 +++ b/man/man1/turnserver.1 @@ -1,5 +1,5 @@ .\" Text automatically generated by txt2man -.TH TURN 1 "04 September 2016" "" "" +.TH TURN 1 "06 September 2016" "" "" .SH GENERAL INFORMATION The \fBTURN Server\fP project contains the source code of a TURN server and TURN client diff --git a/man/man1/turnutils.1 b/man/man1/turnutils.1 index ee7a558..218a8e3 100644 --- a/man/man1/turnutils.1 +++ b/man/man1/turnutils.1 @@ -1,5 +1,5 @@ .\" Text automatically generated by txt2man -.TH TURN 1 "04 September 2016" "" "" +.TH TURN 1 "06 September 2016" "" "" .SH GENERAL INFORMATION A set of turnutils_* programs provides some utility functionality to be used @@ -48,7 +48,21 @@ $ ./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. +.RE +.PP + +.RS ===================================== .SS NAME \fB @@ -414,6 +428,109 @@ 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. For more details, and for the access_token +structure, read rfc7635. +.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\-\-long\-term\-key\-id\fP +long term key id (max. 32 char) +.TP +.B +\fB\-k\fP, \fB\-\-long\-term\-key\fP +base64 encoded long term key +.TP +.B +\fB\-l\fP +\fB\-\-long\-term\-key\-timestamp\fP long term key timestamp (sec since epoch) +.TP +.B +\fB\-m\fP, \fB\-\-long\-term\-key\-lifetime\fP +long term key lifetime in sec +.TP +.B +\fB\-n\fP, \fB\-\-long\-term\-key\-as\-rs\-alg\fP +Authorization Server Resource Server 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. +An example: 16 bit left shift the unixtimestamp. (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 diff --git a/man/man1/turnutils_oauth.1 b/man/man1/turnutils_oauth.1 new file mode 120000 index 0000000..6996d67 --- /dev/null +++ b/man/man1/turnutils_oauth.1 @@ -0,0 +1 @@ +turnutils.1 \ No newline at end of file