Menggunakan Tanda Tangan Digital

Menandatangani permintaan secara digital dengan kunci API

Bergantung pada penggunaan Anda, tanda tangan digital - di samping kunci API - mungkin diperlukan untuk mengautentikasi permintaan. Lihat artikel berikut:

Cara kerja tanda tangan digital

Tanda tangan digital dibuat menggunakan rahasia penandatanganan URL, yang tersedia di Konsol Google Cloud. Rahasia ini pada dasarnya adalah kunci pribadi, yang hanya dibagikan antara Anda dan Google, dan bersifat unik untuk project Anda.

Proses penandatanganan menggunakan algoritma enkripsi untuk menggabungkan URL dan rahasia bersama milik Anda. Tanda tangan unik yang dihasilkan memungkinkan server kami memverifikasi bahwa situs yang membuat permintaan menggunakan kunci API Anda telah diberi otorisasi untuk melakukannya.

Membatasi permintaan yang tidak ditandatangani

Untuk memastikan kunci API Anda hanya menerima permintaan yang ditandatangani:

  1. Buka halaman Quotas Google Maps Platform di Konsol Cloud.
  2. Klik drop-down project dan pilih project yang sama yang Anda gunakan saat membuat kunci API untuk aplikasi atau situs Anda.
  3. Pilih Maps Static API dari drop-down API.
  4. Luaskan bagian Unsigned requests.
  5. Di tabel Quota Name, klik tombol edit di sebelah kuota yang ingin Anda edit. Misalnya, Unsigned requests per day.
  6. Perbarui Quota limit di panel Edit Quota Limit.
  7. Pilih Save.

Sebelum memulai

Sebelum memulai, cari tahu URL untuk halaman web yang berisi peta statis Anda. URL ini adalah URL yang harus ditandatangani secara digital.

Menandatangani permintaan

Lakukan langkah-langkah berikut untuk menandatangani permintaan Anda:

Langkah 1: Dapatkan rahasia penandatanganan URL

Untuk mendapatkan rahasia penandatanganan URL project Anda:

  1. Buka halaman Credentials Google Maps Platform di Konsol Cloud.
  2. Pilih drop-down project dan pilih project yang sama dengan yang Anda gunakan saat membuat kunci API untuk Maps Static API.
  3. Scroll ke bawah ke kartu Secret Generator. Kolom Current secret berisi rahasia penandatanganan URL Anda saat ini.
  4. Halaman ini juga menampilkan widget Sign a URL now yang memungkinkan Anda secara otomatis menandatangani permintaan Maps Static API menggunakan rahasia penandatanganan Anda saat ini. Scroll ke bawah ke kartu Sign a URL now untuk mengaksesnya.

Untuk mendapatkan rahasia penandatanganan URL baru, klik Regenerate Secret. Masa berlaku rahasia sebelumnya akan berakhir 24 jam setelah Anda membuat rahasia yang baru. Setelah 24 jam, permintaan yang berisi rahasia lama tidak akan berfungsi lagi.

Langkah 2: Buat permintaan yang tidak ditandatangani

Karakter yang tidak tercantum dalam tabel di bawah harus dienkode ke URL:

Ringkasan Karakter URL yang Valid
KumpulankarakterPenggunaan URL
Alfanumerik a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 String teks, penggunaan skema (http), port (8080), dll.
Tanpa fungsi khusus - _ . ~ String teks
Dengan fungsi khusus ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Karakter kontrol dan/atau String Teks

Hal yang sama berlaku untuk setiap karakter dalam kumpulan Dengan fungsi khusus, jika karakter tersebut diteruskan dalam string teks. Untuk info selengkapnya, lihat Karakter khusus.

Buat URL permintaan yang tidak ditandatangani tanpa tanda tangan. Untuk mengetahui petunjuknya, lihat dokumentasi developer berikut:

Pastikan Anda juga menyertakan kunci API dalam parameter key. Contoh:

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

Membuat permintaan yang ditandatangani

Untuk kasus penggunaan satu kali, seperti menghosting gambar Maps Static API atau Street View Static API sederhana pada halaman web, atau untuk memecahkan masalah, Anda dapat membuat tanda tangan digital secara otomatis menggunakan widget Sign a URL now yang tersedia.

Untuk permintaan yang dibuat secara dinamis, Anda membutuhkan penandatanganan sisi server, yang memerlukan beberapa langkah perantara tambahan

