mirror of
https://github.com/adidas/api-guidelines.git
synced 2025-10-25 15:19:19 +00:00
Update security.md
This commit is contained in:
ianschechtman
GitHub
@@ -1,20 +1,20 @@
|
||||
# Security
|
||||
|
||||
Every registered API MUST be assigned a unique Client ID and a Client Secret as a part of an HTTP header. The Client Secret MUST NOT be shared. DO NOT solely rely on a Client ID for authentication.
|
||||
Every registered API **MUST** be assigned a unique Client ID and a Client Secret as a part of an HTTP header. The Client Secret **MUST NOT** be shared. **DO NOT** solely rely on a Client ID for authentication.
|
||||
|
||||
## Access Control
|
||||
|
||||
Not every user has a right to every web service. This is vital, as you don't want administrative web services to be misused. The API key SHOULD be sent along as a cookie, body parameter, or HTTP message header to ensure that privileged collections or actions are properly protected from unauthorized use. Every API MUST BE authenticated before it can be used.
|
||||
Not every user has a right to every web service. This is vital, as you don't want administrative web services to be misused. The API key **SHOULD** be sent along as a cookie, body parameter, or HTTP message header to ensure that privileged collections or actions are properly protected from unauthorized use. Every API **MUST BE** authenticated before it can be used.
|
||||
|
||||
## Masking HTTP Headers
|
||||
|
||||
Server versioning information or any other sensitive information from the HTTP headers SHOULD BE removed/masked according to industry best practices. This prevents any form of targeted attacks since the vulnerabilities are mostly specific to the vendors.
|
||||
Server versioning information or any other sensitive information from the HTTP headers **SHOULD BE** removed/masked according to industry best practices. This prevents any form of targeted attacks since the vulnerabilities are mostly specific to the vendors.
|
||||
|
||||
## Use Security HTTP Headers
|
||||
Modern browsers support many HTTP headers that can improve web application security to protect against clickjacking, cross-site scripting, and other common attacks.
|
||||
Your API SHOULD use security HTTP headers to improve the level of protection.
|
||||
See the [list of OWASP Secure Headers](https://owasp.org/www-project-secure-headers/) to form the combination of headers
|
||||
Ideally you SHOULD inlcude HTTP Security Headers at least in these areas unless there is an incompatibility with some functional requirement:
|
||||
Your API **SHOULD** use security HTTP headers to improve the level of protection.
|
||||
See the [list of OWASP Secure Headers](https://owasp.org/www-project-secure-headers/) to form the combination of headers.
|
||||
Ideally you **SHOULD** inlcude HTTP Security Headers at least in these areas unless there is an incompatibility with some functional requirement:
|
||||
|
||||
- HTTP Strict Transport Security
|
||||
- Content-Security-Policy
|
||||
@@ -30,7 +30,7 @@ Ideally you SHOULD inlcude HTTP Security Headers at least in these areas unless
|
||||
|
||||
## Session Management
|
||||
|
||||
RESTful web services SHOULD use session-based authentication, either by establishing a session token via a POST or by using an API key \(Client ID and a Client Secret\) as a POST body argument or as a cookie. Usernames, passwords, session tokens, API keys, and sensitive information MUST NOT appear in the URL, as this can be captured in web server logs, which makes them intrinsically valuable.
|
||||
RESTful web services **SHOULD** use session-based authentication, either by establishing a session token via a POST or by using an API key \(Client ID and a Client Secret\) as a POST body argument or as a cookie. Usernames, passwords, session tokens, API keys, and sensitive information **MUST NOT** appear in the URL, as this can be captured in web server logs, which makes them intrinsically valuable.
|
||||
|
||||
## Protect HTTP Methods
|
||||
|
||||
@@ -38,7 +38,7 @@ RESTful API often use GET \(read\), POST \(create\), PUT \(replace/update\) and
|
||||
|
||||
## HTTP Status Codes
|
||||
|
||||
While designing a REST API, DON'T just use 200 for success or 404 for error. Every error message needs to be customized as NOT to reveal any unnecessary information. Here are some guidelines to consider for each REST API status return code. Proper error handle may help to validate the incoming requests and better identify the potential security risks.
|
||||
While designing a REST API, **DO NOT** just use 200 for success or 404 for error. Every error message needs to be customized as NOT to reveal any unnecessary information. Here are some guidelines to consider for each REST API status return code. Proper error handle may help to validate the incoming requests and better identify the potential security risks.
|
||||
|
||||
* 200 OK - Response to a successful REST API action.
|
||||
* 400 Bad Request - The request is malformed, such as message body format error.
|
||||
@@ -54,17 +54,17 @@ Everything you know about [input validation](https://www.owasp.org/index.php/Dat
|
||||
|
||||
* Secure parsing: Use a secure parser for parsing the incoming messages. If you are using XML, make sure to use a parser that is NOT VULNERABLE to XXE and similar attacks.
|
||||
* Strong typing: It's difficult to perform most attacks if the only allowed values are true or false, or a number, or one of a small number of acceptable values. Strongly type incoming data as quickly as possible.
|
||||
* Validate incoming content-types: When POSTing or PUTting new data, the client will specify the Content-Type \(e.g. application/xml or application/json\) of the incoming data. The server SHOULD NEVER assume the Content-Type; it SHOULD ALWAYS check that the Content-Type header and the content are the same types. A lack of Content-Type header or an unexpected Content-Type header SHOULD result in the server rejecting the content with a 406 Not Acceptable response.
|
||||
* Validate response types: It is common for REST services to allow multiple response types \(e.g. application/xml or application/json, and the client specifies the preferred order of response types by the Accept header in the request. DO NOT simply copy the Accept header to the Content-type header of the response. Reject the request \(ideally with a 406 Not Acceptable response\) if the Accept header does not specifically contain one of the allowable types. Because there are many MIME types for the typical response types, it's important to document for clients specifically which MIME types should be used.
|
||||
* XML input validation: XML-based services MUST ensure that they are protected against common XML-based attacks by using secure XML-parsing. This typically means protecting against XML External Entity attacks, XML-signature wrapping etc.
|
||||
* Validate incoming content-types: When POSTing or PUTting new data, the client will specify the Content-Type \(e.g. application/xml or application/json\) of the incoming data. The server **SHOULD NEVER** assume the Content-Type; it **SHOULD ALWAYS** check that the Content-Type header and the content are the same types. A lack of Content-Type header or an unexpected Content-Type header **SHOULD** result in the server rejecting the content with a 406 Not Acceptable response.
|
||||
* Validate response types: It is common for REST services to allow multiple response types \(e.g. application/xml or application/json, and the client specifies the preferred order of response types by the Accept header in the request. **DO NOT** simply copy the Accept header to the Content-type header of the response. Reject the request \(ideally with a 406 Not Acceptable response\) if the Accept header does not specifically contain one of the allowable types. Because there are many MIME types for the typical response types, it's important to document for clients specifically which MIME types should be used.
|
||||
* XML input validation: XML-based services **MUST** ensure that they are protected against common XML-based attacks by using secure XML-parsing. This typically means protecting against XML External Entity attacks, XML-signature wrapping etc.
|
||||
|
||||
## Escape Content
|
||||
|
||||
This means removing any executable code that would cause the browser to do something you don’t want it to. Typically this means removing `// < for more information on how to implement CSRF-protection.
|
||||
|
||||
CSRF is easily achieved even using random tokens if any XSS exists within your application, so PLEASE MAKE SURE you understand [how to prevent XSS](https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet).
|
||||
CSRF is easily achieved even when using random tokens if any XSS exists within your application, so **PLEASE MAKE SURE** you understand [how to prevent XSS](https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet).
|
||||
|
||||
## Insecure direct object references
|
||||
|
||||
A URL or even a POSTed form should NEVER contain an access control "key" or similar that provides automatic verification. A contextual data check needs to be done, server side, with each request.
|
||||
A URL or even a POSTed form **SHOULD NEVER** contain an access control "key" or similar that provides automatic verification. A contextual data check needs to be done, server side, with each request.
|
||||
|
||||
## Enable CORS for all APIs
|
||||
|
||||
When your API's resources receive requests from a domain other than the API's domain, you MUST enable cross-origin resource sharing \(CORS\) for selected methods on the resource. This amounts to having your API respond to the OPTIONS preflight request with at least the following CORS-required response headers:
|
||||
When your API's resources receive requests from a domain other than the API's domain, you **MUST** enable cross-origin resource sharing \(CORS\) for selected methods on the resource. This amounts to having your API respond to the OPTIONS preflight request with at least the following CORS-required response headers:
|
||||
|
||||
* Access-Control-Allow-Methods
|
||||
* Access-Control-Allow-Headers
|
||||
@@ -98,32 +98,32 @@ When your API's resources receive requests from a domain other than the API's do
|
||||
|
||||
## Data in transit
|
||||
|
||||
Unless the public information is entirely read-only, the use of TLS v1.2 should be MANDATED, especially when credentials, updates, deletions, and any value transactions are performed. The overhead of TLS is negligible on modern hardware, with a minor latency increase that is more than compensated by safety for the end user.
|
||||
Unless the public information is entirely read-only, the use of TLS v1.2 should be **MANDATED**, especially when credentials, updates, deletions, and any value transactions are performed. The overhead of TLS is negligible on modern hardware, with a minor latency increase that is more than compensated by safety for the end user.
|
||||
|
||||
## Message Integrity
|
||||
|
||||
In addition to HTTPS/TLS, JSON Web Token \(JWT\) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. JWT can not only be used to ensure the message integrity but also authentication of both message sender/receiver. The JWT includes the digital signature hash value of the message body to ensure the message integrity during the transmission.
|
||||
In addition to HTTPS/TLS, JSON Web Token \(JWT\) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. JWT can be used not only to ensure the message integrity but also authentication of both message sender/receiver. The JWT includes the digital signature hash value of the message body to ensure message integrity during the transmission.
|
||||
|
||||
## Weak SSL/TLS Ciphers Support:
|
||||
|
||||
The encryption ciphers supported by the server may allow an attacker to eavesdrop on the connection. Verify the following guidelines:
|
||||
|
||||
* When serving up content to your users, ONLY strong ciphers are enabled \(128 bits and above\).
|
||||
* When connecting to other remote systems ensure that your client DOES NOT connect using a weak cipher if the server supports it.
|
||||
* Renegotiation MUST be properly configured \(e.g. Insecure Renegotiation MUST be disabled, due to MiTM attacks and Client-initiated Renegotiation MUST be disabled, due to Denial of Service vulnerability\).
|
||||
* MD5 MUST NOT be used, due to known collision attacks.
|
||||
* RC4 MUST NOT be used, due to cryptoanalytical attacks
|
||||
* Server SHOULD be protected from BEAST Attack
|
||||
* Server SHOULD be protected from CRIME attack, TLS compression MUST be disabled
|
||||
* Server SHOULD support Forward Secrecy
|
||||
* When serving up content to your users, **ONLY** strong ciphers are enabled \(128 bits and above\).
|
||||
* When connecting to other remote systems ensure that your client **DOES NOT** connect using a weak cipher if the server supports it.
|
||||
* Renegotiation **MUST** be properly configured \(e.g. Insecure Renegotiation **MUST** be disabled, due to Man in the Middle (MiTM) attacks and Client-initiated Renegotiation **MUST** be disabled, due to Denial of Service vulnerability\).
|
||||
* MD5 **MUST NOT** be used, due to known collision attacks.
|
||||
* RC4 **MUST NOT** be used, due to cryptoanalytical attacks
|
||||
* Server **SHOULD** be protected from BEAST Attack
|
||||
* Server **SHOULD** be protected from CRIME attack, TLS compression **MUST** be disabled
|
||||
* Server **SHOULD** support Forward Secrecy
|
||||
|
||||
## Mixed Content
|
||||
|
||||
When serving up content to your users over SSL, it’s important that you DO NOT include content served over HTTP such as Images, JavaScript, Flash, or CSS. By mixing HTTP content with HTTPS content, you expose your users to man in the middle attacks and eliminate the security benefits that SSL/TLS provides.
|
||||
When serving up content to your users over SSL, it’s important that you **DO NOT** include content served over HTTP such as Images, JavaScript, Flash, or CSS. By mixing HTTP content with HTTPS content, you expose your users to Man-in-the-Middle attacks and eliminate the security benefits that SSL/TLS provides.
|
||||
|
||||
## SSL Certificate Validity – client and server
|
||||
|
||||
For the communication to be set up, a number of checks on the certificates MUST be passed:
|
||||
For the communication to be set up, a number of checks on the certificates **MUST** be passed:
|
||||
|
||||
* Checking if the Certificate Authority \(CA\) is a known one \(meaning one considered trusted\);
|
||||
* Checking that the certificate is currently valid;
|
||||
@@ -131,15 +131,15 @@ For the communication to be set up, a number of checks on the certificates MUST
|
||||
|
||||
## Certificate Requirements
|
||||
|
||||
The following checklist NEEDS TO BE followed while using an SSL certificate:
|
||||
The following checklist **MUST** be followed while using an SSL certificate:
|
||||
|
||||
* X.509 certificates key length MUST be strong \(e.g. if RSA or DSA is used the key MUST be at least 1024 bits\).
|
||||
* X.509 certificates MUST be signed only with secure hashing algorithms \(e.g. not signed using the MD5 hash, due to known collision attacks on this hash\).
|
||||
* Fully Qualified Domain Name \(FQDN\) certificates is a MANDATE. This is a certificate that has been issued with a name registered with an entity that manages a top-level domain \(TLD\). The differentiating characteristic about an FQDN is that it is unique. There is one controller and that controller determines who can have any name under that root.
|
||||
* NO USAGE of Wildcard SSL Certificate.
|
||||
* SHA-1 \(or MD5\) certificates SHOULD NOT BE used. The problem isn't the security of the server's real certificate; it's the client policy that allows the client to trust low-security certificates.
|
||||
* X.509 certificates key length **MUST** be strong \(e.g. if RSA or DSA is used the key MUST be at least 1024 bits\).
|
||||
* X.509 certificates **MUST** be signed only with secure hashing algorithms \(e.g. not signed using the MD5 hash, due to known collision attacks on this hash\).
|
||||
* Fully Qualified Domain Name \(FQDN\) certificates is a **MANDATE**. This is a certificate that has been issued with a name registered with an entity that manages a top-level domain \(TLD\). The differentiating characteristic about an FQDN is that it is unique. There is one controller and that controller determines who can have any name under that root.
|
||||
* **NO USAGE** of Wildcard SSL Certificate.
|
||||
* SHA-1 \(or MD5\) certificates **SHOULD NOT BE** used. The problem isn't the security of the server's real certificate; it's the client policy that allows the client to trust low-security certificates.
|
||||
|
||||
## Penetration Testing
|
||||
|
||||
An exhaustive penetration testing needs to be performed against all the developed APIs exposed to the public internet and within adidas internal network. For detailed understanding of the process, please contact the adidas Global IT Security Team.
|
||||
An exhaustive penetration testing **MUST** be performed against all the developed APIs exposed to the public internet and within adidas internal network. For detailed understanding of the process, please contact the adidas Global IT Security Team.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user