Reordering chapters

[elarlang]

Edit: used proposal with reasons: #2553 (comment)

---

To have some future step happening faster - we need to think about the order for the chapters.

Proposal for some kind of grouping and order:

V11 Business Logic
V5 Validation, Sanitization and Encoding

V2 Authentication
V3 Session Management
V4 Access Control

V50 Web Frontend Security
V13 API and Web Service
V52 Self-contained Tokens
V51 OAuth and OIDC

V6 Cryptography
V8 Data Protection
V9 Secure Communication

V10 Secure Coding Architecture and Implementation
V12 File and Resources - some sections are fitting to be next to input validation, some with next to configuration
V7 Security Logging and Error Handling
V14 Configuration

V53 WebRTC

[elarlang]

As we are going to reach to this task relatively soon, it would be nice to hear feedback on this as well.

[tghosth]

I would suggest:

---

• V2 Authentication
• V3 Session Management
• V4 Access Control

I think these make sense as an early and important concern, to me dealing with bad content comes afterwards.

• V52 Self-contained Tokens
• V51 OAuth and OIDC

These seem logically connected to the AuthN/AuthZ chapters and therefore it seems silly to split them.

• V11 Business Logic
• V5 Sanitization and Encoding

These are super important, especially as input validation is now in V11 so I think these make sense to come next.

• V50 Web Frontend Security
• V13 API and Web Service

Lots of important things ended up in V50 and I agree that V13 has strong links to V50.

• V6 Cryptography
• V9 Secure Communication
• V8 Data Protection

Makes sense for these to be together. I think V6 and V9 should be next to each other as they deal in similar concepts and then V8 is almost like the application of the theory defined in V6 and maybe in V9.

• V10 Secure Coding Architecture and Implementation
• V12 File and Resources - some sections are fitting to be next to input validation, some with next to configuration
• V7 Security Logging and Error Handling
• V14 Configuration
• V53 WebRTC

I am less opinionated about these ones.

---

[tghosth]

@jmanico @danielcuthbert what do you think?

[elarlang]

Few comments for reasoning behind initial proposal.

I think these make sense as an early and important concern, to me dealing with bad content comes afterwards.

Logic behind "Validation and output" first is - if you have an SQL injection, it does not matter too much how secure is your authentication. Whatever scanner, every script-kiddie etc start from collecting low-hanging fruits from that field. Syntax first, logic later.

These seem logically connected to the AuthN/AuthZ chapters and therefore it seems silly to split them.

Not that silly, as those are even more logically connected to API and services.

[tghosth]

I think these make sense as an early and important concern, to me dealing with bad content comes afterwards.

Logic behind "Validation and output" first is - if you have an SQL injection, it does not matter too much how secure is your authentication. Whatever scanner, every script-kiddie etc start from collecting low-hanging fruits from that field. Syntax first, logic later.

Depends whether the SQLi is in authentication functionality or not :) Authentication still feels to to me like a high risk area to tackle at the first stage.

These seem logically connected to the AuthN/AuthZ chapters and therefore it seems silly to split them.

Not that silly, as those are even more logically connected to API and services.

I am not sure they are more connected to API and services and I definitely don't think they are more connected than the rest of the authentication/session management/access control chapters which are also very connected to API and services.

[elarlang]

Full structure as it stands for BE:

• V2 Authentication
  • V1.2 Authentication Documentation
  • V2.1 Password Security
  • V2.2 General Authentication Security
  • V2.5 Authentication Factor Lifecycle and Recovery
  • V2.6 General Multi-factor authentication requirements
  • V2.7 Out-of-Band authentication mechanisms
  • V2.9 Cryptographic authentication mechanism
  • V2.11 Authentication with an Identity Provider
• V3 Session Management
  • V1.3 Session Management Documentation
  • V3.1 Fundamental Session Management Security
  • V3.3 Session Timeout
  • V3.6 Federated Re-authentication
  • V3.7 Defenses Against Session Abuse
  • V3.8 Session Termination
• V4 Access Control
  • V1.4 Access Control Documentation
  • V4.1 General Access Control Design
  • V4.2 Operation Level Access Control
  • V4.3 Other Access Control Considerations
• V5 Encoding and Sanitization
  • V5.2 Sanitization and Sandboxing
  • V5.3 Injection Prevention
  • V5.4 Memory, String, and Unmanaged Code
  • V5.5 Safe Deserialization
  • V5.6 Validation and Sanitization Architecture
• V6 Cryptography
  • V1.6 Cryptographic Inventory and Documentation
  • V6.2 Algorithms
  • V6.3 Random Values
  • V6.5 Encryption Algorithms
  • V6.6 Hashing and Hash-based Functions
  • V6.7 Public Key Cryptography
  • V6.8 In-Use Data Cryptography
  • V6.9 Post-Quantum Cryptography (PQC)
• V7 Security Logging and Error Handling
  • V1.7 Errors, Logging and Auditing Documentation
  • V7.1 General Logging
  • V7.2 Security Events
  • V7.3 Log Protection
  • V7.4 Error Handling
