ILIAS  release_5-4 Revision v5.4.26-12-gabc799a52e6
SimpleSAML\Utils\Crypto Class Reference
+ Collaboration diagram for SimpleSAML\Utils\Crypto:

Static Public Member Functions

static aesDecrypt ($ciphertext)
 Decrypt data using AES-256-CBC and the system-wide secret salt as key. More...
 
static aesEncrypt ($data)
 Encrypt data using AES-256-CBC and the system-wide secret salt as key. More...
 
static der2pem ($der, $type='CERTIFICATE')
 Convert data from DER to PEM encoding. More...
 
static loadPrivateKey (\SimpleSAML_Configuration $metadata, $required=false, $prefix='', $full_path=false)
 Load a private key from metadata. More...
 
static loadPublicKey (\SimpleSAML_Configuration $metadata, $required=false, $prefix='')
 Get public key or certificate from metadata. More...
 
static pem2der ($pem)
 Convert from PEM to DER encoding. More...
 
static pwHash ($password, $algorithm, $salt=null)
 This function hashes a password with a given algorithm. More...
 
static secureCompare ($known, $user)
 Compare two strings securely. More...
 
static pwValid ($hash, $password)
 This function checks if a password is valid. More...
 

Detailed Description

Definition at line 10 of file Crypto.php.

Member Function Documentation

◆ aesDecrypt()

static SimpleSAML\Utils\Crypto::aesDecrypt (   $ciphertext)
static

Decrypt data using AES-256-CBC and the system-wide secret salt as key.

Parameters
string$ciphertextThe HMAC of the encrypted data, the IV used and the encrypted data, concatenated.
Returns
string The decrypted data.
Exceptions

InvalidArgumentException If $ciphertext is not a string.

Exceptions

SimpleSAML_Error_Exception If the openssl module is not loaded.

Author
Andreas Solberg, UNINETT AS andre.nosp@m.as.s.nosp@m.olber.nosp@m.g@un.nosp@m.inett.nosp@m..no
Jaime Perez, UNINETT AS jaime.nosp@m..per.nosp@m.ez@un.nosp@m.inet.nosp@m.t.no

Definition at line 81 of file Crypto.php.

82 {
83 return self::_aesDecrypt($ciphertext, Config::getSecretSalt());
84 }
static getSecretSalt()
Retrieve the secret salt.
Definition: Config.php:49

References SimpleSAML\Utils\Config\getSecretSalt().

Referenced by SimpleSAML_Utilities\aesDecrypt().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ aesEncrypt()

static SimpleSAML\Utils\Crypto::aesEncrypt (   $data)
static

Encrypt data using AES-256-CBC and the system-wide secret salt as key.

Parameters
string$dataThe data to encrypt.
Returns
string An HMAC of the encrypted data, the IV and the encrypted data, concatenated.
Exceptions

InvalidArgumentException If $data is not a string.

Exceptions

SimpleSAML_Error_Exception If the openssl module is not loaded.

Author
Andreas Solberg, UNINETT AS andre.nosp@m.as.s.nosp@m.olber.nosp@m.g@un.nosp@m.inett.nosp@m..no
Jaime Perez, UNINETT AS jaime.nosp@m..per.nosp@m.ez@un.nosp@m.inet.nosp@m.t.no

Definition at line 146 of file Crypto.php.

147 {
148 return self::_aesEncrypt($data, Config::getSecretSalt());
149 }
$data
Definition: bench.php:6

References $data, and SimpleSAML\Utils\Config\getSecretSalt().

Referenced by SimpleSAML_Utilities\aesEncrypt(), and SimpleSAML\Utils\HTTP\getSecurePOSTRedirectURL().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ der2pem()

static SimpleSAML\Utils\Crypto::der2pem (   $der,
  $type = 'CERTIFICATE' 
)
static

Convert data from DER to PEM encoding.

Parameters
string$derData encoded in DER format.
string$typeThe type of data we are encoding, as expressed by the PEM header. Defaults to "CERTIFICATE".
Returns
string The same data encoded in PEM format.
See also
RFC7648 for known types and PEM format specifics.

Definition at line 160 of file Crypto.php.

161 {
162 return "-----BEGIN ".$type."-----\n".
163 chunk_split(base64_encode($der), 64, "\n").
164 "-----END ".$type."-----\n";
165 }

Referenced by sspmod_authX509_Auth_Source_X509userCert\authenticate().

+ Here is the caller graph for this function:

◆ loadPrivateKey()

static SimpleSAML\Utils\Crypto::loadPrivateKey ( \SimpleSAML_Configuration  $metadata,
  $required = false,
  $prefix = '',
  $full_path = false 
)
static

