From db09acea96b4015fcd6df9417f5c18254ffd033e Mon Sep 17 00:00:00 2001 From: apidesigner Date: Thu, 11 May 2017 15:03:40 +0000 Subject: [PATCH] Updates execution/security.md Auto commit by GitBook Editor --- execution/security.md | 64 ++++++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 28 deletions(-) diff --git a/execution/security.md b/execution/security.md index 525354d..167fb2b 100644 --- a/execution/security.md +++ b/execution/security.md @@ -1,46 +1,54 @@ -# 1 API Authentication: -Every registered RESTful 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. +# 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. -# 2 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 or body parameter to ensure that privileged collections or actions are properly protected from unauthorized use. Every API NEEDS TO BE authenticated before it can be used. +# 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 TO BE authenticated before it can be used. -# 3 Masking HTTP Headers: +# 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. -# 4 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 + 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. +# 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. -# 5 Protect HTTP methods: +# Protect HTTP Methods 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. -# 6 HTTP Return Code: +# 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. -* 200 OK - Response to a successful REST API action. The HTTP method can be GET, POST, PUT, PATCH or DELETE. -* 400 Bad Request - The request is malformed, such as message body format error. -* 401 Unauthorized - Wrong or no authentication ID/password provided. -* 403 Forbidden - It's used when the authentication succeeded but authenticated user doesn't have permission to the request resource -* 404 Not Found - When a non-existent resource is requested -* 405 Method Not Allowed - The error checking for unexpected HTTP method. For example, the RestAPI is expecting HTTP GET, but HTTP PUT is used. -* 429 Too Many Requests - The error is used when there may be DOS attack detected or the request is rejected due to rate limiting -# 7 Input Validation: -Everything you know about input validation (refer: 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. -* 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 type. 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. +* 200 OK - Response to a successful REST API action. +* 400 Bad Request - The request is malformed, such as message body format error. +* 401 Unauthorized - Wrong or no authentication ID/password provided. +* 403 Forbidden - It's used when the authentication succeeded but authenticated user doesn't have permission to the request resource +* 404 Not Found - When a non-existent resource is requested +* 405 Method Not Allowed - The error checking for unexpected HTTP method. For example, the RestAPI is expecting HTTP GET, but HTTP PUT is used. +* 429 Too Many Requests - The error is used when there may be DOS attack detected or the request is rejected due to rate limiting -# 8 Escape Content: +# 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: + +* 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 type. 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 // <![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. -# 9 Restrict Testing Environment: +# 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. -# 10 Storing Tokens at Client Side: +# Storing Tokens at Client Side: There are two ways to save authentication information in the browser: -* Cookies -* HTML5 Web Storage + +* Cookies +* HTML5 Web Storage + In each case, you have to trust that browsers are implemented correctly, and that Website A can't somehow access the authentication information for Website B. In that sense, both storage mechanisms are equally secure. Problems can arise in terms of how you use them though. - If you use cookies: The browser will automatically send the authentication information with every request to the API. This can be convenient so long as you know it's happening. Prevention against CSRF is a must while using this technique. It is also strongly recommended to use cookies with HTTPOnly and Secure flags set. This will allow the browser to send along the token for authentication purposes, but won’t expose it to the JavaScript environment. - If you use HTML5 Web Storage: You have to write JavaScript that manages exactly when and what authentication information is sent.