• V8 Data Protection
  • V1.8 Data Protection and Privacy Documentation
  • V8.1 General Data Protection
  • V8.2 Client-side Data Protection
  • V8.3 Sensitive Private Data
• V9 Secure Communication
  • V9.1 HTTPS Communication with External Facing Services
  • V9.2 General Service to Service Communication Security
  • V9.3 HTTPS Communication between Internal Services
  • V9.4 General TLS Security Guidance
• V10 Secure Coding Architecture and Implementation
  • V1.10 Secure Coding Documentation
  • V10.4 Defensive Coding
  • V10.6 Security Architecture and Dependencies
  • V10.7 Concurrency
• V11 Business Logic
  • V1.11 Business Logic Documentation
  • V11.1 Business Logic Security
  • V11.2 Anti-automation
  • V11.3 Input Validation
• V12 File Handling
  • V1.12 Secure File Upload Documentation
  • V12.1 File Upload and Content
  • V12.4 File Storage
  • V12.5 File Download
• V13 API and Web Service
  • V13.1 Generic Web Service Security
  • V13.4 GraphQL
  • V13.5 WebSocket
  • V13.6 HTTP Request Header Validation
  • V13.7 HTTP/2
• V14 Configuration
  • V1.14 Configuration Documentation
  • V14.1 Build and Deploy
  • V14.3 Unintended Information Leakage
  • V14.7 Back-end Communication Configuration
  • V14.8 Secret Management
• V50 Web Frontend Security
  • V1.50 Web Frontend Security Documentation
  • V50.1 Site Isolation Architecture
  • V50.2 Cookie Setup
  • V50.3 Browser Security Mechanism Headers
  • V50.4 Browser Origin Separation
  • V50.5 Cross-Site Script Inclusion
  • V50.6 Unintended Content Interpretation
  • V50.7 External Resource Integrity
  • V50.8 Other Browser Security Considerations
• V51 OAuth and OIDC
  • V51.1 Generic OAuth and OIDC security
  • V51.2 OAuth Client
  • V51.3 OAuth Resource Server
  • V51.4 OAuth Authorization Server
  • V51.5 OIDC Client
  • V51.6 OpenID Provider
  • V51.7 Consent Management
• V52 Self-contained Tokens
  • V52.1 Token source and integrity
  • V52.2 Token content
• V53 WebRTC
  • V53.1 TURN Server
  • V53.2 Media
  • V53.3 Signalling

[elarlang]

Proposal for in-chapter reorder

---

V3

• V1.3 Session Management Documentation
• V3.1 Fundamental Session Management Security
• V3.3 Session Timeout
• V3.8 Session Termination
• V3.7 Defenses Against Session Abuse
• V3.6 Federated Re-authentication

---

V5

• V5.6 Validation and Sanitization Architecture
• V5.3 Injection Prevention
• V5.2 Sanitization and Sandboxing
• V5.5 Safe Deserialization
• V5.4 Memory, String, and Unmanaged Code

---

V6 just based on the L1 requirements in sections

• V1.6 Cryptographic Inventory and Documentation
• V6.6 Hashing and Hash-based Functions
• V6.5 Encryption Algorithms
• V6.2 Algorithms
• V6.3 Random Values
• V6.7 Public Key Cryptography
• V6.8 In-Use Data Cryptography
• V6.9 Post-Quantum Cryptography (PQC)

Q: can the title for V6.2 be more specific?

---

V9

• V9.4 General TLS Security Guidance
• V9.2 General Service to Service Communication Security
• V9.1 HTTPS Communication with External Facing Services
• V9.3 HTTPS Communication between Internal Services

---

V10

• V1.10 Secure Coding Documentation
• V10.6 Security Architecture and Dependencies
• V10.4 Defensive Coding
• V10.7 Concurrency

---

V11

• V1.11 Business Logic Documentation
• V11.3 Input Validation
• V11.1 Business Logic Security
• V11.2 Anti-automation

---

V13

• V13.1 Generic Web Service Security
• V13.6 HTTP Request Header Validation
• V13.7 HTTP/2
• V13.4 GraphQL
• V13.5 WebSocket

---

V14

• V1.14 Configuration Documentation
• V14.7 Backend Communication Configuration
• V14.8 Secret Management
• V14.1 Build and Deploy
• V14.3 Unintended Information Leakage

---

V50

• V1.50 Web Frontend Security Documentation
• V50.6 Unintended Content Interpretation
• V50.2 Cookie Setup
• V50.4 Browser Origin Separation
• V50.3 Browser Security Mechanism Headers
• V50.7 External Resource Integrity
• V50.8 Other Browser Security Considerations

[tghosth]

Q: can the title for V6.2 be more specific?

Opened #2790. I think with that name, it should be the 2nd section in V6.

Otherwise, no objections to the order above.

[jmanico]

A few suggestions:

v5

V5.6 Validation and Sanitization Architecture
V5.2 Sanitization and Sandboxing
V5.3 Injection Prevention
V5.5 Safe Deserialization
V5.4 Memory, String, and Unmanaged Code

Note: Just putting sanitization before injection for the same reason we put validation first.

v6