Load a private key from metadata.

This function loads a private key from a metadata array. It looks for the following elements:

  • 'privatekey': Name of a private key file in the cert-directory.
  • 'privatekey_pass': Password for the private key.

It returns and array with the following elements:

  • 'PEM': Data for the private key, in PEM-format.
  • 'password': Password for the private key.
Parameters
\SimpleSAML_Configuration$metadataThe metadata array the private key should be loaded from.
bool$requiredWhether the private key is required. If this is true, a missing key will cause an exception. Defaults to false.
string$prefixThe prefix which should be used when reading from the metadata array. Defaults to ''.
bool$full_pathWhether the filename found in the configuration contains the full path to the private key or not. Default to false.
Returns
array|NULL Extracted private key, or NULL if no private key is present.
Exceptions

InvalidArgumentException If $required is not boolean or $prefix is not a string.

Exceptions

SimpleSAML_Error_Exception If no private key is found in the metadata, or it was not possible to load it.

Author
Andreas Solberg, UNINETT AS andre.nosp@m.as.s.nosp@m.olber.nosp@m.g@un.nosp@m.inett.nosp@m..no
Olav Morken, UNINETT AS olav..nosp@m.mork.nosp@m.en@un.nosp@m.inet.nosp@m.t.no

Definition at line 195 of file Crypto.php.

196 {
197 if (!is_bool($required) || !is_string($prefix) || !is_bool($full_path)) {
198 throw new \InvalidArgumentException('Invalid input parameters.');
199 }
200
201 $file = $metadata->getString($prefix.'privatekey', null);
202 if ($file === null) {
203 // no private key found
204 if ($required) {
205 throw new \SimpleSAML_Error_Exception('No private key found in metadata.');
206 } else {
207 return null;
208 }
209 }
210
211 if (!$full_path) {
212 $file = Config::getCertPath($file);
213 }
214
215 $data = @file_get_contents($file);
216 if ($data === false) {
217 throw new \SimpleSAML_Error_Exception('Unable to load private key from file "'.$file.'"');
218 }
219
220 $ret = array(
221 'PEM' => $data,
222 );
223
224 if ($metadata->hasValue($prefix.'privatekey_pass')) {
225 $ret['password'] = $metadata->getString($prefix.'privatekey_pass');
226 }
227
228 return $ret;
229 }
$metadata['__DYNAMIC:1__']
static getCertPath($path)
Resolves a path that may be relative to the cert-directory.
Definition: Config.php:22
$ret
Definition: parser.php:6

References $data, $metadata, $ret, and SimpleSAML\Utils\Config\getCertPath().

Referenced by sspmod_saml_Message\addSign(), sspmod_saml_Message\getDecryptionKeys(), SimpleSAML_Utilities\loadPrivateKey(), and SimpleSAML\Bindings\Shib13\HTTPPost\sendResponse().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ loadPublicKey()

static SimpleSAML\Utils\Crypto::loadPublicKey ( \SimpleSAML_Configuration  $metadata,
  $required = false,
  $prefix = '' 
)
static

Get public key or certificate from metadata.

This function implements a function to retrieve the public key or certificate from a metadata array.

It will search for the following elements in the metadata:

  • 'certData': The certificate as a base64-encoded string.
  • 'certificate': A file with a certificate or public key in PEM-format.
  • 'certFingerprint': The fingerprint of the certificate. Can be a single fingerprint, or an array of multiple valid fingerprints. (deprecated)

This function will return an array with these elements:

  • 'PEM': The public key/certificate in PEM-encoding.
  • 'certData': The certificate data, base64 encoded, on a single line. (Only present if this is a certificate.)
  • 'certFingerprint': Array of valid certificate fingerprints. (Deprecated. Only present if this is a certificate.)
Parameters
\SimpleSAML_Configuration$metadataThe metadata.
bool$requiredWhether the private key is required. If this is TRUE, a missing key will cause an exception. Default is FALSE.
string$prefixThe prefix which should be used when reading from the metadata array. Defaults to ''.
Returns
array|NULL Public key or certificate data, or NULL if no public key or certificate was found.
Exceptions

InvalidArgumentException If $metadata is not an instance of \SimpleSAML_Configuration, $required is not boolean or $prefix is not a string.

Exceptions

SimpleSAML_Error_Exception If no private key is found in the metadata, or it was not possible to load it.

Author
Andreas Solberg, UNINETT AS andre.nosp@m.as.s.nosp@m.olber.nosp@m.g@un.nosp@m.inett.nosp@m..no
Olav Morken, UNINETT AS olav..nosp@m.mork.nosp@m.en@un.nosp@m.inet.nosp@m.t.no
Lasse Birnbaum Jensen

