WebSVN – oidplus – Diff – /trunk/doc/developer_notes/server_secret.md


 
SERVER_SECRET
=============
 
In the base configuration, you will see something like this:
 
    OIDplus::baseConfig()->setValue("SERVER_SECRET", "................................");
 
This value is chosen randomly by the configuration file generator (setup).
 
Derivation of secrets and auth keys
-----------------------------------
 
The usage of `OIDplus::baseConfig()->getValue("SERVER_SECRET")`
is deprecated due to security considerations.
 
Instead, please always use `OIDplus::authUtils()->makeSecret()`
with a unique `$data` argument (prefer a GUID)
if you need a secret that is derived from the server secret.
 
If you want to generate an authentication key (e.g. to send via an email),
use `OIDplus::authUtils()->makeAuthKey()`
with a unique `$data` argument (prefer a GUID)
in combination with `OIDplus::authUtils()->validateAuthKey()`.
An auth key is usually temporary; therefore `makeAuthKey` encodes a timestamp
which can be checked by `validateAuthKey` by providing
a validity period in seconds.
 
Where are makeAuthKey and makeSecret being used?
------------------------------------------------
 
System / Core:
- Auth content Store (OIDplusAuthContentStoreJWT.class.php):
  Key to sign JWT tokens (used for Automated AJAX requests, REST API and logins with "Remember me")
  * If a private/public key pair exists: Sign the JWT using that private key.
  * Otherwise sign it using PBKDF2+HMAC:
    `JWT = HS512(hash_pbkdf2("sha512", OIDplus::authUtils()->makeSecret(["0be35e52-f4ef-11ed-b67e-3c4a92df8582"]), "", 10000, 64/*256bit*/, false))`
- The JWT additionally contains a member `oidplus_ssh = OIDplus::authUtils()->makeSecret(["bb1aebd6-fe6a-11ed-a553-3c4a92df8582"]` (SSH = Server Secret Hash)
  with the sole purpose of allowing to invalidate all issued JWT by changing the server secret.
  (This would be more secure than the Blacklist feature, since changing the server secret)
  also invalidates JWT which might have been maliciously postdated).
- Session Handler (OIDplusSessionHandler.class.php):
  Encryption of session contents (regular logins)
  * if OpenSSL is installed:        sha512-pbkdf2 + AES-256-CBC + sha3-512-hmac
  * if OpenSSL is not installed:    sha3-512-hmac
  * In both cases, the key is `OIDplus::authUtils()->makeSecret(["b118abc8-f4ec-11ed-86ca-3c4a92df8582"])`.
 
Temporary auth keys (sent via email etc.):
* used at plugin forgot RA password (public/091):
  `makeAuthKey(["93a16dbe-f4fb-11ed-b67e-3c4a92df8582", email])`
* used at plugin ViaThinkSoft FreeOID activation (public/200):
  `makeAuthKey(["40c87e20-f4fb-11ed-86ca-3c4a92df8582", email])`
* used at plugin invite RA (ra/092):
  `makeAuthKey(["ed840c3e-f4fa-11ed-b67e-3c4a92df8582", email])`
* used at plugin change RA email (ra/102):
  `makeAuthKey(["5ef24124-f4fb-11ed-b67e-3c4a92df8582", old_email, new_email])`
 
Plugin OID-IP (public/100):
- Authentication token for hidden OIDs = `smallhash(OIDplus::authUtils()->makeSecret(["d8f44c7c-f4e9-11ed-86ca-3c4a92df8582", id]))`
 
Plugin VNag version check (admin/901):
- Webreader password = `OIDplus::authUtils()->makeSecret(["65d9f488-f4eb-11ed-b67e-3c4a92df8582"])`
 
Plugin RDAP (frdl):
- `OIDplus::authUtils()->makeSecret(["cee75760-f4f8-11ed-b67e-3c4a92df8582"])` is used to generate a cache filename
 
Plugin VTS Client Challenge Captcha:
- Challenge integrity : `OIDplus::authUtils()->makeAuthKey(["797bfc34-f4fa-11ed-86ca-3c4a92df8582", challenge])`
- Cache filename : `"vts_client_challenge_" + OIDplus::authUtils()->makeSecret(["461f4a9e-f4fa-11ed-86ca-3c4a92df8582", ipTarget, random]) + ".tmp"`
 
GUID Registry
-------------
 
