Back to all reviewers

Document security behavior references

istio/istio
Based on 1 comments
Other

When implementing security-related functionality such as certificate parsing, cryptographic validation, or authentication mechanisms, always document the expected behavior and include references to official documentation that explains the underlying security decisions.

Security Other

Reviewer Prompt

When implementing security-related functionality such as certificate parsing, cryptographic validation, or authentication mechanisms, always document the expected behavior and include references to official documentation that explains the underlying security decisions.

This practice is crucial for several reasons:

  • It helps future maintainers understand why certain security behaviors exist
  • It provides authoritative backing for security decisions during audits
  • It ensures that security implementations align with established standards and best practices
  • It makes debugging easier when security-related failures occur

Example:

// This cert has a negative serial number.
// Go should fail to parse it, but we should handle this gracefully
// Reference: https://golang.org/pkg/crypto/x509/#Certificate
// Go's x509 package rejects certificates with negative serial numbers
// as per RFC 5280 requirements

Always include links to relevant RFCs, official language documentation, or security standards when implementing security features. This documentation becomes invaluable during security reviews and helps establish the rationale behind security-related code decisions.

1
Comments Analyzed
Other
Primary Language
Security
Category

Source Discussions