Apa pun langkah yang diambil, Anda akan membuat URL permintaan dengan parameter signature yang ditambahkan ke bagian akhir. Contoh:

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

Untuk membuat tanda tangan digital dengan kunci API menggunakan widget Sign a URL now di Konsol Google Cloud:

  1. Cari widget Sign a URL now, seperti yang dijelaskan di Langkah 1: Dapatkan rahasia penandatanganan URL.
  2. Di kolom URL, tempel URL permintaan yang tidak ditandatangani dari Langkah 2: Buat permintaan yang tidak ditandatangani.
  3. Kolom Your Signed URL yang muncul akan berisi URL yang ditandatangani secara digital. Pastikan untuk membuat salinan.
Membuat tanda tangan digital sisi server

Dibandingkan dengan widget Sign a URL now, Anda harus melakukan beberapa langkah tambahan saat membuat tanda tangan digital sisi server:

  1. Hapus bagian host dan skema protokol dari URL, sehingga hanya jalur dan kueri yang tersisa:

  2. /maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY
    
  3. Rahasia penandatanganan URL yang ditampilkan dienkode menggunakan Base64 yang dimodifikasi untuk URL.

    Karena sebagian besar library kriptografis memerlukan kunci dalam format byte mentah, Anda mungkin harus mendekode rahasia penandatanganan URL ke format mentah aslinya sebelum menandatangani.

  4. Tanda tangani permintaan yang dihapus di atas menggunakan HMAC-SHA1.
  5. Karena sebagian besar library kriptografis menghasilkan tanda tangan dalam format byte mentah, Anda harus mengonversi tanda tangan biner yang dihasilkan menggunakan Base64 yang dimodifikasi untuk URL agar tanda tangan tersebut dapat dikonversi menjadi sesuatu yang dapat yang diteruskan dalam URL.

  6. Tambahkan tanda tangan yang dienkode menggunakan Base64 ke URL permintaan asli yang tidak ditandatangani di parameter signature. Contoh:

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

Untuk contoh yang menunjukkan cara menerapkan penandatanganan URL menggunakan kode sisi server, lihat Kode contoh untuk penandatanganan URL di bawah.

Kode contoh untuk penandatanganan URL

Bagian berikut ini menunjukkan cara menerapkan penandatanganan URL menggunakan kode sisi server. URL harus selalu ditandatangani sisi server agar rahasia penandatanganan URL tidak dapat dilihat pengguna.

Python

Contoh di bawah ini menggunakan library Python standar untuk menandatangani URL. (Download kodenya.)

#!/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))

Java

Contoh di bawah ini menggunakan class java.util.Base64 yang tersedia sejak JDK 1.8 - versi lama mungkin perlu menggunakan Apache Commons atau yang serupa. (Download kodenya.)

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;
  }
}

Node.js

Contoh di bawah ini menggunakan modul Node native untuk menandatangani URL. (Download kodenya.)

'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;
}

C#

Contoh di bawah ini menggunakan library System.Security.Cryptography default untuk menandatangani permintaan URL. Perhatikan bahwa kita perlu mengonversi encoding Base64 default untuk mengimplementasikan versi aman untuk URL. (Download kodenya.)

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));
    }
  }
}

Contoh dalam bahasa lain

Contoh yang mencakup lebih banyak bahasa tersedia di project url-signing.

Pemecahan masalah

Jika permintaan menyertakan tanda tangan yang tidak valid, API akan menampilkan error HTTP 403 (Forbidden). Error kemungkinan besar terjadi jika rahasia penandatanganan yang digunakan tidak ditautkan ke kunci API yang diteruskan, atau jika input non-ASCII tidak dienkode ke URL sebelum ditandatangani.

Untuk memecahkan masalah ini, salin URL permintaan, hapus parameter kueri signature, lalu buat ulang tanda tangan yang valid dengan mengikuti petunjuk di bawah:

Untuk membuat tanda tangan digital dengan kunci API menggunakan widget Sign a URL now di Konsol Google Cloud:

  1. Cari widget Sign a URL now, seperti yang dijelaskan di Langkah 1: Dapatkan rahasia penandatanganan URL.
  2. Di kolom URL, tempel URL permintaan yang tidak ditandatangani dari Langkah 2: Buat permintaan yang tidak ditandatangani.
  3. Kolom Your Signed URL yang muncul akan berisi URL yang ditandatangani secara digital. Pastikan untuk membuat salinan.