The "realm GUIDs" are documented at the [ViaThinkSoft OIDplus Registration Authority](https://oidplus.viathinksoft.com/oidplus/?goto=guid%3Aoidplus%2FauthRealms). 

Subversion Repositories oidplus

oidplus/trunk/doc/developer_notes/server_secret.md – Rev 1283 → 1298

Rev 1283		Rev 1298
1		1
2	SERVER_SECRET	2	SERVER_SECRET
3	=============	3	=============
4		4
5	In the base configuration, you will see something like this:	5	In the base configuration, you will see something like this:
6		6
7	OIDplus::baseConfig()->setValue("SERVER_SECRET", "................................");	7	OIDplus::baseConfig()->setValue("SERVER_SECRET", "................................");
8		8
9	This value is chosen randomly by the configuration file generator (setup).	9	This value is chosen randomly by the configuration file generator (setup).
10		10
11	Derivation of secrets and auth keys	11	Derivation of secrets and auth keys
12	-----------------------------------	12	-----------------------------------
13		13
14	The usage of `OIDplus::baseConfig()->getValue("SERVER_SECRET")`	14	The usage of `OIDplus::baseConfig()->getValue("SERVER_SECRET")`
15	is deprecated due to security considerations.	15	is deprecated due to security considerations.
16		16
17	Instead, please always use `OIDplus::authUtils()->makeSecret()`	17	Instead, please always use `OIDplus::authUtils()->makeSecret()`
18	with a unique `$data` argument (prefer a GUID)	18	with a unique `$data` argument (prefer a GUID)
19	if you need a secret that is derived from the server secret.	19	if you need a secret that is derived from the server secret.
20		20
21	If you want to generate an authentication key (e.g. to send via an email),	21	If you want to generate an authentication key (e.g. to send via an email),
22	use `OIDplus::authUtils()->makeAuthKey()`	22	use `OIDplus::authUtils()->makeAuthKey()`
23	with a unique `$data` argument (prefer a GUID)	23	with a unique `$data` argument (prefer a GUID)
24	in combination with `OIDplus::authUtils()->validateAuthKey()`.	24	in combination with `OIDplus::authUtils()->validateAuthKey()`.
25	An auth key is usually temporary; therefore `makeAuthKey` encodes a timestamp	25	An auth key is usually temporary; therefore `makeAuthKey` encodes a timestamp
26	which can be checked by `validateAuthKey` by providing	26	which can be checked by `validateAuthKey` by providing
27	a validity period in seconds.	27	a validity period in seconds.
28		28
29	Where are makeAuthKey and makeSecret being used?	29	Where are makeAuthKey and makeSecret being used?
30	------------------------------------------------	30	------------------------------------------------
31		31
32	System / Core:	32	System / Core:
33	- Auth content Store (OIDplusAuthContentStoreJWT.class.php):	33	- Auth content Store (OIDplusAuthContentStoreJWT.class.php):
34	Key to sign JWT tokens (used for Automated AJAX requests, REST API and logins with "Remember me")	34	Key to sign JWT tokens (used for Automated AJAX requests, REST API and logins with "Remember me")
35	* If a private/public key pair exists: Sign the JWT using that private key.	35	* If a private/public key pair exists: Sign the JWT using that private key.
36	* Otherwise sign it using PBKDF2+HMAC:	36	* Otherwise sign it using PBKDF2+HMAC:
37	`JWT = HS512(hash_pbkdf2("sha512", OIDplus::authUtils()->makeSecret(["0be35e52-f4ef-11ed-b67e-3c4a92df8582"]), "", 10000, 64/256bit/, false))`	37	`JWT = HS512(hash_pbkdf2("sha512", OIDplus::authUtils()->makeSecret(["0be35e52-f4ef-11ed-b67e-3c4a92df8582"]), "", 10000, 64/256bit/, false))`
-		38	- The JWT additionally contains a member `oidplus_ssh = OIDplus::authUtils()->makeSecret(["bb1aebd6-fe6a-11ed-a553-3c4a92df8582"]` (SSH = Server Secret Hash)
-		39	with the sole purpose of allowing to invalidate all issued JWT by changing the server secret.
-		40	(This would be more secure than the Blacklist feature, since changing the server secret)
-		41	also invalidates JWT which might have been maliciously postdated).
38	- Session Handler (OIDplusSessionHandler.class.php):	42	- Session Handler (OIDplusSessionHandler.class.php):
39	Encryption of session contents (regular logins)	43	Encryption of session contents (regular logins)
40	* if OpenSSL is installed: sha512-pbkdf2 + AES-256-CBC + sha3-512-hmac	44	* if OpenSSL is installed: sha512-pbkdf2 + AES-256-CBC + sha3-512-hmac
41	* if OpenSSL is not installed: sha3-512-hmac	45	* if OpenSSL is not installed: sha3-512-hmac
42	* In both cases, the key is `OIDplus::authUtils()->makeSecret(["b118abc8-f4ec-11ed-86ca-3c4a92df8582"])`.	46	* In both cases, the key is `OIDplus::authUtils()->makeSecret(["b118abc8-f4ec-11ed-86ca-3c4a92df8582"])`.
43		47
44	Temporary auth keys (sent via email etc.):	48	Temporary auth keys (sent via email etc.):
45	* used at plugin forgot RA password (public/091):	49	* used at plugin forgot RA password (public/091):
46	`makeAuthKey(["93a16dbe-f4fb-11ed-b67e-3c4a92df8582", email])`	50	`makeAuthKey(["93a16dbe-f4fb-11ed-b67e-3c4a92df8582", email])`
47	* used at plugin ViaThinkSoft FreeOID activation (public/200):	51	* used at plugin ViaThinkSoft FreeOID activation (public/200):
48	`makeAuthKey(["40c87e20-f4fb-11ed-86ca-3c4a92df8582", email])`	52	`makeAuthKey(["40c87e20-f4fb-11ed-86ca-3c4a92df8582", email])`
49	* used at plugin invite RA (ra/092):	53	* used at plugin invite RA (ra/092):
50	`makeAuthKey(["ed840c3e-f4fa-11ed-b67e-3c4a92df8582", email])`	54	`makeAuthKey(["ed840c3e-f4fa-11ed-b67e-3c4a92df8582", email])`
51	* used at plugin change RA email (ra/102):	55	* used at plugin change RA email (ra/102):
52	`makeAuthKey(["5ef24124-f4fb-11ed-b67e-3c4a92df8582", old_email, new_email])`	56	`makeAuthKey(["5ef24124-f4fb-11ed-b67e-3c4a92df8582", old_email, new_email])`
53		57
54	Plugin OID-IP (public/100):	58	Plugin OID-IP (public/100):
55	- Authentication token for hidden OIDs = `smallhash(OIDplus::authUtils()->makeSecret(["d8f44c7c-f4e9-11ed-86ca-3c4a92df8582", id]))`	59	- Authentication token for hidden OIDs = `smallhash(OIDplus::authUtils()->makeSecret(["d8f44c7c-f4e9-11ed-86ca-3c4a92df8582", id]))`
56		60
57	Plugin VNag version check (admin/901):	61	Plugin VNag version check (admin/901):
58	- Webreader password = `OIDplus::authUtils()->makeSecret(["65d9f488-f4eb-11ed-b67e-3c4a92df8582"])`	62	- Webreader password = `OIDplus::authUtils()->makeSecret(["65d9f488-f4eb-11ed-b67e-3c4a92df8582"])`
59		63
60	Plugin RDAP (frdl):	64	Plugin RDAP (frdl):
61	- `OIDplus::authUtils()->makeSecret(["cee75760-f4f8-11ed-b67e-3c4a92df8582"])` is used to generate a cache filename	65	- `OIDplus::authUtils()->makeSecret(["cee75760-f4f8-11ed-b67e-3c4a92df8582"])` is used to generate a cache filename
62		66
63	Plugin VTS Client Challenge Captcha:	67	Plugin VTS Client Challenge Captcha:
64	- Challenge integrity : `OIDplus::authUtils()->makeAuthKey(["797bfc34-f4fa-11ed-86ca-3c4a92df8582", challenge])`	68	- Challenge integrity : `OIDplus::authUtils()->makeAuthKey(["797bfc34-f4fa-11ed-86ca-3c4a92df8582", challenge])`
65	- Cache filename : `"vts_client_challenge_" + OIDplus::authUtils()->makeSecret(["461f4a9e-f4fa-11ed-86ca-3c4a92df8582", ipTarget, random]) + ".tmp"`	69	- Cache filename : `"vts_client_challenge_" + OIDplus::authUtils()->makeSecret(["461f4a9e-f4fa-11ed-86ca-3c4a92df8582", ipTarget, random]) + ".tmp"`
66		70
67	GUID Registry	71	GUID Registry
68	-------------	72	-------------
69		73
70	The "realm GUIDs" are documented at the [ViaThinkSoft OIDplus Registration Authority](https://oidplus.viathinksoft.com/oidplus/?goto=guid%3Aoidplus%2FauthRealms).	74	The "realm GUIDs" are documented at the [ViaThinkSoft OIDplus Registration Authority](https://oidplus.viathinksoft.com/oidplus/?goto=guid%3Aoidplus%2FauthRealms).