s3_storage/vendor/akeeba/s3/src/Configuration.php

   1 <?php
   2 /**
   3  * Akeeba Engine
   4  *
   5  * @package   akeebaengine
   6  * @copyright Copyright (c)2006-2020 Nicholas K. Dionysopoulos / Akeeba Ltd
   7  * @license   GNU General Public License version 3, or later
   8  */
   9
  10 namespace Akeeba\Engine\Postproc\Connector\S3v4;
  11
  12 // Protection against direct access
  13 defined('AKEEBAENGINE') or die();
  14
  15 /**
  16  * Holds the Amazon S3 confiugration credentials
  17  */
  18 class Configuration
  19 {
  20         /**
  21          * Access Key
  22          *
  23          * @var  string
  24          */
  25         protected $access = '';
  26
  27         /**
  28          * Secret Key
  29          *
  30          * @var  string
  31          */
  32         protected $secret = '';
  33
  34         /**
  35          * Security token. This is only required with temporary credentials provisioned by an EC2 instance.
  36          *
  37          * @var  string
  38          */
  39         protected $token = '';
  40
  41         /**
  42          * Signature calculation method ('v2' or 'v4')
  43          *
  44          * @var  string
  45          */
  46         protected $signatureMethod = 'v2';
  47
  48         /**
  49          * AWS region, used for v4 signatures
  50          *
  51          * @var  string
  52          */
  53         protected $region = 'us-east-1';
  54
  55         /**
  56          * Should I use SSL (HTTPS) to communicate to Amazon S3?
  57          *
  58          * @var  bool
  59          */
  60         protected $useSSL = true;
  61
  62         /**
  63          * Should I use SSL (HTTPS) to communicate to Amazon S3?
  64          *
  65          * @var  bool
  66          */
  67         protected $useDualstackUrl = false;
  68
  69         /**
  70          * Should I use legacy, path-style access to the bucket? When it's turned off (default) we use virtual hosting style
  71          * paths which are RECOMMENDED BY AMAZON per http://docs.aws.amazon.com/AmazonS3/latest/API/APIRest.html
  72          *
  73          * @var  bool
  74          */
  75         protected $useLegacyPathStyle = false;
  76
  77         /**
  78          * Amazon S3 endpoint. You can use a custom endpoint with v2 signatures to access third party services which offer
  79          * S3 compatibility, e.g. OwnCloud, Google Storage etc.
  80          *
  81          * @var  string
  82          */
  83         protected $endpoint = 's3.amazonaws.com';
  84
  85         /**
  86          * Public constructor
  87          *
  88          * @param   string  $access           Amazon S3 Access Key
  89          * @param   string  $secret           Amazon S3 Secret Key
  90          * @param   string  $signatureMethod  Signature method (v2 or v4)
  91          * @param   string  $region           Region, only required for v4 signatures
  92          */
  93         function __construct(string $access, string $secret, string $signatureMethod = 'v2', string $region = '')
  94         {
  95                 $this->setAccess($access);
  96                 $this->setSecret($secret);
  97                 $this->setSignatureMethod($signatureMethod);
  98                 $this->setRegion($region);
  99         }
 100
 101         /**
 102          * Get the Amazon access key
 103          *
 104          * @return  string
 105          */
 106         public function getAccess(): string
 107         {
 108                 return $this->access;
 109         }
 110
 111         /**
 112          * Set the Amazon access key
 113          *
 114          * @param   string  $access  The access key to set
 115          *
 116          * @throws  Exception\InvalidAccessKey
 117          */
 118         public function setAccess(string $access): void
 119         {
 120                 if (empty($access))
 121                 {
 122                         throw new Exception\InvalidAccessKey;
 123                 }
 124
 125                 $this->access = $access;
 126         }
 127
 128         /**
 129          * Get the Amazon secret key
 130          *
 131          * @return string
 132          */
 133         public function getSecret(): string
 134         {
 135                 return $this->secret;
 136         }
 137
 138         /**
 139          * Set the Amazon secret key
 140          *
 141          * @param   string  $secret  The secret key to set
 142          *
 143          * @throws  Exception\InvalidSecretKey
 144          */
 145         public function setSecret(string $secret): void
 146         {
 147                 if (empty($secret))
 148                 {
 149                         throw new Exception\InvalidSecretKey;
 150                 }
 151
 152                 $this->secret = $secret;
 153         }
 154
 155         /**
 156          * Return the security token. Only for temporary credentials provisioned through an EC2 instance.
 157          *
 158          * @return  string
 159          */
 160         public function getToken(): string
 161         {
 162                 return $this->token;
 163         }
 164
 165         /**
 166          * Set the security token. Only for temporary credentials provisioned through an EC2 instance.
 167          *
 168          * @param   string  $token
 169          */
 170         public function setToken(string $token): void
 171         {
 172                 $this->token = $token;
 173         }
 174
 175         /**
 176          * Get the signature method to use
 177          *
 178          * @return  string
 179          */
 180         public function getSignatureMethod(): string
 181         {
 182                 return $this->signatureMethod;
 183         }
 184
 185         /**
 186          * Set the signature method to use
 187          *
 188          * @param   string  $signatureMethod  One of v2 or v4
 189          *
 190          * @throws  Exception\InvalidSignatureMethod
 191          */
 192         public function setSignatureMethod(string $signatureMethod): void
 193         {
 194                 $signatureMethod = strtolower($signatureMethod);
 195                 $signatureMethod = trim($signatureMethod);
 196
 197                 if (!in_array($signatureMethod, ['v2', 'v4']))
 198                 {
 199                         throw new Exception\InvalidSignatureMethod;
 200                 }
 201
 202                 // If you switch to v2 signatures we unset the region.
 203                 if ($signatureMethod == 'v2')
 204                 {
 205                         $this->setRegion('');
 206
 207                         /**
 208                          * If we are using Amazon S3 proper (not a custom endpoint) we have to set path style access to false.
 209                          * Amazon S3 does not support v2 signatures with path style access at all (it returns an error telling
 210                          * us to use the virtual hosting endpoint BUCKETNAME.s3.amazonaws.com).
 211                          */
 212                         if (strpos($this->endpoint, 'amazonaws.com') !== false)
 213                         {
 214                                 $this->setUseLegacyPathStyle(false);
 215                         }
 216
 217                 } else {
 218                         if (empty($this->getRegion())) {
 219                                 $this->setRegion('us-east-1');
 220                         }
 221                 }
 222
 223                 $this->signatureMethod = $signatureMethod;
 224         }
 225
 226         /**
 227          * Get the Amazon S3 region
 228          *
 229          * @return  string
 230          */
 231         public function getRegion(): string
 232         {
 233                 return $this->region;
 234         }
 235
 236         /**
 237          * Set the Amazon S3 region
 238          *
 239          * @param   string  $region
 240          */
 241         public function setRegion(string $region): void
 242         {
 243                 /**
 244                  * You can only leave the region empty if you're using v2 signatures. Anything else gets you an exception.
 245                  */
 246                 if (empty($region) && ($this->signatureMethod == 'v4'))
 247                 {
 248                         throw new Exception\InvalidRegion;
 249                 }
 250
 251                 /**
 252                  * Setting a Chinese-looking region force-changes the endpoint but ONLY if you were using the original Amazon S3
 253                  * endpoint. If you're using a custom endpoint and provide a region with 'cn-' in its name we don't override
 254                  * your custom endpoint.
 255                  */
 256                 if (($this->endpoint == 's3.amazonaws.com') && (substr($region, 0, 3) == 'cn-'))
 257                 {
 258                         $this->setEndpoint('amazonaws.com.cn');
 259                 }
 260
 261                 $this->region = $region;
 262         }
 263
 264         /**
 265          * Is the connection to be made over HTTPS?
 266          *
 267          * @return  bool
 268          */
 269         public function isSSL(): bool
 270         {
 271                 return $this->useSSL;
 272         }
 273
 274         /**
 275          * Set the connection SSL preference
 276          *
 277          * @param   bool  $useSSL  True to use HTTPS
 278          */
 279         public function setSSL(bool $useSSL): void
 280         {
 281                 $this->useSSL = $useSSL ? true : false;
 282         }
 283
 284         /**
 285          * Get the Amazon S3 endpoint
 286          *
 287          * @return  string
 288          */
 289         public function getEndpoint(): string
 290         {
 291                 return $this->endpoint;
 292         }
 293
 294         /**
 295          * Set the Amazon S3 endpoint. Do NOT use a protocol
 296          *
 297          * @param   string  $endpoint  Custom endpoint, e.g. 's3.example.com' or 'www.example.com/s3api'
 298          */
 299         public function setEndpoint(string $endpoint): void
 300         {
 301                 if (stristr($endpoint, '://'))
 302                 {
 303                         throw new Exception\InvalidEndpoint;
 304                 }
 305
 306                 /**
 307                  * If you set a custom endpoint we have to switch to v2 signatures since our v4 implementation only supports
 308                  * Amazon endpoints.
 309                  */
 310                 if ((strpos($endpoint, 'amazonaws.com') === false))
 311                 {
 312                         $this->setSignatureMethod('v2');
 313                 }
 314
 315                 $this->endpoint = $endpoint;
 316         }
 317
 318         /**
 319          * Should I use legacy, path-style access to the bucket? You should only use it with custom endpoints. Amazon itself
 320          * is currently deprecating support for path-style access but has extended the migration date to an unknown
 321          * time https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/
 322          *
 323          * @return  bool
 324          */
 325         public function getUseLegacyPathStyle(): bool
 326         {
 327                 return $this->useLegacyPathStyle;
 328         }
 329
 330         /**
 331          * Set the flag for using legacy, path-style access to the bucket
 332          *
 333          * @param   bool  $useLegacyPathStyle
 334          */
 335         public function setUseLegacyPathStyle(bool $useLegacyPathStyle): void
 336         {
 337                 $this->useLegacyPathStyle = $useLegacyPathStyle;
 338
 339                 /**
 340                  * If we are using Amazon S3 proper (not a custom endpoint) we have to set path style access to false.
 341                  * Amazon S3 does not support v2 signatures with path style access at all (it returns an error telling
 342                  * us to use the virtual hosting endpoint BUCKETNAME.s3.amazonaws.com).
 343                  */
 344                 if ((strpos($this->endpoint, 'amazonaws.com') !== false) && ($this->signatureMethod == 'v2'))
 345                 {
 346                         $this->useLegacyPathStyle = false;
 347                 }
 348         }
 349
 350         /**
 351          * Should we use the dualstack URL (which will ship traffic over ipv6 in most cases). For more information on these
 352          * endpoints please read https://docs.aws.amazon.com/AmazonS3/latest/dev/dual-stack-endpoints.html
 353          *
 354          * @return  bool
 355          */
 356         public function getDualstackUrl(): bool
 357         {
 358                 return $this->useDualstackUrl;
 359         }
 360
 361         /**
 362          * Set the flag for using legacy, path-style access to the bucket
 363          *
 364          * @param   bool  $useDualstackUrl
 365          */
 366         public function setUseDualstackUrl(bool $useDualstackUrl): void
 367         {
 368                 $this->useDualstackUrl = $useDualstackUrl;
 369         }
 370 }