از امضای دیجیتال استفاده کنید

درخواست خود را با یک کلید API به صورت دیجیتال امضا کنید

بسته به استفاده شما، ممکن است برای احراز هویت درخواست‌ها، علاوه بر کلید API، به امضای دیجیتال نیاز باشد. مقاله زیر را ببینید:

• Maps Static API سایر محدودیت‌های استفاده

امضای دیجیتال چگونه کار می کند

امضاهای دیجیتال با استفاده از رمز امضای URL تولید می‌شوند که در کنسول ابری Google موجود است. این راز در اصل یک کلید خصوصی است که فقط بین شما و گوگل به اشتراک گذاشته می شود و منحصر به پروژه شماست.

فرآیند امضا از یک الگوریتم رمزگذاری برای ترکیب URL و راز مشترک شما استفاده می کند. امضای منحصربه‌فرد به‌دست‌آمده به سرورهای ما اجازه می‌دهد تا تأیید کنند که هر سایتی که با استفاده از کلید API شما درخواست ایجاد می‌کند مجاز به انجام این کار است.

درخواست های بدون امضا را محدود کنید

برای اطمینان از اینکه کلید API شما فقط درخواست های امضا شده را می پذیرد:

1. به صفحه سهمیه های پلتفرم Google Maps در کنسول Cloud بروید.
2. روی منوی کشویی پروژه کلیک کنید و همان پروژه ای را انتخاب کنید که هنگام ایجاد کلید API برای برنامه یا سایت خود استفاده کرده اید.
3. Maps Static API را از منوی کشویی APIs انتخاب کنید.
4. بخش درخواست های بدون امضا را باز کنید.
5. در جدول Quota Name ، روی دکمه ویرایش در کنار سهمیه ای که می خواهید ویرایش کنید کلیک کنید. به عنوان مثال، درخواست های بدون امضا در روز.
6. محدودیت سهمیه را در کادر ویرایش حد سهمیه به‌روزرسانی کنید.
7. ذخیره را انتخاب کنید.

قبل از شروع

قبل از شروع، URL صفحه وب را که حاوی نقشه استاتیک شما است، مشخص کنید. این URL همان آدرسی است که باید به صورت دیجیتالی امضا شود.

امضای درخواست های شما

امضای درخواست های شما شامل مراحل زیر است:

• مرحله 1: رمز امضای URL خود را دریافت کنید
• مرحله 2: یک درخواست بدون امضا بسازید
• مرحله 3: درخواست امضا شده را ایجاد کنید

مرحله 1: رمز امضای URL خود را دریافت کنید

برای دریافت رمز امضای URL پروژه خود:

1. به صفحه اعتبارنامه پلتفرم Google Maps در کنسول Cloud بروید.
2. کشویی پروژه را انتخاب کنید و همان پروژه ای را که هنگام ایجاد کلید API برای Maps Static API استفاده کردید، انتخاب کنید.
3. به سمت پایین به کارت Secret Generator بروید. فیلد مخفی فعلی حاوی راز امضای URL فعلی شما است.
4. این صفحه همچنین دارای ویجت Sign a URL now است که به شما امکان می دهد به طور خودکار درخواست Maps Static API را با استفاده از رمز امضای فعلی خود امضا کنید. به پایین اسکرول کنید تا کارت یک URL را امضا کنید تا به آن دسترسی داشته باشید.

برای دریافت رمز امضای URL جدید، Regenerate Secret را انتخاب کنید. راز قبلی 24 ساعت پس از ایجاد یک راز جدید منقضی می شود. پس از گذشت 24 ساعت، درخواست های حاوی راز قدیمی دیگر کار نمی کنند.

مرحله 2: درخواست امضا نشده خود را بسازید

نویسه‌هایی که در جدول زیر فهرست نشده‌اند باید با URL رمزگذاری شوند:

همین امر در مورد هر کاراکتر در مجموعه Reserved صدق می کند، اگر آنها در یک رشته متن ارسال شوند. برای اطلاعات بیشتر، کاراکترهای ویژه را ببینید.

URL درخواست امضا نشده خود را بدون امضا بسازید. برای دستورالعمل‌ها، به مستندات توسعه‌دهنده زیر مراجعه کنید:

• Maps Static API

مطمئن شوید که کلید API را نیز در پارامتر key قرار دهید. به عنوان مثال:

https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY

درخواست امضا شده را ایجاد کنید

