Subversion Repositories oidplus

Compare Revisions

Regard whitespace Rev 1281 → Rev 1282

/trunk/doc/developer_notes/server_secret.md
4,48 → 4,76
 
In the base configuration, you will see something like this:
 
OIDplus::baseConfig()->setValue('SERVER_SECRET', '................................');
OIDplus::baseConfig()->setValue("SERVER_SECRET", "................................");
 
This value is chosen randomly by the configuration file generator (setup).
 
Where is SERVER_SECRET being used?
----------------------------------
Derivation of secrets and auth keys
-----------------------------------
 
System:
Important: 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()`.
This auth key is NOT temporary by default so you need to make sure
that you encode a timestamp in it.
 
Implementation
--------------
 
`makeAuthKey(data) = makeSecret(data) = sha3_512_hmac(data, "OIDplus:" + SERVER_SECRET)`
 
Currently, the implementation of `makeAuthKey` and `makeSecret`
is the same, but you should only use `makeAuthKey`
if you combine it with `validateAuthKey`, otherwise, you
should use `makeSecret`. This makes the code easier to understand.
 
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 and logins with "Remember me") using PBKDF2+HMAC
(ONLY if the server does not have a Public/Private key pair!)
`JWT = HS512(hash_pbkdf2('sha512', SERVER_SECRET+"/OIDplusAuthContentStoreJWT", '', 10000, 64/*256bit*/, false))`
Key to sign JWT tokens (used for Automated AJAX requests, REST API and logins with "Remember me") using PBKDF2+HMAC
* If a private/public key pair exists: Sign the JWT using that private key.
* Otherwise sign it with:
`JWT = HS512(hash_pbkdf2("sha512", OIDplus::authUtils()->makeSecret("0be35e52-f4ef-11ed-b67e-3c4a92df8582"), "", 10000, 64/*256bit*/, false))`
- 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
- Auth utils: Generation of auth keys
`makeAuthKey(data) = sha3_512_hmac(data, "authkey:"+SERVER_SECRET);`
used at plugin forgot RA password (public/091):
`makeAuthKey("reset_password;" + email + ";" + timestamp)
= sha3_512_hmac("reset_password;" + email + ";" + timestamp, "authkey:"+SERVER_SECRET);`
used at plugin ViaThinkSoft FreeOID activation (public/200):
`makeAuthKey("com.viathinksoft.freeoid.activate_freeoid;" + email + ";" + timestamp)
= sha3_512_hmac("com.viathinksoft.freeoid.activate_freeoid;" + email + ";" + timestamp, "authkey:"+SERVER_SECRET);`
used at plugin invite RA (ra/092):
`makeAuthKey("activate_ra;" + email + ";" + timestamp)
= sha3_512_hmac("activate_ra;" + email + ";" + timestamp, "authkey:"+SERVER_SECRET);`
used at plugin change RA email (ra/102):
`makeAuthKey("activate_new_ra_email;" + old_email + ";" + new_email + ";" + timestamp)
= sha3_512_hmac("activate_new_ra_email;" + old_email + ";" + new_email + ";" + timestamp, "authkey:"+SERVER_SECRET);`
* 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")`.
 
Plugin WHOIS (public/100):
- Authentication token for hidden OIDs = `smallhash(SERVER_SECRET + "/WHOIS/" + id);`
Temporary auth keys (sent via email etc.):
* used at plugin forgot RA password (public/091):
`makeAuthKey("93a16dbe-f4fb-11ed-b67e-3c4a92df8582:" + email + "/" + timestamp)`
* used at plugin ViaThinkSoft FreeOID activation (public/200):
`makeAuthKey("40c87e20-f4fb-11ed-86ca-3c4a92df8582:" + email + "/" + timestamp)`
* used at plugin invite RA (ra/092):
`makeAuthKey("ed840c3e-f4fa-11ed-b67e-3c4a92df8582:" + email + "/" + timestamp)`
* used at plugin change RA email (ra/102):
`makeAuthKey("5ef24124-f4fb-11ed-b67e-3c4a92df8582:" + old_email + "/" + new_email + "/" + timestamp)`
 
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 = `sha3_512(SERVER_SECRET + "/VNAG")`
- 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
 
Important: Please never use SERVER_SECRET alone for any hashing/HMAC without adding any context to it.
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"`
 
- Example: Bad `hmac(message, SERVER_SECRET)`
- Example: Good `hmac(message, 'xyz:'.SERVER_SECRET)`
GUID Registry
-------------
 
Reason: Since the SERVER_SECRET is used at many different places, we must make sure that the calculated values do not reveal information about the SERVER_SECRET in any kind.
The "real GUIDs" are documented at the [ViaThinkSoft OIDplus Registration Authority](https://oidplus.viathinksoft.com/oidplus/?goto=guid%3Aoidplus%2FauthRealms).