V1.6 Cryptographic Inventory and Documentation
V6.2 Algorithms
V6.3 Random Values
V6.5 Encryption Algorithms
V6.6 Hashing and Hash-based Functions
V6.7 Public Key Cryptography
V6.8 In-Use Data Cryptography
V6.9 Post-Quantum Cryptography (PQC)

Note: Putting primitives up front in this list

v9

V9.4 General TLS Security Guidance
V9.1 HTTPS Communication with External Facing Services
V9.3 HTTPS Communication between Internal Services
V9.2 General Service to Service Communication Security

Note: Putting External (which is more important) up front

v14

V14.1 Configuration Documentation
V14.1 Build and Deploy
V14.8 Secret Management
V14.7 Backend Communication Configuration
V14.3 Unintended Information Leakage

Note: This re-ordering reflects a typical deployment pipeline a bit better

v50

V1.50 Web Frontend Security Documentation
V50.2 Cookie Setup
V50.3 Browser Security Mechanism Headers
V50.4 Browser Origin Separation
V50.7 External Resource Integrity
V50.6 Unintended Content Interpretation
V50.8 Other Browser Security Considerations

Notes: I think this better reflects order of importance of these modules

The rest of the suggestions above look great to me. :)

[elarlang]

So, just after those got changed :)

V6 and V9 I leave Josh to decide, for V5, V14 and V50 I obviously had different opinion and disagree with some of the proposed reasoning.

We will go through this list tomorrow to decide order for chapters, so if you have really good arguments to provide to have any changes, then we can redecide.

[jmanico]

I am sorry I was on vacation last week and am just catching up. I explained my reasoning in the "notes" section at the end of each section. These are just my opinions Elar, and I'm really ok if you take a different path.

[tghosth]

Josh and Elar had a discussion about chapter order and this is where we came down (for sections, a PR was already merged so let's open additional issues if necessary):

---

• V5 Sanitization and Encoding-
• V11 Business Logic
• V50 Web Frontend Security
• V13 API and Web Service
• V12 File Handling

---

• V2 Authentication
• V3 Session Management
• V4 Access Control
• V52 Self-contained Tokens
• V51 OAuth and OIDC

---

• V6 Cryptography
• V9 Secure Communication
• V14 Configuration
• V8 Data Protection

---

• V10 Secure Coding Architecture and Implementation
• V7 Security Logging and Error Handling
• V53 WebRTC

---

Rationale:

• V5/V11/V50/V13 before access control:
  • All services will be accepting input.
  • Vast majority but not all will have access control
  • Even those where access control is relevant, many controls may not be relevant if handled by SSO or IdP.
  • Removal of V1 would change numbering anyway
  • V5 should be first as it is more critical, V11 as it is strongly linked to that.
  • Many key controls for all apps in these sections
  • V13 has strong links to V50.
  • V12 is strongly connected to the concept of securely handling untrusted content.
• Next, V2, V3, V4, V52, V51.
  • These are still highly important chapters
  • Order of occurence is the same as V2, V3, V4, i.e. you authenticate, then you get issued a session and then your permissions get checked for the operation you want to do.
  • V52 Tokens is strongly connected to these chapters, as is V51 although V51 will be less widely applicable.
• V6, V9, V14, V8
  • Makes sense for these to be together.
  • V6 and V9 should be next to each other as they deal in similar concepts
  • V14 has a couple of key sections related to V6/V9 including backend communications and secret management.
  • V8 is almost like the application of the theory defined in V6 and maybe in V9 but overall less key.
• After that, everything else.

[elarlang]

ping @jmanico @randomstuff - the earliest I'll get your feedback the better it is. This decision is at the moment a blocker to move forward with #2456

[jmanico]

I think all of your suggestions here have been reasonable and I do not have a big charge over this. I think you should move forward with this as you see fit.

[elarlang]

PR #2803

Before	After
0x13-V5-Encoding-Sanitization.md	0x10-V1-Encoding-Sanitization.md
0x19-V11-BusLogic.md	0x11-V2-Business-Logic.md
0x50-V50-Web-Frontend-Security.md	0x12-V3-Web-Frontend-Security.md
0x21-V13-API.md	0x13-V4-API.md
0x20-V12-File-Handling.md	0x14-V5-File-Handling.md
0x11-V2-Authentication.md	0x15-V6-Authentication.md
0x12-V3-Session-management.md	0x16-V7-Session-Management.md
0x12-V4-Authorization.md	0x17-V8-Authorization.md
0x52-V52-Tokens.md	0x18-V9-Tokens.md
0x51-V51-OAuth2.md	0x19-V10-OAuth2-and-OIDC.md
0x14-V6-Cryptography.md	0x20-V11-Cryptography.md
0x17-V9-Communications.md	0x21-V12-Communications.md
0x22-V14-Config.md	0x22-V13-Config.md
0x16-V8-Data-Protection.md	0x23-V14-Data-Protection.md
0x18-V10-Coding.md	0x24-V15-Coding.md
0x15-V7-Error-Logging.md	0x25-V16-Logging-and-Error-Handling.md
0x53-V53-WebRTC.md	0x26-V17-WebRTC.md

[jmanico]

This is great work @elarlang - so much cleaner. Nice job! 🥳