برای موارد استفاده یکباره، مانند میزبانی یک تصویر ساده Maps Static API یا Street View Static API در صفحه وب خود، یا اهداف عیب‌یابی، می‌توانید با استفاده از ابزارک موجود Sign a URL now به طور خودکار امضای دیجیتال ایجاد کنید.

برای درخواست هایی که به صورت پویا تولید می شوند، به امضای سمت سرور نیاز دارید که به چند مرحله میانی اضافی نیاز دارد

در هر صورت، شما باید با یک URL درخواست مواجه شوید که یک پارامتر signature به انتهای آن اضافه شده است. به عنوان مثال:

https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY
&signature=BASE64_SIGNATURE

با استفاده از ویجت Sign a URL now

برای ایجاد یک امضای دیجیتال با یک کلید API با استفاده از ویجت Sign a URL now در Google Cloud Console:

1. ویجت Sign a URL now را پیدا کنید، همانطور که در مرحله 1 توضیح داده شد: رمز امضای URL خود را دریافت کنید .
2. در فیلد URL ، URL درخواست امضا نشده خود را از مرحله 2 بچسبانید: درخواست بدون امضا خود را بسازید .
3. فیلد URL امضا شده شما که ظاهر می شود حاوی URL امضا شده دیجیتالی شما خواهد بود. حتما کپی کنید

تولید امضای دیجیتال در سمت سرور

در مقایسه با ویجت Sign a URL now ، هنگام تولید امضای دیجیتال در سمت سرور، باید چند اقدام اضافی انجام دهید:

1. طرح پروتکل و بخش های میزبان URL را حذف کنید و فقط مسیر و پرس و جو را باقی بگذارید:

/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY

2. رمز امضای URL نمایش داده شده در یک Base64 اصلاح شده برای URL ها کدگذاری می شود.

   از آنجایی که اکثر کتابخانه های رمزنگاری نیاز دارند که کلید در قالب بایت خام باشد، احتمالاً باید قبل از امضا، رمز امضای URL خود را در قالب خام اصلی آن رمزگشایی کنید.

3. درخواست حذف شده بالا را با استفاده از HMAC-SHA1 امضا کنید.

4. از آنجایی که اکثر کتابخانه های رمزنگاری امضایی را در قالب بایت خام تولید می کنند، باید امضای باینری حاصل را با استفاده از Base64 اصلاح شده برای URL ها تبدیل کنید تا آن را به چیزی که می تواند در URL ارسال شود تبدیل کنید.

5. امضای کدگذاری شده با Base64 را به URL درخواست امضا نشده اصلی در پارامتر signature اضافه کنید. به عنوان مثال:

   https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY
   &signature=BASE64_SIGNATURE

برای نمونه‌هایی که روش‌های پیاده‌سازی امضای URL با استفاده از کد سمت سرور را نشان می‌دهند، به نمونه کد برای امضای URL در زیر مراجعه کنید.

کد نمونه برای امضای URL

بخش‌های زیر راه‌هایی برای پیاده‌سازی امضای URL با استفاده از کد سمت سرور نشان می‌دهند. URL ها باید همیشه در سمت سرور امضا شوند تا از افشای راز امضای URL شما برای کاربران جلوگیری شود.

#!/usr/bin/python
# -*- coding: utf-8 -*-
""" Signs a URL using a URL signing secret """

import hashlib
import hmac
import base64
import urllib.parse as urlparse


def sign_url(input_url=None, secret=None):
    """ Sign a request URL with a URL signing secret.
      Usage:
      from urlsigner import sign_url
      signed_url = sign_url(input_url=my_url, secret=SECRET)
      Args:
      input_url - The URL to sign
      secret    - Your URL signing secret
      Returns:
      The signed request URL
  """

    if not input_url or not secret:
        raise Exception("Both input_url and secret are required")

    url = urlparse.urlparse(input_url)

    # We only need to sign the path+query part of the string
    url_to_sign = url.path + "?" + url.query

    # Decode the private key into its binary format
    # We need to decode the URL-encoded private key
    decoded_key = base64.urlsafe_b64decode(secret)

    # Create a signature using the private key and the URL-encoded
    # string using HMAC SHA1. This signature will be binary.
    signature = hmac.new(decoded_key, str.encode(url_to_sign), hashlib.sha1)

    # Encode the binary signature into base64 for use within a URL
    encoded_signature = base64.urlsafe_b64encode(signature.digest())

    original_url = url.scheme + "://" + url.netloc + url.path + "?" + url.query

    # Return signed URL
    return original_url + "&signature=" + encoded_signature.decode()


