Update PasswordSpecificsData documentataion.

Review URL: https://codereview.chromium.org/1184453003

Cr-Commit-Position: refs/heads/master@{#334578}

1 files changed, 73 insertions, 2 deletions

diff --git a/sync/protocol/password_specifics.proto b/sync/protocol/password_specifics.proto
index 1baf39d..7f27072 100644
--- a/sync/protocol/password_specifics.proto
+++ b/sync/protocol/password_specifics.proto
@@ -17,25 +17,96 @@ package sync_pb;
 import "encryption.proto";
 
 // These are the properties that get serialized into the |encrypted| field of
-// PasswordSpecifics. They correspond to fields in autofill::PasswordForm. See
-// components/autofill/core/common/password_form.h for more details.
+// PasswordSpecifics. They correspond to fields in autofill::PasswordForm.
+//
+// Sync unique tag is calculated as
+// EscapePath(origin) + "|" +
+// EscapePath(username_element) + "|" +
+// EscapePath(username_value) + "|" +
+// EscapePath(password_element) + "|" +
+// EscapePath(signon_realm)
+// where '+' is the string concatenation operation. EscapePath escapes a partial
+// or complete file/pathname. This includes non-printable, non-7bit, and
+// (including space) the following characters ' "#%:<>?[\]^`{|}'. The space
+// character is encoded as '%20'.
+
+// All the strings are encoded with UTF-8. URLs are encoded in Punycode.
 message PasswordSpecificsData {
+  // SCHEME_HTML(0), the credential represents either a parsed HTML form, or an
+  // android credential or a password saved through Credential Manager API
+  // (https://w3c.github.io/webappsec/specs/credentialmanagement/).
+  // SCHEME_BASIC(1), basic access http authentication.
+  // SCHEME_DIGEST(2), digest access authentication.
+  // SCHEME_OTHER(3), another access authentication.
   optional int32 scheme = 1;
+
+  // For parsed web forms and normal passwords saved through Credential Manager
+  // API: url-scheme://url-host[:url-port]/
+  // For Android apps (local + federated):
+  //     "android://<hash of cert>@<package name>"
+  // where the hash is base64 encoded SHA512 of the app's public certificate.
+  // For federated credentials:
+  //     "federation://" + origin_host + "/" + federation_host
+  // For proxy auth: proxy-host/auth-realm
+  // For HTTP auth: url-scheme://url-host[:url-port]/auth-realm
   optional string signon_realm = 2;
+
+  // For parsed web forms and Credential Manager API:
+  //     url-scheme://url-host[:url-port]/path
+  // For Android: <empty>.
+  // For proxy/HTTP auth: url-scheme://url-host[:url-port]/path
   optional string origin = 3;
+
+  // Only for web-parsed forms - the action target of the form:
+  //     url-scheme://url-host[:url-port]/path
   optional string action = 4;
+
+  // Only for web-parsed forms - the name of the element containing username.
   optional string username_element = 5;
+
+  // For all: the username.
+  // For blacklisted forms: <empty>.
   optional string username_value = 6;
+
+  // Only for web-parsed forms - the name of the element containing password.
   optional string password_element = 7;
+
+  // For all: the password.
+  // For federated logins and blacklisted forms: <empty>
   optional string password_value = 8;
+
+  // True if the credential was saved for a HTTPS session with a valid SSL cert.
+  // Ignored for Android apps.
+  // Note: likely getting deprecated: http://crbug.com/413020
   optional bool ssl_valid = 9;
+
+  // True for the last credential used for logging in on a given site.
   optional bool preferred = 10;
+
+  // Time when the credential was created. Amount of microseconds since 1601.
   optional int64 date_created = 11;
+
+  // True, if user chose permanently not to save the credentials for the form.
   optional bool blacklisted = 12;
+
+  // TYPE_MANUAL(0), user manually filled the username and the password.
+  // TYPE_GENERATED(1), the credential was auto generated.
   optional int32 type = 13;
+
+  // Number of times this login was used for logging in. Chrome uses this field
+  // to distinguish log-in and sign-up forms.
   optional int32 times_used = 14;
+
+  // A human readable name of the account holder. Set by CredentialManager API
+  // and Android.
   optional string display_name = 15;
+
+  // A URL of the avatar for the credential. Set by CredentialManager API and
+  // Android.
   optional string avatar_url = 16;
+
+  // A URL of the IdP used to verify the credential. Set by Credential Manager
+  // API and Android.
   optional string federation_url = 17;
 }