Definition at line 265 of file Crypto.php.

266 {
267 if (!is_bool($required) || !is_string($prefix)) {
268 throw new \InvalidArgumentException('Invalid input parameters.');
269 }
270
271 $keys = $metadata->getPublicKeys(null, false, $prefix);
272 if (!empty($keys)) {
273 foreach ($keys as $key) {
274 if ($key['type'] !== 'X509Certificate') {
275 continue;
276 }
277 if ($key['signing'] !== true) {
278 continue;
279 }
280 $certData = $key['X509Certificate'];
281 $pem = "-----BEGIN CERTIFICATE-----\n".
282 chunk_split($certData, 64).
283 "-----END CERTIFICATE-----\n";
284 $certFingerprint = strtolower(sha1(base64_decode($certData)));
285
286 return array(
287 'certData' => $certData,
288 'PEM' => $pem,
289 'certFingerprint' => array($certFingerprint),
290 );
291 }
292 // no valid key found
293 } elseif ($metadata->hasValue($prefix.'certFingerprint')) {
294 // we only have a fingerprint available
295 $fps = $metadata->getArrayizeString($prefix.'certFingerprint');
296
297 // normalize fingerprint(s) - lowercase and no colons
298 foreach ($fps as &$fp) {
299 assert(is_string($fp));
300 $fp = strtolower(str_replace(':', '', $fp));
301 }
302
303 /*
304 * We can't build a full certificate from a fingerprint, and may as well return an array with only the
305 * fingerprint(s) immediately.
306 */
307 return array('certFingerprint' => $fps);
308 }
309
310 // no public key/certificate available
311 if ($required) {
312 throw new \SimpleSAML_Error_Exception('No public key / certificate found in metadata.');
313 } else {
314 return null;
315 }
316 }
$key
Definition: croninfo.php:18
$keys

References $key, $keys, and $metadata.

Referenced by sspmod_saml_Message\addSign(), SimpleSAML_Utilities\loadPublicKey(), and SimpleSAML\Bindings\Shib13\HTTPPost\sendResponse().

+ Here is the caller graph for this function:

◆ pem2der()

static SimpleSAML\Utils\Crypto::pem2der (   $pem)
static

Convert from PEM to DER encoding.

Parameters
string$pemData encoded in PEM format.
Returns
string The same data encoded in DER format.
Exceptions

InvalidArgumentException If $pem is not encoded in PEM format.

See also
RFC7648 for PEM format specifics.

Definition at line 327 of file Crypto.php.

328 {
329 $pem = trim($pem);
330 $begin = "-----BEGIN ";
331 $end = "-----END ";
332 $lines = explode("\n", $pem);
333 $last = count($lines) - 1;
334
335 if (strpos($lines[0], $begin) !== 0) {
336 throw new \InvalidArgumentException("pem2der: input is not encoded in PEM format.");
337 }
338 unset($lines[0]);
339 if (strpos($lines[$last], $end) !== 0) {
340 throw new \InvalidArgumentException("pem2der: input is not encoded in PEM format.");
341 }
342 unset($lines[$last]);
343
344 return base64_decode(implode($lines));
345 }

References $end.

◆ pwHash()

static SimpleSAML\Utils\Crypto::pwHash (   $password,
  $algorithm,
  $salt = null 
)
static

This function hashes a password with a given algorithm.

Parameters
string$passwordThe password to hash.
string$algorithmThe hashing algorithm, uppercase, optionally prepended with 'S' (salted). See hash_algos() for a complete list of hashing algorithms.
string$saltAn optional salt to use.
Returns
string The hashed password.
Exceptions

InvalidArgumentException If the input parameters are not strings.

Exceptions

SimpleSAML_Error_Exception If the algorithm specified is not supported.

See also
hash_algos()
Author
Dyonisius Visser, TERENA visse.nosp@m.r@te.nosp@m.rena..nosp@m.org
Jaime Perez, UNINETT AS jaime.nosp@m..per.nosp@m.ez@un.nosp@m.inet.nosp@m.t.no

Definition at line 365 of file Crypto.php.