if __name__ == "__main__":
    input_url = input("URL to Sign: ")
    secret = input("URL signing secret: ")
    print("Signed URL: " + sign_url(input_url, secret))

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.net.URISyntaxException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;  // JDK 1.8 only - older versions may need to use Apache Commons or similar.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class UrlSigner {

  // Note: Generally, you should store your private key someplace safe
  // and read them into your code

  private static String keyString = "YOUR_PRIVATE_KEY";
  
  // The URL shown in these examples is a static URL which should already
  // be URL-encoded. In practice, you will likely have code
  // which assembles your URL from user or web service input
  // and plugs those values into its parameters.
  private static String urlString = "YOUR_URL_TO_SIGN";

  // This variable stores the binary key, which is computed from the string (Base64) key
  private static byte[] key;
  
  public static void main(String[] args) throws IOException,
    InvalidKeyException, NoSuchAlgorithmException, URISyntaxException {
    
    BufferedReader input = new BufferedReader(new InputStreamReader(System.in));
    
    String inputUrl, inputKey = null;

    // For testing purposes, allow user input for the URL.
    // If no input is entered, use the static URL defined above.    
    System.out.println("Enter the URL (must be URL-encoded) to sign: ");
    inputUrl = input.readLine();
    if (inputUrl.equals("")) {
      inputUrl = urlString;
    }
    
    // Convert the string to a URL so we can parse it
    URL url = new URL(inputUrl);
 
    // For testing purposes, allow user input for the private key.
    // If no input is entered, use the static key defined above.   
    System.out.println("Enter the Private key to sign the URL: ");
    inputKey = input.readLine();
    if (inputKey.equals("")) {
      inputKey = keyString;
    }
    
    UrlSigner signer = new UrlSigner(inputKey);
    String request = signer.signRequest(url.getPath(),url.getQuery());
    
    System.out.println("Signed URL :" + url.getProtocol() + "://" + url.getHost() + request);
  }
  
  public UrlSigner(String keyString) throws IOException {
    // Convert the key from 'web safe' base 64 to binary
    keyString = keyString.replace('-', '+');
    keyString = keyString.replace('_', '/');
    System.out.println("Key: " + keyString);
    // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar.
    this.key = Base64.getDecoder().decode(keyString);
  }

  public String signRequest(String path, String query) throws NoSuchAlgorithmException,
    InvalidKeyException, UnsupportedEncodingException, URISyntaxException {
    
    // Retrieve the proper URL components to sign
    String resource = path + '?' + query;
    
    // Get an HMAC-SHA1 signing key from the raw key bytes
    SecretKeySpec sha1Key = new SecretKeySpec(key, "HmacSHA1");

    // Get an HMAC-SHA1 Mac instance and initialize it with the HMAC-SHA1 key
    Mac mac = Mac.getInstance("HmacSHA1");
    mac.init(sha1Key);

    // compute the binary signature for the request
    byte[] sigBytes = mac.doFinal(resource.getBytes());

    // base 64 encode the binary signature
    // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar.
    String signature = Base64.getEncoder().encodeToString(sigBytes);
    
    // convert the signature to 'web safe' base 64
    signature = signature.replace('+', '-');
    signature = signature.replace('/', '_');
    
    return resource + "&signature=" + signature;
  }
}

'use strict'

const crypto = require('crypto');
const url = require('url');

/**
 * Convert from 'web safe' base64 to true base64.
 *
 * @param  {string} safeEncodedString The code you want to translate
 *                                    from a web safe form.
 * @return {string}
 */
function removeWebSafe(safeEncodedString) {
  return safeEncodedString.replace(/-/g, '+').replace(/_/g, '/');
}

/**
 * Convert from true base64 to 'web safe' base64
 *
 * @param  {string} encodedString The code you want to translate to a
 *                                web safe form.
 * @return {string}
 */
