Automattic /
jetpack
These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more
| 1 | <?php |
||
| 2 | /** |
||
| 3 | * The Connection Client class file. |
||
| 4 | * |
||
| 5 | * @package jetpack-connection |
||
| 6 | */ |
||
| 7 | |||
| 8 | namespace Automattic\Jetpack\Connection; |
||
| 9 | |||
| 10 | use Automattic\Jetpack\Constants; |
||
| 11 | |||
| 12 | /** |
||
| 13 | * The Client class that is used to connect to WordPress.com Jetpack API. |
||
| 14 | */ |
||
| 15 | class Client { |
||
| 16 | const WPCOM_JSON_API_VERSION = '1.1'; |
||
| 17 | |||
| 18 | /** |
||
| 19 | * Makes an authorized remote request using Jetpack_Signature |
||
| 20 | * |
||
| 21 | * @param Array $args the arguments for the remote request. |
||
| 22 | * @param Array|String $body the request body. |
||
|
0 ignored issues
–
show
|
|||
| 23 | * @return array|WP_Error WP HTTP response on success |
||
| 24 | */ |
||
| 25 | public static function remote_request( $args, $body = null ) { |
||
| 26 | $defaults = array( |
||
| 27 | 'url' => '', |
||
| 28 | 'user_id' => 0, |
||
| 29 | 'blog_id' => 0, |
||
| 30 | 'auth_location' => Constants::get_constant( 'JETPACK_CLIENT__AUTH_LOCATION' ), |
||
| 31 | 'method' => 'POST', |
||
| 32 | 'timeout' => 10, |
||
| 33 | 'redirection' => 0, |
||
| 34 | 'headers' => array(), |
||
| 35 | 'stream' => false, |
||
| 36 | 'filename' => null, |
||
| 37 | 'sslverify' => true, |
||
| 38 | ); |
||
| 39 | |||
| 40 | $args = wp_parse_args( $args, $defaults ); |
||
| 41 | |||
| 42 | $args['blog_id'] = (int) $args['blog_id']; |
||
| 43 | |||
| 44 | if ( 'header' !== $args['auth_location'] ) { |
||
| 45 | $args['auth_location'] = 'query_string'; |
||
| 46 | } |
||
| 47 | |||
| 48 | $token = \Jetpack_Data::get_access_token( $args['user_id'] ); |
||
|
0 ignored issues
–
show
The method
Jetpack_Data::get_access_token() has been deprecated with message: 7.5 Use Connection_Manager instead.
This method has been deprecated. The supplier of the class has supplied an explanatory message. The explanatory message should give you some clue as to whether and when the method will be removed from the class and what other method or class to use instead. Loading history...
|
|||
| 49 | if ( ! $token ) { |
||
| 50 | return new \WP_Error( 'missing_token' ); |
||
|
0 ignored issues
–
show
The call to
WP_Error::__construct() has too many arguments starting with 'missing_token'.
This check compares calls to functions or methods with their respective definitions. If the call has more arguments than are defined, it raises an issue. If a function is defined several times with a different number of parameters, the check may pick up the wrong definition and report false positives. One codebase where this has been known to happen is Wordpress. In this case you can add the Loading history...
|
|||
| 51 | } |
||
| 52 | |||
| 53 | $method = strtoupper( $args['method'] ); |
||
| 54 | |||
| 55 | $timeout = intval( $args['timeout'] ); |
||
| 56 | |||
| 57 | $redirection = $args['redirection']; |
||
| 58 | $stream = $args['stream']; |
||
| 59 | $filename = $args['filename']; |
||
| 60 | $sslverify = $args['sslverify']; |
||
| 61 | |||
| 62 | $request = compact( 'method', 'body', 'timeout', 'redirection', 'stream', 'filename', 'sslverify' ); |
||
| 63 | |||
| 64 | @list( $token_key, $secret ) = explode( '.', $token->secret ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged |
||
|
0 ignored issues
–
show
It seems like you do not handle an error condition here. This can introduce security issues, and is generally not recommended.
If you suppress an error, we recommend checking for the error condition explicitly: // For example instead of
@mkdir($dir);
// Better use
if (@mkdir($dir) === false) {
throw new \RuntimeException('The directory '.$dir.' could not be created.');
}
Loading history...
|
|||
| 65 | if ( empty( $token ) || empty( $secret ) ) { |
||
| 66 | return new \WP_Error( 'malformed_token' ); |
||
|
0 ignored issues
–
show
The call to
WP_Error::__construct() has too many arguments starting with 'malformed_token'.
This check compares calls to functions or methods with their respective definitions. If the call has more arguments than are defined, it raises an issue. If a function is defined several times with a different number of parameters, the check may pick up the wrong definition and report false positives. One codebase where this has been known to happen is Wordpress. In this case you can add the Loading history...
|
|||
| 67 | } |
||
| 68 | |||
| 69 | $token_key = sprintf( |
||
| 70 | '%s:%d:%d', |
||
| 71 | $token_key, |
||
| 72 | Constants::get_constant( 'JETPACK__API_VERSION' ), |
||
| 73 | $token->external_user_id |
||
| 74 | ); |
||
| 75 | |||
| 76 | $time_diff = (int) \Jetpack_Options::get_option( 'time_diff' ); |
||
| 77 | $jetpack_signature = new \Jetpack_Signature( $token->secret, $time_diff ); |
||
| 78 | |||
| 79 | $timestamp = time() + $time_diff; |
||
| 80 | |||
| 81 | if ( function_exists( 'wp_generate_password' ) ) { |
||
| 82 | $nonce = wp_generate_password( 10, false ); |
||
| 83 | } else { |
||
| 84 | $nonce = substr( sha1( wp_rand( 0, 1000000 ) ), 0, 10 ); |
||
| 85 | } |
||
| 86 | |||
| 87 | // Kind of annoying. Maybe refactor Jetpack_Signature to handle body-hashing. |
||
| 88 | if ( is_null( $body ) ) { |
||
| 89 | $body_hash = ''; |
||
| 90 | |||
| 91 | } else { |
||
| 92 | // Allow arrays to be used in passing data. |
||
| 93 | $body_to_hash = $body; |
||
| 94 | |||
| 95 | if ( is_array( $body ) ) { |
||
| 96 | // We cast this to a new variable, because the array form of $body needs to be |
||
| 97 | // maintained so it can be passed into the request later on in the code. |
||
| 98 | if ( count( $body ) > 0 ) { |
||
| 99 | $body_to_hash = wp_json_encode( self::_stringify_data( $body ) ); |
||
| 100 | } else { |
||
| 101 | $body_to_hash = ''; |
||
| 102 | } |
||
| 103 | } |
||
| 104 | |||
| 105 | if ( ! is_string( $body_to_hash ) ) { |
||
| 106 | return new \WP_Error( 'invalid_body', 'Body is malformed.' ); |
||
|
0 ignored issues
–
show
The call to
WP_Error::__construct() has too many arguments starting with 'invalid_body'.
This check compares calls to functions or methods with their respective definitions. If the call has more arguments than are defined, it raises an issue. If a function is defined several times with a different number of parameters, the check may pick up the wrong definition and report false positives. One codebase where this has been known to happen is Wordpress. In this case you can add the Loading history...
|
|||
| 107 | } |
||
| 108 | |||
| 109 | $body_hash = base64_encode( sha1( $body_to_hash, true ) ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode |
||
| 110 | } |
||
| 111 | |||
| 112 | $auth = array( |
||
| 113 | 'token' => $token_key, |
||
| 114 | 'timestamp' => $timestamp, |
||
| 115 | 'nonce' => $nonce, |
||
| 116 | 'body-hash' => $body_hash, |
||
| 117 | ); |
||
| 118 | |||
| 119 | if ( false !== strpos( $args['url'], 'xmlrpc.php' ) ) { |
||
| 120 | $url_args = array( |
||
| 121 | 'for' => 'jetpack', |
||
| 122 | 'wpcom_blog_id' => \Jetpack_Options::get_option( 'id' ), |
||
| 123 | ); |
||
| 124 | } else { |
||
| 125 | $url_args = array(); |
||
| 126 | } |
||
| 127 | |||
| 128 | if ( 'header' !== $args['auth_location'] ) { |
||
| 129 | $url_args += $auth; |
||
| 130 | } |
||
| 131 | |||
| 132 | $url = add_query_arg( urlencode_deep( $url_args ), $args['url'] ); |
||
| 133 | $url = \Jetpack::fix_url_for_bad_hosts( $url ); |
||
| 134 | |||
| 135 | $signature = $jetpack_signature->sign_request( $token_key, $timestamp, $nonce, $body_hash, $method, $url, $body, false ); |
||
| 136 | |||
| 137 | if ( ! $signature || is_wp_error( $signature ) ) { |
||
| 138 | return $signature; |
||
| 139 | } |
||
| 140 | |||
| 141 | // Send an Authorization header so various caches/proxies do the right thing. |
||
| 142 | $auth['signature'] = $signature; |
||
| 143 | $auth['version'] = Constants::get_constant( 'JETPACK__VERSION' ); |
||
| 144 | $header_pieces = array(); |
||
| 145 | foreach ( $auth as $key => $value ) { |
||
| 146 | $header_pieces[] = sprintf( '%s="%s"', $key, $value ); |
||
| 147 | } |
||
| 148 | $request['headers'] = array_merge( |
||
| 149 | $args['headers'], |
||
| 150 | array( |
||
| 151 | 'Authorization' => 'X_JETPACK ' . join( ' ', $header_pieces ), |
||
| 152 | ) |
||
| 153 | ); |
||
| 154 | |||
| 155 | if ( 'header' !== $args['auth_location'] ) { |
||
| 156 | $url = add_query_arg( 'signature', rawurlencode( $signature ), $url ); |
||
| 157 | } |
||
| 158 | |||
| 159 | return self::_wp_remote_request( $url, $request ); |
||
| 160 | } |
||
| 161 | |||
| 162 | /** |
||
| 163 | * Wrapper for wp_remote_request(). Turns off SSL verification for certain SSL errors. |
||
| 164 | * This is lame, but many, many, many hosts have misconfigured SSL. |
||
| 165 | * |
||
| 166 | * When Jetpack is registered, the jetpack_fallback_no_verify_ssl_certs option is set to the current time if: |
||
| 167 | * 1. a certificate error is found AND |
||
| 168 | * 2. not verifying the certificate works around the problem. |
||
| 169 | * |
||
| 170 | * The option is checked on each request. |
||
| 171 | * |
||
| 172 | * @internal |
||
| 173 | * @see Jetpack::fix_url_for_bad_hosts() |
||
| 174 | * |
||
| 175 | * @param String $url the request URL. |
||
| 176 | * @param Array $args request arguments. |
||
| 177 | * @param Boolean $set_fallback whether to allow flagging this request to use a fallback certficate override. |
||
| 178 | * @return array|WP_Error WP HTTP response on success |
||
| 179 | */ |
||
| 180 | public static function _wp_remote_request( $url, $args, $set_fallback = false ) { |
||
| 181 | /** |
||
| 182 | * SSL verification (`sslverify`) for the JetpackClient remote request |
||
| 183 | * defaults to off, use this filter to force it on. |
||
| 184 | * |
||
| 185 | * Return `true` to ENABLE SSL verification, return `false` |
||
| 186 | * to DISABLE SSL verification. |
||
| 187 | * |
||
| 188 | * @since 3.6.0 |
||
| 189 | * |
||
| 190 | * @param bool Whether to force `sslverify` or not. |
||
| 191 | */ |
||
| 192 | if ( apply_filters( 'jetpack_client_verify_ssl_certs', false ) ) { |
||
| 193 | return wp_remote_request( $url, $args ); |
||
| 194 | } |
||
| 195 | |||
| 196 | $fallback = \Jetpack_Options::get_option( 'fallback_no_verify_ssl_certs' ); |
||
| 197 | if ( false === $fallback ) { |
||
| 198 | \Jetpack_Options::update_option( 'fallback_no_verify_ssl_certs', 0 ); |
||
| 199 | } |
||
| 200 | |||
| 201 | if ( (int) $fallback ) { |
||
| 202 | // We're flagged to fallback. |
||
| 203 | $args['sslverify'] = false; |
||
| 204 | } |
||
| 205 | |||
| 206 | $response = wp_remote_request( $url, $args ); |
||
| 207 | |||
| 208 | if ( |
||
| 209 | ! $set_fallback // We're not allowed to set the flag on this request, so whatever happens happens. |
||
| 210 | || |
||
| 211 | isset( $args['sslverify'] ) && ! $args['sslverify'] // No verification - no point in doing it again. |
||
| 212 | || |
||
| 213 | ! is_wp_error( $response ) // Let it ride. |
||
| 214 | ) { |
||
| 215 | self::set_time_diff( $response, $set_fallback ); |
||
| 216 | return $response; |
||
| 217 | } |
||
| 218 | |||
| 219 | // At this point, we're not flagged to fallback and we are allowed to set the flag on this request. |
||
| 220 | |||
| 221 | $message = $response->get_error_message(); |
||
| 222 | |||
| 223 | // Is it an SSL Certificate verification error? |
||
| 224 | if ( |
||
| 225 | false === strpos( $message, '14090086' ) // OpenSSL SSL3 certificate error. |
||
| 226 | && |
||
| 227 | false === strpos( $message, '1407E086' ) // OpenSSL SSL2 certificate error. |
||
| 228 | && |
||
| 229 | false === strpos( $message, 'error setting certificate verify locations' ) // cURL CA bundle not found. |
||
| 230 | && |
||
| 231 | false === strpos( $message, 'Peer certificate cannot be authenticated with' ) // cURL CURLE_SSL_CACERT: CA bundle found, but not helpful |
||
| 232 | // Different versions of curl have different error messages |
||
| 233 | // this string should catch them all. |
||
| 234 | && |
||
| 235 | false === strpos( $message, 'Problem with the SSL CA cert' ) // cURL CURLE_SSL_CACERT_BADFILE: probably access rights. |
||
| 236 | ) { |
||
| 237 | // No, it is not. |
||
| 238 | return $response; |
||
| 239 | } |
||
| 240 | |||
| 241 | // Redo the request without SSL certificate verification. |
||
| 242 | $args['sslverify'] = false; |
||
| 243 | $response = wp_remote_request( $url, $args ); |
||
| 244 | |||
| 245 | if ( ! is_wp_error( $response ) ) { |
||
| 246 | // The request went through this time, flag for future fallbacks. |
||
| 247 | \Jetpack_Options::update_option( 'fallback_no_verify_ssl_certs', time() ); |
||
| 248 | self::set_time_diff( $response, $set_fallback ); |
||
| 249 | } |
||
| 250 | |||
| 251 | return $response; |
||
| 252 | } |
||
| 253 | |||
| 254 | /** |
||
| 255 | * Sets the time difference for correct signature computation. |
||
| 256 | * |
||
| 257 | * @param HTTP_Response $response the response object. |
||
| 258 | * @param Boolean $force_set whether to force setting the time difference. |
||
| 259 | */ |
||
| 260 | public static function set_time_diff( &$response, $force_set = false ) { |
||
| 261 | $code = wp_remote_retrieve_response_code( $response ); |
||
| 262 | |||
| 263 | // Only trust the Date header on some responses. |
||
| 264 | if ( 200 != $code && 304 != $code && 400 != $code && 401 != $code ) { // phpcs:ignore WordPress.PHP.StrictComparisons.LooseComparison |
||
| 265 | return; |
||
| 266 | } |
||
| 267 | |||
| 268 | $date = wp_remote_retrieve_header( $response, 'date' ); |
||
| 269 | if ( ! $date ) { |
||
| 270 | return; |
||
| 271 | } |
||
| 272 | |||
| 273 | $time = (int) strtotime( $date ); |
||
| 274 | if ( 0 >= $time ) { |
||
| 275 | return; |
||
| 276 | } |
||
| 277 | |||
| 278 | $time_diff = $time - time(); |
||
| 279 | |||
| 280 | if ( $force_set ) { // During register. |
||
| 281 | \Jetpack_Options::update_option( 'time_diff', $time_diff ); |
||
| 282 | } else { // Otherwise. |
||
| 283 | $old_diff = \Jetpack_Options::get_option( 'time_diff' ); |
||
| 284 | if ( false === $old_diff || abs( $time_diff - (int) $old_diff ) > 10 ) { |
||
| 285 | \Jetpack_Options::update_option( 'time_diff', $time_diff ); |
||
| 286 | } |
||
| 287 | } |
||
| 288 | } |
||
| 289 | |||
| 290 | /** |
||
| 291 | * Queries the WordPress.com REST API with a user token. |
||
| 292 | * |
||
| 293 | * @param string $path REST API path. |
||
| 294 | * @param string $version REST API version. Default is `2`. |
||
| 295 | * @param array $args Arguments to {@see WP_Http}. Default is `array()`. |
||
| 296 | * @param string $body Body passed to {@see WP_Http}. Default is `null`. |
||
|
0 ignored issues
–
show
Should the type for parameter
$body not be string|null?
This check looks for It makes a suggestion as to what type it considers more descriptive. Most often this is a case of a parameter that can be null in addition to its declared types. Loading history...
|
|||
| 297 | * @param string $base_api_path REST API root. Default is `wpcom`. |
||
| 298 | * |
||
| 299 | * @return array|WP_Error $response Response data, else {@see WP_Error} on failure. |
||
| 300 | */ |
||
| 301 | public static function wpcom_json_api_request_as_user( |
||
| 302 | $path, |
||
| 303 | $version = '2', |
||
| 304 | $args = array(), |
||
| 305 | $body = null, |
||
| 306 | $base_api_path = 'wpcom' |
||
| 307 | ) { |
||
| 308 | $base_api_path = trim( $base_api_path, '/' ); |
||
| 309 | $version = ltrim( $version, 'v' ); |
||
| 310 | $path = ltrim( $path, '/' ); |
||
| 311 | |||
| 312 | $args = array_intersect_key( |
||
| 313 | $args, |
||
| 314 | array( |
||
| 315 | 'headers' => 'array', |
||
| 316 | 'method' => 'string', |
||
| 317 | 'timeout' => 'int', |
||
| 318 | 'redirection' => 'int', |
||
| 319 | 'stream' => 'boolean', |
||
| 320 | 'filename' => 'string', |
||
| 321 | 'sslverify' => 'boolean', |
||
| 322 | ) |
||
| 323 | ); |
||
| 324 | |||
| 325 | $args['user_id'] = get_current_user_id(); |
||
| 326 | $args['method'] = isset( $args['method'] ) ? strtoupper( $args['method'] ) : 'GET'; |
||
| 327 | $args['url'] = sprintf( |
||
| 328 | '%s://%s/%s/v%s/%s', |
||
| 329 | self::protocol(), |
||
| 330 | Constants::get_constant( 'JETPACK__WPCOM_JSON_API_HOST' ), |
||
| 331 | $base_api_path, |
||
| 332 | $version, |
||
| 333 | $path |
||
| 334 | ); |
||
| 335 | |||
| 336 | if ( isset( $body ) && ! isset( $args['headers'] ) && in_array( $args['method'], array( 'POST', 'PUT', 'PATCH' ), true ) ) { |
||
| 337 | $args['headers'] = array( 'Content-Type' => 'application/json' ); |
||
| 338 | } |
||
| 339 | |||
| 340 | if ( isset( $body ) && ! is_string( $body ) ) { |
||
| 341 | $body = wp_json_encode( $body ); |
||
| 342 | } |
||
| 343 | |||
| 344 | return self::remote_request( $args, $body ); |
||
| 345 | } |
||
| 346 | |||
| 347 | /** |
||
| 348 | * Query the WordPress.com REST API using the blog token |
||
| 349 | * |
||
| 350 | * @param String $path The API endpoint relative path. |
||
| 351 | * @param String $version The API version. |
||
| 352 | * @param Array $args Request arguments. |
||
| 353 | * @param String $body Request body. |
||
|
0 ignored issues
–
show
Should the type for parameter
$body not be string|null?
This check looks for It makes a suggestion as to what type it considers more descriptive. Most often this is a case of a parameter that can be null in addition to its declared types. Loading history...
|
|||
| 354 | * @param String $base_api_path (optional) the API base path override, defaults to 'rest'. |
||
| 355 | * @return Array|WP_Error $response Data. |
||
| 356 | */ |
||
| 357 | public static function wpcom_json_api_request_as_blog( |
||
| 358 | $path, |
||
| 359 | $version = self::WPCOM_JSON_API_VERSION, |
||
| 360 | $args = array(), |
||
| 361 | $body = null, |
||
| 362 | $base_api_path = 'rest' |
||
| 363 | ) { |
||
| 364 | $filtered_args = array_intersect_key( |
||
| 365 | $args, |
||
| 366 | array( |
||
| 367 | 'headers' => 'array', |
||
| 368 | 'method' => 'string', |
||
| 369 | 'timeout' => 'int', |
||
| 370 | 'redirection' => 'int', |
||
| 371 | 'stream' => 'boolean', |
||
| 372 | 'filename' => 'string', |
||
| 373 | 'sslverify' => 'boolean', |
||
| 374 | ) |
||
| 375 | ); |
||
| 376 | |||
| 377 | // unprecedingslashit. |
||
| 378 | $_path = preg_replace( '/^\//', '', $path ); |
||
| 379 | |||
| 380 | // Use GET by default whereas `remote_request` uses POST. |
||
| 381 | $request_method = ( isset( $filtered_args['method'] ) ) ? $filtered_args['method'] : 'GET'; |
||
| 382 | |||
| 383 | $url = sprintf( |
||
| 384 | '%s://%s/%s/v%s/%s', |
||
| 385 | self::protocol(), |
||
| 386 | Constants::get_constant( 'JETPACK__WPCOM_JSON_API_HOST' ), |
||
| 387 | $base_api_path, |
||
| 388 | $version, |
||
| 389 | $_path |
||
| 390 | ); |
||
| 391 | |||
| 392 | $validated_args = array_merge( |
||
| 393 | $filtered_args, |
||
| 394 | array( |
||
| 395 | 'url' => $url, |
||
| 396 | 'blog_id' => (int) \Jetpack_Options::get_option( 'id' ), |
||
| 397 | 'method' => $request_method, |
||
| 398 | ) |
||
| 399 | ); |
||
| 400 | |||
| 401 | return self::remote_request( $validated_args, $body ); |
||
| 402 | } |
||
| 403 | |||
| 404 | /** |
||
| 405 | * Takes an array or similar structure and recursively turns all values into strings. This is used to |
||
| 406 | * make sure that body hashes are made ith the string version, which is what will be seen after a |
||
| 407 | * server pulls up the data in the $_POST array. |
||
| 408 | * |
||
| 409 | * @param Array|Mixed $data the data that needs to be stringified. |
||
| 410 | * |
||
| 411 | * @return array|string |
||
| 412 | */ |
||
| 413 | public static function _stringify_data( $data ) { |
||
| 414 | |||
| 415 | // Booleans are special, lets just makes them and explicit 1/0 instead of the 0 being an empty string. |
||
| 416 | if ( is_bool( $data ) ) { |
||
| 417 | return $data ? '1' : '0'; |
||
| 418 | } |
||
| 419 | |||
| 420 | // Cast objects into arrays. |
||
| 421 | if ( is_object( $data ) ) { |
||
| 422 | $data = (array) $data; |
||
| 423 | } |
||
| 424 | |||
| 425 | // Non arrays at this point should be just converted to strings. |
||
| 426 | if ( ! is_array( $data ) ) { |
||
| 427 | return (string) $data; |
||
| 428 | } |
||
| 429 | |||
| 430 | foreach ( $data as $key => &$value ) { |
||
| 431 | $value = self::_stringify_data( $value ); |
||
| 432 | } |
||
| 433 | |||
| 434 | return $data; |
||
| 435 | } |
||
| 436 | |||
| 437 | /** |
||
| 438 | * Gets protocol string. |
||
| 439 | * |
||
| 440 | * @return string `https` (if possible), else `http`. |
||
| 441 | */ |
||
| 442 | public static function protocol() { |
||
| 443 | /** |
||
| 444 | * Determines whether Jetpack can send outbound https requests to the WPCOM api. |
||
| 445 | * |
||
| 446 | * @since 3.6.0 |
||
| 447 | * |
||
| 448 | * @param bool $proto Defaults to true. |
||
| 449 | */ |
||
| 450 | $https = apply_filters( 'jetpack_can_make_outbound_https', true ); |
||
| 451 | |||
| 452 | return $https ? 'https' : 'http'; |
||
| 453 | } |
||
| 454 | } |
||
| 455 |
This check looks for
@paramannotations where the type inferred by our type inference engine differs from the declared type.It makes a suggestion as to what type it considers more descriptive.
Most often this is a case of a parameter that can be null in addition to its declared types.