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

$ciphertext

The HMAC of the encrypted data, the IV used and the encrypted data, concatenated.

Returns

string The decrypted data.

Exceptions

Definition at line 81 of file Crypto.php.

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

Referenced by SimpleSAML_Utilities\aesDecrypt().

    {
        return self::_aesDecrypt($ciphertext, Config::getSecretSalt());
    }

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

$data

The data to encrypt.

Returns

string An HMAC of the encrypted data, the IV and the encrypted data, concatenated.

Exceptions

Definition at line 146 of file Crypto.php.

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

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

    {
        return self::_aesEncrypt($data, Config::getSecretSalt());
    }

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	$der	Data encoded in DER format.
string	$type	The 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.

Referenced by sspmod_authX509_Auth_Source_X509userCert\authenticate().

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

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	$metadata	The metadata array the private key should be loaded from.
bool	$required	Whether the private key is required. If this is true, a missing key will cause an exception. Defaults to false.
string	$prefix	The prefix which should be used when reading from the metadata array. Defaults to ''.
bool	$full_path	Whether 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

Definition at line 195 of file Crypto.php.

References $data, $file, $ret, array, SimpleSAML\Utils\Config\getCertPath(), SimpleSAML_Configuration\getString(), and SimpleSAML_Configuration\hasValue().

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

    {
        if (!is_bool($required) || !is_string($prefix) || !is_bool($full_path)) {
            throw new \InvalidArgumentException('Invalid input parameters.');
        }

        $file = $metadata->getString($prefix.'privatekey', null);
        if ($file === null) {
            // no private key found
            if ($required) {
                throw new \SimpleSAML_Error_Exception('No private key found in metadata.');
            } else {
                return null;
            }
        }

        if (!$full_path) {
            $file = Config::getCertPath($file);
        }

        $data = @file_get_contents($file);
        if ($data === false) {
            throw new \SimpleSAML_Error_Exception('Unable to load private key from file "'.$file.'"');
        }

        $ret = array(
            'PEM' => $data,
        );

        if ($metadata->hasValue($prefix.'privatekey_pass')) {
            $ret['password'] = $metadata->getString($prefix.'privatekey_pass');
        }

        return $ret;
    }

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	$metadata	The metadata.
bool	$required	Whether the private key is required. If this is TRUE, a missing key will cause an exception. Default is FALSE.
string	$prefix	The 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

Definition at line 265 of file Crypto.php.