function makeWebSafe(encodedString) {
  return encodedString.replace(/\+/g, '-').replace(/\//g, '_');
}

/**
 * Takes a base64 code and decodes it.
 *
 * @param  {string} code The encoded data.
 * @return {string}
 */
function decodeBase64Hash(code) {
  // "new Buffer(...)" is deprecated. Use Buffer.from if it exists.
  return Buffer.from ? Buffer.from(code, 'base64') : new Buffer(code, 'base64');
}

/**
 * Takes a key and signs the data with it.
 *
 * @param  {string} key  Your unique secret key.
 * @param  {string} data The url to sign.
 * @return {string}
 */
function encodeBase64Hash(key, data) {
  return crypto.createHmac('sha1', key).update(data).digest('base64');
}

/**
 * Sign a URL using a secret key.
 *
 * @param  {string} path   The url you want to sign.
 * @param  {string} secret Your unique secret key.
 * @return {string}
 */
function sign(path, secret) {
  const uri = url.parse(path);
  const safeSecret = decodeBase64Hash(removeWebSafe(secret));
  const hashedSignature = makeWebSafe(encodeBase64Hash(safeSecret, uri.path));
  return url.format(uri) + '&signature=' + hashedSignature;
}

using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
using System.Web;

namespace SignUrl {

  public struct GoogleSignedUrl {

    public static string Sign(string url, string keyString) {
      ASCIIEncoding encoding = new ASCIIEncoding();

      // converting key to bytes will throw an exception, need to replace '-' and '_' characters first.
      string usablePrivateKey = keyString.Replace("-", "+").Replace("_", "/");
      byte[] privateKeyBytes = Convert.FromBase64String(usablePrivateKey);

      Uri uri = new Uri(url);
      byte[] encodedPathAndQueryBytes = encoding.GetBytes(uri.LocalPath + uri.Query);

      // compute the hash
      HMACSHA1 algorithm = new HMACSHA1(privateKeyBytes);
      byte[] hash = algorithm.ComputeHash(encodedPathAndQueryBytes);

      // convert the bytes to string and make url-safe by replacing '+' and '/' characters
      string signature = Convert.ToBase64String(hash).Replace("+", "-").Replace("/", "_");
            
      // Add the signature to the existing URI.
      return uri.Scheme+"://"+uri.Host+uri.LocalPath + uri.Query +"&signature=" + signature;
    }
  }

  class Program {

    static void Main() {
    
      // Note: Generally, you should store your private key someplace safe
      // and read them into your code

      const string keyString = "YOUR_PRIVATE_KEY";
  
      // The URL shown in these examples is a static URL which should already
      // be URL-encoded. In practice, you will likely have code
      // which assembles your URL from user or web service input
      // and plugs those values into its parameters.
      const  string urlString = "YOUR_URL_TO_SIGN";
      
      string inputUrl = null;
      string inputKey = null;
    
      Console.WriteLine("Enter the URL (must be URL-encoded) to sign: ");
      inputUrl = Console.ReadLine();
      if (inputUrl.Length == 0) {
        inputUrl = urlString;
      }     
    
      Console.WriteLine("Enter the Private key to sign the URL: ");
      inputKey = Console.ReadLine();
      if (inputKey.Length == 0) {
        inputKey = keyString;
      }
      
      Console.WriteLine(GoogleSignedUrl.Sign(inputUrl,inputKey));
    }
  }
}

نمونه هایی در زبان های اضافی

نمونه هایی که زبان های بیشتری را پوشش می دهند در پروژه امضای url موجود است.

عیب یابی

اگر درخواست شامل یک امضای نامعتبر باشد، API یک خطای HTTP 403 (Forbidden) برمی‌گرداند. این خطا به احتمال زیاد در صورتی رخ می دهد که رمز امضای استفاده شده به کلید API ارسال شده مرتبط نباشد، یا اگر ورودی غیرASCII قبل از امضا با URL رمزگذاری نشده باشد.

برای عیب‌یابی مشکل، URL درخواست را کپی کنید، پارامتر پرس و جو signature را حذف کنید، و یک امضای معتبر را طبق دستورالعمل‌های زیر ایجاد کنید:

برای ایجاد امضای دیجیتال با کلید API با استفاده از ابزارک Sign a URL now در Google Cloud Console:

1. ویجت Sign a URL now را پیدا کنید، همانطور که در مرحله 1 توضیح داده شد: رمز امضای URL خود را دریافت کنید .
2. در فیلد URL ، URL درخواست امضا نشده خود را از مرحله 2 بچسبانید: درخواست بدون امضا خود را بسازید .
3. فیلد URL امضا شده شما که ظاهر می شود حاوی URL امضا شده دیجیتالی شما خواهد بود. حتما کپی کنید