AWS sdk-for-php documentation change
Summary
Restructured and updated the S3 pre-signed URL documentation, adding specific code examples for HTTP GET and PUT requests, and removing some general information sections.
Security assessment
The changes primarily focus on restructuring the documentation and adding specific code examples. While pre-signed URLs are a security feature, there is no evidence in the diff that this change addresses a specific security issue or adds new security-related documentation.
Diff
diff --git a/sdk-for-php/v3/developer-guide/s3-presigned-url.md index 413d51e90..4d020f48a 100644 --- a/sdk-for-php/v3/developer-guide/s3-presigned-url.md +++ b/sdk-for-php/v3/developer-guide/s3-presigned-url.md @@ -5 +5 @@ -CredentialsCreating a pre-signed requestCreating a pre-signed URLGetting the URL to an object +HTTP GET requestHTTP PUT request @@ -9 +9 @@ CredentialsCreating a pre-signed requestCreating a pre-signed URLGetting the URL -You can authenticate certain types of requests by passing the required information as query-string parameters instead of using the Authorization HTTP header. This is useful for enabling direct third-party browser access to your private Amazon S3 data, without proxying the request. The idea is to construct a “pre-signed” request and encode it as a URL that an end-user’s browser can retrieve. Additionally, you can limit a pre-signed request by specifying an expiration time. +You can authenticate certain types of requests by passing the required information as query-string parameters instead of using the Authorization HTTP header. This is useful for enabling direct third-party browser access to your private Amazon S3 data, without proxying the request. The idea is to construct a “pre-signed” request and encode it as a URL that another user can use. Additionally, you can limit a pre-signed request by specifying an expiration time. @@ -11 +11 @@ You can authenticate certain types of requests by passing the required informati -The following examples show how to: +## Create a pre-signed URL for an HTTP GET request @@ -13 +13 @@ The following examples show how to: - * Create a pre-signed URL to get an S3 object using [createPresignedRequest](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.S3Client.html#_createPresignedRequest). +The following code example shows how to create a pre-signed URL for an HTTP GET request by using the SDK for PHP. @@ -15,0 +16 @@ The following examples show how to: + <?php @@ -16,0 +18 @@ The following examples show how to: + require 'vendor/autoload.php'; @@ -18 +20 @@ The following examples show how to: -All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code). + use Aws\S3\S3Client; @@ -20 +22,3 @@ All the example code for the AWS SDK for PHP is available [here on GitHub](https -## Credentials + $s3Client = new S3Client([ + 'region' => 'us-west-2', + ]); @@ -22 +26,8 @@ All the example code for the AWS SDK for PHP is available [here on GitHub](https -Before running the example code, configure your AWS credentials, as described in [Credentials](./guide_credentials.html). Then import the AWS SDK for PHP, as described in [Basic usage](./getting-started_basic-usage.html). + // Supply a CommandInterface object and an expires parameter to the `createPresignedRequest` method. + $request = $s3Client->createPresignedRequest( + $s3Client->getCommand('GetObject', [ + 'Bucket' => 'amzn-s3-demo-bucket', + 'Key' => 'demo-key', + ]), + '+1 hour' + ); @@ -24 +35,2 @@ Before running the example code, configure your AWS credentials, as described in -## Creating a pre-signed request + // From the resulting RequestInterface object, you can get the URL. + $presignedUrl = (string) $request->getUri(); @@ -26 +38 @@ Before running the example code, configure your AWS credentials, as described in -You can get the pre-signed URL to an Amazon S3 object by using the `Aws\S3\S3Client::createPresignedRequest()` method. This method accepts an `Aws\CommandInterface` object and expired timestamp and returns a pre-signed `Psr\Http\Message\RequestInterface` object. You can retrieve the pre-signed URL of the object using the `getUri()` method of the request. + echo $presignedUrl; @@ -28 +40 @@ You can get the pre-signed URL to an Amazon S3 object by using the `Aws\S3\S3Cli -The most common scenario is creating a pre-signed URL to GET an object. +The [API reference for the `createPresignedRequest`](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.S3Client.html#method_createPresignedRequest)method provides more details. @@ -30 +42 @@ The most common scenario is creating a pre-signed URL to GET an object. -**Imports** +Someone else can use the `$presignedUrl` value to retrieve the object within the next hour. When the HTTP GET request is made—using a browser, for example—it appears to the S3 service that the call is coming from the user who created the pres-signed URL. @@ -31,0 +44 @@ The most common scenario is creating a pre-signed URL to GET an object. +## Create a pre-signed URL for an HTTP PUT request @@ -33,4 +46 @@ The most common scenario is creating a pre-signed URL to GET an object. - use Aws\Exception\AwsException; - use AwsUtilities\PrintableLineBreak; - use AwsUtilities\TestableReadline; - use DateTime; +The following code example shows how to create a pre-signed URL for an HTTP PUT request by using the SDK for PHP. @@ -38 +47,0 @@ The most common scenario is creating a pre-signed URL to GET an object. - require 'vendor/autoload.php'; @@ -39,0 +49 @@ The most common scenario is creating a pre-signed URL to GET an object. + <?php @@ -41 +51 @@ The most common scenario is creating a pre-signed URL to GET an object. -**Sample Code** + require 'vendor/autoload.php'; @@ -42,0 +53 @@ The most common scenario is creating a pre-signed URL to GET an object. + use Aws\S3\S3Client; @@ -44,3 +55,2 @@ The most common scenario is creating a pre-signed URL to GET an object. - $command = $s3Service->getClient()->getCommand('GetObject', [ - 'Bucket' => $bucket, - 'Key' => $key, + $s3Client = new S3Client([ + 'region' => 'us-west-2', @@ -48,0 +59,7 @@ The most common scenario is creating a pre-signed URL to GET an object. + $request = $s3Client->createPresignedRequest( + $s3Client->getCommand('PutObject', [ + 'Bucket' => 'amzn-s3-demo-bucket', + 'Key' => 'demo-key', + ]), + '+1 hour' + ); @@ -50,20 +67,2 @@ The most common scenario is creating a pre-signed URL to GET an object. -## Creating a pre-signed URL - -You can create pre-signed URLs for any Amazon S3 operation using the `getCommand` method for creating a command object, and then calling the `createPresignedRequest()` method with the command. When ultimately sending the request, be sure to use the same method and the same headers as the returned request. - -**Sample Code** - - - try { - $preSignedUrl = $s3Service->preSignedUrl($command, $expiration); - echo "Your preSignedUrl is \n$preSignedUrl\nand will be good for the next 20 minutes.\n"; - echo $linebreak; - echo "Thanks for trying the Amazon S3 presigned URL demo.\n"; - } catch (AwsException $exception) { - echo $linebreak; - echo "Something went wrong: $exception"; - die(); - } - - -## Getting the URL to an object + // From the resulting RequestInterface object, you can get the URL. + $presignedUrl = (string) $request->getUri(); @@ -71 +70 @@ You can create pre-signed URLs for any Amazon S3 operation using the `getCommand -If you only need the public URL to an object stored in an Amazon S3 bucket, you can use the `Aws\S3\S3Client::getObjectUrl()` method. This method returns an unsigned URL to the given bucket and key. +Someone else can now use the pre-signed URL in an HTTP PUT request to upload a file: @@ -73 +71,0 @@ If you only need the public URL to an object stored in an Amazon S3 bucket, you -**Sample Code** @@ -74,0 +73,3 @@ If you only need the public URL to an object stored in an Amazon S3 bucket, you + function uploadWithPresignedUrl($presignedUrl, $filePath, $s3Client): ?\GuzzleHttp\Psr7\Response { + // Get the HTTP handler from the S3 client. + $handler = $s3Client->getHandlerList()->resolve(); @@ -76 +77,2 @@ If you only need the public URL to an object stored in an Amazon S3 bucket, you - $preSignedUrl = $s3Service->preSignedUrl($command, $expiration); + // Create a stream from the file. + $fileStream = new Stream(fopen($filePath, 'r')); @@ -77,0 +80,10 @@ If you only need the public URL to an object stored in an Amazon S3 bucket, you + // Create the request. + $request = new \GuzzleHttp\Psr7\Request( + 'PUT', + $presignedUrl, + [ + 'Content-Type' => mime_content_type($filePath), + 'Content-Length' => filesize($filePath) + ], + $fileStream + ); @@ -79,3 +91,10 @@ If you only need the public URL to an object stored in an Amazon S3 bucket, you -###### Important - -The URL returned by this method is not validated to ensure that the bucket or key exists, nor does this method ensure that the object allows unauthenticated access. + // Send the request using the handler. + try { + $promise = $handler($request, []); + $response = $promise->wait(); + return $response; + } catch (Exception $e) { + echo "Error uploading file: " . $e->getMessage() . "\n"; + return null; + } + }