Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updates execution/security.md

Browse Source 
Auto commit by GitBook Editor
This commit is contained in:
apidesigner
2017-05-11 15:15:51 +00:00
parent 40c2592cc8
commit 48e5ef4138
1 changed files with 36 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
execution/security.md
View File

@@ -1,4 +1,5 @@
# API Authentication
#
API 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
@@ -14,7 +15,7 @@ RESTful web services SHOULD use session-based authentication, either by establis
RESTful API often use GET (read), POST (create), PUT (replace/update) and DELETE (to delete a record). Not all of these are valid choices for every single resource collection, user, or action. Make sure the incoming HTTP method is valid for the session token/API key and associated resource collection, action, and record.
# HTTP Status Codes
HTTP defines status code. While designing a REST API, DON'T just use 200 for success or 404 for error. Every error message needs to be customized as to NOT 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.
HTTP defines status code. While designing a REST API, DON'T just use 200 for success or 404 for error. Every error message needs to be customized as to NOT 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.
@@ -25,7 +26,7 @@ HTTP defines status code. While designing a REST API, DON'T just use 200 for suc
* 429 Too Many Requests - The error is used when there may be DOS attack detected or the request is rejected due to rate limiting
# Intput Validation
Everything you know about [input validation](https://www.owasp.org/index.php/Data_Validation) applies to RESTful web services, but add 10% because automated tools can easily fuzz your interfaces for hours on end at high velocity. Help the user input high quality data into your web services, such as ensuring a Zip code makes sense for the supplied address, or the date makes sense. If not, reject that input. Also make sure that the output encoding is very strong for your application. Some other specific forms of input validations need to be implemented:
Everything you know about [input validation](https://www.owasp.org/index.php/Data_Validation) applies to RESTful web services, but add 10% because automated tools can easily fuzz your interfaces for hours on end at high velocity. Help the user input high quality data into your web services, such as ensuring a Zip code makes sense for the supplied address, or the date makes sense. If not, reject that input. Also make sure that the output encoding is very strong for your application. Some other specific forms of input validations need to be implemented:
* 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.
@@ -37,13 +38,13 @@ Everything you know about [input validation](https://www.owasp.org/index.php/Dat
* 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
# 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 `// <![CDATA[` tags and HTML attributes that cause JavaScript to be evaluated. If you use standard data formats like JSON, you can use standard libraries which have been thoroughly checked by many professionals. However, DO NOT TRY TO DO THIS YOURSELF. Use a known library, or the auto-escaping features of your favorite template library. This needs to be done in the browser and on your server, if you allow users to submit data that is saved into a database.
# Restrict Testing Environment
THUMB Rule. No production data or any form of sensitive data to be used while testing the APIs in the testing environment.
# Storing Tokens at Client Side
# Storing Tokens at Client Side
There are two ways to save authentication information in the browser:
* Cookies
@@ -61,49 +62,52 @@ For resources exposed by RESTful web services, it's important to make sure any P
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_(Cross_Site_Scripting)_Prevention_Cheat_Sheet).
# 12 Insecure direct object references:
# 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 data contextual check needs to be done, server side, with each request.
# 13 Enable CORS for all APIs:
# Enable CORS for all APIs
When your API's resources receive requests from a domain other than the API's own 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
* Access-Control-Allow-Origin
# 14 Data in transit:
# Data in transit
Unless the public information is completely read-only, the use of TLS v1.2 should be MANDATED, particularly where 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.
# 15 Message Integrity:
# 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.
# 16 Weak SSL/TLS Ciphers Support:
# 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 crypto-analytical 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
# 17 Mixed Content:
* 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 crypto-analytical 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.
# 18 SSL certificate validity – client and server:
In order 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;
* Checking that the name of the site and the name reported in the certificate match.
# SSL Certificate Validity – client and server
In order for the communication to be set up, a number of checks on the certificates MUST be passed:
# 19 Certificate Requirements:
* Checking if the Certificate Authority (CA) is a known one (meaning one considered trusted);
* Checking that the certificate is currently valid;
* Checking that the name of the site and the name reported in the certificate match.
# Certificate Requirements
The following checklist NEEDS TO 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 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 USGAE 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.
# 20 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.
* 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 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 USGAE 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.