References $key, $keys, array, SimpleSAML_Configuration\getArrayizeString(), SimpleSAML_Configuration\getPublicKeys(), and SimpleSAML_Configuration\hasValue().

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

    {
        if (!is_bool($required) || !is_string($prefix)) {
            throw new \InvalidArgumentException('Invalid input parameters.');
        }

        $keys = $metadata->getPublicKeys(null, false, $prefix);
        if ($keys !== null) {
            foreach ($keys as $key) {
                if ($key['type'] !== 'X509Certificate') {
                    continue;
                }
                if ($key['signing'] !== true) {
                    continue;
                }
                $certData = $key['X509Certificate'];
                $pem = "-----BEGIN CERTIFICATE-----\n".
                    chunk_split($certData, 64).
                    "-----END CERTIFICATE-----\n";
                $certFingerprint = strtolower(sha1(base64_decode($certData)));

                return array(
                    'certData'        => $certData,
                    'PEM'             => $pem,
                    'certFingerprint' => array($certFingerprint),
                );
            }
            // no valid key found
        } elseif ($metadata->hasValue($prefix.'certFingerprint')) {
            // we only have a fingerprint available
            $fps = $metadata->getArrayizeString($prefix.'certFingerprint');

            // normalize fingerprint(s) - lowercase and no colons
            foreach ($fps as &$fp) {
                assert('is_string($fp)');
                $fp = strtolower(str_replace(':', '', $fp));
            }

            /*
             * We can't build a full certificate from a fingerprint, and may as well return an array with only the
             * fingerprint(s) immediately.
             */
            return array('certFingerprint' => $fps);
        }

        // no public key/certificate available
        if ($required) {
            throw new \SimpleSAML_Error_Exception('No public key / certificate found in metadata.');
        } else {
            return null;
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

pem2der()

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

static

Convert from PEM to DER encoding.

Parameters

string

$pem

Data encoded in PEM format.

Returns

string The same data encoded in DER format.

Exceptions

Definition at line 327 of file Crypto.php.

References $end.

    {
        $pem   = trim($pem);
        $begin = "-----BEGIN ";
        $end   = "-----END ";
        $lines = explode("\n", $pem);
        $last  = count($lines) - 1;

        if (strpos($lines[0], $begin) !== 0) {
            throw new \InvalidArgumentException("pem2der: input is not encoded in PEM format.");
        }
        unset($lines[0]);
        if (strpos($lines[$last], $end) !== 0) {
            throw new \InvalidArgumentException("pem2der: input is not encoded in PEM format.");
        }
        unset($lines[$last]);

        return base64_decode(implode($lines));
    }

pwHash()

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

static

This function hashes a password with a given algorithm.

Parameters

string	$password	The password to hash.
string	$algorithm	The hashing algorithm, uppercase, optionally prepended with 'S' (salted). See hash_algos() for a complete list of hashing algorithms.
string	$salt	An optional salt to use.

Returns

string The hashed password.

Exceptions

Definition at line 365 of file Crypto.php.

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

    {
        if (!is_string($algorithm) || !is_string($password)) {
            throw new \InvalidArgumentException('Invalid input parameters.');
        }

        // hash w/o salt
        if (in_array(strtolower($algorithm), hash_algos(), true)) {
            $alg_str = '{'.str_replace('SHA1', 'SHA', $algorithm).'}'; // LDAP compatibility
            $hash = hash(strtolower($algorithm), $password, true);
            return $alg_str.base64_encode($hash);
        }

        // hash w/ salt
        if ($salt === null) { // no salt provided, generate one
            // default 8 byte salt, but 4 byte for LDAP SHA1 hashes
            $bytes = ($algorithm == 'SSHA1') ? 4 : 8;
            $salt = openssl_random_pseudo_bytes($bytes);
        }

        if ($algorithm[0] == 'S' && in_array(substr(strtolower($algorithm), 1), hash_algos(), true)) {
            $alg = substr(strtolower($algorithm), 1); // 'sha256' etc
            $alg_str = '{'.str_replace('SSHA1', 'SSHA', $algorithm).'}'; // LDAP compatibility
            $hash = hash($alg, $password.$salt, true);
            return $alg_str.base64_encode($hash.$salt);
        }

        throw new \SimpleSAML_Error_Exception('Hashing algorithm \''.strtolower($algorithm).'\' is not supported');
    }

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	$hash	The password as it appears in password file, optionally prepended with algorithm.
string	$password	The password to check in clear.

Returns

boolean True if the hash corresponds with the given password, false otherwise.

Exceptions

Definition at line 440 of file Crypto.php.

    {
        if (!is_string($hash) || !is_string($password)) {
            throw new \InvalidArgumentException('Invalid input parameters.');
        }

        // match algorithm string (e.g. '{SSHA256}', '{MD5}')
        if (preg_match('/^{(.*?)}(.*)$/', $hash, $matches)) {
            // LDAP compatibility
            $alg = preg_replace('/^(S?SHA)$/', '${1}1', $matches[1]);

            // hash w/o salt
            if (in_array(strtolower($alg), hash_algos(), true)) {
                return self::secureCompare($hash, self::pwHash($password, $alg));
            }

            // hash w/ salt
            if ($alg[0] === 'S' && in_array(substr(strtolower($alg), 1), hash_algos(), true)) {
                $php_alg = substr(strtolower($alg), 1);

                // get hash length of this algorithm to learn how long the salt is
                $hash_length = strlen(hash($php_alg, '', true));
                $salt = substr(base64_decode($matches[2]), $hash_length);
                return self::secureCompare($hash, self::pwHash($password, $alg, $salt));
            }
        } else {
            return $hash === $password;
        }

        throw new \SimpleSAML_Error_Exception('Hashing algorithm \''.strtolower($alg).'\' is not supported');
    }

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	$known	A known string.
string	$user	A 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.

    {
        if (function_exists('hash_equals')) {
            // use hash_equals() if available (PHP >= 5.6)
            return hash_equals($known, $user);
        }

        // compare manually in constant time
        $len = mb_strlen($known, '8bit'); // see mbstring.func_overload
        if ($len !== mb_strlen($user, '8bit')) {
            return false; // length differs
        }
        $diff = 0;
        for ($i = 0; $i < $len; $i++) {
            $diff |= ord($known[$i]) ^ ord($user[$i]);
        }
        // if all the bytes in $a and $b are identical, $diff should be equal to 0
        return $diff === 0;
    }

---

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

• libs/composer/vendor/simplesamlphp/simplesamlphp/lib/SimpleSAML/Utils/Crypto.php