• File Bug
• View source
• Edit this page

AIP-147

Sensitive fields

Sometimes APIs need to collect sensitive information such as private encryptionkeys meant to bestored by the underlying service but not intended to beread after writing due to the sensitive nature of the data. For this type ofdata, extra consideration is required for the representation of the sensitivedata in API requests and responses.

Guidance

If the sensitive information isrequired for the resource as a whole toexist, the datashould be accepted as aninput-only fieldwith no corresponding output field. Because the sensitive data must be presentfor the resource to exist, users of the API may assume that existence of theresource implies storage of the sensitive data. For example:

messageSelfManagedKeypair{stringname=1[(google.api.field_behavior)=IDENTIFIER];// The public key data in PEM-encoded form.bytespublic_key=2;// The private key data in PEM-encoded form.bytesprivate_key=3[(google.api.field_behavior)=INPUT_ONLY];}

If the sensitive information isoptional within the containing resource, anoutput-only boolean field with a postfix of_setshould be used toindicate whether or not the sensitive information is present. For example:

messageIntegration{stringname=1[(google.api.field_behavior)=IDENTIFIER];stringuri=2;// A secret to be passed in the `Authorization` header of the webhook.stringshared_secret=3[(google.api.field_behavior)=INPUT_ONLY];// True if a `shared_secret` has been set for this Integration.boolshared_secret_set=4[(google.api.field_behavior)=OUTPUT_ONLY];}

If it is important to be able to identify the sensitive information withoutallowing it to be read back entirely, a field of the same type with anobfuscated_ prefixmay be used instead of the boolean_set field toprovide contextual information about the sensitive information. The specificnature of the obfuscation is outside the scope of this AIP. For example:

messageAccountRecoverySettings{// An email to use for account recovery.stringemail=1[(google.api.field_behavior)=INPUT_ONLY];// An obfuscated representation of the recovery email. For example,// `ada@example.com` might be represented as `a**@e*****e.com`.stringobfuscated_email=2[(google.api.field_behavior)=OUTPUT_ONLY];}