{"Entry":{"collection":"guc","key":"scram_iterations","name":"scram_iterations","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Connections and Authentication / Authentication","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"15","status":"added","to":"16"}],"content_hash":"74fb893930fb9d70fae3c1b44a8ff6279e32bd238ab3a27b3bfba95ab1e5fe8e","context":"","default_changed_in":[],"default_history":[{"from":"16","to":"19","value":"4096"}],"derived_content_hash":"d7b3e665750c0c3465e08516a01f160b92cd326c27cab0d8025776f35c0e7b27","editorial":{"advice":{"olap":"Use the same count for analytical roles; workload class is not a reason to expose a distinct verifier count. Schedule credential rotation so long-lived service accounts do not retain the old count.","oltp":"Choose one count through a security and authentication-latency benchmark, enforce it in every password-management session, and rotate all role passwords so stored verifiers converge. Load-test reconnect storms and failover before raising it.","small":"Keep the upstream count unless testing justifies a change. A smaller server should reduce connection churn with pooling, but must still keep all generated verifiers at one consistent count."},"mechanism":["scram_iterations is embedded in every newly generated SCRAM-SHA-256 verifier. Raising it increases offline-guessing cost but also increases legitimate password-setting and authentication work; existing verifiers keep the iteration count with which they were created until their passwords are reset.","It is a USER-context setting, so the session that executes CREATE ROLE or ALTER ROLE determines the count written into the new verifier. Role, database, or application-specific overrides can therefore create a mixture of counts even when postgresql.conf has one value.","PostgreSQL warns that when a role's stored count differs from the configured server value, an unauthenticated observer can distinguish response behavior and infer that the role exists. A count change therefore requires uniform session policy and rotation of all SCRAM verifiers, not only a GUC edit."],"pitfalls":["Changing the GUC without resetting existing passwords; their verifiers retain the old count.","Allowing role or database session defaults to generate verifiers with counts different from postgresql.conf, creating a role-existence side channel.","Raising the count without load-testing authentication storms, failover, pooler reconnects, and password rotation jobs.","Assuming a higher count repairs weak passwords or compensates for leaked verifier material."],"references":[{"title":"PostgreSQL 19 Beta 4: scram_iterations","url":"https://www.postgresql.org/docs/19/runtime-config-connection.html#GUC-SCRAM-ITERATIONS"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["password_encryption","md5_password_warnings","authentication_timeout","oauth_validator_libraries","krb_server_keyfile"],"summary":"scram_iterations is the PostgreSQL setting that defines the iteration count for SCRAM secret generation."},"enumvals":[],"first_version":"16","group":"Connections and Authentication","group_slug":"connection","imported_at":"2026-09-27T17:57:31.92135+08:00","intro_commit":{"authored_at":"2023-03-27T09:46:29+02:00","discussion":["https://postgr.es/m/F72E7BC7-189F-4B17-BF47-9735EB72C364@yesql.se"],"hash":"b577743000cd0974052af3a71770a23760423102","subject":"Make SCRAM iteration count configurable","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=b577743000cd0974052af3a71770a23760423102"},"key":"scram_iterations","last_version":"20","max_val":"","min_val":"","name":"scram_iterations","position":345,"present_in":["16","17","18","19","20"],"repair_provenance":{"original_source_revision":"english-manuals:9247ef2e985d9470767d84f96ee480028094dfc72dc6b9cd3bea7b1d890a9a63","receipt_sha256":"c6bf35c7a4bd4adcb5bfdebd009bd70be47c090f87157aa684f4d00b1e047d48","repair":"wiki-repair-20261023"},"short_desc":"The number of computational iterations to be performed when encrypting a password using SCRAM-SHA-256.","short_desc_zh":"","source_rev":"wiki-repair-20261023:f18e03bc6d0582d9581d9baa0ae2c311f11e6830cfa7e6337eeb63f1958d7827","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"scram_iterations","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"scram_iterations","SourceRevision":"wiki-repair-20261023:f18e03bc6d0582d9581d9baa0ae2c311f11e6830cfa7e6337eeb63f1958d7827","Facts":{"boot_val":"4096","category":"Connections and Authentication / Authentication","context":"user","description":"The number of computational iterations to be performed when encrypting a password using SCRAM-SHA-256. The default is 4096. A higher number of iterations provides additional protection against brute-force attacks on stored passwords, but makes authentication slower. Changing the value has no effect on existing passwords encrypted with SCRAM-SHA-256 as the iteration count is fixed at the time of encryption. In order to make use of a changed value, a new password must be set. Note If a role password was created with a different iteration count than the value of scram_iterations specified in the postgresql.conf file or on the server command line, an unauthenticated user can discern the existence of the role by observing discrepancies in the server's responses to connection attempts. If you find this concerning, ensure that all role passwords are created with scram_iterations set to the value specified in the postgresql.conf file or on the server command line.","description_zh":"使用 SCRAM-SHA-256 加密密码时执行的计算迭代次数。默认值为 4096。更高的迭代次数可以对存储密码遭受暴力破解攻击提供额外保护，但也会使认证变慢。更改此值不会影响现有的 SCRAM-SHA-256 加密密码，因为迭代次数在加密时就已经固定。要利用更改后的值，必须设置新密码。 注意 如果某个角色密码创建时使用的迭代次数，与 postgresql.conf 文件或服务器命令行上指定的 scram_iterations 值不同，未认证用户便可通过观察服务器对连接尝试的响应差异，辨别该角色是否存在。如果你担心这一点，请确保创建所有角色密码时，scram_iterations 都被设为 postgresql.conf 文件或服务器命令行中指定的值。","description_zh_html":"\u003cp\u003e\n        使用 SCRAM-SHA-256 加密密码时执行的计算迭代次数。默认值为\n        \u003ccode class=\"literal\"\u003e4096\u003c/code\u003e。更高的迭代次数可以对存储密码遭受暴力破解攻击提供额外保护，但也会使认证变慢。更改此值不会影响现有的 SCRAM-SHA-256 加密密码，因为迭代次数在加密时就已经固定。要利用更改后的值，必须设置新密码。\n       \u003c/p\u003e\u003cdiv class=\"note\"\u003e\u003ch3 class=\"title\"\u003e注意\u003c/h3\u003e\u003cp\u003e\n         如果某个角色密码创建时使用的迭代次数，与 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e\n         文件或服务器命令行上指定的 \u003ccode class=\"literal\"\u003escram_iterations\u003c/code\u003e 值不同，未认证用户便可通过观察服务器对连接尝试的响应差异，辨别该角色是否存在。如果你担心这一点，请确保创建所有角色密码时，\u003ccode class=\"literal\"\u003escram_iterations\u003c/code\u003e\n         都被设为 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e 文件或服务器命令行中指定的值。\n        \u003c/p\u003e\u003c/div\u003e","doc":{"anchor":"GUC-SCRAM-ITERATIONS","file":"runtime-config-connection.html","lang":"en","sha256":"567ba928f3e4c4783f548dc8a54f1e748f02bbe163924605f2132eb5b0da440d","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":"2147483647","metadata_version":"18","min_val":"1","name":"scram_iterations","short_desc":"Sets the iteration count for SCRAM secret generation.","source":"pg-settings-source-snapshot","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-connection.html","sha256":"f4e5e4debc927cfa154bbdd71f3bf2eda8130ac3acace1109fe7d45ef2a3456b"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":null,"vartype":"integer","zh_from":"same-version-pgdoc"},"ManualEvidence":{"doc":{"anchor":"GUC-SCRAM-ITERATIONS","file":"runtime-config-connection.html","lang":"en","sha256":"567ba928f3e4c4783f548dc8a54f1e748f02bbe163924605f2132eb5b0da440d","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"scram_iterations","SourceDatabase":"center","Version":"18","Locale":"en","Title":"scram_iterations","Summary":"The number of computational iterations to be performed when encrypting a password using SCRAM-SHA-256. The default is 4096. A higher number of iterations provides additional protection against brute-force attacks on stored passwords, but makes authentication slower. Changing the value has no effect on existing passwords encrypted with SCRAM-SHA-256 as the iteration count is fixed at the time of encryption. In order to make use of a changed value, a new password must be set. Note If a role password was created with a different iteration count than the value of scram_iterations specified in the postgresql.conf file or on the server command line, an unauthenticated user can discern the existence of the role by observing discrepancies in the server's responses to connection attempts. If you find this concerning, ensure that all role passwords are created with scram_iterations set to the value specified in the postgresql.conf file or on the server command line.","BodyHTML":"\u003cp\u003eThe number of computational iterations to be performed when encrypting a password using SCRAM-SHA-256. The default is 4096. A higher number of iterations provides additional protection against brute-force attacks on stored passwords, but makes authentication slower. Changing the value has no effect on existing passwords encrypted with SCRAM-SHA-256 as the iteration count is fixed at the time of encryption. In order to make use of a changed value, a new password must be set. Note If a role password was created with a different iteration count than the value of scram_iterations specified in the postgresql.conf file or on the server command line, an unauthenticated user can discern the existence of the role by observing discrepancies in the server\u0026#39;s responses to connection attempts. If you find this concerning, ensure that all role passwords are created with scram_iterations set to the value specified in the postgresql.conf file or on the server command line.\u003c/p\u003e","SourceRevision":"wiki-repair-20261023:f18e03bc6d0582d9581d9baa0ae2c311f11e6830cfa7e6337eeb63f1958d7827","ContentHash":"46273f867e40727201f426f6affdf31b248ba4e0c6879c5106e2fe8f80073323","Payload":{"description":"The number of computational iterations to be performed when encrypting a password using SCRAM-SHA-256. The default is 4096. A higher number of iterations provides additional protection against brute-force attacks on stored passwords, but makes authentication slower. Changing the value has no effect on existing passwords encrypted with SCRAM-SHA-256 as the iteration count is fixed at the time of encryption. In order to make use of a changed value, a new password must be set. Note If a role password was created with a different iteration count than the value of scram_iterations specified in the postgresql.conf file or on the server command line, an unauthenticated user can discern the existence of the role by observing discrepancies in the server's responses to connection attempts. If you find this concerning, ensure that all role passwords are created with scram_iterations set to the value specified in the postgresql.conf file or on the server command line."}},"RequestedLocale":"en","Fallback":false,"Versions":["16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}