> the payload, with `token` added */ public static function verify( string $token, string $issuer, array $expect ): Result { foreach ( array( 'site_uuid', 'attempt_id', 'spk_fingerprint' ) as $name ) { if ( ! isset( $expect[ $name ] ) || ! is_string( $expect[ $name ] ) || '' === $expect[ $name ] ) { return Result::err( 'binding_mismatch', 'there is no ' . $name . ' to bind the document to' ); } } if ( '' === $issuer ) { return Result::err( 'binding_mismatch', 'there is no issuer to bind the document to' ); } // The key is named by the document it verifies, so the payload is read // before the signature: only to find the key, and the Jws call below // is what decides. The header kid must equal the payload kid there. $peek = self::peek( $token ); if ( ! $peek->isOk() ) { return $peek; } $kid = $peek->value()['kid']; $raw = $peek->value()['key']; $jws = Jws::verify( $token, Constants::BINDING_TYP, array( $kid => $raw ) ); if ( ! $jws->isOk() ) { return $jws; } /** @var JsonObject $p */ $p = $jws->value()['payload']; $names = $p->keys(); sort( $names ); $wanted = self::MEMBERS; sort( $wanted ); if ( $names !== $wanted ) { return Result::err( 'binding_malformed', 'the binding document carries exactly the members of contract section 3.5' ); } if ( 2 !== $p->get( 'v' ) ) { return Result::err( 'binding_malformed', 'v is 2' ); } // Every string non-empty, as `verifyBinding()` in core-grant requires. foreach ( array( 'site_id', 'org_id', 'org_name', 'approved_by', 'iss', 'site_uuid', 'attempt_id', 'spk_fingerprint', 'grant_public_key', 'kid', 'issued_at' ) as $name ) { if ( ! is_string( $p->get( $name ) ) || '' === $p->get( $name ) ) { return Result::err( 'binding_malformed', $name . ' is a non-empty string' ); } } if ( 1 !== preg_match( self::UUID_PATTERN, $p->get( 'site_id' ) ) ) { return Result::err( 'binding_malformed', 'site_id is a canonical UUID' ); } if ( 1 !== preg_match( self::FINGERPRINT_PATTERN, $p->get( 'spk_fingerprint' ) ) ) { return Result::err( 'binding_malformed', 'spk_fingerprint is sha256: plus 64 lowercase hex characters' ); } $generation = $p->get( 'generation' ); if ( ! is_int( $generation ) || $generation < 1 ) { return Result::err( 'binding_malformed', 'generation is a positive integer' ); } $ttl = $p->get( 'grant_max_ttl_seconds' ); if ( ! is_int( $ttl ) || $ttl < 1 ) { return Result::err( 'binding_malformed', 'grant_max_ttl_seconds is a positive integer' ); } $epoch = $p->get( 'epoch' ); if ( ! is_int( $epoch ) || $epoch < 0 ) { return Result::err( 'binding_malformed', 'epoch is a non-negative integer' ); } $min = $p->get( 'gateway_min_grant_format' ); $max = $p->get( 'gateway_max_grant_format' ); if ( ! is_int( $min ) || ! is_int( $max ) || $min < 1 || $max < $min ) { return Result::err( 'binding_malformed', 'the gateway format range is two positive integers, min no greater than max' ); } if ( 1 !== preg_match( self::ISSUED_AT_PATTERN, $p->get( 'issued_at' ), $date ) || ! checkdate( (int) $date[2], (int) $date[3], (int) $date[1] ) ) { return Result::err( 'binding_malformed', 'issued_at is an ISO 8601 timestamp' ); } // A signer may bind a site but may not choose a new destination: the // document names this build's compiled issuer or it is refused. if ( ! hash_equals( $issuer, $p->get( 'iss' ) ) ) { return Result::err( 'binding_mismatch', 'the binding is not bound to this build\'s issuer' ); } // Each binding answers its own question, so each is compared apart. if ( ! hash_equals( $expect['site_uuid'], $p->get( 'site_uuid' ) ) ) { return Result::err( 'binding_mismatch', 'the binding is for another site_uuid' ); } if ( ! hash_equals( $expect['attempt_id'], $p->get( 'attempt_id' ) ) ) { return Result::err( 'binding_mismatch', 'the binding is from another pairing attempt' ); } if ( ! hash_equals( $expect['spk_fingerprint'], $p->get( 'spk_fingerprint' ) ) ) { return Result::err( 'binding_mismatch', 'the binding is for another site key' ); } $out = $p->toArray(); $out['token'] = $token; return Result::ok( $out ); } /** * The payload's `kid` and key, read without trusting either. * * Bounded the way `Jws` bounds a pre-auth parse: the binding endpoint's * reply is a few hundred bytes, and the caller has already capped the body. * * @return Result Result */ private static function peek( string $token ): Result { $parts = explode( '.', $token, 4 ); if ( 3 !== count( $parts ) ) { return Result::err( 'jws_malformed', 'not a three-part compact serialization' ); } $bytes = Base64Url::decode( $parts[1] ); if ( ! $bytes->isOk() ) { return Result::err( 'binding_malformed', 'the payload is not base64url' ); } $payload = json_decode( $bytes->value(), true, 4 ); if ( ! is_array( $payload ) || ! isset( $payload['kid'], $payload['grant_public_key'] ) || ! is_string( $payload['kid'] ) || ! is_string( $payload['grant_public_key'] ) || '' === $payload['kid'] ) { return Result::err( 'binding_malformed', 'the payload names no kid and grant_public_key' ); } $key = Keys::parsePublicKey( $payload['grant_public_key'] ); if ( ! $key->isOk() ) { return Result::err( 'binding_malformed', $key->error()->message() ); } return Result::ok( array( 'kid' => $payload['kid'], 'key' => $key->value(), ) ); } }