Bagaimana menggunakannya¶

Untuk mengambil keuntungan dari perlindungan CSRF dalam tampilan anda, ikuti langkah-langkah ini:

1. Middleware CSRD diaktifkan secara awalan dalam pengaturan MIDDLEWARE. Jika anda menimpa pengaturan itu, ingat bahwa 'django.middleware.csrf.CsrfViewMiddleware'  harys datang sebelum tampilan middleware apapun yang menganggap bahwa serangan CSRF telah ditangani.

   Jika anda meniadakan itu, yang tidak dianjurkan, anda dapat menggunakan csrf_protect() pada tampilan tertentu anda ingin lindungi (lihat dibawah).

2. Dalam cetakan manapun yang menggunakan formulir POST, gunakan etiket csrf_token didalam unsur <form> jika formulir adalah untuk internalURL, misalnya:

   <form method="post">{% csrf_token %}
   

   Ini jangan diselesaikan untuk formulir POST yang sasaran external URL, sejak itu akan menyebabkan token CSRF bocor, membawa pada kerentanan.

3. Dalam fungsi tampilan sesuai, pastikan bahwa RequestContext digunakan untuk membangun tanggapan sehingga {% csrf_token %} akan bekerja dengan benar. Jika anda sedang menggunakan fungsi render(), tampilan umum, atau aplikasi bantuan, anda sudah dilindungi sejak ini semua menggunakan RequestContext.

function getCookie(name) {
    var cookieValue = null;
    if (document.cookie && document.cookie !== '') {
        var cookies = document.cookie.split(';');
        for (var i = 0; i < cookies.length; i++) {
            var cookie = cookies[i].trim();
            // Does this cookie string begin with the name we want?
            if (cookie.substring(0, name.length + 1) === (name + '=')) {
                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
                break;
            }
        }
    }
    return cookieValue;
}
var csrftoken = getCookie('csrftoken');

var csrftoken = Cookies.get('csrftoken');

{% csrf_token %}
<script type="text/javascript">
// using jQuery
var csrftoken = jQuery("[name=csrfmiddlewaretoken]").val();
</script>

function csrfSafeMethod(method) {
    // these HTTP methods do not require CSRF protection
    return (/^(GET|HEAD|OPTIONS|TRACE)$/.test(method));
}
$.ajaxSetup({
    beforeSend: function(xhr, settings) {
        if (!csrfSafeMethod(settings.type) && !this.crossDomain) {
            xhr.setRequestHeader("X-CSRFToken", csrftoken);
        }
    }
});

$httpProvider.defaults.xsrfCookieName = 'csrftoken';
$httpProvider.defaults.xsrfHeaderName = 'X-CSRFToken';

<form method="post">{{ csrf_input }}

Permintaan tertolak¶

Secara awalan, sebuah tanggapan '403 Forbidden' dikirim ke pengguna jika sebuah permintaan datang gaagl melakukan pemeriksaan oleh CsrfViewMiddleware. Ini harus biasanya hanya dilihat ketika ada Cross Site Request Forgery asli, atau ketika, karena pada kesalahan pemrograman, token CSRF belum dimasukkan dengan formulir POST.

Halaman kesalahan, bagaimanapun, itu tidak sangat ramah, jadi anda mungkin ingin menyediakan tampilan anda sendiri untuk menangani kondisi ini. Untuk melakukan ini, cukup setel pengaturan CSRF_FAILURE_VIEW.

Kegagalan CSRF adalah tercatat sebagai peringatan pada pencatat django.security.csrf 1.

Bagaimana itu bekerja¶

Perlindungan CSRF berdasarkan pada hal-hal berikut:

1. Sebuah kue CSRF yaitu berdasarkan pada nilai rahasia acak, yang situs-situs lain tidak akan mengaksesnya.

   Kue ini disetel oleh CsrfViewMiddleware. Itu dikirim dengan setiap tanggapan yang telah memanggil django.middleware.csrf.get_token() (fungsi digunakan secara internal untuk mengambil token CSRF), jika itu belum disetel pada permintaan.

   Untuk terlindungi terhadap serangan BREACH, token tidak cukup rahasia; sebuah garam acak ditambahkan ke rahasia dan digunakan untuk mengaduk itu.

   Untuk alasan keamanan, nilai dari rahasia berubah setiap waktu pengguna masuk.

2. Sebuah bidang formulir sembunyi dengan nama 'csrfmiddlewaretoken' hadir dalam semua formulir POST keluar. Nilai dari bidang ini adalah, kembali, nilai rahasia, dengan garam yang keduanya ditambahkan ke itu dan digunakan untuk mengacak nya. Garam dibangkitkan kembali pada setiap panggilan pada get_token() sehingga nilai bidang formulir berubah dalam setiap tanggapan tersebut.

   Bagian selesai dengan etiket cetakan.

3. Untuk semua permintaan datang yang tidak menggunakan HTTP GET, HEAD, OPTIONS atau TRACE, kue CSRF harus hadir, dan bidang 'csrfmiddlewaretoken' harus hadir dan benar. Jika itu tidak, pengguna akan mendapatkan kesalahan 403.

   Ketika mengesahkan nilai bidang 'csrfmiddlewaretoken', hanya rahasia, bukan seluruhnya token, dibandingkan dengan rahasia dalam nilai kue. Ini mengizinkan penggunaan dari token selalu-berubah. Selagi setiap permintaan mungkin menggunakan token nya sendiri, rahasia tetap umum pada semua.

   Pemeriksaan ini selesai dengan CsrfViewMiddleware.

4. Sebagai tambahan, untuk permintaan HTTP, pemeriksaan perujuk ketat oleh CsrfViewMiddleware. Ini berarti bahwa bahkan jika sebuah subranah dapat disetel atau dirubah kue-kue pada ranah anda, itu dapat memaksa seorang pengguna untuk menempatkan ke aplikasi anda sejak bahwa permintaan tidak akan datang dari ranah tepat anda sendiri.

   Ini juga membahas serangan seorang-dalam-tengah yang memungkinkan dibawah HTTPS ketika menggunakan sebuah rahasia berdiri sendiri sesi, dikarenakan kenyataan bahwa kepala Set-Cookie HTTP (sayangnya) diterima oleh klien bahkan ketika mereka sedang berbicara pada situs dibawah HTTPS. (Pemeriksaan perujuk belum dilakukan untuk permintaan HTTP karena kehadiran dari kepala Referer tidak cukup handal dibawah HTTP.)

   Jika pengaturan CSRF_COOKIE_DOMAIN disetel, perujuk dibandingkan terhadap itu. Pengaturan ini mendukung subranah. Sebagai contoh, CSRF_COOKIE_DOMAIN = '.example.com' akan mengizinkan permintaan POST dari www.example.com dan api.example.com. Jika pengaturan tidak disetel, kemudian perujuk harus cocok kepala Host HTTP.

   Memperluas rujukan diterima diluar rumah saat ini atau ranah kue dapat diselesaikan dengan pengaturan CSRF_TRUSTED_ORIGINS.

Ini memastikan bahwa hanya formulir yang asli dari ranah terpercaya dapat digunakan untuk data POST kembali.

It deliberately ignores GET requests (and other requests that are defined as 'safe' by RFC 7231#section-4.2.1). These requests ought never to have any potentially dangerous side effects, and so a CSRF attack with a GET request ought to be harmless. RFC 7231#section-4.2.1 defines POST, PUT, and DELETE as 'unsafe', and all other methods are also assumed to be unsafe, for maximum protection.

Perlindungan CSRF tidak dapat melindungi terhadap serangan seorang-dalam-tengah, jadi gunakan HTTPS dengan HTTP Strict Transport Security. Itu juga menganggap validation of the HOST header dan yang tidak ada cross-site scripting vulnerabilities apapun pada situs anda (karena kerentanan XSS sudah membiarkan seorang penyerang melakukan apapun mengizinkan kerentanan CSRF dan lebih buruk lagi).

Tembolok¶

Jika etiket cetakan csrf_token digunakan oleh cetakan (atau fungsi get_token dipanggil cara lain), CsrfViewMiddleware akan menambah sebuah kue dan sebuah kepala Vary: Cookie ke tanggapan. Ini berarti bahwa middleware akan bermain baik dengan middleware cache jika itu digunakan sesuai panduan (UpdateCacheMiddleware berjalan sebelum semua middleware lain).

Bagaimanapun, jika anda menggunakan penghias cache pada tampilan masing-masing, middleware CSRF belum bisa menyetel kepala Vary atau kue CSRF, dan tanggapan akan di simpan sementara tanpa salah satu. Dalam kasus ini, pada tampilan apapun yang akan membutuhkan token CSRF untuk dimasukkan anda harus menggunakan penghias django.views.decorators.csrf.csrf_protect() dahulu:

from django.views.decorators.cache import cache_page
from django.views.decorators.csrf import csrf_protect

@cache_page(60 * 15)
@csrf_protect
def my_view(request):
    ...

Jika anda sedang menggunakan tampilan berdasarkan-kelas, anda dapat mengacu ke Decorating class-based views1.

Pengujian¶

CsrfViewMiddleware biasanya berupa halaman besar untuk mencoba fungsi tampilan, dikarenakan kebutuhan untuk token CSRF yang harus dikirim dengan setiap permintaan POST. Untuk alasan ini, klien HTTP Django untuk percobaan telah dirubah untuk menyetel bendera di permintaan yang mengendurkan middleware dan penghias csrf_protect sehingga mereka tidak lagi menolak permintaan. Dalam setiap kepatuhan lain (misalnya mengirim kue dll.), mereka berperilaku sama.

Jika, untuk beberapa alasan, anda ingin klien percobaan melakukan pemeriksaan CSRF, anda dapat membuat sebuah instance dari klien percobaan yang memaksa pemeriksaan CSRF:

>>> from django.test import Client
>>> csrf_client = Client(enforce_csrf_checks=True)

Batasan¶

Sub ranah dalam sebuah situs akan dapat menyetel kue pada klien untuk seluruh ranah. Dengan mengatur kue dan menggunakan token berhubungan, sub ranah akan dapat mengelak perlindungan CDRF. Cara satu-satunya mengindari ini adalah memastikan bahwa sub ranah dikendalikan oleh pengguna terpercaya (atau, setidaknya tidak dapat menyetel kue). Catat bahwa bahkan tanpa CSRF, ada banyak kerentanan seperti fiksasi sesi, bahwa memberikan sub ranah pada pihak tidak dipercaya adalah ide buruk, dan kerentanan ini tidak dapat dengan mudah diperbaiki dengan peramban saat ini.

Kasus tepi¶

Tampilan-tampilan tertentu dapat memiliki persyaratan tidak biasa yang berarti mereka tidak cocok pola biasa dipertimbangkan disini. Sejumlah kegunaan dapat berguna dalam keadaan seperti ini. Skenario mereka mungkin dibutuhkan digambarkan dalam bagian berikut.

from django.views.decorators.csrf import csrf_exempt, csrf_protect

@csrf_exempt
def my_view(request):

    @csrf_protect
    def protected_path(request):
        do_something()

    if some_condition():
       return protected_path(request)
    else:
       do_something_else()

Aplikasi bantuan dan dipakai kembali¶

Karena itu memungkinkan untuk pengembang mematikan CsrfViewMiddleware, semua tampilan terkait dalam aplikasi bantuan menggunakan penghias csrf_protect untuk memastikan keamanan dari aplikasi ini terhadap CSRF. Dianjurkan bahwa pengembang dari aplikasi digunakan kembali lainnya yang ingin jaminan sama juga menggunakan penghias csrf_protect pada tampilan mereka.

Pengaturan¶

Sejumlah pengaturan dapat digunakan untuk mengendalikan perilaku CSRF Django:

• CSRF_COOKIE_AGE
• CSRF_COOKIE_DOMAIN
• CSRF_COOKIE_HTTPONLY
• CSRF_COOKIE_NAME
• CSRF_COOKIE_PATH
• CSRF_COOKIE_SAMESITE
• CSRF_COOKIE_SECURE
• CSRF_FAILURE_VIEW
• CSRF_HEADER_NAME
• CSRF_TRUSTED_ORIGINS
• CSRF_USE_SESSIONS

Pertanyaan Sering Ditanya¶