366 {
367 if (!is_string($algorithm) || !is_string($password)) {
368 throw new \InvalidArgumentException('Invalid input parameters.');
369 }
370
371 // hash w/o salt
372 if (in_array(strtolower($algorithm), hash_algos(), true)) {
373 $alg_str = '{'.str_replace('SHA1', 'SHA', $algorithm).'}'; // LDAP compatibility
374 $hash = hash(strtolower($algorithm), $password, true);
375 return $alg_str.base64_encode($hash);
376 }
377
378 // hash w/ salt
379 if ($salt === null) { // no salt provided, generate one
380 // default 8 byte salt, but 4 byte for LDAP SHA1 hashes
381 $bytes = ($algorithm == 'SSHA1') ? 4 : 8;
382 $salt = openssl_random_pseudo_bytes($bytes);
383 }
384
385 if ($algorithm[0] == 'S' && in_array(substr(strtolower($algorithm), 1), hash_algos(), true)) {
386 $alg = substr(strtolower($algorithm), 1); // 'sha256' etc
387 $alg_str = '{'.str_replace('SSHA1', 'SSHA', $algorithm).'}'; // LDAP compatibility
388 $hash = hash($alg, $password.$salt, true);
389 return $alg_str.base64_encode($hash.$salt);
390 }
391
392 throw new \SimpleSAML_Error_Exception('Hashing algorithm \''.strtolower($algorithm).'\' is not supported');
393 }
$password
Definition: cron.php:14
hash(StreamInterface $stream, $algo, $rawOutput=false)
Calculate a hash of a Stream.
Definition: functions.php:406

References $password, and GuzzleHttp\Psr7\hash().

+ Here is the call graph for this function:

◆ pwValid()

static SimpleSAML\Utils\Crypto::pwValid (   $hash,
  $password 
)
static

This function checks if a password is valid.

Parameters
string$hashThe password as it appears in password file, optionally prepended with algorithm.
string$passwordThe password to check in clear.
Returns
boolean True if the hash corresponds with the given password, false otherwise.
Exceptions

InvalidArgumentException If the input parameters are not strings.

Exceptions

SimpleSAML_Error_Exception If the algorithm specified is not supported.

Author
Dyonisius Visser, TERENA visse.nosp@m.r@te.nosp@m.rena..nosp@m.org

Definition at line 440 of file Crypto.php.

441 {
442 if (!is_string($hash) || !is_string($password)) {
443 throw new \InvalidArgumentException('Invalid input parameters.');
444 }
445
446 // match algorithm string (e.g. '{SSHA256}', '{MD5}')
447 if (preg_match('/^{(.*?)}(.*)$/', $hash, $matches)) {
448 // LDAP compatibility
449 $alg = preg_replace('/^(S?SHA)$/', '${1}1', $matches[1]);
450
451 // hash w/o salt
452 if (in_array(strtolower($alg), hash_algos(), true)) {
453 return self::secureCompare($hash, self::pwHash($password, $alg));
454 }
455
456 // hash w/ salt
457 if ($alg[0] === 'S' && in_array(substr(strtolower($alg), 1), hash_algos(), true)) {
458 $php_alg = substr(strtolower($alg), 1);
459
460 // get hash length of this algorithm to learn how long the salt is
461 $hash_length = strlen(hash($php_alg, '', true));
462 $salt = substr(base64_decode($matches[2]), $hash_length);
463 return self::secureCompare($hash, self::pwHash($password, $alg, $salt));
464 }
465 } else {
466 return $hash === $password;
467 }
468
469 throw new \SimpleSAML_Error_Exception('Hashing algorithm \''.strtolower($alg).'\' is not supported');
470 }
static secureCompare($known, $user)
Compare two strings securely.
Definition: Crypto.php:407

◆ secureCompare()

static SimpleSAML\Utils\Crypto::secureCompare (   $known,
  $user 
)
static

Compare two strings securely.

This method checks if two strings are equal in constant time, avoiding timing attacks. Use it every time we need to compare a string with a secret that shouldn't be leaked, i.e. when verifying passwords, one-time codes, etc.

Parameters
string$knownA known string.
string$userA user-provided string to compare with the known string.
Returns
bool True if both strings are equal, false otherwise.

Definition at line 407 of file Crypto.php.

408 {
409 if (function_exists('hash_equals')) {
410 // use hash_equals() if available (PHP >= 5.6)
411 return hash_equals($known, $user);
412 }
413
414 // compare manually in constant time
415 $len = mb_strlen($known, '8bit'); // see mbstring.func_overload
416 if ($len !== mb_strlen($user, '8bit')) {
417 return false; // length differs
418 }
419 $diff = 0;
420 for ($i = 0; $i < $len; $i++) {
421 $diff |= ord($known[$i]) ^ ord($user[$i]);
422 }
423 // if all the bytes in $a and $b are identical, $diff should be equal to 0
424 return $diff === 0;
425 }
$i
Definition: disco.tpl.php:19
$user
Definition: migrateto20.php:57

The documentation for this class was generated from the following file: