*/ private $ctx; /** * @param array{site_id: string, issuer: string, keys: array, epoch: int, generation: int, now: callable|int, jti_store: object} $ctx */ public function __construct( array $ctx ) { $this->ctx = array_merge( array( 'clock_skew_seconds' => Constants::CLOCK_SKEW_SECONDS ), $ctx ); } /** * @return Result Result, payload: array, msg: array}> */ public function verify( string $token ): Result { $skew = (int) $this->ctx['clock_skew_seconds']; $now = (int) ( is_callable( $this->ctx['now'] ) ? call_user_func( $this->ctx['now'] ) : $this->ctx['now'] ); $jws = Jws::verify( $token, Constants::CONTROL_TYP, $this->ctx['keys'] ); if ( ! $jws->isOk() ) { return $jws; } /** @var JsonObject $p */ $p = $jws->value()['payload']; $generation = $p->get( 'generation' ); if ( ! is_int( $generation ) || $generation < 0 ) { return Result::err( 'claim_type', 'generation is a non-negative integer' ); } $names = $p->keys(); sort( $names ); $wanted = self::MEMBERS; sort( $wanted ); if ( $names !== $wanted ) { return Result::err( 'claim_type', 'a control message carries exactly ' . implode( ', ', self::MEMBERS ) ); } $v = $p->get( 'v' ); if ( ! is_int( $v ) || $v < 1 ) { return Result::err( 'claim_type', 'v is a positive integer' ); } if ( ! is_string( $p->get( 'iss' ) ) || ! hash_equals( (string) $this->ctx['issuer'], $p->get( 'iss' ) ) ) { return Result::err( 'iss_mismatch', 'iss is not the issuer stored at pairing' ); } $aud = $p->get( 'aud' ); if ( ! is_string( $aud ) || ! hash_equals( Constants::AUD_PREFIX . $this->ctx['site_id'], $aud ) ) { return Result::err( 'aud_mismatch', 'the message is not for this site' ); } $jti = $p->get( 'jti' ); if ( ! is_string( $jti ) || 1 !== preg_match( Constants::JTI_PATTERN, $jti ) ) { return Result::err( 'jti_malformed', 'jti is 32 lowercase hex characters' ); } $iat = $p->get( 'iat' ); $exp = $p->get( 'exp' ); if ( ! is_int( $iat ) || ! is_int( $exp ) ) { return Result::err( 'claim_type', 'iat and exp are Unix second counts' ); } if ( $exp <= $iat || $exp - $iat > Constants::CONTROL_MAX_TTL_SECONDS ) { return Result::err( 'ttl_exceeded', 'exp - iat must be 1 to ' . Constants::CONTROL_MAX_TTL_SECONDS . ' seconds' ); } if ( $now >= $exp ) { return Result::err( 'expired', 'the control message has expired' ); } if ( $now < $iat - $skew ) { return Result::err( 'not_yet_valid', 'the control message was issued in the future' ); } // The generation before the epoch (section 7.2): a message for a binding // this site no longer holds is refused for that, whatever its epoch. if ( $generation !== (int) $this->ctx['generation'] ) { return Result::err( 'generation_mismatch', 'generation ' . $generation . ' is not this site\'s ' . (int) $this->ctx['generation'] ); } $epoch = $p->get( 'epoch' ); if ( ! is_int( $epoch ) || $epoch < 0 ) { return Result::err( 'claim_type', 'epoch is a non-negative integer' ); } $fence = (int) $this->ctx['epoch']; if ( $epoch < $fence ) { return Result::err( 'epoch_stale', 'epoch ' . $epoch . ' is below the stored ' . $fence ); } $msg = Message::validate( $p->get( 'msg' ) ); if ( ! $msg->isOk() ) { return $msg; } $header = $jws->value()['header']; if ( 'key.install' === $msg->value()['kind'] ) { // The signer re-installing its own key under a new name would hold // two of the two slots with one secret, and could then retire the // sibling it was meant to sit beside. $incoming = \Pielyt\Crypto\Keys::parsePublicKey( $msg->value()['public_key'] ); $signer = $this->ctx['keys'][ $header['kid'] ] ?? null; if ( $incoming->isOk() && is_string( $signer ) && hash_equals( $signer, $incoming->value() ) ) { return Result::err( 'key_proof_invalid', 'the incoming key is the key signing its install' ); } $proof = self::verifyKeyProof( $msg->value()['proof'], $msg->value()['public_key'], $msg->value()['kid'], $header['kid'], $aud, $generation, $jti ); if ( ! $proof->isOk() ) { return $proof; } } try { $consumed = $this->ctx['jti_store']->consume( $jti, $exp ); } catch ( \RuntimeException $e ) { return Result::err( 'jti_store_unavailable', 'the replay store could not answer' ); } if ( ! $consumed ) { return Result::err( 'jti_replayed', $jti . ' has already been used' ); } return Result::ok( array( 'header' => $header, 'payload' => array( 'v' => $v, 'iss' => $p->get( 'iss' ), 'aud' => $aud, 'jti' => $jti, 'iat' => $iat, 'exp' => $exp, 'epoch' => $epoch, 'generation' => $generation, ), 'msg' => $msg->value(), ) ); } /** * Contract section 3.8: the incoming key signs `{aud, kid, prev, jti, * generation}` with its own private half. * * What it establishes is that the holder of the new key took part in this * install, for this site, under this generation, at the request of `prev` * (the active key signing the enclosing message). A key nobody holds cannot * be installed, and a proof made for another site, another generation or * another signer is refused. It says nothing about freshness beyond its * `jti` differing from the outer one; the outer message carries that. * * @param string $public_key The incoming key, `b64u:` encoded. */ public static function verifyKeyProof( string $proof, string $public_key, string $kid, string $prev, string $aud, int $generation, string $outer_jti ): Result { $raw = \Pielyt\Crypto\Keys::parsePublicKey( $public_key ); if ( ! $raw->isOk() ) { return Result::err( 'key_proof_invalid', 'the incoming key does not parse' ); } if ( $kid === $prev ) { return Result::err( 'key_proof_invalid', 'a key cannot sign its own install' ); } $jws = Jws::verify( $proof, Constants::KEY_PROOF_TYP, array( $kid => $raw->value() ) ); if ( ! $jws->isOk() ) { return Result::err( 'key_proof_invalid', 'the proof does not verify under the incoming key: ' . $jws->error()->code() ); } /** @var JsonObject $p */ $p = $jws->value()['payload']; $names = $p->keys(); sort( $names ); $wanted = self::PROOF_MEMBERS; sort( $wanted ); if ( $names !== $wanted ) { return Result::err( 'key_proof_invalid', 'the proof carries exactly aud, kid, prev, jti and generation' ); } $jti = $p->get( 'jti' ); if ( ! is_string( $p->get( 'aud' ) ) || ! hash_equals( $aud, $p->get( 'aud' ) ) || ! is_string( $p->get( 'kid' ) ) || ! hash_equals( $kid, $p->get( 'kid' ) ) || ! is_string( $p->get( 'prev' ) ) || ! hash_equals( $prev, $p->get( 'prev' ) ) || $generation !== $p->get( 'generation' ) || ! is_string( $jti ) || 1 !== preg_match( Constants::JTI_PATTERN, $jti ) || $jti === $outer_jti ) { return Result::err( 'key_proof_invalid', 'the proof is not for this install of ' . $kid ); } return Result::ok(); } }