js+php client + documentation

README.md

@@ -1 +1,15 @@
-# hit-doc
+#  AWS SDK
+Данный раздел описывает библиотеки, необходимые, чтобы подключиться и использовать сервисы Hotbox/Icebox.
+Здесь вы найдете подробные инструкции:
++ Установке библиотек
++ Формированию учетных данных (необходимо для подписи запросов)
++ Использованию каждой отдельной библиотеки
+Также к каждой библиотеке прилогаются тесты иллюстрирующие возможные варианты использования.
+
+Для получения информации относительно методов, поддерживаемых сервисами Hotbox/Icebox:[hotbox-help](https://help.mail.ru/hotbox-help)
+
+При возникновении любых вопросов/сложностей вы можете написать нам и мы поможем вам решить их:
+```[email protected]```
+
+
+

authorization/v4-query/README.md

@@ -0,0 +1,70 @@
+####  Для функции создания сигнатуры вам необходимы следующие параметры:
+##### 1) Method:
+```
+GET и тд
+```
+##### 2) Credentials:
+```
+    - access_key = "you-access-key"
+    - secret_key = "you-secret-key"
+    - region = "ru-msk"
+```
+##### 3) Service:
+```
+s3
+```
+##### 4) HashedPlayload
+```
+UNSIGNED-PAYLOAD
+```
+##### 5, 6) timeStamp и dateStamp
+Если есть заголовок 'x-amz-date'
+```
+timeStamp = содержание заголовка 'x-amz-date'
+dateStamp = часть отображающая время в заголовке 'x-amz-date'
+```
+Например:
+```
+x-amz-date = 20170609T120101Z
+timeStamp = 20170609T120101Z
+dateStamp = 20170609
+```
+Если нет заголовока 'x-amz-date', но  есть заголовок 'date'
+* из заголовка date вычисляем значения timeStamp и dateStamp
+
+##### 7) CanonicalHeaders
+
+смотри файл [_get_canonical_and_signed_headers](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/_get_canonical_and_signed_headers.md)
+
+##### 8) SignedHeaders
+смотри файл [_get_canonical_and_signed_headers](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/_get_canonical_and_signed_headers.md)
+##### 9) Credential (не хеш с ключами доступа а строка включающаяся url в 'x-amz-credentials') - объединяются в одну строку через "\n"
+```
+access_key
+dateStamp
+region
+service
+"aws4_request"
+```
+##### 10) Expires
+```
+Содержание заголовка 'x-amz-expires' - число в секундах или дефолтное значение 86400
+```
+##### 11) URI
+1. До начала вычисления подписи необходимо добавить в query параметры урла все параметры авторизации кроме сигнатуры
+2. Если в урле уже содержатся query параметры, то параметры авторизации дописываются после них
+3. Данные параметры добавляются через "&"
+
+- timeStamp - смотри 5 пункт
+- EncodedCredentialString - Credential из пункта 9 с заэнкожеными символами (смотри файл  [_uri_encode](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/_uri_encode.md))
+- Expires - смотри 10 пункт
+- EncodedSignedHeaders - SignedHeaders из пункта 8  с заэнкожеными символами (смотри файл  [_uri_encode](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/_uri_encode.md))
+```
+"X-Amz-Algorithm=AWS4-HMAC-SHA256"
+"X-Amz-Credential=EncodedCredentialString"
+"X-Amz-Date=timeStamp"
+"X-Amz-Expires=Expires"
+"X-Amz-SignedHeaders=EncodedSignedHeaders"
+```
+
+### Следуйте в файл  [SignatureCalculating](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/SignatureCalculating.md)

authorization/v4-query/SignatureCalculating.md

@@ -0,0 +1,67 @@
+#### SignatureCalculating
+
+##### 1. Формирование CanonicalRequest
+Необходимо объединить в 1 строку следующие элементы через  "\n"
+- CanonicalUri - Uri пропущенный через функцию канонаколизации [смотри файл _uri_encode](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/_uri_encode.md)
+- CanonicalQuery query параметры урла после пропущенные через функцию [смотри файл_sort_query_string](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/_sort_query_params.md)
+- описание остальных параметров смотри в [ основные параметры ](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/README.md)
+```
+method
+CanonicalURI
+CanonicalQueryString
+CanonicalHeaders
+SignedHeaders
+HashedPlayload
+```
+##### 2. Формирование Scope
+Необходимо объединить в 1 строку следующие элементы через  "\n"
+- описание параметров смотри в [ основные параметры ](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/README.md)
+```
+dateStamp
+region
+service
+"aws4_request"
+
+```
+##### 3. Формирование String2Sign
+Необходимо объединить в 1 строку следующие элементы через  "\n"
+- Scope - смотри пункт 2
+- описание остальных параметров смотри в [ основные параметры ](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/README.md)
+```
+"AWS4-HMAC-SHA256",
+timeStamp,
+Scope,
+sha256_hex(CanonicalRequest)
+```
+##### 4. Формирование Signature
+ 1. Формирование kSigning
+ ```
+kSecret   = "AWS4" + secret_key;
+kDate     = hmac_sha256(dateStamp, kSecret);
+kRegion   = hmac_sha256(region, kDate);
+kService  = hmac_sha256(service, kRegion);
+kSigning  = hmac_sha256("aws4_request", kService);
+ ```
+2. Формирование Signature
+- String2Sign - смотри пункт 3
+- kSigning    - смотри пункт 4 часть 1
+```
+Signature = hmac_sha256_hex( String2Sign, kSigning);
+```
+##### 5. Формирование Url
+теперь необходимо присоединить параметр с вычисленной signature из пункта 4 в конец урла:
+```
+url?query_param1&auth_query_params&X-Amz-Signature=Signature"
+```
+- query_param1 - любые параметры относящиеся к запросу  (acl и  тд)
+- auth_query_params = (смотри пункт 11 [параметры авторизации](https://github.com/mailru/hit-doc/blob/master/authorization/v4-query/README.md))
+```
+"X-Amz-Algorithm=AWS4-HMAC-SHA256"
+"X-Amz-Credential=EncodedCredentialString"
+"X-Amz-Date=timeStamp"
+"X-Amz-Expires=Expires"
+"X-Amz-SignedHeaders=EncodedSignedHeaders"
+```
+
+
+

authorization/v4-query/_get_canonical_and_signed_headers.md

@@ -0,0 +1,51 @@
+#### Данная функция
+- принимает в качестве аргументов
+```
+все заголовки, которые вы включаете в запрос
+```
+- возвращает две ссылки
+```
+  - одна содержит  CanonicalHeaders
+  - вторая содержит SignedHeaders
+```
+#### В данной функции вы должны:
+- все заголовки должны быть в lowercase
+- значения всех заголовков должны подчиняться правилам
+  - группа идущих подряд пробелов/табов заменяется на один пробел
+  - пробелы/табы в начале и в конце удаляются
+####  Формирование canonicalheaders и signedheaders
+- canonicalHeaders формируются путем объединения подписываемых заголовков и их значений через ":". Каждая такая пара заголовок-значение разделяются "\n"
+Например:
+имеются заголовки
+```
+headers:
+  "X-amz-date" = "20170801T000000Z"
+  "Host"       = "bucketname.cldmail.ru"
+  "X-amz-acl"  = "public"
+  "Connection"   = "close"
+```
+вы должны получить
+```
+CanonicalHeaders =  "x-amz-date:20170801T000000Z\nhost:bucketname.cldmail.ru\nx-amz-acl:public"
+SignedHeaders    = "x-amz-date;host;x-amz-acl"
+```
+####  В качестве примера прилагается перловая функция вычисляющая canonicalheaders и signedheaders
+```
+sub _canonicalize_headers_aws4 {
+    my $hdr = shift;                                                  # принимаемые функцией параметры - заголовки
+    my ($CanonicalHeaders,@SignedHeaders, %new_hdr)
+    for my $header_name (@headers){                                    # копирование всех хедеров и их значений в новый хеш "%new_hdr"
+        $new_hdr{$header_name} = $hdr->{$header_name};
+    }
+
+    for my $key (sort keys %new_hdr){                                  # все заголовки сортируются и при этом
+        $new_hdr{$key} =~ s/[\s\t]+/ /g;                                 # группа пробелов/табов заменяется единичным пробелом
+        $new_hdr{$key} =~ s/^\s?(.+)\s?$/$1/;                            # пробелы с начала и с конца значения заголовка удаляются
+
+        $CanonicalHeaders .= "$key:$new_hdr{$key}\n";                  # конкатенация  "заголовок:значение\n" к canonicalheaders
+        push @SignedHeaders, $key;                                     # добавление заголовка в массив signedheaders
+    }
+    my $headers = join (";",@SignedHeaders);                           # превращение массива signedheaders в строку состаяющую из элементов этого массива, объндиненных через ";"
+    return $CanonicalHeaders, $headers;                                # возвращение canonicalheaders и signedheaders
+}
+```

authorization/v4-query/_sort_query_params.md

@@ -0,0 +1,47 @@
+#### Данная функция
+- принимает
+```
+строку
+```
+- отдает
+```
+строку
+```
+#### Данная функция выполняет
+```
+X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EncodedCredentialString&X-Amz-Date=timeStamp&X-Amz-Expires=Expires&X-Amz-SignedHeaders=EncodedSignedHeaders
+```
+-  делит строку на массив из отдельных элементов query параметров
+```
+array:
+  - X-Amz-Algorithm=AWS4-HMAC-SHA256
+  - X-Amz-Credential=EncodedCredentialString
+  - X-Amz-Date=timeStamp
+  - X-Amz-Expires=Expires
+  - X-Amz-SignedHeaders=EncodedSignedHeaders  
+```
+- делит каждый элемент массива на ключ и значение
+- анескейпит и эскейпит каждый ключ и значение
+- заменяет все плюсы на пробелы
+
+- собирается обратно в строку
+```
+X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EncodedCredentialString&X-Amz-Date=timeStamp&X-Amz-Expires=Expires&X-Amz-SignedHeaders=EncodedSignedHeaders
+```
+
+#### Пример функции на perl
+
+```
+sub _sort_query_string {
+	return '' unless length $_[0];
+	my @params;
+	for my $param (split /&/, $_[0] ) {
+		my ( $key, $value ) =
+			map { tr/+/ /; uri_escape( uri_unescape( $_ ) ) }
+			split /=/, $param;
+		push @params, join '=', $key, $value;
+	}
+	return join '&', sort @params;
+}
+
+```

authorization/v4-query/_uri_encode.md

@@ -0,0 +1,49 @@
+#### Данная функция
+- принимает в качестве аргументов
+```
+строка
+```
+возвращает
+```
+строка
+```
+#### В данной функции вы должны
+- заэнкодить все символы которые не являются unreserved
+     - включение и выключение слеша из этого списка обусловлено необходимостью энкодить и урлы и обычные параметры
+```
+A-Za-z0-9._~-
+```
+```
+A-Za-z0-9._~/-
+```
+
+- заменить все плюсы на %20
+- после энкодинга необходимо прогнать полученную строку через функцию (_canonicalize) которая выполнит следующее:
+  - идет по строке
+    - если встречается %.. то разъенкоживает символ а затем если он не unreserved то энкодят его снова
+    - если встречается простой символ то оставляем его как есть а затем если он не unreserved то энкодим его
+    - (данная функция обеспечивает абсолютно правильный энкодинг вне зависимости от пришедших параметров)
+
+#### Прилагается пример данной функции на языке perl
+```
+our %UNRESERVED = map { $_ => 1 } 'a'..'z','A'..'Z','0'..'9',qw(- . _ ~ /);
+
+sub _canonicalize {
+	my ($uri) = @_;
+	$uri =~ s/\+/%20/g;
+	$uri =~ s{\G%(..)|(.)}{
+	    my $c = $1 ? chr(hex($1)) : $2;
+	    $UNRESERVED{$c} ? $c : sprintf "%%%02X", ord($c)
+	}ge;
+	return $uri;
+}
+
+sub _uri_encode {
+	my ($uri, $encode_slash) = @_;
+	my $unreserved_string = $encode_slash ? "A-Za-z0-9._~-" : "A-Za-z0-9._~/-";
+	$uri =~ s{([^$unreserved_string])}{ sprintf '%%%02X',ord($1) }sge;
+	$uri =~ s/\+/%20/g;
+	$uri = _canonicalize($uri, $encode_slash);
+	return $uri;
+}
+```