OWASP - User contributions [en]

Transport Layer Protection Cheat Sheet

2013-07-10T06:30:44Z

Jeffrey Walton: Added Rule - Prefer Ephemeral Key Exchanges

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

=== Rule - Prefer Ephemeral Key Exchanges ===

Ephemeral key exchanges are based on Diffie-Hellman and use per-session, temporary keys during the initial SSL/TLS handshake. They provide perfect forward secrecy (PFS), which means a compromise of the server's long term signing key does not compromise the confidentiality of past session. When the server uses an ephemeral key, the server will sign the temporary key with its long term key (the long term key is the customary key available in its certificate).

If you have a server farm and are providing forward secrecy, then you might have to disable session resumption. For example, Apache writes the session id's and master secrets to disk so all servers in the farm can participate in resuming a session (there is currently no in-memory mechanism to achieve the sharing). Writing the session id and master secret to disk undermines forward secrecy.

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provides cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Disable cipher suites that do not offer authentication (NULL ciphersuites, aNULL or eNULL)
* Disable anonymous Diffie-Hellman key exchange (ADH)
* Disable export level ciphers (EXP, eg. ciphers containing DES)
* Disable key sizes smaller than 128 bits for encrypting payload traffic
* Disable the use of MD5 as a hashing mechanism for payload traffic
* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing). For example, the RSA client authentication signature always uses both SHA-1 and MD5, and that usage is allowed.

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG], and [

=== Rule - Support TLS-PSK and TLS-SRP for Mutual Authentication ===

When using a shared secret or password offer TLS-PSK (Pre-Shared Key) or TLS-SRP (Secure Remote Password), which are known as Password Authenticated Key Exchange (PAKEs). TLS-PSK and TLS-SRP properly bind the channel, which refers to the cryptographic binding between the outer tunnel and the inner authentication protocol. IANA currently reserves [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 79 PSK cipehr suites] and [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 9 SRP cipher suites].

Basic authentication places the user's password on the wire in the plain text after a server authenticates itself. Basic authentication only provides unilateral authentication. In contrast, both TLS-PSK and TLS-SRP provide mutual authentication, meaning each party proves it knows the password without placing the password on the wire in the plain text.

Finally, using a PAKE removes the need to trust an outside party, such as a Certification Authority (CA).

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Use Fully Qualified Names in Certificates ===

Use fully qualified names in the DNS name field, and do not use unqualifed names (e.g., 'www'), local names (e.g., 'localhost'), or private IP addresses (e.g., 192.168.1.1) in the DNS name field. Unqualifed names, local names, or private IP addresses violate the certificate specification.

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts. Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses in Certificates ===

Certificates should not use private addresses. RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [http://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

For more information, please see the [[Pinning Cheat Sheet]].

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening

2013-06-28T18:41:12Z

Jeffrey Walton: Fixed OpenSSL configure switches

[[C-Based Toolchain Hardening]] is a treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

This is a prescriptive article, and it will not debate semantics or speculate on behavior. Some information, such as the C/C++ committee's motivation and pedigree for [https://groups.google.com/a/isocpp.org/forum/?fromgroups=#!topic/std-discussion/ak8e1mzBhGs "program diagnostics", <tt>NDEBUG</tt>, <tt>assert</tt>, and <tt>abort()</tt>], appears to be lost like a tale in the Lord of the Rings. As such, the article will specify semantics (for example, the philosophy of 'debug' and 'release' build configurations), assign behaviors (for example, what an assert should do in a 'debug' and 'release' build configurations), and present a position. If you find the posture is too aggressive, then you should back off as required to suite your taste.

A secure toolchain is not a silver bullet. It is one piece of an overall strategy in the engineering process to help ensure success. It will compliment existing processes such as static analysis, dynamic analysis, secure coding, negative test suites, and the like. Tools such as Valgrind and Helgrind will still be needed. And a project will still require solid designs and architectures.

The OWASP [http://code.google.com/p/owasp-esapi-cplusplus/source ESAPI C++] project eats its own dog food. Many of the examples you will see in this article come directly from the ESAPI C++ project.

Finally, a [[Category:Cheat Sheet|cheat sheet]] is available for those who desire a terse treatment of the material. Please visit [[C-Based_Toolchain_Hardening_Cheat_Sheet|C-Based Toolchain Hardening Cheat Sheet]] for the abbreviated version.

== Wisdom ==

Code '''must''' be correct. It '''should''' be secure. It '''can''' be efficient.

[http://en.wikipedia.org/wiki/Jon_Bentley Dr. Jon Bentley]: ''"If it doesn't have to be correct, I can make it as fast as you'd like it to be"''.

[http://en.wikipedia.org/wiki/Gary_McGraw Dr. Gary McGraw]: ''"Thou shalt not rely solely on security features and functions to build secure software as security is an emergent property of the entire system and thus relies on building and integrating all parts properly"''.

== Configuration ==

Configuration is the first opportunity to configure your project for success. Not only do you have to configure your project to meet reliability and security goals, you must also configure integrated libraries properly. You typically have has three choices. First, you can use auto-configuration utilities if on Linux or Unix. Second, you can write a makefile by hand. This is predominant on Linux, Mac OS X, and Unix, but it applies to Windows as well. Finally, you can use an integrated development environment or IDE.

=== Build Configurations ===

At this stage in the process, you should concentrate on configuring for two builds: Debug and Release. Debug will be used for development and include full instrumentation. Release will be configured for production. The difference between the two settings is usually ''optimization level'' and ''debug level''. A third build configuration is Test, and its usually a special case of Release.

For debug and release builds, the settings are typically diametrically opposed. Debug configurations have no optimizations and full debug information; while Release builds have optimizations and minimal to moderate debug information. In addition, debug code has full assertions and additional library integration, such as mudflaps and malloc guards such as <tt>dmalloc</tt>.

The Test configuration is often a Release configuration that makes everything public for testing and builds a test harness. For example, all member functions public (C++ class) and all interfaces (library or shared object) should be made available for testing. Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

[http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8] introduced an optimization of <tt>-Og</tt>. Note that it is only an optimization, and still requires a customary debug level via <tt>-g</tt>.

==== Debug Builds ====

Debug builds are where developers spend most of their time when vetting problems, so this build should concentrate forces and tools or be a 'force multiplier'. Though many do not realize, debug code is more highly valued than release code because its adorned with additional instrumentation. The debug instrumentation will cause a program to become nearly "self-debugging", and help you catch mistakes such as bad parameters, failed API calls, and memory problems.

Self-debugging code reduces your time during trouble shooting and debugging. Reducing time under the debugger means you have more time for development and feature requests. If code is checked in without debug instrumentation, it should be fixed by adding instrumentation or rejected.

For GCC, optimizations and debug symbolication are controlled through two switches: <tt>-O</tt> and <tt>-g</tt>. You should use the following as part of your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for a minimal debug session:

<pre>-O0 -g3 -ggdb</pre>

<tt>-O0</tt> turns off optimizations and <tt>-g3</tt> ensures maximum debug information is available. You may need to use <tt>-O1</tt> so some analysis is performed. Otherwise, your debug build will be missing a number of warnings not present in release builds. <tt>-g3</tt> ensures maximum debugging information is available for the debug session, including symbolic constants and <tt>#defines</tt>. <tt>-ggdb</tt> includes extensions to help with a debug session under GDB. For completeness, Jan Krachtovil stated <tt>-ggdb</tt> currently has no effect in a private email.

Debug build should also define <tt>DEBUG</tt>, and ensure <tt>NDEBUG</tt> is not defined. <tt>NDEBUG</tt> removes "program diagnostics"; and has undesirable behavior and side effects which discussed below in more detail. The defines should be present for all code, and not just the program. You use it for all code (your program and included libraries) because you need to know how they fail too (remember, you take the bug report - not the third party library).

In addition, you should use other relevant flags, such as <tt>-fno-omit-frame-pointer</tt>. Ensuring a frame pointer exists makes it easier to decode stack traces. Since debug builds are not shipped, its OK to leave symbols in the executable. Programs with debug information do not suffer performance hits. See, for example, [http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]

Finally, you should ensure your project includes additional diagnostic libraries, such as <tt>dmalloc</tt> and [http://code.google.com/p/address-sanitizer/ Address Sanitizer]. A comparison of some memory checking tools can be found at [http://code.google.com/p/address-sanitizer/wiki/ComparisonOfMemoryTools Comparison Of Memory Tools]. If you don't include additional diagostics in debug builds, then you should start using them sinces its OK to find errors you are not looking for.

==== Release Builds ====

Release builds are what your customer receives. They are meant to be run on production hardware and servers, and they should be reliable, secure, and efficient. A stable release build is the product of the hard work and effort during development.

For release builds, you should use the following as part of <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for release builds:

<pre>-On -g2</pre>

<tt>-O''n''</tt> sets optimizations for speed or size (for example, <tt>-Os</tt> or <tt>-O2</tt>), and <tt>-g2</tt> ensure debugging information is created.

Debugging information should be stripped and retained in case of symbolication for a crash report from the field. While not desired, debug information can be left in place without a performance penalty. See ''[http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]'' for details.

Release builds should also define <tt>NDEBUG</tt>, and ensure <tt>DEBUG</tt> is not defined. The time for debugging and diagnostics is over, so users get production code with full optimizations, no "programming diagnostics", and other efficiencies. If you can't optimize or your are performing excessive logging, it usually means the program is not ready for production.

If you have been relying on an <tt>assert</tt> and then a subsequent <tt>abort()</tt>, you have been abusing "program diagnostics" since it has no place in production code. If you want a memory dump, create one so users don't have to worry about secrets and other sensitive information being written to the filesystem and emailed in plain text.

For Windows, you would use <tt>/Od</tt> for debug builds; and <tt>/Ox</tt>, <tt>/O2</tt> or <tt>/Os</tt> for release builds. See Microsoft's [http://msdn.microsoft.com/en-us/library/k1ack8f1.aspx /O Options (Optimize Code)] for details.

==== Test Builds ====

Test builds are used to provide heuristic validation by way of positive and negative test suites. Under a test configuration, all interfaces are tested to ensure they perform to specification and satisfaction. "Satisfaction" is subjective, but it should include no crashing and no trashing of your memory arena, even when faced with negative tests.

Because all interfaces are tested (and not just the public ones), your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> should include:

<pre>-Dprotected=public -Dprivate=public</pre>

You should also change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>.

Nearly everyone gets a positive test right, so no more needs to be said. The negative self tests are much more interesting, and you should concentrate on trying to make your program fail so you can verify its fails gracefully. Remember, a bad guy is not going to be courteous when he attempts to cause your program to fail. And its your project that takes egg on the face by way of a bug report or guest appearance on [http://www.grok.org.uk/full-disclosure/ Full Disclosure] or [http://www.securityfocus.com/archive Bugtraq] - not ''<nowiki><some library></nowiki>'' you included.

=== Auto Tools ===

Auto configuration tools are popular on many Linux and Unix based systems, and the tools include ''Autoconf'', ''Automake'', ''config'', and ''Configure''. The tools work together to produce project files from scripts and template files. After the process completes, your project should be setup and ready to be made with <tt>make</tt>.

When using auto configuration tools, there are a few files of interest worth mentioning. The files are part of the auto tools chain and include <tt>m4</tt> and the various <tt>*.in</tt>, <tt>*.ac</tt> (autoconf), and <tt>*.am</tt> (automake) files. At times, you will have to open them, or the resulting makefiles, to tune the "stock" configuration.

There are three downsides to the command line configuration tools in the toolchain: (1) they often ignore user requests, (2) they cannot create configurations, and (3) security is often not a goal.

To demonstrate the first issue, confider your project with the following: <tt>configure CFLAGS="-Wall -fPIE" CXXFLAGS="-Wall -fPIE" LDFLAGS="-pie"</tt>. You will probably find the auto tools ignored your request, which means the command below will not produce expected results. As a work around, you will have to open an <tt>m4</tt> scripts, <tt>Makefile.in</tt> or <tt>Makefile.am</tt> and fix the configuration.

<pre>$ configure CFLAGS="-Wall -Wextra -Wconversion -fPIE -Wno-unused-parameter
-Wformat=2 -Wformat-security -fstack-protector-all -Wstrict-overflow"
LDFLAGS="-pie -z,noexecstack -z,noexecheap -z,relro -z,now"</pre>

For the second point, you will probably be disappointed to learn [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html Automake does not support the concept of configurations]. Its not entirely Autoconf's or Automake's fault - ''Make'' and its inability to detect changes is the underlying problem. Specifically, ''Make'' only [http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html checks modification times of prerequisites and targets], and does not check things like <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>. The net effect is you will not receive expected results when you issue <tt>make debug</tt> and then <tt>make test</tt> or <tt>make release</tt>.

Finally, you will probably be disappointed to learn tools such as Autoconf and Automake miss many security related opportunities and ship insecure out of the box. There are a number of compiler switches and linker flags that improve the defensive posture of a program, but they are not 'on' by default. Tools like Autoconf - which are supposed to handle this situation - often provides setting to serve the lowest of all denominators.

A recent discussion on the Automake mailing list illuminates the issue: ''[https://lists.gnu.org/archive/html/autoconf/2012-12/msg00038.html Enabling compiler warning flags]''. Attempts to improve default configurations were met with resistance and no action was taken. The resistance is often of the form, "<nowiki><some useful warning></nowiki> also produces false positives" or "<nowiki><some obscure platform></nowiki> does not support <nowiki><established security feature></nowiki>". Its noteworthy that David Wheeler, the author of ''[http://www.dwheeler.com/secure-programs/ Secure Programming for Linux and Unix HOWTO]'', was one of the folks trying to improve the posture.

=== Makefiles ===

Make is one of the earliest build systems dating back to the 1970s. Its available on Linux, Mac OS X and Unix, so you will frequently encounter projects using it. Unfortunately, Make has a number of short comings (''[http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful]'' and ''[http://www.conifersystems.com/whitepapers/gnu-make/ What’s Wrong With GNU make?]''), and can cause some discomfort. Despite issues with Make, ESAPI C++ uses Make primarily for three reasons: first, its omnipresent; second, its easier to manage than the Auto Tools family; and third, <tt>libtool</tt> was out of the question.

Consider what happens when you: (1) type <tt>make debug</tt>, and then type <tt>make release</tt>. Each build would require different <tt>CFLAGS</tt> due to optimizations and level of debug support. In your makefile, you would extract the relevant target and set <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> similar to below (taken from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/Makefile ESAPI C++ Makefile]):

<pre># Makefile
DEBUG_GOALS = $(filter $(MAKECMDGOALS), debug)
ifneq ($(DEBUG_GOALS),)
WANT_DEBUG := 1
WANT_TEST := 0
WANT_RELEASE := 0
endif
…

ifeq ($(WANT_DEBUG),1)
ESAPI_CFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
ESAPI_CXXFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
endif

ifeq ($(WANT_RELEASE),1)
ESAPI_CFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
ESAPI_CXXFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
endif

ifeq ($(WANT_TEST),1)
ESAPI_CFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
ESAPI_CXXFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
endif
…

# Merge ESAPI flags with user supplied flags. We perform the extra step to ensure
# user options follow our options, which should give user option's a preference.
override CFLAGS := $(ESAPI_CFLAGS) $(CFLAGS)
override CXXFLAGS := $(ESAPI_CXXFLAGS) $(CXXFLAGS)
override LDFLAGS := $(ESAPI_LDFLAGS) $(LDFLAGS)
…</pre>

Make will first build the program in a debug configuration for a session under the debugger using a rule similar to:

<pre>%.cpp:%.o:
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@</pre>

When you want the release build, Make will do nothing because it considers everything up to date despite the fact <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> have changed. Hence, your program will actually be in a debug configuration and risk a <tt>SIGABRT</tt> at runtime because debug instrumentation is present (recall <tt>assert</tt> calls <tt>abort()</tt> when <tt>NDEBUG</tt> is '''not''' defined). In essence, you have DoS'd yourself due to <tt>make</tt>.

In addition, many projects do not honor the user's command line. ESAPI C++ does its best to ensure a user's flags are honored via <tt>override</tt> as shown above, but other projects do not. For example, consider a project that should be built with Position Independent Executable (PIE or ASLR) enabled and data execution prevention (DEP) enabled. Dismissing user settings combined with insecure out of the box settings (and not picking them up during auto-setup or auto-configure) means a program built with the following will likely have neither defense:

<pre>$ make CFLAGS="-fPIE" CXXFLAGS="-fPIE" LDFLAGS="-pie -z,noexecstack, -z,noexecheap"</pre>

Defenses such as ASLR and DEP are especially important on Linux because [http://linux.die.net/man/5/elf Data Execution - not Prevention - is the norm].

=== Integration ===

Project level integration presents opportunities to harden your program or library with domain specific knowledge. For example, if the platform supports Position Independent Executables (PIE or ASLR) and data execution prevention (DEP), then you should integrate with it. The consequences of not doing so could result in exploitation. As a case in point, see KingCope's 0-days for MySQL in December, 2012 (CVE-2012-5579 and CVE-2012-5612, among others). Integration with platform security would have neutered a number of the 0-days.

You also have the opportunity to include helpful libraries that are not need for business logic support. For example, if you are working on a platform with [http://dmalloc.com DMalloc] or [http://code.google.com/p/address-sanitizer/ Address Sanitizer], you should probably use it in your debug builds. For Ubuntu, DMalloc available from the package manager and can be installed with <tt>sudo apt-get install libdmalloc5</tt>. For Apple platforms, its available as a scheme option (see [[#Clang/Xcode|Clang/Xcode]] below). Address Sanitizer is available in [http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8 and above] for many platforms.

In addition, project level integration is an opportunity to harden third party libraries you chose to include. Because you chose to include them, you and your users are responsible for them. If you or your users endure a SP800-53 audit, third party libraries will be in scope because the supply chain is included (specifically, item SA-12, Supply Chain Protection). The audits are not limited to those in the US Federal arena - financial institutions perform reviews too. A perfect example of violating this guidance is [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525], which was due to [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library].

Another example is including OpenSSL. You know (1) [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 is insecure], (2) [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 is insecure], and (3) [http://arstechnica.com/security/2012/09/crime-hijacks-https-sessions/ compression is insecure] (among others). In addition, suppose you don't use hardware and engines, and only allow static linking. Given the knowledge and specifications, you would configure the OpenSSL library as follows:

<pre>$ Configure darwin64-x86_64-cc -no-hw -no-engine -no-comp -no-shared -no-dso -no-ssl2 -no-ssl3 --openssldir=…</pre>

''Note Well'': you might want engines, especially on Ivy Bridge microarchitectures (3rd generation Intel Core i5 and i7 processors). To have OpenSSL use the processor's random number generator (via the of <tt>rdrand</tt> instruction), you will need to call OpenSSL's <tt>ENGINE_load_rdrand()</tt> function and then <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. See [http://wiki.opensslfoundation.com/index.php/Random_Numbers OpenSSL's Random Numbers] for details.

If you configure without the switches, then you will likely have vulnerable code/libraries and risk failing an audit. If the program is a remote server, then the following command will reveal if compression is active on the channel:

<pre>$ echo "GET / HTTP1.0" | openssl s_client -connect <nowiki>example.com:443</nowiki></pre>

<tt>nm</tt> or <tt>openssl s_client</tt> will show that compression is enabled in the client. In fact, any symbol within the <tt>OPENSSL_NO_COMP</tt> preprocessor macro will bear witness since <tt>-no-comp</tt> is translated into a <tt>CFLAGS</tt> define.

<pre>$ nm /usr/local/ssl/iphoneos/lib/libcrypto.a 2>/dev/null | egrep -i "(COMP_CTX_new|COMP_CTX_free)"
0000000000000110 T COMP_CTX_free
0000000000000000 T COMP_CTX_new</pre>

Even more egregious is the answer given to auditors who specifically ask about configurations and protocols: "we don't use weak/wounded/broken ciphers" or "we follow best practices." The use of compression tells the auditor that you are using wounded protocol in an insecure configuration and you don't follow best practices. That will likely set off alarm bells, and ensure the auditor dives deeper on more items.

== Preprocessor ==

The preprocessor is crucial to setting up a project for success. The C committee provided one macro - <tt>NDEBUG</tt> - and the macro can be used to derive a number of configurations and drive engineering processes. Unfortunately, the committee also left many related items to chance, which has resulted in programmers abusing builtin facilities. This section will help you set up you projects to integrate well with other projects and ensure reliability and security.

There are three topics to discuss when hardening the preprocessor. The first is well defined configurations which produce well defined behaviors, the second is useful behavior from assert, and the third is proper use of macros when integrating vendor code and third party libraries.

=== Configurations ===

To remove ambiguity, you should recognize two configurations: Release and Debug. Release is for production code on live servers, and its behavior is requested via the C/C++ <tt>NDEBUG</tt> macro. Its also the only macro observed by the C and C++ Committees and Posix. Diametrically opposed to release is Debug. While there is a compelling argument for <tt>!defined(NDEBUG)</tt>, you should have an explicit macro for the configuration and that macro should be <tt>DEBUG</tt>. This is because vendors and outside libraries use <tt>DEBUG</tt> (or similar) macro for their configuration. For example, Carnegie Mellon's Mach kernel uses <tt>DEBUG</tt>, Microsoft's CRT uses [http://msdn.microsoft.com/en-us/library/ww5t02fa%28v=vs.71%29.aspx<tt>_DEBUG</tt>], and Wind River Workbench uses <tt>DEBUG_MODE</tt>.

In addition to <tt>NDEBUG</tt> (Release) and <tt>DEBUG</tt> (Debug), you have two additional cross products: both are defined or neither are defined. Defining both should be an error, and defining neither should default to a release configuration. Below is from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/esapi/EsapiCommon.h ESAPI C++ EsapiCommon.h], which is the configuration file used by all source files:

<pre>// Only one or the other, but not both
#if (defined(DEBUG) || defined(_DEBUG)) && (defined(NDEBUG) || defined(_NDEBUG))
# error Both DEBUG and NDEBUG are defined.
#endif

// The only time we switch to debug is when asked. NDEBUG or {nothing} results
// in release build (fewer surprises at runtime).
#if defined(DEBUG) || defined(_DEBUG)
# define ESAPI_BUILD_DEBUG 1
#else
# define ESAPI_BUILD_RELEASE 1
#endif</pre>

When <tt>DEBUG</tt> is in effect, your code should receive full debug instrumentation, including the full force of assertions.

=== ASSERT ===

Asserts will help you create self-debugging code by helping you find the point of first failure quickly and easily. Asserts should be used throughout your program, including parameter validation, return value checking and program state. The <tt>assert</tt> will silently guard your code through its lifetime. It will always be there, even when not debugging a specific component of a module. If you have thorough code coverage, you will spend less time debugging and more time developing because programs will debug themselves.

To use asserts effectively, you should assert everything. That includes parameters upon entering a function, return values from function calls, and any program state. Everywhere you place an <tt>if</tt> statement for validation or checking, you should have an assert. Everywhere you have an <tt>assert</tt> for validation or checking, you should have an <tt>if</tt> statement. They go hand-in-hand.

If you are still using <tt>printf</tt>'s, then you have an opportunity for improvement. In the time it takes for you to write a <tt>printf</tt> or <tt>NSLog</tt> statement, you could have written an <tt>assert</tt>. Unlike the <tt>printf</tt> or <tt>NSLog</tt> which are often removed when no longer needed, the <tt>assert</tt> stays active forever. Remember, this is all about finding the point of first failure quickly so you can spend your time doing other things.

There is one problem with using asserts - [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html Posix states <tt>assert</tt> should call <tt>abort()</tt>] if <tt>NDEBUG</tt> is '''not''' defined. When debugging, <tt>NDEBUG</tt> will never be defined since you want the "program diagnostics" (quote from the Posix description). The behavior makes <tt>assert</tt> and its accompanying <tt>abort()</tt> completely useless for development. The result of "program diagnostics" calling <tt>abort()</tt> due to standard C/C++ behavior is disuse - developers simply don't use them. Its incredibly bad for the development community because self-debugging programs can help eradicate so many stability problems.

Since self-debugging programs are so powerful, you will have to have to supply your own assert and signal handler with improved behavior. Your assert will exchange auto-aborting behavior for auto-debugging behavior. The auto-debugging facility will ensure the debugger snaps when a problem is detected, and you will find the point of first failure quickly and easily.

ESAPI C++ supplies its own assert with the behavior described above. In the code below, <tt>ASSERT</tt> raises <tt>SIGTRAP</tt> when in effect or it evaluates to <tt>void</tt> in other cases.

<pre>// A debug assert which should be sprinkled liberally. This assert fires and then continues rather
// than calling abort(). Useful when examining negative test cases from the command line.
#if (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_STARNIX))
# define ESAPI_ASSERT1(exp) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
# define ESAPI_ASSERT2(exp, msg) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< ": \"" << (msg) << "\"" << std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
#elif (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_WINDOWS))
# define ESAPI_ASSERT1(exp) assert(exp)
# define ESAPI_ASSERT2(exp, msg) assert(exp)
#else
# define ESAPI_ASSERT1(exp) ((void)(exp))
# define ESAPI_ASSERT2(exp, msg) ((void)(exp))
#endif

#if !defined(ASSERT)
# define ASSERT(exp) ESAPI_ASSERT1(exp)
#endif</pre>

At program startup, a <tt>SIGTRAP</tt> handler will be installed if one is not provided by another component:

<pre>struct DebugTrapHandler
{
DebugTrapHandler()
{
struct sigaction new_handler, old_handler;

do
{
int ret = 0;

ret = sigaction (SIGTRAP, NULL, &old_handler);
if (ret != 0) break; // Failed

// Don't step on another's handler
if (old_handler.sa_handler != NULL) break;

new_handler.sa_handler = &DebugTrapHandler::NullHandler;
new_handler.sa_flags = 0;

ret = sigemptyset (&new_handler.sa_mask);
if (ret != 0) break; // Failed

ret = sigaction (SIGTRAP, &new_handler, NULL);
if (ret != 0) break; // Failed

} while(0);
}

static void NullHandler(int /*unused*/) { }

};

// We specify a relatively low priority, to make sure we run before other CTORs
// http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#C_002b_002b-Attributes
static const DebugTrapHandler g_dummyHandler __attribute__ ((init_priority (110)));</pre>

On a Windows platform, you would call <tt>_set_invalid_parameter_handler</tt> (and possibly <tt>set_unexpected</tt> or <tt>set_terminate</tt>) to install a new handler.

Live hosts running production code should always define <tt>NDEBUG</tt> (i.e., release configuration), which means they do not assert or auto-abort. Auto-abortion is not acceptable behavior, and anyone who asks for the behavior is completely abusing the functionality of "program diagnostics". If a program wants a core dump, then it should create the dump rather than crashing.

For more reading on asserting effectively, please see one of John Robbin's books, such as ''[http://www.amazon.com/dp/0735608865 Debugging Applications]''. John is a legendary bug slayer in Windows circles, and he will show you how to do nearly everything, from debugging a simple program to bug slaying in multithreaded programs.

=== Additional Macros ===

Additional macros include any macros needed to integrate properly and securely. It includes integrating the program with the platform (for example MFC or Cocoa/CocoaTouch) and libraries (for example, Crypto++ or OpenSSL). It can be a challenge because you have to have proficiency with your platform and all included libraries and frameworks. The list below illustrates the level of detail you will need when integrating.

Though Boost is missing from the list, it appears to lack recommendations, additional debug diagnostics, and a hardening guide. See ''[http://stackoverflow.com/questions/14927033/boost-hardening-guide-preprocessor-macros BOOST Hardening Guide (Preprocessor Macros)]'' for details. In addition, Tim Day points to ''[http://boost.2283326.n4.nabble.com/boost-build-should-we-not-define-SECURE-SCL-0-by-default-for-all-msvc-toolsets-td2654710.html <nowiki>[boost.build] should we not define _SECURE_SCL=0 by default for all msvc toolsets</nowiki>]'' for a recent discussion related to hardening (or lack thereof).

In addition to what you should define, defining some macros and undefining others should trigger a security related defect. For example, <tt>-U_FORTIFY_SOURCES</tt> on Linux and <tt>_CRT_SECURE_NO_WARNINGS=1</tt>, <tt>_SCL_SECURE_NO_WARNINGS</tt>, <tt>_ATL_SECURE_NO_WARNINGS</tt> or <tt>STRSAFE_NO_DEPRECATE</tt> on Windows.

{| border="1"

|-style="background:#DADADA"
!Platform/Library!!Debug!!Release
|+ Table 1: Additional Platform/Library Macros

|-
|width="175pt"|All
|width="250pt"|DEBUG=1
|width="250pt"|NDEBUG=1

|-
|Linux
|_GLIBCXX_DEBUG=1a 
_GLIBCXX_CONCEPT_CHECKS=1b
|_FORTIFY_SOURCE=2

|-
|Android
|NDK_DEBUG=1
|_FORTIFY_SOURCE=1 (4.2 and above) 
<tt>#define LOGI(...)</tt> (define to nothing, preempt logging)

|-
|Cocoa/CocoaTouch
|
|NS_BLOCK_ASSERTIONS=1 
<tt>#define NSLog(...)</tt> (define to nothing, preempt ASL)

|-
|SafeInt
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1

|-
|Microsoft
|_DEBUG=1, STRICT, 
_SECURE_SCL=1, _HAS_ITERATOR_DEBUGGING=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1
|STRICT 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1

|-
|Microsoft ATL & MFC
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS

|-
|STLPort
|_STLP_DEBUG=1, _STLP_USE_DEBUG_LIB=1 
_STLP_DEBUG_ALLOC=1, _STLP_DEBUG_UNINITIALIZED=1
|

|-
|SQLite
|SQLITE_DEBUG, SQLITE_MEMDEBUG 
SQLITE_SECURE_DELETEc 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nd
|SQLITE_SECURE_DELETEc 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nd

|-
|SQLCipher
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3e
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3e

|}

a Be careful with <tt>_GLIBCXX_DEBUG</tt> when using pre-compiled libraries such as Boost from a distribution. There are ABI incompatibilities, and the result will likely be a crash. You will have to compile Boost with <tt>_GLIBCXX_DEBUG</tt> or omit <tt>_GLIBCXX_DEBUG</tt>.

b See [http://gcc.gnu.org/onlinedocs/libstdc++/manual/concept_checking.html Chapter 5, Diagnostics] of the libstdc++ manual for details.

c SQLite secure deletion zeroizes memory on destruction. Define as required, and always define in US Federal since zeroization is required for FIPS 140-2, Level 1.

d ''N'' is 0644 by default, which means everyone has some access.

e Force temporary tables into memory (no unencrypted data to disk).

== Compiler and Linker ==

Compiler writers provide a rich set of warnings from the analysis of code during compilation. Both GCC and Visual Studio have static analysis capabilities to help find mistakes early in the development process. The built in static analysis capabilities of GCC and Visual Studio are usually sufficient to ensure proper API usage and catch a number of mistakes such as using an uninitialized variable or comparing a negative signed int and a positive unsigned int.

As a concrete example, (and for those not familiar with C/C++ promotion rules), a warning will be issued if a signed integer is promoted to an unsigned integer and then compared because a side effect is <tt>-1 > 1</tt> after promotion! GCC and Visual Studio will not currently catch, for example, SQL injections and other tainted data usage. For that, you will need a tool designed to perform data flow analysis or taint analysis.

Some in the development community resist static analysis or refute its results. For example, when static analysis warned the Linux kernel's <tt>sys_prctl</tt> was comparing an unsigned value against less than zero, Jesper Juhl offered a patch to clean up the code. Linus Torvalds howled “No, you don't do this… GCC is crap” (referring to compiling with warnings). For the full discussion, see ''[http://linux.derkeiler.com/Mailing-Lists/Kernel/2006-11/msg08325.html <nowiki>[PATCH] Don't compare unsigned variable for <0 in sys_prctl()</nowiki>]'' from the Linux Kernel mailing list.

The following sections will detail steps for three platforms. First is a typical GNU Linux based distribution offering GCC and Binutils, second is Clang and Xcode, and third is modern Windows platforms.

=== Distribution Hardening ===

Before discussing GCC and Binutils, it would be a good time to point out some of the defenses discussed below are all ready present in a distribution. Unfortunately, its design by committee, so what is present is usually only a mild variation of what is available (this way, everyone is mildly offended). For those who are purely worried about performance, you might be surprised to learn you have already taken the small performance hint without even knowing.

Linux and BSD distributions often apply some hardening without intervention via ''[http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html GCC Spec Files]''. If you are using Debian, Ubuntu, Linux Mint and family, see ''[http://wiki.debian.org/Hardening Debian Hardening]''. For Red Hat and Fedora systems, see ''[http://lists.fedoraproject.org/pipermail/devel-announce/2011-August/000821.html New hardened build support (coming) in F16]''. Gentoo users should visit ''[http://www.gentoo.org/proj/en/hardened/ Hardened Gentoo]''.

You can see the settings being used by a distribution via <tt>gcc -dumpspecs</tt>. From Linux Mint 12 below, -fstack-protector (but not -fstack-protector-all) is used by default.

<pre>$ gcc -dumpspecs
…
*link_ssp: %{fstack-protector:}

*ssp_default: %{!fno-stack-protector:%{!fstack-protector-all: %{!ffreestanding:%{!nostdlib:-fstack-protector}}}}
…</pre>

The “SSP” above stands for Stack Smashing Protector. SSP is a reimplementation of Hiroaki Etoh's work on IBM Pro Police Stack Detector. See Hiroaki Etoh's patch ''[http://gcc.gnu.org/ml/gcc-patches/2001-06/msg01753.html gcc stack-smashing protector]'' and IBM's ''[http://www.research.ibm.com/trl/projects/security/ssp/ GCC extension for protecting applications from stack-smashing attacks]'' for details.

=== GCC/Binutils ===

GCC (the compiler collection) and Binutils (the assemblers, linkers, and other tools) are separate projects that work together to produce a final executable. Both the compiler and linker offer options to help you write safer and more secure code. The linker will produce code which takes advantage of platform security features offered by the kernel and PaX, such as no-exec stacks and heaps (NX) and Position Independent Executable (PIE).

The table below offers a set of compiler options to build your program. Static analysis warnings help catch mistakes early, while the linker options harden the executable at runtime. In the table below, “GCC” should be loosely taken as “non-ancient distributions.” While the GCC team considers 4.2 ancient, you will still encounter it on Apple and BSD platforms due to changes in GPL licensing around 2007. Refer to ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Option Summary]'', ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html Options to Request or Suppress Warnings]'' and ''[http://sourceware.org/binutils/docs-2.21/ld/Options.html Binutils (LD) Command Line Options]'' for usage details.

Noteworthy of special mention are <tt>-fno-strict-overflow</tt> and <tt>-fwrapv</tt>a. The flags ensure the compiler does not remove statements that result in overflow or wrap. If your program only runs correctly using the flags, it is likely violating C/C++ rules on overflow and illegal. If the program is illegal due to overflow or wrap checking, you should consider using [http://code.google.com/p/safe-iop/ safe-iop] for C or David LeBlanc's [http://safeint.codeplex.com SafeInt] in C++.

For a project compiled and linked with hardened settings, some of those settings can be verified with the [http://www.trapkit.de/tools/checksec.html Checksec] tool written by Tobias Klein. The <tt>checksec.sh</tt> script is designed to test standard Linux OS and PaX security features being used by an application. See the [http://www.trapkit.de/tools/checksec.html Trapkit] web page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 2: GCC C Warning Options

|-
|width="200pt"|<nowiki>-Wall -Wextra</nowiki>
|width="75t"|GCC
|width="425pt"|Enables many warnings (despite their names, all and extra do not turn on all warnings).a

|-
|<nowiki>-Wconversion</nowiki>
|GCC
|Warn for implicit conversions that may alter a value (includes -Wsign-conversion).

|-
|<nowiki>-Wsign-conversion</nowiki>
|GCC
|Warn for implicit conversions that may change the sign of an integer value, such as assigning a signed integer to an unsigned integer (<tt>-1 > 1</tt> after promotion!).

|-
|<nowiki>-Wcast-align</nowiki>
|GCC
|Warn for a pointer cast to a type which has a different size, causing an invalid alignment and subsequent bus error on ARM processors.

|-
|<nowiki>-Wformat=2 -Wformat-security</nowiki>
|GCC
|Increases warnings related to possible security defects, including incorrect format specifiers.

|-
|<nowiki>-fno-common</nowiki>
|GCC
|Prevent global variables being simultaneously defined in different object files.

|-
|<nowiki>-fstack-protector or -fstack-protector-all</nowiki>
|GCC
|Stack Smashing Protector (SSP). Improves stack layout and adds a guard to detect stack based buffer overflows.b

|-
|<nowiki>-fno-omit-frame-pointer</nowiki>
|GCC
|Improves backtraces for post-mortem analysis

|-
|<nowiki>-Wmissing-prototypes and -Wmissing-declarations</nowiki>
|GCC
|Warn if a global function is defined without a prototype or declaration.

|-
|<nowiki>-Wstrict-prototypes</nowiki>
|GCC
|Warn if a function is declared or defined without specifying the argument types.

|-
|<nowiki>-Wstrict-overflow</nowiki>
|GCC 4.2
|Warn about optimizations taken due to <nowiki>[undefined]</nowiki> signed integer overflow assumptions.

|-
|<nowiki>-Wtrampolines</nowiki>
|GCC 4.3
|Warn about trampolines generated for pointers to nested functions. Trampolines require executable stacks.

|-
|<nowiki>-fsanitize=address</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/address-sanitizer/ AddressSanitizer], a fast memory error detector. Memory access instructions will be instrumented to help detect heap, stack, and global buffer overflows; as well as use-after-free bugs.

|-
|<nowiki>-fsanitize=thread</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/data-race-test/wiki/ThreadSanitizer ThreadSanitizer], a fast data race detector. Memory access instructions will be instrumented to detect data race bugs.

|-
|<nowiki>-Wl,-z,nodlopen and -Wl,-z,nodump</nowiki>
|Binutils 2.10
|Reduces the ability of an attacker to load, manipulate, and dump shared objects.

|-
|<nowiki>-Wl,-z,noexecstack and -Wl,-z,noexecheap</nowiki>
|Binutils 2.14
|Data Execution Prevention (DEP). ELF headers are marked with PT_GNU_STACK and PT_GNU_HEAP.

|-
|<nowiki>-Wl,-z,relro</nowiki>
|Binutils 2.15
|Helps remediate Global Offset Table (GOT) attacks on executables.

|-
|<nowiki>-Wl,-z,now</nowiki>
|Binutils 2.15
|Helps remediate Procedure Linkage Table (PLT) attacks on executables.

|-
|<nowiki>-fPIC</nowiki>
|Binutils
|Position Independent Code. Used for libraries and shared objects. Both -fPIC (compiler) and -shared (linker) are required.

|-
|<nowiki>-fPIE</nowiki>
|Binutils 2.16
|Position Independent Executable (ASLR). Used for programs. Both -fPIE (compiler) and -pie (linker) are required.

|}

a Unlike Clang and -Weverything, GCC does not provide a switch to truly enable all warnings. 
b -fstack-protector guards functions with high risk objects such as C strings, while -fstack-protector-all guards all objects.

Additional C++ warnings which can be used include the following in Table 3. See ''[http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html GCC's Options Controlling C++ Dialect]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 3: GCC C++ Warning Options

|-
|width="200pt"|<nowiki>-Woverloaded-virtual</nowiki>
|width="425pt"|Warn when a function declaration hides virtual functions from a base class.

|-
|<nowiki>-Wreorder</nowiki>
|Warn when the order of member initializers given in the code does not match the order in which they must be executed.

|-
|<nowiki>-Wsign-promo</nowiki>
|Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size.

|-
|<nowiki>-Wnon-virtual-dtor</nowiki>
|Warn when a class has virtual functions and an accessible non-virtual destructor.

|-
|<nowiki>-Weffc++</nowiki>
|Warn about violations of the following style guidelines from Scott Meyers' ''[http://www.aristeia.com/books.html Effective C++, Second Edition]'' book.

|}

And additional Objective C warnings which are often useful include the following. See ''[http://gcc.gnu.org/onlinedocs/gcc/Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html Options Controlling Objective-C and Objective-C++ Dialects]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 4: GCC Objective C Warning Options

|-
|width="200pt"|<nowiki>-Wstrict-selector-match</nowiki>
|width="425pt"|Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type id or Class.

|-
|<nowiki>-Wundeclared-selector</nowiki>
|Warn if a <tt>@selector(…)</tt> expression referring to an undeclared selector is found.

|}

The use of aggressive warnings will produce spurious noise. The noise is a tradeoff - you can learn of potential problems at the cost of wading through some chaff. The following will help reduces spurious noise from the warning system:

* -Wno-unused-parameter (GCC)
* -Wno-type-limits (GCC 4.3)
* -Wno-tautological-compare (Clang)

Finally, a simple version based Makefile example is shown below. This is different than feature based makefile produced by auto tools (which will test for a particular feature and then define a symbol or configure a template file). Not all platforms use all options and flags. To address the issue you can pursue one of two strategies. First, you can ship with a weakened posture by servicing the lowest common denominator; or you can ship with everything in force. In the latter case, those who don't have a feature available will edit the makefile to accommodate their installation.

<pre>CXX=g++
EGREP = egrep
…

GCC_COMPILER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version')
GCC41_OR_LATER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version (4\.[1-9]|[5-9])')
…

GNU_LD210_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[0-9]|2\.[2-9])')
GNU_LD214_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[4-9]|2\.[2-9])')
…

ifeq ($(GCC_COMPILER),1)
MY_CC_FLAGS += -Wall -Wextra -Wconversion
MY_CC_FLAGS += -Wformat=2 -Wformat-security
MY_CC_FLAGS += -Wno-unused-parameter
endif

ifeq ($(GCC41_OR_LATER),1)
MY_CC_FLAGS += -fstack-protector-all
endif

ifeq ($(GCC42_OR_LATER),1)
MY_CC_FLAGS += -Wstrict-overflow
endif

ifeq ($(GCC43_OR_LATER),1)
MY_CC_FLAGS += -Wtrampolines
endif

ifeq ($(GNU_LD210_OR_LATER),1)
MY_LD_FLAGS += -z,nodlopen -z,nodump
endif

ifeq ($(GNU_LD214_OR_LATER),1)
MY_LD_FLAGS += -z,noexecstack -z,noexecheap
endif

ifeq ($(GNU_LD215_OR_LATER),1)
MY_LD_FLAGS += -z,relro -z,now
endif

ifeq ($(GNU_LD216_OR_LATER),1)
MY_CC_FLAGS += -fPIE
MY_LD_FLAGS += -pie
endif

# Use 'override' to honor the user's command line
override CFLAGS := $(MY_CC_FLAGS) $(CFLAGS)
override CXXFLAGS := $(MY_CC_FLAGS) $(CXXFLAGS)
override LDFLAGS := $(MY_LD_FLAGS) $(LDFLAGS)
…</pre>

=== Clang/Xcode ===

[http://clang.llvm.org Clang] and [http://llvm.org LLVM] have been aggressively developed since Apple lost its GPL compiler back in 2007 (due to Tivoization which resulted in GPLv3). Since that time, a number of developers and Goggle have joined the effort. While Clang will consume most (all?) GCC/Binutil flags and switches, the project supports a number of its own options, including a static analyzer. In addition, Clang is relatively easy to build with additional diagnostics, such as Dr. John Regher and Peng Li's [http://embed.cs.utah.edu/ioc/ Integer Overflow Checker (IOC)].

IOC is incredibly useful, and has found bugs in a number of projects, from the Linux Kernel (<tt>include/linux/bitops.h</tt>, still unfixed), SQLite, PHP, Firefox (many still unfixed), LLVM, and Python. Future version of Clang (Clang 3.3 and above) will allow you to enable the checks out of the box with <tt>-fsanitize=integer</tt> and <tt>-fsanitize=shift</tt>.

Clang options can be found at [http://clang.llvm.org/docs/UsersManual.html Clang Compiler User’s Manual]. Clang does include an option to turn on all warnings - <tt>-Weverything</tt>. Use it with care but use it regularly since you will get back a lot of noise and issues you missed. For example, add <tt>-Weverything</tt> for production builds and make non-spurious issues a quality gate. Under Xcode, simply add <tt>-Weverything</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>.

In addition to compiler warnings, both static analysis and additional security checks can be performed. Reading on Clang's static analysis capabilities can be found at [http://clang-analyzer.llvm.org Clang Static Analyzer]. Figure 1 below shows some of the security checks utilized by Xcode.

{| align="center"
| [[File:toolchan-hardening-11.png|thumb|450px|Figure 1: Clang/LLVM and Xcode options]]
|}

=== Visual Studio ===

Visual Studio offers a convenient Integrated Development Environment (IDE) for managing solutions and their settings. the section called “Visual Studio Options” discusses option which should be used with Visual Studio, and the section called “Project Properties” demonstrates incorporating those options into a solution's project.

The table below lists the compiler and linker switches which should be used under Visual Studio. Refer to Howard and LeBlanc's Writing Secure Code (Microsoft Press) for a detailed discussion; or ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]'' in Security Briefs by Michael Howard. In the table below, “Visual Studio” refers to nearly all versions of the development environment, including Visual Studio 5.0 and 6.0.

For a project compiled and linked with hardened settings, those settings can be verified with BinScope. BinScope is a verification tool from Microsoft that analyzes binaries to ensure that they have been built in compliance with Microsoft's Security Development Lifecycle (SDLC) requirements and recommendations. See the ''[https://www.microsoft.com/download/en/details.aspx?id=11910 BinScope Binary Analyzer]'' download page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 5: Visual Studio Warning Options

|-
|width="150pt"|<nowiki>/W4</nowiki>
|width="100pt"|Visual Studio
|width="350pt"|Warning level 4, which includes most warnings.

|-
|<nowiki>/WAll</nowiki>
|Visual Studio 2003
|Enable all warnings, including those off by default.a

|-
|<nowiki>/GS</nowiki>
|Visual Studio 2003
|Adds a security cookie (guard or canary) on the stack before the return address buffer stack based for overflow checks.a

|-
|<nowiki>/SafeSEH</nowiki>
|Visual Studio 2003
|Safe structured exception handling to remediate SEH overwrites.

|-
|<nowiki>/analyze</nowiki>
|Visual Studio 2005
|Enterprise code analysis (freely available with Windows SDK for Windows Server 2008 and .NET Framework 3.5).

|-
|<nowiki>/NXCOMPAT</nowiki>
|Visual Studio 2005
|Data Execution Prevention (DEP).

|-
|<nowiki>/dynamicbase</nowiki>
|Visual Studio 2005 SP1
|Address Space Layout Randomization (ASLR).

|-
|<nowiki>strict_gs_check</nowiki>
|Visual Studio 2005 SP1
|Aggressively applies stack protections to a source file to help detect some categories of stack based buffer overruns.b

|}

aSee Jon Sturgeon's discussion of the switch at ''[https://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx Off By Default Compiler Warnings in Visual C++]''. 
aWhen using /GS, there are a number of circumstances which affect the inclusion of a security cookie. For example, the guard is not used if there is no buffer in the stack frame, optimizations are disabled, or the function is declared naked or contains inline assembly. 
b<tt>#pragma strict_gs_check(on)</tt> should be used sparingly, but is recommend in high risk situations, such as when a source file parses input from the internet.

=== Warn Suppression ===

From the tables above, a lot of warnings have been enabled to help detect possible programming mistakes. The potential mistakes are detected via compiler which carries around a lot of contextual information during its code analysis phase. At times, you will receive spurious warnings because the compiler is not ''that'' smart. Its understandable and even a good thing (how would you like to be out of a job because a program writes its own programs?). At times you will have to learn how to work with the compiler's warning system to suppress warnings. Notice what was not said: turn off the warnings.

Suppressing warnings placates the compiler for spurious noise so you can get to the issues that matter (you are separating the wheat from the chaff). This section will offer some hints and point out some potential minefields. First is an unused parameter (for example, <tt>argc</tt> or <tt>argv</tt>). Suppressing unused parameter warnings is especially helpful for C++ and interface programming, where parameters are often unused. For this warning, simply define an "UNUSED" macro and warp the parameter:

<pre>#define UNUSED_PARAMETER(x) ((void)x)
…

int main(int argc, char* argv[])
{
UNUSED_PARAMETER(argc);
UNUSED_PARAMETER(argv);
…
}</pre>

A potential minefield lies near "comparing unsigned and signed" values, and <tt>-Wconversion</tt> will catch it for you. This is because C/C++ promotion rules state the signed value will be promoted to an unsigned value and then compared. That means <tt>-1 > 1</tt> after promotion! To fix this, you cannot blindly cast - you must first range test the value:

<pre>int x = GetX();
unsigned int y = GetY();

ASSERT(x >= 0);
if(!(x >= 0))
throw runtime_error("WTF??? X is negative.");

if(static_cast<unsigned int>(x) > y)
cout << "x is greater than y" << endl;
else
cout << "x is not greater than y" << endl;</pre>

Notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>x</tt>. Just run the program and wait for it to tell you there is a problem. If there is a problem, the program will snap the debugger (and more importantly, not call a useless <tt>abort()</tt> as specified by Posix). It beats the snot out of <tt>printf</tt> that are removed when no longer needed or pollute outputs.

Another conversion problem you will encounter conversion between types, and <tt>-Wconversion</tt> will also catch it for you. The following will always have an opportunity to fail, and should light up like a Christmas tree:

<pre>struct sockaddr_in addr;
…

addr.sin_port = htons(atoi(argv[2]));</pre>

The following would probably serve you much better. Notice <tt>atoi</tt> and fiends are not used because they can silently fail. In addition, the code is instrumented so you don't need to waste a lot of time debugging potential problems:

<pre>const char* cstr = GetPortString();

ASSERT(cstr != NULL);
if(!(cstr != NULL))
throw runtime_error("WTF??? Port string is not valid.");

istringstream iss(cstr);
long long t = 0;
iss >> t;

ASSERT(!(iss.fail()));
if(iss.fail())
throw runtime_error("WTF??? Failed to read port.");

// Should this be a port above the reserved range ([0-1024] on Unix)?
ASSERT(t > 0);
if(!(t > 0))
throw runtime_error("WTF??? Port is too small");

ASSERT(t < static_cast<long long>(numeric_limits<unsigned int>::max()));
if(!(t < static_cast<long long>(numeric_limits<unsigned int>::max())))
throw runtime_error("WTF??? Port is too large");

// OK to use port
unsigned short port = static_cast<unsigned short>(t);
…</pre>

Again, notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>port</tt>. This code will continue checking conditions, years after being instrumented (assuming to wrote code to read a config file early in the project). There's no need to remove the <tt>ASSERT</tt>s as with <tt>printf</tt> since they are silent guardians.

Another useful suppression trick is too avoid ignoring return values. Not only is it useful to suppress the warning, its required for correct code. For example, <tt>snprint</tt> will alert you to truncations through its return value. You should not make them silent truncations by ignoring the warning or casting to <tt>void</tt>:

<pre>char path[PATH_MAX];
…

int ret = snprintf(path, sizeof(path), "%s/%s", GetDirectory(), GetObjectName());
ASSERT(ret != -1);
ASSERT(!(ret >= sizeof(path)));

if(ret == -1 || ret >= sizeof(path))
throw runtime_error("WTF??? Unable to build full object name");

// OK to use path
…</pre>

The problem is pandemic, and not just boring user land programs. Projects which offer high integrity code, such as SELinux, suffer silent truncations. The following is from an approved SELinux patch even though a comment was made that it [http://permalink.gmane.org/gmane.comp.security.selinux/16845 suffered silent truncations in its <tt>security_compute_create_name</tt> function] from <tt>compute_create.c</tt>.

<pre>12 int security_compute_create_raw(security_context_t scon,
13 security_context_t tcon,
14 security_class_t tclass,
15 security_context_t * newcon)
16 {
17 char path[PATH_MAX];
18 char *buf;
19 size_t size;
20 int fd, ret;
21
22 if (!selinux_mnt) {
23 errno = ENOENT;
24 return -1;
25 }
26
27 snprintf(path, sizeof path, "%s/create", selinux_mnt);
28 fd = open(path, O_RDWR);</pre>

Unlike other examples, the above code will not debug itself, and you will have to set breakpoints and trace calls to determine the point of first failure. (And the code above gambles that the truncated file does not exist or is not under an adversary's control by blindly performing the <tt>open</tt>).

== Runtime ==

The previous sections concentrated on setting up your project for success. This section will examine additional hints for running with increased diagnostics and defenses. Not all platforms are created equal - GNU Linux is difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening to a program after compiling and static linking]; while Windows allows post-build hardening through a download. Remember, the goal is to find the point of first failure quickly so you can improve the reliability and security of the code.

=== Xcode ===

Xcode offers additional [http://developer.apple.com/library/mac/#recipes/xcode_help-scheme_editor/Articles/SchemeDiagnostics.html Application Diagnostics] that can help find memory errors and object use problems. Schemes can be managed through ''Products'' menu item, ''Scheme'' submenu item, and then ''Edit''. From the editor, navigate to the ''Diagnostics'' tab. In the figure below, four additional instruments are enabled for the debugging cycle: Scribble guards, Edge guards, Malloc guards, and Zombies.

{| align="center"
| [[File:toolchan-hardening-1.png|thumb|450px|Figure 2: Xcode Memory Diagnostics]]
|}

There is one caveat with using some of the guards: Apple only provides them for the simulator, and not a device. In the past, the guards were available for both devices and simulators.

=== Windows ===

Visual Studio offers a number of debugging aides for use during development. The aides are called [http://msdn.microsoft.com/en-us/library/d21c150d.aspx Managed Debugging Assistants (MDAs)]. You can find the MDAs on the ''Debug'' menu, then ''Exceptions'' submenu. MDAs allow you to tune your debugging experience by, for example, filter exceptions for which the debugger should snap. For more details, see Stephen Toub's ''[http://msdn.microsoft.com/en-us/magazine/cc163606.aspx Let The CLR Find Bugs For You With Managed Debugging Assistants]''.

{| align="center"
| [[File:toolchan-hardening-2.png|thumb|450px|Figure 3: Managed Debugging Assistants]]
|}

Finally, for runtime hardening, Microsoft has a helpful tool called EMET. EMET is the [http://support.microsoft.com/kb/2458544 Enhanced Mitigation Experience Toolkit], and allows you to apply runtime hardening to an executable which was built without. Its very useful for utilities and other programs that were built without an SDLC.

{| align="center"
| [[File:toolchan-hardening-3.png|thumb|450px|Figure 4: Windows and EMET]]
|}

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

Baltimore

2013-05-26T22:28:51Z

Jeffrey Walton: Added meeting heading

The '''OWASP Baltimore Local Chapter''' meetings are FREE and OPEN to anyone interested in learning more about application security. We encourage individuals to provide knowledge transfer via hands-on training and presentations of specific OWASP projects and research topics and sharing SDLC knowledge.

We the encourage vendor-agnostic presentations to utilize the OWASP Powerpoint template when applicable and individual volunteerism to enable perpetual growth. As a 501(3)c non-profit association donations of meeting space or refreshments sponsorship is encouraged, simply contact the local chapter leaders listed on this page to discuss. Prior to participating with OWASP please review the Chapter Rules.

The chapter is committed to providing an engaging experience for a variety of audience types ranging from local students and those beginning in app-sec, to those experienced and accomplished professionals who are looking for competent collaborators for OWASP-related projects. To this end, we will continue to conduct both monthly chapter meetings as well as out-of-band curricula, on application security topics.

{{Chapter Template|chaptername=Baltimore|extra =Come see us at a chapter meeting, join the mailing list, or email us directly.

The chapter leaders are [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb]. Please feel free to email us. The chapter leaders and mailing list welcome your participation and thoughts.

OWASP Baltimore uses Meetup to schedule its meetings. Please see [http://www.meetup.com/OWASP-Baltimore-Chapter/ OWASP Baltimore Chapter] for more information and breaking news.

The group's mailing list is [http://lists.owasp.org/mailman/listinfo/owasp-baltimore OWASP Baltimore], and its archive can be found at [http://lists.owasp.org/pipermail/owasp-baltimore OWASP Baltimore Archives].|mailinglistsite=http://lists.owasp.org/mailman/listinfo/owasp-baltimore|emailarchives=http://lists.owasp.org/pipermail/owasp-baltimore OWASP Baltimore Archives}}

== Meetings ==

Meetings are held the first Thursday of each month. Announcements are made on the [http://lists.owasp.org/mailman/listinfo/owasp-baltimore OWASP Baltimore mailing list] and [http://www.meetup.com/OWASP-Baltimore-Chapter/ OWASP Baltimore Chapter Meetup]. Offline questions are answered by [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb].

== Local News ==

OWASP Baltimore is currently seeking corporate sponsors to host meetings. Please contact [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb] if you have resources available for OWASP.

We are also in a drive for membership. If you know someone with an interest in application security, be sure to pass on the chapter contacts! Everyone is welcome to join us at our chapter meetings.

[[Category:OWASP Chapter]]
[[Category:Maryland]]

Baltimore

2013-05-26T16:58:18Z

Jeffrey Walton: Still fiddling with bits

The '''OWASP Baltimore Local Chapter''' meetings are FREE and OPEN to anyone interested in learning more about application security. We encourage individuals to provide knowledge transfer via hands-on training and presentations of specific OWASP projects and research topics and sharing SDLC knowledge.

We the encourage vendor-agnostic presentations to utilize the OWASP Powerpoint template when applicable and individual volunteerism to enable perpetual growth. As a 501(3)c non-profit association donations of meeting space or refreshments sponsorship is encouraged, simply contact the local chapter leaders listed on this page to discuss. Prior to participating with OWASP please review the Chapter Rules.

The chapter is committed to providing an engaging experience for a variety of audience types ranging from local students and those beginning in app-sec, to those experienced and accomplished professionals who are looking for competent collaborators for OWASP-related projects. To this end, we will continue to conduct both monthly chapter meetings as well as out-of-band curricula, on application security topics.

{{Chapter Template|chaptername=Baltimore|extra =Come see us at a chapter meeting, join the mailing list, or email us directly.

The chapter leaders are [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb]. Please feel free to email us. The chapter leaders and mailing list welcome your participation and thoughts.

OWASP Baltimore uses Meetup to schedule its meetings. Please see [http://www.meetup.com/OWASP-Baltimore-Chapter/ OWASP Baltimore Chapter] for more information and breaking news.

The group's mailing list is [http://lists.owasp.org/mailman/listinfo/owasp-baltimore OWASP Baltimore], and its archive can be found at [http://lists.owasp.org/pipermail/owasp-baltimore OWASP Baltimore Archives].|mailinglistsite=http://lists.owasp.org/mailman/listinfo/owasp-baltimore|emailarchives=http://lists.owasp.org/pipermail/owasp-baltimore OWASP Baltimore Archives}}

== Local News ==

OWASP Baltimore is currently seeking corporate sponsors to host meetings. Please contact [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb] if you have resources available for OWASP.

We are also in a drive for membership. If you know someone with an interest in application security, be sure to pass on the chapter contacts! Everyone is welcome to join us at our chapter meetings.

[[Category:OWASP Chapter]]
[[Category:Maryland]]

Baltimore

2013-05-26T16:56:19Z

Jeffrey Walton: Fixed that Chapter Template (its a bit tricky!)

The '''OWASP Baltimore Local Chapter''' meetings are FREE and OPEN to anyone interested in learning more about application security. We encourage individuals to provide knowledge transfer via hands-on training and presentations of specific OWASP projects and research topics and sharing SDLC knowledge.

We the encourage vendor-agnostic presentations to utilize the OWASP Powerpoint template when applicable and individual volunteerism to enable perpetual growth. As a 501(3)c non-profit association donations of meeting space or refreshments sponsorship is encouraged, simply contact the local chapter leaders listed on this page to discuss. Prior to participating with OWASP please review the Chapter Rules.

The chapter is committed to providing an engaging experience for a variety of audience types ranging from local students and those beginning in app-sec, to those experienced and accomplished professionals who are looking for competent collaborators for OWASP-related projects. To this end, we will continue to conduct both monthly chapter meetings as well as out-of-band curricula, on application security topics.

{{Chapter Template|chaptername=Baltimore|extra =Come see us at a chapter meeting, join the mailing list, or email us directly.

The chapter leaders are [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb]. Please feel free to email us. The group's mailing list is [http://lists.owasp.org/mailman/listinfo/owasp-baltimore OWASP Baltimore], and its archive can be found at [http://lists.owasp.org/pipermail/owasp-baltimore OWASP Baltimore Archives]. The chapter leaders and mailing list welcome your participation and thoughts.

OWASP Baltimore uses Meetup to schedule its meetings. Please see [http://www.meetup.com/OWASP-Baltimore-Chapter/ OWASP Baltimore Chapter] for more information and breaking news.

|mailinglistsite=http://lists.owasp.org/mailman/listinfo/owasp-baltimore|emailarchives=http://lists.owasp.org/pipermail/owasp-baltimore OWASP Baltimore Archives}}

== Local News ==

OWASP Baltimore is currently seeking corporate sponsors to host meetings. Please contact [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb] if you have resources available for OWASP.

We are also in a drive for membership. If you know someone with an interest in application security, be sure to pass on the chapter contacts! Everyone is welcome to join us at our chapter meetings.

[[Category:OWASP Chapter]]
[[Category:Maryland]]

Baltimore

2013-05-26T16:53:08Z

Jeffrey Walton:

The '''OWASP Baltimore Local Chapter''' meetings are FREE and OPEN to anyone interested in learning more about application security. We encourage individuals to provide knowledge transfer via hands-on training and presentations of specific OWASP projects and research topics and sharing SDLC knowledge.

We the encourage vendor-agnostic presentations to utilize the OWASP Powerpoint template when applicable and individual volunteerism to enable perpetual growth. As a 501(3)c non-profit association donations of meeting space or refreshments sponsorship is encouraged, simply contact the local chapter leaders listed on this page to discuss. Prior to participating with OWASP please review the Chapter Rules.

The chapter is committed to providing an engaging experience for a variety of audience types ranging from local students and those beginning in app-sec, to those experienced and accomplished professionals who are looking for competent collaborators for OWASP-related projects. To this end, we will continue to conduct both monthly chapter meetings as well as out-of-band curricula, on application security topics.

{{Chapter Template|chaptername=Baltimore|extra =Come see us at a chapter meeting, join the mailing list, or email us directly.

== Communications and Contacts ==

The chapter leaders are [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb]. Please feel free to email us. The group's mailing list is [http://lists.owasp.org/mailman/listinfo/owasp-baltimore OWASP Baltimore], and its archive can be found at [http://lists.owasp.org/pipermail/owasp-baltimore OWASP Baltimore Archives]. The chapter leaders and mailing list welcome your participation and thoughts.

OWASP Baltimore uses Meetup to schedule its meetings. Please see [http://www.meetup.com/OWASP-Baltimore-Chapter/ OWASP Baltimore Chapter] for more information and breaking news.

== Local News ==

OWASP Baltimore is currently seeking corporate sponsors to host meetings. Please contact [mailto:rajiv.t.mathew@gmail.com Rajiv Mathew] and [mailto:lattera@gmail.com Shawn Webb] if you have resources available for OWASP.

We are also in a drive for membership. If you know someone with an interest in application security, be sure to pass on the chapter contacts! Everyone is welcome to join us at our chapter meetings.

[[Category:OWASP Chapter]]
[[Category:Maryland]]

File:Securing-Wireless-Channels-in-the-Mobile-Space.ppt

2013-05-05T13:41:32Z

Jeffrey Walton: uploaded a new version of "File:Securing-Wireless-Channels-in-the-Mobile-Space.ppt": Added slide for TLS-PSK and "Does it Work". The "Does it Work" slide features the Google Group posting by Alibo where he asked about Chrome complaining abou

Presentation of "Securing Wireless Channels in the Mobile Space" given in Northern Virginia on February 7, 2013.

File:Pubkey-pin-ios.zip

2013-05-03T17:46:14Z

Jeffrey Walton: uploaded a new version of "File:Pubkey-pin-ios.zip": Updated source code comments to include both certificate and public key pinning

iOS program code for "Securing Wireless Channels in the Mobile Space" presentation (Northern Virginia, 2013-02-07)

Certificate and Public Key Pinning

2013-05-03T02:26:54Z

Jeffrey Walton: Cleaned up PSK

[[Certificate and Public Key Pinning]] is a technical guide to implementing certificate and public key pinning as discussed at the ''[https://www.owasp.org/index.php/Virginia Virginia chapter's]'' presentation [[Media:Securing-Wireless-Channels-in-the-Mobile-Space.ppt|Securing Wireless Channels in the Mobile Space]]. This guide is focused on providing clear, simple, actionable guidance for securing the channel in a hostile environment where actors could be malicious and the conference of trust a liability. Additional presentation material included [[Media:pubkey-pin-supplement.pdf|supplement with code excerpts]], [[Media:pubkey-pin-android.zip|Android sample program]], [[Media:pubkey-pin-ios.zip|iOS sample program]], [[Media:pubkey-pin-dotnet.zip|.Net sample program]], and [[Media:pubkey-pin-openssl.zip|OpenSSL sample program]].

A cheat sheet is available at [[Pinning_Cheat_Sheet|Pinning Cheat Sheet]].

== Introduction ==

Secure channels are a cornerstone to users and employees working remotely and on the go. Users and developers expect end-to-end security when sending and receiving data - especially sensitive data on channels protected by VPN, SSL, or TLS. While organizations which control DNS and CA have likely reduced risk to trivial levels under most threat models, users and developers subjugated to other's DNS and a public CA hierarchy are exposed to non-trivial amounts of risk. In fact, history has shown those relying on outside services have suffered chronic breaches in their secure channels.

The pandemic abuse of trust has resulted in users, developers and applications making security related decisions on untrusted input. The situation is somewhat of a paradox: entities such as DNS and CAs are trusted and supposed to supply trusted input; yet their input cannot be trusted. Relying on untrusted input for security related decisions is not only bad karma, it violates a number of secure coding principals (see, for example, OWASP's [[Injection Theory]] and [[Data Validation]]).

Pinning effectively removes the "conference of trust". An application which pins a certificate or public key no longer needs to depend on others - such as DNS or CAs - when making security decisions relating to a peer's identity. For those familiar with SSH, you should realize that public key pinning nearly identical to SSH's <tt>StrictHostKeyChecking</tt> option. SSH had it right the entire time, and the rest of the world is beginning to realize the virtues of directly identifying a host or service by its public key.

Others who actively engage in pinning include Google and its browser Chrome. Chrome was successful in detecting the DigiNotar compromise which uncovered suspected interception by the Iranian government on its citizens. The initial report of the compromise can be found at ''[https://productforums.google.com/d/topic/gmail/3J3r2JqFNTw/discussion Is This MITM Attack to Gmail's SSL?]''; and Google Security's immediate response at ''[https://googleonlinesecurity.blogspot.com/2011/08/update-on-attempted-man-in-middle.html An update on attempted man-in-the-middle attacks]''.

== What's the problem? ==

Users, developers, and applications expect end-to-end security on their secure channels, but some secure channels are not meeting the expectation. Specifically, channels built using well known protocols such as VPN, SSL, and TLS can be vulnerable to a number of attacks.

Examples of past failures are listed on the discussion tab for this article. This cheat sheet does not attempt to catalogue the failures in the industry, investigate the design flaws in the scaffolding, justify the lack of accountability or liability with the providers, explain the race to the bottom in services, or demystify the collusion between, for example, Browsers and CAs. For additional reading, please visit ''[http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf PKI is Broken]'' and ''[http://blog.cryptographyengineering.com/2012/02/how-to-fix-internet.html The Internet is Broken]''.

=== Patient 0 ===

The original problem was the ''Key Distribution Problem''. Insecure communications can be transformed into a secure communication problem with encryption. Encrypted communications can be transformed into an identity problem with signatures. The identity problem terminates at the key distribution problem. They are the same problem.

=== The Cures ===

There are three cures for the key distribution problem. First is to have first hand knowledge of your partner or peer (i.e., a peer, server or service). This could be solved with SneakerNet. Unfortunately, SneakerNet does not scale and cannot be used to solve the key distribution problem.

The second is to rely on others, and it has two variants: (1) web of trust, and (2) hierarchy of trust. Web of Trust and Hierarchy of Trust solve the key distribution problem in a sterile environment. However, Web of Trust and Hierarchy of Trust each requires us to require us to rely on others - or '''confer trust'''. In practice, trusting others is showing to be problematic.

== What Is Pinning? ==

Pinning is the process of associating a host with their ''expected'' X509 certificate or public key. Once a certificate or public key is known or seen for a host, the certificate or public key is associated or 'pinned' to the host. If more than one certificate or public key is acceptable, then the program holds a ''pinset'' (taking from [https://developers.google.com/events/io/sessions/gooio2012/107/ Jon Larimer and Kenny Root Google I/O talk]). In this case, the advertised identity must match one of the elements in the pinset.

A host or service's certificate or public key can be added to an application at development time, or it can be added upon first encountering the certificate or public key. The former - adding at development time - is preferred since ''preloading'' the certificate or public key ''out of band'' usually means the attacker cannot taint the pin. If the certificate or public key is added upon first encounter, you will be using ''key continuity''. Key continuity can fail if the attacker has a privileged position during the first first encounter.

Pinning leverages knowledge of the pre-existing relationship between the user and an organization or service to help make better security related decisions. Because you already have information on the server or service, you don't need to rely on generalized mechanisms meant to solve the ''key distribution'' problem. That is, you don't need to turn to DNS for name/address mappings or CAs for bindings and status. Once exception is revocation and it is discussed below in [[#Pinning_Gaps|Pinning Gaps]].

It is also worth mention that Pinning is not Stapling. Stapling sends both the certificate and OCSP responder information in the same request to avoid the additional fetches the client should perform during path validations.

=== When Do You Pin? ===

You should pin anytime you want to be relatively certain of the remote host's identity or when operating in a hostile environment. Since one or both are almost always true, you should probably pin all the time.

A perfect case in point: during the two weeks or so of preparation for the presentation and cheat sheet, we've observed three relevant and related failures. First was [http://gaurangkp.wordpress.com/2013/01/09/nokia-https-mitm/ Nokia/Opera willfully breaking the secure channel]; second was [http://blog.malwarebytes.org/intelligence/2013/02/digital-certificates-and-malware-a-dangerous-mix/ DigiCert issuing a code signing certificate for malware]; and third was [http://krebsonsecurity.com/2013/02/security-firm-bit9-hacked-used-to-spread-malware/ Bit9's loss of its root signing key]. The environment is not only hostile, its toxic.

=== When Do You Whitelist? ===

If you are working for an organization which practices "egress filtering" as part of a Data Loss Prevention (DLP) strategy, you will likely encounter ''Interception Proxies''. I like to refer to these things as '''"good" bad guys''' (as opposed to '''"bad" bad guys''') since both break end-to-end security and we can't tell them apart. In this case, '''do not''' offer to whitelist the interception proxy since it defeats your security goals. Add the interception proxy's public key to your pinset after being '''instructed''' to do so by the folks in Risk Acceptance.

Note: if you whitelist a certificate or public key for a different host (for example, to accommodate an interception proxy), you are no longer pinning the expected certificates and keys for the host. Security and integrity on the channel could suffer, and it surely breaks end-to-end security expectations of users and organizations.

For more reading on interception proxies, the additional risk they bestow, and how they fail, see Dr. Matthew Green's ''[http://blog.cryptographyengineering.com/2012/03/how-do-interception-proxies-fail.html How do Interception Proxies fail?]'' and Jeff Jarmoc's BlackHat talk ''[https://www.blackhat.com/html/bh-eu-12/bh-eu-12-archives.html#jarmoc SSL/TLS Interception Proxies and Transitive Trust]''.

=== How Do You Pin? ===

The idea is to re-use the exiting protocols and infrastructure, but use them in a hardened manner. For re-use, a program would keep doing the things it used to do when establishing a secure connection.

To harden the channel, the program would would take advantage of the <tt>OnConnect</tt> callback offered by a library, framework or platform. In the callback, the program would verify the remote host's identity by validating its certificate or public key. While pinning does not have to occur in an <tt>OnConnect</tt> callback, its often most convenient because the underlying connection information is readily available.

== What Should Be Pinned? ==

The first thing to decide is what should be pinned. For this choice, you have two options: you can (1) pin the certificate; or (2) pin the public key. If you choose public keys, you have two additional choices: (a) pin the <tt>subjectPublicKeyInfo</tt>; or (b) pin one of the concrete types such as <tt>RSAPublicKey</tt> or <tt>DSAPublicKey</tt>.

The three choices are explained below in more detail. I would encourage you to pin the <tt>subjectPublicKeyInfo</tt> because it has the public parameters (such as <tt>{e,n}</tt> for an RSA public key) '''and''' contextual information such as an algorithm and OID. The context will help you keep your bearings at times, and Figure 1 below shows the additional information available.

=== Encodings/Formats ===

For the purposes of this article, the objects are in X509-compatible presentation format (PKCS#1 defers to X509, both of which use ASN.1). If you have a PEM encoded object (for example, <tt>-----BEGIN CERTIFICATE-----</tt>, <tt>-----END CERTIFICATE-----</tt>), then convert the object to DER encoding. Conversion using OpenSSL is offered below in [[#Format_Conversions|Format Conversions]].

A certificate is an object which binds an entity (such as a person or organization) to a public key via a signature. The certificate is DER encoded, and has associated data or attributes such as ''Subject'' (who is identified or bound), ''Issuer'' (who signed it), ''Validity'' (''NotBefore'' and ''NotAfter''), and a ''Public Key''.

A certificate has a ''subjectPublicKeyInfo''. The subjectPublicKeyInfo is a key with additional information. The ASN.1 type includes an ''Algorithm ID'', a ''Version'', and an extensible format to hold a concrete public key. Figures 1 and 2 below show different views of the same of a RSA key, which is the subjectPublicKeyInfo. The key is for the site [https://www.random.org random.org], and it is used in the sample programs and listings below.

{| align="center"
| [[File:random-org-der-dump.png|thumb|375px|Figure 1: subjectPublicKeyInfo dumped with dumpans1]]
| [[File:random-org-der-hex.png|thumb|375px|Figure 2: subjectPublicKeyInfo under a hex editor]]
|}

The concrete public key is an encoded public key. The key format will usually be specified elsewhere - for example, PKCS#1 in the case of RSA Public Keys. In the case of an RSA public key, the type is ''RSAPublicKey'' and the parameters <tt>{e,n}</tt> will be ASN.1 encoded. Figures 1 and 2 above clearly show the modulus (''n'' at line 28) and exponent (''e'' at line 289). For DSA, the concrete type is DSAPublicKey and the ASN.1 encoded parameters would be <tt>{p,q,g,y}</tt>.

Final takeaways: (1) a certificate binds an entity to a public key; (2) a certificate has a subjectPublicKeyInfo; and (3) a subjectPublicKeyInfo has an concrete public key. For those who want to learn more, a more in-depth discussion from a programmer's perspective can be found at the Code Project's article ''[http://www.codeproject.com/Articles/25487/Cryptographic-Interoperability-Keys Cryptographic Interoperability: Keys]''.

=== Certificate ===

[[File:pin-cert.png|thumb|right|100px|Certificate]] The certificate is easiest to pin. You can fetch the certificate out of band for the website, have the IT folks email your company certificate to you, use <tt>openssl s_client</tt> to retrieve the certificate etc. When the certificate expires, you would update your application. Assuming your application has no bugs or security defects, the application would be updated every year or two.

At runtime, you retrieve the website or server's certificate in the callback. Within the callback, you compare the retrieved certificate with the certificate embedded within the program. If the comparison fails, then fail the method or function.

There is a downside to pinning a certificate. If the site rotates its certificate on a regular basis, then your application would need to be updated regularly. For example, Google rotates its certificates, so you will need to update your application about once a month (if it depended on Google services). Even though Google rotates its certificates, the underlying public keys (within the certificate) remain static.

=== Public Key ===

[[File:pin-pubkey.png|thumb|right|100px|Public Key]] Public key pinning is more flexible but a little trickier due to the extra steps necessary to extract the public key from a certificate. As with a certificate, the program checks the extracted public key with its embedded copy of the public key.

There are two downsides two public key pinning. First, its harder to work with keys (versus certificates) since you usually must extract the key from the certificate. Extraction is a minor inconvenience in Java and .Net, buts its uncomfortable in Cocoa/CocoaTouch and OpenSSL. Second, the key is static and may violate key rotation policies.

=== Hashing ===

While the three choices above used DER encoding, its also acceptable to use a hash of the information (or other transforms). In fact, the original sample programs were written using digested certificates and public keys. The samples were changed to allow a programmer to inspect the objects with tools like <tt>dumpasn1</tt> and other ASN.1 decoders.

Hashing also provides three additional benefits. First, hashing allows you to anonymize a certificate or public key. This might be important if you application is concerned about leaking information during decompilation and re-engineering.

Second, a digested certificate fingerprint is often available as a native API for many libraries, so its convenient to use.

Finally, an organization might want to supply a reserve (or back-up) identity in case the primary identity is compromised. Hashing ensures your adversaries do not see the reserved certificate or public key in advance of its use. In fact, Google's IETF draft ''websec-key-pinning'' uses the technique.

== What About X509? ==

PKI{X} and the Internet form an intersection. What Internet users expect and what they receive from CAs could vary wildly. For example, an Internet user has security goals, while a CA has revenue goals and legal goals. Many are surprised to learn that the user is often required to perform host identity verification even though the CA issued the certificate (the details are buried in CA warranties on their certificates and their Certification Practice Statement (CPS)).

There are a number of PKI profiles available. For the Internet, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL)", also known as [http://tools.ietf.org/rfc/rfc5280.txt RFC 5280], is of interest. Since a certificate is specified in the ITU's X509 standard, there are lots of mandatory and optional fields available for validation from both bodies. Because of the disjoint goals among groups, the next section provides guidance.

=== Mandatory Checks ===

All X509 verifications must include:

* A path validation check. The check verifies all the signatures on certificates in the chain are valid under a given PKI. The check begins at the server or service's certificate (the leaf), and proceeds back to a trusted root certificate (the root).

* A validity check, or the <tt>notBefore</tt> and <tt>notAfter</tt> fields. The <tt>notAfter</tt> field is especially important since a CA will not warrant the certificate after the date, and it does not have to provide CRL/OCSP updates after the date.

* Revocation status. As with <tt>notAfter</tt>, revocation is important because the CA will not warrant a certificate once it is listed as revoked. The IETF approved way of checking a certificate's revocation is OCSP and specified in [http://tools.ietf.org/rfc/rfc2560.txt RFC 2560].

=== Optional Checks ===

<nowiki>[Mulling over what else to present, and the best way to present it. Subject name? DNS lookups? Key Usage? Algorithms? Geolocation based on IP? Check back soon.]</nowiki>

=== Public Key Checks ===

''Quod vide'' (''q.v.''). Verifying the identity of a host with knowledge of its associated/expected public key is pinning.

== Examples of Pinning ==

This section demonstrates certificate and public key pinning in Android Java, iOS, .Net, and OpenSSL. All programs attempt to connect to [https://www.random.org random.org] and fetch bytes (Dr. Mads Haahr participates in AOSP's pinning program, so the site should have a static key). The programs enjoy a pre-existing relationship with the site (more correctly, ''a priori'' knowledge), so they include a copy of the site's public key and pin the identity on the key.

Parameter validation, return value checking, and error checking have been omitted in the code below, but is present in the sample programs. So the sample code is ready for copy/paste. By far, the most uncomfortable languages are C-based: iOS and OpenSSL.

=== Android ===

Pinning in Android is accomplished through a custom <tt>X509TrustManager</tt>. <tt>X509TrustManager</tt> should perform the customary X509 checks in addition to performing the pin.

Download: [[Media:pubkey-pin-android.zip|Android sample program]]

<pre>public final class PubKeyManager implements X509TrustManager
{
private static String PUB_KEY = "30820122300d06092a864886f70d0101" +
"0105000382010f003082010a0282010100b35ea8adaf4cb6db86068a836f3c85" +
"5a545b1f0cc8afb19e38213bac4d55c3f2f19df6dee82ead67f70a990131b6bc" +
"ac1a9116acc883862f00593199df19ce027c8eaaae8e3121f7f329219464e657" +
"2cbf66e8e229eac2992dd795c4f23df0fe72b6ceef457eba0b9029619e0395b8" +
"609851849dd6214589a2ceba4f7a7dcceb7ab2a6b60c27c69317bd7ab2135f50" +
"c6317e5dbfb9d1e55936e4109b7b911450c746fe0d5d07165b6b23ada7700b00" +
"33238c858ad179a82459c4718019c111b4ef7be53e5972e06ca68a112406da38" +
"cf60d2f4fda4d1cd52f1da9fd6104d91a34455cd7b328b02525320a35253147b" +
"e0b7a5bc860966dc84f10d723ce7eed5430203010001";

public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException
{
if (chain == null) {
throw new IllegalArgumentException("checkServerTrusted: X509Certificate array is null");
}

if (!(chain.length > 0)) {
throw new IllegalArgumentException("checkServerTrusted: X509Certificate is empty");
}

if (!(null != authType && authType.equalsIgnoreCase("RSA"))) {
throw new CertificateException("checkServerTrusted: AuthType is not RSA");
}

// Perform customary SSL/TLS checks
try {
TrustManagerFactory tmf = TrustManagerFactory.getInstance("X509");
tmf.init((KeyStore) null);

for (TrustManager trustManager : tmf.getTrustManagers()) {
((X509TrustManager) trustManager).checkServerTrusted(chain, authType);
}
} catch (Exception e) {
throw new CertificateException(e);
}

// Hack ahead: BigInteger and toString(). We know a DER encoded Public Key begins
// with 0x30 (ASN.1 SEQUENCE and CONSTRUCTED), so there is no leading 0x00 to drop.
RSAPublicKey pubkey = (RSAPublicKey) chain[0].getPublicKey();
String encoded = new BigInteger(1 /* positive */, pubkey.getEncoded()).toString(16);

// Pin it!
final boolean expected = PUB_KEY.equalsIgnoreCase(encoded);
if (!expected) {
throw new CertificateException("checkServerTrusted: Expected public key: "
+ PUB_KEY + ", got public key:" + encoded);
}
}
}
}</pre>

<tt>PubKeyManager</tt> would be used in code similar to below.

<pre>TrustManager tm[] = { new PubKeyManager() };

SSLContext context = SSLContext.getInstance("TLS");
context.init(null, tm, null);

URL url = new URL( "https://www.random.org/integers/?" +
"num=16&min=0&max=255&col=16&base=10&format=plain&rnd=new");

HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
connection.setSSLSocketFactory(context.getSocketFactory());

InputStreamReader instream = new InputStreamReader(connection.getInputStream());
StreamTokenizer tokenizer = new StreamTokenizer(instream);
...</pre>

=== iOS ===

iOS pinning is performed through a <tt>NSURLConnectionDelegate</tt>. The delegate must implement <tt>connection:canAuthenticateAgainstProtectionSpace:</tt> and <tt>connection:didReceiveAuthenticationChallenge:</tt>. Within <tt>connection:didReceiveAuthenticationChallenge:</tt>, the delegate must call <tt>SecTrustEvaluate</tt> to perform customary X509 checks.

Download: [[Media:pubkey-pin-ios.zip|iOS sample program]].

<pre>-(IBAction)fetchButtonTapped:(id)sender
{
NSString* requestString = @"https://www.random.org/integers/?
num=16&min=0&max=255&col=16&base=16&format=plain&rnd=new";
NSURL* requestUrl = [NSURL URLWithString:requestString];

NSURLRequest* request = [NSURLRequest requestWithURL:requestUrl
cachePolicy:NSURLRequestReloadIgnoringLocalCacheData
timeoutInterval:10.0f];

NSURLConnection* connection = [[NSURLConnection alloc] initWithRequest:request delegate:self];
}

-(BOOL)connection:(NSURLConnection *)connection canAuthenticateAgainstProtectionSpace:
(NSURLProtectionSpace*)space
{
return [[space authenticationMethod] isEqualToString: NSURLAuthenticationMethodServerTrust];
}

- (void)connection:(NSURLConnection *)connection didReceiveAuthenticationChallenge:
(NSURLAuthenticationChallenge *)challenge
{
if ([[[challenge protectionSpace] authenticationMethod] isEqualToString: NSURLAuthenticationMethodServerTrust])
{
do
{
SecTrustRef serverTrust = [[challenge protectionSpace] serverTrust];
if(nil == serverTrust)
break; /* failed */

OSStatus status = SecTrustEvaluate(serverTrust, NULL);
if(!(errSecSuccess == status))
break; /* failed */

SecCertificateRef serverCertificate = SecTrustGetCertificateAtIndex(serverTrust, 0);
if(nil == serverCertificate)
break; /* failed */

CFDataRef serverCertificateData = SecCertificateCopyData(serverCertificate);
[(id)serverCertificateData autorelease];
if(nil == serverCertificateData)
break; /* failed */

const UInt8* const data = CFDataGetBytePtr(serverCertificateData);
const CFIndex size = CFDataGetLength(serverCertificateData);
NSData* cert1 = [NSData dataWithBytes:data length:(NSUInteger)size];

NSString *file = [[NSBundle mainBundle] pathForResource:@"random-org" ofType:@"der"];
NSData* cert2 = [NSData dataWithContentsOfFile:file];

if(nil == cert1 || nil == cert2)
break; /* failed */

const BOOL equal = [cert1 isEqualToData:cert2];
if(!equal)
break; /* failed */

// The only good exit point
return [[challenge sender] useCredential: [NSURLCredential credentialForTrust: serverTrust]
forAuthenticationChallenge: challenge];
} while(0);

// Bad dog
return [[challenge sender] cancelAuthenticationChallenge: challenge];
}</pre>

=== .Net ===

.Net pinning can be achieved by using <tt>ServicePointManager</tt> as shown below.

Download: [[Media:pubkey-pin-dotnet.zip|.Net sample program]].

<pre>// Encoded RSAPublicKey
private static String PUB_KEY = "30818902818100C4A06B7B52F8D17DC1CCB47362" +
"C64AB799AAE19E245A7559E9CEEC7D8AA4DF07CB0B21FDFD763C63A313A668FE9D764E" +
"D913C51A676788DB62AF624F422C2F112C1316922AA5D37823CD9F43D1FC54513D14B2" +
"9E36991F08A042C42EAAEEE5FE8E2CB10167174A359CEBF6FACC2C9CA933AD403137EE" +
"2C3F4CBED9460129C72B0203010001";

public static void Main(string[] args)
{
ServicePointManager.ServerCertificateValidationCallback = PinPublicKey;
WebRequest wr = WebRequest.Create("https://encrypted.google.com/");
wr.GetResponse();
}

public static bool PinPublicKey(object sender, X509Certificate certificate, X509Chain chain,
SslPolicyErrors sslPolicyErrors)
{
if (null == certificate)
return false;

String pk = certificate.GetPublicKeyString();
if (pk.Equals(PUB_KEY))
return true;

// Bad dog
return false;
}</pre>

=== OpenSSL ===

Pinning can occur at one of two places with OpenSSL. First is the user supplied <tt>verify_callback</tt>. Second is after the connection is established via <tt>SSL_get_peer_certificate</tt>. Either method will allow you to access the peer's certificate.

Though OpenSSL performs the X509 checks, you must fail the connection and tear down the socket on error. By design, a server that does not supply a certificate will result in <tt>X509_V_OK</tt> with a '''NULL''' certificate. To check the result of the customary verification: (1) you must call <tt>SSL_get_verify_result</tt> and verify the return code is <tt>X509_V_OK</tt>; and (2) you must call <tt>SSL_get_peer_certificate</tt> and verify the certificate is '''non-NULL'''.

Download: [[Media:pubkey-pin-openssl.zip|OpenSSL sample program]].

<pre>int pkp_pin_peer_pubkey(SSL* ssl)
{
if(NULL == ssl) return FALSE;

X509* cert = NULL;
FILE* fp = NULL;

/* Scratch */
int len1 = 0, len2 = 0;
unsigned char *buff1 = NULL, *buff2 = NULL;

/* Result is returned to caller */
int ret = 0, result = FALSE;

do
{
/* http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html */
cert = SSL_get_peer_certificate(ssl);
if(!(cert != NULL))
break; /* failed */

/* Begin Gyrations to get the subjectPublicKeyInfo */
/* Thanks to Viktor Dukhovni on the OpenSSL mailing list */

/* http://groups.google.com/group/mailing.openssl.users/browse_thread/thread/d61858dae102c6c7 */
len1 = i2d_X509_PUBKEY(X509_get_X509_PUBKEY(cert), NULL);
if(!(len1 > 0))
break; /* failed */

/* scratch */
unsigned char* temp = NULL;

/* http://www.openssl.org/docs/crypto/buffer.html */
buff1 = temp = OPENSSL_malloc(len1);
if(!(buff1 != NULL))
break; /* failed */

/* http://www.openssl.org/docs/crypto/d2i_X509.html */
len2 = i2d_X509_PUBKEY(X509_get_X509_PUBKEY(cert), &temp);

/* These checks are verifying we got back the same values as when we sized the buffer. */
/* Its pretty weak since they should always be the same. But it gives us something to test. */
if(!((len1 == len2) && (temp != NULL) && ((temp - buff1) == len1)))
break; /* failed */

/* End Gyrations */

/* See the warning above!!! */
/* http://pubs.opengroup.org/onlinepubs/009696699/functions/fopen.html */
fp = fopen("random-org.der", "rx");
if(NULL ==fp) {
fp = fopen("random-org.der", "r");

if(!(NULL != fp))
break; /* failed */

/* Seek to eof to determine the file's size */
/* http://pubs.opengroup.org/onlinepubs/009696699/functions/fseek.html */
ret = fseek(fp, 0, SEEK_END);
if(!(0 == ret))
break; /* failed */

/* Fetch the file's size */
/* http://pubs.opengroup.org/onlinepubs/009696699/functions/ftell.html */
long size = ftell(fp);

/* Arbitrary size, but should be relatively small (less than 1K or 2K) */
if(!(size != -1 && size > 0 && size < 2048))
break; /* failed */

/* Rewind to beginning to perform the read */
/* http://pubs.opengroup.org/onlinepubs/009696699/functions/fseek.html */
ret = fseek(fp, 0, SEEK_SET);
if(!(0 == ret))
break; /* failed */

/* Re-use buff2 and len2 */
buff2 = NULL; len2 = (int)size;

/* http://www.openssl.org/docs/crypto/buffer.html */
buff2 = OPENSSL_malloc(len2);
if(!(buff2 != NULL))
break; /* failed */

/* http://pubs.opengroup.org/onlinepubs/009696699/functions/fread.html */
/* Returns number of elements read, which should be 1 */
ret = (int)fread(buff2, (size_t)len2, 1, fp);
if(!(ret == 1))
break; /* failed */

/* Re-use size. MIN and MAX macro below... */
size = len1 < len2 ? len1 : len2;

/*************************/
/***** PAYDIRT *****/
/*************************/
if(len1 != (int)size || len2 != (int)size || 0 != memcmp(buff1, buff2, (size_t)size))
break; /* failed */

/* The one good exit point */
result = TRUE;

} while(0);

if(fp != NULL)
fclose(fp);

/* http://www.openssl.org/docs/crypto/buffer.html */
if(NULL != buff2)
OPENSSL_free(buff2);

/* http://www.openssl.org/docs/crypto/buffer.html */
if(NULL != buff1)
OPENSSL_free(buff1);

/* http://www.openssl.org/docs/crypto/X509_new.html */
if(NULL != cert)
X509_free(cert);

return result;
}</pre>

== Pinning Alternatives ==

Not all applications use split key cryptography. Fortunately, there are protocols which allow you to set up a secure channel based on knowledge of passwords and pre-shared secrets (rather than putting the secret on the wire in a basic authentication scheme). Two are listed below - SRP and PSK. SRP and PSK have [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 88 cipher suites assigned to them by IANA for TLS], so there's no shortage of choices.

{| align="center"
| [[File:pin-iana-assigned.png|thumb|450px|Figure 3: IANA reserved cipher suites for SRP and PSK]]
|}

=== SRP ===

Secure Remote Password (SRP) is a Password Authenticated Key Exchange (PAKE) by Thomas Wu based upon Diffie-Hellman. The protocol is standardized in [https://tools.ietf.org/rfc/rfc5054.txt RFC 5054] and available in the OpenSSL library (among others). In the SRP scheme, the server uses a verifier which consists of a <tt>{salt, hash(password)}</tt> pair. The user has the password and receives the salt from the server. With lots of hand waiving, both parties select per-instance random values (nonces) and execute the protocol using ''g{(salt + password)|verifier} + nonces'' rather than traditional Diffie-Hellman using ''gab''.

[[File:homer-p-np.jpg|thumb|right|150px|P=NP!!!]]Diffie-Hellman based schemes are part of a family of problems based on Discrete Logs (DL), which are logarithms over a finite field. DL schemes are appealing because they are known to be hard (unless ''P=NP'', which would cause computational number theorists to have a cow).

=== PSK ===

PSK is Pre-Shared Key and specified in [https://tools.ietf.org/rfc/rfc4279.txt RFC 4279] and [https://tools.ietf.org/rfc/rfc4764.txt RFC 4764]. The shared secret is used as a pre-master secret in TLS-PSK for SSL/TLS; or used to key a block cipher in EAP-PSK. EAP-PSK is designed for authentication over insecure networks such as IEEE 802.11.

== Miscellaneous ==

This sections covers administrivia and miscellaneous items related to pinning.

=== Ephemeral Keys ===

Ephemeral keys are temporary keys used for one instance of a protocol execution and then thrown away. An ephemeral key has the benefit of providing forward secrecy, meaning a compromise of the site or service's long term (static) signing key does not facilitate decrypting past messages because the key was temporary and discarded (once the session terminated).

Ephemeral keys do not affect pinning because the Ephemeral key is delivered in a separate <tt>ServerKeyExchange</tt> message. In addition, the ephemeral key is a key and not a certificate, so it does not change the construction of the certificate chain. That is, the certificate of interest will still be located at <tt>certificates[0]</tt>.

=== Pinning Gaps ===

There are two gaps when pinning due to reuse of the existing infrastructure and protocols. First, an explicit challenge is '''not''' sent by the program to the peer server based on the server's public information. So the program never knows if the peer can actually decrypt messages. However, the shortcoming is usually academic in practice since an adversary will receive messages it can't decrypt.

Second is revocation. Clients don't usually engage in revocation checking, so it could be possible to use a known bad certificate or key in a pinset. Even if revocation is active, Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) can be defeated in a hostile environment. An application can take steps to remediate, with the primary means being freshness. That is, an application should be updated and distributed immediately when a critical security parameter changes.

=== No Relationship ^@$! ===

If you don't have a pre-existing relationship, all is not lost. First, you can pin a host or server's certificate or public key the first time you encounter it. If the bad guy was not active when you encountered the certificate or public key, he or she will not be successful with future funny business.

Second, bad certificates are being spotted quicker in the field due to projects like [http://www.chromium.org Chromium] and [https://addons.mozilla.org/en-us/firefox/addon/certificate-patrol/ Certificate Patrol], and initiatives like the EFF's [https://www.eff.org/observatory SSL Observatory].

Third, help is on its way, and there are a number of futures that will assist with the endeavors:

* Public Key Pinning (http://www.ietf.org/id/draft-ietf-websec-key-pinning-04.txt) – an extension to the HTTP protocol allowing web host operators to instruct user agents (UAs) to remember ("pin") the hosts' cryptographic identities for a given period of time.
* DNS-based Authentication of Named Entities (DANE) (https://datatracker.ietf.org/doc/rfc6698/) - uses Secure DNS to associate Certificates with Domain Names For S/MIME, SMTP with TLS, DNSSEC and TLSA records.
* Sovereign Keys (http://www.eff.org/sovereign-keys) - operates by providing an optional and secure way of associating domain names with public keys via DNSSEC. PKI (hierarchical) is still used. Semi-centralized with append only logging.
* Convergence (http://convergence.io) – different [geographical] views of a site and its associated data (certificates and public keys). Web of Trust is used. Semi-centralized.

While Sovereign Keys and Convergence still require us to confer trust to outside parties, the parties involved do not serve share holders or covet revenue streams. Their interests are industry transparency and user security.

=== More Information? ===

Pinning is an ''old new thing'' that has been shaken, stirred, and repackaged. While "pinning" and "pinsets" are relatively new terms for old things, Jon Larimer and Kenny Root spent time on the subject at Google I/O 2012 with their talk ''[https://developers.google.com/events/io/sessions/gooio2012/107/ Security and Privacy in Android Apps]''.

=== Format Conversions ===

As a convenience to readers, the following with convert between PEM and DER format using OpenSSL.

<pre># Public key, X509
$ openssl genrsa -out rsa-openssl.pem 3072
$ openssl rsa -in rsa-openssl.pem -pubout -outform DER -out rsa-openssl.der</pre>

<pre># Private key, PKCS#8
$ openssl genrsa -out rsa-openssl.pem 3072
$ openssl pkcs8 -nocrypt -in rsa-openssl.pem -inform PEM -topk8 -outform DER -out rsa-openssl.der</pre>

== References ==

* OWASP [[Injection_Theory|Injection Theory]]
* OWASP [[Data_Validation|Data Validation]]
* OWASP [[Transport_Layer_Protection_Cheat_Sheet|Transport Layer Protection Cheat Sheet]]
* IETF [http://www.ietf.org/id/draft-ietf-websec-key-pinning-04.txt Public Key Pinning]
* IETF [http://www.ietf.org/rfc/rfc5054.txt RFC 5054 (SRP)]
* IETF [http://www.ietf.org/rfc/rfc4764.txt RFC 4764 (EAP-PSK)]
* IETF [http://www.ietf.org/rfc/rfc1421.txt RFC 1421 (PEM Encoding)]
* IETF [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 (Internet X.509, PKIX)]
* IETF [http://www.ietf.org/rfc/rfc4648.txt RFC 4648 (Base16, Base32, and Base64 Encodings)]
* IETF [http://www.ietf.org/rfc/rfc3279.txt RFC 3279 (PKI, X509 Algorithms and CRL Profiles)]
* IETF [http://www.ietf.org/rfc/rfc4055.txt RFC 4055 (PKI, X509 Additional Algorithms and CRL Profiles)]
* IETF [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 (TLS 1.0)]
* IETF [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 (TLS 1.1)]
* IETF [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 (TLS 1.2)]
* IETF [http://www.ietf.org/rfc/rfc6698.txt RFC 6698, Draft (DANE)]
* EFF [http://www.eff.org/sovereign-keys Sovereign Keys]
* Thoughtcrime Labs [http://convergence.io/ Convergence]
* RSA Laboratories [http://www.rsa.com/rsalabs/node.asp?id=2125 PKCS#1, RSA Encryption Standard]
* RSA Laboratories [http://www.rsa.com/rsalabs/node.asp?id=2128 PKCS#6, Extended-Certificate Syntax Standard]
* ITU [http://www.itu.int/rec/T-REC-X.690-200811-I/en Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)]
* TOR Project [https://blog.torproject.org/blog/detecting-certificate-authority-compromises-and-web-browser-collusion Detecting Certificate Authority Compromises and Web Browser Collusion]
* Code Project [http://www.codeproject.com/Articles/25487/Cryptographic-Interoperability-Keys Cryptographic Interoperability: Keys]
* Google I/O [https://developers.google.com/events/io/sessions/gooio2012/107/ Security and Privacy in Android Apps]
* Trevor Perrin [https://crypto.stanford.edu/RealWorldCrypto/slides/perrin.pdf Transparency, Trust Agility, Pinning (Recent Developments in Server Authentication)]
* Dr. Peter Gutmann's [http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf PKI is Broken]
* Dr. Matthew Green's [http://blog.cryptographyengineering.com/2012/02/how-to-fix-internet.html The Internet is Broken]
* Dr. Matthew Green's [http://blog.cryptographyengineering.com/2012/03/how-do-interception-proxies-fail.html How do Interception Proxies fail?]

= Authors and Primary Editors =

* Jeffrey Walton - jeffrey, owasp.org
* JohnSteven - john, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

File:Securing-Wireless-Channels-in-the-Mobile-Space.ppt

2013-05-03T01:51:51Z

Jeffrey Walton: uploaded a new version of "File:Securing-Wireless-Channels-in-the-Mobile-Space.ppt": Updated slide deck. Used at Baltimore, MD OWASP meeting 02-MAY-2013.

Presentation of "Securing Wireless Channels in the Mobile Space" given in Northern Virginia on February 7, 2013.

File:Securing Wireless Channels in the Mobile Space.ppt

2013-05-03T01:49:42Z

Jeffrey Walton: Updated slide deck. Used at Baltimore, MD OWASP meeting 02-MAY-2013.

Updated slide deck. Used at Baltimore, MD OWASP meeting 02-MAY-2013.

File:Pubkey-pin-ios.zip

2013-05-03T01:47:17Z

Jeffrey Walton: uploaded a new version of "File:Pubkey-pin-ios.zip"

iOS program code for "Securing Wireless Channels in the Mobile Space" presentation (Northern Virginia, 2013-02-07)

Transport Layer Protection Cheat Sheet

2013-04-28T19:56:41Z

Jeffrey Walton: Added "shared secret or password"

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Support TLS-PSK and TLS-SRP for Mutual Authentication ===

When using a shared secret or password offer TLS-PSK (Pre-Shared Key) or TLS-SRP (Secure Remote Password), which are known as Password Authenticated Key Exchange (PAKEs). TLS-PSK and TLS-SRP properly bind the channel, which refers to the cryptographic binding between the outer tunnel and the inner authentication protocol. IANA currently reserves [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 79 PSK cipehr suites] and [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 9 SRP cipher suites].

Basic authentication places the user's password on the wire in the plain text after a server authenticates itself. Basic authentication only provides unilateral authentication. In contrast, both TLS-PSK and TLS-SRP provide mutual authentication, meaning each party proves it knows the password without placing the password on the wire in the plain text.

Finally, using a PAKE removes the need to trust an outside party, such as a Certification Authority (CA).

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Use Fully Qualified Names in Certificates ===

Use fully qualified names in the DNS name field, and do not use unqualifed names (e.g., 'www'), local names (e.g., 'localhost'), or private IP addresses (e.g., 192.168.1.1) in the DNS name field. Unqualifed names, local names, or private IP addresses violate the certificate specification.

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts. Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses in Certificates ===

Certificates should not use private addresses. RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [http://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-28T00:34:45Z

Jeffrey Walton: Added IAN infor on PSK and SRP

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Support TLS-PSK and TLS-SRP for Mutual Authentication ===

Use TLS-PSK (Pre-Shared Key) or TLS-SRP (Secure Remote Password), which are known as Password Authenticated Key Exchange (PAKEs). TLS-PSK and TLS-SRP properly bind the channel, which refers to the cryptographic binding between the outer tunnel and the inner authentication protocol. IANA currently reserves [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 79 PSK cipehr suites] and [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 9 SRP cipher suites].

Basic authentication places the user's password on the wire in the plain text after a server authenticates itself. Basic authentication only provides unilateral authentication. In contrast, both TLS-PSK and TLS-SRP provide mutual authentication, meaning each party proves it knows the password without placing the password on the wire in the plain text.

Finally, using a PAKE removes the need to trust an outside party, such as a Certification Authority (CA).

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Use Fully Qualified Names in Certificates ===

Use fully qualified names in the DNS name field, and do not use unqualifed names (e.g., 'www'), local names (e.g., 'localhost'), or private IP addresses (e.g., 192.168.1.1) in the DNS name field. Unqualifed names, local names, or private IP addresses violate the certificate specification.

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts. Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses in Certificates ===

Certificates should not use private addresses. RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [http://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-27T22:57:22Z

Jeffrey Walton: Password Based Authentication -> Mutual Authentication

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Support TLS-PSK and TLS-SRP for Mutual Authentication ===

Use TLS-PSK (Pre-Shared Key) or TLS-SRP (Secure Remote Password), which are known as Password Authenticated Key Exchange (PAKEs). TLS-PSK and TLS-SRP properly bind the channel, which refers to the cryptographic binding between the outer tunnel and the inner authentication protocol.

Basic authentication places the user's password on the wire in the plain text after a server authenticates itself. Basic authentication only provides unilateral authentication. In contrast, both TLS-PSK and TLS-SRP provide mutual authentication, meaning each party proves it knows the password without placing the password on the wire in the plain text.

Finally, using a PAKE removes the need to trust an outside party, such as a Certification Authority (CA).

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Use Fully Qualified Names in Certificates ===

Use fully qualified names in the DNS name field, and do not use unqualifed names (e.g., 'www'), local names (e.g., 'localhost'), or private IP addresses (e.g., 192.168.1.1) in the DNS name field. Unqualifed names, local names, or private IP addresses violate the certificate specification.

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts. Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses in Certificates ===

Certificates should not use private addresses. RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [http://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-27T22:56:24Z

Jeffrey Walton: Added "Rule - Support TLS-PSK and TLS-SRP for Password Based Authentication"

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Support TLS-PSK and TLS-SRP for Password Based Authentication ===

Use TLS-PSK (Pre-Shared Key) or TLS-SRP (Secure Remote Password), which are known as Password Authenticated Key Exchange (PAKEs). TLS-PSK and TLS-SRP properly bind the channel, which refers to the cryptographic binding between the outer tunnel and the inner authentication protocol.

Basic authentication places the user's password on the wire in the plain text after a server authenticates itself. Basic authentication only provides unilateral authentication. In contrast, both TLS-PSK and TLS-SRP provide mutual authentication, meaning each party proves it knows the password without placing the password on the wire in the plain text.

Finally, using a PAKE removes the need to trust an outside party, such as a Certification Authority (CA).

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Use Fully Qualified Names in Certificates ===

Use fully qualified names in the DNS name field, and do not use unqualifed names (e.g., 'www'), local names (e.g., 'localhost'), or private IP addresses (e.g., 192.168.1.1) in the DNS name field. Unqualifed names, local names, or private IP addresses violate the certificate specification.

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts. Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses in Certificates ===

Certificates should not use private addresses. RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [http://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-04T17:44:47Z

Jeffrey Walton: Added rule for "Use Fully Qualified Names in Certificates"

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Use Fully Qualified Names in Certificates ===

Use fully qualified names in the DNS name field, and do not use unqualifed names (e.g., 'www'), local names (e.g., 'localhost'), or private IP addresses (e.g., 192.168.1.1) in the DNS name field. Unqualifed names, local names, or private IP addresses violate the certificate specification.

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts. Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses in Certificates ===

Certificates should not use private addresses. RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [http://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-04T13:15:17Z

Jeffrey Walton: Wikified link to Gutmann's book

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts.

Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses ===

RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8. Certificates should not use private addresses.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [http://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-04T13:14:15Z

Jeffrey Walton: Added rule for "Do Not Use RFC 1918 Addresses"

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts.

Finally, wildcard certificates violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Do Not Use RFC 1918 Addresses ===

RFC 1918 is [http://tools.ietf.org/rfc/rfc1918.txt Address Allocation for Private Internets]. Private addresses are Internet Assigned Numbers Authority (IANA) reserved and include 192.168/16, 172.16/12, and 10/8. Certificates should not use private addresses.

Certificates issued with private addresses violate [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines]. In addition, Peter Gutmann writes in in [www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security]: "This one is particularly troublesome because, in combination with the router-compromise attacks... and ...OSCP-defeating measures, it allows an attacker to spoof any EV-certificate site."

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-04T12:59:43Z

Jeffrey Walton: Added rule for "Do Not Use Wildcard Certificates"

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

=== Rule - Do Not Use Wildcard Certificates ===

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

Statistics gathered by Qualys for [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts.

Finally, wildcard certificates violate the [https://www.cabforum.org/EV_Certificate_Guidelines.pdf EV Certificate Guidelines].

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-03T16:51:28Z

Jeffrey Walton: Improved flow

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected. Finally, statistics gather by Qualys for their [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey 2010] indicate wildcard certificates have a 4.4% share, so the practice is not standard for public facing hosts.

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Transport Layer Protection Cheat Sheet

2013-04-03T16:48:30Z

Jeffrey Walton: Added statistic on wildcard certifcate market share

= Introduction =

This article provides a simple model to follow when implementing transport layer protection for an application. Although the concept of SSL is known to many, the actual details and security specific decisions of implementation are often poorly understood and frequently result in insecure deployments. This article establishes clear rules which provide guidance on securely designing and configuring transport layer security for an application. This article is focused on the use of SSL/TLS between a web application and a web browser, but that we also encourage the use of SSL/TLS or other network encryption technologies, such as VPN, on back end and other non-browser based connections. 

== Architectural Decision ==

An architectural decision must be made to determine the appropriate method to protect data when it is being transmitted. The most common options available to corporations are Virtual Private Networks (VPN) or a SSL/TLS model commonly used by web applications. The selected model is determined by the business needs of the particular organization. For example, a VPN connection may be the best design for a partnership between two companies that includes mutual access to a shared server over a variety of protocols. Conversely, an Internet facing enterprise web application would likely be best served by a SSL/TLS model.

This cheat sheet will focus on security considerations when the SSL/TLS model is selected. This is a frequently used model for publicly accessible web applications.

= Providing Transport Layer Protection with SSL/TLS =

== Benefits ==

The primary benefit of transport layer security is the protection of web application data from unauthorized disclosure and modification when it is transmitted between clients (web browsers) and the web application server, and between the web application server and back end and other non-browser based enterprise components.

The server validation component of TLS provides authentication of the server to the client. If configured to require client side certificates, TLS can also play a role in client authentication to the server. However, in practice client side certificates are not often used in lieu of username and password based authentication models for clients.

TLS also provides two additional benefits that are commonly overlooked; integrity guarantees and replay prevention. A TLS stream of communication contains built-in controls to prevent tampering with any portion of the encrypted data. In addition, controls are also built-in to prevent a captured stream of TLS data from being replayed at a later time.

It should be noted that TLS provides the above guarantees to data during transmission. TLS does not offer any of these security benefits to data that is at rest. Therefore appropriate security controls must be added to protect data while at rest within the application or within data stores.

== Basic Requirements ==

The basic requirements for using TLS are: access to a Public Key Infrastructure (PKI) in order to obtain certificates, access to a directory or an Online Certificate Status Protocol (OCSP) responder in order to check certificate revocation status, and agreement/ability to support a minimum configuration of protocol versions and protocol options for each version.

== SSL vs. TLS ==

The terms, Secure Socket Layer (SSL) and Transport Layer Security (TLS) are often used interchangeably. In fact, SSL v3.1 is equivalent to TLS v1.0. However, different versions of SSL and TLS are supported by modern web browsers and by most modern web frameworks and platforms. For the purposes of this cheat sheet we will refer to the technology generically as TLS. Recommendations regarding the use of SSL and TLS protocols, as well as browser support for TLS, can be found in the rule below title [[Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols| "Only Support Strong Protocols"]].

[[Image:Asvs_cryptomodule.gif|thumb|350px|right|Cryptomodule Parts and Operation]]

== When to Use a FIPS 140-2 Validated Cryptomodule ==

If the web application may be the target of determined attackers (a common threat model for Internet accessible applications handling sensitive data), it is strongly advised to use TLS services that are provided by [http://csrc.nist.gov/groups/STM/cmvp/validation.html FIPS 140-2 validated cryptomodules].

A cryptomodule, whether it is a software library or a hardware device, basically consists of three parts:

* Components that implement cryptographic algorithms (symmetric and asymmetric algorithms, hash algorithms, random number generator algorithms, and message authentication code algorithms)
* Components that call and manage cryptographic functions (inputs and outputs include cryptographic keys and so-called critical security parameters)
* A physical container around the components that implement cryptographic algorithms and the components that call and manage cryptographic functions

The security of a cryptomodule and its services (and the web applications that call the cryptomodule) depend on the correct implementation and integration of each of these three parts. In addition, the cryptomodule must be used and accessed securely. The includes consideration for:

* Calling and managing cryptographic functions
* Securely Handling inputs and output
* Ensuring the secure construction of the physical container around the components

In order to leverage the benefits of TLS it is important to use a TLS service (e.g. library, web framework, web application server) which has been FIPS 140-2 validated. In addition, the cryptomodule must be installed, configured and operated in either an approved or an allowed mode to provide a high degree of certainty that the FIPS 140-2 validated cryptomodule is providing the expected security services in the expected manner.

If the system is legally required to use FIPS 140-2 encryption (e.g., owned or operated by or on behalf of the U.S. Government) then TLS must be used and SSL disabled. Details on why SSL is unacceptable are described in Section 7.1 of [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program].

Further reading on the use of TLS to protect highly sensitive data against determined attackers can be viewed in [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP800-52 Guidelines for the Selection and Use of Transport Layer Security (TLS) Implementations]

== Secure Server Design ==

=== Rule - Use TLS for All Login Pages and All Authenticated Pages ===

The login page and all subsequent authenticated pages must be exclusively accessed over TLS. The initial login page, referred to as the "login landing page", must be served over TLS. Failure to utilize TLS for the login landing page allows an attacker to modify the login form action, causing the user's credentials to be posted to an arbitrary location. Failure to utilize TLS for authenticated pages after the login enables an attacker to view the unencrypted session ID and compromise the user's authenticated session.

=== Rule - Use TLS on Any Networks (External and Internal) Transmitting Sensitive Data ===

All networks, both external and internal, which transmit sensitive data must utilize TLS or an equivalent transport layer security mechanism. It is not sufficient to claim that access to the internal network is "restricted to employees". Numerous recent data compromises have shown that the internal network can be breached by attackers. In these attacks, sniffers have been installed to access unencrypted sensitive data sent on the internal network.

=== Rule - Do Not Provide Non-TLS Pages for Secure Content ===

All pages which are available over TLS must not be available over a non-TLS connection. A user may inadvertently bookmark or manually type a URL to a HTTP page (e.g. http://example.com/myaccount) within the authenticated portion of the application. If this request is processed by the application then the response, and any sensitive data, would be returned to the user over the clear text HTTP.

=== Rule - REMOVED - Do Not Perform Redirects from Non-TLS Page to TLS Login Page ===

This recommendation has been removed. Ultimately, the below guidance will only provide user education and cannot provide any technical controls to protect the user against a man-in-the-middle attack.

--

A common practice is to redirect users that have requested a non-TLS version of the login page to the TLS version (e.g. http://example.com/login redirects to https://example.com/login). This practice creates an additional attack vector for a man in the middle attack. In addition, redirecting from non-TLS versions to the TLS version reinforces to the user that the practice of requesting the non-TLS page is acceptable and secure.

In this scenario, the man-in-the-middle attack is used by the attacker to intercept the non-TLS to TLS redirect message. The attacker then injects the HTML of the actual login page and changes the form to post over unencrypted HTTP. This allows the attacker to view the user's credentials as they are transmitted in the clear.

It is recommended to display a security warning message to the user whenever the non-TLS login page is requested. This security warning should urge the user to always type "HTTPS" into the browser or bookmark the secure login page. This approach will help educate users on the correct and most secure method of accessing the application.

Currently there are no controls that an application can enforce to entirely mitigate this risk. Ultimately, this issue is the responsibility of the user since the application cannot prevent the user from initially typing [http://owasp.org http://example.com/login] (versus HTTPS).

Note: [http://www.w3.org/Security/wiki/Strict_Transport_Security Strict Transport Security] will address this issue and will provide a server side control to instruct supporting browsers that the site should only be accessed over HTTPS

=== Rule - Do Not Mix TLS and Non-TLS Content ===

A page that is available over TLS must be comprised completely of content which is transmitted over TLS. The page must not contain any content that is transmitted over unencrypted HTTP. This includes content from unrelated third party sites.

An attacker could intercept any of the data transmitted over the unencrypted HTTP and inject malicious content into the user's page. This malicious content would be included in the page even if the overall page is served over TLS. In addition, an attacker could steal the user's session cookie that is transmitted with any non-TLS requests. This is possible if the cookie's 'secure' flag is not set. See the rule 'Use "Secure" Cookie Flag'

=== Rule - Use "Secure" Cookie Flag ===

The "Secure" flag must be set for all user cookies. Failure to use the "secure" flag enables an attacker to access the session cookie by tricking the user's browser into submitting a request to an unencrypted page on the site. This attack is possible even if the server is not configured to offer HTTP content since the attacker is monitoring the requests and does not care if the server responds with a 404 or doesn't respond at all.

=== Rule - Keep Sensitive Data Out of the URL ===

Sensitive data must not be transmitted via URL arguments. A more appropriate place is to store sensitive data in a server side repository or within the user's session. When using TLS the URL arguments and values are encrypted during transit. However, there are two methods that the URL arguments and values could be exposed.

1. The entire URL is cached within the local user's browser history. This may expose sensitive data to any other user of the workstation.

2. The entire URL is exposed if the user clicks on a link to another HTTPS site. This may expose sensitive data within the referral field to the third party site. This exposure occurs in most browsers and will only occur on transitions between two TLS sites.

For example, a user following a link on [http://owasp.org https://example.com] which leads to [http://owasp.org https://someOtherexample.com] would expose the full URL of [http://owasp.org https://example.com] (including URL arguments) in the referral header (within most browsers). This would not be the case if the user followed a link on [http://owasp.org https://example.com] to [http://owasp.org http://someHTTPexample.com]

=== Rule - Prevent Caching of Sensitive Data ===

The TLS protocol provides confidentiality only for data in transit but it does not help with potential data leakage issues at the client or intermediary proxies. As a result, it is frequently prudent to instruct these nodes not to cache or persist sensitive data. One option is to add a suitable Cache-Control header to relevant HTTP responses, for example "Cache-Control: no-cache, no store, must-revalidate". For compatibility with HTTP/1.0 the response should include header "Pragma: no-cache". More information is available in [http://www.ietf.org/rfc/rfc2616.txt HTTP 1.1 RFC 2616], section 14.9.

=== Rule - Use HTTP Strict Transport Security ===

A new browser security setting called HTTP Strict Transport Security (HSTS) will significantly enhance the implementation of TLS for a domain. HSTS is enabled via a special response header and this instructs [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security#Browser_Support compatible browsers] to enforce the following security controls:

* All requests to the domain will be sent over HTTPS
* Any attempts to send an HTTP requests to the domain will be automatically upgraded by the browser to HTTPS before the request is sent
* If a user encounters a bad SSL certificate, the user will receive an error message and will not be allowed to override the warning message

Additional information on HSTS can be found at [https://www.owasp.org/index.php/HTTP_Strict_Transport_Security https://www.owasp.org/index.php/HTTP_Strict_Transport_Security] and also on the OWASP [http://www.youtube.com/watch?v=zEV3HOuM_Vw&feature=youtube_gdata AppSecTutorial Series - Episode 4]

== Server Certificate and Protocol Configuration ==

Note: If using a FIPS 140-2 cryptomodule disregard the following rules and defer to the recommended configuration for the particular cryptomodule.

=== Rule - Use an Appropriate Certification Authority for the Application's User Base ===

An application user must never be presented with a warning that the certificate was signed by an unknown or untrusted authority. The application's user population must have access to the public certificate of the certification authority which issued the server's certificate. For Internet accessible websites, the most effective method of achieving this goal is to purchase the TLS certificate from a recognize certification authority. Popular Internet browsers already contain the public certificates of these recognized certification authorities.

Internal applications with a limited user population can use an internal certification authority provided its public certificate is securely distributed to all users. However, remember that all certificates issued by this certification authority will be trusted by the users. Therefore, utilize controls to protect the private key and ensure that only authorized individuals have the ability to sign certificates.

The use of self signed certificates is never acceptable. Self signed certificates negate the benefit of end-point authentication and also significantly decrease the ability for an individual to detect a man-in-the-middle attack.

=== Rule - Only Support Strong Protocols ===

SSL/TLS is a collection of protocols. Weaknesses have been identified with earlier SSL protocols, including [http://www.schneier.com/paper-ssl-revised.pdf SSLv2] and [http://www.yaksman.org/~lweith/ssl.pdf SSLv3]. The best practice for transport layer protection is to only provide support for the TLS protocols - TLS1.0, TLS 1.1 and TLS 1.2. This configuration will provide maximum protection against skilled and determined attackers and is appropriate for applications handling sensitive data or performing critical operations.

[http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers Nearly all modern browsers support at least TLS 1.0]. As of February 2013, contemporary browsers (Chrome v20+, IE v8+, Opera v10+, and Safari v5+) [http://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers support TLS 1.1 and TLS 1.2]. You should provide support for TLS 1.1 and TLS 1.2 to accommodate clients which support the protocols.

In situations where lesser security requirements are necessary, it may be acceptable to also provide support for SSL 3.0 and TLS 1.0. [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 has known weaknesses] which severely compromise the channel's security. TLS 1.0 suffers [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html CBC Chaining attacks and Padding Oracle attacks]. SSLv3 and TLSv1.0 should only be used only after risk analysis and acceptance.

Under no circumstances should SSLv2 be enabled as a protocol selection. The [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 protocol is broken] and does not provide adequate transport layer protection.

=== Rule - Only Support Strong Cryptographic Ciphers ===

Each protocol (SSLv3, TLSv1.0, etc) provide cipher suites. As of TLS 1.2, [http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3 there is support for over 300 suites (320+ and counting)], including [http://www.mail-archive.com/cryptography@randombit.net/msg03785.html national vanity cipher suites]. The strength of the encryption used within a TLS session is determined by the encryption cipher negotiated between the server and the browser. In order to ensure that only strong cryptographic ciphers are selected the server must be modified to disable the use of weak ciphers. It is recommended to configure the server to only support strong ciphers and to use sufficiently large key sizes. In general, the following should be observed when selecting CipherSuites:

* Use AES, 3-key 3DES for encryption operated in CBC mode
* Stream Ciphers which XOR the key stream with plaintext (such as AES/CTR mode)
* Use SHA1 or above for digests, prefer SHA2 (or equivalent)
* MD5 should not be used except as a PRF (no signing, no MACs)
* Do not provide support for NULL ciphersuites (aNULL or eNULL)
* Do not provide support for anonymous Diffie-Hellman
* Support ephemeral Diffie-Hellman key exchange

Note: The TLS usage of MD5 does not expose the TLS protocol to any of the weaknesses of the MD5 algorithm (see FIPS 140-2 IG). However, MD5 must never be used outside of TLS protocol (e.g. for general hashing).

Note: Use of Ephemeral Diffie-Hellman key exchange will protect confidentiality of the transmitted plaintext data even if the corresponding RSA or DSS server private key got compromised. An attacker would have to perform active man-in-the-middle attack at the time of the key exchange to be able to extract the transmitted plaintext. All modern browsers support this key exchange with the notable exception of Internet Explorer prior to Windows Vista.

Additional information can be obtained within the [http://www.ietf.org/rfc/rfc4346.txt TLS 1.1 RFC 4346] and [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf FIPS 140-2 IG]

=== Rule - Only Support Secure Renegotiations ===

A design weakness in TLS, identified as [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3555 CVE-2009-3555], allows an attacker to inject a plaintext of his choice into a TLS session of a victim. In the HTTPS context the attacker might be able to inject his own HTTP requests on behalf of the victim. The issue can be mitigated either by disabling support for TLS renegotiations or by supporting only renegotiations compliant with [http://www.ietf.org/rfc/rfc5746.txt RFC 5746]. All modern browsers have been updated to comply with this RFC.

=== Rule - Disable Compression ===

Compression Ratio Info-leak Made Easy (CRIME) is an exploit against the data compression scheme used by the TLS and SPDY protocols. The exploit allows an adversary to recover user authentication cookies from HTTPS. The recovered cookie can be subsequently used for session hijacking attacks.

=== Rule - Use Strong Keys & Protect Them ===

The private key used to generate the cipher key must be sufficiently strong for the anticipated lifetime of the private key and corresponding certificate. The current best practice is to select a key size of at least 2048. Keys of length 1024 will be obsolete beginning in 2010. Additional information on key lifetimes and comparable key strengths can be found in [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf NIST SP 800-57]. In addition, the private key must be stored in a location that is protected from unauthorized access.

=== Rule - Use a Certificate That Supports Required Domain Names ===

A user should never be presented with a certificate error, including prompts to reconcile domain or hostname mismatches, or expired certificates. If the application is available at both [https://owasp.org https://www.example.com] and [https://owasp.org https://example.com] then an appropriate certificate, or certificates, must be presented to accommodate the situation. The presence of certificate errors desensitizes users to TLS error messages and increases the possibility an attacker could launch a convincing phishing or man-in-the-middle attack.

For example, consider a web application accessible at [https://owasp.org https://abc.example.com] and [https://owasp.org https://xyz.example.com]. One certificate should be acquired for the host or server ''abc.example.com''; and a second certificate for host or server ''xyz.example.com''. In both cases, the hostname would be present in the Subject's Common Name (CN).

Alternatively, the Subject Alternate Names (SANs) can be used to provide a specific listing of multiple names where the certificate is valid. In the example above, the certificate could list the Subject's CN as ''example.com'', and list two SANs: ''abc.example.com'' and ''xyz.example.com''. These certificates are sometimes referred to as "multiple domain certificates".

You should refrain from using wildcard certificates. Though they are expedient at circumventing annoying user prompts, they also [[Least_privilege|violate the principal of least privilege]] and asks the user to trust all machines, including developer's machines, the secretary's machine in the lobby and the sign-in kiosk. Statistics gather by Qualsys for their [http://media.blackhat.com/bh-us-10/presentations/Ristic/BlackHat-USA-2010-Ristic-Qualys-SSL-Survey-HTTP-Rating-Guide-slides.pdf Internet SSL Survey] indicate wildcard certificates have a 4.4% share, so the practice is clearly not standard. Obtaining access to the private key is left as an exercise for the attacker, but its made much easier when stored on the file system unprotected.

=== Rule - Always Provide All Needed Certificates ===

Clients attempt to solve the problem of identifying a server or host using PKI and X509 certificate. When a user receives a server or host's certificate, the certificate must be validated back to a trusted root certification authority. This is known as path validation.

There can be one or more intermediate certificates in between the end-entity (server or host) certificate and root certificate. In addition to validating both endpoints, the user will also have to validate all intermediate certificates. Validating all intermediate certificates can be tricky because the user may not have them locally. This is a well-known PKI issue called the “Which Directory?" problem.

To avoid the “Which Directory?" problem, a server should provide the user with all required certificates used in a path validation.

== Client (Browser) Configuration ==

The validation procedures to ensure that a certificate is valid are complex and difficult to correctly perform. In a typical web application model, these checks will be performed by the client's web browser in accordance with local browser settings and are out of the control of the application. However, these items do need to be addressed in the following scenarios:

* The application server establishes connections to other applications over TLS for purposes such as web services or any exchange of data
* A thick client application is connecting to a server via TLS

In these situations extensive certificate validation checks must occur in order to establish the validity of the certificate. Consult the following resources to assist in the design and testing of this functionality. The NIST PKI testing site includes a full test suite of certificates and expected outcomes of the test cases.
* [http://csrc.nist.gov/groups/ST/crypto_apps_infra/pki/pkitesting.html NIST PKI Testing]
* [http://www.ietf.org/rfc/rfc5280.txt IETF RFC 5280]

As specified in the above guidance, if the certificate can not be validated for any reason then the connection between the client and server must be dropped. Any data exchanged over a connection where the certificate has not properly been validated could be exposed to unauthorized access or modification.

== Additional Controls ==

=== Extended Validation Certificates ===

Extended validation certificates (EV Certificates) proffer an enhanced investigation by the issuer into the requesting party due to the industry's race to the bottom. The purpose of EV certificates is to provide the user with greater assurance that the owner of the certificate is a verified legal entity for the site. Browsers with support for EV certificates distinguish an EV certificate in a variety of ways. Internet Explorer will color a portion of the URL in green, while Mozilla will add a green portion to the left of the URL indicating the company name.

High value websites should consider the use of EV certificates to enhance customer confidence in the certificate. It should also be noted that EV certificates do not provide any greater technical security for the TLS. The purpose of the EV certificate is to increase user confidence that the target site is indeed who it claims to be.

=== Client-Side Certificates ===

Client side certificates can be used with TLS to prove the identity of the client to the server. Referred to as "two-way TLS", this configuration requires the client to provide their certificate to the server, in addition to the server providing their's to the client. If client certificates are used, ensure that the same validation of the client certificate is performed by the server, as indicated for the validation of server certificates above. In addition, the server should be configured to drop the TLS connection if the client certificate cannot be verified or is not provided.

The use of client side certificates is relatively rare currently due to the complexities of certificate generation, safe distribution, client side configuration, certificate revocation and reissuance, and the fact that clients can only authenticate on machines where their client side certificate is installed. Such certificates are typically used for very high value connections that have small user populations.

=== Certificate and Public Key Pinning ===

Hybrid and native applications can take advantage of [[Certificate_and_Public_Key_Pinning|certificate and public key pinning]]. Pinning associates a host (for example, server) with an identity (for example, certificate or public key), and allows an application to leverage knowledge of the pre-existing relationship. At runtime, the application would inspect the certificate or public key received after connecting to the server. If the certificate or public key is expected, then the application would proceed as normal. If unexpected, the application would stop using the channel and close the connection since an adversary could control the channel or server.

Pinning still requires customary X509 checks, such as revocation, since CRLs and OCSP provides real time status information. Otherwise, an application could possibly (1) accept a known bad certificate; or (2) require an out-of-band update, which could result in a lengthy App Store approval.

Browser based applications are at a disadvantage since most browsers do not allow the user to leverage pre-existing relationships and ''a priori'' knowledge. In addition, Javascript and Websockets do not expose methods to for a web app to query the underlying secure connection information (such as the certificate or public key). It is noteworthy that Chromium based browsers perform pinning on selected sites, but the list is currently maintained by the vendor.

= Providing Transport Layer Protection for Back End and Other Connections =

Although not the focus of this cheat sheet, it should be stressed that transport layer protection is necessary for back-end connections and any other connection where sensitive data is exchanged or where user identity is established. Failure to implement an effective and robust transport layer security will expose sensitive data and undermine the effectiveness of any authentication or access control mechanism.

== Secure Internal Network Fallacy ==

The internal network of a corporation is not immune to attacks. Many recent high profile intrusions, where thousands of sensitive customer records were compromised, have been perpetrated by attackers that have gained internal network access and then used sniffers to capture unencrypted data as it traversed the internal network.

= Related Articles =

* OWASP – [[Testing for SSL-TLS (OWASP-CM-001)|Testing for SSL-TLS]], and OWASP [[Guide to Cryptography]]
* OWASP – [http://www.owasp.org/index.php/ASVS Application Security Verification Standard (ASVS) – Communication Security Verification Requirements (V10)]
* OWASP – ASVS Article on [[Why you need to use a FIPS 140-2 validated cryptomodule]]
* SSL Labs http://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide]
* yaSSL – [http://www.yassl.com/yaSSL/Blog/Entries/2010/10/7_Differences_between_SSL_and_TLS_Protocol_Versions.html Differences between SSL and TLS Protocol Versions]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf SP 800-52 Guidelines for the selection and use of transport layer security (TLS) Implementations]
* NIST – [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2 Security Requirements for Cryptographic Modules]
* NIST – [http://csrc.nist.gov/groups/STM/cmvp/documents/fips140-2/FIPS1402IG.pdf Implementation Guidance for FIPS PUB 140-2 and the Cryptographic Module Validation Program]
* NIST – [http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf SP 800-57 Recommendation for Key Management, Revision 2]
* NIST – [http://csrc.nist.gov/publications/drafts.html#sp800-95 SP 800-95 Guide to Secure Web Services]
* IETF – [http://www.ietf.org/rfc/rfc5280.txt RFC 5280 Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile]
* IETF – [http://www.ietf.org/rfc/rfc2246.txt RFC 2246 The Transport Layer Security (TLS) Protocol Version 1.0 (JAN 1999)]
* IETF – [http://www.ietf.org/rfc/rfc4346.txt RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 (APR 2006)]
* IETF – [http://www.ietf.org/rfc/rfc5246.txt RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 (AUG 2008)]

= Authors and Primary Editors =

Michael Coates - michael.coates[at]owasp.org 
Dave Wichers - dave.wichers[at]aspectsecurity.com 
Michael Boberski - boberski_michael[at]bah.com 
Tyler Reguly -treguly[at]sslfail.com

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening

2013-03-28T03:00:18Z

Jeffrey Walton:

[[C-Based Toolchain Hardening]] is a treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

This is a prescriptive article, and it will not debate semantics or speculate on behavior. Some information, such as the C/C++ committee's motivation and pedigree for [https://groups.google.com/a/isocpp.org/forum/?fromgroups=#!topic/std-discussion/ak8e1mzBhGs "program diagnostics", <tt>NDEBUG</tt>, <tt>assert</tt>, and <tt>abort()</tt>], appears to be lost like a tale in the Lord of the Rings. As such, the article will specify semantics (for example, the philosophy of 'debug' and 'release' build configurations), assign behaviors (for example, what an assert should do in a 'debug' and 'release' build configurations), and present a position. If you find the posture is too aggressive, then you should back off as required to suite your taste.

A secure toolchain is not a silver bullet. It is one piece of an overall strategy in the engineering process to help ensure success. It will compliment existing processes such as static analysis, dynamic analysis, secure coding, negative test suites, and the like. Tools such as Valgrind and Helgrind will still be needed. And a project will still require solid designs and architectures.

The OWASP [http://code.google.com/p/owasp-esapi-cplusplus/source ESAPI C++] project eats its own dog food. Many of the examples you will see in this article come directly from the ESAPI C++ project.

Finally, a [[Category:Cheat Sheet|cheat sheet]] is available for those who desire a terse treatment of the material. Please visit [[C-Based_Toolchain_Hardening_Cheat_Sheet|C-Based Toolchain Hardening Cheat Sheet]] for the abbreviated version.

== Wisdom ==

Code '''must''' be correct. It '''should''' be secure. It '''can''' be efficient.

[http://en.wikipedia.org/wiki/Jon_Bentley Dr. Jon Bentley]: ''"If it doesn't have to be correct, I can make it as fast as you'd like it to be"''.

[http://en.wikipedia.org/wiki/Gary_McGraw Dr. Gary McGraw]: ''"Thou shalt not rely solely on security features and functions to build secure software as security is an emergent property of the entire system and thus relies on building and integrating all parts properly"''.

== Configuration ==

Configuration is the first opportunity to configure your project for success. Not only do you have to configure your project to meet reliability and security goals, you must also configure integrated libraries properly. You typically have has three choices. First, you can use auto-configuration utilities if on Linux or Unix. Second, you can write a makefile by hand. This is predominant on Linux, Mac OS X, and Unix, but it applies to Windows as well. Finally, you can use an integrated development environment or IDE.

=== Build Configurations ===

At this stage in the process, you should concentrate on configuring for two builds: Debug and Release. Debug will be used for development and include full instrumentation. Release will be configured for production. The difference between the two settings is usually ''optimization level'' and ''debug level''. A third build configuration is Test, and its usually a special case of Release.

For debug and release builds, the settings are typically diametrically opposed. Debug configurations have no optimizations and full debug information; while Release builds have optimizations and minimal to moderate debug information. In addition, debug code has full assertions and additional library integration, such as mudflaps and malloc guards such as <tt>dmalloc</tt>.

The Test configuration is often a Release configuration that makes everything public for testing and builds a test harness. For example, all member functions public (C++ class) and all interfaces (library or shared object) should be made available for testing. Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

[http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8] introduced an optimization of <tt>-Og</tt>. Note that it is only an optimization, and still requires a customary debug level via <tt>-g</tt>.

==== Debug Builds ====

Debug builds are where developers spend most of their time when vetting problems, so this build should concentrate forces and tools or be a 'force multiplier'. Though many do not realize, debug code is more highly valued than release code because its adorned with additional instrumentation. The debug instrumentation will cause a program to become nearly "self-debugging", and help you catch mistakes such as bad parameters, failed API calls, and memory problems.

Self-debugging code reduces your time during trouble shooting and debugging. Reducing time under the debugger means you have more time for development and feature requests. If code is checked in without debug instrumentation, it should be fixed by adding instrumentation or rejected.

For GCC, optimizations and debug symbolication are controlled through two switches: <tt>-O</tt> and <tt>-g</tt>. You should use the following as part of your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for a minimal debug session:

<pre>-O0 -g3 -ggdb</pre>

<tt>-O0</tt> turns off optimizations and <tt>-g3</tt> ensures maximum debug information is available. You may need to use <tt>-O1</tt> so some analysis is performed. Otherwise, your debug build will be missing a number of warnings not present in release builds. <tt>-g3</tt> ensures maximum debugging information is available for the debug session, including symbolic constants and <tt>#defines</tt>. <tt>-ggdb</tt> includes extensions to help with a debug session under GDB. For completeness, Jan Krachtovil stated <tt>-ggdb</tt> currently has no effect in a private email.

Debug build should also define <tt>DEBUG</tt>, and ensure <tt>NDEBUG</tt> is not defined. <tt>NDEBUG</tt> removes "program diagnostics"; and has undesirable behavior and side effects which discussed below in more detail. The defines should be present for all code, and not just the program. You use it for all code (your program and included libraries) because you need to know how they fail too (remember, you take the bug report - not the third party library).

In addition, you should use other relevant flags, such as <tt>-fno-omit-frame-pointer</tt>. Ensuring a frame pointer exists makes it easier to decode stack traces. Since debug builds are not shipped, its OK to leave symbols in the executable. Programs with debug information do not suffer performance hits. See, for example, [http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]

Finally, you should ensure your project includes additional diagnostic libraries, such as <tt>dmalloc</tt> and [http://code.google.com/p/address-sanitizer/ Address Sanitizer]. A comparison of some memory checking tools can be found at [http://code.google.com/p/address-sanitizer/wiki/ComparisonOfMemoryTools Comparison Of Memory Tools]. If you don't include additional diagostics in debug builds, then you should start using them sinces its OK to find errors you are not looking for.

==== Release Builds ====

Release builds are what your customer receives. They are meant to be run on production hardware and servers, and they should be reliable, secure, and efficient. A stable release build is the product of the hard work and effort during development.

For release builds, you should use the following as part of <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for release builds:

<pre>-On -g2</pre>

<tt>-O''n''</tt> sets optimizations for speed or size (for example, <tt>-Os</tt> or <tt>-O2</tt>), and <tt>-g2</tt> ensure debugging information is created.

Debugging information should be stripped and retained in case of symbolication for a crash report from the field. While not desired, debug information can be left in place without a performance penalty. See ''[http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]'' for details.

Release builds should also define <tt>NDEBUG</tt>, and ensure <tt>DEBUG</tt> is not defined. The time for debugging and diagnostics is over, so users get production code with full optimizations, no "programming diagnostics", and other efficiencies. If you can't optimize or your are performing excessive logging, it usually means the program is not ready for production.

If you have been relying on an <tt>assert</tt> and then a subsequent <tt>abort()</tt>, you have been abusing "program diagnostics" since it has no place in production code. If you want a memory dump, create one so users don't have to worry about secrets and other sensitive information being written to the filesystem and emailed in plain text.

For Windows, you would use <tt>/Od</tt> for debug builds; and <tt>/Ox</tt>, <tt>/O2</tt> or <tt>/Os</tt> for release builds. See Microsoft's [http://msdn.microsoft.com/en-us/library/k1ack8f1.aspx /O Options (Optimize Code)] for details.

==== Test Builds ====

Test builds are used to provide heuristic validation by way of positive and negative test suites. Under a test configuration, all interfaces are tested to ensure they perform to specification and satisfaction. "Satisfaction" is subjective, but it should include no crashing and no trashing of your memory arena, even when faced with negative tests.

Because all interfaces are tested (and not just the public ones), your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> should include:

<pre>-Dprotected=public -Dprivate=public</pre>

You should also change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>.

Nearly everyone gets a positive test right, so no more needs to be said. The negative self tests are much more interesting, and you should concentrate on trying to make your program fail so you can verify its fails gracefully. Remember, a bad guy is not going to be courteous when he attempts to cause your program to fail. And its your project that takes egg on the face by way of a bug report or guest appearance on [http://www.grok.org.uk/full-disclosure/ Full Disclosure] or [http://www.securityfocus.com/archive Bugtraq] - not ''<nowiki><some library></nowiki>'' you included.

=== Auto Tools ===

Auto configuration tools are popular on many Linux and Unix based systems, and the tools include ''Autoconf'', ''Automake'', ''config'', and ''Configure''. The tools work together to produce project files from scripts and template files. After the process completes, your project should be setup and ready to be made with <tt>make</tt>.

When using auto configuration tools, there are a few files of interest worth mentioning. The files are part of the auto tools chain and include <tt>m4</tt> and the various <tt>*.in</tt>, <tt>*.ac</tt> (autoconf), and <tt>*.am</tt> (automake) files. At times, you will have to open them, or the resulting makefiles, to tune the "stock" configuration.

There are three downsides to the command line configuration tools in the toolchain: (1) they often ignore user requests, (2) they cannot create configurations, and (3) security is often not a goal.

To demonstrate the first issue, confider your project with the following: <tt>configure CFLAGS="-Wall -fPIE" CXXFLAGS="-Wall -fPIE" LDFLAGS="-pie"</tt>. You will probably find the auto tools ignored your request, which means the command below will not produce expected results. As a work around, you will have to open an <tt>m4</tt> scripts, <tt>Makefile.in</tt> or <tt>Makefile.am</tt> and fix the configuration.

<pre>$ configure CFLAGS="-Wall -Wextra -Wconversion -fPIE -Wno-unused-parameter
-Wformat=2 -Wformat-security -fstack-protector-all -Wstrict-overflow"
LDFLAGS="-pie -z,noexecstack -z,noexecheap -z,relro -z,now"</pre>

For the second point, you will probably be disappointed to learn [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html Automake does not support the concept of configurations]. Its not entirely Autoconf's or Automake's fault - ''Make'' and its inability to detect changes is the underlying problem. Specifically, ''Make'' only [http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html checks modification times of prerequisites and targets], and does not check things like <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>. The net effect is you will not receive expected results when you issue <tt>make debug</tt> and then <tt>make test</tt> or <tt>make release</tt>.

Finally, you will probably be disappointed to learn tools such as Autoconf and Automake miss many security related opportunities and ship insecure out of the box. There are a number of compiler switches and linker flags that improve the defensive posture of a program, but they are not 'on' by default. Tools like Autoconf - which are supposed to handle this situation - often provides setting to serve the lowest of all denominators.

A recent discussion on the Automake mailing list illuminates the issue: ''[https://lists.gnu.org/archive/html/autoconf/2012-12/msg00038.html Enabling compiler warning flags]''. Attempts to improve default configurations were met with resistance and no action was taken. The resistance is often of the form, "<nowiki><some useful warning></nowiki> also produces false positives" or "<nowiki><some obscure platform></nowiki> does not support <nowiki><established security feature></nowiki>". Its noteworthy that David Wheeler, the author of ''[http://www.dwheeler.com/secure-programs/ Secure Programming for Linux and Unix HOWTO]'', was one of the folks trying to improve the posture.

=== Makefiles ===

Make is one of the earliest build systems dating back to the 1970s. Its available on Linux, Mac OS X and Unix, so you will frequently encounter projects using it. Unfortunately, Make has a number of short comings (''[http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful]'' and ''[http://www.conifersystems.com/whitepapers/gnu-make/ What’s Wrong With GNU make?]''), and can cause some discomfort. Despite issues with Make, ESAPI C++ uses Make primarily for three reasons: first, its omnipresent; second, its easier to manage than the Auto Tools family; and third, <tt>libtool</tt> was out of the question.

Consider what happens when you: (1) type <tt>make debug</tt>, and then type <tt>make release</tt>. Each build would require different <tt>CFLAGS</tt> due to optimizations and level of debug support. In your makefile, you would extract the relevant target and set <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> similar to below (taken from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/Makefile ESAPI C++ Makefile]):

<pre># Makefile
DEBUG_GOALS = $(filter $(MAKECMDGOALS), debug)
ifneq ($(DEBUG_GOALS),)
WANT_DEBUG := 1
WANT_TEST := 0
WANT_RELEASE := 0
endif
…

ifeq ($(WANT_DEBUG),1)
ESAPI_CFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
ESAPI_CXXFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
endif

ifeq ($(WANT_RELEASE),1)
ESAPI_CFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
ESAPI_CXXFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
endif

ifeq ($(WANT_TEST),1)
ESAPI_CFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
ESAPI_CXXFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
endif
…

# Merge ESAPI flags with user supplied flags. We perform the extra step to ensure
# user options follow our options, which should give user option's a preference.
override CFLAGS := $(ESAPI_CFLAGS) $(CFLAGS)
override CXXFLAGS := $(ESAPI_CXXFLAGS) $(CXXFLAGS)
override LDFLAGS := $(ESAPI_LDFLAGS) $(LDFLAGS)
…</pre>

Make will first build the program in a debug configuration for a session under the debugger using a rule similar to:

<pre>%.cpp:%.o:
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@</pre>

When you want the release build, Make will do nothing because it considers everything up to date despite the fact <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> have changed. Hence, your program will actually be in a debug configuration and risk a <tt>SIGABRT</tt> at runtime because debug instrumentation is present (recall <tt>assert</tt> calls <tt>abort()</tt> when <tt>NDEBUG</tt> is '''not''' defined). In essence, you have DoS'd yourself due to <tt>make</tt>.

In addition, many projects do not honor the user's command line. ESAPI C++ does its best to ensure a user's flags are honored via <tt>override</tt> as shown above, but other projects do not. For example, consider a project that should be built with Position Independent Executable (PIE or ASLR) enabled and data execution prevention (DEP) enabled. Dismissing user settings combined with insecure out of the box settings (and not picking them up during auto-setup or auto-configure) means a program built with the following will likely have neither defense:

<pre>$ make CFLAGS="-fPIE" CXXFLAGS="-fPIE" LDFLAGS="-pie -z,noexecstack, -z,noexecheap"</pre>

Defenses such as ASLR and DEP are especially important on Linux because [http://linux.die.net/man/5/elf Data Execution - not Prevention - is the norm].

=== Integration ===

Project level integration presents opportunities to harden your program or library with domain specific knowledge. For example, if the platform supports Position Independent Executables (PIE or ASLR) and data execution prevention (DEP), then you should integrate with it. The consequences of not doing so could result in exploitation. As a case in point, see KingCope's 0-days for MySQL in December, 2012 (CVE-2012-5579 and CVE-2012-5612, among others). Integration with platform security would have neutered a number of the 0-days.

You also have the opportunity to include helpful libraries that are not need for business logic support. For example, if you are working on a platform with [http://dmalloc.com DMalloc] or [http://code.google.com/p/address-sanitizer/ Address Sanitizer], you should probably use it in your debug builds. For Ubuntu, DMalloc available from the package manager and can be installed with <tt>sudo apt-get install libdmalloc5</tt>. For Apple platforms, its available as a scheme option (see [[#Clang/Xcode|Clang/Xcode]] below). Address Sanitizer is available in [http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8 and above] for many platforms.

In addition, project level integration is an opportunity to harden third party libraries you chose to include. Because you chose to include them, you and your users are responsible for them. If you or your users endure a SP800-53 audit, third party libraries will be in scope because the supply chain is included (specifically, item SA-12, Supply Chain Protection). The audits are not limited to those in the US Federal arena - financial institutions perform reviews too. A perfect example of violating this guidance is [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525], which was due to [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library].

Another example is including OpenSSL. You know (1) [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 is insecure], (2) [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 is insecure], and (3) [http://arstechnica.com/security/2012/09/crime-hijacks-https-sessions/ compression is insecure] (among others). In addition, suppose you don't use hardware and engines, and only allow static linking. Given the knowledge and specifications, you would configure the OpenSSL library as follows:

<pre>$ Configure darwin64-x86_64-cc -no-hw -no-engines -no-comp -no-shared -no-dso -no-sslv2 -no-sslv3 --openssldir=…</pre>

''Note Well'': you might want engines, especially on Ivy Bridge microarchitectures (3rd generation Intel Core i5 and i7 processors). To have OpenSSL use the processor's random number generator (via the of <tt>rdrand</tt> instruction), you will need to call OpenSSL's <tt>ENGINE_load_rdrand()</tt> function and then <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. See [http://wiki.opensslfoundation.com/index.php/Random_Numbers OpenSSL's Random Numbers] for details.

If you configure without the switches, then you will likely have vulnerable code/libraries and risk failing an audit. If the program is a remote server, then the following command will reveal if compression is active on the channel:

<pre>$ echo "GET / HTTP1.0" | openssl s_client -connect <nowiki>example.com:443</nowiki></pre>

<tt>nm</tt> or <tt>openssl s_client</tt> will show that compression is enabled in the client. In fact, any symbol within the <tt>OPENSSL_NO_COMP</tt> preprocessor macro will bear witness since <tt>-no-comp</tt> is translated into a <tt>CFLAGS</tt> define.

<pre>$ nm /usr/local/ssl/iphoneos/lib/libcrypto.a 2>/dev/null | egrep -i "(COMP_CTX_new|COMP_CTX_free)"
0000000000000110 T COMP_CTX_free
0000000000000000 T COMP_CTX_new</pre>

Even more egregious is the answer given to auditors who specifically ask about configurations and protocols: "we don't use weak/wounded/broken ciphers" or "we follow best practices." The use of compression tells the auditor that you are using wounded protocol in an insecure configuration and you don't follow best practices. That will likely set off alarm bells, and ensure the auditor dives deeper on more items.

== Preprocessor ==

The preprocessor is crucial to setting up a project for success. The C committee provided one macro - <tt>NDEBUG</tt> - and the macro can be used to derive a number of configurations and drive engineering processes. Unfortunately, the committee also left many related items to chance, which has resulted in programmers abusing builtin facilities. This section will help you set up you projects to integrate well with other projects and ensure reliability and security.

There are three topics to discuss when hardening the preprocessor. The first is well defined configurations which produce well defined behaviors, the second is useful behavior from assert, and the third is proper use of macros when integrating vendor code and third party libraries.

=== Configurations ===

To remove ambiguity, you should recognize two configurations: Release and Debug. Release is for production code on live servers, and its behavior is requested via the C/C++ <tt>NDEBUG</tt> macro. Its also the only macro observed by the C and C++ Committees and Posix. Diametrically opposed to release is Debug. While there is a compelling argument for <tt>!defined(NDEBUG)</tt>, you should have an explicit macro for the configuration and that macro should be <tt>DEBUG</tt>. This is because vendors and outside libraries use <tt>DEBUG</tt> (or similar) macro for their configuration. For example, Carnegie Mellon's Mach kernel uses <tt>DEBUG</tt>, Microsoft's CRT uses [http://msdn.microsoft.com/en-us/library/ww5t02fa%28v=vs.71%29.aspx<tt>_DEBUG</tt>], and Wind River Workbench uses <tt>DEBUG_MODE</tt>.

In addition to <tt>NDEBUG</tt> (Release) and <tt>DEBUG</tt> (Debug), you have two additional cross products: both are defined or neither are defined. Defining both should be an error, and defining neither should default to a release configuration. Below is from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/esapi/EsapiCommon.h ESAPI C++ EsapiCommon.h], which is the configuration file used by all source files:

<pre>// Only one or the other, but not both
#if (defined(DEBUG) || defined(_DEBUG)) && (defined(NDEBUG) || defined(_NDEBUG))
# error Both DEBUG and NDEBUG are defined.
#endif

// The only time we switch to debug is when asked. NDEBUG or {nothing} results
// in release build (fewer surprises at runtime).
#if defined(DEBUG) || defined(_DEBUG)
# define ESAPI_BUILD_DEBUG 1
#else
# define ESAPI_BUILD_RELEASE 1
#endif</pre>

When <tt>DEBUG</tt> is in effect, your code should receive full debug instrumentation, including the full force of assertions.

=== ASSERT ===

Asserts will help you create self-debugging code by helping you find the point of first failure quickly and easily. Asserts should be used throughout your program, including parameter validation, return value checking and program state. The <tt>assert</tt> will silently guard your code through its lifetime. It will always be there, even when not debugging a specific component of a module. If you have thorough code coverage, you will spend less time debugging and more time developing because programs will debug themselves.

To use asserts effectively, you should assert everything. That includes parameters upon entering a function, return values from function calls, and any program state. Everywhere you place an <tt>if</tt> statement for validation or checking, you should have an assert. Everywhere you have an <tt>assert</tt> for validation or checking, you should have an <tt>if</tt> statement. They go hand-in-hand.

If you are still using <tt>printf</tt>'s, then you have an opportunity for improvement. In the time it takes for you to write a <tt>printf</tt> or <tt>NSLog</tt> statement, you could have written an <tt>assert</tt>. Unlike the <tt>printf</tt> or <tt>NSLog</tt> which are often removed when no longer needed, the <tt>assert</tt> stays active forever. Remember, this is all about finding the point of first failure quickly so you can spend your time doing other things.

There is one problem with using asserts - [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html Posix states <tt>assert</tt> should call <tt>abort()</tt>] if <tt>NDEBUG</tt> is '''not''' defined. When debugging, <tt>NDEBUG</tt> will never be defined since you want the "program diagnostics" (quote from the Posix description). The behavior makes <tt>assert</tt> and its accompanying <tt>abort()</tt> completely useless for development. The result of "program diagnostics" calling <tt>abort()</tt> due to standard C/C++ behavior is disuse - developers simply don't use them. Its incredibly bad for the development community because self-debugging programs can help eradicate so many stability problems.

Since self-debugging programs are so powerful, you will have to have to supply your own assert and signal handler with improved behavior. Your assert will exchange auto-aborting behavior for auto-debugging behavior. The auto-debugging facility will ensure the debugger snaps when a problem is detected, and you will find the point of first failure quickly and easily.

ESAPI C++ supplies its own assert with the behavior described above. In the code below, <tt>ASSERT</tt> raises <tt>SIGTRAP</tt> when in effect or it evaluates to <tt>void</tt> in other cases.

<pre>// A debug assert which should be sprinkled liberally. This assert fires and then continues rather
// than calling abort(). Useful when examining negative test cases from the command line.
#if (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_STARNIX))
# define ESAPI_ASSERT1(exp) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
# define ESAPI_ASSERT2(exp, msg) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< ": \"" << (msg) << "\"" << std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
#elif (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_WINDOWS))
# define ESAPI_ASSERT1(exp) assert(exp)
# define ESAPI_ASSERT2(exp, msg) assert(exp)
#else
# define ESAPI_ASSERT1(exp) ((void)(exp))
# define ESAPI_ASSERT2(exp, msg) ((void)(exp))
#endif

#if !defined(ASSERT)
# define ASSERT(exp) ESAPI_ASSERT1(exp)
#endif</pre>

At program startup, a <tt>SIGTRAP</tt> handler will be installed if one is not provided by another component:

<pre>struct DebugTrapHandler
{
DebugTrapHandler()
{
struct sigaction new_handler, old_handler;

do
{
int ret = 0;

ret = sigaction (SIGTRAP, NULL, &old_handler);
if (ret != 0) break; // Failed

// Don't step on another's handler
if (old_handler.sa_handler != NULL) break;

new_handler.sa_handler = &DebugTrapHandler::NullHandler;
new_handler.sa_flags = 0;

ret = sigemptyset (&new_handler.sa_mask);
if (ret != 0) break; // Failed

ret = sigaction (SIGTRAP, &new_handler, NULL);
if (ret != 0) break; // Failed

} while(0);
}

static void NullHandler(int /*unused*/) { }

};

// We specify a relatively low priority, to make sure we run before other CTORs
// http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#C_002b_002b-Attributes
static const DebugTrapHandler g_dummyHandler __attribute__ ((init_priority (110)));</pre>

On a Windows platform, you would call <tt>_set_invalid_parameter_handler</tt> (and possibly <tt>set_unexpected</tt> or <tt>set_terminate</tt>) to install a new handler.

Live hosts running production code should always define <tt>NDEBUG</tt> (i.e., release configuration), which means they do not assert or auto-abort. Auto-abortion is not acceptable behavior, and anyone who asks for the behavior is completely abusing the functionality of "program diagnostics". If a program wants a core dump, then it should create the dump rather than crashing.

For more reading on asserting effectively, please see one of John Robbin's books, such as ''[http://www.amazon.com/dp/0735608865 Debugging Applications]''. John is a legendary bug slayer in Windows circles, and he will show you how to do nearly everything, from debugging a simple program to bug slaying in multithreaded programs.

=== Additional Macros ===

Additional macros include any macros needed to integrate properly and securely. It includes integrating the program with the platform (for example MFC or Cocoa/CocoaTouch) and libraries (for example, Crypto++ or OpenSSL). It can be a challenge because you have to have proficiency with your platform and all included libraries and frameworks. The list below illustrates the level of detail you will need when integrating.

Though Boost is missing from the list, it appears to lack recommendations, additional debug diagnostics, and a hardening guide. See ''[http://stackoverflow.com/questions/14927033/boost-hardening-guide-preprocessor-macros BOOST Hardening Guide (Preprocessor Macros)]'' for details. In addition, Tim Day points to ''[http://boost.2283326.n4.nabble.com/boost-build-should-we-not-define-SECURE-SCL-0-by-default-for-all-msvc-toolsets-td2654710.html <nowiki>[boost.build] should we not define _SECURE_SCL=0 by default for all msvc toolsets</nowiki>]'' for a recent discussion related to hardening (or lack thereof).

In addition to what you should define, defining some macros and undefining others should trigger a security related defect. For example, <tt>-U_FORTIFY_SOURCES</tt> on Linux and <tt>_CRT_SECURE_NO_WARNINGS=1</tt>, <tt>_SCL_SECURE_NO_WARNINGS</tt>, <tt>_ATL_SECURE_NO_WARNINGS</tt> or <tt>STRSAFE_NO_DEPRECATE</tt> on Windows.

{| border="1"

|-style="background:#DADADA"
!Platform/Library!!Debug!!Release
|+ Table 1: Additional Platform/Library Macros

|-
|width="175pt"|All
|width="250pt"|DEBUG=1
|width="250pt"|NDEBUG=1

|-
|Linux
|_GLIBCXX_DEBUG=1a 
_GLIBCXX_CONCEPT_CHECKS=1b
|_FORTIFY_SOURCE=2

|-
|Android
|NDK_DEBUG=1
|_FORTIFY_SOURCE=1 (4.2 and above) 
<tt>#define LOGI(...)</tt> (define to nothing, preempt logging)

|-
|Cocoa/CocoaTouch
|
|NS_BLOCK_ASSERTIONS=1 
<tt>#define NSLog(...)</tt> (define to nothing, preempt ASL)

|-
|SafeInt
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1

|-
|Microsoft
|_DEBUG=1, STRICT, 
_SECURE_SCL=1, _HAS_ITERATOR_DEBUGGING=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1
|STRICT 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1

|-
|Microsoft ATL & MFC
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS

|-
|STLPort
|_STLP_DEBUG=1, _STLP_USE_DEBUG_LIB=1 
_STLP_DEBUG_ALLOC=1, _STLP_DEBUG_UNINITIALIZED=1
|

|-
|SQLite
|SQLITE_DEBUG, SQLITE_MEMDEBUG 
SQLITE_SECURE_DELETEc 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nd
|SQLITE_SECURE_DELETEc 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nd

|-
|SQLCipher
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3e
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3e

|}

a Be careful with <tt>_GLIBCXX_DEBUG</tt> when using pre-compiled libraries such as Boost from a distribution. There are ABI incompatibilities, and the result will likely be a crash. You will have to compile Boost with <tt>_GLIBCXX_DEBUG</tt> or omit <tt>_GLIBCXX_DEBUG</tt>.

b See [http://gcc.gnu.org/onlinedocs/libstdc++/manual/concept_checking.html Chapter 5, Diagnostics] of the libstdc++ manual for details.

c SQLite secure deletion zeroizes memory on destruction. Define as required, and always define in US Federal since zeroization is required for FIPS 140-2, Level 1.

d ''N'' is 0644 by default, which means everyone has some access.

e Force temporary tables into memory (no unencrypted data to disk).

== Compiler and Linker ==

Compiler writers provide a rich set of warnings from the analysis of code during compilation. Both GCC and Visual Studio have static analysis capabilities to help find mistakes early in the development process. The built in static analysis capabilities of GCC and Visual Studio are usually sufficient to ensure proper API usage and catch a number of mistakes such as using an uninitialized variable or comparing a negative signed int and a positive unsigned int.

As a concrete example, (and for those not familiar with C/C++ promotion rules), a warning will be issued if a signed integer is promoted to an unsigned integer and then compared because a side effect is <tt>-1 > 1</tt> after promotion! GCC and Visual Studio will not currently catch, for example, SQL injections and other tainted data usage. For that, you will need a tool designed to perform data flow analysis or taint analysis.

Some in the development community resist static analysis or refute its results. For example, when static analysis warned the Linux kernel's <tt>sys_prctl</tt> was comparing an unsigned value against less than zero, Jesper Juhl offered a patch to clean up the code. Linus Torvalds howled “No, you don't do this… GCC is crap” (referring to compiling with warnings). For the full discussion, see ''[http://linux.derkeiler.com/Mailing-Lists/Kernel/2006-11/msg08325.html <nowiki>[PATCH] Don't compare unsigned variable for <0 in sys_prctl()</nowiki>]'' from the Linux Kernel mailing list.

The following sections will detail steps for three platforms. First is a typical GNU Linux based distribution offering GCC and Binutils, second is Clang and Xcode, and third is modern Windows platforms.

=== Distribution Hardening ===

Before discussing GCC and Binutils, it would be a good time to point out some of the defenses discussed below are all ready present in a distribution. Unfortunately, its design by committee, so what is present is usually only a mild variation of what is available (this way, everyone is mildly offended). For those who are purely worried about performance, you might be surprised to learn you have already taken the small performance hint without even knowing.

Linux and BSD distributions often apply some hardening without intervention via ''[http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html GCC Spec Files]''. If you are using Debian, Ubuntu, Linux Mint and family, see ''[http://wiki.debian.org/Hardening Debian Hardening]''. For Red Hat and Fedora systems, see ''[http://lists.fedoraproject.org/pipermail/devel-announce/2011-August/000821.html New hardened build support (coming) in F16]''. Gentoo users should visit ''[http://www.gentoo.org/proj/en/hardened/ Hardened Gentoo]''.

You can see the settings being used by a distribution via <tt>gcc -dumpspecs</tt>. From Linux Mint 12 below, -fstack-protector (but not -fstack-protector-all) is used by default.

<pre>$ gcc -dumpspecs
…
*link_ssp: %{fstack-protector:}

*ssp_default: %{!fno-stack-protector:%{!fstack-protector-all: %{!ffreestanding:%{!nostdlib:-fstack-protector}}}}
…</pre>

The “SSP” above stands for Stack Smashing Protector. SSP is a reimplementation of Hiroaki Etoh's work on IBM Pro Police Stack Detector. See Hiroaki Etoh's patch ''[http://gcc.gnu.org/ml/gcc-patches/2001-06/msg01753.html gcc stack-smashing protector]'' and IBM's ''[http://www.research.ibm.com/trl/projects/security/ssp/ GCC extension for protecting applications from stack-smashing attacks]'' for details.

=== GCC/Binutils ===

GCC (the compiler collection) and Binutils (the assemblers, linkers, and other tools) are separate projects that work together to produce a final executable. Both the compiler and linker offer options to help you write safer and more secure code. The linker will produce code which takes advantage of platform security features offered by the kernel and PaX, such as no-exec stacks and heaps (NX) and Position Independent Executable (PIE).

The table below offers a set of compiler options to build your program. Static analysis warnings help catch mistakes early, while the linker options harden the executable at runtime. In the table below, “GCC” should be loosely taken as “non-ancient distributions.” While the GCC team considers 4.2 ancient, you will still encounter it on Apple and BSD platforms due to changes in GPL licensing around 2007. Refer to ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Option Summary]'', ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html Options to Request or Suppress Warnings]'' and ''[http://sourceware.org/binutils/docs-2.21/ld/Options.html Binutils (LD) Command Line Options]'' for usage details.

Noteworthy of special mention are <tt>-fno-strict-overflow</tt> and <tt>-fwrapv</tt>a. The flags ensure the compiler does not remove statements that result in overflow or wrap. If your program only runs correctly using the flags, it is likely violating C/C++ rules on overflow and illegal. If the program is illegal due to overflow or wrap checking, you should consider using [http://code.google.com/p/safe-iop/ safe-iop] for C or David LeBlanc's [http://safeint.codeplex.com SafeInt] in C++.

For a project compiled and linked with hardened settings, some of those settings can be verified with the [http://www.trapkit.de/tools/checksec.html Checksec] tool written by Tobias Klein. The <tt>checksec.sh</tt> script is designed to test standard Linux OS and PaX security features being used by an application. See the [http://www.trapkit.de/tools/checksec.html Trapkit] web page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 2: GCC C Warning Options

|-
|width="200pt"|<nowiki>-Wall -Wextra</nowiki>
|width="75t"|GCC
|width="425pt"|Enables many warnings (despite their names, all and extra do not turn on all warnings).a

|-
|<nowiki>-Wconversion</nowiki>
|GCC
|Warn for implicit conversions that may alter a value (includes -Wsign-conversion).

|-
|<nowiki>-Wsign-conversion</nowiki>
|GCC
|Warn for implicit conversions that may change the sign of an integer value, such as assigning a signed integer to an unsigned integer (<tt>-1 > 1</tt> after promotion!).

|-
|<nowiki>-Wcast-align</nowiki>
|GCC
|Warn for a pointer cast to a type which has a different size, causing an invalid alignment and subsequent bus error on ARM processors.

|-
|<nowiki>-Wformat=2 -Wformat-security</nowiki>
|GCC
|Increases warnings related to possible security defects, including incorrect format specifiers.

|-
|<nowiki>-fno-common</nowiki>
|GCC
|Prevent global variables being simultaneously defined in different object files.

|-
|<nowiki>-fstack-protector or -fstack-protector-all</nowiki>
|GCC
|Stack Smashing Protector (SSP). Improves stack layout and adds a guard to detect stack based buffer overflows.b

|-
|<nowiki>-fno-omit-frame-pointer</nowiki>
|GCC
|Improves backtraces for post-mortem analysis

|-
|<nowiki>-Wmissing-prototypes and -Wmissing-declarations</nowiki>
|GCC
|Warn if a global function is defined without a prototype or declaration.

|-
|<nowiki>-Wstrict-prototypes</nowiki>
|GCC
|Warn if a function is declared or defined without specifying the argument types.

|-
|<nowiki>-Wstrict-overflow</nowiki>
|GCC 4.2
|Warn about optimizations taken due to <nowiki>[undefined]</nowiki> signed integer overflow assumptions.

|-
|<nowiki>-Wtrampolines</nowiki>
|GCC 4.3
|Warn about trampolines generated for pointers to nested functions. Trampolines require executable stacks.

|-
|<nowiki>-fsanitize=address</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/address-sanitizer/ AddressSanitizer], a fast memory error detector. Memory access instructions will be instrumented to help detect heap, stack, and global buffer overflows; as well as use-after-free bugs.

|-
|<nowiki>-fsanitize=thread</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/data-race-test/wiki/ThreadSanitizer ThreadSanitizer], a fast data race detector. Memory access instructions will be instrumented to detect data race bugs.

|-
|<nowiki>-Wl,-z,nodlopen and -Wl,-z,nodump</nowiki>
|Binutils 2.10
|Reduces the ability of an attacker to load, manipulate, and dump shared objects.

|-
|<nowiki>-Wl,-z,noexecstack and -Wl,-z,noexecheap</nowiki>
|Binutils 2.14
|Data Execution Prevention (DEP). ELF headers are marked with PT_GNU_STACK and PT_GNU_HEAP.

|-
|<nowiki>-Wl,-z,relro</nowiki>
|Binutils 2.15
|Helps remediate Global Offset Table (GOT) attacks on executables.

|-
|<nowiki>-Wl,-z,now</nowiki>
|Binutils 2.15
|Helps remediate Procedure Linkage Table (PLT) attacks on executables.

|-
|<nowiki>-fPIC</nowiki>
|Binutils
|Position Independent Code. Used for libraries and shared objects. Both -fPIC (compiler) and -shared (linker) are required.

|-
|<nowiki>-fPIE</nowiki>
|Binutils 2.16
|Position Independent Executable (ASLR). Used for programs. Both -fPIE (compiler) and -pie (linker) are required.

|}

a Unlike Clang and -Weverything, GCC does not provide a switch to truly enable all warnings. 
b -fstack-protector guards functions with high risk objects such as C strings, while -fstack-protector-all guards all objects.

Additional C++ warnings which can be used include the following in Table 3. See ''[http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html GCC's Options Controlling C++ Dialect]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 3: GCC C++ Warning Options

|-
|width="200pt"|<nowiki>-Woverloaded-virtual</nowiki>
|width="425pt"|Warn when a function declaration hides virtual functions from a base class.

|-
|<nowiki>-Wreorder</nowiki>
|Warn when the order of member initializers given in the code does not match the order in which they must be executed.

|-
|<nowiki>-Wsign-promo</nowiki>
|Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size.

|-
|<nowiki>-Wnon-virtual-dtor</nowiki>
|Warn when a class has virtual functions and an accessible non-virtual destructor.

|-
|<nowiki>-Weffc++</nowiki>
|Warn about violations of the following style guidelines from Scott Meyers' ''[http://www.aristeia.com/books.html Effective C++, Second Edition]'' book.

|}

And additional Objective C warnings which are often useful include the following. See ''[http://gcc.gnu.org/onlinedocs/gcc/Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html Options Controlling Objective-C and Objective-C++ Dialects]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 4: GCC Objective C Warning Options

|-
|width="200pt"|<nowiki>-Wstrict-selector-match</nowiki>
|width="425pt"|Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type id or Class.

|-
|<nowiki>-Wundeclared-selector</nowiki>
|Warn if a <tt>@selector(…)</tt> expression referring to an undeclared selector is found.

|}

The use of aggressive warnings will produce spurious noise. The noise is a tradeoff - you can learn of potential problems at the cost of wading through some chaff. The following will help reduces spurious noise from the warning system:

* -Wno-unused-parameter (GCC)
* -Wno-type-limits (GCC 4.3)
* -Wno-tautological-compare (Clang)

Finally, a simple version based Makefile example is shown below. This is different than feature based makefile produced by auto tools (which will test for a particular feature and then define a symbol or configure a template file). Not all platforms use all options and flags. To address the issue you can pursue one of two strategies. First, you can ship with a weakened posture by servicing the lowest common denominator; or you can ship with everything in force. In the latter case, those who don't have a feature available will edit the makefile to accommodate their installation.

<pre>CXX=g++
EGREP = egrep
…

GCC_COMPILER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version')
GCC41_OR_LATER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version (4\.[1-9]|[5-9])')
…

GNU_LD210_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[0-9]|2\.[2-9])')
GNU_LD214_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[4-9]|2\.[2-9])')
…

ifeq ($(GCC_COMPILER),1)
MY_CC_FLAGS += -Wall -Wextra -Wconversion
MY_CC_FLAGS += -Wformat=2 -Wformat-security
MY_CC_FLAGS += -Wno-unused-parameter
endif

ifeq ($(GCC41_OR_LATER),1)
MY_CC_FLAGS += -fstack-protector-all
endif

ifeq ($(GCC42_OR_LATER),1)
MY_CC_FLAGS += -Wstrict-overflow
endif

ifeq ($(GCC43_OR_LATER),1)
MY_CC_FLAGS += -Wtrampolines
endif

ifeq ($(GNU_LD210_OR_LATER),1)
MY_LD_FLAGS += -z,nodlopen -z,nodump
endif

ifeq ($(GNU_LD214_OR_LATER),1)
MY_LD_FLAGS += -z,noexecstack -z,noexecheap
endif

ifeq ($(GNU_LD215_OR_LATER),1)
MY_LD_FLAGS += -z,relro -z,now
endif

ifeq ($(GNU_LD216_OR_LATER),1)
MY_CC_FLAGS += -fPIE
MY_LD_FLAGS += -pie
endif

# Use 'override' to honor the user's command line
override CFLAGS := $(MY_CC_FLAGS) $(CFLAGS)
override CXXFLAGS := $(MY_CC_FLAGS) $(CXXFLAGS)
override LDFLAGS := $(MY_LD_FLAGS) $(LDFLAGS)
…</pre>

=== Clang/Xcode ===

[http://clang.llvm.org Clang] and [http://llvm.org LLVM] have been aggressively developed since Apple lost its GPL compiler back in 2007 (due to Tivoization which resulted in GPLv3). Since that time, a number of developers and Goggle have joined the effort. While Clang will consume most (all?) GCC/Binutil flags and switches, the project supports a number of its own options, including a static analyzer. In addition, Clang is relatively easy to build with additional diagnostics, such as Dr. John Regher and Peng Li's [http://embed.cs.utah.edu/ioc/ Integer Overflow Checker (IOC)].

IOC is incredibly useful, and has found bugs in a number of projects, from the Linux Kernel (<tt>include/linux/bitops.h</tt>, still unfixed), SQLite, PHP, Firefox (many still unfixed), LLVM, and Python. Future version of Clang (Clang 3.3 and above) will allow you to enable the checks out of the box with <tt>-fsanitize=integer</tt> and <tt>-fsanitize=shift</tt>.

Clang options can be found at [http://clang.llvm.org/docs/UsersManual.html Clang Compiler User’s Manual]. Clang does include an option to turn on all warnings - <tt>-Weverything</tt>. Use it with care but use it regularly since you will get back a lot of noise and issues you missed. For example, add <tt>-Weverything</tt> for production builds and make non-spurious issues a quality gate. Under Xcode, simply add <tt>-Weverything</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>.

In addition to compiler warnings, both static analysis and additional security checks can be performed. Reading on Clang's static analysis capabilities can be found at [http://clang-analyzer.llvm.org Clang Static Analyzer]. Figure 1 below shows some of the security checks utilized by Xcode.

{| align="center"
| [[File:toolchan-hardening-11.png|thumb|450px|Figure 1: Clang/LLVM and Xcode options]]
|}

=== Visual Studio ===

Visual Studio offers a convenient Integrated Development Environment (IDE) for managing solutions and their settings. the section called “Visual Studio Options” discusses option which should be used with Visual Studio, and the section called “Project Properties” demonstrates incorporating those options into a solution's project.

The table below lists the compiler and linker switches which should be used under Visual Studio. Refer to Howard and LeBlanc's Writing Secure Code (Microsoft Press) for a detailed discussion; or ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]'' in Security Briefs by Michael Howard. In the table below, “Visual Studio” refers to nearly all versions of the development environment, including Visual Studio 5.0 and 6.0.

For a project compiled and linked with hardened settings, those settings can be verified with BinScope. BinScope is a verification tool from Microsoft that analyzes binaries to ensure that they have been built in compliance with Microsoft's Security Development Lifecycle (SDLC) requirements and recommendations. See the ''[https://www.microsoft.com/download/en/details.aspx?id=11910 BinScope Binary Analyzer]'' download page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 5: Visual Studio Warning Options

|-
|width="150pt"|<nowiki>/W4</nowiki>
|width="100pt"|Visual Studio
|width="350pt"|Warning level 4, which includes most warnings.

|-
|<nowiki>/WAll</nowiki>
|Visual Studio 2003
|Enable all warnings, including those off by default.a

|-
|<nowiki>/GS</nowiki>
|Visual Studio 2003
|Adds a security cookie (guard or canary) on the stack before the return address buffer stack based for overflow checks.a

|-
|<nowiki>/SafeSEH</nowiki>
|Visual Studio 2003
|Safe structured exception handling to remediate SEH overwrites.

|-
|<nowiki>/analyze</nowiki>
|Visual Studio 2005
|Enterprise code analysis (freely available with Windows SDK for Windows Server 2008 and .NET Framework 3.5).

|-
|<nowiki>/NXCOMPAT</nowiki>
|Visual Studio 2005
|Data Execution Prevention (DEP).

|-
|<nowiki>/dynamicbase</nowiki>
|Visual Studio 2005 SP1
|Address Space Layout Randomization (ASLR).

|-
|<nowiki>strict_gs_check</nowiki>
|Visual Studio 2005 SP1
|Aggressively applies stack protections to a source file to help detect some categories of stack based buffer overruns.b

|}

aSee Jon Sturgeon's discussion of the switch at ''[https://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx Off By Default Compiler Warnings in Visual C++]''. 
aWhen using /GS, there are a number of circumstances which affect the inclusion of a security cookie. For example, the guard is not used if there is no buffer in the stack frame, optimizations are disabled, or the function is declared naked or contains inline assembly. 
b<tt>#pragma strict_gs_check(on)</tt> should be used sparingly, but is recommend in high risk situations, such as when a source file parses input from the internet.

=== Warn Suppression ===

From the tables above, a lot of warnings have been enabled to help detect possible programming mistakes. The potential mistakes are detected via compiler which carries around a lot of contextual information during its code analysis phase. At times, you will receive spurious warnings because the compiler is not ''that'' smart. Its understandable and even a good thing (how would you like to be out of a job because a program writes its own programs?). At times you will have to learn how to work with the compiler's warning system to suppress warnings. Notice what was not said: turn off the warnings.

Suppressing warnings placates the compiler for spurious noise so you can get to the issues that matter (you are separating the wheat from the chaff). This section will offer some hints and point out some potential minefields. First is an unused parameter (for example, <tt>argc</tt> or <tt>argv</tt>). Suppressing unused parameter warnings is especially helpful for C++ and interface programming, where parameters are often unused. For this warning, simply define an "UNUSED" macro and warp the parameter:

<pre>#define UNUSED_PARAMETER(x) ((void)x)
…

int main(int argc, char* argv[])
{
UNUSED_PARAMETER(argc);
UNUSED_PARAMETER(argv);
…
}</pre>

A potential minefield lies near "comparing unsigned and signed" values, and <tt>-Wconversion</tt> will catch it for you. This is because C/C++ promotion rules state the signed value will be promoted to an unsigned value and then compared. That means <tt>-1 > 1</tt> after promotion! To fix this, you cannot blindly cast - you must first range test the value:

<pre>int x = GetX();
unsigned int y = GetY();

ASSERT(x >= 0);
if(!(x >= 0))
throw runtime_error("WTF??? X is negative.");

if(static_cast<unsigned int>(x) > y)
cout << "x is greater than y" << endl;
else
cout << "x is not greater than y" << endl;</pre>

Notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>x</tt>. Just run the program and wait for it to tell you there is a problem. If there is a problem, the program will snap the debugger (and more importantly, not call a useless <tt>abort()</tt> as specified by Posix). It beats the snot out of <tt>printf</tt> that are removed when no longer needed or pollute outputs.

Another conversion problem you will encounter conversion between types, and <tt>-Wconversion</tt> will also catch it for you. The following will always have an opportunity to fail, and should light up like a Christmas tree:

<pre>struct sockaddr_in addr;
…

addr.sin_port = htons(atoi(argv[2]));</pre>

The following would probably serve you much better. Notice <tt>atoi</tt> and fiends are not used because they can silently fail. In addition, the code is instrumented so you don't need to waste a lot of time debugging potential problems:

<pre>const char* cstr = GetPortString();

ASSERT(cstr != NULL);
if(!(cstr != NULL))
throw runtime_error("WTF??? Port string is not valid.");

istringstream iss(cstr);
long long t = 0;
iss >> t;

ASSERT(!(iss.fail()));
if(iss.fail())
throw runtime_error("WTF??? Failed to read port.");

// Should this be a port above the reserved range ([0-1024] on Unix)?
ASSERT(t > 0);
if(!(t > 0))
throw runtime_error("WTF??? Port is too small");

ASSERT(t < static_cast<long long>(numeric_limits<unsigned int>::max()));
if(!(t < static_cast<long long>(numeric_limits<unsigned int>::max())))
throw runtime_error("WTF??? Port is too large");

// OK to use port
unsigned short port = static_cast<unsigned short>(t);
…</pre>

Again, notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>port</tt>. This code will continue checking conditions, years after being instrumented (assuming to wrote code to read a config file early in the project). There's no need to remove the <tt>ASSERT</tt>s as with <tt>printf</tt> since they are silent guardians.

Another useful suppression trick is too avoid ignoring return values. Not only is it useful to suppress the warning, its required for correct code. For example, <tt>snprint</tt> will alert you to truncations through its return value. You should not make them silent truncations by ignoring the warning or casting to <tt>void</tt>:

<pre>char path[PATH_MAX];
…

int ret = snprintf(path, sizeof(path), "%s/%s", GetDirectory(), GetObjectName());
ASSERT(ret != -1);
ASSERT(!(ret >= sizeof(path)));

if(ret == -1 || ret >= sizeof(path))
throw runtime_error("WTF??? Unable to build full object name");

// OK to use path
…</pre>

The problem is pandemic, and not just boring user land programs. Projects which offer high integrity code, such as SELinux, suffer silent truncations. The following is from an approved SELinux patch even though a comment was made that it [http://permalink.gmane.org/gmane.comp.security.selinux/16845 suffered silent truncations in its <tt>security_compute_create_name</tt> function] from <tt>compute_create.c</tt>.

<pre>12 int security_compute_create_raw(security_context_t scon,
13 security_context_t tcon,
14 security_class_t tclass,
15 security_context_t * newcon)
16 {
17 char path[PATH_MAX];
18 char *buf;
19 size_t size;
20 int fd, ret;
21
22 if (!selinux_mnt) {
23 errno = ENOENT;
24 return -1;
25 }
26
27 snprintf(path, sizeof path, "%s/create", selinux_mnt);
28 fd = open(path, O_RDWR);</pre>

Unlike other examples, the above code will not debug itself, and you will have to set breakpoints and trace calls to determine the point of first failure. (And the code above gambles that the truncated file does not exist or is not under an adversary's control by blindly performing the <tt>open</tt>).

== Runtime ==

The previous sections concentrated on setting up your project for success. This section will examine additional hints for running with increased diagnostics and defenses. Not all platforms are created equal - GNU Linux is difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening to a program after compiling and static linking]; while Windows allows post-build hardening through a download. Remember, the goal is to find the point of first failure quickly so you can improve the reliability and security of the code.

=== Xcode ===

Xcode offers additional [http://developer.apple.com/library/mac/#recipes/xcode_help-scheme_editor/Articles/SchemeDiagnostics.html Application Diagnostics] that can help find memory errors and object use problems. Schemes can be managed through ''Products'' menu item, ''Scheme'' submenu item, and then ''Edit''. From the editor, navigate to the ''Diagnostics'' tab. In the figure below, four additional instruments are enabled for the debugging cycle: Scribble guards, Edge guards, Malloc guards, and Zombies.

{| align="center"
| [[File:toolchan-hardening-1.png|thumb|450px|Figure 2: Xcode Memory Diagnostics]]
|}

There is one caveat with using some of the guards: Apple only provides them for the simulator, and not a device. In the past, the guards were available for both devices and simulators.

=== Windows ===

Visual Studio offers a number of debugging aides for use during development. The aides are called [http://msdn.microsoft.com/en-us/library/d21c150d.aspx Managed Debugging Assistants (MDAs)]. You can find the MDAs on the ''Debug'' menu, then ''Exceptions'' submenu. MDAs allow you to tune your debugging experience by, for example, filter exceptions for which the debugger should snap. For more details, see Stephen Toub's ''[http://msdn.microsoft.com/en-us/magazine/cc163606.aspx Let The CLR Find Bugs For You With Managed Debugging Assistants]''.

{| align="center"
| [[File:toolchan-hardening-2.png|thumb|450px|Figure 3: Managed Debugging Assistants]]
|}

Finally, for runtime hardening, Microsoft has a helpful tool called EMET. EMET is the [http://support.microsoft.com/kb/2458544 Enhanced Mitigation Experience Toolkit], and allows you to apply runtime hardening to an executable which was built without. Its very useful for utilities and other programs that were built without an SDLC.

{| align="center"
| [[File:toolchan-hardening-3.png|thumb|450px|Figure 4: Windows and EMET]]
|}

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

C-Based Toolchain Hardening

2013-03-18T04:23:43Z

Jeffrey Walton:

[[C-Based Toolchain Hardening]] is a treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

This is a prescriptive article, and it will not debate semantics or speculate on behavior. Some information, such as the C/C++ committee's motivation and pedigree for [https://groups.google.com/a/isocpp.org/forum/?fromgroups=#!topic/std-discussion/ak8e1mzBhGs "program diagnostics", <tt>NDEBUG</tt>, <tt>assert</tt>, and <tt>abort()</tt>], appears to be lost like a tale in the Lord of the Rings. As such, the article will specify semantics (for example, the philosophy of 'debug' and 'release' build configurations), assign behaviors (for example, what an assert should do in a 'debug' and 'release' build configurations), and present a position. If you find the posture is too aggressive, then you should back off as required to suite your taste.

A secure toolchain is not a silver bullet. It is one piece of an overall strategy in the engineering process to help ensure success. It will compliment existing processes such as static analysis, dynamic analysis, secure coding, negative test suites, and the like. Tools such as Valgrind and Helgrind will still be needed. And a project will still require solid designs and architectures.

The OWASP [http://code.google.com/p/owasp-esapi-cplusplus/source ESAPI C++] project eats its own dog food. Many of the examples you will see in this article come directly from the ESAPI C++ project.

Finally, a [[Category:Cheat Sheet|cheat sheet]] is available for those who desire a terse treatment of the material. Please visit [[C-Based_Toolchain_Hardening_Cheat_Sheet|C-Based Toolchain Hardening Cheat Sheet]] for the abbreviated version.

== Wisdom ==

Code '''must''' be correct. It '''should''' be secure. It '''can''' be efficient.

[http://en.wikipedia.org/wiki/Jon_Bentley Dr. Jon Bentley]: ''"If it doesn't have to be correct, I can make it as fast as you'd like it to be"''.

[http://en.wikipedia.org/wiki/Gary_McGraw Dr. Gary McGraw]: ''"Thou shalt not rely solely on security features and functions to build secure software as security is an emergent property of the entire system and thus relies on building and integrating all parts properly"''.

== Configuration ==

Configuration is the first opportunity to configure your project for success. Not only do you have to configure your project to meet reliability and security goals, you must also configure integrated libraries properly. You typically have has three choices. First, you can use auto-configuration utilities if on Linux or Unix. Second, you can write a makefile by hand. This is predominant on Linux, Mac OS X, and Unix, but it applies to Windows as well. Finally, you can use an integrated development environment or IDE.

=== Build Configurations ===

At this stage in the process, you should concentrate on configuring for two builds: Debug and Release. Debug will be used for development and include full instrumentation. Release will be configured for production. The difference between the two settings is usually ''optimization level'' and ''debug level''. A third build configuration is Test, and its usually a special case of Release.

For debug and release builds, the settings are typically diametrically opposed. Debug configurations have no optimizations and full debug information; while Release builds have optimizations and minimal to moderate debug information. In addition, debug code has full assertions and additional library integration, such as mudflaps and malloc guards such as <tt>dmalloc</tt>.

The Test configuration is often a Release configuration that makes everything public for testing and builds a test harness. For example, all member functions public (C++ class) and all interfaces (library or shared object) should be made available for testing. Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

[http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8] introduced an optimization of <tt>-Og</tt>. Note that it is only an optimization, and still requires a customary debug level via <tt>-g</tt>.

==== Debug Builds ====

Debug builds are where developers spend most of their time when vetting problems, so this build should concentrate forces and tools or be a 'force multiplier'. Though many do not realize, debug code is more highly valued than release code because its adorned with additional instrumentation. The debug instrumentation will cause a program to become nearly "self-debugging", and help you catch mistakes such as bad parameters, failed API calls, and memory problems.

Self-debugging code reduces your time during trouble shooting and debugging. Reducing time under the debugger means you have more time for development and feature requests. If code is checked in without debug instrumentation, it should be fixed by adding instrumentation or rejected.

For GCC, optimizations and debug symbolication are controlled through two switches: <tt>-O</tt> and <tt>-g</tt>. You should use the following as part of your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for a minimal debug session:

<pre>-O0 -g3 -ggdb</pre>

<tt>-O0</tt> turns off optimizations and <tt>-g3</tt> ensures maximum debug information is available. You may need to use <tt>-O1</tt> so some analysis is performed. Otherwise, your debug build will be missing a number of warnings not present in release builds. <tt>-g3</tt> ensures maximum debugging information is available for the debug session, including symbolic constants and <tt>#defines</tt>. <tt>-ggdb</tt> includes extensions to help with a debug session under GDB. For completeness, Jan Krachtovil stated <tt>-ggdb</tt> currently has no effect in a private email.

Debug build should also define <tt>DEBUG</tt>, and ensure <tt>NDEBUG</tt> is not defined. <tt>NDEBUG</tt> removes "program diagnostics"; and has undesirable behavior and side effects which discussed below in more detail. The defines should be present for all code, and not just the program. You use it for all code (your program and included libraries) because you need to know how they fail too (remember, you take the bug report - not the third party library).

In addition, you should use other relevant flags, such as <tt>-fno-omit-frame-pointer</tt>. Ensuring a frame pointer exists makes it easier to decode stack traces. Since debug builds are not shipped, its OK to leave symbols in the executable. Programs with debug information do not suffer performance hits. See, for example, [http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]

Finally, you should ensure your project includes additional diagnostic libraries, such as <tt>dmalloc</tt> and [http://code.google.com/p/address-sanitizer/ Address Sanitizer]. A comparison of some memory checking tools can be found at [http://code.google.com/p/address-sanitizer/wiki/ComparisonOfMemoryTools Comparison Of Memory Tools]. If you don't include additional diagostics in debug builds, then you should start using them sinces its OK to find errors you are not looking for.

==== Release Builds ====

Release builds are what your customer receives. They are meant to be run on production hardware and servers, and they should be reliable, secure, and efficient. A stable release build is the product of the hard work and effort during development.

For release builds, you should use the following as part of <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for release builds:

<pre>-On -g2</pre>

<tt>-O''n''</tt> sets optimizations for speed or size (for example, <tt>-Os</tt> or <tt>-O2</tt>), and <tt>-g2</tt> ensure debugging information is created.

Debugging information should be stripped and retained in case of symbolication for a crash report from the field. While not desired, debug information can be left in place without a performance penalty. See ''[http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]'' for details.

Release builds should also define <tt>NDEBUG</tt>, and ensure <tt>DEBUG</tt> is not defined. The time for debugging and diagnostics is over, so users get production code with full optimizations, no "programming diagnostics", and other efficiencies. If you can't optimize or your are performing excessive logging, it usually means the program is not ready for production.

If you have been relying on an <tt>assert</tt> and then a subsequent <tt>abort()</tt>, you have been abusing "program diagnostics" since it has no place in production code. If you want a memory dump, create one so users don't have to worry about secrets and other sensitive information being written to the filesystem and emailed in plain text.

For Windows, you would use <tt>/Od</tt> for debug builds; and <tt>/Ox</tt>, <tt>/O2</tt> or <tt>/Os</tt> for release builds. See Microsoft's [http://msdn.microsoft.com/en-us/library/k1ack8f1.aspx /O Options (Optimize Code)] for details.

==== Test Builds ====

Test builds are used to provide heuristic validation by way of positive and negative test suites. Under a test configuration, all interfaces are tested to ensure they perform to specification and satisfaction. "Satisfaction" is subjective, but it should include no crashing and no trashing of your memory arena, even when faced with negative tests.

Because all interfaces are tested (and not just the public ones), your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> should include:

<pre>-Dprotected=public -Dprivate=public</pre>

You should also change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>.

Nearly everyone gets a positive test right, so no more needs to be said. The negative self tests are much more interesting, and you should concentrate on trying to make your program fail so you can verify its fails gracefully. Remember, a bad guy is not going to be courteous when he attempts to cause your program to fail. And its your project that takes egg on the face by way of a bug report or guest appearance on [http://www.grok.org.uk/full-disclosure/ Full Disclosure] or [http://www.securityfocus.com/archive Bugtraq] - not ''<nowiki><some library></nowiki>'' you included.

=== Auto Tools ===

Auto configuration tools are popular on many Linux and Unix based systems, and the tools include ''Autoconf'', ''Automake'', ''config'', and ''Configure''. The tools work together to produce project files from scripts and template files. After the process completes, your project should be setup and ready to be made with <tt>make</tt>.

When using auto configuration tools, there are a few files of interest worth mentioning. The files are part of the auto tools chain and include <tt>m4</tt> and the various <tt>*.in</tt>, <tt>*.ac</tt> (autoconf), and <tt>*.am</tt> (automake) files. At times, you will have to open them, or the resulting makefiles, to tune the "stock" configuration.

There are three downsides to the command line configuration tools in the toolchain: (1) they often ignore user requests, (2) they cannot create configurations, and (3) security is often not a goal.

To demonstrate the first issue, confider your project with the following: <tt>configure CFLAGS="-Wall -fPIE" CXXFLAGS="-Wall -fPIE" LDFLAGS="-pie"</tt>. You will probably find the auto tools ignored your request, which means the command below will not produce expected results. As a work around, you will have to open an <tt>m4</tt> scripts, <tt>Makefile.in</tt> or <tt>Makefile.am</tt> and fix the configuration.

<pre>$ configure CFLAGS="-Wall -Wextra -Wconversion -fPIE -Wno-unused-parameter
-Wformat=2 -Wformat-security -fstack-protector-all -Wstrict-overflow"
LDFLAGS="-pie -z,noexecstack -z,noexecheap -z,relro -z,now"</pre>

For the second point, you will probably be disappointed to learn [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html Automake does not support the concept of configurations]. Its not entirely Autoconf's or Automake's fault - ''Make'' and its inability to detect changes is the underlying problem. Specifically, ''Make'' only [http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html checks modification times of prerequisites and targets], and does not check things like <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>. The net effect is you will not receive expected results when you issue <tt>make debug</tt> and then <tt>make test</tt> or <tt>make release</tt>.

Finally, you will probably be disappointed to learn tools such as Autoconf and Automake miss many security related opportunities and ship insecure out of the box. There are a number of compiler switches and linker flags that improve the defensive posture of a program, but they are not 'on' by default. Tools like Autoconf - which are supposed to handle this situation - often provides setting to serve the lowest of all denominators.

A recent discussion on the Automake mailing list illuminates the issue: ''[https://lists.gnu.org/archive/html/autoconf/2012-12/msg00038.html Enabling compiler warning flags]''. Attempts to improve default configurations were met with resistance and no action was taken. The resistance is often of the form, "<nowiki><some useful warning></nowiki> also produces false positives" or "<nowiki><some obscure platform></nowiki> does not support <nowiki><established security feature></nowiki>". Its noteworthy that David Wheeler, the author of ''[http://www.dwheeler.com/secure-programs/ Secure Programming for Linux and Unix HOWTO]'', was one of the folks trying to improve the posture.

=== Makefiles ===

Make is one of the earliest build systems dating back to the 1970s. Its available on Linux, Mac OS X and Unix, so you will frequently encounter projects using it. Unfortunately, Make has a number of short comings (''[http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful]'' and ''[http://www.conifersystems.com/whitepapers/gnu-make/ What’s Wrong With GNU make?]''), and can cause some discomfort. Despite issues with Make, ESAPI C++ uses Make primarily for three reasons: first, its omnipresent; second, its easier to manage than the Auto Tools family; and third, <tt>libtool</tt> was out of the question.

Consider what happens when you: (1) type <tt>make debug</tt>, and then type <tt>make release</tt>. Each build would require different <tt>CFLAGS</tt> due to optimizations and level of debug support. In your makefile, you would extract the relevant target and set <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> similar to below (taken from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/Makefile ESAPI C++ Makefile]):

<pre># Makefile
DEBUG_GOALS = $(filter $(MAKECMDGOALS), debug)
ifneq ($(DEBUG_GOALS),)
WANT_DEBUG := 1
WANT_TEST := 0
WANT_RELEASE := 0
endif
…

ifeq ($(WANT_DEBUG),1)
ESAPI_CFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
ESAPI_CXXFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
endif

ifeq ($(WANT_RELEASE),1)
ESAPI_CFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
ESAPI_CXXFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
endif

ifeq ($(WANT_TEST),1)
ESAPI_CFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
ESAPI_CXXFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
endif
…

# Merge ESAPI flags with user supplied flags. We perform the extra step to ensure
# user options follow our options, which should give user option's a preference.
override CFLAGS := $(ESAPI_CFLAGS) $(CFLAGS)
override CXXFLAGS := $(ESAPI_CXXFLAGS) $(CXXFLAGS)
override LDFLAGS := $(ESAPI_LDFLAGS) $(LDFLAGS)
…</pre>

Make will first build the program in a debug configuration for a session under the debugger using a rule similar to:

<pre>%.cpp:%.o:
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@</pre>

When you want the release build, Make will do nothing because it considers everything up to date despite the fact <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> have changed. Hence, your program will actually be in a debug configuration and risk a <tt>SIGABRT</tt> at runtime because debug instrumentation is present (recall <tt>assert</tt> calls <tt>abort()</tt> when <tt>NDEBUG</tt> is '''not''' defined). In essence, you have DoS'd yourself due to <tt>make</tt>.

In addition, many projects do not honor the user's command line. ESAPI C++ does its best to ensure a user's flags are honored via <tt>override</tt> as shown above, but other projects do not. For example, consider a project that should be built with Position Independent Executable (PIE or ASLR) enabled and data execution prevention (DEP) enabled. Dismissing user settings combined with insecure out of the box settings (and not picking them up during auto-setup or auto-configure) means a program built with the following will likely have neither defense:

<pre>$ make CFLAGS="-fPIE" CXXFLAGS="-fPIE" LDFLAGS="-pie -z,noexecstack, -z,noexecheap"</pre>

Defenses such as ASLR and DEP are especially important on Linux because [http://linux.die.net/man/5/elf Data Execution - not Prevention - is the norm].

=== Integration ===

Project level integration presents opportunities to harden your program or library with domain specific knowledge. For example, if the platform supports Position Independent Executables (PIE or ASLR) and data execution prevention (DEP), then you should integrate with it. The consequences of not doing so could result in exploitation. As a case in point, see KingCope's 0-days for MySQL in December, 2012 (CVE-2012-5579 and CVE-2012-5612, among others). Integration with platform security would have neutered a number of the 0-days.

You also have the opportunity to include helpful libraries that are not need for business logic support. For example, if you are working on a platform with [http://dmalloc.com DMalloc] or [http://code.google.com/p/address-sanitizer/ Address Sanitizer], you should probably use it in your debug builds. For Ubuntu, DMalloc available from the package manager and can be installed with <tt>sudo apt-get install libdmalloc5</tt>. For Apple platforms, its available as a scheme option (see [[#Clang/Xcode|Clang/Xcode]] below). Address Sanitizer is available in [http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8 and above] for many platforms.

In addition, project level integration is an opportunity to harden third party libraries you chose to include. Because you chose to include them, you and your users are responsible for them. If you or your users endure a SP800-53 audit, third party libraries will be in scope because the supply chain is included (specifically, item SA-12, Supply Chain Protection). The audits are not limited to those in the US Federal arena - financial institutions perform reviews too. A perfect example of violating this guidance is [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525], which was due to [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library].

Another example is including OpenSSL. You know (1) [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 is insecure], (2) [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 is insecure], and (3) [http://arstechnica.com/security/2012/09/crime-hijacks-https-sessions/ compression is insecure] (among others). In addition, suppose you don't use hardware and engines, and only allow static linking. Given the knowledge and specifications, you would configure the OpenSSL library as follows:

<pre>$ Configure darwin64-x86_64-cc -no-hw -no-engines -no-comp -no-shared -no-dso -no-sslv2 -no-sslv3 --openssldir=…</pre>

''Note Well'': you might want engines, especially on Ivy Bridge microarchitectures (3rd generation Intel Core i5 and i7 processors). To have OpenSSL use the processor's random number generator (via the of <tt>rdrand</tt> instruction), you will need to call OpenSSL's <tt>ENGINE_load_rdrand()</tt> function and then <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. See [http://wiki.opensslfoundation.com/index.php/Random_Numbers OpenSSL's Random Numbers] for details.

If you configure without the switches, then you will likely have vulnerable code/libraries and risk failing an audit. If the program is a remote server, then the following command will reveal if compression is active on the channel:

<pre>$ echo "GET / HTTP1.0" | openssl s_client -connect <nowiki>example.com:443</nowiki></pre>

<tt>nm</tt> or <tt>openssl s_client</tt> will show that compression is enabled in the client. In fact, any symbol within the <tt>OPENSSL_NO_COMP</tt> preprocessor macro will bear witness since <tt>-no-comp</tt> is translated into a <tt>CFLAGS</tt> define.

<pre>$ nm /usr/local/ssl/iphoneos/lib/libcrypto.a 2>/dev/null | egrep -i "(COMP_CTX_new|COMP_CTX_free)"
0000000000000110 T COMP_CTX_free
0000000000000000 T COMP_CTX_new</pre>

Even more egregious is the answer given to auditors who specifically ask about configurations and protocols: "we don't use weak/wounded/broken ciphers" or "we follow best practices." The use of compression tells the auditor that you are using wounded protocol in an insecure configuration and you don't follow best practices. That will likely set off alarm bells, and ensure the auditor dives deeper on more items.

== Preprocessor ==

The preprocessor is crucial to setting up a project for success. The C committee provided one macro - <tt>NDEBUG</tt> - and the macro can be used to derive a number of configurations and drive engineering processes. Unfortunately, the committee also left many related items to chance, which has resulted in programmers abusing builtin facilities. This section will help you set up you projects to integrate well with other projects and ensure reliability and security.

There are three topics to discuss when hardening the preprocessor. The first is well defined configurations which produce well defined behaviors, the second is useful behavior from assert, and the third is proper use of macros when integrating vendor code and third party libraries.

=== Configurations ===

To remove ambiguity, you should recognize two configurations: Release and Debug. Release is for production code on live servers, and its behavior is requested via the C/C++ <tt>NDEBUG</tt> macro. Its also the only macro observed by the C and C++ Committees and Posix. Diametrically opposed to release is Debug. While there is a compelling argument for <tt>!defined(NDEBUG)</tt>, you should have an explicit macro for the configuration and that macro should be <tt>DEBUG</tt>. This is because vendors and outside libraries use <tt>DEBUG</tt> (or similar) macro for their configuration. For example, Carnegie Mellon's Mach kernel uses <tt>DEBUG</tt>, Microsoft's CRT uses [http://msdn.microsoft.com/en-us/library/ww5t02fa%28v=vs.71%29.aspx<tt>_DEBUG</tt>], and Wind River Workbench uses <tt>DEBUG_MODE</tt>.

In addition to <tt>NDEBUG</tt> (Release) and <tt>DEBUG</tt> (Debug), you have two additional cross products: both are defined or neither are defined. Defining both should be an error, and defining neither should default to a release configuration. Below is from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/esapi/EsapiCommon.h ESAPI C++ EsapiCommon.h], which is the configuration file used by all source files:

<pre>// Only one or the other, but not both
#if (defined(DEBUG) || defined(_DEBUG)) && (defined(NDEBUG) || defined(_NDEBUG))
# error Both DEBUG and NDEBUG are defined.
#endif

// The only time we switch to debug is when asked. NDEBUG or {nothing} results
// in release build (fewer surprises at runtime).
#if defined(DEBUG) || defined(_DEBUG)
# define ESAPI_BUILD_DEBUG 1
#else
# define ESAPI_BUILD_RELEASE 1
#endif</pre>

When <tt>DEBUG</tt> is in effect, your code should receive full debug instrumentation, including the full force of assertions.

=== ASSERT ===

Asserts will help you create self-debugging code by helping you find the point of first failure quickly and easily. Asserts should be used throughout your program, including parameter validation, return value checking and program state. The <tt>assert</tt> will silently guard your code through its lifetime. It will always be there, even when not debugging a specific component of a module. If you have thorough code coverage, you will spend less time debugging and more time developing because programs will debug themselves.

To use asserts effectively, you should assert everything. That includes parameters upon entering a function, return values from function calls, and any program state. Everywhere you place an <tt>if</tt> statement for validation or checking, you should have an assert. Everywhere you have an <tt>assert</tt> for validation or checking, you should have an <tt>if</tt> statement. They go hand-in-hand.

If you are still using <tt>printf</tt>'s, then you have an opportunity for improvement. In the time it takes for you to write a <tt>printf</tt> or <tt>NSLog</tt> statement, you could have written an <tt>assert</tt>. Unlike the <tt>printf</tt> or <tt>NSLog</tt> which are often removed when no longer needed, the <tt>assert</tt> stays active forever. Remember, this is all about finding the point of first failure quickly so you can spend your time doing other things.

There is one problem with using asserts - [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html Posix states <tt>assert</tt> should call <tt>abort()</tt>] if <tt>NDEBUG</tt> is '''not''' defined. When debugging, <tt>NDEBUG</tt> will never be defined since you want the "program diagnostics" (quote from the Posix description). The behavior makes <tt>assert</tt> and its accompanying <tt>abort()</tt> completely useless for development. The result of "program diagnostics" calling <tt>abort()</tt> due to standard C/C++ behavior is disuse - developers simply don't use them. Its incredibly bad for the development community because self-debugging programs can help eradicate so many stability problems.

Since self-debugging programs are so powerful, you will have to have to supply your own assert and signal handler with improved behavior. Your assert will exchange auto-aborting behavior for auto-debugging behavior. The auto-debugging facility will ensure the debugger snaps when a problem is detected, and you will find the point of first failure quickly and easily.

ESAPI C++ supplies its own assert with the behavior described above. In the code below, <tt>ASSERT</tt> raises <tt>SIGTRAP</tt> when in effect or it evaluates to <tt>void</tt> in other cases.

<pre>// A debug assert which should be sprinkled liberally. This assert fires and then continues rather
// than calling abort(). Useful when examining negative test cases from the command line.
#if (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_STARNIX))
# define ESAPI_ASSERT1(exp) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
# define ESAPI_ASSERT2(exp, msg) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< ": \"" << (msg) << "\"" << std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
#elif (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_WINDOWS))
# define ESAPI_ASSERT1(exp) assert(exp)
# define ESAPI_ASSERT2(exp, msg) assert(exp)
#else
# define ESAPI_ASSERT1(exp) ((void)(exp))
# define ESAPI_ASSERT2(exp, msg) ((void)(exp))
#endif

#if !defined(ASSERT)
# define ASSERT(exp) ESAPI_ASSERT1(exp)
#endif</pre>

At program startup, a <tt>SIGTRAP</tt> handler will be installed if one is not provided by another component:

<pre>struct DebugTrapHandler
{
DebugTrapHandler()
{
struct sigaction new_handler, old_handler;

do
{
int ret = 0;

ret = sigaction (SIGTRAP, NULL, &old_handler);
if (ret != 0) break; // Failed

// Don't step on another's handler
if (old_handler.sa_handler != NULL) break;

new_handler.sa_handler = &DebugTrapHandler::NullHandler;
new_handler.sa_flags = 0;

ret = sigemptyset (&new_handler.sa_mask);
if (ret != 0) break; // Failed

ret = sigaction (SIGTRAP, &new_handler, NULL);
if (ret != 0) break; // Failed

} while(0);
}

static void NullHandler(int /*unused*/) { }

};

// We specify a relatively low priority, to make sure we run before other CTORs
// http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#C_002b_002b-Attributes
static const DebugTrapHandler g_dummyHandler __attribute__ ((init_priority (110)));</pre>

On a Windows platform, you would call <tt>_set_invalid_parameter_handler</tt> (and possibly <tt>set_unexpected</tt> or <tt>set_terminate</tt>) to install a new handler.

Live hosts running production code should always define <tt>NDEBUG</tt> (i.e., release configuration), which means they do not assert or auto-abort. Auto-abortion is not acceptable behavior, and anyone who asks for the behavior is completely abusing the functionality of "program diagnostics". If a program wants a core dump, then it should create the dump rather than crashing.

For more reading on asserting effectively, please see one of John Robbin's books, such as ''[http://www.amazon.com/dp/0735608865 Debugging Applications]''. John is a legendary bug slayer in Windows circles, and he will show you how to do nearly everything, from debugging a simple program to bug slaying in multithreaded programs.

=== Additional Macros ===

Additional macros include any macros needed to integrate properly and securely. It includes integrating the program with the platform (for example MFC or Cocoa/CocoaTouch) and libraries (for example, Crypto++ or OpenSSL). It can be a challenge because you have to have proficiency with your platform and all included libraries and frameworks. The list below illustrates the level of detail you will need when integrating.

Though Boost is missing from the list, it appears to lack recommendations, additional debug diagnostics, and a hardening guide. See ''[http://stackoverflow.com/questions/14927033/boost-hardening-guide-preprocessor-macros BOOST Hardening Guide (Preprocessor Macros)]'' for details. In addition, Tim Day points to ''[http://boost.2283326.n4.nabble.com/boost-build-should-we-not-define-SECURE-SCL-0-by-default-for-all-msvc-toolsets-td2654710.html <nowiki>[boost.build] should we not define _SECURE_SCL=0 by default for all msvc toolsets</nowiki>]'' for a recent discussion related to hardening (or lack thereof).

In addition to what you should define, defining some macros and undefining others should trigger a security related defect. For example, <tt>-U_FORTIFY_SOURCES</tt> on Linux and <tt>_CRT_SECURE_NO_WARNINGS=1</tt>, <tt>_SCL_SECURE_NO_WARNINGS</tt>, <tt>_ATL_SECURE_NO_WARNINGS</tt> or <tt>STRSAFE_NO_DEPRECATE</tt> on Windows.

{| border="1"

|-style="background:#DADADA"
!Platform/Library!!Debug!!Release
|+ Table 1: Additional Platform/Library Macros

|-
|width="175pt"|All
|width="250pt"|DEBUG=1
|width="250pt"|NDEBUG=1

|-
|Linux
|_GLIBCXX_DEBUG=1a
|_FORTIFY_SOURCE=2

|-
|Android
|NDK_DEBUG=1
|_FORTIFY_SOURCE=1 (4.2 and above) 
<tt>#define LOGI(...)</tt> (define to nothing, preempt logging)

|-
|Cocoa/CocoaTouch
|
|NS_BLOCK_ASSERTIONS=1 
<tt>#define NSLog(...)</tt> (define to nothing, preempt ASL)

|-
|SafeInt
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1

|-
|Microsoft
|_DEBUG=1, STRICT, 
_SECURE_SCL=1, _HAS_ITERATOR_DEBUGGING=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1
|STRICT 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1

|-
|Microsoft ATL & MFC
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS

|-
|STLPort
|_STLP_DEBUG=1, _STLP_USE_DEBUG_LIB=1 
_STLP_DEBUG_ALLOC=1, _STLP_DEBUG_UNINITIALIZED=1
|

|-
|SQLite
|SQLITE_DEBUG, SQLITE_MEMDEBUG 
SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc
|SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc

|-
|SQLCipher
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3d
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3d

|}

a Be careful with <tt>_GLIBCXX_DEBUG</tt> when using pre-compiled libraries such as Boost from a distribution. There are ABI incompatibilities, and the result will likely be a crash. You will have to compile Boost with <tt>_GLIBCXX_DEBUG</tt> or omit <tt>_GLIBCXX_DEBUG</tt>.

b SQLite secure deletion zeroizes memory on destruction. Define as required, and always define in US Federal since zeroization is required for FIPS 140-2, Level 1.

c ''N'' is 0644 by default, which means everyone has some access.

d Force temporary tables into memory (no unencrypted data to disk).

== Compiler and Linker ==

Compiler writers provide a rich set of warnings from the analysis of code during compilation. Both GCC and Visual Studio have static analysis capabilities to help find mistakes early in the development process. The built in static analysis capabilities of GCC and Visual Studio are usually sufficient to ensure proper API usage and catch a number of mistakes such as using an uninitialized variable or comparing a negative signed int and a positive unsigned int.

As a concrete example, (and for those not familiar with C/C++ promotion rules), a warning will be issued if a signed integer is promoted to an unsigned integer and then compared because a side effect is <tt>-1 > 1</tt> after promotion! GCC and Visual Studio will not currently catch, for example, SQL injections and other tainted data usage. For that, you will need a tool designed to perform data flow analysis or taint analysis.

Some in the development community resist static analysis or refute its results. For example, when static analysis warned the Linux kernel's <tt>sys_prctl</tt> was comparing an unsigned value against less than zero, Jesper Juhl offered a patch to clean up the code. Linus Torvalds howled “No, you don't do this… GCC is crap” (referring to compiling with warnings). For the full discussion, see ''[http://linux.derkeiler.com/Mailing-Lists/Kernel/2006-11/msg08325.html <nowiki>[PATCH] Don't compare unsigned variable for <0 in sys_prctl()</nowiki>]'' from the Linux Kernel mailing list.

The following sections will detail steps for three platforms. First is a typical GNU Linux based distribution offering GCC and Binutils, second is Clang and Xcode, and third is modern Windows platforms.

=== Distribution Hardening ===

Before discussing GCC and Binutils, it would be a good time to point out some of the defenses discussed below are all ready present in a distribution. Unfortunately, its design by committee, so what is present is usually only a mild variation of what is available (this way, everyone is mildly offended). For those who are purely worried about performance, you might be surprised to learn you have already taken the small performance hint without even knowing.

Linux and BSD distributions often apply some hardening without intervention via ''[http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html GCC Spec Files]''. If you are using Debian, Ubuntu, Linux Mint and family, see ''[http://wiki.debian.org/Hardening Debian Hardening]''. For Red Hat and Fedora systems, see ''[http://lists.fedoraproject.org/pipermail/devel-announce/2011-August/000821.html New hardened build support (coming) in F16]''. Gentoo users should visit ''[http://www.gentoo.org/proj/en/hardened/ Hardened Gentoo]''.

You can see the settings being used by a distribution via <tt>gcc -dumpspecs</tt>. From Linux Mint 12 below, -fstack-protector (but not -fstack-protector-all) is used by default.

<pre>$ gcc -dumpspecs
…
*link_ssp: %{fstack-protector:}

*ssp_default: %{!fno-stack-protector:%{!fstack-protector-all: %{!ffreestanding:%{!nostdlib:-fstack-protector}}}}
…</pre>

The “SSP” above stands for Stack Smashing Protector. SSP is a reimplementation of Hiroaki Etoh's work on IBM Pro Police Stack Detector. See Hiroaki Etoh's patch ''[http://gcc.gnu.org/ml/gcc-patches/2001-06/msg01753.html gcc stack-smashing protector]'' and IBM's ''[http://www.research.ibm.com/trl/projects/security/ssp/ GCC extension for protecting applications from stack-smashing attacks]'' for details.

=== GCC/Binutils ===

GCC (the compiler collection) and Binutils (the assemblers, linkers, and other tools) are separate projects that work together to produce a final executable. Both the compiler and linker offer options to help you write safer and more secure code. The linker will produce code which takes advantage of platform security features offered by the kernel and PaX, such as no-exec stacks and heaps (NX) and Position Independent Executable (PIE).

The table below offers a set of compiler options to build your program. Static analysis warnings help catch mistakes early, while the linker options harden the executable at runtime. In the table below, “GCC” should be loosely taken as “non-ancient distributions.” While the GCC team considers 4.2 ancient, you will still encounter it on Apple and BSD platforms due to changes in GPL licensing around 2007. Refer to ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Option Summary]'', ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html Options to Request or Suppress Warnings]'' and ''[http://sourceware.org/binutils/docs-2.21/ld/Options.html Binutils (LD) Command Line Options]'' for usage details.

Noteworthy of special mention are <tt>-fno-strict-overflow</tt> and <tt>-fwrapv</tt>a. The flags ensure the compiler does not remove statements that result in overflow or wrap. If your program only runs correctly using the flags, it is likely violating C/C++ rules on overflow and illegal. If the program is illegal due to overflow or wrap checking, you should consider using [http://code.google.com/p/safe-iop/ safe-iop] for C or David LeBlanc's [http://safeint.codeplex.com SafeInt] in C++.

For a project compiled and linked with hardened settings, some of those settings can be verified with the [http://www.trapkit.de/tools/checksec.html Checksec] tool written by Tobias Klein. The <tt>checksec.sh</tt> script is designed to test standard Linux OS and PaX security features being used by an application. See the [http://www.trapkit.de/tools/checksec.html Trapkit] web page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 2: GCC C Warning Options

|-
|width="200pt"|<nowiki>-Wall -Wextra</nowiki>
|width="75t"|GCC
|width="425pt"|Enables many warnings (despite their names, all and extra do not turn on all warnings).a

|-
|<nowiki>-Wconversion</nowiki>
|GCC
|Warn for implicit conversions that may alter a value (includes -Wsign-conversion).

|-
|<nowiki>-Wsign-conversion</nowiki>
|GCC
|Warn for implicit conversions that may change the sign of an integer value, such as assigning a signed integer to an unsigned integer (<tt>-1 > 1</tt> after promotion!).

|-
|<nowiki>-Wcast-align</nowiki>
|GCC
|Warn for a pointer cast to a type which has a different size, causing an invalid alignment and subsequent bus error on ARM processors.

|-
|<nowiki>-Wformat=2 -Wformat-security</nowiki>
|GCC
|Increases warnings related to possible security defects, including incorrect format specifiers.

|-
|<nowiki>-fno-common</nowiki>
|GCC
|Prevent global variables being simultaneously defined in different object files.

|-
|<nowiki>-fstack-protector or -fstack-protector-all</nowiki>
|GCC
|Stack Smashing Protector (SSP). Improves stack layout and adds a guard to detect stack based buffer overflows.b

|-
|<nowiki>-fno-omit-frame-pointer</nowiki>
|GCC
|Improves backtraces for post-mortem analysis

|-
|<nowiki>-Wmissing-prototypes and -Wmissing-declarations</nowiki>
|GCC
|Warn if a global function is defined without a prototype or declaration.

|-
|<nowiki>-Wstrict-prototypes</nowiki>
|GCC
|Warn if a function is declared or defined without specifying the argument types.

|-
|<nowiki>-Wstrict-overflow</nowiki>
|GCC 4.2
|Warn about optimizations taken due to <nowiki>[undefined]</nowiki> signed integer overflow assumptions.

|-
|<nowiki>-Wtrampolines</nowiki>
|GCC 4.3
|Warn about trampolines generated for pointers to nested functions. Trampolines require executable stacks.

|-
|<nowiki>-fsanitize=address</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/address-sanitizer/ AddressSanitizer], a fast memory error detector. Memory access instructions will be instrumented to help detect heap, stack, and global buffer overflows; as well as use-after-free bugs.

|-
|<nowiki>-fsanitize=thread</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/data-race-test/wiki/ThreadSanitizer ThreadSanitizer], a fast data race detector. Memory access instructions will be instrumented to detect data race bugs.

|-
|<nowiki>-Wl,-z,nodlopen and -Wl,-z,nodump</nowiki>
|Binutils 2.10
|Reduces the ability of an attacker to load, manipulate, and dump shared objects.

|-
|<nowiki>-Wl,-z,noexecstack and -Wl,-z,noexecheap</nowiki>
|Binutils 2.14
|Data Execution Prevention (DEP). ELF headers are marked with PT_GNU_STACK and PT_GNU_HEAP.

|-
|<nowiki>-Wl,-z,relro</nowiki>
|Binutils 2.15
|Helps remediate Global Offset Table (GOT) attacks on executables.

|-
|<nowiki>-Wl,-z,now</nowiki>
|Binutils 2.15
|Helps remediate Procedure Linkage Table (PLT) attacks on executables.

|-
|<nowiki>-fPIC</nowiki>
|Binutils
|Position Independent Code. Used for libraries and shared objects. Both -fPIC (compiler) and -shared (linker) are required.

|-
|<nowiki>-fPIE</nowiki>
|Binutils 2.16
|Position Independent Executable (ASLR). Used for programs. Both -fPIE (compiler) and -pie (linker) are required.

|}

a Unlike Clang and -Weverything, GCC does not provide a switch to truly enable all warnings. 
b -fstack-protector guards functions with high risk objects such as C strings, while -fstack-protector-all guards all objects.

Additional C++ warnings which can be used include the following in Table 3. See ''[http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html GCC's Options Controlling C++ Dialect]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 3: GCC C++ Warning Options

|-
|width="200pt"|<nowiki>-Woverloaded-virtual</nowiki>
|width="425pt"|Warn when a function declaration hides virtual functions from a base class.

|-
|<nowiki>-Wreorder</nowiki>
|Warn when the order of member initializers given in the code does not match the order in which they must be executed.

|-
|<nowiki>-Wsign-promo</nowiki>
|Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size.

|-
|<nowiki>-Wnon-virtual-dtor</nowiki>
|Warn when a class has virtual functions and an accessible non-virtual destructor.

|-
|<nowiki>-Weffc++</nowiki>
|Warn about violations of the following style guidelines from Scott Meyers' ''[http://www.aristeia.com/books.html Effective C++, Second Edition]'' book.

|}

And additional Objective C warnings which are often useful include the following. See ''[http://gcc.gnu.org/onlinedocs/gcc/Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html Options Controlling Objective-C and Objective-C++ Dialects]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 4: GCC Objective C Warning Options

|-
|width="200pt"|<nowiki>-Wstrict-selector-match</nowiki>
|width="425pt"|Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type id or Class.

|-
|<nowiki>-Wundeclared-selector</nowiki>
|Warn if a <tt>@selector(…)</tt> expression referring to an undeclared selector is found.

|}

The use of aggressive warnings will produce spurious noise. The noise is a tradeoff - you can learn of potential problems at the cost of wading through some chaff. The following will help reduces spurious noise from the warning system:

* -Wno-unused-parameter (GCC)
* -Wno-type-limits (GCC 4.3)
* -Wno-tautological-compare (Clang)

Finally, a simple version based Makefile example is shown below. This is different than feature based makefile produced by auto tools (which will test for a particular feature and then define a symbol or configure a template file). Not all platforms use all options and flags. To address the issue you can pursue one of two strategies. First, you can ship with a weakened posture by servicing the lowest common denominator; or you can ship with everything in force. In the latter case, those who don't have a feature available will edit the makefile to accommodate their installation.

<pre>CXX=g++
EGREP = egrep
…

GCC_COMPILER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version')
GCC41_OR_LATER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version (4\.[1-9]|[5-9])')
…

GNU_LD210_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[0-9]|2\.[2-9])')
GNU_LD214_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[4-9]|2\.[2-9])')
…

ifeq ($(GCC_COMPILER),1)
MY_CC_FLAGS += -Wall -Wextra -Wconversion
MY_CC_FLAGS += -Wformat=2 -Wformat-security
MY_CC_FLAGS += -Wno-unused-parameter
endif

ifeq ($(GCC41_OR_LATER),1)
MY_CC_FLAGS += -fstack-protector-all
endif

ifeq ($(GCC42_OR_LATER),1)
MY_CC_FLAGS += -Wstrict-overflow
endif

ifeq ($(GCC43_OR_LATER),1)
MY_CC_FLAGS += -Wtrampolines
endif

ifeq ($(GNU_LD210_OR_LATER),1)
MY_LD_FLAGS += -z,nodlopen -z,nodump
endif

ifeq ($(GNU_LD214_OR_LATER),1)
MY_LD_FLAGS += -z,noexecstack -z,noexecheap
endif

ifeq ($(GNU_LD215_OR_LATER),1)
MY_LD_FLAGS += -z,relro -z,now
endif

ifeq ($(GNU_LD216_OR_LATER),1)
MY_CC_FLAGS += -fPIE
MY_LD_FLAGS += -pie
endif

# Use 'override' to honor the user's command line
override CFLAGS := $(MY_CC_FLAGS) $(CFLAGS)
override CXXFLAGS := $(MY_CC_FLAGS) $(CXXFLAGS)
override LDFLAGS := $(MY_LD_FLAGS) $(LDFLAGS)
…</pre>

=== Clang/Xcode ===

[http://clang.llvm.org Clang] and [http://llvm.org LLVM] have been aggressively developed since Apple lost its GPL compiler back in 2007 (due to Tivoization which resulted in GPLv3). Since that time, a number of developers and Goggle have joined the effort. While Clang will consume most (all?) GCC/Binutil flags and switches, the project supports a number of its own options, including a static analyzer. In addition, Clang is relatively easy to build with additional diagnostics, such as Dr. John Regher and Peng Li's [http://embed.cs.utah.edu/ioc/ Integer Overflow Checker (IOC)].

IOC is incredibly useful, and has found bugs in a number of projects, from the Linux Kernel (<tt>include/linux/bitops.h</tt>, still unfixed), SQLite, PHP, Firefox (many still unfixed), LLVM, and Python. Future version of Clang (Clang 3.3 and above) will allow you to enable the checks out of the box with <tt>-fsanitize=integer</tt> and <tt>-fsanitize=shift</tt>.

Clang options can be found at [http://clang.llvm.org/docs/UsersManual.html Clang Compiler User’s Manual]. Clang does include an option to turn on all warnings - <tt>-Weverything</tt>. Use it with care but use it regularly since you will get back a lot of noise and issues you missed. For example, add <tt>-Weverything</tt> for production builds and make non-spurious issues a quality gate. Under Xcode, simply add <tt>-Weverything</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>.

In addition to compiler warnings, both static analysis and additional security checks can be performed. Reading on Clang's static analysis capabilities can be found at [http://clang-analyzer.llvm.org Clang Static Analyzer]. Figure 1 below shows some of the security checks utilized by Xcode.

{| align="center"
| [[File:toolchan-hardening-11.png|thumb|450px|Figure 1: Clang/LLVM and Xcode options]]
|}

=== Visual Studio ===

Visual Studio offers a convenient Integrated Development Environment (IDE) for managing solutions and their settings. the section called “Visual Studio Options” discusses option which should be used with Visual Studio, and the section called “Project Properties” demonstrates incorporating those options into a solution's project.

The table below lists the compiler and linker switches which should be used under Visual Studio. Refer to Howard and LeBlanc's Writing Secure Code (Microsoft Press) for a detailed discussion; or ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]'' in Security Briefs by Michael Howard. In the table below, “Visual Studio” refers to nearly all versions of the development environment, including Visual Studio 5.0 and 6.0.

For a project compiled and linked with hardened settings, those settings can be verified with BinScope. BinScope is a verification tool from Microsoft that analyzes binaries to ensure that they have been built in compliance with Microsoft's Security Development Lifecycle (SDLC) requirements and recommendations. See the ''[https://www.microsoft.com/download/en/details.aspx?id=11910 BinScope Binary Analyzer]'' download page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 5: Visual Studio Warning Options

|-
|width="150pt"|<nowiki>/W4</nowiki>
|width="100pt"|Visual Studio
|width="350pt"|Warning level 4, which includes most warnings.

|-
|<nowiki>/WAll</nowiki>
|Visual Studio 2003
|Enable all warnings, including those off by default.a

|-
|<nowiki>/GS</nowiki>
|Visual Studio 2003
|Adds a security cookie (guard or canary) on the stack before the return address buffer stack based for overflow checks.a

|-
|<nowiki>/SafeSEH</nowiki>
|Visual Studio 2003
|Safe structured exception handling to remediate SEH overwrites.

|-
|<nowiki>/analyze</nowiki>
|Visual Studio 2005
|Enterprise code analysis (freely available with Windows SDK for Windows Server 2008 and .NET Framework 3.5).

|-
|<nowiki>/NXCOMPAT</nowiki>
|Visual Studio 2005
|Data Execution Prevention (DEP).

|-
|<nowiki>/dynamicbase</nowiki>
|Visual Studio 2005 SP1
|Address Space Layout Randomization (ASLR).

|-
|<nowiki>strict_gs_check</nowiki>
|Visual Studio 2005 SP1
|Aggressively applies stack protections to a source file to help detect some categories of stack based buffer overruns.b

|}

aSee Jon Sturgeon's discussion of the switch at ''[https://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx Off By Default Compiler Warnings in Visual C++]''. 
aWhen using /GS, there are a number of circumstances which affect the inclusion of a security cookie. For example, the guard is not used if there is no buffer in the stack frame, optimizations are disabled, or the function is declared naked or contains inline assembly. 
b<tt>#pragma strict_gs_check(on)</tt> should be used sparingly, but is recommend in high risk situations, such as when a source file parses input from the internet.

=== Warn Suppression ===

From the tables above, a lot of warnings have been enabled to help detect possible programming mistakes. The potential mistakes are detected via compiler which carries around a lot of contextual information during its code analysis phase. At times, you will receive spurious warnings because the compiler is not ''that'' smart. Its understandable and even a good thing (how would you like to be out of a job because a program writes its own programs?). At times you will have to learn how to work with the compiler's warning system to suppress warnings. Notice what was not said: turn off the warnings.

Suppressing warnings placates the compiler for spurious noise so you can get to the issues that matter (you are separating the wheat from the chaff). This section will offer some hints and point out some potential minefields. First is an unused parameter (for example, <tt>argc</tt> or <tt>argv</tt>). Suppressing unused parameter warnings is especially helpful for C++ and interface programming, where parameters are often unused. For this warning, simply define an "UNUSED" macro and warp the parameter:

<pre>#define UNUSED_PARAMETER(x) ((void)x)
…

int main(int argc, char* argv[])
{
UNUSED_PARAMETER(argc);
UNUSED_PARAMETER(argv);
…
}</pre>

A potential minefield lies near "comparing unsigned and signed" values, and <tt>-Wconversion</tt> will catch it for you. This is because C/C++ promotion rules state the signed value will be promoted to an unsigned value and then compared. That means <tt>-1 > 1</tt> after promotion! To fix this, you cannot blindly cast - you must first range test the value:

<pre>int x = GetX();
unsigned int y = GetY();

ASSERT(x >= 0);
if(!(x >= 0))
throw runtime_error("WTF??? X is negative.");

if(static_cast<unsigned int>(x) > y)
cout << "x is greater than y" << endl;
else
cout << "x is not greater than y" << endl;</pre>

Notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>x</tt>. Just run the program and wait for it to tell you there is a problem. If there is a problem, the program will snap the debugger (and more importantly, not call a useless <tt>abort()</tt> as specified by Posix). It beats the snot out of <tt>printf</tt> that are removed when no longer needed or pollute outputs.

Another conversion problem you will encounter conversion between types, and <tt>-Wconversion</tt> will also catch it for you. The following will always have an opportunity to fail, and should light up like a Christmas tree:

<pre>struct sockaddr_in addr;
…

addr.sin_port = htons(atoi(argv[2]));</pre>

The following would probably serve you much better. Notice <tt>atoi</tt> and fiends are not used because they can silently fail. In addition, the code is instrumented so you don't need to waste a lot of time debugging potential problems:

<pre>const char* cstr = GetPortString();

ASSERT(cstr != NULL);
if(!(cstr != NULL))
throw runtime_error("WTF??? Port string is not valid.");

istringstream iss(cstr);
long long t = 0;
iss >> t;

ASSERT(!(iss.fail()));
if(iss.fail())
throw runtime_error("WTF??? Failed to read port.");

// Should this be a port above the reserved range ([0-1024] on Unix)?
ASSERT(t > 0);
if(!(t > 0))
throw runtime_error("WTF??? Port is too small");

ASSERT(t < static_cast<long long>(numeric_limits<unsigned int>::max()));
if(!(t < static_cast<long long>(numeric_limits<unsigned int>::max())))
throw runtime_error("WTF??? Port is too large");

// OK to use port
unsigned short port = static_cast<unsigned short>(t);
…</pre>

Again, notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>port</tt>. This code will continue checking conditions, years after being instrumented (assuming to wrote code to read a config file early in the project). There's no need to remove the <tt>ASSERT</tt>s as with <tt>printf</tt> since they are silent guardians.

Another useful suppression trick is too avoid ignoring return values. Not only is it useful to suppress the warning, its required for correct code. For example, <tt>snprint</tt> will alert you to truncations through its return value. You should not make them silent truncations by ignoring the warning or casting to <tt>void</tt>:

<pre>char path[PATH_MAX];
…

int ret = snprintf(path, sizeof(path), "%s/%s", GetDirectory(), GetObjectName());
ASSERT(ret != -1);
ASSERT(!(ret >= sizeof(path)));

if(ret == -1 || ret >= sizeof(path))
throw runtime_error("WTF??? Unable to build full object name");

// OK to use path
…</pre>

The problem is pandemic, and not just boring user land programs. Projects which offer high integrity code, such as SELinux, suffer silent truncations. The following is from an approved SELinux patch even though a comment was made that it [http://permalink.gmane.org/gmane.comp.security.selinux/16845 suffered silent truncations in its <tt>security_compute_create_name</tt> function] from <tt>compute_create.c</tt>.

<pre>12 int security_compute_create_raw(security_context_t scon,
13 security_context_t tcon,
14 security_class_t tclass,
15 security_context_t * newcon)
16 {
17 char path[PATH_MAX];
18 char *buf;
19 size_t size;
20 int fd, ret;
21
22 if (!selinux_mnt) {
23 errno = ENOENT;
24 return -1;
25 }
26
27 snprintf(path, sizeof path, "%s/create", selinux_mnt);
28 fd = open(path, O_RDWR);</pre>

Unlike other examples, the above code will not debug itself, and you will have to set breakpoints and trace calls to determine the point of first failure. (And the code above gambles that the truncated file does not exist or is not under an adversary's control by blindly performing the <tt>open</tt>).

== Runtime ==

The previous sections concentrated on setting up your project for success. This section will examine additional hints for running with increased diagnostics and defenses. Not all platforms are created equal - GNU Linux is difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening to a program after compiling and static linking]; while Windows allows post-build hardening through a download. Remember, the goal is to find the point of first failure quickly so you can improve the reliability and security of the code.

=== Xcode ===

Xcode offers additional [http://developer.apple.com/library/mac/#recipes/xcode_help-scheme_editor/Articles/SchemeDiagnostics.html Application Diagnostics] that can help find memory errors and object use problems. Schemes can be managed through ''Products'' menu item, ''Scheme'' submenu item, and then ''Edit''. From the editor, navigate to the ''Diagnostics'' tab. In the figure below, four additional instruments are enabled for the debugging cycle: Scribble guards, Edge guards, Malloc guards, and Zombies.

{| align="center"
| [[File:toolchan-hardening-1.png|thumb|450px|Figure 2: Xcode Memory Diagnostics]]
|}

There is one caveat with using some of the guards: Apple only provides them for the simulator, and not a device. In the past, the guards were available for both devices and simulators.

=== Windows ===

Visual Studio offers a number of debugging aides for use during development. The aides are called [http://msdn.microsoft.com/en-us/library/d21c150d.aspx Managed Debugging Assistants (MDAs)]. You can find the MDAs on the ''Debug'' menu, then ''Exceptions'' submenu. MDAs allow you to tune your debugging experience by, for example, filter exceptions for which the debugger should snap. For more details, see Stephen Toub's ''[http://msdn.microsoft.com/en-us/magazine/cc163606.aspx Let The CLR Find Bugs For You With Managed Debugging Assistants]''.

{| align="center"
| [[File:toolchan-hardening-2.png|thumb|450px|Figure 3: Managed Debugging Assistants]]
|}

Finally, for runtime hardening, Microsoft has a helpful tool called EMET. EMET is the [http://support.microsoft.com/kb/2458544 Enhanced Mitigation Experience Toolkit], and allows you to apply runtime hardening to an executable which was built without. Its very useful for utilities and other programs that were built without an SDLC.

{| align="center"
| [[File:toolchan-hardening-3.png|thumb|450px|Figure 4: Windows and EMET]]
|}

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

C-Based Toolchain Hardening

2013-03-13T02:27:15Z

Jeffrey Walton: Moved SQLITE_TEMP_STORE into SQLCipher per Stephen Lombardo recommendation (SL is author of SQLCipher)

[[C-Based Toolchain Hardening]] is a treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

This is a prescriptive article, and it will not debate semantics or speculate on behavior. Some information, such as the C/C++ committee's motivation and pedigree for [https://groups.google.com/a/isocpp.org/forum/?fromgroups=#!topic/std-discussion/ak8e1mzBhGs "program diagnostics", <tt>NDEBUG</tt>, <tt>assert</tt>, and <tt>abort()</tt>], appears to be lost like a tale in the Lord of the Rings. As such, the article will specify semantics (for example, the philosophy of 'debug' and 'release' build configurations), assign behaviors (for example, what an assert should do in a 'debug' and 'release' build configurations), and present a position. If you find the posture is too aggressive, then you should back off as required to suite your taste.

A secure toolchain is not a silver bullet. It is one piece of an overall strategy in the engineering process to help ensure success. It will compliment existing processes such as static analysis, dynamic analysis, secure coding, negative test suites, and the like. Tools such as Valgrind and Helgrind will still be needed. And a project will still require solid designs and architectures.

The OWASP [http://code.google.com/p/owasp-esapi-cplusplus/source ESAPI C++] project eats its own dog food. Many of the examples you will see in this article come directly from the ESAPI C++ project.

Finally, a [[Category:Cheat Sheet|cheat sheet]] is available for those who desire a terse treatment of the material. Please visit [[C-Based_Toolchain_Hardening_Cheat_Sheet|C-Based Toolchain Hardening Cheat Sheet]] for the abbreviated version.

== Wisdom ==

Code '''must''' be correct. It '''should''' be secure. It '''can''' be efficient.

[http://en.wikipedia.org/wiki/Jon_Bentley Dr. Jon Bentley]: ''"If it doesn't have to be correct, I can make it as fast as you'd like it to be"''.

[http://en.wikipedia.org/wiki/Gary_McGraw Dr. Gary McGraw]: ''"Thou shalt not rely solely on security features and functions to build secure software as security is an emergent property of the entire system and thus relies on building and integrating all parts properly"''.

== Configuration ==

Configuration is the first opportunity to configure your project for success. Not only do you have to configure your project to meet reliability and security goals, you must also configure integrated libraries properly. You typically have has three choices. First, you can use auto-configuration utilities if on Linux or Unix. Second, you can write a makefile by hand. This is predominant on Linux, Mac OS X, and Unix, but it applies to Windows as well. Finally, you can use an integrated development environment or IDE.

=== Build Configurations ===

At this stage in the process, you should concentrate on configuring for two builds: Debug and Release. Debug will be used for development and include full instrumentation. Release will be configured for production. The difference between the two settings is usually ''optimization level'' and ''debug level''. A third build configuration is Test, and its usually a special case of Release.

For debug and release builds, the settings are typically diametrically opposed. Debug configurations have no optimizations and full debug information; while Release builds have optimizations and minimal to moderate debug information. In addition, debug code has full assertions and additional library integration, such as mudflaps and malloc guards such as <tt>dmalloc</tt>.

The Test configuration is often a Release configuration that makes everything public for testing and builds a test harness. For example, all member functions public (C++ class) and all interfaces (library or shared object) should be made available for testing. Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

[http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8] introduced an optimization of <tt>-Og</tt>. Note that it is only an optimization, and still requires a customary debug level via <tt>-g</tt>.

==== Debug Builds ====

Debug builds are where developers spend most of their time when vetting problems, so this build should concentrate forces and tools or be a 'force multiplier'. Though many do not realize, debug code is more highly valued than release code because its adorned with additional instrumentation. The debug instrumentation will cause a program to become nearly "self-debugging", and help you catch mistakes such as bad parameters, failed API calls, and memory problems.

Self-debugging code reduces your time during trouble shooting and debugging. Reducing time under the debugger means you have more time for development and feature requests. If code is checked in without debug instrumentation, it should be fixed by adding instrumentation or rejected.

For GCC, optimizations and debug symbolication are controlled through two switches: <tt>-O</tt> and <tt>-g</tt>. You should use the following as part of your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for a minimal debug session:

<pre>-O0 -g3 -ggdb</pre>

<tt>-O0</tt> turns off optimizations and <tt>-g3</tt> ensures maximum debug information is available. You may need to use <tt>-O1</tt> so some analysis is performed. Otherwise, your debug build will be missing a number of warnings not present in release builds. <tt>-g3</tt> ensures maximum debugging information is available for the debug session, including symbolic constants and <tt>#defines</tt>. <tt>-ggdb</tt> includes extensions to help with a debug session under GDB. For completeness, Jan Krachtovil stated <tt>-ggdb</tt> currently has no effect in a private email.

Debug build should also define <tt>DEBUG</tt>, and ensure <tt>NDEBUG</tt> is not defined. <tt>NDEBUG</tt> removes "program diagnostics"; and has undesirable behavior and side effects which discussed below in more detail. The defines should be present for all code, and not just the program. You use it for all code (your program and included libraries) because you need to know how they fail too (remember, you take the bug report - not the third party library).

In addition, you should also use other relevant flags, such as <tt>-fno-omit-frame-pointer</tt> and <tt>-fsanitize=address</tt>. Finally, you should also ensure your project includes additional diagnostic libraries, such as <tt>dmalloc</tt>. The additional flags and libraries are discussed below in more detail.

==== Release Builds ====

Release builds are what your customer receives. They are meant to be run on production hardware and servers, and they should be reliable, secure, and efficient. A stable release build is the product of the hard work and effort during development.

For release builds, you should use the following as part of <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for release builds:

<pre>-On -g2</pre>

<tt>-O''n''</tt> sets optimizations for speed or size (for example, <tt>-Os</tt> or <tt>-O2</tt>), and <tt>-g2</tt> ensure debugging information is created.

Debugging information should be stripped and retained in case of symbolication for a crash report from the field. While not desired, debug information can be left in place without a performance penalty. See ''[http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]'' for details.

Release builds should also define <tt>NDEBUG</tt>, and ensure <tt>DEBUG</tt> is not defined. The time for debugging and diagnostics is over, so users get production code with full optimizations, no "programming diagnostics", and other efficiencies. If you can't optimize or your are performing excessive logging, it usually means the program is not ready for production.

If you have been relying on an <tt>assert</tt> and then a subsequent <tt>abort()</tt>, you have been abusing "program diagnostics" since it has no place in production code. If you want a memory dump, create one so users don't have to worry about secrets and other sensitive information being written to the filesystem and emailed in plain text.

For Windows, you would use <tt>/Od</tt> for debug builds; and <tt>/Ox</tt>, <tt>/O2</tt> or <tt>/Os</tt> for release builds. See Microsoft's [http://msdn.microsoft.com/en-us/library/k1ack8f1.aspx /O Options (Optimize Code)] for details.

==== Test Builds ====

Test builds are used to provide heuristic validation by way of positive and negative test suites. Under a test configuration, all interfaces are tested to ensure they perform to specification and satisfaction. "Satisfaction" is subjective, but it should include no crashing and no trashing of your memory arena, even when faced with negative tests.

Because all interfaces are tested (and not just the public ones), your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> should include:

<pre>-Dprotected=public -Dprivate=public</pre>

You should also change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>.

Nearly everyone gets a positive test right, so no more needs to be said. The negative self tests are much more interesting, and you should concentrate on trying to make your program fail so you can verify its fails gracefully. Remember, a bad guy is not going to be courteous when he attempts to cause your program to fail. And its your project that takes egg on the face by way of a bug report or guest appearance on [http://www.grok.org.uk/full-disclosure/ Full Disclosure] or [http://www.securityfocus.com/archive Bugtraq] - not ''<nowiki><some library></nowiki>'' you included.

=== Auto Tools ===

Auto configuration tools are popular on many Linux and Unix based systems, and the tools include ''Autoconf'', ''Automake'', ''config'', and ''Configure''. The tools work together to produce project files from scripts and template files. After the process completes, your project should be setup and ready to be made with <tt>make</tt>.

When using auto configuration tools, there are a few files of interest worth mentioning. The files are part of the auto tools chain and include <tt>m4</tt> and the various <tt>*.in</tt>, <tt>*.ac</tt> (autoconf), and <tt>*.am</tt> (automake) files. At times, you will have to open them, or the resulting makefiles, to tune the "stock" configuration.

There are three downsides to the command line configuration tools in the toolchain: (1) they often ignore user requests, (2) they cannot create configurations, and (3) security is often not a goal.

To demonstrate the first issue, confider your project with the following: <tt>configure CFLAGS="-Wall -fPIE" CXXFLAGS="-Wall -fPIE" LDFLAGS="-pie"</tt>. You will probably find the auto tools ignored your request, which means the command below will not produce expected results. As a work around, you will have to open an <tt>m4</tt> scripts, <tt>Makefile.in</tt> or <tt>Makefile.am</tt> and fix the configuration.

<pre>$ configure CFLAGS="-Wall -Wextra -Wconversion -fPIE -Wno-unused-parameter
-Wformat=2 -Wformat-security -fstack-protector-all -Wstrict-overflow"
LDFLAGS="-pie -z,noexecstack -z,noexecheap -z,relro -z,now"</pre>

For the second point, you will probably be disappointed to learn [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html Automake does not support the concept of configurations]. Its not entirely Autoconf's or Automake's fault - ''Make'' and its inability to detect changes is the underlying problem. Specifically, ''Make'' only [http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html checks modification times of prerequisites and targets], and does not check things like <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>. The net effect is you will not receive expected results when you issue <tt>make debug</tt> and then <tt>make test</tt> or <tt>make release</tt>.

Finally, you will probably be disappointed to learn tools such as Autoconf and Automake miss many security related opportunities and ship insecure out of the box. There are a number of compiler switches and linker flags that improve the defensive posture of a program, but they are not 'on' by default. Tools like Autoconf - which are supposed to handle this situation - often provides setting to serve the lowest of all denominators.

A recent discussion on the Automake mailing list illuminates the issue: ''[https://lists.gnu.org/archive/html/autoconf/2012-12/msg00038.html Enabling compiler warning flags]''. Attempts to improve default configurations were met with resistance and no action was taken. The resistance is often of the form, "<nowiki><some useful warning></nowiki> also produces false positives" or "<nowiki><some obscure platform></nowiki> does not support <nowiki><established security feature></nowiki>". Its noteworthy that David Wheeler, the author of ''[http://www.dwheeler.com/secure-programs/ Secure Programming for Linux and Unix HOWTO]'', was one of the folks trying to improve the posture.

=== Makefiles ===

Make is one of the earliest build systems dating back to the 1970s. Its available on Linux, Mac OS X and Unix, so you will frequently encounter projects using it. Unfortunately, Make has a number of short comings (''[http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful]'' and ''[http://www.conifersystems.com/whitepapers/gnu-make/ What’s Wrong With GNU make?]''), and can cause some discomfort. Despite issues with Make, ESAPI C++ uses Make primarily for three reasons: first, its omnipresent; second, its easier to manage than the Auto Tools family; and third, <tt>libtool</tt> was out of the question.

Consider what happens when you: (1) type <tt>make debug</tt>, and then type <tt>make release</tt>. Each build would require different <tt>CFLAGS</tt> due to optimizations and level of debug support. In your makefile, you would extract the relevant target and set <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> similar to below (taken from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/Makefile ESAPI C++ Makefile]):

<pre># Makefile
DEBUG_GOALS = $(filter $(MAKECMDGOALS), debug)
ifneq ($(DEBUG_GOALS),)
WANT_DEBUG := 1
WANT_TEST := 0
WANT_RELEASE := 0
endif
…

ifeq ($(WANT_DEBUG),1)
ESAPI_CFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
ESAPI_CXXFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
endif

ifeq ($(WANT_RELEASE),1)
ESAPI_CFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
ESAPI_CXXFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
endif

ifeq ($(WANT_TEST),1)
ESAPI_CFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
ESAPI_CXXFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
endif
…

# Merge ESAPI flags with user supplied flags. We perform the extra step to ensure
# user options follow our options, which should give user option's a preference.
override CFLAGS := $(ESAPI_CFLAGS) $(CFLAGS)
override CXXFLAGS := $(ESAPI_CXXFLAGS) $(CXXFLAGS)
override LDFLAGS := $(ESAPI_LDFLAGS) $(LDFLAGS)
…</pre>

Make will first build the program in a debug configuration for a session under the debugger using a rule similar to:

<pre>%.cpp:%.o:
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@</pre>

When you want the release build, Make will do nothing because it considers everything up to date despite the fact <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> have changed. Hence, your program will actually be in a debug configuration and risk a <tt>SIGABRT</tt> at runtime because debug instrumentation is present (recall <tt>assert</tt> calls <tt>abort()</tt> when <tt>NDEBUG</tt> is '''not''' defined). In essence, you have DoS'd yourself due to <tt>make</tt>.

In addition, many projects do not honor the user's command line. ESAPI C++ does its best to ensure a user's flags are honored via <tt>override</tt> as shown above, but other projects do not. For example, consider a project that should be built with Position Independent Executable (PIE or ASLR) enabled and data execution prevention (DEP) enabled. Dismissing user settings combined with insecure out of the box settings (and not picking them up during auto-setup or auto-configure) means a program built with the following will likely have neither defense:

<pre>$ make CFLAGS="-fPIE" CXXFLAGS="-fPIE" LDFLAGS="-pie -z,noexecstack, -z,noexecheap"</pre>

Defenses such as ASLR and DEP are especially important on Linux because [http://linux.die.net/man/5/elf Data Execution - not Prevention - is the norm].

=== Integration ===

Project level integration presents opportunities to harden your program or library with domain specific knowledge. For example, if the platform supports Position Independent Executables (PIE or ASLR) and data execution prevention (DEP), then you should integrate with it. The consequences of not doing so could result in exploitation. As a case in point, see KingCope's 0-days for MySQL in December, 2012 (CVE-2012-5579 and CVE-2012-5612, among others). Integration with platform security would have neutered a number of the 0-days.

You also have the opportunity to include helpful libraries that are not need for business logic support. For example, if you are working on a platform with [http://dmalloc.com DMalloc] or [http://code.google.com/p/address-sanitizer/ Address Sanitizer], you should probably use it in your debug builds. For Ubuntu, DMalloc available from the package manager and can be installed with <tt>sudo apt-get install libdmalloc5</tt>. For Apple platforms, its available as a scheme option (see [[#Clang/Xcode|Clang/Xcode]] below). Address Sanitizer is available in [http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8 and above] for many platforms.

In addition, project level integration is an opportunity to harden third party libraries you chose to include. Because you chose to include them, you and your users are responsible for them. If you or your users endure a SP800-53 audit, third party libraries will be in scope because the supply chain is included (specifically, item SA-12, Supply Chain Protection). The audits are not limited to those in the US Federal arena - financial institutions perform reviews too. A perfect example of violating this guidance is [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525], which was due to [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library].

Another example is including OpenSSL. You know (1) [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 is insecure], (2) [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 is insecure], and (3) [http://arstechnica.com/security/2012/09/crime-hijacks-https-sessions/ compression is insecure] (among others). In addition, suppose you don't use hardware and engines, and only allow static linking. Given the knowledge and specifications, you would configure the OpenSSL library as follows:

<pre>$ Configure darwin64-x86_64-cc -no-hw -no-engines -no-comp -no-shared -no-dso -no-sslv2 -no-sslv3 --openssldir=…</pre>

''Note Well'': you might want engines, especially on Ivy Bridge microarchitectures (3rd generation Intel Core i5 and i7 processors). To have OpenSSL use the processor's random number generator (via the of <tt>rdrand</tt> instruction), you will need to call OpenSSL's <tt>ENGINE_load_rdrand()</tt> function and then <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. See [http://wiki.opensslfoundation.com/index.php/Random_Numbers OpenSSL's Random Numbers] for details.

If you configure without the switches, then you will likely have vulnerable code/libraries and risk failing an audit. If the program is a remote server, then the following command will reveal if compression is active on the channel:

<pre>$ echo "GET / HTTP1.0" | openssl s_client -connect <nowiki>example.com:443</nowiki></pre>

<tt>nm</tt> or <tt>openssl s_client</tt> will show that compression is enabled in the client. In fact, any symbol within the <tt>OPENSSL_NO_COMP</tt> preprocessor macro will bear witness since <tt>-no-comp</tt> is translated into a <tt>CFLAGS</tt> define.

<pre>$ nm /usr/local/ssl/iphoneos/lib/libcrypto.a 2>/dev/null | egrep -i "(COMP_CTX_new|COMP_CTX_free)"
0000000000000110 T COMP_CTX_free
0000000000000000 T COMP_CTX_new</pre>

Even more egregious is the answer given to auditors who specifically ask about configurations and protocols: "we don't use weak/wounded/broken ciphers" or "we follow best practices." The use of compression tells the auditor that you are using wounded protocol in an insecure configuration and you don't follow best practices. That will likely set off alarm bells, and ensure the auditor dives deeper on more items.

== Preprocessor ==

The preprocessor is crucial to setting up a project for success. The C committee provided one macro - <tt>NDEBUG</tt> - and the macro can be used to derive a number of configurations and drive engineering processes. Unfortunately, the committee also left many related items to chance, which has resulted in programmers abusing builtin facilities. This section will help you set up you projects to integrate well with other projects and ensure reliability and security.

There are three topics to discuss when hardening the preprocessor. The first is well defined configurations which produce well defined behaviors, the second is useful behavior from assert, and the third is proper use of macros when integrating vendor code and third party libraries.

=== Configurations ===

To remove ambiguity, you should recognize two configurations: Release and Debug. Release is for production code on live servers, and its behavior is requested via the C/C++ <tt>NDEBUG</tt> macro. Its also the only macro observed by the C and C++ Committees and Posix. Diametrically opposed to release is Debug. While there is a compelling argument for <tt>!defined(NDEBUG)</tt>, you should have an explicit macro for the configuration and that macro should be <tt>DEBUG</tt>. This is because vendors and outside libraries use <tt>DEBUG</tt> (or similar) macro for their configuration. For example, Carnegie Mellon's Mach kernel uses <tt>DEBUG</tt>, Microsoft's CRT uses [http://msdn.microsoft.com/en-us/library/ww5t02fa%28v=vs.71%29.aspx<tt>_DEBUG</tt>], and Wind River Workbench uses <tt>DEBUG_MODE</tt>.

In addition to <tt>NDEBUG</tt> (Release) and <tt>DEBUG</tt> (Debug), you have two additional cross products: both are defined or neither are defined. Defining both should be an error, and defining neither should default to a release configuration. Below is from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/esapi/EsapiCommon.h ESAPI C++ EsapiCommon.h], which is the configuration file used by all source files:

<pre>// Only one or the other, but not both
#if (defined(DEBUG) || defined(_DEBUG)) && (defined(NDEBUG) || defined(_NDEBUG))
# error Both DEBUG and NDEBUG are defined.
#endif

// The only time we switch to debug is when asked. NDEBUG or {nothing} results
// in release build (fewer surprises at runtime).
#if defined(DEBUG) || defined(_DEBUG)
# define ESAPI_BUILD_DEBUG 1
#else
# define ESAPI_BUILD_RELEASE 1
#endif</pre>

When <tt>DEBUG</tt> is in effect, your code should receive full debug instrumentation, including the full force of assertions.

=== ASSERT ===

Asserts will help you create self-debugging code by helping you find the point of first failure quickly and easily. Asserts should be used throughout your program, including parameter validation, return value checking and program state. The <tt>assert</tt> will silently guard your code through its lifetime. It will always be there, even when not debugging a specific component of a module. If you have thorough code coverage, you will spend less time debugging and more time developing because programs will debug themselves.

To use asserts effectively, you should assert everything. That includes parameters upon entering a function, return values from function calls, and any program state. Everywhere you place an <tt>if</tt> statement for validation or checking, you should have an assert. Everywhere you have an <tt>assert</tt> for validation or checking, you should have an <tt>if</tt> statement. They go hand-in-hand.

If you are still using <tt>printf</tt>'s, then you have an opportunity for improvement. In the time it takes for you to write a <tt>printf</tt> or <tt>NSLog</tt> statement, you could have written an <tt>assert</tt>. Unlike the <tt>printf</tt> or <tt>NSLog</tt> which are often removed when no longer needed, the <tt>assert</tt> stays active forever. Remember, this is all about finding the point of first failure quickly so you can spend your time doing other things.

There is one problem with using asserts - [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html Posix states <tt>assert</tt> should call <tt>abort()</tt>] if <tt>NDEBUG</tt> is '''not''' defined. When debugging, <tt>NDEBUG</tt> will never be defined since you want the "program diagnostics" (quote from the Posix description). The behavior makes <tt>assert</tt> and its accompanying <tt>abort()</tt> completely useless for development. The result of "program diagnostics" calling <tt>abort()</tt> due to standard C/C++ behavior is disuse - developers simply don't use them. Its incredibly bad for the development community because self-debugging programs can help eradicate so many stability problems.

Since self-debugging programs are so powerful, you will have to have to supply your own assert and signal handler with improved behavior. Your assert will exchange auto-aborting behavior for auto-debugging behavior. The auto-debugging facility will ensure the debugger snaps when a problem is detected, and you will find the point of first failure quickly and easily.

ESAPI C++ supplies its own assert with the behavior described above. In the code below, <tt>ASSERT</tt> raises <tt>SIGTRAP</tt> when in effect or it evaluates to <tt>void</tt> in other cases.

<pre>// A debug assert which should be sprinkled liberally. This assert fires and then continues rather
// than calling abort(). Useful when examining negative test cases from the command line.
#if (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_STARNIX))
# define ESAPI_ASSERT1(exp) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
# define ESAPI_ASSERT2(exp, msg) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< ": \"" << (msg) << "\"" << std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
#elif (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_WINDOWS))
# define ESAPI_ASSERT1(exp) assert(exp)
# define ESAPI_ASSERT2(exp, msg) assert(exp)
#else
# define ESAPI_ASSERT1(exp) ((void)(exp))
# define ESAPI_ASSERT2(exp, msg) ((void)(exp))
#endif

#if !defined(ASSERT)
# define ASSERT(exp) ESAPI_ASSERT1(exp)
#endif</pre>

At program startup, a <tt>SIGTRAP</tt> handler will be installed if one is not provided by another component:

<pre>struct DebugTrapHandler
{
DebugTrapHandler()
{
struct sigaction new_handler, old_handler;

do
{
int ret = 0;

ret = sigaction (SIGTRAP, NULL, &old_handler);
if (ret != 0) break; // Failed

// Don't step on another's handler
if (old_handler.sa_handler != NULL) break;

new_handler.sa_handler = &DebugTrapHandler::NullHandler;
new_handler.sa_flags = 0;

ret = sigemptyset (&new_handler.sa_mask);
if (ret != 0) break; // Failed

ret = sigaction (SIGTRAP, &new_handler, NULL);
if (ret != 0) break; // Failed

} while(0);
}

static void NullHandler(int /*unused*/) { }

};

// We specify a relatively low priority, to make sure we run before other CTORs
// http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#C_002b_002b-Attributes
static const DebugTrapHandler g_dummyHandler __attribute__ ((init_priority (110)));</pre>

On a Windows platform, you would call <tt>_set_invalid_parameter_handler</tt> (and possibly <tt>set_unexpected</tt> or <tt>set_terminate</tt>) to install a new handler.

Live hosts running production code should always define <tt>NDEBUG</tt> (i.e., release configuration), which means they do not assert or auto-abort. Auto-abortion is not acceptable behavior, and anyone who asks for the behavior is completely abusing the functionality of "program diagnostics". If a program wants a core dump, then it should create the dump rather than crashing.

For more reading on asserting effectively, please see one of John Robbin's books, such as ''[http://www.amazon.com/dp/0735608865 Debugging Applications]''. John is a legendary bug slayer in Windows circles, and he will show you how to do nearly everything, from debugging a simple program to bug slaying in multithreaded programs.

=== Additional Macros ===

Additional macros include any macros needed to integrate properly and securely. It includes integrating the program with the platform (for example MFC or Cocoa/CocoaTouch) and libraries (for example, Crypto++ or OpenSSL). It can be a challenge because you have to have proficiency with your platform and all included libraries and frameworks. The list below illustrates the level of detail you will need when integrating.

Though Boost is missing from the list, it appears to lack recommendations, additional debug diagnostics, and a hardening guide. See ''[http://stackoverflow.com/questions/14927033/boost-hardening-guide-preprocessor-macros BOOST Hardening Guide (Preprocessor Macros)]'' for details. In addition, Tim Day points to ''[http://boost.2283326.n4.nabble.com/boost-build-should-we-not-define-SECURE-SCL-0-by-default-for-all-msvc-toolsets-td2654710.html <nowiki>[boost.build] should we not define _SECURE_SCL=0 by default for all msvc toolsets</nowiki>]'' for a recent discussion related to hardening (or lack thereof).

In addition to what you should define, defining some macros and undefining others should trigger a security related defect. For example, <tt>-U_FORTIFY_SOURCES</tt> on Linux and <tt>_CRT_SECURE_NO_WARNINGS=1</tt>, <tt>_SCL_SECURE_NO_WARNINGS</tt>, <tt>_ATL_SECURE_NO_WARNINGS</tt> or <tt>STRSAFE_NO_DEPRECATE</tt> on Windows.

{| border="1"

|-style="background:#DADADA"
!Platform/Library!!Debug!!Release
|+ Table 1: Additional Platform/Library Macros

|-
|width="175pt"|All
|width="250pt"|DEBUG=1
|width="250pt"|NDEBUG=1

|-
|Linux
|_GLIBCXX_DEBUG=1a
|_FORTIFY_SOURCE=2

|-
|Android
|NDK_DEBUG=1
|_FORTIFY_SOURCE=1 (4.2 and above) 
<tt>#define LOGI(...)</tt> (define to nothing, preempt logging)

|-
|Cocoa/CocoaTouch
|
|NS_BLOCK_ASSERTIONS=1 
<tt>#define NSLog(...)</tt> (define to nothing, preempt ASL)

|-
|SafeInt
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1

|-
|Microsoft
|_DEBUG=1, STRICT, 
_SECURE_SCL=1, _HAS_ITERATOR_DEBUGGING=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1
|STRICT 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1

|-
|Microsoft ATL & MFC
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS

|-
|STLPort
|_STLP_DEBUG=1, _STLP_USE_DEBUG_LIB=1 
_STLP_DEBUG_ALLOC=1, _STLP_DEBUG_UNINITIALIZED=1
|

|-
|SQLite
|SQLITE_DEBUG, SQLITE_MEMDEBUG 
SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc
|SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc

|-
|SQLCipher
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3d
|SQLITE_HAS_CODEC=1 
SQLITE_TEMP_STORE=3d

|}

a Be careful with <tt>_GLIBCXX_DEBUG</tt> when using pre-compiled libraries such as Boost from a distribution. There are ABI incompatibilities, and the result will likely be a crash. You will have to compile Boost with <tt>_GLIBCXX_DEBUG</tt> or omit <tt>_GLIBCXX_DEBUG</tt>.

b SQLite secure deletion zeroizes memory on destruction. Define as required, and always define in US Federal since zeroization is required for FIPS 140-2, Level 1.

c ''N'' is 0644 by default, which means everyone has some access.

d Force temporary tables into memory (no unencrypted data to disk).

== Compiler and Linker ==

Compiler writers provide a rich set of warnings from the analysis of code during compilation. Both GCC and Visual Studio have static analysis capabilities to help find mistakes early in the development process. The built in static analysis capabilities of GCC and Visual Studio are usually sufficient to ensure proper API usage and catch a number of mistakes such as using an uninitialized variable or comparing a negative signed int and a positive unsigned int.

As a concrete example, (and for those not familiar with C/C++ promotion rules), a warning will be issued if a signed integer is promoted to an unsigned integer and then compared because a side effect is <tt>-1 > 1</tt> after promotion! GCC and Visual Studio will not currently catch, for example, SQL injections and other tainted data usage. For that, you will need a tool designed to perform data flow analysis or taint analysis.

Some in the development community resist static analysis or refute its results. For example, when static analysis warned the Linux kernel's <tt>sys_prctl</tt> was comparing an unsigned value against less than zero, Jesper Juhl offered a patch to clean up the code. Linus Torvalds howled “No, you don't do this… GCC is crap” (referring to compiling with warnings). For the full discussion, see ''[http://linux.derkeiler.com/Mailing-Lists/Kernel/2006-11/msg08325.html <nowiki>[PATCH] Don't compare unsigned variable for <0 in sys_prctl()</nowiki>]'' from the Linux Kernel mailing list.

The following sections will detail steps for three platforms. First is a typical GNU Linux based distribution offering GCC and Binutils, second is Clang and Xcode, and third is modern Windows platforms.

=== Distribution Hardening ===

Before discussing GCC and Binutils, it would be a good time to point out some of the defenses discussed below are all ready present in a distribution. Unfortunately, its design by committee, so what is present is usually only a mild variation of what is available (this way, everyone is mildly offended). For those who are purely worried about performance, you might be surprised to learn you have already taken the small performance hint without even knowing.

Linux and BSD distributions often apply some hardening without intervention via ''[http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html GCC Spec Files]''. If you are using Debian, Ubuntu, Linux Mint and family, see ''[http://wiki.debian.org/Hardening Debian Hardening]''. For Red Hat and Fedora systems, see ''[http://lists.fedoraproject.org/pipermail/devel-announce/2011-August/000821.html New hardened build support (coming) in F16]''. Gentoo users should visit ''[http://www.gentoo.org/proj/en/hardened/ Hardened Gentoo]''.

You can see the settings being used by a distribution via <tt>gcc -dumpspecs</tt>. From Linux Mint 12 below, -fstack-protector (but not -fstack-protector-all) is used by default.

<pre>$ gcc -dumpspecs
…
*link_ssp: %{fstack-protector:}

*ssp_default: %{!fno-stack-protector:%{!fstack-protector-all: %{!ffreestanding:%{!nostdlib:-fstack-protector}}}}
…</pre>

The “SSP” above stands for Stack Smashing Protector. SSP is a reimplementation of Hiroaki Etoh's work on IBM Pro Police Stack Detector. See Hiroaki Etoh's patch ''[http://gcc.gnu.org/ml/gcc-patches/2001-06/msg01753.html gcc stack-smashing protector]'' and IBM's ''[http://www.research.ibm.com/trl/projects/security/ssp/ GCC extension for protecting applications from stack-smashing attacks]'' for details.

=== GCC/Binutils ===

GCC (the compiler collection) and Binutils (the assemblers, linkers, and other tools) are separate projects that work together to produce a final executable. Both the compiler and linker offer options to help you write safer and more secure code. The linker will produce code which takes advantage of platform security features offered by the kernel and PaX, such as no-exec stacks and heaps (NX) and Position Independent Executable (PIE).

The table below offers a set of compiler options to build your program. Static analysis warnings help catch mistakes early, while the linker options harden the executable at runtime. In the table below, “GCC” should be loosely taken as “non-ancient distributions.” While the GCC team considers 4.2 ancient, you will still encounter it on Apple and BSD platforms due to changes in GPL licensing around 2007. Refer to ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Option Summary]'', ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html Options to Request or Suppress Warnings]'' and ''[http://sourceware.org/binutils/docs-2.21/ld/Options.html Binutils (LD) Command Line Options]'' for usage details.

Noteworthy of special mention are <tt>-fno-strict-overflow</tt> and <tt>-fwrapv</tt>a. The flags ensure the compiler does not remove statements that result in overflow or wrap. If your program only runs correctly using the flags, it is likely violating C/C++ rules on overflow and illegal. If the program is illegal due to overflow or wrap checking, you should consider using [http://code.google.com/p/safe-iop/ safe-iop] for C or David LeBlanc's [http://safeint.codeplex.com SafeInt] in C++.

For a project compiled and linked with hardened settings, some of those settings can be verified with the [http://www.trapkit.de/tools/checksec.html Checksec] tool written by Tobias Klein. The <tt>checksec.sh</tt> script is designed to test standard Linux OS and PaX security features being used by an application. See the [http://www.trapkit.de/tools/checksec.html Trapkit] web page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 2: GCC C Warning Options

|-
|width="200pt"|<nowiki>-Wall -Wextra</nowiki>
|width="75t"|GCC
|width="425pt"|Enables many warnings (despite their names, all and extra do not turn on all warnings).a

|-
|<nowiki>-Wconversion</nowiki>
|GCC
|Warn for implicit conversions that may alter a value (includes -Wsign-conversion).

|-
|<nowiki>-Wsign-conversion</nowiki>
|GCC
|Warn for implicit conversions that may change the sign of an integer value, such as assigning a signed integer to an unsigned integer (<tt>-1 > 1</tt> after promotion!).

|-
|<nowiki>-Wcast-align</nowiki>
|GCC
|Warn for a pointer cast to a type which has a different size, causing an invalid alignment and subsequent bus error on ARM processors.

|-
|<nowiki>-Wformat=2 -Wformat-security</nowiki>
|GCC
|Increases warnings related to possible security defects, including incorrect format specifiers.

|-
|<nowiki>-fno-common</nowiki>
|GCC
|Prevent global variables being simultaneously defined in different object files.

|-
|<nowiki>-fstack-protector or -fstack-protector-all</nowiki>
|GCC
|Stack Smashing Protector (SSP). Improves stack layout and adds a guard to detect stack based buffer overflows.b

|-
|<nowiki>-fno-omit-frame-pointer</nowiki>
|GCC
|Improves backtraces for post-mortem analysis

|-
|<nowiki>-Wmissing-prototypes and -Wmissing-declarations</nowiki>
|GCC
|Warn if a global function is defined without a prototype or declaration.

|-
|<nowiki>-Wstrict-prototypes</nowiki>
|GCC
|Warn if a function is declared or defined without specifying the argument types.

|-
|<nowiki>-Wstrict-overflow</nowiki>
|GCC 4.2
|Warn about optimizations taken due to <nowiki>[undefined]</nowiki> signed integer overflow assumptions.

|-
|<nowiki>-Wtrampolines</nowiki>
|GCC 4.3
|Warn about trampolines generated for pointers to nested functions. Trampolines require executable stacks.

|-
|<nowiki>-fsanitize=address</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/address-sanitizer/ AddressSanitizer], a fast memory error detector. Memory access instructions will be instrumented to help detect heap, stack, and global buffer overflows; as well as use-after-free bugs.

|-
|<nowiki>-fsanitize=thread</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/data-race-test/wiki/ThreadSanitizer ThreadSanitizer], a fast data race detector. Memory access instructions will be instrumented to detect data race bugs.

|-
|<nowiki>-Wl,-z,nodlopen and -Wl,-z,nodump</nowiki>
|Binutils 2.10
|Reduces the ability of an attacker to load, manipulate, and dump shared objects.

|-
|<nowiki>-Wl,-z,noexecstack and -Wl,-z,noexecheap</nowiki>
|Binutils 2.14
|Data Execution Prevention (DEP). ELF headers are marked with PT_GNU_STACK and PT_GNU_HEAP.

|-
|<nowiki>-Wl,-z,relro</nowiki>
|Binutils 2.15
|Helps remediate Global Offset Table (GOT) attacks on executables.

|-
|<nowiki>-Wl,-z,now</nowiki>
|Binutils 2.15
|Helps remediate Procedure Linkage Table (PLT) attacks on executables.

|-
|<nowiki>-fPIC</nowiki>
|Binutils
|Position Independent Code. Used for libraries and shared objects. Both -fPIC (compiler) and -shared (linker) are required.

|-
|<nowiki>-fPIE</nowiki>
|Binutils 2.16
|Position Independent Executable (ASLR). Used for programs. Both -fPIE (compiler) and -pie (linker) are required.

|}

a Unlike Clang and -Weverything, GCC does not provide a switch to truly enable all warnings. 
b -fstack-protector guards functions with high risk objects such as C strings, while -fstack-protector-all guards all objects.

Additional C++ warnings which can be used include the following in Table 3. See ''[http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html GCC's Options Controlling C++ Dialect]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 3: GCC C++ Warning Options

|-
|width="200pt"|<nowiki>-Woverloaded-virtual</nowiki>
|width="425pt"|Warn when a function declaration hides virtual functions from a base class.

|-
|<nowiki>-Wreorder</nowiki>
|Warn when the order of member initializers given in the code does not match the order in which they must be executed.

|-
|<nowiki>-Wsign-promo</nowiki>
|Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size.

|-
|<nowiki>-Wnon-virtual-dtor</nowiki>
|Warn when a class has virtual functions and an accessible non-virtual destructor.

|-
|<nowiki>-Weffc++</nowiki>
|Warn about violations of the following style guidelines from Scott Meyers' ''[http://www.aristeia.com/books.html Effective C++, Second Edition]'' book.

|}

And additional Objective C warnings which are often useful include the following. See ''[http://gcc.gnu.org/onlinedocs/gcc/Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html Options Controlling Objective-C and Objective-C++ Dialects]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 4: GCC Objective C Warning Options

|-
|width="200pt"|<nowiki>-Wstrict-selector-match</nowiki>
|width="425pt"|Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type id or Class.

|-
|<nowiki>-Wundeclared-selector</nowiki>
|Warn if a <tt>@selector(…)</tt> expression referring to an undeclared selector is found.

|}

The use of aggressive warnings will produce spurious noise. The noise is a tradeoff - you can learn of potential problems at the cost of wading through some chaff. The following will help reduces spurious noise from the warning system:

* -Wno-unused-parameter (GCC)
* -Wno-type-limits (GCC 4.3)
* -Wno-tautological-compare (Clang)

Finally, a simple version based Makefile example is shown below. This is different than feature based makefile produced by auto tools (which will test for a particular feature and then define a symbol or configure a template file). Not all platforms use all options and flags. To address the issue you can pursue one of two strategies. First, you can ship with a weakened posture by servicing the lowest common denominator; or you can ship with everything in force. In the latter case, those who don't have a feature available will edit the makefile to accommodate their installation.

<pre>CXX=g++
EGREP = egrep
…

GCC_COMPILER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version')
GCC41_OR_LATER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version (4\.[1-9]|[5-9])')
…

GNU_LD210_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[0-9]|2\.[2-9])')
GNU_LD214_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[4-9]|2\.[2-9])')
…

ifeq ($(GCC_COMPILER),1)
MY_CC_FLAGS += -Wall -Wextra -Wconversion
MY_CC_FLAGS += -Wformat=2 -Wformat-security
MY_CC_FLAGS += -Wno-unused-parameter
endif

ifeq ($(GCC41_OR_LATER),1)
MY_CC_FLAGS += -fstack-protector-all
endif

ifeq ($(GCC42_OR_LATER),1)
MY_CC_FLAGS += -Wstrict-overflow
endif

ifeq ($(GCC43_OR_LATER),1)
MY_CC_FLAGS += -Wtrampolines
endif

ifeq ($(GNU_LD210_OR_LATER),1)
MY_LD_FLAGS += -z,nodlopen -z,nodump
endif

ifeq ($(GNU_LD214_OR_LATER),1)
MY_LD_FLAGS += -z,noexecstack -z,noexecheap
endif

ifeq ($(GNU_LD215_OR_LATER),1)
MY_LD_FLAGS += -z,relro -z,now
endif

ifeq ($(GNU_LD216_OR_LATER),1)
MY_CC_FLAGS += -fPIE
MY_LD_FLAGS += -pie
endif

# Use 'override' to honor the user's command line
override CFLAGS := $(MY_CC_FLAGS) $(CFLAGS)
override CXXFLAGS := $(MY_CC_FLAGS) $(CXXFLAGS)
override LDFLAGS := $(MY_LD_FLAGS) $(LDFLAGS)
…</pre>

=== Clang/Xcode ===

[http://clang.llvm.org Clang] and [http://llvm.org LLVM] have been aggressively developed since Apple lost its GPL compiler back in 2007 (due to Tivoization which resulted in GPLv3). Since that time, a number of developers and Goggle have joined the effort. While Clang will consume most (all?) GCC/Binutil flags and switches, the project supports a number of its own options, including a static analyzer. In addition, Clang is relatively easy to build with additional diagnostics, such as Dr. John Regher and Peng Li's [http://embed.cs.utah.edu/ioc/ Integer Overflow Checker (IOC)].

IOC is incredibly useful, and has found bugs in a number of projects, from the Linux Kernel (<tt>include/linux/bitops.h</tt>, still unfixed), SQLite, PHP, Firefox (many still unfixed), LLVM, and Python. Future version of Clang (Clang 3.3 and above) will allow you to enable the checks out of the box with <tt>-fsanitize=integer</tt> and <tt>-fsanitize=shift</tt>.

Clang options can be found at [http://clang.llvm.org/docs/UsersManual.html Clang Compiler User’s Manual]. Clang does include an option to turn on all warnings - <tt>-Weverything</tt>. Use it with care but use it regularly since you will get back a lot of noise and issues you missed. For example, add <tt>-Weverything</tt> for production builds and make non-spurious issues a quality gate. Under Xcode, simply add <tt>-Weverything</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>.

In addition to compiler warnings, both static analysis and additional security checks can be performed. Reading on Clang's static analysis capabilities can be found at [http://clang-analyzer.llvm.org Clang Static Analyzer]. Figure 1 below shows some of the security checks utilized by Xcode.

{| align="center"
| [[File:toolchan-hardening-11.png|thumb|450px|Figure 1: Clang/LLVM and Xcode options]]
|}

=== Visual Studio ===

Visual Studio offers a convenient Integrated Development Environment (IDE) for managing solutions and their settings. the section called “Visual Studio Options” discusses option which should be used with Visual Studio, and the section called “Project Properties” demonstrates incorporating those options into a solution's project.

The table below lists the compiler and linker switches which should be used under Visual Studio. Refer to Howard and LeBlanc's Writing Secure Code (Microsoft Press) for a detailed discussion; or ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]'' in Security Briefs by Michael Howard. In the table below, “Visual Studio” refers to nearly all versions of the development environment, including Visual Studio 5.0 and 6.0.

For a project compiled and linked with hardened settings, those settings can be verified with BinScope. BinScope is a verification tool from Microsoft that analyzes binaries to ensure that they have been built in compliance with Microsoft's Security Development Lifecycle (SDLC) requirements and recommendations. See the ''[https://www.microsoft.com/download/en/details.aspx?id=11910 BinScope Binary Analyzer]'' download page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 5: Visual Studio Warning Options

|-
|width="150pt"|<nowiki>/W4</nowiki>
|width="100pt"|Visual Studio
|width="350pt"|Warning level 4, which includes most warnings.

|-
|<nowiki>/WAll</nowiki>
|Visual Studio 2003
|Enable all warnings, including those off by default.a

|-
|<nowiki>/GS</nowiki>
|Visual Studio 2003
|Adds a security cookie (guard or canary) on the stack before the return address buffer stack based for overflow checks.a

|-
|<nowiki>/SafeSEH</nowiki>
|Visual Studio 2003
|Safe structured exception handling to remediate SEH overwrites.

|-
|<nowiki>/analyze</nowiki>
|Visual Studio 2005
|Enterprise code analysis (freely available with Windows SDK for Windows Server 2008 and .NET Framework 3.5).

|-
|<nowiki>/NXCOMPAT</nowiki>
|Visual Studio 2005
|Data Execution Prevention (DEP).

|-
|<nowiki>/dynamicbase</nowiki>
|Visual Studio 2005 SP1
|Address Space Layout Randomization (ASLR).

|-
|<nowiki>strict_gs_check</nowiki>
|Visual Studio 2005 SP1
|Aggressively applies stack protections to a source file to help detect some categories of stack based buffer overruns.b

|}

aSee Jon Sturgeon's discussion of the switch at ''[https://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx Off By Default Compiler Warnings in Visual C++]''. 
aWhen using /GS, there are a number of circumstances which affect the inclusion of a security cookie. For example, the guard is not used if there is no buffer in the stack frame, optimizations are disabled, or the function is declared naked or contains inline assembly. 
b<tt>#pragma strict_gs_check(on)</tt> should be used sparingly, but is recommend in high risk situations, such as when a source file parses input from the internet.

=== Warn Suppression ===

From the tables above, a lot of warnings have been enabled to help detect possible programming mistakes. The potential mistakes are detected via compiler which carries around a lot of contextual information during its code analysis phase. At times, you will receive spurious warnings because the compiler is not ''that'' smart. Its understandable and even a good thing (how would you like to be out of a job because a program writes its own programs?). At times you will have to learn how to work with the compiler's warning system to suppress warnings. Notice what was not said: turn off the warnings.

Suppressing warnings placates the compiler for spurious noise so you can get to the issues that matter (you are separating the wheat from the chaff). This section will offer some hints and point out some potential minefields. First is an unused parameter (for example, <tt>argc</tt> or <tt>argv</tt>). Suppressing unused parameter warnings is especially helpful for C++ and interface programming, where parameters are often unused. For this warning, simply define an "UNUSED" macro and warp the parameter:

<pre>#define UNUSED_PARAMETER(x) ((void)x)
…

int main(int argc, char* argv[])
{
UNUSED_PARAMETER(argc);
UNUSED_PARAMETER(argv);
…
}</pre>

A potential minefield lies near "comparing unsigned and signed" values, and <tt>-Wconversion</tt> will catch it for you. This is because C/C++ promotion rules state the signed value will be promoted to an unsigned value and then compared. That means <tt>-1 > 1</tt> after promotion! To fix this, you cannot blindly cast - you must first range test the value:

<pre>int x = GetX();
unsigned int y = GetY();

ASSERT(x >= 0);
if(!(x >= 0))
throw runtime_error("WTF??? X is negative.");

if(static_cast<unsigned int>(x) > y)
cout << "x is greater than y" << endl;
else
cout << "x is not greater than y" << endl;</pre>

Notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>x</tt>. Just run the program and wait for it to tell you there is a problem. If there is a problem, the program will snap the debugger (and more importantly, not call a useless <tt>abort()</tt> as specified by Posix). It beats the snot out of <tt>printf</tt> that are removed when no longer needed or pollute outputs.

Another conversion problem you will encounter conversion between types, and <tt>-Wconversion</tt> will also catch it for you. The following will always have an opportunity to fail, and should light up like a Christmas tree:

<pre>struct sockaddr_in addr;
…

addr.sin_port = htons(atoi(argv[2]));</pre>

The following would probably serve you much better. Notice <tt>atoi</tt> and fiends are not used because they can silently fail. In addition, the code is instrumented so you don't need to waste a lot of time debugging potential problems:

<pre>const char* cstr = GetPortString();

ASSERT(cstr != NULL);
if(!(cstr != NULL))
throw runtime_error("WTF??? Port string is not valid.");

istringstream iss(cstr);
long long t = 0;
iss >> t;

ASSERT(!(iss.fail()));
if(iss.fail())
throw runtime_error("WTF??? Failed to read port.");

// Should this be a port above the reserved range ([0-1024] on Unix)?
ASSERT(t > 0);
if(!(t > 0))
throw runtime_error("WTF??? Port is too small");

ASSERT(t < static_cast<long long>(numeric_limits<unsigned int>::max()));
if(!(t < static_cast<long long>(numeric_limits<unsigned int>::max())))
throw runtime_error("WTF??? Port is too large");

// OK to use port
unsigned short port = static_cast<unsigned short>(t);
…</pre>

Again, notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>port</tt>. This code will continue checking conditions, years after being instrumented (assuming to wrote code to read a config file early in the project). There's no need to remove the <tt>ASSERT</tt>s as with <tt>printf</tt> since they are silent guardians.

Another useful suppression trick is too avoid ignoring return values. Not only is it useful to suppress the warning, its required for correct code. For example, <tt>snprint</tt> will alert you to truncations through its return value. You should not make them silent truncations by ignoring the warning or casting to <tt>void</tt>:

<pre>char path[PATH_MAX];
…

int ret = snprintf(path, sizeof(path), "%s/%s", GetDirectory(), GetObjectName());
ASSERT(ret != -1);
ASSERT(!(ret >= sizeof(path)));

if(ret == -1 || ret >= sizeof(path))
throw runtime_error("WTF??? Unable to build full object name");

// OK to use path
…</pre>

The problem is pandemic, and not just boring user land programs. Projects which offer high integrity code, such as SELinux, suffer silent truncations. The following is from an approved SELinux patch even though a comment was made that it [http://permalink.gmane.org/gmane.comp.security.selinux/16845 suffered silent truncations in its <tt>security_compute_create_name</tt> function] from <tt>compute_create.c</tt>.

<pre>12 int security_compute_create_raw(security_context_t scon,
13 security_context_t tcon,
14 security_class_t tclass,
15 security_context_t * newcon)
16 {
17 char path[PATH_MAX];
18 char *buf;
19 size_t size;
20 int fd, ret;
21
22 if (!selinux_mnt) {
23 errno = ENOENT;
24 return -1;
25 }
26
27 snprintf(path, sizeof path, "%s/create", selinux_mnt);
28 fd = open(path, O_RDWR);</pre>

Unlike other examples, the above code will not debug itself, and you will have to set breakpoints and trace calls to determine the point of first failure. (And the code above gambles that the truncated file does not exist or is not under an adversary's control by blindly performing the <tt>open</tt>).

== Runtime ==

The previous sections concentrated on setting up your project for success. This section will examine additional hints for running with increased diagnostics and defenses. Not all platforms are created equal - GNU Linux is difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening to a program after compiling and static linking]; while Windows allows post-build hardening through a download. Remember, the goal is to find the point of first failure quickly so you can improve the reliability and security of the code.

=== Xcode ===

Xcode offers additional [http://developer.apple.com/library/mac/#recipes/xcode_help-scheme_editor/Articles/SchemeDiagnostics.html Application Diagnostics] that can help find memory errors and object use problems. Schemes can be managed through ''Products'' menu item, ''Scheme'' submenu item, and then ''Edit''. From the editor, navigate to the ''Diagnostics'' tab. In the figure below, four additional instruments are enabled for the debugging cycle: Scribble guards, Edge guards, Malloc guards, and Zombies.

{| align="center"
| [[File:toolchan-hardening-1.png|thumb|450px|Figure 2: Xcode Memory Diagnostics]]
|}

There is one caveat with using some of the guards: Apple only provides them for the simulator, and not a device. In the past, the guards were available for both devices and simulators.

=== Windows ===

Visual Studio offers a number of debugging aides for use during development. The aides are called [http://msdn.microsoft.com/en-us/library/d21c150d.aspx Managed Debugging Assistants (MDAs)]. You can find the MDAs on the ''Debug'' menu, then ''Exceptions'' submenu. MDAs allow you to tune your debugging experience by, for example, filter exceptions for which the debugger should snap. For more details, see Stephen Toub's ''[http://msdn.microsoft.com/en-us/magazine/cc163606.aspx Let The CLR Find Bugs For You With Managed Debugging Assistants]''.

{| align="center"
| [[File:toolchan-hardening-2.png|thumb|450px|Figure 3: Managed Debugging Assistants]]
|}

Finally, for runtime hardening, Microsoft has a helpful tool called EMET. EMET is the [http://support.microsoft.com/kb/2458544 Enhanced Mitigation Experience Toolkit], and allows you to apply runtime hardening to an executable which was built without. Its very useful for utilities and other programs that were built without an SDLC.

{| align="center"
| [[File:toolchan-hardening-3.png|thumb|450px|Figure 4: Windows and EMET]]
|}

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

Testing for SSL-TLS (OWASP-CM-001)

2013-03-10T05:46:03Z

Jeffrey Walton: Broke RSA and DSA key sizes out into separate entries

{{Template:OWASP Testing Guide v3}}

== Brief Summary ==

Due to historic export restrictions of high grade cryptography, legacy and new web servers are often able and configured to handle weak cryptographic options.

Even if high grade ciphers are normally used and installed, some server misconfiguration could be used to force the use of a weaker cipher to gain access to the supposed secure communication channel.

==Testing SSL / TLS Cipher Specifications and Requirements ==

The http clear-text protocol is normally secured via an SSL or TLS tunnel, resulting in https traffic. In addition to providing encryption of data in transit, https allows the identification of servers (and, optionally, of clients) by means of digital certificates.

Historically, there have been limitations set in place by the U.S. government to allow cryptosystems to be exported only for key sizes of, at most, 40 bits, a key length which could be broken and would allow the decryption of communications. Since then, cryptographic export regulations have been relaxed (though some constraints still hold); however, it is important to check the SSL configuration being used to avoid putting in place cryptographic support which could be easily defeated. SSL-based services should not offer the possibility to choose weak ciphers.

Cipher determination is performed as follows: in the initial phase of a SSL connection setup, the client sends the server a Client Hello message specifying, among other information, the cipher suites that it is able to handle. A client is usually a web browser (most popular SSL client nowadays), but not necessarily, since it can be any SSL-enabled application; the same holds for the server, which needs not be a web server, though this is the most common case. (For example, a noteworthy class of SSL clients is that of SSL proxies such as stunnel (www.stunnel.org) which can be used to allow non-SSL enabled tools to talk to SSL services.) A cipher suite is specified by an encryption protocol (DES, RC4, AES), the encryption key length (such as 40, 56, or 128 bits), and a hash algorithm (SHA, MD5) used for integrity checking. Upon receiving a Client Hello message, the server decides which cipher suite it will use for that session. It is possible (for example, by means of configuration directives) to specify which cipher suites the server will honor. In this way you may control, for example, whether or not conversations with clients will support 40-bit encryption only.

==SSL Testing Criteria==
Large number of available cipher suites and quick progress in cryptoanalysis makes judging a SSL server a non-trivial task. These criteria are widely recognised as minimum checklist:

* SSLv2, due to known weaknesses in protocol design [http://www.schneier.com/paper-ssl.html]
* SSLv3, due to known weaknesses in protocol design [http://www.yaksman.org/~lweith/ssl.pdf]
* Compression, due to known weaknesses in protocol design [http://www.ekoparty.org/2012/juliano-rizzo.php]
* Cipher suites with symmetric encryption algorithm smaller than 112 bits
* X.509 certificates with RSA key smaller than 2048 bits
* X.509 certificates with DSA key smaller than 2048 bits
* X.509 certificates signed using MD5 hash, due to known collision attacks on this hash
* TLS Renegotiation vulnerability [http://www.phonefactor.com/sslgap/ssl-tls-authentication-patches]

The following standards can be used as reference while assessing SSL servers:

* [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf NIST SP 800-52] recommends U.S. federal systems to use at least TLS 1.0 with ciphersuites based on RSA or DSA key agreement with ephemeral Diffie-Hellman, 3DES or AES for confidentality and SHA1 for integrity protection. NIST SP 800-52 specifically disallows non-FIPS compliant algorithms like RC4 and MD5. An exception is U.S. federal systems making connections to outside servers, where these algorithms can be used in SSL client mode.
* [https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml PCI-DSS v1.2] in point 4.1 requires compliant parties to use "strong cryptography" without precisely defining key lengths and algorithms. Common interpretation, partially based on previous versions of the standard, is that at least 128 bit key cipher, no export strength algorithms and no SSLv2 should be used[http://www.digicert.com/news/DigiCert_PCI_White_Paper.pdf].
* [https://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide] has been proposed to standardize SSL server assessment and currently is in draft version.

SSL Server Database can be used to assess configuration of publicly available SSL servers[https://www.ssllabs.com/ssldb/analyze.html] based on SSL Rating Guide[https://www.ssllabs.com/projects/rating-guide/index.html]

==Black Box Test and example==

In order to detect possible support of weak ciphers, the ports associated to SSL/TLS wrapped services must be identified. These typically include port 443, which is the standard https port; however, this may change because a) https services may be configured to run on non-standard ports, and b) there may be additional SSL/TLS wrapped services related to the web application. In general, a service discovery is required to identify such ports.

The nmap scanner, via the “–sV” scan option, is able to identify SSL services. Vulnerability Scanners, in addition to performing service discovery, may include checks against weak ciphers (for example, the Nessus scanner has the capability of checking SSL services on arbitrary ports, and will report weak ciphers).

'''Example 1'''. SSL service recognition via nmap.

<pre>
[root@test]# nmap -F -sV localhost

Starting nmap 3.75 ( http://www.insecure.org/nmap/ ) at 2005-07-27 14:41 CEST
Interesting ports on localhost.localdomain (127.0.0.1):
(The 1205 ports scanned but not shown below are in state: closed)

PORT STATE SERVICE VERSION
443/tcp open ssl OpenSSL
901/tcp open http Samba SWAT administration server
8080/tcp open http Apache httpd 2.0.54 ((Unix) mod_ssl/2.0.54 OpenSSL/0.9.7g PHP/4.3.11)
8081/tcp open http Apache Tomcat/Coyote JSP engine 1.0

Nmap run completed -- 1 IP address (1 host up) scanned in 27.881 seconds
[root@test]#
</pre>

'''Example 2'''. Identifying weak ciphers with Nessus.
The following is an anonymized excerpt of a report generated by the Nessus scanner, corresponding to the identification of a server certificate allowing weak ciphers (see underlined text).

'''https (443/tcp)'''
'''Description'''
Here is the SSLv2 server certificate:
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: md5WithRSAEncryption
Issuer: C=**, ST=******, L=******, O=******, OU=******, CN=******
Validity
Not Before: Oct 17 07:12:16 2002 GMT
Not After : Oct 16 07:12:16 2004 GMT
Subject: C=**, ST=******, L=******, O=******, CN=******
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:98:4f:24:16:cb:0f:74:e8:9c:55:ce:62:14:4e:
6b:84:c5:81:43:59:c1:2e:ac:ba:af:92:51:f3:0b:
ad:e1:4b:22:ba:5a:9a:1e:0f:0b:fb:3d:5d:e6:fc:
ef:b8:8c:dc:78:28:97:8b:f0:1f:17:9f:69:3f:0e:
72:51:24:1b:9c:3d:85:52:1d:df:da:5a:b8:2e:d2:
09:00:76:24:43:bc:08:67:6b:dd:6b:e9:d2:f5:67:
e1:90:2a:b4:3b:b4:3c:b3:71:4e:88:08:74:b9:a8:
2d:c4:8c:65:93:08:e6:2f:fd:e0:fa:dc:6d:d7:a2:
3d:0a:75:26:cf:dc:47:74:29
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
Page 10
Network Vulnerability Assessment Report 25.05.2005
X509v3 Subject Key Identifier:
10:00:38:4C:45:F0:7C:E4:C6:A7:A4:E2:C9:F0:E4:2B:A8:F9:63:A8
X509v3 Authority Key Identifier:
keyid:CE:E5:F9:41:7B:D9:0E:5E:5D:DF:5E:B9:F3:E6:4A:12:19:02:76:CE
DirName:/C=**/ST=******/L=******/O=******/OU=******/CN=******
serial:00
Signature Algorithm: md5WithRSAEncryption
7b:14:bd:c7:3c:0c:01:8d:69:91:95:46:5c:e6:1e:25:9b:aa:
8b:f5:0d:de:e3:2e:82:1e:68:be:97:3b:39:4a:83:ae:fd:15:
2e:50:c8:a7:16:6e:c9:4e:76:cc:fd:69:ae:4f:12:b8:e7:01:
b6:58:7e:39:d1:fa:8d:49:bd:ff:6b:a8:dd:ae:83:ed:bc:b2:
40:e3:a5:e0:fd:ae:3f:57:4d:ec:f3:21:34:b1:84:97:06:6f:
f4:7d:f4:1c:84:cc:bb:1c:1c:e7:7a:7d:2d:e9:49:60:93:12:
0d:9f:05:8c:8e:f9:cf:e8:9f:fc:15:c0:6e:e2:fe:e5:07:81:
82:fc
Here is the list of available SSLv2 ciphers:
RC4-MD5
EXP-RC4-MD5
RC2-CBC-MD5
EXP-RC2-CBC-MD5
DES-CBC-MD5
DES-CBC3-MD5
RC4-64-MD5
The SSLv2 server offers 5 strong ciphers, but also 0 medium strength and '''2 weak "export class" ciphers'''.
The weak/medium ciphers may be chosen by an export-grade or badly configured client software. They only offer a limited protection against a brute force attack
Solution: disable those ciphers and upgrade your client software if necessary.
See http://support.microsoft.com/default.aspx?scid=kben-us216482
or http://httpd.apache.org/docs-2.0/mod/mod_ssl.html#sslciphersuite
This SSLv2 server also accepts SSLv3 connections.
This SSLv2 server also accepts TLSv1 connections.

Vulnerable hosts
''(list of vulnerable hosts follows)''

'''Example 3'''. Manually audit weak SSL cipher levels with OpenSSL. The following will attempt to connect to Google.com with SSLv2.
<pre>
[root@test]# openssl s_client -no_tls1 -no_ssl3 -connect www.google.com:443
CONNECTED(00000003)
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDYzCCAsygAwIBAgIQYFbAC3yUC8RFj9MS7lfBkzANBgkqhkiG9w0BAQQFADCB
zjELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJ
Q2FwZSBUb3duMR0wGwYDVQQKExRUaGF3dGUgQ29uc3VsdGluZyBjYzEoMCYGA1UE
CxMfQ2VydGlmaWNhdGlvbiBTZXJ2aWNlcyBEaXZpc2lvbjEhMB8GA1UEAxMYVGhh
d3RlIFByZW1pdW0gU2VydmVyIENBMSgwJgYJKoZIhvcNAQkBFhlwcmVtaXVtLXNl
cnZlckB0aGF3dGUuY29tMB4XDTA2MDQyMTAxMDc0NVoXDTA3MDQyMTAxMDc0NVow
aDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDU1v
dW50YWluIFZpZXcxEzARBgNVBAoTCkdvb2dsZSBJbmMxFzAVBgNVBAMTDnd3dy5n
b29nbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/e2Vs8U33fRDk
5NNpNgkB1zKw4rqTozmfwty7eTEI8PVH1Bf6nthocQ9d9SgJAI2WOBP4grPj7MqO
dXMTFWGDfiTnwes16G7NZlyh6peT68r7ifrwSsVLisJp6pUf31M5Z3D88b+Yy4PE
D7BJaTxq6NNmP1vYUJeXsGSGrV6FUQIDAQABo4GmMIGjMB0GA1UdJQQWMBQGCCsG
AQUFBwMBBggrBgEFBQcDAjBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vY3JsLnRo
YXd0ZS5jb20vVGhhd3RlUHJlbWl1bVNlcnZlckNBLmNybDAyBggrBgEFBQcBAQQm
MCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0ZS5jb20wDAYDVR0TAQH/
BAIwADANBgkqhkiG9w0BAQQFAAOBgQADlTbBdVY6LD1nHWkhTadmzuWq2rWE0KO3
Ay+7EleYWPOo+EST315QLpU6pQgblgobGoI5x/fUg2U8WiYj1I1cbavhX2h1hda3
FJWnB3SiXaiuDTsGxQ267EwCVWD5bCrSWa64ilSJTgiUmzAv0a2W8YHXdG08+nYc
X/dVk5WRTw==
-----END CERTIFICATE-----
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
---
No client certificate CA names sent
---
Ciphers common between both SSL endpoints:
RC4-MD5 EXP-RC4-MD5 RC2-CBC-MD5
EXP-RC2-CBC-MD5 DES-CBC-MD5 DES-CBC3-MD5
RC4-64-MD5
---
SSL handshake has read 1023 bytes and written 333 bytes
---
New, SSLv2, Cipher is DES-CBC3-MD5
Server public key is 1024 bit
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : SSLv2
Cipher : DES-CBC3-MD5
Session-ID: 709F48E4D567C70A2E49886E4C697CDE
Session-ID-ctx:
Master-Key: 649E68F8CF936E69642286AC40A80F433602E3C36FD288C3
Key-Arg : E8CB6FEB9ECF3033
Start Time: 1156977226
Timeout : 300 (sec)
Verify return code: 21 (unable to verify the first certificate)
---
closed
</pre>

'''Example 4'''. Testing supported protocols and ciphers using SSLScan.

SSLScan is a free command line tool that scans a HTTPS service to enumerate what protocols (supports SSLv2, SSLv3 and TLS1) and what ciphers the HTTPS service supports. It runs both on Linux and Windows OS (OSX not tested) and is released under a open source license.

<pre>
[user@test]$ ./SSLScan --no-failed mail.google.com
_
___ ___| |___ ___ __ _ _ __
/ __/ __| / __|/ __/ _` | '_ \
\__ \__ \ \__ \ (_| (_| | | | |
|___/___/_|___/\___\__,_|_| |_|

Version 1.9.0-win
http://www.titania.co.uk
Copyright 2010 Ian Ventura-Whiting / Michael Boman
Compiled against OpenSSL 0.9.8n 24 Mar 2010

Testing SSL server mail.google.com on port 443

Supported Server Cipher(s):
accepted SSLv3 256 bits AES256-SHA
accepted SSLv3 128 bits AES128-SHA
accepted SSLv3 168 bits DES-CBC3-SHA
accepted SSLv3 128 bits RC4-SHA
accepted SSLv3 128 bits RC4-MD5
accepted TLSv1 256 bits AES256-SHA
accepted TLSv1 128 bits AES128-SHA
accepted TLSv1 168 bits DES-CBC3-SHA
accepted TLSv1 128 bits RC4-SHA
accepted TLSv1 128 bits RC4-MD5

Prefered Server Cipher(s):
SSLv3 128 bits RC4-SHA
TLSv1 128 bits RC4-SHA

SSL Certificate:
Version: 2
Serial Number: -4294967295
Signature Algorithm: sha1WithRSAEncryption
Issuer: /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
Not valid before: Dec 18 00:00:00 2009 GMT
Not valid after: Dec 18 23:59:59 2011 GMT
Subject: /C=US/ST=California/L=Mountain View/O=Google Inc/CN=mail.google.com
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:d9:27:c8:11:f2:7b:e4:45:c9:46:b6:63:75:83:
b1:77:7e:17:41:89:80:38:f1:45:27:a0:3c:d9:e8:
a8:00:4b:d9:07:d0:ba:de:ed:f4:2c:a6:ac:dc:27:
13:ec:0c:c1:a6:99:17:42:e6:8d:27:d2:81:14:b0:
4b:82:fa:b2:c5:d0:bb:20:59:62:28:a3:96:b5:61:
f6:76:c1:6d:46:d2:fd:ba:c6:0f:3d:d1:c9:77:9a:
58:33:f6:06:76:32:ad:51:5f:29:5f:6e:f8:12:8b:
ad:e6:c5:08:39:b3:43:43:a9:5b:91:1d:d7:e3:cf:
51:df:75:59:8e:8d:80:ab:53
Exponent: 65537 (0x10001)
X509v3 Extensions:
X509v3 Basic Constraints: critical
CA:FALSE X509v3 CRL Distribution Points:
URI:http://crl.thawte.com/ThawteSGCCA.crl
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication, Netscape Server Gated Crypto Authority Information Access:
OCSP - URI:http://ocsp.thawte.com
CA Issuers - URI:http://www.thawte.com/repository/Thawte_SGC_CA.crt
Verify Certificate:
unable to get local issuer certificate

Renegotiation requests supported
</pre>

'''Example 5'''. Testing common SSL flaws with ssl_tests

ssl_tests (http://www.pentesterscripting.com/discovery/ssl_tests) is a bash script that uses sslscan and openssl to check for various flaws - ssl version 2, weak ciphers, md5withRSAEncryption,SSLv3 Force Ciphering Bug/Renegotiation.

<pre>

[user@test]$ ./ssl_test.sh 192.168.1.3 443
+++++++++++++++++++++++++++++++++++++++++++++++++
SSL Tests - v2, weak ciphers, MD5, Renegotiation
by Aung Khant, http://yehg.net
+++++++++++++++++++++++++++++++++++++++++++++++++

[*] testing on 192.168.1.3:443 ..

[*] tesing for sslv2 ..
[*] sslscan 192.168.1.3:443 | grep Accepted SSLv2
Accepted SSLv2 168 bits DES-CBC3-MD5
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 128 bits RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv2 128 bits RC4-MD5

[*] testing for weak ciphers ...
[*] sslscan 192.168.1.3:443 | grep 40 bits | grep Accepted
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv3 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-RC2-CBC-MD5
Accepted SSLv3 40 bits EXP-RC4-MD5
Accepted TLSv1 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-RC2-CBC-MD5
Accepted TLSv1 40 bits EXP-RC4-MD5

[*] sslscan 192.168.1.3:443 | grep 56 bits | grep Accepted
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv3 56 bits EDH-RSA-DES-CBC-SHA
Accepted SSLv3 56 bits DES-CBC-SHA
Accepted TLSv1 56 bits EDH-RSA-DES-CBC-SHA
Accepted TLSv1 56 bits DES-CBC-SHA

[*] testing for MD5 certificate ..
[*] sslscan 192.168.1.3:443 | grep MD5WithRSAEncryption

[*] testing for SSLv3 Force Ciphering Bug/Renegotiation ..
[*] echo R | openssl s_client -connect 192.168.1.3:443 | grep DONE
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
RENEGOTIATING
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
DONE

[*] done

</pre>

==White Box Test and example==

Check the configuration of the web servers which provide https services. If the web application provides other SSL/TLS wrapped services, these should be checked as well.

'''Example:''' The following registry path in Microsoft Windows 2003 defines the ciphers available to the server:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\

==Testing SSL certificate validity – client and server==

When accessing a web application via the https protocol, a secure channel is established between the client (usually the browser) and the server. The identity of one (the server) or both parties (client and server) is then established by means of digital certificates. In order for the communication to be set up, a number of checks on the certificates must be passed. While discussing SSL and certificate based authentication is beyond the scope of this Guide, we will focus on the main criteria involved in ascertaining certificate validity: a) checking if the Certificate Authority (CA) is a known one (meaning one considered trusted), b) checking that the certificate is currently valid, and c) checking that the name of the site and the name reported in the certificate match.
Remember to upgrade your browser because CA certs expired too, in every release of the browser, CA Certs has been renewed. Moreover it's important to update the browser because more web sites require strong cipher more of 40 or 56 bit.

Let’s examine each check more in detail.

a) Each browser comes with a preloaded list of trusted CAs, against which the certificate signing CA is compared (this list can be customized and expanded at will). During the initial negotiations with an https server, if the server certificate relates to a CA unknown to the browser, a warning is usually raised. This happens most often because a web application relies on a certificate signed by a self-established CA. Whether this is to be considered a concern depends on several factors. For example, this may be fine for an Intranet environment (think of corporate web email being provided via https; here, obviously all users recognize the internal CA as a trusted CA). When a service is provided to the general public via the Internet, however (i.e. when it is important to positively verify the identity of the server we are talking to), it is usually imperative to rely on a trusted CA, one which is recognized by all the user base (and here we stop with our considerations; we won’t delve deeper in the implications of the trust model being used by digital certificates).

b) Certificates have an associated period of validity, therefore they may expire. Again, we are warned by the browser about this. A public service needs a temporally valid certificate; otherwise, it means we are talking with a server whose certificate was issued by someone we trust, but has expired without being renewed.

c) What if the name on the certificate and the name of the server do not match? If this happens, it might sound suspicious. For a number of reasons, this is not so rare to see. A system may host a number of name-based virtual hosts, which share the same IP address and are identified by means of the HTTP 1.1 Host: header information. In this case, since the SSL handshake checks the server certificate before the HTTP request is processed, it is not possible to assign different certificates to each virtual server. Therefore, if the name of the site and the name reported in the certificate do not match, we have a condition which is typically signalled by the browser. To avoid this, one of two techniques should be used. First is Server Name Indication (SNI), which is a TLS extension from [http://www.ietf.org/rfc/rfc3546.txt RFC 3546]; and second is IP-based virtual servers must be used. [2] and [3] describe techniques to deal with this problem and allow name-based virtual hosts to be correctly referenced.

===Black Box Testing and examples===

Examine the validity of the certificates used by the application. Browsers will issue a warning when encountering expired certificates, certificates issued by untrusted CAs, and certificates which do not match namewise with the site to which they should refer. By clicking on the padlock which appears in the browser window when visiting an https site, you can look at information related to the certificate – including the issuer, period of validity, encryption characteristics, etc.

If the application requires a client certificate, you probably have installed one to access it. Certificate information is available in the browser by inspecting the relevant certificate(s) in the list of the installed certificates.

These checks must be applied to all visible SSL-wrapped communication channels used by the application. Though this is the usual https service running on port 443, there may be additional services involved depending on the web application architecture and on deployment issues (an https administrative port left open, https services on non-standard ports, etc.). Therefore, apply these checks to all SSL-wrapped ports which have been discovered. For example, the nmap scanner features a scanning mode (enabled by the –sV command line switch) which identifies SSL-wrapped services. The Nessus vulnerability scanner has the capability of performing SSL checks on all SSL/TLS-wrapped services.

'''Examples'''

Rather than providing a fictitious example, we have inserted an anonymized real-life example to stress how frequently one stumbles on https sites whose certificates are inaccurate with respect to naming.

The following screenshots refer to a regional site of a high-profile IT company.

Warning issued by Microsoft Internet Explorer. We are visiting an ''.it'' site and the certificate was issued to a ''.com ''site! Internet Explorer warns that the name on the certificate does not match the name of the site.

[[Image:SSL Certificate Validity Testing IE Warning.gif]]

Warning issued by Mozilla Firefox. The message issued by Firefox is different – Firefox complains because it cannot ascertain the identity of the ''.com'' site the certificate refers to because it does not know the CA which signed the certificate. In fact, Internet Explorer and Firefox do not come preloaded with the same list of CAs. Therefore, the behavior experienced with various browsers may differ.

[[Image:SSL Certificate Validity Testing Firefox Warning.gif]]

===White Box Testing and examples===

Examine the validity of the certificates used by the application at both server and client levels. The usage of certificates is primarily at the web server level; however, there may be additional communication paths protected by SSL (for example, towards the DBMS). You should check the application architecture to identify all SSL protected channels.

==References==
'''Whitepapers''' 
* [1] RFC2246. The TLS Protocol Version 1.0 (updated by RFC3546) - http://www.ietf.org/rfc/rfc2246.txt
* [2] RFC2817. Upgrading to TLS Within HTTP/1.1 - http://www.ietf.org/rfc/rfc2817.txt
* [3] RFC3546. Transport Layer Security (TLS) Extensions - http://www.ietf.org/rfc/rfc3546.txt
* [4] www.verisign.net features various material on the topic

'''Tools'''

* https://www.ssllabs.com/ssldb/

* Vulnerability scanners may include checks regarding certificate validity, including name mismatch and time expiration. They usually report other information as well, such as the CA which issued the certificate. Remember that there is no unified notion of a “trusted CA”; what is trusted depends on the configuration of the software and on the human assumptions made beforehand. Browsers come with a preloaded list of trusted CAs. If your web application relies on a CA which is not in this list (for example, because you rely on a self-made CA), you should take into account the process of configuring user browsers to recognize the CA.

* The Nessus scanner includes a plugin to check for expired certificates or certificates which are going to expire within 60 days (plugin “SSL certificate expiry”, plugin id 15901). This plugin will check certificates ''installed on the server.

* Vulnerability scanners may include checks against weak ciphers. For example, the Nessus scanner (http://www.nessus.org) has this capability and flags the presence of SSL weak ciphers (see example provided above).

* You may also rely on specialized tools such as SSL Digger (http://www.mcafee.com/us/downloads/free-tools/ssldigger.aspx), or – for the command line oriented – experiment with the openssl tool, which provides access to OpenSSL cryptographic functions directly from a Unix shell (may be already available on *nix boxes, otherwise see www.openssl.org).

* To identify SSL-based services, use a vulnerability scanner or a port scanner with service recognition capabilities. The nmap scanner features a “-sV” scanning option which tries to identify services, while the nessus vulnerability scanner has the capability of identifying SSL-based services on arbitrary ports and to run vulnerability checks on them regardless of whether they are configured on standard or non-standard ports.

* In case you need to talk to a SSL service but your favourite tool doesn’t support SSL, you may benefit from a SSL proxy such as stunnel; stunnel will take care of tunneling the underlying protocol (usually http, but not necessarily so) and communicate with the SSL service you need to reach.

* ssl_tests, http://www.pentesterscripting.com/discovery/ssl_tests

* Finally, a word of advice. Though it may be tempting to use a regular browser to check certificates, there are various reasons for not doing so. Browsers have been plagued by various bugs in this area, and the way the browser will perform the check might be influenced by configuration settings that may not be evident. Instead, rely on vulnerability scanners or on specialized tools to do the job.

* [http://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet OWASP Transport Layer Protection Cheat Sheet]

[[Category:Cryptographic Vulnerability]]
[[Category:SSL]]

Testing for SSL-TLS (OWASP-CM-001)

2013-03-10T05:37:25Z

Jeffrey Walton: SP800-52 states 1024-bit is acceptable until 2010. Time for an update to 2048 (112-bit security level).....

{{Template:OWASP Testing Guide v3}}

== Brief Summary ==

Due to historic export restrictions of high grade cryptography, legacy and new web servers are often able and configured to handle weak cryptographic options.

Even if high grade ciphers are normally used and installed, some server misconfiguration could be used to force the use of a weaker cipher to gain access to the supposed secure communication channel.

==Testing SSL / TLS Cipher Specifications and Requirements ==

The http clear-text protocol is normally secured via an SSL or TLS tunnel, resulting in https traffic. In addition to providing encryption of data in transit, https allows the identification of servers (and, optionally, of clients) by means of digital certificates.

Historically, there have been limitations set in place by the U.S. government to allow cryptosystems to be exported only for key sizes of, at most, 40 bits, a key length which could be broken and would allow the decryption of communications. Since then, cryptographic export regulations have been relaxed (though some constraints still hold); however, it is important to check the SSL configuration being used to avoid putting in place cryptographic support which could be easily defeated. SSL-based services should not offer the possibility to choose weak ciphers.

Cipher determination is performed as follows: in the initial phase of a SSL connection setup, the client sends the server a Client Hello message specifying, among other information, the cipher suites that it is able to handle. A client is usually a web browser (most popular SSL client nowadays), but not necessarily, since it can be any SSL-enabled application; the same holds for the server, which needs not be a web server, though this is the most common case. (For example, a noteworthy class of SSL clients is that of SSL proxies such as stunnel (www.stunnel.org) which can be used to allow non-SSL enabled tools to talk to SSL services.) A cipher suite is specified by an encryption protocol (DES, RC4, AES), the encryption key length (such as 40, 56, or 128 bits), and a hash algorithm (SHA, MD5) used for integrity checking. Upon receiving a Client Hello message, the server decides which cipher suite it will use for that session. It is possible (for example, by means of configuration directives) to specify which cipher suites the server will honor. In this way you may control, for example, whether or not conversations with clients will support 40-bit encryption only.

==SSL Testing Criteria==
Large number of available cipher suites and quick progress in cryptoanalysis makes judging a SSL server a non-trivial task. These criteria are widely recognised as minimum checklist:

* SSLv2, due to known weaknesses in protocol design [http://www.schneier.com/paper-ssl.html]
* SSLv3, due to known weaknesses in protocol design [http://www.yaksman.org/~lweith/ssl.pdf]
* Compression, due to known weaknesses in protocol design [http://www.ekoparty.org/2012/juliano-rizzo.php]
* Cipher suites with symmetric encryption algorithm smaller than 112 bits
* X.509 certificates with RSA or DSA key smaller than 2048 bits
* X.509 certificates signed using MD5 hash, due to known collision attacks on this hash
* TLS Renegotiation vulnerability [http://www.phonefactor.com/sslgap/ssl-tls-authentication-patches]

The following standards can be used as reference while assessing SSL servers:

* [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf NIST SP 800-52] recommends U.S. federal systems to use at least TLS 1.0 with ciphersuites based on RSA or DSA key agreement with ephemeral Diffie-Hellman, 3DES or AES for confidentality and SHA1 for integrity protection. NIST SP 800-52 specifically disallows non-FIPS compliant algorithms like RC4 and MD5. An exception is U.S. federal systems making connections to outside servers, where these algorithms can be used in SSL client mode.
* [https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml PCI-DSS v1.2] in point 4.1 requires compliant parties to use "strong cryptography" without precisely defining key lengths and algorithms. Common interpretation, partially based on previous versions of the standard, is that at least 128 bit key cipher, no export strength algorithms and no SSLv2 should be used[http://www.digicert.com/news/DigiCert_PCI_White_Paper.pdf].
* [https://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide] has been proposed to standardize SSL server assessment and currently is in draft version.

SSL Server Database can be used to assess configuration of publicly available SSL servers[https://www.ssllabs.com/ssldb/analyze.html] based on SSL Rating Guide[https://www.ssllabs.com/projects/rating-guide/index.html]

==Black Box Test and example==

In order to detect possible support of weak ciphers, the ports associated to SSL/TLS wrapped services must be identified. These typically include port 443, which is the standard https port; however, this may change because a) https services may be configured to run on non-standard ports, and b) there may be additional SSL/TLS wrapped services related to the web application. In general, a service discovery is required to identify such ports.

The nmap scanner, via the “–sV” scan option, is able to identify SSL services. Vulnerability Scanners, in addition to performing service discovery, may include checks against weak ciphers (for example, the Nessus scanner has the capability of checking SSL services on arbitrary ports, and will report weak ciphers).

'''Example 1'''. SSL service recognition via nmap.

<pre>
[root@test]# nmap -F -sV localhost

Starting nmap 3.75 ( http://www.insecure.org/nmap/ ) at 2005-07-27 14:41 CEST
Interesting ports on localhost.localdomain (127.0.0.1):
(The 1205 ports scanned but not shown below are in state: closed)

PORT STATE SERVICE VERSION
443/tcp open ssl OpenSSL
901/tcp open http Samba SWAT administration server
8080/tcp open http Apache httpd 2.0.54 ((Unix) mod_ssl/2.0.54 OpenSSL/0.9.7g PHP/4.3.11)
8081/tcp open http Apache Tomcat/Coyote JSP engine 1.0

Nmap run completed -- 1 IP address (1 host up) scanned in 27.881 seconds
[root@test]#
</pre>

'''Example 2'''. Identifying weak ciphers with Nessus.
The following is an anonymized excerpt of a report generated by the Nessus scanner, corresponding to the identification of a server certificate allowing weak ciphers (see underlined text).

'''https (443/tcp)'''
'''Description'''
Here is the SSLv2 server certificate:
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: md5WithRSAEncryption
Issuer: C=**, ST=******, L=******, O=******, OU=******, CN=******
Validity
Not Before: Oct 17 07:12:16 2002 GMT
Not After : Oct 16 07:12:16 2004 GMT
Subject: C=**, ST=******, L=******, O=******, CN=******
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:98:4f:24:16:cb:0f:74:e8:9c:55:ce:62:14:4e:
6b:84:c5:81:43:59:c1:2e:ac:ba:af:92:51:f3:0b:
ad:e1:4b:22:ba:5a:9a:1e:0f:0b:fb:3d:5d:e6:fc:
ef:b8:8c:dc:78:28:97:8b:f0:1f:17:9f:69:3f:0e:
72:51:24:1b:9c:3d:85:52:1d:df:da:5a:b8:2e:d2:
09:00:76:24:43:bc:08:67:6b:dd:6b:e9:d2:f5:67:
e1:90:2a:b4:3b:b4:3c:b3:71:4e:88:08:74:b9:a8:
2d:c4:8c:65:93:08:e6:2f:fd:e0:fa:dc:6d:d7:a2:
3d:0a:75:26:cf:dc:47:74:29
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
Page 10
Network Vulnerability Assessment Report 25.05.2005
X509v3 Subject Key Identifier:
10:00:38:4C:45:F0:7C:E4:C6:A7:A4:E2:C9:F0:E4:2B:A8:F9:63:A8
X509v3 Authority Key Identifier:
keyid:CE:E5:F9:41:7B:D9:0E:5E:5D:DF:5E:B9:F3:E6:4A:12:19:02:76:CE
DirName:/C=**/ST=******/L=******/O=******/OU=******/CN=******
serial:00
Signature Algorithm: md5WithRSAEncryption
7b:14:bd:c7:3c:0c:01:8d:69:91:95:46:5c:e6:1e:25:9b:aa:
8b:f5:0d:de:e3:2e:82:1e:68:be:97:3b:39:4a:83:ae:fd:15:
2e:50:c8:a7:16:6e:c9:4e:76:cc:fd:69:ae:4f:12:b8:e7:01:
b6:58:7e:39:d1:fa:8d:49:bd:ff:6b:a8:dd:ae:83:ed:bc:b2:
40:e3:a5:e0:fd:ae:3f:57:4d:ec:f3:21:34:b1:84:97:06:6f:
f4:7d:f4:1c:84:cc:bb:1c:1c:e7:7a:7d:2d:e9:49:60:93:12:
0d:9f:05:8c:8e:f9:cf:e8:9f:fc:15:c0:6e:e2:fe:e5:07:81:
82:fc
Here is the list of available SSLv2 ciphers:
RC4-MD5
EXP-RC4-MD5
RC2-CBC-MD5
EXP-RC2-CBC-MD5
DES-CBC-MD5
DES-CBC3-MD5
RC4-64-MD5
The SSLv2 server offers 5 strong ciphers, but also 0 medium strength and '''2 weak "export class" ciphers'''.
The weak/medium ciphers may be chosen by an export-grade or badly configured client software. They only offer a limited protection against a brute force attack
Solution: disable those ciphers and upgrade your client software if necessary.
See http://support.microsoft.com/default.aspx?scid=kben-us216482
or http://httpd.apache.org/docs-2.0/mod/mod_ssl.html#sslciphersuite
This SSLv2 server also accepts SSLv3 connections.
This SSLv2 server also accepts TLSv1 connections.

Vulnerable hosts
''(list of vulnerable hosts follows)''

'''Example 3'''. Manually audit weak SSL cipher levels with OpenSSL. The following will attempt to connect to Google.com with SSLv2.
<pre>
[root@test]# openssl s_client -no_tls1 -no_ssl3 -connect www.google.com:443
CONNECTED(00000003)
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDYzCCAsygAwIBAgIQYFbAC3yUC8RFj9MS7lfBkzANBgkqhkiG9w0BAQQFADCB
zjELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJ
Q2FwZSBUb3duMR0wGwYDVQQKExRUaGF3dGUgQ29uc3VsdGluZyBjYzEoMCYGA1UE
CxMfQ2VydGlmaWNhdGlvbiBTZXJ2aWNlcyBEaXZpc2lvbjEhMB8GA1UEAxMYVGhh
d3RlIFByZW1pdW0gU2VydmVyIENBMSgwJgYJKoZIhvcNAQkBFhlwcmVtaXVtLXNl
cnZlckB0aGF3dGUuY29tMB4XDTA2MDQyMTAxMDc0NVoXDTA3MDQyMTAxMDc0NVow
aDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDU1v
dW50YWluIFZpZXcxEzARBgNVBAoTCkdvb2dsZSBJbmMxFzAVBgNVBAMTDnd3dy5n
b29nbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/e2Vs8U33fRDk
5NNpNgkB1zKw4rqTozmfwty7eTEI8PVH1Bf6nthocQ9d9SgJAI2WOBP4grPj7MqO
dXMTFWGDfiTnwes16G7NZlyh6peT68r7ifrwSsVLisJp6pUf31M5Z3D88b+Yy4PE
D7BJaTxq6NNmP1vYUJeXsGSGrV6FUQIDAQABo4GmMIGjMB0GA1UdJQQWMBQGCCsG
AQUFBwMBBggrBgEFBQcDAjBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vY3JsLnRo
YXd0ZS5jb20vVGhhd3RlUHJlbWl1bVNlcnZlckNBLmNybDAyBggrBgEFBQcBAQQm
MCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0ZS5jb20wDAYDVR0TAQH/
BAIwADANBgkqhkiG9w0BAQQFAAOBgQADlTbBdVY6LD1nHWkhTadmzuWq2rWE0KO3
Ay+7EleYWPOo+EST315QLpU6pQgblgobGoI5x/fUg2U8WiYj1I1cbavhX2h1hda3
FJWnB3SiXaiuDTsGxQ267EwCVWD5bCrSWa64ilSJTgiUmzAv0a2W8YHXdG08+nYc
X/dVk5WRTw==
-----END CERTIFICATE-----
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
---
No client certificate CA names sent
---
Ciphers common between both SSL endpoints:
RC4-MD5 EXP-RC4-MD5 RC2-CBC-MD5
EXP-RC2-CBC-MD5 DES-CBC-MD5 DES-CBC3-MD5
RC4-64-MD5
---
SSL handshake has read 1023 bytes and written 333 bytes
---
New, SSLv2, Cipher is DES-CBC3-MD5
Server public key is 1024 bit
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : SSLv2
Cipher : DES-CBC3-MD5
Session-ID: 709F48E4D567C70A2E49886E4C697CDE
Session-ID-ctx:
Master-Key: 649E68F8CF936E69642286AC40A80F433602E3C36FD288C3
Key-Arg : E8CB6FEB9ECF3033
Start Time: 1156977226
Timeout : 300 (sec)
Verify return code: 21 (unable to verify the first certificate)
---
closed
</pre>

'''Example 4'''. Testing supported protocols and ciphers using SSLScan.

SSLScan is a free command line tool that scans a HTTPS service to enumerate what protocols (supports SSLv2, SSLv3 and TLS1) and what ciphers the HTTPS service supports. It runs both on Linux and Windows OS (OSX not tested) and is released under a open source license.

<pre>
[user@test]$ ./SSLScan --no-failed mail.google.com
_
___ ___| |___ ___ __ _ _ __
/ __/ __| / __|/ __/ _` | '_ \
\__ \__ \ \__ \ (_| (_| | | | |
|___/___/_|___/\___\__,_|_| |_|

Version 1.9.0-win
http://www.titania.co.uk
Copyright 2010 Ian Ventura-Whiting / Michael Boman
Compiled against OpenSSL 0.9.8n 24 Mar 2010

Testing SSL server mail.google.com on port 443

Supported Server Cipher(s):
accepted SSLv3 256 bits AES256-SHA
accepted SSLv3 128 bits AES128-SHA
accepted SSLv3 168 bits DES-CBC3-SHA
accepted SSLv3 128 bits RC4-SHA
accepted SSLv3 128 bits RC4-MD5
accepted TLSv1 256 bits AES256-SHA
accepted TLSv1 128 bits AES128-SHA
accepted TLSv1 168 bits DES-CBC3-SHA
accepted TLSv1 128 bits RC4-SHA
accepted TLSv1 128 bits RC4-MD5

Prefered Server Cipher(s):
SSLv3 128 bits RC4-SHA
TLSv1 128 bits RC4-SHA

SSL Certificate:
Version: 2
Serial Number: -4294967295
Signature Algorithm: sha1WithRSAEncryption
Issuer: /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
Not valid before: Dec 18 00:00:00 2009 GMT
Not valid after: Dec 18 23:59:59 2011 GMT
Subject: /C=US/ST=California/L=Mountain View/O=Google Inc/CN=mail.google.com
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:d9:27:c8:11:f2:7b:e4:45:c9:46:b6:63:75:83:
b1:77:7e:17:41:89:80:38:f1:45:27:a0:3c:d9:e8:
a8:00:4b:d9:07:d0:ba:de:ed:f4:2c:a6:ac:dc:27:
13:ec:0c:c1:a6:99:17:42:e6:8d:27:d2:81:14:b0:
4b:82:fa:b2:c5:d0:bb:20:59:62:28:a3:96:b5:61:
f6:76:c1:6d:46:d2:fd:ba:c6:0f:3d:d1:c9:77:9a:
58:33:f6:06:76:32:ad:51:5f:29:5f:6e:f8:12:8b:
ad:e6:c5:08:39:b3:43:43:a9:5b:91:1d:d7:e3:cf:
51:df:75:59:8e:8d:80:ab:53
Exponent: 65537 (0x10001)
X509v3 Extensions:
X509v3 Basic Constraints: critical
CA:FALSE X509v3 CRL Distribution Points:
URI:http://crl.thawte.com/ThawteSGCCA.crl
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication, Netscape Server Gated Crypto Authority Information Access:
OCSP - URI:http://ocsp.thawte.com
CA Issuers - URI:http://www.thawte.com/repository/Thawte_SGC_CA.crt
Verify Certificate:
unable to get local issuer certificate

Renegotiation requests supported
</pre>

'''Example 5'''. Testing common SSL flaws with ssl_tests

ssl_tests (http://www.pentesterscripting.com/discovery/ssl_tests) is a bash script that uses sslscan and openssl to check for various flaws - ssl version 2, weak ciphers, md5withRSAEncryption,SSLv3 Force Ciphering Bug/Renegotiation.

<pre>

[user@test]$ ./ssl_test.sh 192.168.1.3 443
+++++++++++++++++++++++++++++++++++++++++++++++++
SSL Tests - v2, weak ciphers, MD5, Renegotiation
by Aung Khant, http://yehg.net
+++++++++++++++++++++++++++++++++++++++++++++++++

[*] testing on 192.168.1.3:443 ..

[*] tesing for sslv2 ..
[*] sslscan 192.168.1.3:443 | grep Accepted SSLv2
Accepted SSLv2 168 bits DES-CBC3-MD5
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 128 bits RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv2 128 bits RC4-MD5

[*] testing for weak ciphers ...
[*] sslscan 192.168.1.3:443 | grep 40 bits | grep Accepted
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv3 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-RC2-CBC-MD5
Accepted SSLv3 40 bits EXP-RC4-MD5
Accepted TLSv1 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-RC2-CBC-MD5
Accepted TLSv1 40 bits EXP-RC4-MD5

[*] sslscan 192.168.1.3:443 | grep 56 bits | grep Accepted
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv3 56 bits EDH-RSA-DES-CBC-SHA
Accepted SSLv3 56 bits DES-CBC-SHA
Accepted TLSv1 56 bits EDH-RSA-DES-CBC-SHA
Accepted TLSv1 56 bits DES-CBC-SHA

[*] testing for MD5 certificate ..
[*] sslscan 192.168.1.3:443 | grep MD5WithRSAEncryption

[*] testing for SSLv3 Force Ciphering Bug/Renegotiation ..
[*] echo R | openssl s_client -connect 192.168.1.3:443 | grep DONE
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
RENEGOTIATING
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
DONE

[*] done

</pre>

==White Box Test and example==

Check the configuration of the web servers which provide https services. If the web application provides other SSL/TLS wrapped services, these should be checked as well.

'''Example:''' The following registry path in Microsoft Windows 2003 defines the ciphers available to the server:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\

==Testing SSL certificate validity – client and server==

When accessing a web application via the https protocol, a secure channel is established between the client (usually the browser) and the server. The identity of one (the server) or both parties (client and server) is then established by means of digital certificates. In order for the communication to be set up, a number of checks on the certificates must be passed. While discussing SSL and certificate based authentication is beyond the scope of this Guide, we will focus on the main criteria involved in ascertaining certificate validity: a) checking if the Certificate Authority (CA) is a known one (meaning one considered trusted), b) checking that the certificate is currently valid, and c) checking that the name of the site and the name reported in the certificate match.
Remember to upgrade your browser because CA certs expired too, in every release of the browser, CA Certs has been renewed. Moreover it's important to update the browser because more web sites require strong cipher more of 40 or 56 bit.

Let’s examine each check more in detail.

a) Each browser comes with a preloaded list of trusted CAs, against which the certificate signing CA is compared (this list can be customized and expanded at will). During the initial negotiations with an https server, if the server certificate relates to a CA unknown to the browser, a warning is usually raised. This happens most often because a web application relies on a certificate signed by a self-established CA. Whether this is to be considered a concern depends on several factors. For example, this may be fine for an Intranet environment (think of corporate web email being provided via https; here, obviously all users recognize the internal CA as a trusted CA). When a service is provided to the general public via the Internet, however (i.e. when it is important to positively verify the identity of the server we are talking to), it is usually imperative to rely on a trusted CA, one which is recognized by all the user base (and here we stop with our considerations; we won’t delve deeper in the implications of the trust model being used by digital certificates).

b) Certificates have an associated period of validity, therefore they may expire. Again, we are warned by the browser about this. A public service needs a temporally valid certificate; otherwise, it means we are talking with a server whose certificate was issued by someone we trust, but has expired without being renewed.

c) What if the name on the certificate and the name of the server do not match? If this happens, it might sound suspicious. For a number of reasons, this is not so rare to see. A system may host a number of name-based virtual hosts, which share the same IP address and are identified by means of the HTTP 1.1 Host: header information. In this case, since the SSL handshake checks the server certificate before the HTTP request is processed, it is not possible to assign different certificates to each virtual server. Therefore, if the name of the site and the name reported in the certificate do not match, we have a condition which is typically signalled by the browser. To avoid this, one of two techniques should be used. First is Server Name Indication (SNI), which is a TLS extension from [http://www.ietf.org/rfc/rfc3546.txt RFC 3546]; and second is IP-based virtual servers must be used. [2] and [3] describe techniques to deal with this problem and allow name-based virtual hosts to be correctly referenced.

===Black Box Testing and examples===

Examine the validity of the certificates used by the application. Browsers will issue a warning when encountering expired certificates, certificates issued by untrusted CAs, and certificates which do not match namewise with the site to which they should refer. By clicking on the padlock which appears in the browser window when visiting an https site, you can look at information related to the certificate – including the issuer, period of validity, encryption characteristics, etc.

If the application requires a client certificate, you probably have installed one to access it. Certificate information is available in the browser by inspecting the relevant certificate(s) in the list of the installed certificates.

These checks must be applied to all visible SSL-wrapped communication channels used by the application. Though this is the usual https service running on port 443, there may be additional services involved depending on the web application architecture and on deployment issues (an https administrative port left open, https services on non-standard ports, etc.). Therefore, apply these checks to all SSL-wrapped ports which have been discovered. For example, the nmap scanner features a scanning mode (enabled by the –sV command line switch) which identifies SSL-wrapped services. The Nessus vulnerability scanner has the capability of performing SSL checks on all SSL/TLS-wrapped services.

'''Examples'''

Rather than providing a fictitious example, we have inserted an anonymized real-life example to stress how frequently one stumbles on https sites whose certificates are inaccurate with respect to naming.

The following screenshots refer to a regional site of a high-profile IT company.

Warning issued by Microsoft Internet Explorer. We are visiting an ''.it'' site and the certificate was issued to a ''.com ''site! Internet Explorer warns that the name on the certificate does not match the name of the site.

[[Image:SSL Certificate Validity Testing IE Warning.gif]]

Warning issued by Mozilla Firefox. The message issued by Firefox is different – Firefox complains because it cannot ascertain the identity of the ''.com'' site the certificate refers to because it does not know the CA which signed the certificate. In fact, Internet Explorer and Firefox do not come preloaded with the same list of CAs. Therefore, the behavior experienced with various browsers may differ.

[[Image:SSL Certificate Validity Testing Firefox Warning.gif]]

===White Box Testing and examples===

Examine the validity of the certificates used by the application at both server and client levels. The usage of certificates is primarily at the web server level; however, there may be additional communication paths protected by SSL (for example, towards the DBMS). You should check the application architecture to identify all SSL protected channels.

==References==
'''Whitepapers''' 
* [1] RFC2246. The TLS Protocol Version 1.0 (updated by RFC3546) - http://www.ietf.org/rfc/rfc2246.txt
* [2] RFC2817. Upgrading to TLS Within HTTP/1.1 - http://www.ietf.org/rfc/rfc2817.txt
* [3] RFC3546. Transport Layer Security (TLS) Extensions - http://www.ietf.org/rfc/rfc3546.txt
* [4] www.verisign.net features various material on the topic

'''Tools'''

* https://www.ssllabs.com/ssldb/

* Vulnerability scanners may include checks regarding certificate validity, including name mismatch and time expiration. They usually report other information as well, such as the CA which issued the certificate. Remember that there is no unified notion of a “trusted CA”; what is trusted depends on the configuration of the software and on the human assumptions made beforehand. Browsers come with a preloaded list of trusted CAs. If your web application relies on a CA which is not in this list (for example, because you rely on a self-made CA), you should take into account the process of configuring user browsers to recognize the CA.

* The Nessus scanner includes a plugin to check for expired certificates or certificates which are going to expire within 60 days (plugin “SSL certificate expiry”, plugin id 15901). This plugin will check certificates ''installed on the server.

* Vulnerability scanners may include checks against weak ciphers. For example, the Nessus scanner (http://www.nessus.org) has this capability and flags the presence of SSL weak ciphers (see example provided above).

* You may also rely on specialized tools such as SSL Digger (http://www.mcafee.com/us/downloads/free-tools/ssldigger.aspx), or – for the command line oriented – experiment with the openssl tool, which provides access to OpenSSL cryptographic functions directly from a Unix shell (may be already available on *nix boxes, otherwise see www.openssl.org).

* To identify SSL-based services, use a vulnerability scanner or a port scanner with service recognition capabilities. The nmap scanner features a “-sV” scanning option which tries to identify services, while the nessus vulnerability scanner has the capability of identifying SSL-based services on arbitrary ports and to run vulnerability checks on them regardless of whether they are configured on standard or non-standard ports.

* In case you need to talk to a SSL service but your favourite tool doesn’t support SSL, you may benefit from a SSL proxy such as stunnel; stunnel will take care of tunneling the underlying protocol (usually http, but not necessarily so) and communicate with the SSL service you need to reach.

* ssl_tests, http://www.pentesterscripting.com/discovery/ssl_tests

* Finally, a word of advice. Though it may be tempting to use a regular browser to check certificates, there are various reasons for not doing so. Browsers have been plagued by various bugs in this area, and the way the browser will perform the check might be influenced by configuration settings that may not be evident. Instead, rely on vulnerability scanners or on specialized tools to do the job.

* [http://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet OWASP Transport Layer Protection Cheat Sheet]

[[Category:Cryptographic Vulnerability]]
[[Category:SSL]]

Testing for SSL-TLS (OWASP-CM-001)

2013-03-10T05:31:03Z

Jeffrey Walton: Added references to Testing Criteria

{{Template:OWASP Testing Guide v3}}

== Brief Summary ==

Due to historic export restrictions of high grade cryptography, legacy and new web servers are often able and configured to handle weak cryptographic options.

Even if high grade ciphers are normally used and installed, some server misconfiguration could be used to force the use of a weaker cipher to gain access to the supposed secure communication channel.

==Testing SSL / TLS Cipher Specifications and Requirements ==

The http clear-text protocol is normally secured via an SSL or TLS tunnel, resulting in https traffic. In addition to providing encryption of data in transit, https allows the identification of servers (and, optionally, of clients) by means of digital certificates.

Historically, there have been limitations set in place by the U.S. government to allow cryptosystems to be exported only for key sizes of, at most, 40 bits, a key length which could be broken and would allow the decryption of communications. Since then, cryptographic export regulations have been relaxed (though some constraints still hold); however, it is important to check the SSL configuration being used to avoid putting in place cryptographic support which could be easily defeated. SSL-based services should not offer the possibility to choose weak ciphers.

Cipher determination is performed as follows: in the initial phase of a SSL connection setup, the client sends the server a Client Hello message specifying, among other information, the cipher suites that it is able to handle. A client is usually a web browser (most popular SSL client nowadays), but not necessarily, since it can be any SSL-enabled application; the same holds for the server, which needs not be a web server, though this is the most common case. (For example, a noteworthy class of SSL clients is that of SSL proxies such as stunnel (www.stunnel.org) which can be used to allow non-SSL enabled tools to talk to SSL services.) A cipher suite is specified by an encryption protocol (DES, RC4, AES), the encryption key length (such as 40, 56, or 128 bits), and a hash algorithm (SHA, MD5) used for integrity checking. Upon receiving a Client Hello message, the server decides which cipher suite it will use for that session. It is possible (for example, by means of configuration directives) to specify which cipher suites the server will honor. In this way you may control, for example, whether or not conversations with clients will support 40-bit encryption only.

==SSL Testing Criteria==
Large number of available cipher suites and quick progress in cryptoanalysis makes judging a SSL server a non-trivial task. These criteria are widely recognised as minimum checklist:

* SSLv2, due to known weaknesses in protocol design [www.schneier.com/paper-ssl.html]
* SSLv3, due to known weaknesses in protocol design [www.yaksman.org/~lweith/ssl.pdf]
* Compression, due to known weaknesses in protocol design [http://www.ekoparty.org/2012/juliano-rizzo.php]
* Cipher suites with symmetric encryption algorithm smaller than 112 bits
* X.509 certificates with RSA or DSA key smaller than 1024 bits
* X.509 certificates signed using MD5 hash, due to known collision attacks on this hash
* TLS Renegotiation vulnerability [http://www.phonefactor.com/sslgap/ssl-tls-authentication-patches]

The following standards can be used as reference while assessing SSL servers:

* [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf NIST SP 800-52] recommends U.S. federal systems to use at least TLS 1.0 with ciphersuites based on RSA or DSA key agreement with ephemeral Diffie-Hellman, 3DES or AES for confidentality and SHA1 for integrity protection. NIST SP 800-52 specifically disallows non-FIPS compliant algorithms like RC4 and MD5. An exception is U.S. federal systems making connections to outside servers, where these algorithms can be used in SSL client mode.
* [https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml PCI-DSS v1.2] in point 4.1 requires compliant parties to use "strong cryptography" without precisely defining key lengths and algorithms. Common interpretation, partially based on previous versions of the standard, is that at least 128 bit key cipher, no export strength algorithms and no SSLv2 should be used[http://www.digicert.com/news/DigiCert_PCI_White_Paper.pdf].
* [https://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide] has been proposed to standardize SSL server assessment and currently is in draft version.

SSL Server Database can be used to assess configuration of publicly available SSL servers[https://www.ssllabs.com/ssldb/analyze.html] based on SSL Rating Guide[https://www.ssllabs.com/projects/rating-guide/index.html]

==Black Box Test and example==

In order to detect possible support of weak ciphers, the ports associated to SSL/TLS wrapped services must be identified. These typically include port 443, which is the standard https port; however, this may change because a) https services may be configured to run on non-standard ports, and b) there may be additional SSL/TLS wrapped services related to the web application. In general, a service discovery is required to identify such ports.

The nmap scanner, via the “–sV” scan option, is able to identify SSL services. Vulnerability Scanners, in addition to performing service discovery, may include checks against weak ciphers (for example, the Nessus scanner has the capability of checking SSL services on arbitrary ports, and will report weak ciphers).

'''Example 1'''. SSL service recognition via nmap.

<pre>
[root@test]# nmap -F -sV localhost

Starting nmap 3.75 ( http://www.insecure.org/nmap/ ) at 2005-07-27 14:41 CEST
Interesting ports on localhost.localdomain (127.0.0.1):
(The 1205 ports scanned but not shown below are in state: closed)

PORT STATE SERVICE VERSION
443/tcp open ssl OpenSSL
901/tcp open http Samba SWAT administration server
8080/tcp open http Apache httpd 2.0.54 ((Unix) mod_ssl/2.0.54 OpenSSL/0.9.7g PHP/4.3.11)
8081/tcp open http Apache Tomcat/Coyote JSP engine 1.0

Nmap run completed -- 1 IP address (1 host up) scanned in 27.881 seconds
[root@test]#
</pre>

'''Example 2'''. Identifying weak ciphers with Nessus.
The following is an anonymized excerpt of a report generated by the Nessus scanner, corresponding to the identification of a server certificate allowing weak ciphers (see underlined text).

'''https (443/tcp)'''
'''Description'''
Here is the SSLv2 server certificate:
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: md5WithRSAEncryption
Issuer: C=**, ST=******, L=******, O=******, OU=******, CN=******
Validity
Not Before: Oct 17 07:12:16 2002 GMT
Not After : Oct 16 07:12:16 2004 GMT
Subject: C=**, ST=******, L=******, O=******, CN=******
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:98:4f:24:16:cb:0f:74:e8:9c:55:ce:62:14:4e:
6b:84:c5:81:43:59:c1:2e:ac:ba:af:92:51:f3:0b:
ad:e1:4b:22:ba:5a:9a:1e:0f:0b:fb:3d:5d:e6:fc:
ef:b8:8c:dc:78:28:97:8b:f0:1f:17:9f:69:3f:0e:
72:51:24:1b:9c:3d:85:52:1d:df:da:5a:b8:2e:d2:
09:00:76:24:43:bc:08:67:6b:dd:6b:e9:d2:f5:67:
e1:90:2a:b4:3b:b4:3c:b3:71:4e:88:08:74:b9:a8:
2d:c4:8c:65:93:08:e6:2f:fd:e0:fa:dc:6d:d7:a2:
3d:0a:75:26:cf:dc:47:74:29
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
Page 10
Network Vulnerability Assessment Report 25.05.2005
X509v3 Subject Key Identifier:
10:00:38:4C:45:F0:7C:E4:C6:A7:A4:E2:C9:F0:E4:2B:A8:F9:63:A8
X509v3 Authority Key Identifier:
keyid:CE:E5:F9:41:7B:D9:0E:5E:5D:DF:5E:B9:F3:E6:4A:12:19:02:76:CE
DirName:/C=**/ST=******/L=******/O=******/OU=******/CN=******
serial:00
Signature Algorithm: md5WithRSAEncryption
7b:14:bd:c7:3c:0c:01:8d:69:91:95:46:5c:e6:1e:25:9b:aa:
8b:f5:0d:de:e3:2e:82:1e:68:be:97:3b:39:4a:83:ae:fd:15:
2e:50:c8:a7:16:6e:c9:4e:76:cc:fd:69:ae:4f:12:b8:e7:01:
b6:58:7e:39:d1:fa:8d:49:bd:ff:6b:a8:dd:ae:83:ed:bc:b2:
40:e3:a5:e0:fd:ae:3f:57:4d:ec:f3:21:34:b1:84:97:06:6f:
f4:7d:f4:1c:84:cc:bb:1c:1c:e7:7a:7d:2d:e9:49:60:93:12:
0d:9f:05:8c:8e:f9:cf:e8:9f:fc:15:c0:6e:e2:fe:e5:07:81:
82:fc
Here is the list of available SSLv2 ciphers:
RC4-MD5
EXP-RC4-MD5
RC2-CBC-MD5
EXP-RC2-CBC-MD5
DES-CBC-MD5
DES-CBC3-MD5
RC4-64-MD5
The SSLv2 server offers 5 strong ciphers, but also 0 medium strength and '''2 weak "export class" ciphers'''.
The weak/medium ciphers may be chosen by an export-grade or badly configured client software. They only offer a limited protection against a brute force attack
Solution: disable those ciphers and upgrade your client software if necessary.
See http://support.microsoft.com/default.aspx?scid=kben-us216482
or http://httpd.apache.org/docs-2.0/mod/mod_ssl.html#sslciphersuite
This SSLv2 server also accepts SSLv3 connections.
This SSLv2 server also accepts TLSv1 connections.

Vulnerable hosts
''(list of vulnerable hosts follows)''

'''Example 3'''. Manually audit weak SSL cipher levels with OpenSSL. The following will attempt to connect to Google.com with SSLv2.
<pre>
[root@test]# openssl s_client -no_tls1 -no_ssl3 -connect www.google.com:443
CONNECTED(00000003)
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDYzCCAsygAwIBAgIQYFbAC3yUC8RFj9MS7lfBkzANBgkqhkiG9w0BAQQFADCB
zjELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJ
Q2FwZSBUb3duMR0wGwYDVQQKExRUaGF3dGUgQ29uc3VsdGluZyBjYzEoMCYGA1UE
CxMfQ2VydGlmaWNhdGlvbiBTZXJ2aWNlcyBEaXZpc2lvbjEhMB8GA1UEAxMYVGhh
d3RlIFByZW1pdW0gU2VydmVyIENBMSgwJgYJKoZIhvcNAQkBFhlwcmVtaXVtLXNl
cnZlckB0aGF3dGUuY29tMB4XDTA2MDQyMTAxMDc0NVoXDTA3MDQyMTAxMDc0NVow
aDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDU1v
dW50YWluIFZpZXcxEzARBgNVBAoTCkdvb2dsZSBJbmMxFzAVBgNVBAMTDnd3dy5n
b29nbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/e2Vs8U33fRDk
5NNpNgkB1zKw4rqTozmfwty7eTEI8PVH1Bf6nthocQ9d9SgJAI2WOBP4grPj7MqO
dXMTFWGDfiTnwes16G7NZlyh6peT68r7ifrwSsVLisJp6pUf31M5Z3D88b+Yy4PE
D7BJaTxq6NNmP1vYUJeXsGSGrV6FUQIDAQABo4GmMIGjMB0GA1UdJQQWMBQGCCsG
AQUFBwMBBggrBgEFBQcDAjBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vY3JsLnRo
YXd0ZS5jb20vVGhhd3RlUHJlbWl1bVNlcnZlckNBLmNybDAyBggrBgEFBQcBAQQm
MCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0ZS5jb20wDAYDVR0TAQH/
BAIwADANBgkqhkiG9w0BAQQFAAOBgQADlTbBdVY6LD1nHWkhTadmzuWq2rWE0KO3
Ay+7EleYWPOo+EST315QLpU6pQgblgobGoI5x/fUg2U8WiYj1I1cbavhX2h1hda3
FJWnB3SiXaiuDTsGxQ267EwCVWD5bCrSWa64ilSJTgiUmzAv0a2W8YHXdG08+nYc
X/dVk5WRTw==
-----END CERTIFICATE-----
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
---
No client certificate CA names sent
---
Ciphers common between both SSL endpoints:
RC4-MD5 EXP-RC4-MD5 RC2-CBC-MD5
EXP-RC2-CBC-MD5 DES-CBC-MD5 DES-CBC3-MD5
RC4-64-MD5
---
SSL handshake has read 1023 bytes and written 333 bytes
---
New, SSLv2, Cipher is DES-CBC3-MD5
Server public key is 1024 bit
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : SSLv2
Cipher : DES-CBC3-MD5
Session-ID: 709F48E4D567C70A2E49886E4C697CDE
Session-ID-ctx:
Master-Key: 649E68F8CF936E69642286AC40A80F433602E3C36FD288C3
Key-Arg : E8CB6FEB9ECF3033
Start Time: 1156977226
Timeout : 300 (sec)
Verify return code: 21 (unable to verify the first certificate)
---
closed
</pre>

'''Example 4'''. Testing supported protocols and ciphers using SSLScan.

SSLScan is a free command line tool that scans a HTTPS service to enumerate what protocols (supports SSLv2, SSLv3 and TLS1) and what ciphers the HTTPS service supports. It runs both on Linux and Windows OS (OSX not tested) and is released under a open source license.

<pre>
[user@test]$ ./SSLScan --no-failed mail.google.com
_
___ ___| |___ ___ __ _ _ __
/ __/ __| / __|/ __/ _` | '_ \
\__ \__ \ \__ \ (_| (_| | | | |
|___/___/_|___/\___\__,_|_| |_|

Version 1.9.0-win
http://www.titania.co.uk
Copyright 2010 Ian Ventura-Whiting / Michael Boman
Compiled against OpenSSL 0.9.8n 24 Mar 2010

Testing SSL server mail.google.com on port 443

Supported Server Cipher(s):
accepted SSLv3 256 bits AES256-SHA
accepted SSLv3 128 bits AES128-SHA
accepted SSLv3 168 bits DES-CBC3-SHA
accepted SSLv3 128 bits RC4-SHA
accepted SSLv3 128 bits RC4-MD5
accepted TLSv1 256 bits AES256-SHA
accepted TLSv1 128 bits AES128-SHA
accepted TLSv1 168 bits DES-CBC3-SHA
accepted TLSv1 128 bits RC4-SHA
accepted TLSv1 128 bits RC4-MD5

Prefered Server Cipher(s):
SSLv3 128 bits RC4-SHA
TLSv1 128 bits RC4-SHA

SSL Certificate:
Version: 2
Serial Number: -4294967295
Signature Algorithm: sha1WithRSAEncryption
Issuer: /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
Not valid before: Dec 18 00:00:00 2009 GMT
Not valid after: Dec 18 23:59:59 2011 GMT
Subject: /C=US/ST=California/L=Mountain View/O=Google Inc/CN=mail.google.com
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:d9:27:c8:11:f2:7b:e4:45:c9:46:b6:63:75:83:
b1:77:7e:17:41:89:80:38:f1:45:27:a0:3c:d9:e8:
a8:00:4b:d9:07:d0:ba:de:ed:f4:2c:a6:ac:dc:27:
13:ec:0c:c1:a6:99:17:42:e6:8d:27:d2:81:14:b0:
4b:82:fa:b2:c5:d0:bb:20:59:62:28:a3:96:b5:61:
f6:76:c1:6d:46:d2:fd:ba:c6:0f:3d:d1:c9:77:9a:
58:33:f6:06:76:32:ad:51:5f:29:5f:6e:f8:12:8b:
ad:e6:c5:08:39:b3:43:43:a9:5b:91:1d:d7:e3:cf:
51:df:75:59:8e:8d:80:ab:53
Exponent: 65537 (0x10001)
X509v3 Extensions:
X509v3 Basic Constraints: critical
CA:FALSE X509v3 CRL Distribution Points:
URI:http://crl.thawte.com/ThawteSGCCA.crl
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication, Netscape Server Gated Crypto Authority Information Access:
OCSP - URI:http://ocsp.thawte.com
CA Issuers - URI:http://www.thawte.com/repository/Thawte_SGC_CA.crt
Verify Certificate:
unable to get local issuer certificate

Renegotiation requests supported
</pre>

'''Example 5'''. Testing common SSL flaws with ssl_tests

ssl_tests (http://www.pentesterscripting.com/discovery/ssl_tests) is a bash script that uses sslscan and openssl to check for various flaws - ssl version 2, weak ciphers, md5withRSAEncryption,SSLv3 Force Ciphering Bug/Renegotiation.

<pre>

[user@test]$ ./ssl_test.sh 192.168.1.3 443
+++++++++++++++++++++++++++++++++++++++++++++++++
SSL Tests - v2, weak ciphers, MD5, Renegotiation
by Aung Khant, http://yehg.net
+++++++++++++++++++++++++++++++++++++++++++++++++

[*] testing on 192.168.1.3:443 ..

[*] tesing for sslv2 ..
[*] sslscan 192.168.1.3:443 | grep Accepted SSLv2
Accepted SSLv2 168 bits DES-CBC3-MD5
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 128 bits RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv2 128 bits RC4-MD5

[*] testing for weak ciphers ...
[*] sslscan 192.168.1.3:443 | grep 40 bits | grep Accepted
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv3 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-RC2-CBC-MD5
Accepted SSLv3 40 bits EXP-RC4-MD5
Accepted TLSv1 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-RC2-CBC-MD5
Accepted TLSv1 40 bits EXP-RC4-MD5

[*] sslscan 192.168.1.3:443 | grep 56 bits | grep Accepted
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv3 56 bits EDH-RSA-DES-CBC-SHA
Accepted SSLv3 56 bits DES-CBC-SHA
Accepted TLSv1 56 bits EDH-RSA-DES-CBC-SHA
Accepted TLSv1 56 bits DES-CBC-SHA

[*] testing for MD5 certificate ..
[*] sslscan 192.168.1.3:443 | grep MD5WithRSAEncryption

[*] testing for SSLv3 Force Ciphering Bug/Renegotiation ..
[*] echo R | openssl s_client -connect 192.168.1.3:443 | grep DONE
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
RENEGOTIATING
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
DONE

[*] done

</pre>

==White Box Test and example==

Check the configuration of the web servers which provide https services. If the web application provides other SSL/TLS wrapped services, these should be checked as well.

'''Example:''' The following registry path in Microsoft Windows 2003 defines the ciphers available to the server:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\

==Testing SSL certificate validity – client and server==

When accessing a web application via the https protocol, a secure channel is established between the client (usually the browser) and the server. The identity of one (the server) or both parties (client and server) is then established by means of digital certificates. In order for the communication to be set up, a number of checks on the certificates must be passed. While discussing SSL and certificate based authentication is beyond the scope of this Guide, we will focus on the main criteria involved in ascertaining certificate validity: a) checking if the Certificate Authority (CA) is a known one (meaning one considered trusted), b) checking that the certificate is currently valid, and c) checking that the name of the site and the name reported in the certificate match.
Remember to upgrade your browser because CA certs expired too, in every release of the browser, CA Certs has been renewed. Moreover it's important to update the browser because more web sites require strong cipher more of 40 or 56 bit.

Let’s examine each check more in detail.

a) Each browser comes with a preloaded list of trusted CAs, against which the certificate signing CA is compared (this list can be customized and expanded at will). During the initial negotiations with an https server, if the server certificate relates to a CA unknown to the browser, a warning is usually raised. This happens most often because a web application relies on a certificate signed by a self-established CA. Whether this is to be considered a concern depends on several factors. For example, this may be fine for an Intranet environment (think of corporate web email being provided via https; here, obviously all users recognize the internal CA as a trusted CA). When a service is provided to the general public via the Internet, however (i.e. when it is important to positively verify the identity of the server we are talking to), it is usually imperative to rely on a trusted CA, one which is recognized by all the user base (and here we stop with our considerations; we won’t delve deeper in the implications of the trust model being used by digital certificates).

b) Certificates have an associated period of validity, therefore they may expire. Again, we are warned by the browser about this. A public service needs a temporally valid certificate; otherwise, it means we are talking with a server whose certificate was issued by someone we trust, but has expired without being renewed.

c) What if the name on the certificate and the name of the server do not match? If this happens, it might sound suspicious. For a number of reasons, this is not so rare to see. A system may host a number of name-based virtual hosts, which share the same IP address and are identified by means of the HTTP 1.1 Host: header information. In this case, since the SSL handshake checks the server certificate before the HTTP request is processed, it is not possible to assign different certificates to each virtual server. Therefore, if the name of the site and the name reported in the certificate do not match, we have a condition which is typically signalled by the browser. To avoid this, one of two techniques should be used. First is Server Name Indication (SNI), which is a TLS extension from [http://www.ietf.org/rfc/rfc3546.txt RFC 3546]; and second is IP-based virtual servers must be used. [2] and [3] describe techniques to deal with this problem and allow name-based virtual hosts to be correctly referenced.

===Black Box Testing and examples===

Examine the validity of the certificates used by the application. Browsers will issue a warning when encountering expired certificates, certificates issued by untrusted CAs, and certificates which do not match namewise with the site to which they should refer. By clicking on the padlock which appears in the browser window when visiting an https site, you can look at information related to the certificate – including the issuer, period of validity, encryption characteristics, etc.

If the application requires a client certificate, you probably have installed one to access it. Certificate information is available in the browser by inspecting the relevant certificate(s) in the list of the installed certificates.

These checks must be applied to all visible SSL-wrapped communication channels used by the application. Though this is the usual https service running on port 443, there may be additional services involved depending on the web application architecture and on deployment issues (an https administrative port left open, https services on non-standard ports, etc.). Therefore, apply these checks to all SSL-wrapped ports which have been discovered. For example, the nmap scanner features a scanning mode (enabled by the –sV command line switch) which identifies SSL-wrapped services. The Nessus vulnerability scanner has the capability of performing SSL checks on all SSL/TLS-wrapped services.

'''Examples'''

Rather than providing a fictitious example, we have inserted an anonymized real-life example to stress how frequently one stumbles on https sites whose certificates are inaccurate with respect to naming.

The following screenshots refer to a regional site of a high-profile IT company.

Warning issued by Microsoft Internet Explorer. We are visiting an ''.it'' site and the certificate was issued to a ''.com ''site! Internet Explorer warns that the name on the certificate does not match the name of the site.

[[Image:SSL Certificate Validity Testing IE Warning.gif]]

Warning issued by Mozilla Firefox. The message issued by Firefox is different – Firefox complains because it cannot ascertain the identity of the ''.com'' site the certificate refers to because it does not know the CA which signed the certificate. In fact, Internet Explorer and Firefox do not come preloaded with the same list of CAs. Therefore, the behavior experienced with various browsers may differ.

[[Image:SSL Certificate Validity Testing Firefox Warning.gif]]

===White Box Testing and examples===

Examine the validity of the certificates used by the application at both server and client levels. The usage of certificates is primarily at the web server level; however, there may be additional communication paths protected by SSL (for example, towards the DBMS). You should check the application architecture to identify all SSL protected channels.

==References==
'''Whitepapers''' 
* [1] RFC2246. The TLS Protocol Version 1.0 (updated by RFC3546) - http://www.ietf.org/rfc/rfc2246.txt
* [2] RFC2817. Upgrading to TLS Within HTTP/1.1 - http://www.ietf.org/rfc/rfc2817.txt
* [3] RFC3546. Transport Layer Security (TLS) Extensions - http://www.ietf.org/rfc/rfc3546.txt
* [4] www.verisign.net features various material on the topic

'''Tools'''

* https://www.ssllabs.com/ssldb/

* Vulnerability scanners may include checks regarding certificate validity, including name mismatch and time expiration. They usually report other information as well, such as the CA which issued the certificate. Remember that there is no unified notion of a “trusted CA”; what is trusted depends on the configuration of the software and on the human assumptions made beforehand. Browsers come with a preloaded list of trusted CAs. If your web application relies on a CA which is not in this list (for example, because you rely on a self-made CA), you should take into account the process of configuring user browsers to recognize the CA.

* The Nessus scanner includes a plugin to check for expired certificates or certificates which are going to expire within 60 days (plugin “SSL certificate expiry”, plugin id 15901). This plugin will check certificates ''installed on the server.

* Vulnerability scanners may include checks against weak ciphers. For example, the Nessus scanner (http://www.nessus.org) has this capability and flags the presence of SSL weak ciphers (see example provided above).

* You may also rely on specialized tools such as SSL Digger (http://www.mcafee.com/us/downloads/free-tools/ssldigger.aspx), or – for the command line oriented – experiment with the openssl tool, which provides access to OpenSSL cryptographic functions directly from a Unix shell (may be already available on *nix boxes, otherwise see www.openssl.org).

* To identify SSL-based services, use a vulnerability scanner or a port scanner with service recognition capabilities. The nmap scanner features a “-sV” scanning option which tries to identify services, while the nessus vulnerability scanner has the capability of identifying SSL-based services on arbitrary ports and to run vulnerability checks on them regardless of whether they are configured on standard or non-standard ports.

* In case you need to talk to a SSL service but your favourite tool doesn’t support SSL, you may benefit from a SSL proxy such as stunnel; stunnel will take care of tunneling the underlying protocol (usually http, but not necessarily so) and communicate with the SSL service you need to reach.

* ssl_tests, http://www.pentesterscripting.com/discovery/ssl_tests

* Finally, a word of advice. Though it may be tempting to use a regular browser to check certificates, there are various reasons for not doing so. Browsers have been plagued by various bugs in this area, and the way the browser will perform the check might be influenced by configuration settings that may not be evident. Instead, rely on vulnerability scanners or on specialized tools to do the job.

* [http://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet OWASP Transport Layer Protection Cheat Sheet]

[[Category:Cryptographic Vulnerability]]
[[Category:SSL]]

Testing for SSL-TLS (OWASP-CM-001)

2013-03-10T05:23:50Z

Jeffrey Walton: Title case for heading

{{Template:OWASP Testing Guide v3}}

== Brief Summary ==

Due to historic export restrictions of high grade cryptography, legacy and new web servers are often able and configured to handle weak cryptographic options.

Even if high grade ciphers are normally used and installed, some server misconfiguration could be used to force the use of a weaker cipher to gain access to the supposed secure communication channel.

==Testing SSL / TLS Cipher Specifications and Requirements ==

The http clear-text protocol is normally secured via an SSL or TLS tunnel, resulting in https traffic. In addition to providing encryption of data in transit, https allows the identification of servers (and, optionally, of clients) by means of digital certificates.

Historically, there have been limitations set in place by the U.S. government to allow cryptosystems to be exported only for key sizes of, at most, 40 bits, a key length which could be broken and would allow the decryption of communications. Since then, cryptographic export regulations have been relaxed (though some constraints still hold); however, it is important to check the SSL configuration being used to avoid putting in place cryptographic support which could be easily defeated. SSL-based services should not offer the possibility to choose weak ciphers.

Cipher determination is performed as follows: in the initial phase of a SSL connection setup, the client sends the server a Client Hello message specifying, among other information, the cipher suites that it is able to handle. A client is usually a web browser (most popular SSL client nowadays), but not necessarily, since it can be any SSL-enabled application; the same holds for the server, which needs not be a web server, though this is the most common case. (For example, a noteworthy class of SSL clients is that of SSL proxies such as stunnel (www.stunnel.org) which can be used to allow non-SSL enabled tools to talk to SSL services.) A cipher suite is specified by an encryption protocol (DES, RC4, AES), the encryption key length (such as 40, 56, or 128 bits), and a hash algorithm (SHA, MD5) used for integrity checking. Upon receiving a Client Hello message, the server decides which cipher suite it will use for that session. It is possible (for example, by means of configuration directives) to specify which cipher suites the server will honor. In this way you may control, for example, whether or not conversations with clients will support 40-bit encryption only.

==SSL testing criteria==
Large number of available cipher suites and quick progress in cryptoanalysis makes judging a SSL server a non-trivial task. These criteria are widely recognised as minimum checklist:

* SSLv2, due to known weaknesses in protocol design
* SSLv3, due to known weaknesses in protocol design
* Compression, due to known weaknesses in protocol design
* Cipher suites with symmetric encryption algorithm smaller than 112 bits
* X.509 certificates with RSA or DSA key smaller than 1024 bits
* X.509 certificates signed using MD5 hash, due to known collision attacks on this hash
* TLS Renegotiation vulnerability[http://www.phonefactor.com/sslgap/ssl-tls-authentication-patches]

The following standards can be used as reference while assessing SSL servers:

* [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf NIST SP 800-52] recommends U.S. federal systems to use at least TLS 1.0 with ciphersuites based on RSA or DSA key agreement with ephemeral Diffie-Hellman, 3DES or AES for confidentality and SHA1 for integrity protection. NIST SP 800-52 specifically disallows non-FIPS compliant algorithms like RC4 and MD5. An exception is U.S. federal systems making connections to outside servers, where these algorithms can be used in SSL client mode.
* [https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml PCI-DSS v1.2] in point 4.1 requires compliant parties to use "strong cryptography" without precisely defining key lengths and algorithms. Common interpretation, partially based on previous versions of the standard, is that at least 128 bit key cipher, no export strength algorithms and no SSLv2 should be used[http://www.digicert.com/news/DigiCert_PCI_White_Paper.pdf].
* [https://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide] has been proposed to standardize SSL server assessment and currently is in draft version.

SSL Server Database can be used to assess configuration of publicly available SSL servers[https://www.ssllabs.com/ssldb/analyze.html] based on SSL Rating Guide[https://www.ssllabs.com/projects/rating-guide/index.html]

==Black Box Test and example==

In order to detect possible support of weak ciphers, the ports associated to SSL/TLS wrapped services must be identified. These typically include port 443, which is the standard https port; however, this may change because a) https services may be configured to run on non-standard ports, and b) there may be additional SSL/TLS wrapped services related to the web application. In general, a service discovery is required to identify such ports.

The nmap scanner, via the “–sV” scan option, is able to identify SSL services. Vulnerability Scanners, in addition to performing service discovery, may include checks against weak ciphers (for example, the Nessus scanner has the capability of checking SSL services on arbitrary ports, and will report weak ciphers).

'''Example 1'''. SSL service recognition via nmap.

<pre>
[root@test]# nmap -F -sV localhost

Starting nmap 3.75 ( http://www.insecure.org/nmap/ ) at 2005-07-27 14:41 CEST
Interesting ports on localhost.localdomain (127.0.0.1):
(The 1205 ports scanned but not shown below are in state: closed)

PORT STATE SERVICE VERSION
443/tcp open ssl OpenSSL
901/tcp open http Samba SWAT administration server
8080/tcp open http Apache httpd 2.0.54 ((Unix) mod_ssl/2.0.54 OpenSSL/0.9.7g PHP/4.3.11)
8081/tcp open http Apache Tomcat/Coyote JSP engine 1.0

Nmap run completed -- 1 IP address (1 host up) scanned in 27.881 seconds
[root@test]#
</pre>

'''Example 2'''. Identifying weak ciphers with Nessus.
The following is an anonymized excerpt of a report generated by the Nessus scanner, corresponding to the identification of a server certificate allowing weak ciphers (see underlined text).

'''https (443/tcp)'''
'''Description'''
Here is the SSLv2 server certificate:
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: md5WithRSAEncryption
Issuer: C=**, ST=******, L=******, O=******, OU=******, CN=******
Validity
Not Before: Oct 17 07:12:16 2002 GMT
Not After : Oct 16 07:12:16 2004 GMT
Subject: C=**, ST=******, L=******, O=******, CN=******
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:98:4f:24:16:cb:0f:74:e8:9c:55:ce:62:14:4e:
6b:84:c5:81:43:59:c1:2e:ac:ba:af:92:51:f3:0b:
ad:e1:4b:22:ba:5a:9a:1e:0f:0b:fb:3d:5d:e6:fc:
ef:b8:8c:dc:78:28:97:8b:f0:1f:17:9f:69:3f:0e:
72:51:24:1b:9c:3d:85:52:1d:df:da:5a:b8:2e:d2:
09:00:76:24:43:bc:08:67:6b:dd:6b:e9:d2:f5:67:
e1:90:2a:b4:3b:b4:3c:b3:71:4e:88:08:74:b9:a8:
2d:c4:8c:65:93:08:e6:2f:fd:e0:fa:dc:6d:d7:a2:
3d:0a:75:26:cf:dc:47:74:29
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
Page 10
Network Vulnerability Assessment Report 25.05.2005
X509v3 Subject Key Identifier:
10:00:38:4C:45:F0:7C:E4:C6:A7:A4:E2:C9:F0:E4:2B:A8:F9:63:A8
X509v3 Authority Key Identifier:
keyid:CE:E5:F9:41:7B:D9:0E:5E:5D:DF:5E:B9:F3:E6:4A:12:19:02:76:CE
DirName:/C=**/ST=******/L=******/O=******/OU=******/CN=******
serial:00
Signature Algorithm: md5WithRSAEncryption
7b:14:bd:c7:3c:0c:01:8d:69:91:95:46:5c:e6:1e:25:9b:aa:
8b:f5:0d:de:e3:2e:82:1e:68:be:97:3b:39:4a:83:ae:fd:15:
2e:50:c8:a7:16:6e:c9:4e:76:cc:fd:69:ae:4f:12:b8:e7:01:
b6:58:7e:39:d1:fa:8d:49:bd:ff:6b:a8:dd:ae:83:ed:bc:b2:
40:e3:a5:e0:fd:ae:3f:57:4d:ec:f3:21:34:b1:84:97:06:6f:
f4:7d:f4:1c:84:cc:bb:1c:1c:e7:7a:7d:2d:e9:49:60:93:12:
0d:9f:05:8c:8e:f9:cf:e8:9f:fc:15:c0:6e:e2:fe:e5:07:81:
82:fc
Here is the list of available SSLv2 ciphers:
RC4-MD5
EXP-RC4-MD5
RC2-CBC-MD5
EXP-RC2-CBC-MD5
DES-CBC-MD5
DES-CBC3-MD5
RC4-64-MD5
The SSLv2 server offers 5 strong ciphers, but also 0 medium strength and '''2 weak "export class" ciphers'''.
The weak/medium ciphers may be chosen by an export-grade or badly configured client software. They only offer a limited protection against a brute force attack
Solution: disable those ciphers and upgrade your client software if necessary.
See http://support.microsoft.com/default.aspx?scid=kben-us216482
or http://httpd.apache.org/docs-2.0/mod/mod_ssl.html#sslciphersuite
This SSLv2 server also accepts SSLv3 connections.
This SSLv2 server also accepts TLSv1 connections.

Vulnerable hosts
''(list of vulnerable hosts follows)''

'''Example 3'''. Manually audit weak SSL cipher levels with OpenSSL. The following will attempt to connect to Google.com with SSLv2.
<pre>
[root@test]# openssl s_client -no_tls1 -no_ssl3 -connect www.google.com:443
CONNECTED(00000003)
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDYzCCAsygAwIBAgIQYFbAC3yUC8RFj9MS7lfBkzANBgkqhkiG9w0BAQQFADCB
zjELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJ
Q2FwZSBUb3duMR0wGwYDVQQKExRUaGF3dGUgQ29uc3VsdGluZyBjYzEoMCYGA1UE
CxMfQ2VydGlmaWNhdGlvbiBTZXJ2aWNlcyBEaXZpc2lvbjEhMB8GA1UEAxMYVGhh
d3RlIFByZW1pdW0gU2VydmVyIENBMSgwJgYJKoZIhvcNAQkBFhlwcmVtaXVtLXNl
cnZlckB0aGF3dGUuY29tMB4XDTA2MDQyMTAxMDc0NVoXDTA3MDQyMTAxMDc0NVow
aDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDU1v
dW50YWluIFZpZXcxEzARBgNVBAoTCkdvb2dsZSBJbmMxFzAVBgNVBAMTDnd3dy5n
b29nbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/e2Vs8U33fRDk
5NNpNgkB1zKw4rqTozmfwty7eTEI8PVH1Bf6nthocQ9d9SgJAI2WOBP4grPj7MqO
dXMTFWGDfiTnwes16G7NZlyh6peT68r7ifrwSsVLisJp6pUf31M5Z3D88b+Yy4PE
D7BJaTxq6NNmP1vYUJeXsGSGrV6FUQIDAQABo4GmMIGjMB0GA1UdJQQWMBQGCCsG
AQUFBwMBBggrBgEFBQcDAjBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vY3JsLnRo
YXd0ZS5jb20vVGhhd3RlUHJlbWl1bVNlcnZlckNBLmNybDAyBggrBgEFBQcBAQQm
MCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0ZS5jb20wDAYDVR0TAQH/
BAIwADANBgkqhkiG9w0BAQQFAAOBgQADlTbBdVY6LD1nHWkhTadmzuWq2rWE0KO3
Ay+7EleYWPOo+EST315QLpU6pQgblgobGoI5x/fUg2U8WiYj1I1cbavhX2h1hda3
FJWnB3SiXaiuDTsGxQ267EwCVWD5bCrSWa64ilSJTgiUmzAv0a2W8YHXdG08+nYc
X/dVk5WRTw==
-----END CERTIFICATE-----
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
---
No client certificate CA names sent
---
Ciphers common between both SSL endpoints:
RC4-MD5 EXP-RC4-MD5 RC2-CBC-MD5
EXP-RC2-CBC-MD5 DES-CBC-MD5 DES-CBC3-MD5
RC4-64-MD5
---
SSL handshake has read 1023 bytes and written 333 bytes
---
New, SSLv2, Cipher is DES-CBC3-MD5
Server public key is 1024 bit
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : SSLv2
Cipher : DES-CBC3-MD5
Session-ID: 709F48E4D567C70A2E49886E4C697CDE
Session-ID-ctx:
Master-Key: 649E68F8CF936E69642286AC40A80F433602E3C36FD288C3
Key-Arg : E8CB6FEB9ECF3033
Start Time: 1156977226
Timeout : 300 (sec)
Verify return code: 21 (unable to verify the first certificate)
---
closed
</pre>

'''Example 4'''. Testing supported protocols and ciphers using SSLScan.

SSLScan is a free command line tool that scans a HTTPS service to enumerate what protocols (supports SSLv2, SSLv3 and TLS1) and what ciphers the HTTPS service supports. It runs both on Linux and Windows OS (OSX not tested) and is released under a open source license.

<pre>
[user@test]$ ./SSLScan --no-failed mail.google.com
_
___ ___| |___ ___ __ _ _ __
/ __/ __| / __|/ __/ _` | '_ \
\__ \__ \ \__ \ (_| (_| | | | |
|___/___/_|___/\___\__,_|_| |_|

Version 1.9.0-win
http://www.titania.co.uk
Copyright 2010 Ian Ventura-Whiting / Michael Boman
Compiled against OpenSSL 0.9.8n 24 Mar 2010

Testing SSL server mail.google.com on port 443

Supported Server Cipher(s):
accepted SSLv3 256 bits AES256-SHA
accepted SSLv3 128 bits AES128-SHA
accepted SSLv3 168 bits DES-CBC3-SHA
accepted SSLv3 128 bits RC4-SHA
accepted SSLv3 128 bits RC4-MD5
accepted TLSv1 256 bits AES256-SHA
accepted TLSv1 128 bits AES128-SHA
accepted TLSv1 168 bits DES-CBC3-SHA
accepted TLSv1 128 bits RC4-SHA
accepted TLSv1 128 bits RC4-MD5

Prefered Server Cipher(s):
SSLv3 128 bits RC4-SHA
TLSv1 128 bits RC4-SHA

SSL Certificate:
Version: 2
Serial Number: -4294967295
Signature Algorithm: sha1WithRSAEncryption
Issuer: /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
Not valid before: Dec 18 00:00:00 2009 GMT
Not valid after: Dec 18 23:59:59 2011 GMT
Subject: /C=US/ST=California/L=Mountain View/O=Google Inc/CN=mail.google.com
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:d9:27:c8:11:f2:7b:e4:45:c9:46:b6:63:75:83:
b1:77:7e:17:41:89:80:38:f1:45:27:a0:3c:d9:e8:
a8:00:4b:d9:07:d0:ba:de:ed:f4:2c:a6:ac:dc:27:
13:ec:0c:c1:a6:99:17:42:e6:8d:27:d2:81:14:b0:
4b:82:fa:b2:c5:d0:bb:20:59:62:28:a3:96:b5:61:
f6:76:c1:6d:46:d2:fd:ba:c6:0f:3d:d1:c9:77:9a:
58:33:f6:06:76:32:ad:51:5f:29:5f:6e:f8:12:8b:
ad:e6:c5:08:39:b3:43:43:a9:5b:91:1d:d7:e3:cf:
51:df:75:59:8e:8d:80:ab:53
Exponent: 65537 (0x10001)
X509v3 Extensions:
X509v3 Basic Constraints: critical
CA:FALSE X509v3 CRL Distribution Points:
URI:http://crl.thawte.com/ThawteSGCCA.crl
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication, Netscape Server Gated Crypto Authority Information Access:
OCSP - URI:http://ocsp.thawte.com
CA Issuers - URI:http://www.thawte.com/repository/Thawte_SGC_CA.crt
Verify Certificate:
unable to get local issuer certificate

Renegotiation requests supported
</pre>

'''Example 5'''. Testing common SSL flaws with ssl_tests

ssl_tests (http://www.pentesterscripting.com/discovery/ssl_tests) is a bash script that uses sslscan and openssl to check for various flaws - ssl version 2, weak ciphers, md5withRSAEncryption,SSLv3 Force Ciphering Bug/Renegotiation.

<pre>

[user@test]$ ./ssl_test.sh 192.168.1.3 443
+++++++++++++++++++++++++++++++++++++++++++++++++
SSL Tests - v2, weak ciphers, MD5, Renegotiation
by Aung Khant, http://yehg.net
+++++++++++++++++++++++++++++++++++++++++++++++++

[*] testing on 192.168.1.3:443 ..

[*] tesing for sslv2 ..
[*] sslscan 192.168.1.3:443 | grep Accepted SSLv2
Accepted SSLv2 168 bits DES-CBC3-MD5
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 128 bits RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv2 128 bits RC4-MD5

[*] testing for weak ciphers ...
[*] sslscan 192.168.1.3:443 | grep 40 bits | grep Accepted
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv3 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-RC2-CBC-MD5
Accepted SSLv3 40 bits EXP-RC4-MD5
Accepted TLSv1 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-RC2-CBC-MD5
Accepted TLSv1 40 bits EXP-RC4-MD5

[*] sslscan 192.168.1.3:443 | grep 56 bits | grep Accepted
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv3 56 bits EDH-RSA-DES-CBC-SHA
Accepted SSLv3 56 bits DES-CBC-SHA
Accepted TLSv1 56 bits EDH-RSA-DES-CBC-SHA
Accepted TLSv1 56 bits DES-CBC-SHA

[*] testing for MD5 certificate ..
[*] sslscan 192.168.1.3:443 | grep MD5WithRSAEncryption

[*] testing for SSLv3 Force Ciphering Bug/Renegotiation ..
[*] echo R | openssl s_client -connect 192.168.1.3:443 | grep DONE
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
RENEGOTIATING
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
DONE

[*] done

</pre>

==White Box Test and example==

Check the configuration of the web servers which provide https services. If the web application provides other SSL/TLS wrapped services, these should be checked as well.

'''Example:''' The following registry path in Microsoft Windows 2003 defines the ciphers available to the server:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\

==Testing SSL certificate validity – client and server==

When accessing a web application via the https protocol, a secure channel is established between the client (usually the browser) and the server. The identity of one (the server) or both parties (client and server) is then established by means of digital certificates. In order for the communication to be set up, a number of checks on the certificates must be passed. While discussing SSL and certificate based authentication is beyond the scope of this Guide, we will focus on the main criteria involved in ascertaining certificate validity: a) checking if the Certificate Authority (CA) is a known one (meaning one considered trusted), b) checking that the certificate is currently valid, and c) checking that the name of the site and the name reported in the certificate match.
Remember to upgrade your browser because CA certs expired too, in every release of the browser, CA Certs has been renewed. Moreover it's important to update the browser because more web sites require strong cipher more of 40 or 56 bit.

Let’s examine each check more in detail.

a) Each browser comes with a preloaded list of trusted CAs, against which the certificate signing CA is compared (this list can be customized and expanded at will). During the initial negotiations with an https server, if the server certificate relates to a CA unknown to the browser, a warning is usually raised. This happens most often because a web application relies on a certificate signed by a self-established CA. Whether this is to be considered a concern depends on several factors. For example, this may be fine for an Intranet environment (think of corporate web email being provided via https; here, obviously all users recognize the internal CA as a trusted CA). When a service is provided to the general public via the Internet, however (i.e. when it is important to positively verify the identity of the server we are talking to), it is usually imperative to rely on a trusted CA, one which is recognized by all the user base (and here we stop with our considerations; we won’t delve deeper in the implications of the trust model being used by digital certificates).

b) Certificates have an associated period of validity, therefore they may expire. Again, we are warned by the browser about this. A public service needs a temporally valid certificate; otherwise, it means we are talking with a server whose certificate was issued by someone we trust, but has expired without being renewed.

c) What if the name on the certificate and the name of the server do not match? If this happens, it might sound suspicious. For a number of reasons, this is not so rare to see. A system may host a number of name-based virtual hosts, which share the same IP address and are identified by means of the HTTP 1.1 Host: header information. In this case, since the SSL handshake checks the server certificate before the HTTP request is processed, it is not possible to assign different certificates to each virtual server. Therefore, if the name of the site and the name reported in the certificate do not match, we have a condition which is typically signalled by the browser. To avoid this, one of two techniques should be used. First is Server Name Indication (SNI), which is a TLS extension from [http://www.ietf.org/rfc/rfc3546.txt RFC 3546]; and second is IP-based virtual servers must be used. [2] and [3] describe techniques to deal with this problem and allow name-based virtual hosts to be correctly referenced.

===Black Box Testing and examples===

Examine the validity of the certificates used by the application. Browsers will issue a warning when encountering expired certificates, certificates issued by untrusted CAs, and certificates which do not match namewise with the site to which they should refer. By clicking on the padlock which appears in the browser window when visiting an https site, you can look at information related to the certificate – including the issuer, period of validity, encryption characteristics, etc.

If the application requires a client certificate, you probably have installed one to access it. Certificate information is available in the browser by inspecting the relevant certificate(s) in the list of the installed certificates.

These checks must be applied to all visible SSL-wrapped communication channels used by the application. Though this is the usual https service running on port 443, there may be additional services involved depending on the web application architecture and on deployment issues (an https administrative port left open, https services on non-standard ports, etc.). Therefore, apply these checks to all SSL-wrapped ports which have been discovered. For example, the nmap scanner features a scanning mode (enabled by the –sV command line switch) which identifies SSL-wrapped services. The Nessus vulnerability scanner has the capability of performing SSL checks on all SSL/TLS-wrapped services.

'''Examples'''

Rather than providing a fictitious example, we have inserted an anonymized real-life example to stress how frequently one stumbles on https sites whose certificates are inaccurate with respect to naming.

The following screenshots refer to a regional site of a high-profile IT company.

Warning issued by Microsoft Internet Explorer. We are visiting an ''.it'' site and the certificate was issued to a ''.com ''site! Internet Explorer warns that the name on the certificate does not match the name of the site.

[[Image:SSL Certificate Validity Testing IE Warning.gif]]

Warning issued by Mozilla Firefox. The message issued by Firefox is different – Firefox complains because it cannot ascertain the identity of the ''.com'' site the certificate refers to because it does not know the CA which signed the certificate. In fact, Internet Explorer and Firefox do not come preloaded with the same list of CAs. Therefore, the behavior experienced with various browsers may differ.

[[Image:SSL Certificate Validity Testing Firefox Warning.gif]]

===White Box Testing and examples===

Examine the validity of the certificates used by the application at both server and client levels. The usage of certificates is primarily at the web server level; however, there may be additional communication paths protected by SSL (for example, towards the DBMS). You should check the application architecture to identify all SSL protected channels.

==References==
'''Whitepapers''' 
* [1] RFC2246. The TLS Protocol Version 1.0 (updated by RFC3546) - http://www.ietf.org/rfc/rfc2246.txt
* [2] RFC2817. Upgrading to TLS Within HTTP/1.1 - http://www.ietf.org/rfc/rfc2817.txt
* [3] RFC3546. Transport Layer Security (TLS) Extensions - http://www.ietf.org/rfc/rfc3546.txt
* [4] www.verisign.net features various material on the topic

'''Tools'''

* https://www.ssllabs.com/ssldb/

* Vulnerability scanners may include checks regarding certificate validity, including name mismatch and time expiration. They usually report other information as well, such as the CA which issued the certificate. Remember that there is no unified notion of a “trusted CA”; what is trusted depends on the configuration of the software and on the human assumptions made beforehand. Browsers come with a preloaded list of trusted CAs. If your web application relies on a CA which is not in this list (for example, because you rely on a self-made CA), you should take into account the process of configuring user browsers to recognize the CA.

* The Nessus scanner includes a plugin to check for expired certificates or certificates which are going to expire within 60 days (plugin “SSL certificate expiry”, plugin id 15901). This plugin will check certificates ''installed on the server.

* Vulnerability scanners may include checks against weak ciphers. For example, the Nessus scanner (http://www.nessus.org) has this capability and flags the presence of SSL weak ciphers (see example provided above).

* You may also rely on specialized tools such as SSL Digger (http://www.mcafee.com/us/downloads/free-tools/ssldigger.aspx), or – for the command line oriented – experiment with the openssl tool, which provides access to OpenSSL cryptographic functions directly from a Unix shell (may be already available on *nix boxes, otherwise see www.openssl.org).

* To identify SSL-based services, use a vulnerability scanner or a port scanner with service recognition capabilities. The nmap scanner features a “-sV” scanning option which tries to identify services, while the nessus vulnerability scanner has the capability of identifying SSL-based services on arbitrary ports and to run vulnerability checks on them regardless of whether they are configured on standard or non-standard ports.

* In case you need to talk to a SSL service but your favourite tool doesn’t support SSL, you may benefit from a SSL proxy such as stunnel; stunnel will take care of tunneling the underlying protocol (usually http, but not necessarily so) and communicate with the SSL service you need to reach.

* ssl_tests, http://www.pentesterscripting.com/discovery/ssl_tests

* Finally, a word of advice. Though it may be tempting to use a regular browser to check certificates, there are various reasons for not doing so. Browsers have been plagued by various bugs in this area, and the way the browser will perform the check might be influenced by configuration settings that may not be evident. Instead, rely on vulnerability scanners or on specialized tools to do the job.

* [http://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet OWASP Transport Layer Protection Cheat Sheet]

[[Category:Cryptographic Vulnerability]]
[[Category:SSL]]

Testing for SSL-TLS (OWASP-CM-001)

2013-03-10T05:23:09Z

Jeffrey Walton: Testing criteria: removed paragraph on why its OK to use MD5 (no longer relevant/true)

{{Template:OWASP Testing Guide v3}}

== Brief Summary ==

Due to historic export restrictions of high grade cryptography, legacy and new web servers are often able and configured to handle weak cryptographic options.

Even if high grade ciphers are normally used and installed, some server misconfiguration could be used to force the use of a weaker cipher to gain access to the supposed secure communication channel.

==Testing SSL / TLS cipher specifications and requirements for site==

The http clear-text protocol is normally secured via an SSL or TLS tunnel, resulting in https traffic. In addition to providing encryption of data in transit, https allows the identification of servers (and, optionally, of clients) by means of digital certificates.

Historically, there have been limitations set in place by the U.S. government to allow cryptosystems to be exported only for key sizes of, at most, 40 bits, a key length which could be broken and would allow the decryption of communications. Since then, cryptographic export regulations have been relaxed (though some constraints still hold); however, it is important to check the SSL configuration being used to avoid putting in place cryptographic support which could be easily defeated. SSL-based services should not offer the possibility to choose weak ciphers.

Cipher determination is performed as follows: in the initial phase of a SSL connection setup, the client sends the server a Client Hello message specifying, among other information, the cipher suites that it is able to handle. A client is usually a web browser (most popular SSL client nowadays), but not necessarily, since it can be any SSL-enabled application; the same holds for the server, which needs not be a web server, though this is the most common case. (For example, a noteworthy class of SSL clients is that of SSL proxies such as stunnel (www.stunnel.org) which can be used to allow non-SSL enabled tools to talk to SSL services.) A cipher suite is specified by an encryption protocol (DES, RC4, AES), the encryption key length (such as 40, 56, or 128 bits), and a hash algorithm (SHA, MD5) used for integrity checking. Upon receiving a Client Hello message, the server decides which cipher suite it will use for that session. It is possible (for example, by means of configuration directives) to specify which cipher suites the server will honor. In this way you may control, for example, whether or not conversations with clients will support 40-bit encryption only.

==SSL testing criteria==
Large number of available cipher suites and quick progress in cryptoanalysis makes judging a SSL server a non-trivial task. These criteria are widely recognised as minimum checklist:

* SSLv2, due to known weaknesses in protocol design
* SSLv3, due to known weaknesses in protocol design
* Compression, due to known weaknesses in protocol design
* Cipher suites with symmetric encryption algorithm smaller than 112 bits
* X.509 certificates with RSA or DSA key smaller than 1024 bits
* X.509 certificates signed using MD5 hash, due to known collision attacks on this hash
* TLS Renegotiation vulnerability[http://www.phonefactor.com/sslgap/ssl-tls-authentication-patches]

The following standards can be used as reference while assessing SSL servers:

* [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf NIST SP 800-52] recommends U.S. federal systems to use at least TLS 1.0 with ciphersuites based on RSA or DSA key agreement with ephemeral Diffie-Hellman, 3DES or AES for confidentality and SHA1 for integrity protection. NIST SP 800-52 specifically disallows non-FIPS compliant algorithms like RC4 and MD5. An exception is U.S. federal systems making connections to outside servers, where these algorithms can be used in SSL client mode.
* [https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml PCI-DSS v1.2] in point 4.1 requires compliant parties to use "strong cryptography" without precisely defining key lengths and algorithms. Common interpretation, partially based on previous versions of the standard, is that at least 128 bit key cipher, no export strength algorithms and no SSLv2 should be used[http://www.digicert.com/news/DigiCert_PCI_White_Paper.pdf].
* [https://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide] has been proposed to standardize SSL server assessment and currently is in draft version.

SSL Server Database can be used to assess configuration of publicly available SSL servers[https://www.ssllabs.com/ssldb/analyze.html] based on SSL Rating Guide[https://www.ssllabs.com/projects/rating-guide/index.html]

==Black Box Test and example==

In order to detect possible support of weak ciphers, the ports associated to SSL/TLS wrapped services must be identified. These typically include port 443, which is the standard https port; however, this may change because a) https services may be configured to run on non-standard ports, and b) there may be additional SSL/TLS wrapped services related to the web application. In general, a service discovery is required to identify such ports.

The nmap scanner, via the “–sV” scan option, is able to identify SSL services. Vulnerability Scanners, in addition to performing service discovery, may include checks against weak ciphers (for example, the Nessus scanner has the capability of checking SSL services on arbitrary ports, and will report weak ciphers).

'''Example 1'''. SSL service recognition via nmap.

<pre>
[root@test]# nmap -F -sV localhost

Starting nmap 3.75 ( http://www.insecure.org/nmap/ ) at 2005-07-27 14:41 CEST
Interesting ports on localhost.localdomain (127.0.0.1):
(The 1205 ports scanned but not shown below are in state: closed)

PORT STATE SERVICE VERSION
443/tcp open ssl OpenSSL
901/tcp open http Samba SWAT administration server
8080/tcp open http Apache httpd 2.0.54 ((Unix) mod_ssl/2.0.54 OpenSSL/0.9.7g PHP/4.3.11)
8081/tcp open http Apache Tomcat/Coyote JSP engine 1.0

Nmap run completed -- 1 IP address (1 host up) scanned in 27.881 seconds
[root@test]#
</pre>

'''Example 2'''. Identifying weak ciphers with Nessus.
The following is an anonymized excerpt of a report generated by the Nessus scanner, corresponding to the identification of a server certificate allowing weak ciphers (see underlined text).

'''https (443/tcp)'''
'''Description'''
Here is the SSLv2 server certificate:
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: md5WithRSAEncryption
Issuer: C=**, ST=******, L=******, O=******, OU=******, CN=******
Validity
Not Before: Oct 17 07:12:16 2002 GMT
Not After : Oct 16 07:12:16 2004 GMT
Subject: C=**, ST=******, L=******, O=******, CN=******
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:98:4f:24:16:cb:0f:74:e8:9c:55:ce:62:14:4e:
6b:84:c5:81:43:59:c1:2e:ac:ba:af:92:51:f3:0b:
ad:e1:4b:22:ba:5a:9a:1e:0f:0b:fb:3d:5d:e6:fc:
ef:b8:8c:dc:78:28:97:8b:f0:1f:17:9f:69:3f:0e:
72:51:24:1b:9c:3d:85:52:1d:df:da:5a:b8:2e:d2:
09:00:76:24:43:bc:08:67:6b:dd:6b:e9:d2:f5:67:
e1:90:2a:b4:3b:b4:3c:b3:71:4e:88:08:74:b9:a8:
2d:c4:8c:65:93:08:e6:2f:fd:e0:fa:dc:6d:d7:a2:
3d:0a:75:26:cf:dc:47:74:29
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
Page 10
Network Vulnerability Assessment Report 25.05.2005
X509v3 Subject Key Identifier:
10:00:38:4C:45:F0:7C:E4:C6:A7:A4:E2:C9:F0:E4:2B:A8:F9:63:A8
X509v3 Authority Key Identifier:
keyid:CE:E5:F9:41:7B:D9:0E:5E:5D:DF:5E:B9:F3:E6:4A:12:19:02:76:CE
DirName:/C=**/ST=******/L=******/O=******/OU=******/CN=******
serial:00
Signature Algorithm: md5WithRSAEncryption
7b:14:bd:c7:3c:0c:01:8d:69:91:95:46:5c:e6:1e:25:9b:aa:
8b:f5:0d:de:e3:2e:82:1e:68:be:97:3b:39:4a:83:ae:fd:15:
2e:50:c8:a7:16:6e:c9:4e:76:cc:fd:69:ae:4f:12:b8:e7:01:
b6:58:7e:39:d1:fa:8d:49:bd:ff:6b:a8:dd:ae:83:ed:bc:b2:
40:e3:a5:e0:fd:ae:3f:57:4d:ec:f3:21:34:b1:84:97:06:6f:
f4:7d:f4:1c:84:cc:bb:1c:1c:e7:7a:7d:2d:e9:49:60:93:12:
0d:9f:05:8c:8e:f9:cf:e8:9f:fc:15:c0:6e:e2:fe:e5:07:81:
82:fc
Here is the list of available SSLv2 ciphers:
RC4-MD5
EXP-RC4-MD5
RC2-CBC-MD5
EXP-RC2-CBC-MD5
DES-CBC-MD5
DES-CBC3-MD5
RC4-64-MD5
The SSLv2 server offers 5 strong ciphers, but also 0 medium strength and '''2 weak "export class" ciphers'''.
The weak/medium ciphers may be chosen by an export-grade or badly configured client software. They only offer a limited protection against a brute force attack
Solution: disable those ciphers and upgrade your client software if necessary.
See http://support.microsoft.com/default.aspx?scid=kben-us216482
or http://httpd.apache.org/docs-2.0/mod/mod_ssl.html#sslciphersuite
This SSLv2 server also accepts SSLv3 connections.
This SSLv2 server also accepts TLSv1 connections.

Vulnerable hosts
''(list of vulnerable hosts follows)''

'''Example 3'''. Manually audit weak SSL cipher levels with OpenSSL. The following will attempt to connect to Google.com with SSLv2.
<pre>
[root@test]# openssl s_client -no_tls1 -no_ssl3 -connect www.google.com:443
CONNECTED(00000003)
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDYzCCAsygAwIBAgIQYFbAC3yUC8RFj9MS7lfBkzANBgkqhkiG9w0BAQQFADCB
zjELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJ
Q2FwZSBUb3duMR0wGwYDVQQKExRUaGF3dGUgQ29uc3VsdGluZyBjYzEoMCYGA1UE
CxMfQ2VydGlmaWNhdGlvbiBTZXJ2aWNlcyBEaXZpc2lvbjEhMB8GA1UEAxMYVGhh
d3RlIFByZW1pdW0gU2VydmVyIENBMSgwJgYJKoZIhvcNAQkBFhlwcmVtaXVtLXNl
cnZlckB0aGF3dGUuY29tMB4XDTA2MDQyMTAxMDc0NVoXDTA3MDQyMTAxMDc0NVow
aDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDU1v
dW50YWluIFZpZXcxEzARBgNVBAoTCkdvb2dsZSBJbmMxFzAVBgNVBAMTDnd3dy5n
b29nbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/e2Vs8U33fRDk
5NNpNgkB1zKw4rqTozmfwty7eTEI8PVH1Bf6nthocQ9d9SgJAI2WOBP4grPj7MqO
dXMTFWGDfiTnwes16G7NZlyh6peT68r7ifrwSsVLisJp6pUf31M5Z3D88b+Yy4PE
D7BJaTxq6NNmP1vYUJeXsGSGrV6FUQIDAQABo4GmMIGjMB0GA1UdJQQWMBQGCCsG
AQUFBwMBBggrBgEFBQcDAjBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vY3JsLnRo
YXd0ZS5jb20vVGhhd3RlUHJlbWl1bVNlcnZlckNBLmNybDAyBggrBgEFBQcBAQQm
MCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0ZS5jb20wDAYDVR0TAQH/
BAIwADANBgkqhkiG9w0BAQQFAAOBgQADlTbBdVY6LD1nHWkhTadmzuWq2rWE0KO3
Ay+7EleYWPOo+EST315QLpU6pQgblgobGoI5x/fUg2U8WiYj1I1cbavhX2h1hda3
FJWnB3SiXaiuDTsGxQ267EwCVWD5bCrSWa64ilSJTgiUmzAv0a2W8YHXdG08+nYc
X/dVk5WRTw==
-----END CERTIFICATE-----
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
---
No client certificate CA names sent
---
Ciphers common between both SSL endpoints:
RC4-MD5 EXP-RC4-MD5 RC2-CBC-MD5
EXP-RC2-CBC-MD5 DES-CBC-MD5 DES-CBC3-MD5
RC4-64-MD5
---
SSL handshake has read 1023 bytes and written 333 bytes
---
New, SSLv2, Cipher is DES-CBC3-MD5
Server public key is 1024 bit
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : SSLv2
Cipher : DES-CBC3-MD5
Session-ID: 709F48E4D567C70A2E49886E4C697CDE
Session-ID-ctx:
Master-Key: 649E68F8CF936E69642286AC40A80F433602E3C36FD288C3
Key-Arg : E8CB6FEB9ECF3033
Start Time: 1156977226
Timeout : 300 (sec)
Verify return code: 21 (unable to verify the first certificate)
---
closed
</pre>

'''Example 4'''. Testing supported protocols and ciphers using SSLScan.

SSLScan is a free command line tool that scans a HTTPS service to enumerate what protocols (supports SSLv2, SSLv3 and TLS1) and what ciphers the HTTPS service supports. It runs both on Linux and Windows OS (OSX not tested) and is released under a open source license.

<pre>
[user@test]$ ./SSLScan --no-failed mail.google.com
_
___ ___| |___ ___ __ _ _ __
/ __/ __| / __|/ __/ _` | '_ \
\__ \__ \ \__ \ (_| (_| | | | |
|___/___/_|___/\___\__,_|_| |_|

Version 1.9.0-win
http://www.titania.co.uk
Copyright 2010 Ian Ventura-Whiting / Michael Boman
Compiled against OpenSSL 0.9.8n 24 Mar 2010

Testing SSL server mail.google.com on port 443

Supported Server Cipher(s):
accepted SSLv3 256 bits AES256-SHA
accepted SSLv3 128 bits AES128-SHA
accepted SSLv3 168 bits DES-CBC3-SHA
accepted SSLv3 128 bits RC4-SHA
accepted SSLv3 128 bits RC4-MD5
accepted TLSv1 256 bits AES256-SHA
accepted TLSv1 128 bits AES128-SHA
accepted TLSv1 168 bits DES-CBC3-SHA
accepted TLSv1 128 bits RC4-SHA
accepted TLSv1 128 bits RC4-MD5

Prefered Server Cipher(s):
SSLv3 128 bits RC4-SHA
TLSv1 128 bits RC4-SHA

SSL Certificate:
Version: 2
Serial Number: -4294967295
Signature Algorithm: sha1WithRSAEncryption
Issuer: /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
Not valid before: Dec 18 00:00:00 2009 GMT
Not valid after: Dec 18 23:59:59 2011 GMT
Subject: /C=US/ST=California/L=Mountain View/O=Google Inc/CN=mail.google.com
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:d9:27:c8:11:f2:7b:e4:45:c9:46:b6:63:75:83:
b1:77:7e:17:41:89:80:38:f1:45:27:a0:3c:d9:e8:
a8:00:4b:d9:07:d0:ba:de:ed:f4:2c:a6:ac:dc:27:
13:ec:0c:c1:a6:99:17:42:e6:8d:27:d2:81:14:b0:
4b:82:fa:b2:c5:d0:bb:20:59:62:28:a3:96:b5:61:
f6:76:c1:6d:46:d2:fd:ba:c6:0f:3d:d1:c9:77:9a:
58:33:f6:06:76:32:ad:51:5f:29:5f:6e:f8:12:8b:
ad:e6:c5:08:39:b3:43:43:a9:5b:91:1d:d7:e3:cf:
51:df:75:59:8e:8d:80:ab:53
Exponent: 65537 (0x10001)
X509v3 Extensions:
X509v3 Basic Constraints: critical
CA:FALSE X509v3 CRL Distribution Points:
URI:http://crl.thawte.com/ThawteSGCCA.crl
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication, Netscape Server Gated Crypto Authority Information Access:
OCSP - URI:http://ocsp.thawte.com
CA Issuers - URI:http://www.thawte.com/repository/Thawte_SGC_CA.crt
Verify Certificate:
unable to get local issuer certificate

Renegotiation requests supported
</pre>

'''Example 5'''. Testing common SSL flaws with ssl_tests

ssl_tests (http://www.pentesterscripting.com/discovery/ssl_tests) is a bash script that uses sslscan and openssl to check for various flaws - ssl version 2, weak ciphers, md5withRSAEncryption,SSLv3 Force Ciphering Bug/Renegotiation.

<pre>

[user@test]$ ./ssl_test.sh 192.168.1.3 443
+++++++++++++++++++++++++++++++++++++++++++++++++
SSL Tests - v2, weak ciphers, MD5, Renegotiation
by Aung Khant, http://yehg.net
+++++++++++++++++++++++++++++++++++++++++++++++++

[*] testing on 192.168.1.3:443 ..

[*] tesing for sslv2 ..
[*] sslscan 192.168.1.3:443 | grep Accepted SSLv2
Accepted SSLv2 168 bits DES-CBC3-MD5
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 128 bits RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv2 128 bits RC4-MD5

[*] testing for weak ciphers ...
[*] sslscan 192.168.1.3:443 | grep 40 bits | grep Accepted
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv3 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-RC2-CBC-MD5
Accepted SSLv3 40 bits EXP-RC4-MD5
Accepted TLSv1 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-RC2-CBC-MD5
Accepted TLSv1 40 bits EXP-RC4-MD5

[*] sslscan 192.168.1.3:443 | grep 56 bits | grep Accepted
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv3 56 bits EDH-RSA-DES-CBC-SHA
Accepted SSLv3 56 bits DES-CBC-SHA
Accepted TLSv1 56 bits EDH-RSA-DES-CBC-SHA
Accepted TLSv1 56 bits DES-CBC-SHA

[*] testing for MD5 certificate ..
[*] sslscan 192.168.1.3:443 | grep MD5WithRSAEncryption

[*] testing for SSLv3 Force Ciphering Bug/Renegotiation ..
[*] echo R | openssl s_client -connect 192.168.1.3:443 | grep DONE
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
RENEGOTIATING
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
DONE

[*] done

</pre>

==White Box Test and example==

Check the configuration of the web servers which provide https services. If the web application provides other SSL/TLS wrapped services, these should be checked as well.

'''Example:''' The following registry path in Microsoft Windows 2003 defines the ciphers available to the server:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\

==Testing SSL certificate validity – client and server==

When accessing a web application via the https protocol, a secure channel is established between the client (usually the browser) and the server. The identity of one (the server) or both parties (client and server) is then established by means of digital certificates. In order for the communication to be set up, a number of checks on the certificates must be passed. While discussing SSL and certificate based authentication is beyond the scope of this Guide, we will focus on the main criteria involved in ascertaining certificate validity: a) checking if the Certificate Authority (CA) is a known one (meaning one considered trusted), b) checking that the certificate is currently valid, and c) checking that the name of the site and the name reported in the certificate match.
Remember to upgrade your browser because CA certs expired too, in every release of the browser, CA Certs has been renewed. Moreover it's important to update the browser because more web sites require strong cipher more of 40 or 56 bit.

Let’s examine each check more in detail.

a) Each browser comes with a preloaded list of trusted CAs, against which the certificate signing CA is compared (this list can be customized and expanded at will). During the initial negotiations with an https server, if the server certificate relates to a CA unknown to the browser, a warning is usually raised. This happens most often because a web application relies on a certificate signed by a self-established CA. Whether this is to be considered a concern depends on several factors. For example, this may be fine for an Intranet environment (think of corporate web email being provided via https; here, obviously all users recognize the internal CA as a trusted CA). When a service is provided to the general public via the Internet, however (i.e. when it is important to positively verify the identity of the server we are talking to), it is usually imperative to rely on a trusted CA, one which is recognized by all the user base (and here we stop with our considerations; we won’t delve deeper in the implications of the trust model being used by digital certificates).

b) Certificates have an associated period of validity, therefore they may expire. Again, we are warned by the browser about this. A public service needs a temporally valid certificate; otherwise, it means we are talking with a server whose certificate was issued by someone we trust, but has expired without being renewed.

c) What if the name on the certificate and the name of the server do not match? If this happens, it might sound suspicious. For a number of reasons, this is not so rare to see. A system may host a number of name-based virtual hosts, which share the same IP address and are identified by means of the HTTP 1.1 Host: header information. In this case, since the SSL handshake checks the server certificate before the HTTP request is processed, it is not possible to assign different certificates to each virtual server. Therefore, if the name of the site and the name reported in the certificate do not match, we have a condition which is typically signalled by the browser. To avoid this, one of two techniques should be used. First is Server Name Indication (SNI), which is a TLS extension from [http://www.ietf.org/rfc/rfc3546.txt RFC 3546]; and second is IP-based virtual servers must be used. [2] and [3] describe techniques to deal with this problem and allow name-based virtual hosts to be correctly referenced.

===Black Box Testing and examples===

Examine the validity of the certificates used by the application. Browsers will issue a warning when encountering expired certificates, certificates issued by untrusted CAs, and certificates which do not match namewise with the site to which they should refer. By clicking on the padlock which appears in the browser window when visiting an https site, you can look at information related to the certificate – including the issuer, period of validity, encryption characteristics, etc.

If the application requires a client certificate, you probably have installed one to access it. Certificate information is available in the browser by inspecting the relevant certificate(s) in the list of the installed certificates.

These checks must be applied to all visible SSL-wrapped communication channels used by the application. Though this is the usual https service running on port 443, there may be additional services involved depending on the web application architecture and on deployment issues (an https administrative port left open, https services on non-standard ports, etc.). Therefore, apply these checks to all SSL-wrapped ports which have been discovered. For example, the nmap scanner features a scanning mode (enabled by the –sV command line switch) which identifies SSL-wrapped services. The Nessus vulnerability scanner has the capability of performing SSL checks on all SSL/TLS-wrapped services.

'''Examples'''

Rather than providing a fictitious example, we have inserted an anonymized real-life example to stress how frequently one stumbles on https sites whose certificates are inaccurate with respect to naming.

The following screenshots refer to a regional site of a high-profile IT company.

Warning issued by Microsoft Internet Explorer. We are visiting an ''.it'' site and the certificate was issued to a ''.com ''site! Internet Explorer warns that the name on the certificate does not match the name of the site.

[[Image:SSL Certificate Validity Testing IE Warning.gif]]

Warning issued by Mozilla Firefox. The message issued by Firefox is different – Firefox complains because it cannot ascertain the identity of the ''.com'' site the certificate refers to because it does not know the CA which signed the certificate. In fact, Internet Explorer and Firefox do not come preloaded with the same list of CAs. Therefore, the behavior experienced with various browsers may differ.

[[Image:SSL Certificate Validity Testing Firefox Warning.gif]]

===White Box Testing and examples===

Examine the validity of the certificates used by the application at both server and client levels. The usage of certificates is primarily at the web server level; however, there may be additional communication paths protected by SSL (for example, towards the DBMS). You should check the application architecture to identify all SSL protected channels.

==References==
'''Whitepapers''' 
* [1] RFC2246. The TLS Protocol Version 1.0 (updated by RFC3546) - http://www.ietf.org/rfc/rfc2246.txt
* [2] RFC2817. Upgrading to TLS Within HTTP/1.1 - http://www.ietf.org/rfc/rfc2817.txt
* [3] RFC3546. Transport Layer Security (TLS) Extensions - http://www.ietf.org/rfc/rfc3546.txt
* [4] www.verisign.net features various material on the topic

'''Tools'''

* https://www.ssllabs.com/ssldb/

* Vulnerability scanners may include checks regarding certificate validity, including name mismatch and time expiration. They usually report other information as well, such as the CA which issued the certificate. Remember that there is no unified notion of a “trusted CA”; what is trusted depends on the configuration of the software and on the human assumptions made beforehand. Browsers come with a preloaded list of trusted CAs. If your web application relies on a CA which is not in this list (for example, because you rely on a self-made CA), you should take into account the process of configuring user browsers to recognize the CA.

* The Nessus scanner includes a plugin to check for expired certificates or certificates which are going to expire within 60 days (plugin “SSL certificate expiry”, plugin id 15901). This plugin will check certificates ''installed on the server.

* Vulnerability scanners may include checks against weak ciphers. For example, the Nessus scanner (http://www.nessus.org) has this capability and flags the presence of SSL weak ciphers (see example provided above).

* You may also rely on specialized tools such as SSL Digger (http://www.mcafee.com/us/downloads/free-tools/ssldigger.aspx), or – for the command line oriented – experiment with the openssl tool, which provides access to OpenSSL cryptographic functions directly from a Unix shell (may be already available on *nix boxes, otherwise see www.openssl.org).

* To identify SSL-based services, use a vulnerability scanner or a port scanner with service recognition capabilities. The nmap scanner features a “-sV” scanning option which tries to identify services, while the nessus vulnerability scanner has the capability of identifying SSL-based services on arbitrary ports and to run vulnerability checks on them regardless of whether they are configured on standard or non-standard ports.

* In case you need to talk to a SSL service but your favourite tool doesn’t support SSL, you may benefit from a SSL proxy such as stunnel; stunnel will take care of tunneling the underlying protocol (usually http, but not necessarily so) and communicate with the SSL service you need to reach.

* ssl_tests, http://www.pentesterscripting.com/discovery/ssl_tests

* Finally, a word of advice. Though it may be tempting to use a regular browser to check certificates, there are various reasons for not doing so. Browsers have been plagued by various bugs in this area, and the way the browser will perform the check might be influenced by configuration settings that may not be evident. Instead, rely on vulnerability scanners or on specialized tools to do the job.

* [http://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet OWASP Transport Layer Protection Cheat Sheet]

[[Category:Cryptographic Vulnerability]]
[[Category:SSL]]

Testing for SSL-TLS (OWASP-CM-001)

2013-03-10T05:19:28Z

Jeffrey Walton: Testing criteria: added SSLv3 (should also add TLS 1.0); added compression; removed Export (EXP) level cipher suites; lowered security level to 112-bits (e.g., 3-key TDES) (matches 1024 moduli)

{{Template:OWASP Testing Guide v3}}

== Brief Summary ==

Due to historic export restrictions of high grade cryptography, legacy and new web servers are often able and configured to handle weak cryptographic options.

Even if high grade ciphers are normally used and installed, some server misconfiguration could be used to force the use of a weaker cipher to gain access to the supposed secure communication channel.

==Testing SSL / TLS cipher specifications and requirements for site==

The http clear-text protocol is normally secured via an SSL or TLS tunnel, resulting in https traffic. In addition to providing encryption of data in transit, https allows the identification of servers (and, optionally, of clients) by means of digital certificates.

Historically, there have been limitations set in place by the U.S. government to allow cryptosystems to be exported only for key sizes of, at most, 40 bits, a key length which could be broken and would allow the decryption of communications. Since then, cryptographic export regulations have been relaxed (though some constraints still hold); however, it is important to check the SSL configuration being used to avoid putting in place cryptographic support which could be easily defeated. SSL-based services should not offer the possibility to choose weak ciphers.

Technically, cipher determination is performed as follows. In the initial phase of a SSL connection setup, the client sends the server a Client Hello message specifying, among other information, the cipher suites that it is able to handle. A client is usually a web browser (most popular SSL client nowadays), but not necessarily, since it can be any SSL-enabled application; the same holds for the server, which needs not be a web server, though this is the most common case. (For example, a noteworthy class of SSL clients is that of SSL proxies such as stunnel (www.stunnel.org) which can be used to allow non-SSL enabled tools to talk to SSL services.) A cipher suite is specified by an encryption protocol (DES, RC4, AES), the encryption key length (such as 40, 56, or 128 bits), and a hash algorithm (SHA, MD5) used for integrity checking. Upon receiving a Client Hello message, the server decides which cipher suite it will use for that session. It is possible (for example, by means of configuration directives) to specify which cipher suites the server will honor. In this way you may control, for example, whether or not conversations with clients will support 40-bit encryption only.

==SSL testing criteria==
Large number of available cipher suites and quick progress in cryptoanalysis makes judging a SSL server a non-trivial task. These criteria are widely recognised as minimum checklist:

* SSLv2, due to known weaknesses in protocol design
* SSLv3, due to known weaknesses in protocol design
* Compression, due to known weaknesses in protocol design
* Cipher suites with symmetric encryption algorithm smaller than 112 bits
* X.509 certificates with RSA or DSA key smaller than 1024 bits
* X.509 certificates signed using MD5 hash, due to known collision attacks on this hash
* TLS Renegotiation vulnerability[http://www.phonefactor.com/sslgap/ssl-tls-authentication-patches]

While there are known collision attacks on MD5 and known cryptoanalytical attacks on RC4, their specific usage in SSL and TLS doesn't allow these attacks to be practical and SSLv3 or TLSv1 cipher suites using RC4 and MD5 with key length of 128 bit is still considered sufficient[http://www.rsa.com/rsalabs/node.asp?id=2009].

The following standards can be used as reference while assessing SSL servers:

* [http://csrc.nist.gov/publications/nistpubs/800-52/SP800-52.pdf NIST SP 800-52] recommends U.S. federal systems to use at least TLS 1.0 with ciphersuites based on RSA or DSA key agreement with ephemeral Diffie-Hellman, 3DES or AES for confidentality and SHA1 for integrity protection. NIST SP 800-52 specifically disallows non-FIPS compliant algorithms like RC4 and MD5. An exception is U.S. federal systems making connections to outside servers, where these algorithms can be used in SSL client mode.
* [https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml PCI-DSS v1.2] in point 4.1 requires compliant parties to use "strong cryptography" without precisely defining key lengths and algorithms. Common interpretation, partially based on previous versions of the standard, is that at least 128 bit key cipher, no export strength algorithms and no SSLv2 should be used[http://www.digicert.com/news/DigiCert_PCI_White_Paper.pdf].
* [https://www.ssllabs.com/projects/rating-guide/index.html SSL Server Rating Guide] has been proposed to standardize SSL server assessment and currently is in draft version.

SSL Server Database can be used to assess configuration of publicly available SSL servers[https://www.ssllabs.com/ssldb/analyze.html] based on SSL Rating Guide[https://www.ssllabs.com/projects/rating-guide/index.html]

==Black Box Test and example==

In order to detect possible support of weak ciphers, the ports associated to SSL/TLS wrapped services must be identified. These typically include port 443, which is the standard https port; however, this may change because a) https services may be configured to run on non-standard ports, and b) there may be additional SSL/TLS wrapped services related to the web application. In general, a service discovery is required to identify such ports.

The nmap scanner, via the “–sV” scan option, is able to identify SSL services. Vulnerability Scanners, in addition to performing service discovery, may include checks against weak ciphers (for example, the Nessus scanner has the capability of checking SSL services on arbitrary ports, and will report weak ciphers).

'''Example 1'''. SSL service recognition via nmap.

<pre>
[root@test]# nmap -F -sV localhost

Starting nmap 3.75 ( http://www.insecure.org/nmap/ ) at 2005-07-27 14:41 CEST
Interesting ports on localhost.localdomain (127.0.0.1):
(The 1205 ports scanned but not shown below are in state: closed)

PORT STATE SERVICE VERSION
443/tcp open ssl OpenSSL
901/tcp open http Samba SWAT administration server
8080/tcp open http Apache httpd 2.0.54 ((Unix) mod_ssl/2.0.54 OpenSSL/0.9.7g PHP/4.3.11)
8081/tcp open http Apache Tomcat/Coyote JSP engine 1.0

Nmap run completed -- 1 IP address (1 host up) scanned in 27.881 seconds
[root@test]#
</pre>

'''Example 2'''. Identifying weak ciphers with Nessus.
The following is an anonymized excerpt of a report generated by the Nessus scanner, corresponding to the identification of a server certificate allowing weak ciphers (see underlined text).

'''https (443/tcp)'''
'''Description'''
Here is the SSLv2 server certificate:
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: md5WithRSAEncryption
Issuer: C=**, ST=******, L=******, O=******, OU=******, CN=******
Validity
Not Before: Oct 17 07:12:16 2002 GMT
Not After : Oct 16 07:12:16 2004 GMT
Subject: C=**, ST=******, L=******, O=******, CN=******
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:98:4f:24:16:cb:0f:74:e8:9c:55:ce:62:14:4e:
6b:84:c5:81:43:59:c1:2e:ac:ba:af:92:51:f3:0b:
ad:e1:4b:22:ba:5a:9a:1e:0f:0b:fb:3d:5d:e6:fc:
ef:b8:8c:dc:78:28:97:8b:f0:1f:17:9f:69:3f:0e:
72:51:24:1b:9c:3d:85:52:1d:df:da:5a:b8:2e:d2:
09:00:76:24:43:bc:08:67:6b:dd:6b:e9:d2:f5:67:
e1:90:2a:b4:3b:b4:3c:b3:71:4e:88:08:74:b9:a8:
2d:c4:8c:65:93:08:e6:2f:fd:e0:fa:dc:6d:d7:a2:
3d:0a:75:26:cf:dc:47:74:29
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
Page 10
Network Vulnerability Assessment Report 25.05.2005
X509v3 Subject Key Identifier:
10:00:38:4C:45:F0:7C:E4:C6:A7:A4:E2:C9:F0:E4:2B:A8:F9:63:A8
X509v3 Authority Key Identifier:
keyid:CE:E5:F9:41:7B:D9:0E:5E:5D:DF:5E:B9:F3:E6:4A:12:19:02:76:CE
DirName:/C=**/ST=******/L=******/O=******/OU=******/CN=******
serial:00
Signature Algorithm: md5WithRSAEncryption
7b:14:bd:c7:3c:0c:01:8d:69:91:95:46:5c:e6:1e:25:9b:aa:
8b:f5:0d:de:e3:2e:82:1e:68:be:97:3b:39:4a:83:ae:fd:15:
2e:50:c8:a7:16:6e:c9:4e:76:cc:fd:69:ae:4f:12:b8:e7:01:
b6:58:7e:39:d1:fa:8d:49:bd:ff:6b:a8:dd:ae:83:ed:bc:b2:
40:e3:a5:e0:fd:ae:3f:57:4d:ec:f3:21:34:b1:84:97:06:6f:
f4:7d:f4:1c:84:cc:bb:1c:1c:e7:7a:7d:2d:e9:49:60:93:12:
0d:9f:05:8c:8e:f9:cf:e8:9f:fc:15:c0:6e:e2:fe:e5:07:81:
82:fc
Here is the list of available SSLv2 ciphers:
RC4-MD5
EXP-RC4-MD5
RC2-CBC-MD5
EXP-RC2-CBC-MD5
DES-CBC-MD5
DES-CBC3-MD5
RC4-64-MD5
The SSLv2 server offers 5 strong ciphers, but also 0 medium strength and '''2 weak "export class" ciphers'''.
The weak/medium ciphers may be chosen by an export-grade or badly configured client software. They only offer a limited protection against a brute force attack
Solution: disable those ciphers and upgrade your client software if necessary.
See http://support.microsoft.com/default.aspx?scid=kben-us216482
or http://httpd.apache.org/docs-2.0/mod/mod_ssl.html#sslciphersuite
This SSLv2 server also accepts SSLv3 connections.
This SSLv2 server also accepts TLSv1 connections.

Vulnerable hosts
''(list of vulnerable hosts follows)''

'''Example 3'''. Manually audit weak SSL cipher levels with OpenSSL. The following will attempt to connect to Google.com with SSLv2.
<pre>
[root@test]# openssl s_client -no_tls1 -no_ssl3 -connect www.google.com:443
CONNECTED(00000003)
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDYzCCAsygAwIBAgIQYFbAC3yUC8RFj9MS7lfBkzANBgkqhkiG9w0BAQQFADCB
zjELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJ
Q2FwZSBUb3duMR0wGwYDVQQKExRUaGF3dGUgQ29uc3VsdGluZyBjYzEoMCYGA1UE
CxMfQ2VydGlmaWNhdGlvbiBTZXJ2aWNlcyBEaXZpc2lvbjEhMB8GA1UEAxMYVGhh
d3RlIFByZW1pdW0gU2VydmVyIENBMSgwJgYJKoZIhvcNAQkBFhlwcmVtaXVtLXNl
cnZlckB0aGF3dGUuY29tMB4XDTA2MDQyMTAxMDc0NVoXDTA3MDQyMTAxMDc0NVow
aDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDU1v
dW50YWluIFZpZXcxEzARBgNVBAoTCkdvb2dsZSBJbmMxFzAVBgNVBAMTDnd3dy5n
b29nbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC/e2Vs8U33fRDk
5NNpNgkB1zKw4rqTozmfwty7eTEI8PVH1Bf6nthocQ9d9SgJAI2WOBP4grPj7MqO
dXMTFWGDfiTnwes16G7NZlyh6peT68r7ifrwSsVLisJp6pUf31M5Z3D88b+Yy4PE
D7BJaTxq6NNmP1vYUJeXsGSGrV6FUQIDAQABo4GmMIGjMB0GA1UdJQQWMBQGCCsG
AQUFBwMBBggrBgEFBQcDAjBABgNVHR8EOTA3MDWgM6Axhi9odHRwOi8vY3JsLnRo
YXd0ZS5jb20vVGhhd3RlUHJlbWl1bVNlcnZlckNBLmNybDAyBggrBgEFBQcBAQQm
MCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0ZS5jb20wDAYDVR0TAQH/
BAIwADANBgkqhkiG9w0BAQQFAAOBgQADlTbBdVY6LD1nHWkhTadmzuWq2rWE0KO3
Ay+7EleYWPOo+EST315QLpU6pQgblgobGoI5x/fUg2U8WiYj1I1cbavhX2h1hda3
FJWnB3SiXaiuDTsGxQ267EwCVWD5bCrSWa64ilSJTgiUmzAv0a2W8YHXdG08+nYc
X/dVk5WRTw==
-----END CERTIFICATE-----
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
---
No client certificate CA names sent
---
Ciphers common between both SSL endpoints:
RC4-MD5 EXP-RC4-MD5 RC2-CBC-MD5
EXP-RC2-CBC-MD5 DES-CBC-MD5 DES-CBC3-MD5
RC4-64-MD5
---
SSL handshake has read 1023 bytes and written 333 bytes
---
New, SSLv2, Cipher is DES-CBC3-MD5
Server public key is 1024 bit
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : SSLv2
Cipher : DES-CBC3-MD5
Session-ID: 709F48E4D567C70A2E49886E4C697CDE
Session-ID-ctx:
Master-Key: 649E68F8CF936E69642286AC40A80F433602E3C36FD288C3
Key-Arg : E8CB6FEB9ECF3033
Start Time: 1156977226
Timeout : 300 (sec)
Verify return code: 21 (unable to verify the first certificate)
---
closed
</pre>

'''Example 4'''. Testing supported protocols and ciphers using SSLScan.

SSLScan is a free command line tool that scans a HTTPS service to enumerate what protocols (supports SSLv2, SSLv3 and TLS1) and what ciphers the HTTPS service supports. It runs both on Linux and Windows OS (OSX not tested) and is released under a open source license.

<pre>
[user@test]$ ./SSLScan --no-failed mail.google.com
_
___ ___| |___ ___ __ _ _ __
/ __/ __| / __|/ __/ _` | '_ \
\__ \__ \ \__ \ (_| (_| | | | |
|___/___/_|___/\___\__,_|_| |_|

Version 1.9.0-win
http://www.titania.co.uk
Copyright 2010 Ian Ventura-Whiting / Michael Boman
Compiled against OpenSSL 0.9.8n 24 Mar 2010

Testing SSL server mail.google.com on port 443

Supported Server Cipher(s):
accepted SSLv3 256 bits AES256-SHA
accepted SSLv3 128 bits AES128-SHA
accepted SSLv3 168 bits DES-CBC3-SHA
accepted SSLv3 128 bits RC4-SHA
accepted SSLv3 128 bits RC4-MD5
accepted TLSv1 256 bits AES256-SHA
accepted TLSv1 128 bits AES128-SHA
accepted TLSv1 168 bits DES-CBC3-SHA
accepted TLSv1 128 bits RC4-SHA
accepted TLSv1 128 bits RC4-MD5

Prefered Server Cipher(s):
SSLv3 128 bits RC4-SHA
TLSv1 128 bits RC4-SHA

SSL Certificate:
Version: 2
Serial Number: -4294967295
Signature Algorithm: sha1WithRSAEncryption
Issuer: /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
Not valid before: Dec 18 00:00:00 2009 GMT
Not valid after: Dec 18 23:59:59 2011 GMT
Subject: /C=US/ST=California/L=Mountain View/O=Google Inc/CN=mail.google.com
Public Key Algorithm: rsaEncryption
RSA Public Key: (1024 bit)
Modulus (1024 bit):
00:d9:27:c8:11:f2:7b:e4:45:c9:46:b6:63:75:83:
b1:77:7e:17:41:89:80:38:f1:45:27:a0:3c:d9:e8:
a8:00:4b:d9:07:d0:ba:de:ed:f4:2c:a6:ac:dc:27:
13:ec:0c:c1:a6:99:17:42:e6:8d:27:d2:81:14:b0:
4b:82:fa:b2:c5:d0:bb:20:59:62:28:a3:96:b5:61:
f6:76:c1:6d:46:d2:fd:ba:c6:0f:3d:d1:c9:77:9a:
58:33:f6:06:76:32:ad:51:5f:29:5f:6e:f8:12:8b:
ad:e6:c5:08:39:b3:43:43:a9:5b:91:1d:d7:e3:cf:
51:df:75:59:8e:8d:80:ab:53
Exponent: 65537 (0x10001)
X509v3 Extensions:
X509v3 Basic Constraints: critical
CA:FALSE X509v3 CRL Distribution Points:
URI:http://crl.thawte.com/ThawteSGCCA.crl
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication, Netscape Server Gated Crypto Authority Information Access:
OCSP - URI:http://ocsp.thawte.com
CA Issuers - URI:http://www.thawte.com/repository/Thawte_SGC_CA.crt
Verify Certificate:
unable to get local issuer certificate

Renegotiation requests supported
</pre>

'''Example 5'''. Testing common SSL flaws with ssl_tests

ssl_tests (http://www.pentesterscripting.com/discovery/ssl_tests) is a bash script that uses sslscan and openssl to check for various flaws - ssl version 2, weak ciphers, md5withRSAEncryption,SSLv3 Force Ciphering Bug/Renegotiation.

<pre>

[user@test]$ ./ssl_test.sh 192.168.1.3 443
+++++++++++++++++++++++++++++++++++++++++++++++++
SSL Tests - v2, weak ciphers, MD5, Renegotiation
by Aung Khant, http://yehg.net
+++++++++++++++++++++++++++++++++++++++++++++++++

[*] testing on 192.168.1.3:443 ..

[*] tesing for sslv2 ..
[*] sslscan 192.168.1.3:443 | grep Accepted SSLv2
Accepted SSLv2 168 bits DES-CBC3-MD5
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 128 bits RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv2 128 bits RC4-MD5

[*] testing for weak ciphers ...
[*] sslscan 192.168.1.3:443 | grep 40 bits | grep Accepted
Accepted SSLv2 40 bits EXP-RC2-CBC-MD5
Accepted SSLv2 40 bits EXP-RC4-MD5
Accepted SSLv3 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-DES-CBC-SHA
Accepted SSLv3 40 bits EXP-RC2-CBC-MD5
Accepted SSLv3 40 bits EXP-RC4-MD5
Accepted TLSv1 40 bits EXP-EDH-RSA-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-DES-CBC-SHA
Accepted TLSv1 40 bits EXP-RC2-CBC-MD5
Accepted TLSv1 40 bits EXP-RC4-MD5

[*] sslscan 192.168.1.3:443 | grep 56 bits | grep Accepted
Accepted SSLv2 56 bits DES-CBC-MD5
Accepted SSLv3 56 bits EDH-RSA-DES-CBC-SHA
Accepted SSLv3 56 bits DES-CBC-SHA
Accepted TLSv1 56 bits EDH-RSA-DES-CBC-SHA
Accepted TLSv1 56 bits DES-CBC-SHA

[*] testing for MD5 certificate ..
[*] sslscan 192.168.1.3:443 | grep MD5WithRSAEncryption

[*] testing for SSLv3 Force Ciphering Bug/Renegotiation ..
[*] echo R | openssl s_client -connect 192.168.1.3:443 | grep DONE
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
RENEGOTIATING
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=DE/ST=Berlin/L=Berlin/O=XAMPP/OU=XAMPP/CN=localhost/emailAddress=admin@localhost
verify return:1
DONE

[*] done

</pre>

==White Box Test and example==

Check the configuration of the web servers which provide https services. If the web application provides other SSL/TLS wrapped services, these should be checked as well.

'''Example:''' The following registry path in Microsoft Windows 2003 defines the ciphers available to the server:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\

==Testing SSL certificate validity – client and server==

When accessing a web application via the https protocol, a secure channel is established between the client (usually the browser) and the server. The identity of one (the server) or both parties (client and server) is then established by means of digital certificates. In order for the communication to be set up, a number of checks on the certificates must be passed. While discussing SSL and certificate based authentication is beyond the scope of this Guide, we will focus on the main criteria involved in ascertaining certificate validity: a) checking if the Certificate Authority (CA) is a known one (meaning one considered trusted), b) checking that the certificate is currently valid, and c) checking that the name of the site and the name reported in the certificate match.
Remember to upgrade your browser because CA certs expired too, in every release of the browser, CA Certs has been renewed. Moreover it's important to update the browser because more web sites require strong cipher more of 40 or 56 bit.

Let’s examine each check more in detail.

a) Each browser comes with a preloaded list of trusted CAs, against which the certificate signing CA is compared (this list can be customized and expanded at will). During the initial negotiations with an https server, if the server certificate relates to a CA unknown to the browser, a warning is usually raised. This happens most often because a web application relies on a certificate signed by a self-established CA. Whether this is to be considered a concern depends on several factors. For example, this may be fine for an Intranet environment (think of corporate web email being provided via https; here, obviously all users recognize the internal CA as a trusted CA). When a service is provided to the general public via the Internet, however (i.e. when it is important to positively verify the identity of the server we are talking to), it is usually imperative to rely on a trusted CA, one which is recognized by all the user base (and here we stop with our considerations; we won’t delve deeper in the implications of the trust model being used by digital certificates).

b) Certificates have an associated period of validity, therefore they may expire. Again, we are warned by the browser about this. A public service needs a temporally valid certificate; otherwise, it means we are talking with a server whose certificate was issued by someone we trust, but has expired without being renewed.

c) What if the name on the certificate and the name of the server do not match? If this happens, it might sound suspicious. For a number of reasons, this is not so rare to see. A system may host a number of name-based virtual hosts, which share the same IP address and are identified by means of the HTTP 1.1 Host: header information. In this case, since the SSL handshake checks the server certificate before the HTTP request is processed, it is not possible to assign different certificates to each virtual server. Therefore, if the name of the site and the name reported in the certificate do not match, we have a condition which is typically signalled by the browser. To avoid this, one of two techniques should be used. First is Server Name Indication (SNI), which is a TLS extension from [http://www.ietf.org/rfc/rfc3546.txt RFC 3546]; and second is IP-based virtual servers must be used. [2] and [3] describe techniques to deal with this problem and allow name-based virtual hosts to be correctly referenced.

===Black Box Testing and examples===

Examine the validity of the certificates used by the application. Browsers will issue a warning when encountering expired certificates, certificates issued by untrusted CAs, and certificates which do not match namewise with the site to which they should refer. By clicking on the padlock which appears in the browser window when visiting an https site, you can look at information related to the certificate – including the issuer, period of validity, encryption characteristics, etc.

If the application requires a client certificate, you probably have installed one to access it. Certificate information is available in the browser by inspecting the relevant certificate(s) in the list of the installed certificates.

These checks must be applied to all visible SSL-wrapped communication channels used by the application. Though this is the usual https service running on port 443, there may be additional services involved depending on the web application architecture and on deployment issues (an https administrative port left open, https services on non-standard ports, etc.). Therefore, apply these checks to all SSL-wrapped ports which have been discovered. For example, the nmap scanner features a scanning mode (enabled by the –sV command line switch) which identifies SSL-wrapped services. The Nessus vulnerability scanner has the capability of performing SSL checks on all SSL/TLS-wrapped services.

'''Examples'''

Rather than providing a fictitious example, we have inserted an anonymized real-life example to stress how frequently one stumbles on https sites whose certificates are inaccurate with respect to naming.

The following screenshots refer to a regional site of a high-profile IT company.

Warning issued by Microsoft Internet Explorer. We are visiting an ''.it'' site and the certificate was issued to a ''.com ''site! Internet Explorer warns that the name on the certificate does not match the name of the site.

[[Image:SSL Certificate Validity Testing IE Warning.gif]]

Warning issued by Mozilla Firefox. The message issued by Firefox is different – Firefox complains because it cannot ascertain the identity of the ''.com'' site the certificate refers to because it does not know the CA which signed the certificate. In fact, Internet Explorer and Firefox do not come preloaded with the same list of CAs. Therefore, the behavior experienced with various browsers may differ.

[[Image:SSL Certificate Validity Testing Firefox Warning.gif]]

===White Box Testing and examples===

Examine the validity of the certificates used by the application at both server and client levels. The usage of certificates is primarily at the web server level; however, there may be additional communication paths protected by SSL (for example, towards the DBMS). You should check the application architecture to identify all SSL protected channels.

==References==
'''Whitepapers''' 
* [1] RFC2246. The TLS Protocol Version 1.0 (updated by RFC3546) - http://www.ietf.org/rfc/rfc2246.txt
* [2] RFC2817. Upgrading to TLS Within HTTP/1.1 - http://www.ietf.org/rfc/rfc2817.txt
* [3] RFC3546. Transport Layer Security (TLS) Extensions - http://www.ietf.org/rfc/rfc3546.txt
* [4] www.verisign.net features various material on the topic

'''Tools'''

* https://www.ssllabs.com/ssldb/

* Vulnerability scanners may include checks regarding certificate validity, including name mismatch and time expiration. They usually report other information as well, such as the CA which issued the certificate. Remember that there is no unified notion of a “trusted CA”; what is trusted depends on the configuration of the software and on the human assumptions made beforehand. Browsers come with a preloaded list of trusted CAs. If your web application relies on a CA which is not in this list (for example, because you rely on a self-made CA), you should take into account the process of configuring user browsers to recognize the CA.

* The Nessus scanner includes a plugin to check for expired certificates or certificates which are going to expire within 60 days (plugin “SSL certificate expiry”, plugin id 15901). This plugin will check certificates ''installed on the server.

* Vulnerability scanners may include checks against weak ciphers. For example, the Nessus scanner (http://www.nessus.org) has this capability and flags the presence of SSL weak ciphers (see example provided above).

* You may also rely on specialized tools such as SSL Digger (http://www.mcafee.com/us/downloads/free-tools/ssldigger.aspx), or – for the command line oriented – experiment with the openssl tool, which provides access to OpenSSL cryptographic functions directly from a Unix shell (may be already available on *nix boxes, otherwise see www.openssl.org).

* To identify SSL-based services, use a vulnerability scanner or a port scanner with service recognition capabilities. The nmap scanner features a “-sV” scanning option which tries to identify services, while the nessus vulnerability scanner has the capability of identifying SSL-based services on arbitrary ports and to run vulnerability checks on them regardless of whether they are configured on standard or non-standard ports.

* In case you need to talk to a SSL service but your favourite tool doesn’t support SSL, you may benefit from a SSL proxy such as stunnel; stunnel will take care of tunneling the underlying protocol (usually http, but not necessarily so) and communicate with the SSL service you need to reach.

* ssl_tests, http://www.pentesterscripting.com/discovery/ssl_tests

* Finally, a word of advice. Though it may be tempting to use a regular browser to check certificates, there are various reasons for not doing so. Browsers have been plagued by various bugs in this area, and the way the browser will perform the check might be influenced by configuration settings that may not be evident. Instead, rely on vulnerability scanners or on specialized tools to do the job.

* [http://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet OWASP Transport Layer Protection Cheat Sheet]

[[Category:Cryptographic Vulnerability]]
[[Category:SSL]]

Clickjacking Defense Cheat Sheet

2013-03-09T07:04:15Z

Jeffrey Walton: Improved flow

= Clickjacking Defense Introduction =

This cheat sheet is focused on providing developer guidance on Clickjack/UI Redress attack prevention. For more information on the risk of Clickjacking, please visit [https://www.owasp.org/index.php/Clickjacking this page]. Additional references on clickjacking can be found [https://www.owasp.org/index.php/Clickjacking#References here].

The most popular way to defend against clickjacking is to include some sort of "frame-breaking" functionality which prevents other web pages from framing the site you wish to defend. This cheat sheet will discuss two methods of implementing frame-breaking: first is X-FRAME-OPTIONS headers (used if the browser supports the functionality); and second is javascript frame-breaking code.

= Defending with X-FRAME-OPTIONS response headers =

The X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in a <frame> or <iframe>. Sites can use this to avoid clickjacking attacks, by ensuring that their content is not embedded into other sites.

=== X-FRAME-OPTIONS Header Types ===

There are three types of X-FRAME-OPTIONS headers.
* The first is X-FRAME-OPTIONS DENY, which prevents any domain from framing the content.
* The second option is X-FRAME-OPTIONS SAMEORIGIN, which only allows the current site to frame the content.
* The third, is the X-FRAME-OPTIONS ALLOW-FROM 'sitename' header, which permits the specified 'sitename' to frame this page. (e.g., ALLOW-FROM http://www.foo.com) The ALLOW-FROM option is a relatively recent addition (circa 2012) and may not be supported by all browsers yet.

=== Browser Support ===

The following browsers support X-FRAME-OPTIONS headers.

<table border="1">
<tr> <th>Browser</th> <th>Lowest version</th></tr>
<tr> <td>Internet Explorer</td> <td>8.0</td></tr>
<tr> <td>Firefox (Gecko)</td> <td>3.6.9 (1.9.2.9)</td></tr>
<tr> <td>Opera</td> <td>10.50</td> </tr> <tr> <td>Safari</td> <td>4.0</td></tr>
<tr> <td>Chrome</td> <td>4.1.249.1042</td> </tr>
</table>

Reference: [https://developer.mozilla.org/en-US/docs/The_X-FRAME-OPTIONS_response_header https://developer.mozilla.org/en-US/docs/The_X-FRAME-OPTIONS_response_header]

=== Implementation ===

To implement this protection, you need to add the header to any page that you want to protect from being clickjacked. One way to do this is to add the header manually to every page. A possibly simpler way is to implement a filter that automatically adds the header to every page.

OWASP has an [[ClickjackFilter for Java EE|article and some code]] that provides all the details for implementing this in the Java EE environment.

The SDL blog has posted an [http://blogs.msdn.com/sdl/archive/2009/02/05/clickjacking-defense-in-ie8.aspx article] covering how to implement this in a .NET environment.

=== Limitations ===

* '''Per-page policy specifcation'''
The policy needs to be specifed for every page, which can complicate deployment. Providing the ability to enforce it for the entire site, at login time for instance, could simplify adoption.

* '''Problems with multi-domain sites'''
The current implementation does not allow the webmaster to provide a whitelist of domains that are allowed to frame the page. While whitelisting can be dangerous, in some cases a webmaster might have no choice but to use more than one hostname.

* '''Proxies'''
Web proxies are notorious for adding and stripping headers. If a web proxy strips the X-FRAME-OPTIONS header then the site loses its framing protection.

= Clickjacking defense for legacy browsers =

The following methodology will prevent a webpage from being framed even in legacy browsers.

In the document HEAD element, add the following:

First apply an ID to the style element itself:

<style id="antiClickjack">body{display:none !important;}</style>

And then delete that style by its ID immediately after in the script:

<script type="text/javascript">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
</script>

This way, everything can be in the document HEAD and you only need one method/taglib in your API.

Reference: [https://www.codemagi.com/blog/post/194 https://www.codemagi.com/blog/post/194]

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T06:57:42Z

Jeffrey Walton: Added note on removing dependencies

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. You will use a debug build while developing, your continuous integration or build server will use test configurations, and you will ship release builds.

1970's K&R code and one size fits all flags are from a bygone era. Proccesses have evolved and matured to meet the challanges of a modern landscape, including threats. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your program. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program. Because a stable library with required functionality can be elusive and its tricky to integrate libraries, you should try to minimize dependencies and avoid thrid party libraries whenever possible.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug builds also present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. If you don't use <tt>/Wall</tt>, Microsoft recomends using <tt>/W4</tt> and enabling C4191, C4242, C4263, C4264, C4265, C4266, C4302, C4826, C4905, C4906, and C4928. Finally, <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'', ''[http://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx “Off By Default” Compiler Warnings in Visual C++]'', and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Options Summary]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T06:52:11Z

Jeffrey Walton: Added preamble before recommending against using Autotools (its sure to raise objections)

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. You will use a debug build while developing, your continuous integration or build server will use test configurations, and you will ship release builds.

1970's K&R code and one size fits all flags are from a bygone era. Proccesses have evolved and matured to meet the challanges of a modern landscape, including threats. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your program. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug builds also present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. If you don't use <tt>/Wall</tt>, Microsoft recomends using <tt>/W4</tt> and enabling C4191, C4242, C4263, C4264, C4265, C4266, C4302, C4826, C4905, C4906, and C4928. Finally, <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'', ''[http://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx “Off By Default” Compiler Warnings in Visual C++]'', and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Options Summary]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T06:38:52Z

Jeffrey Walton: Improved flow

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your program. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug builds also present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. If you don't use <tt>/Wall</tt>, Microsoft recomends using <tt>/W4</tt> and enabling C4191, C4242, C4263, C4264, C4265, C4266, C4302, C4826, C4905, C4906, and C4928. Finally, <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'', ''[http://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx “Off By Default” Compiler Warnings in Visual C++]'', and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Options Summary]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Mobile Jailbreaking Cheat Sheet

2013-03-09T06:23:38Z

Jeffrey Walton: Added opening paragraph

= Dangers of Jailbreaking and Rooting Mobile Devices =

==What is "jailbreaking" and "rooting"?==

Jailbreaking and rooting is the process of gaining unauthorized access or elevated privileges on a system. The terms are different between operating system, and the differences in terminology reflect the differences in security models used by the operating systems vendors.

For iOS, '''Jailbreaking''' is the process of modifying iOS system kernels to allow file system read and write access. Most jailbreaking tools (and exploits) remove the limitations and security features built by the manufacturer Apple (the "jail") through the use of custom kernels, which make unauthorized modifications to the operating system. Almost all jailbreaking tools allow users to run code not approved and signed by Apple. This allows users to install additional applications, extensions and patches without the control of Apple’s App Store.

On Android, '''Rooting''' is the process of gaining administrative or privileged access for the Android OS. As the Android OS is based on the Linux Kernel, rooting a device is analogous to gaining access to administrative, root user-equivalent, permissions on Linux. Unlike iOS, rooting is (usually) not required to run applications outside from the Android Market. Some carriers control this through operating system settings or device firmware. Rooting also enables the user to completely remove and replace the device's operating system.

==Why do they occur?==
iOS: Many users are lured into jailbreaking to take advantage of apps made available through third party app sources, such as Cydia, which are otherwise banned or not approved by Apple. There is an inherent risk in installing such applications as they are not quality controlled nor have they gone through the Apple approval and application approval process. Hence, they may contain vulnerable or malicious code that could allow the device to be compromised. Alternately, jailbreaking can allow users to enhance some built in functions on their device. For example, a jailbroken phone can be used with a different carrier than the one it was configured with, FaceTime can be used over a 3G connection, or the phone can be unlocked to be used internationally. More technically savvy users also perform jailbreaking to enable user interface customizations, preferences and features not available through the normal software interface. Typically, these functionalities are achieved by patching specific binaries in the operating system.
A debated purpose for jailbreaking in the iOS community is for installing pirated iOS applications. Jailbreaking proponents discourage this use, such as Cydia warning users of pirated software when they add a pirated software repository. However, repositories such as Hackulous promote pirated applications and the tools to pirate and distribute applications.

Android: Rooting Android devices allows users to gain access to additional hardware rights, backup utilities and direct hardware access. Additionally, rooting allows users to remove the pre-installed "bloatware", additional features that many carriers or manufacturers put onto devices, which can use considerable amounts of disk space and memory. Most users root their device to leverage a custom read only memory (ROM) developed by the Android Community, which brings distinctive capabilities that are not available through the official ROMs installed by the carriers. Custom ROMs also provide users an option to 'upgrade' the operating system and optimize the phone experience by giving users access to features, such as tethering, that are normally blocked or limited by carriers.

==What are the common tools used?==

iOS: Jailbreaking software can be categorized into two main groups:
#Tethered: Requires the device to be connected to a system in order to bypass the iBoot signature check for iOS devices. The iOS device needs to be connected or tethered to a computer system every time it has to reboot in order to access the jailbreak application, such as redsn0w, and boot correctly.
#Un-tethered: Requires connection for the initial jailbreak process and then all the software, such as sn0wbreeze and evasi0n, is on the device for future un-tethered reboots, without losing the jailbreak or the functionality of the phone.

Some common, but not all of the iOS jailbreaking tools are listed below:
*Absinthe
*blackra1n
*Corona
*greenpois0n
*JailbreakMe
*limera1n
*PwnageTool
*redsn0w
* evasi0n
*sn0wbreeze
*Spirit

A more comprehensive list of jailbreaking tools for iOS, exploits and kernel patches can be found on the iPhoneWiki website.

Android: There are various rooting software available for Android. Tools and processes vary depending on the user’s device. The process is usually to:
#Unlock the boot loader.
#Install a rooting application and / or flash a custom ROM through the recovery mode.

Not all of the above tasks are necessary and different toolkits are available for device specific rooting process. Custom ROMs are based on the hardware being used; examples of some are as follows:

CyanogenMod ROMs are one of the most popular aftermarket replacement firmware in the Android world. More comprehensive device specific firmwares, flashing guides, rooting tools and patch details can be referenced from the homepage.

ClockWorkMod is a custom recovery option for Android phones and tablets that allows you to perform several advanced recovery, restoration, installation and maintenance operations etc. Please refer to xda-developers for more details.

==Why can it be dangerous?==

The tools above can be broadly categorized in the following categories:
*Userland Exploits: Jailbroken access is only obtained within the user layer. For instance, a user may have root access, but is not able to change the boot process. These exploits can be patched with a firmware update.
*iBoot Exploit: Jailbroken access to user level and boot process. iBoot exploits can be patched with a firmware update.
*Bootrom Exploits: Jailbroken access to user level and boot process. Bootrom exploits cannot be patched with a firmware update. Hardware update of bootrom required to patch in such cases.

Some high level risks for rooting or jailbreaking devices are as follows:

===Technical Risks:===
#General Mobile
##Some jailbreaking methods leave SSH enabled with a well known default password (i.e. alpine) that attackers can use for Command & Control.
##Entire file system of a rooted or jailbroken device is vulnerable to a malicious user inserting or extracting files. This vulnerability is exploited by many malware programs, including Droid Kung Fu, Droid Dream and Ikee.
##Credentials to sensitive applications, such as banking or corporate applications, can be stolen using key logging, sniffing or other malicious software and then transmitted via the internet connection.
#iOS
##Applications on a jailbroken device run as root outside of the iOS sandbox. This can allow applications to access sensitive data contained in other apps or install malicious software negating sandboxing functionality.
##Jailbroken devices can allow a user to install and run self-signed applications. Since the apps do not go through the App Store, they are not reviewed by Apple. These apps may contain vulnerable or malicious code that can be used to exploit a device.
#Android
##Android users that change the permissions on their device to grant root access to applications increase security exposure to malicious applications and potential application flaws.
##3rd party Android application markets have been identified as hosting malicious applications with remote administrative (RAT) capabilities.

===Non-technical risks:===
#According to the Unted States Librarian of Congress (who issues Digital Millennium Copyright Act (DMCA) excemptions), jailbreaking or rooting of a smartphone is '''not''' deemed illegal in the US for persons who engage in noninfringing uses. The approval can provide some users with a false sense safety and jailbreaking or rooting as being harmless. Its noteworthy the Librarian does not apporve jailbreaking of tablets, however. Please see ''[http://www.theinquirer.net/inquirer/news/2220251/us-rules-jailbreaking-tablets-is-illegal US rules jailbreaking tablets is illegal]'' for a layman's analysis.

#Software updates cannot be immediately applied because doing so would remove the jailbreak. This leaves the device vulnerable to known, unpatched software vulnerabilities.
#Users can be tricked into downloading malicious software. For example, malware commonly uses the following tactics to trick users into downloading software.
##Apps will often advertise that they provide additional functionality or remove ads from popular apps but also contain malicious code.
##Some apps will not have any malicious code as part of the initial version of the app but subsequent "Updates" will insert malicious code.
#Manufacturers have determined that jailbreaking or rooting is a breach of the terms of use for the device and therefore voids the warranty. This can be an issue for the user if the device needs hardware repair or technical support (Note: a device can be restored and therefore it is not a major issue, unless hardware damage otherwise covered by the warranty prevents restoration).

What controls can be used to protect against it?
Before an organization chooses to implement a mobile solution in their environment they should conduct a thorough risk assessment. This risk assessment should include an evaluation of the dangers posed by jailbroken or rooted devices, which are inherently more vulnerable to malicious applications or vulnerabilities such as those listed in the OWASP Mobile Security Top Ten Risks. Once this has assessment has been completed, management can determine which risks to accept and which risks will require additional controls to mitigate. Below are a few examples of both technical and non-technical controls that an organization may use.

===Technical Controls:===

Some of the detective controls to monitor for jailbroken or rooted devices include:
#Identify 3rd party app stores (e.g., Cydia).
#Attempt to identify modified kernels by comparing certain system files that the application would have access to on a non jailbroken device to known good file hashes. This technique can serve as a good starting point for detection.
#Attempt to write a file outside of the application’s root directory. The attempt should fail for non-jailbroken devices.

Note: Most Mobile Device Management (MDM) solutions can perform these checks but require an application to be installed on the device.

===Non-Technical Controls:===

Organizations must understand the following key points when thinking about mobile security:
#Perform a risk assessment to determine risks associated with mobile device use are appropriately identified, prioritized and mitigated to reduce or manage risk at levels acceptable to management.
#Review application inventory listing on frequent basis to identify applications posing significant risk to the mobility environment.
#Technology solutions such as Mobile Device Management (MDM) or Mobile Application Management (MAM) should be only one part of the overall security strategy. High level considerations include:
##Policies and procedures.
##User awareness and user buy-in.
##Technical controls and platforms.
##Auditing, logging, and monitoring.
#While many organizations choose a Bring Your Own Device (BYOD) strategy, the risks and benefits need to be considered and addressed before such a strategy is put in place. For example, the organization may consider developing a support plan for the various devices and operating systems that could be introduced to the environment. Many organizations struggle with this since there are such a wide variety of devices, particularly Android devices.
#There is not a ‘one size fits all’ solution to mobile security. Different levels of security controls should be employed based on the sensitivity of data that is collected, stored, or processed on a mobile device or through a mobile application.
#User awareness and user buy-in are key. For consumers or customers, this could be a focus on privacy and how Personally Identifiable Information (PII) is handled. For employees, this could be a focus on Acceptable Use Agreements (AUA) as well as privacy for personal devices.

==Conclusion==

Jailbreaking and rooting tools, resources and processes are constantly updated and have made the process easier than ever for end-users. Many users are lured to jailbreak or root their device in order to gain more control over the device, upgrade their operating systems or install packages normally unavailable through standard channels. While having these options may allow the user to utilize the device more effectively, many users do not understand that jailbreaking or rooting can potentially allow malware to bypass many of the device's built in security features. The balance of user experience versus corporate security needs to be carefully considered since all mobile platforms have seen an increase in malware attacks over the past year. Mobile devices now hold more personal and corporate data than ever before and have become a very appealing target for attackers. Overall, the best defense for an enterprise is to build an overarching mobile strategy that accounts for technical controls, non technical controls and the people in the environment. Considerations need to not only focus on solutions such as MDM, but also policies and procedures around common issues of BYOD, and user security awareness.

= Authors and Primary Editors =

Suktika Mukhopadhyay 
Brandon Clark 
Talha Tariq

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Mobile Jailbreaking Cheat Sheet

2013-03-09T05:41:21Z

Jeffrey Walton: Added " ... for persons who engage in noninfringing uses"

= Dangers of Jailbreaking and Rooting Mobile Devices (Cheat Sheet) =

==What is "jailbreaking" and "rooting"?==

iOS: Jailbreaking is the process of modifying iOS system kernels to allow file system read and write access. Most jailbreaking tools (and exploits) remove the limitations and security features built by the manufacturer Apple (the "jail") through the use of custom kernels, which make unauthorized modifications to the operating system. Almost all jailbreaking tools allow users to run code not approved and signed by Apple. This allows users to install additional applications, extensions and patches without the control of Apple’s App Store.

Android: Rooting is the process of gaining administrative or privileged access for the Android OS. As the Android OS is based on the Linux Kernel, rooting a device is analogous to gaining access to administrative, root user-equivalent, permissions on Linux. Unlike iOS, rooting is (usually) not required to run applications outside from the Android Market. Some carriers control this through operating system settings or device firmware. Rooting also enables the user to completely remove and replace the device's operating system.

==Why do they occur?==
iOS: Many users are lured into jailbreaking to take advantage of apps made available through third party app sources, such as Cydia, which are otherwise banned or not approved by Apple. There is an inherent risk in installing such applications as they are not quality controlled nor have they gone through the Apple approval and application approval process. Hence, they may contain vulnerable or malicious code that could allow the device to be compromised. Alternately, jailbreaking can allow users to enhance some built in functions on their device. For example, a jailbroken phone can be used with a different carrier than the one it was configured with, FaceTime can be used over a 3G connection, or the phone can be unlocked to be used internationally. More technically savvy users also perform jailbreaking to enable user interface customizations, preferences and features not available through the normal software interface. Typically, these functionalities are achieved by patching specific binaries in the operating system.
A debated purpose for jailbreaking in the iOS community is for installing pirated iOS applications. Jailbreaking proponents discourage this use, such as Cydia warning users of pirated software when they add a pirated software repository. However, repositories such as Hackulous promote pirated applications and the tools to pirate and distribute applications.

Android: Rooting Android devices allows users to gain access to additional hardware rights, backup utilities and direct hardware access. Additionally, rooting allows users to remove the pre-installed "bloatware", additional features that many carriers or manufacturers put onto devices, which can use considerable amounts of disk space and memory. Most users root their device to leverage a custom read only memory (ROM) developed by the Android Community, which brings distinctive capabilities that are not available through the official ROMs installed by the carriers. Custom ROMs also provide users an option to 'upgrade' the operating system and optimize the phone experience by giving users access to features, such as tethering, that are normally blocked or limited by carriers.

==What are the common tools used?==

iOS: Jailbreaking software can be categorized into two main groups:
#Tethered: Requires the device to be connected to a system in order to bypass the iBoot signature check for iOS devices. The iOS device needs to be connected or tethered to a computer system every time it has to reboot in order to access the jailbreak application, such as redsn0w, and boot correctly.
#Un-tethered: Requires connection for the initial jailbreak process and then all the software, such as sn0wbreeze and evasi0n, is on the device for future un-tethered reboots, without losing the jailbreak or the functionality of the phone.

Some common, but not all of the iOS jailbreaking tools are listed below:
*Absinthe
*blackra1n
*Corona
*greenpois0n
*JailbreakMe
*limera1n
*PwnageTool
*redsn0w
* evasi0n
*sn0wbreeze
*Spirit

A more comprehensive list of jailbreaking tools for iOS, exploits and kernel patches can be found on the iPhoneWiki website.

Android: There are various rooting software available for Android. Tools and processes vary depending on the user’s device. The process is usually to:
#Unlock the boot loader.
#Install a rooting application and / or flash a custom ROM through the recovery mode.

Not all of the above tasks are necessary and different toolkits are available for device specific rooting process. Custom ROMs are based on the hardware being used; examples of some are as follows:

CyanogenMod ROMs are one of the most popular aftermarket replacement firmware in the Android world. More comprehensive device specific firmwares, flashing guides, rooting tools and patch details can be referenced from the homepage.

ClockWorkMod is a custom recovery option for Android phones and tablets that allows you to perform several advanced recovery, restoration, installation and maintenance operations etc. Please refer to xda-developers for more details.

==Why can it be dangerous?==

The tools above can be broadly categorized in the following categories:
*Userland Exploits: Jailbroken access is only obtained within the user layer. For instance, a user may have root access, but is not able to change the boot process. These exploits can be patched with a firmware update.
*iBoot Exploit: Jailbroken access to user level and boot process. iBoot exploits can be patched with a firmware update.
*Bootrom Exploits: Jailbroken access to user level and boot process. Bootrom exploits cannot be patched with a firmware update. Hardware update of bootrom required to patch in such cases.

Some high level risks for rooting or jailbreaking devices are as follows:

===Technical Risks:===
#General Mobile
##Some jailbreaking methods leave SSH enabled with a well known default password (i.e. alpine) that attackers can use for Command & Control.
##Entire file system of a rooted or jailbroken device is vulnerable to a malicious user inserting or extracting files. This vulnerability is exploited by many malware programs, including Droid Kung Fu, Droid Dream and Ikee.
##Credentials to sensitive applications, such as banking or corporate applications, can be stolen using key logging, sniffing or other malicious software and then transmitted via the internet connection.
#iOS
##Applications on a jailbroken device run as root outside of the iOS sandbox. This can allow applications to access sensitive data contained in other apps or install malicious software negating sandboxing functionality.
##Jailbroken devices can allow a user to install and run self-signed applications. Since the apps do not go through the App Store, they are not reviewed by Apple. These apps may contain vulnerable or malicious code that can be used to exploit a device.
#Android
##Android users that change the permissions on their device to grant root access to applications increase security exposure to malicious applications and potential application flaws.
##3rd party Android application markets have been identified as hosting malicious applications with remote administrative (RAT) capabilities.

===Non-technical risks:===
#According to the Unted States Librarian of Congress (who issues Digital Millennium Copyright Act (DMCA) excemptions), jailbreaking or rooting of a smartphone is '''not''' deemed illegal in the US for persons who engage in noninfringing uses. The approval can provide some users with a false sense safety and jailbreaking or rooting as being harmless. Its noteworthy the Librarian does not apporve jailbreaking of tablets, however. Please see ''[http://www.theinquirer.net/inquirer/news/2220251/us-rules-jailbreaking-tablets-is-illegal US rules jailbreaking tablets is illegal]'' for a layman's analysis.

#Software updates cannot be immediately applied because doing so would remove the jailbreak. This leaves the device vulnerable to known, unpatched software vulnerabilities.
#Users can be tricked into downloading malicious software. For example, malware commonly uses the following tactics to trick users into downloading software.
##Apps will often advertise that they provide additional functionality or remove ads from popular apps but also contain malicious code.
##Some apps will not have any malicious code as part of the initial version of the app but subsequent "Updates" will insert malicious code.
#Manufacturers have determined that jailbreaking or rooting is a breach of the terms of use for the device and therefore voids the warranty. This can be an issue for the user if the device needs hardware repair or technical support (Note: a device can be restored and therefore it is not a major issue, unless hardware damage otherwise covered by the warranty prevents restoration).

What controls can be used to protect against it?
Before an organization chooses to implement a mobile solution in their environment they should conduct a thorough risk assessment. This risk assessment should include an evaluation of the dangers posed by jailbroken or rooted devices, which are inherently more vulnerable to malicious applications or vulnerabilities such as those listed in the OWASP Mobile Security Top Ten Risks. Once this has assessment has been completed, management can determine which risks to accept and which risks will require additional controls to mitigate. Below are a few examples of both technical and non-technical controls that an organization may use.

===Technical Controls:===

Some of the detective controls to monitor for jailbroken or rooted devices include:
#Identify 3rd party app stores (e.g., Cydia).
#Attempt to identify modified kernels by comparing certain system files that the application would have access to on a non jailbroken device to known good file hashes. This technique can serve as a good starting point for detection.
#Attempt to write a file outside of the application’s root directory. The attempt should fail for non-jailbroken devices.

Note: Most Mobile Device Management (MDM) solutions can perform these checks but require an application to be installed on the device.

===Non-Technical Controls:===

Organizations must understand the following key points when thinking about mobile security:
#Perform a risk assessment to determine risks associated with mobile device use are appropriately identified, prioritized and mitigated to reduce or manage risk at levels acceptable to management.
#Review application inventory listing on frequent basis to identify applications posing significant risk to the mobility environment.
#Technology solutions such as Mobile Device Management (MDM) or Mobile Application Management (MAM) should be only one part of the overall security strategy. High level considerations include:
##Policies and procedures.
##User awareness and user buy-in.
##Technical controls and platforms.
##Auditing, logging, and monitoring.
#While many organizations choose a Bring Your Own Device (BYOD) strategy, the risks and benefits need to be considered and addressed before such a strategy is put in place. For example, the organization may consider developing a support plan for the various devices and operating systems that could be introduced to the environment. Many organizations struggle with this since there are such a wide variety of devices, particularly Android devices.
#There is not a ‘one size fits all’ solution to mobile security. Different levels of security controls should be employed based on the sensitivity of data that is collected, stored, or processed on a mobile device or through a mobile application.
#User awareness and user buy-in are key. For consumers or customers, this could be a focus on privacy and how Personally Identifiable Information (PII) is handled. For employees, this could be a focus on Acceptable Use Agreements (AUA) as well as privacy for personal devices.

==Conclusion==

Jailbreaking and rooting tools, resources and processes are constantly updated and have made the process easier than ever for end-users. Many users are lured to jailbreak or root their device in order to gain more control over the device, upgrade their operating systems or install packages normally unavailable through standard channels. While having these options may allow the user to utilize the device more effectively, many users do not understand that jailbreaking or rooting can potentially allow malware to bypass many of the device's built in security features. The balance of user experience versus corporate security needs to be carefully considered since all mobile platforms have seen an increase in malware attacks over the past year. Mobile devices now hold more personal and corporate data than ever before and have become a very appealing target for attackers. Overall, the best defense for an enterprise is to build an overarching mobile strategy that accounts for technical controls, non technical controls and the people in the environment. Considerations need to not only focus on solutions such as MDM, but also policies and procedures around common issues of BYOD, and user security awareness.

= Authors and Primary Editors =

Suktika Mukhopadhyay 
Brandon Clark 
Talha Tariq

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Mobile Jailbreaking Cheat Sheet

2013-03-09T05:39:50Z

Jeffrey Walton: "deemed legal" -> "not deemed illegal". The register letter stated "...circumvention of technological measures... does not apply to persons who engage in noninfring ing uses...". "not illegal" seems closer to the register letter.

= Dangers of Jailbreaking and Rooting Mobile Devices (Cheat Sheet) =

==What is "jailbreaking" and "rooting"?==

iOS: Jailbreaking is the process of modifying iOS system kernels to allow file system read and write access. Most jailbreaking tools (and exploits) remove the limitations and security features built by the manufacturer Apple (the "jail") through the use of custom kernels, which make unauthorized modifications to the operating system. Almost all jailbreaking tools allow users to run code not approved and signed by Apple. This allows users to install additional applications, extensions and patches without the control of Apple’s App Store.

Android: Rooting is the process of gaining administrative or privileged access for the Android OS. As the Android OS is based on the Linux Kernel, rooting a device is analogous to gaining access to administrative, root user-equivalent, permissions on Linux. Unlike iOS, rooting is (usually) not required to run applications outside from the Android Market. Some carriers control this through operating system settings or device firmware. Rooting also enables the user to completely remove and replace the device's operating system.

==Why do they occur?==
iOS: Many users are lured into jailbreaking to take advantage of apps made available through third party app sources, such as Cydia, which are otherwise banned or not approved by Apple. There is an inherent risk in installing such applications as they are not quality controlled nor have they gone through the Apple approval and application approval process. Hence, they may contain vulnerable or malicious code that could allow the device to be compromised. Alternately, jailbreaking can allow users to enhance some built in functions on their device. For example, a jailbroken phone can be used with a different carrier than the one it was configured with, FaceTime can be used over a 3G connection, or the phone can be unlocked to be used internationally. More technically savvy users also perform jailbreaking to enable user interface customizations, preferences and features not available through the normal software interface. Typically, these functionalities are achieved by patching specific binaries in the operating system.
A debated purpose for jailbreaking in the iOS community is for installing pirated iOS applications. Jailbreaking proponents discourage this use, such as Cydia warning users of pirated software when they add a pirated software repository. However, repositories such as Hackulous promote pirated applications and the tools to pirate and distribute applications.

Android: Rooting Android devices allows users to gain access to additional hardware rights, backup utilities and direct hardware access. Additionally, rooting allows users to remove the pre-installed "bloatware", additional features that many carriers or manufacturers put onto devices, which can use considerable amounts of disk space and memory. Most users root their device to leverage a custom read only memory (ROM) developed by the Android Community, which brings distinctive capabilities that are not available through the official ROMs installed by the carriers. Custom ROMs also provide users an option to 'upgrade' the operating system and optimize the phone experience by giving users access to features, such as tethering, that are normally blocked or limited by carriers.

==What are the common tools used?==

iOS: Jailbreaking software can be categorized into two main groups:
#Tethered: Requires the device to be connected to a system in order to bypass the iBoot signature check for iOS devices. The iOS device needs to be connected or tethered to a computer system every time it has to reboot in order to access the jailbreak application, such as redsn0w, and boot correctly.
#Un-tethered: Requires connection for the initial jailbreak process and then all the software, such as sn0wbreeze and evasi0n, is on the device for future un-tethered reboots, without losing the jailbreak or the functionality of the phone.

Some common, but not all of the iOS jailbreaking tools are listed below:
*Absinthe
*blackra1n
*Corona
*greenpois0n
*JailbreakMe
*limera1n
*PwnageTool
*redsn0w
* evasi0n
*sn0wbreeze
*Spirit

A more comprehensive list of jailbreaking tools for iOS, exploits and kernel patches can be found on the iPhoneWiki website.

Android: There are various rooting software available for Android. Tools and processes vary depending on the user’s device. The process is usually to:
#Unlock the boot loader.
#Install a rooting application and / or flash a custom ROM through the recovery mode.

Not all of the above tasks are necessary and different toolkits are available for device specific rooting process. Custom ROMs are based on the hardware being used; examples of some are as follows:

CyanogenMod ROMs are one of the most popular aftermarket replacement firmware in the Android world. More comprehensive device specific firmwares, flashing guides, rooting tools and patch details can be referenced from the homepage.

ClockWorkMod is a custom recovery option for Android phones and tablets that allows you to perform several advanced recovery, restoration, installation and maintenance operations etc. Please refer to xda-developers for more details.

==Why can it be dangerous?==

The tools above can be broadly categorized in the following categories:
*Userland Exploits: Jailbroken access is only obtained within the user layer. For instance, a user may have root access, but is not able to change the boot process. These exploits can be patched with a firmware update.
*iBoot Exploit: Jailbroken access to user level and boot process. iBoot exploits can be patched with a firmware update.
*Bootrom Exploits: Jailbroken access to user level and boot process. Bootrom exploits cannot be patched with a firmware update. Hardware update of bootrom required to patch in such cases.

Some high level risks for rooting or jailbreaking devices are as follows:

===Technical Risks:===
#General Mobile
##Some jailbreaking methods leave SSH enabled with a well known default password (i.e. alpine) that attackers can use for Command & Control.
##Entire file system of a rooted or jailbroken device is vulnerable to a malicious user inserting or extracting files. This vulnerability is exploited by many malware programs, including Droid Kung Fu, Droid Dream and Ikee.
##Credentials to sensitive applications, such as banking or corporate applications, can be stolen using key logging, sniffing or other malicious software and then transmitted via the internet connection.
#iOS
##Applications on a jailbroken device run as root outside of the iOS sandbox. This can allow applications to access sensitive data contained in other apps or install malicious software negating sandboxing functionality.
##Jailbroken devices can allow a user to install and run self-signed applications. Since the apps do not go through the App Store, they are not reviewed by Apple. These apps may contain vulnerable or malicious code that can be used to exploit a device.
#Android
##Android users that change the permissions on their device to grant root access to applications increase security exposure to malicious applications and potential application flaws.
##3rd party Android application markets have been identified as hosting malicious applications with remote administrative (RAT) capabilities.

===Non-technical risks:===
#According to the Unted States Librarian of Congress (who issues Digital Millennium Copyright Act (DMCA) excemptions), jailbreaking or rooting of a smartphone is '''not''' deemed illegal in the US. The approval can provide some users with a false sense safety and jailbreaking or rooting as being harmless. Its noteworthy the Librarian does not apporve jailbreaking of tablets, however. Please see ''[http://www.theinquirer.net/inquirer/news/2220251/us-rules-jailbreaking-tablets-is-illegal US rules jailbreaking tablets is illegal]'' for a layman's analysis.

#Software updates cannot be immediately applied because doing so would remove the jailbreak. This leaves the device vulnerable to known, unpatched software vulnerabilities.
#Users can be tricked into downloading malicious software. For example, malware commonly uses the following tactics to trick users into downloading software.
##Apps will often advertise that they provide additional functionality or remove ads from popular apps but also contain malicious code.
##Some apps will not have any malicious code as part of the initial version of the app but subsequent "Updates" will insert malicious code.
#Manufacturers have determined that jailbreaking or rooting is a breach of the terms of use for the device and therefore voids the warranty. This can be an issue for the user if the device needs hardware repair or technical support (Note: a device can be restored and therefore it is not a major issue, unless hardware damage otherwise covered by the warranty prevents restoration).

What controls can be used to protect against it?
Before an organization chooses to implement a mobile solution in their environment they should conduct a thorough risk assessment. This risk assessment should include an evaluation of the dangers posed by jailbroken or rooted devices, which are inherently more vulnerable to malicious applications or vulnerabilities such as those listed in the OWASP Mobile Security Top Ten Risks. Once this has assessment has been completed, management can determine which risks to accept and which risks will require additional controls to mitigate. Below are a few examples of both technical and non-technical controls that an organization may use.

===Technical Controls:===

Some of the detective controls to monitor for jailbroken or rooted devices include:
#Identify 3rd party app stores (e.g., Cydia).
#Attempt to identify modified kernels by comparing certain system files that the application would have access to on a non jailbroken device to known good file hashes. This technique can serve as a good starting point for detection.
#Attempt to write a file outside of the application’s root directory. The attempt should fail for non-jailbroken devices.

Note: Most Mobile Device Management (MDM) solutions can perform these checks but require an application to be installed on the device.

===Non-Technical Controls:===

Organizations must understand the following key points when thinking about mobile security:
#Perform a risk assessment to determine risks associated with mobile device use are appropriately identified, prioritized and mitigated to reduce or manage risk at levels acceptable to management.
#Review application inventory listing on frequent basis to identify applications posing significant risk to the mobility environment.
#Technology solutions such as Mobile Device Management (MDM) or Mobile Application Management (MAM) should be only one part of the overall security strategy. High level considerations include:
##Policies and procedures.
##User awareness and user buy-in.
##Technical controls and platforms.
##Auditing, logging, and monitoring.
#While many organizations choose a Bring Your Own Device (BYOD) strategy, the risks and benefits need to be considered and addressed before such a strategy is put in place. For example, the organization may consider developing a support plan for the various devices and operating systems that could be introduced to the environment. Many organizations struggle with this since there are such a wide variety of devices, particularly Android devices.
#There is not a ‘one size fits all’ solution to mobile security. Different levels of security controls should be employed based on the sensitivity of data that is collected, stored, or processed on a mobile device or through a mobile application.
#User awareness and user buy-in are key. For consumers or customers, this could be a focus on privacy and how Personally Identifiable Information (PII) is handled. For employees, this could be a focus on Acceptable Use Agreements (AUA) as well as privacy for personal devices.

==Conclusion==

Jailbreaking and rooting tools, resources and processes are constantly updated and have made the process easier than ever for end-users. Many users are lured to jailbreak or root their device in order to gain more control over the device, upgrade their operating systems or install packages normally unavailable through standard channels. While having these options may allow the user to utilize the device more effectively, many users do not understand that jailbreaking or rooting can potentially allow malware to bypass many of the device's built in security features. The balance of user experience versus corporate security needs to be carefully considered since all mobile platforms have seen an increase in malware attacks over the past year. Mobile devices now hold more personal and corporate data than ever before and have become a very appealing target for attackers. Overall, the best defense for an enterprise is to build an overarching mobile strategy that accounts for technical controls, non technical controls and the people in the environment. Considerations need to not only focus on solutions such as MDM, but also policies and procedures around common issues of BYOD, and user security awareness.

= Authors and Primary Editors =

Suktika Mukhopadhyay 
Brandon Clark 
Talha Tariq

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Mobile Jailbreaking Cheat Sheet

2013-03-09T05:18:31Z

Jeffrey Walton: Clarified excemptions made by Congressal Librarian, cited reference

= Dangers of Jailbreaking and Rooting Mobile Devices (Cheat Sheet) =

==What is "jailbreaking" and "rooting"?==

iOS: Jailbreaking is the process of modifying iOS system kernels to allow file system read and write access. Most jailbreaking tools (and exploits) remove the limitations and security features built by the manufacturer Apple (the "jail") through the use of custom kernels, which make unauthorized modifications to the operating system. Almost all jailbreaking tools allow users to run code not approved and signed by Apple. This allows users to install additional applications, extensions and patches without the control of Apple’s App Store.

Android: Rooting is the process of gaining administrative or privileged access for the Android OS. As the Android OS is based on the Linux Kernel, rooting a device is analogous to gaining access to administrative, root user-equivalent, permissions on Linux. Unlike iOS, rooting is (usually) not required to run applications outside from the Android Market. Some carriers control this through operating system settings or device firmware. Rooting also enables the user to completely remove and replace the device's operating system.

==Why do they occur?==
iOS: Many users are lured into jailbreaking to take advantage of apps made available through third party app sources, such as Cydia, which are otherwise banned or not approved by Apple. There is an inherent risk in installing such applications as they are not quality controlled nor have they gone through the Apple approval and application approval process. Hence, they may contain vulnerable or malicious code that could allow the device to be compromised. Alternately, jailbreaking can allow users to enhance some built in functions on their device. For example, a jailbroken phone can be used with a different carrier than the one it was configured with, FaceTime can be used over a 3G connection, or the phone can be unlocked to be used internationally. More technically savvy users also perform jailbreaking to enable user interface customizations, preferences and features not available through the normal software interface. Typically, these functionalities are achieved by patching specific binaries in the operating system.
A debated purpose for jailbreaking in the iOS community is for installing pirated iOS applications. Jailbreaking proponents discourage this use, such as Cydia warning users of pirated software when they add a pirated software repository. However, repositories such as Hackulous promote pirated applications and the tools to pirate and distribute applications.

Android: Rooting Android devices allows users to gain access to additional hardware rights, backup utilities and direct hardware access. Additionally, rooting allows users to remove the pre-installed "bloatware", additional features that many carriers or manufacturers put onto devices, which can use considerable amounts of disk space and memory. Most users root their device to leverage a custom read only memory (ROM) developed by the Android Community, which brings distinctive capabilities that are not available through the official ROMs installed by the carriers. Custom ROMs also provide users an option to 'upgrade' the operating system and optimize the phone experience by giving users access to features, such as tethering, that are normally blocked or limited by carriers.

==What are the common tools used?==

iOS: Jailbreaking software can be categorized into two main groups:
#Tethered: Requires the device to be connected to a system in order to bypass the iBoot signature check for iOS devices. The iOS device needs to be connected or tethered to a computer system every time it has to reboot in order to access the jailbreak application, such as redsn0w, and boot correctly.
#Un-tethered: Requires connection for the initial jailbreak process and then all the software, such as sn0wbreeze and evasi0n, is on the device for future un-tethered reboots, without losing the jailbreak or the functionality of the phone.

Some common, but not all of the iOS jailbreaking tools are listed below:
*Absinthe
*blackra1n
*Corona
*greenpois0n
*JailbreakMe
*limera1n
*PwnageTool
*redsn0w
* evasi0n
*sn0wbreeze
*Spirit

A more comprehensive list of jailbreaking tools for iOS, exploits and kernel patches can be found on the iPhoneWiki website.

Android: There are various rooting software available for Android. Tools and processes vary depending on the user’s device. The process is usually to:
#Unlock the boot loader.
#Install a rooting application and / or flash a custom ROM through the recovery mode.

Not all of the above tasks are necessary and different toolkits are available for device specific rooting process. Custom ROMs are based on the hardware being used; examples of some are as follows:

CyanogenMod ROMs are one of the most popular aftermarket replacement firmware in the Android world. More comprehensive device specific firmwares, flashing guides, rooting tools and patch details can be referenced from the homepage.

ClockWorkMod is a custom recovery option for Android phones and tablets that allows you to perform several advanced recovery, restoration, installation and maintenance operations etc. Please refer to xda-developers for more details.

==Why can it be dangerous?==

The tools above can be broadly categorized in the following categories:
*Userland Exploits: Jailbroken access is only obtained within the user layer. For instance, a user may have root access, but is not able to change the boot process. These exploits can be patched with a firmware update.
*iBoot Exploit: Jailbroken access to user level and boot process. iBoot exploits can be patched with a firmware update.
*Bootrom Exploits: Jailbroken access to user level and boot process. Bootrom exploits cannot be patched with a firmware update. Hardware update of bootrom required to patch in such cases.

Some high level risks for rooting or jailbreaking devices are as follows:

===Technical Risks:===
#General Mobile
##Some jailbreaking methods leave SSH enabled with a well known default password (i.e. alpine) that attackers can use for Command & Control.
##Entire file system of a rooted or jailbroken device is vulnerable to a malicious user inserting or extracting files. This vulnerability is exploited by many malware programs, including Droid Kung Fu, Droid Dream and Ikee.
##Credentials to sensitive applications, such as banking or corporate applications, can be stolen using key logging, sniffing or other malicious software and then transmitted via the internet connection.
#iOS
##Applications on a jailbroken device run as root outside of the iOS sandbox. This can allow applications to access sensitive data contained in other apps or install malicious software negating sandboxing functionality.
##Jailbroken devices can allow a user to install and run self-signed applications. Since the apps do not go through the App Store, they are not reviewed by Apple. These apps may contain vulnerable or malicious code that can be used to exploit a device.
#Android
##Android users that change the permissions on their device to grant root access to applications increase security exposure to malicious applications and potential application flaws.
##3rd party Android application markets have been identified as hosting malicious applications with remote administrative (RAT) capabilities.

===Non-technical risks:===
#According to the Unted States Librarian of Congress (who issues Digital Millennium Copyright Act (DMCA) excemptions), jailbreaking or rooting of a smartphone is deemed 'legal' in the US. The approval can provide some users with a false sense safety and jailbreaking or rooting as being harmless. Its noteworthy the Librarian does not apporve jailbreaking of tablets, however. Please see ''[http://www.theinquirer.net/inquirer/news/2220251/us-rules-jailbreaking-tablets-is-illegal US rules jailbreaking tablets is illegal]'' for a layman's analysis.

#Software updates cannot be immediately applied because doing so would remove the jailbreak. This leaves the device vulnerable to known, unpatched software vulnerabilities.
#Users can be tricked into downloading malicious software. For example, malware commonly uses the following tactics to trick users into downloading software.
##Apps will often advertise that they provide additional functionality or remove ads from popular apps but also contain malicious code.
##Some apps will not have any malicious code as part of the initial version of the app but subsequent "Updates" will insert malicious code.
#Manufacturers have determined that jailbreaking or rooting is a breach of the terms of use for the device and therefore voids the warranty. This can be an issue for the user if the device needs hardware repair or technical support (Note: a device can be restored and therefore it is not a major issue, unless hardware damage otherwise covered by the warranty prevents restoration).

What controls can be used to protect against it?
Before an organization chooses to implement a mobile solution in their environment they should conduct a thorough risk assessment. This risk assessment should include an evaluation of the dangers posed by jailbroken or rooted devices, which are inherently more vulnerable to malicious applications or vulnerabilities such as those listed in the OWASP Mobile Security Top Ten Risks. Once this has assessment has been completed, management can determine which risks to accept and which risks will require additional controls to mitigate. Below are a few examples of both technical and non-technical controls that an organization may use.

===Technical Controls:===

Some of the detective controls to monitor for jailbroken or rooted devices include:
#Identify 3rd party app stores (e.g., Cydia).
#Attempt to identify modified kernels by comparing certain system files that the application would have access to on a non jailbroken device to known good file hashes. This technique can serve as a good starting point for detection.
#Attempt to write a file outside of the application’s root directory. The attempt should fail for non-jailbroken devices.

Note: Most Mobile Device Management (MDM) solutions can perform these checks but require an application to be installed on the device.

===Non-Technical Controls:===

Organizations must understand the following key points when thinking about mobile security:
#Perform a risk assessment to determine risks associated with mobile device use are appropriately identified, prioritized and mitigated to reduce or manage risk at levels acceptable to management.
#Review application inventory listing on frequent basis to identify applications posing significant risk to the mobility environment.
#Technology solutions such as Mobile Device Management (MDM) or Mobile Application Management (MAM) should be only one part of the overall security strategy. High level considerations include:
##Policies and procedures.
##User awareness and user buy-in.
##Technical controls and platforms.
##Auditing, logging, and monitoring.
#While many organizations choose a Bring Your Own Device (BYOD) strategy, the risks and benefits need to be considered and addressed before such a strategy is put in place. For example, the organization may consider developing a support plan for the various devices and operating systems that could be introduced to the environment. Many organizations struggle with this since there are such a wide variety of devices, particularly Android devices.
#There is not a ‘one size fits all’ solution to mobile security. Different levels of security controls should be employed based on the sensitivity of data that is collected, stored, or processed on a mobile device or through a mobile application.
#User awareness and user buy-in are key. For consumers or customers, this could be a focus on privacy and how Personally Identifiable Information (PII) is handled. For employees, this could be a focus on Acceptable Use Agreements (AUA) as well as privacy for personal devices.

==Conclusion==

Jailbreaking and rooting tools, resources and processes are constantly updated and have made the process easier than ever for end-users. Many users are lured to jailbreak or root their device in order to gain more control over the device, upgrade their operating systems or install packages normally unavailable through standard channels. While having these options may allow the user to utilize the device more effectively, many users do not understand that jailbreaking or rooting can potentially allow malware to bypass many of the device's built in security features. The balance of user experience versus corporate security needs to be carefully considered since all mobile platforms have seen an increase in malware attacks over the past year. Mobile devices now hold more personal and corporate data than ever before and have become a very appealing target for attackers. Overall, the best defense for an enterprise is to build an overarching mobile strategy that accounts for technical controls, non technical controls and the people in the environment. Considerations need to not only focus on solutions such as MDM, but also policies and procedures around common issues of BYOD, and user security awareness.

= Authors and Primary Editors =

Suktika Mukhopadhyay 
Brandon Clark 
Talha Tariq

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

Mobile Jailbreaking Cheat Sheet

2013-03-09T04:59:54Z

Jeffrey Walton: Added the newest family member: evasi0n

= Dangers of Jailbreaking and Rooting Mobile Devices (Cheat Sheet) =

==What is "jailbreaking" and "rooting"?==

iOS: Jailbreaking is the process of modifying iOS system kernels to allow file system read and write access. Most jailbreaking tools (and exploits) remove the limitations and security features built by the manufacturer Apple (the "jail") through the use of custom kernels, which make unauthorized modifications to the operating system. Almost all jailbreaking tools allow users to run code not approved and signed by Apple. This allows users to install additional applications, extensions and patches without the control of Apple’s App Store.

Android: Rooting is the process of gaining administrative or privileged access for the Android OS. As the Android OS is based on the Linux Kernel, rooting a device is analogous to gaining access to administrative, root user-equivalent, permissions on Linux. Unlike iOS, rooting is (usually) not required to run applications outside from the Android Market. Some carriers control this through operating system settings or device firmware. Rooting also enables the user to completely remove and replace the device's operating system.

==Why do they occur?==
iOS: Many users are lured into jailbreaking to take advantage of apps made available through third party app sources, such as Cydia, which are otherwise banned or not approved by Apple. There is an inherent risk in installing such applications as they are not quality controlled nor have they gone through the Apple approval and application approval process. Hence, they may contain vulnerable or malicious code that could allow the device to be compromised. Alternately, jailbreaking can allow users to enhance some built in functions on their device. For example, a jailbroken phone can be used with a different carrier than the one it was configured with, FaceTime can be used over a 3G connection, or the phone can be unlocked to be used internationally. More technically savvy users also perform jailbreaking to enable user interface customizations, preferences and features not available through the normal software interface. Typically, these functionalities are achieved by patching specific binaries in the operating system.
A debated purpose for jailbreaking in the iOS community is for installing pirated iOS applications. Jailbreaking proponents discourage this use, such as Cydia warning users of pirated software when they add a pirated software repository. However, repositories such as Hackulous promote pirated applications and the tools to pirate and distribute applications.

Android: Rooting Android devices allows users to gain access to additional hardware rights, backup utilities and direct hardware access. Additionally, rooting allows users to remove the pre-installed "bloatware", additional features that many carriers or manufacturers put onto devices, which can use considerable amounts of disk space and memory. Most users root their device to leverage a custom read only memory (ROM) developed by the Android Community, which brings distinctive capabilities that are not available through the official ROMs installed by the carriers. Custom ROMs also provide users an option to 'upgrade' the operating system and optimize the phone experience by giving users access to features, such as tethering, that are normally blocked or limited by carriers.

==What are the common tools used?==

iOS: Jailbreaking software can be categorized into two main groups:
#Tethered: Requires the device to be connected to a system in order to bypass the iBoot signature check for iOS devices. The iOS device needs to be connected or tethered to a computer system every time it has to reboot in order to access the jailbreak application, such as redsn0w, and boot correctly.
#Un-tethered: Requires connection for the initial jailbreak process and then all the software, such as sn0wbreeze and evasi0n, is on the device for future un-tethered reboots, without losing the jailbreak or the functionality of the phone.

Some common, but not all of the iOS jailbreaking tools are listed below:
*Absinthe
*blackra1n
*Corona
*greenpois0n
*JailbreakMe
*limera1n
*PwnageTool
*redsn0w
*sn0wbreeze
*Spirit

A more comprehensive list of jailbreaking tools for iOS, exploits and kernel patches can be found on the iPhoneWiki website.

Android: There are various rooting software available for Android. Tools and processes vary depending on the user’s device. The process is usually to:
#Unlock the boot loader.
#Install a rooting application and / or flash a custom ROM through the recovery mode.

Not all of the above tasks are necessary and different toolkits are available for device specific rooting process. Custom ROMs are based on the hardware being used; examples of some are as follows:

CyanogenMod ROMs are one of the most popular aftermarket replacement firmware in the Android world. More comprehensive device specific firmwares, flashing guides, rooting tools and patch details can be referenced from the homepage.

ClockWorkMod is a custom recovery option for Android phones and tablets that allows you to perform several advanced recovery, restoration, installation and maintenance operations etc. Please refer to xda-developers for more details.

==Why can it be dangerous?==

The tools above can be broadly categorized in the following categories:
*Userland Exploits: Jailbroken access is only obtained within the user layer. For instance, a user may have root access, but is not able to change the boot process. These exploits can be patched with a firmware update.
*iBoot Exploit: Jailbroken access to user level and boot process. iBoot exploits can be patched with a firmware update.
*Bootrom Exploits: Jailbroken access to user level and boot process. Bootrom exploits cannot be patched with a firmware update. Hardware update of bootrom required to patch in such cases.

Some high level risks for rooting or jailbreaking devices are as follows:

===Technical Risks:===
#General Mobile
##Some jailbreaking methods leave SSH enabled with a well known default password (i.e. alpine) that attackers can use for Command & Control.
##Entire file system of a rooted or jailbroken device is vulnerable to a malicious user inserting or extracting files. This vulnerability is exploited by many malware programs, including Droid Kung Fu, Droid Dream and Ikee.
##Credentials to sensitive applications, such as banking or corporate applications, can be stolen using key logging, sniffing or other malicious software and then transmitted via the internet connection.
#iOS
##Applications on a jailbroken device run as root outside of the iOS sandbox. This can allow applications to access sensitive data contained in other apps or install malicious software negating sandboxing functionality.
##Jailbroken devices can allow a user to install and run self-signed applications. Since the apps do not go through the App Store, they are not reviewed by Apple. These apps may contain vulnerable or malicious code that can be used to exploit a device.
#Android
##Android users that change the permissions on their device to grant root access to applications increase security exposure to malicious applications and potential application flaws.
##3rd party Android application markets have been identified as hosting malicious applications with remote administrative (RAT) capabilities.

===Non-technical risks:===
#Under the current Digital Millennium Copyright Act (DMCA), jailbreaking or rooting is termed as 'legal' in the US, which can provide some users with a false sense safety and jailbreaking or rooting as being harmless. Please refer to 'Rulemaking on Anticircumvention' for more details.
#Software updates cannot be immediately applied because doing so would remove the jailbreak. This leaves the device vulnerable to known, unpatched software vulnerabilities.
#Users can be tricked into downloading malicious software. For example, malware commonly uses the following tactics to trick users into downloading software.
##Apps will often advertise that they provide additional functionality or remove ads from popular apps but also contain malicious code.
##Some apps will not have any malicious code as part of the initial version of the app but subsequent "Updates" will insert malicious code.
#Manufacturers have determined that jailbreaking or rooting is a breach of the terms of use for the device and therefore voids the warranty. This can be an issue for the user if the device needs hardware repair or technical support (Note: a device can be restored and therefore it is not a major issue, unless hardware damage otherwise covered by the warranty prevents restoration).

What controls can be used to protect against it?
Before an organization chooses to implement a mobile solution in their environment they should conduct a thorough risk assessment. This risk assessment should include an evaluation of the dangers posed by jailbroken or rooted devices, which are inherently more vulnerable to malicious applications or vulnerabilities such as those listed in the OWASP Mobile Security Top Ten Risks. Once this has assessment has been completed, management can determine which risks to accept and which risks will require additional controls to mitigate. Below are a few examples of both technical and non-technical controls that an organization may use.

===Technical Controls:===

Some of the detective controls to monitor for jailbroken or rooted devices include:
#Identify 3rd party app stores (e.g., Cydia).
#Attempt to identify modified kernels by comparing certain system files that the application would have access to on a non jailbroken device to known good file hashes. This technique can serve as a good starting point for detection.
#Attempt to write a file outside of the application’s root directory. The attempt should fail for non-jailbroken devices.

Note: Most Mobile Device Management (MDM) solutions can perform these checks but require an application to be installed on the device.

===Non-Technical Controls:===

Organizations must understand the following key points when thinking about mobile security:
#Perform a risk assessment to determine risks associated with mobile device use are appropriately identified, prioritized and mitigated to reduce or manage risk at levels acceptable to management.
#Review application inventory listing on frequent basis to identify applications posing significant risk to the mobility environment.
#Technology solutions such as Mobile Device Management (MDM) or Mobile Application Management (MAM) should be only one part of the overall security strategy. High level considerations include:
##Policies and procedures.
##User awareness and user buy-in.
##Technical controls and platforms.
##Auditing, logging, and monitoring.
#While many organizations choose a Bring Your Own Device (BYOD) strategy, the risks and benefits need to be considered and addressed before such a strategy is put in place. For example, the organization may consider developing a support plan for the various devices and operating systems that could be introduced to the environment. Many organizations struggle with this since there are such a wide variety of devices, particularly Android devices.
#There is not a ‘one size fits all’ solution to mobile security. Different levels of security controls should be employed based on the sensitivity of data that is collected, stored, or processed on a mobile device or through a mobile application.
#User awareness and user buy-in are key. For consumers or customers, this could be a focus on privacy and how Personally Identifiable Information (PII) is handled. For employees, this could be a focus on Acceptable Use Agreements (AUA) as well as privacy for personal devices.

==Conclusion==

Jailbreaking and rooting tools, resources and processes are constantly updated and have made the process easier than ever for end-users. Many users are lured to jailbreak or root their device in order to gain more control over the device, upgrade their operating systems or install packages normally unavailable through standard channels. While having these options may allow the user to utilize the device more effectively, many users do not understand that jailbreaking or rooting can potentially allow malware to bypass many of the device's built in security features. The balance of user experience versus corporate security needs to be carefully considered since all mobile platforms have seen an increase in malware attacks over the past year. Mobile devices now hold more personal and corporate data than ever before and have become a very appealing target for attackers. Overall, the best defense for an enterprise is to build an overarching mobile strategy that accounts for technical controls, non technical controls and the people in the environment. Considerations need to not only focus on solutions such as MDM, but also policies and procedures around common issues of BYOD, and user security awareness.

= Authors and Primary Editors =

Suktika Mukhopadhyay 
Brandon Clark 
Talha Tariq

= Other Cheatsheets =
{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T04:55:08Z

Jeffrey Walton: Fixed markup

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your program. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug build present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. If you don't use <tt>/Wall</tt>, Microsoft recomends using <tt>/W4</tt> and enabling C4191, C4242, C4263, C4264, C4265, C4266, C4302, C4826, C4905, C4906, and C4928. Finally, <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'', ''[http://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx “Off By Default” Compiler Warnings in Visual C++]'', and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Options Summary]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T04:53:41Z

Jeffrey Walton: Added Microsoft warnings C4191, C4242, C4263, C4264, C4265, C4266, C4302, C4826, C4905, C4906, and C4928

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your program. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug build present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. If you don't use <tt>/Wall</tt>, Microsoft recomends using </W4> and enabling C4191, C4242, C4263, C4264, C4265, C4266, C4302, C4826, C4905, C4906, and C4928. Finally, <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'', ''[http://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx “Off By Default” Compiler Warnings in Visual C++]'', and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Options Summary]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T04:45:04Z

Jeffrey Walton: Code -> Program

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your program. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug build present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'', ''[http://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx “Off By Default” Compiler Warnings in Visual C++]'', and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Options Summary]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T04:41:22Z

Jeffrey Walton: Improved references

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your code. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug build present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'', ''[http://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx “Off By Default” Compiler Warnings in Visual C++]'', and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Options Summary]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T04:32:01Z

Jeffrey Walton: Improved flow

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, integration, static analysis, and platform security. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed by backup or sync. If your default configuration includes a logging level of ten or ''maximum verbosity'', you probably lack stability and are trying to track problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when operating in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your code. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries. A well integrated library can compliment your code, and a poorlly written library can detract from your program.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug build present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC, and the flags include <tt>-Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor</tt> and possibly <tt>-Weffc++</tt>. Finally, Objective C should include <tt>-Wstrict-selector-match</tt> and <tt>-Wundeclared-selector</tt>.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T03:29:05Z

Jeffrey Walton: Moved some platform security flags from 'static Anlysis' to 'Platform Security'; Improved flow

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed. If your default configuration includes a logging level of ten or ''Maximum Verbosity'', you are probably trying to track down problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want to be as close to production as possible, so you should be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when used in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your code. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug build present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. C++ presents additional opportunities under GCC. The additional flags include: -Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor and possibly -Weffc++. Finally, Objective C should include -Wstrict-selector-match and -Wundeclared-selector.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, and <tt>/analyze</tt>. <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Android's Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), -fstack-protector-all (or -fstack-protector), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. If available, you should also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> (the last two should be used in debug configurations). <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exec heaps, you should also use <tt>-z,noexecheap</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, <tt>/GS</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), use of stack cookies, and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening Cheat Sheet

2013-03-09T02:26:49Z

Jeffrey Walton: Created page with "C-Based Toolchain Hardening Cheat Sheet is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C lang..."

[[C-Based Toolchain Hardening Cheat Sheet]] is a brief treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

For those who would like a deeper treatment of the subject matter, please visit [[C-Based_Toolchain_Hardening|C-Based Toolchain Hardening]].

== Actionable Items ==

The [[C-Based Toolchain Hardening Cheat Sheet]] calls for the following actionable items:

* Provide debug, release, and test configurations
* Provide an assert with useful behavior
* Configure code to take advantage of configurations
* Properly integrate third party libraries
* Use the compiler's built-in static analysis capabilities
* Integrate with platform security measures

The remainder of this cheat sheet briefly explains the bulleted, actionable items. For a thorough treatment, please visit the [[C-Based_Toolchain_Hardening|full article]].

== Build Configurations ==

You should support three build configurations. First is ''Debug'', second is ''Release'', and third is ''Test''. One size does '''not''' fit all, and each speaks to a different facet of the engineering process. Because tools like Autconfig and Automake [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html do not support the notion of build configurations], you should prefer to work in an Integrated Develop Environments (IDE) or write your makefiles so the desired targets are supported. In addition, Autconfig and Automake often ignores user supplied flags (it depends on the folks writing the various scripts and templates), so you might find it easier to again write a makefile from scratch rather than retrofitting existing auto tool files.

=== Debug Builds ===

Debug is used during development, and the build assists you in finding problems in the code. During this phase, you develop your program and test integration with third party libraries you program depends upon. To help with debugging and diagnostics, you should define <tt>DEBUG</tt> and <tt>_DEBUG</tt> (if on a Windows platform) preprocessor macros and supply other 'debugging and diagnostic' oriented flags to the compiler and linker. Additional preprocessor macros for selected libraries are offered in the [[C-Based_Toolchain_Hardening|full article]].

You should use the following for GCC when building for debug: <tt>-O0</tt> (or <tt>-O1</tt>) and <tt>-g3</tt> <tt>-ggdb</tt>. No optimizations improve debuggability because optimizations often rearrange statements to improve instruction scheduling and remove unneeded code. You may need <tt>-O1</tt> to ensure some analysis is performed. <tt>-g3</tt> ensures maximum debug information is available, including symbolic constants and <tt>#defines</tt>.

Asserts will help you write self debugging programs. The program will alert you to the point of first failure quickly and easily. Because asserts are so powerful, the code should be completely and full instrumented with asserts that: (1) validates and asserts all program state relevant to a function or a method; (2) validates and asserts all function parameters; and (3) validates and asserts all return values for functions or methods which return a value. Because of item (3), you should be very suspicious of void functions that cannot convey failures.

Anywhere you have an <tt>if</tt> statement for validation, you should have an assert. Anywhere you have an assert, you should have an <tt>if</tt> statement. They go hand-in-hand. Posix states if <tt>NDEBUG</tt> is '''not''' defined, then <tt>assert</tt> [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html "shall write information about the particular call that failed on stderr and shall call abort"]. Calling abort during development is useless behavior, so you must supply your own assert that <tt>SIGTRAP</tt>s. A Unix and Linux example of a <tt>SIGTRAP</tt> based assert is provided in the [[C-Based_Toolchain_Hardening|full article]].

Unlike other debugging and diagnostic methods - such as breakpoints and <tt>printf</tt> - asserts stay in forever and become silent guardians. If you accidentally nudge something in an apparently unrelated code path, the assert will snap the debugger for you. The enduring coverage means debug code - with its additional diagnostics and instrumentation - is more highly valued than unadorned release code. If code is checked in that does not have the additional debugging and diagnostics, including full assertions, you should reject the check-in.

=== Release Builds ===

Release builds are diametrically opposed to debug configurations. In a release configuration, the program will be built for use in production. Your program is expected to operate correctly, securely and efficiently. The time for debugging and diagnostics is over, and your program will define <tt>NDEBUG</tt> to remove the supplemental information and behavior.

A release configuration should also use <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. The optimizations will make it somewhat more difficult to make sense of a stack trace, but they should be few and far between. The <tt>-g''N''</tt> flag ensures debugging information is available for post mortem analysis. While you generate debugging information for release builds, you should strip the information before shipping and check the symbols into you version control system along with the tagged build.

<tt>NDEBUG</tt> will also remove asserts from your program by defining them to <tt>void</tt> since its not acceptable to crash via <tt>abort</tt> in production. You should not depend upon assert for crash report generation because those reports could contain sensitive information and may end up on foreign systems, including for example, [http://msdn.microsoft.com/en-us/library/windows/hardware/gg487440.aspx Windows Error Reporting]. If you want a crash dump, you should generate it yourself in a controlled manner while ensuring no sensitive information is written or leaked.

Release builds should also curtail logging. If you followed earlier guidance, you have properly instrumented code and can determine the point of first failure quickly and easily. Simply log the failure and and relevant parameters. Remove all <tt>NSLog</tt> and similar calls because sensitive information might be logged to a system logger. Worse, the data in the logs might be egressed. If your default configuration includes a logging level of ten or ''Maximum Verbosity'', you are probably trying to track down problems in the field. That usually means your program or library is not ready for production.

=== Test Builds ===

A Test build is closely related to a release build. In this build configuration, you want as close to production as possible, so you be using <tt>-O2</tt>/<tt>-O3</tt>/<tt>-Os</tt> and <tt>-g1</tt>/<tt>-g2</tt>. You will run your suite of ''positive'' and ''negative'' tests against the test build.

You will also want to exercise all functions or methods provided by the program and not just the public interfaces, so everything should be made public. For example, all member functions public (C++ classes), all selectors (Objective C), all methods (Java), and all interfaces (library or shared object) should be made available for testing. As such, you should:

* Add <tt>-Dprotected=public -Dprivate=public</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>
* Change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>

Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

You should also concentrate on negative tests. Positive self tests are relatively useless except for functional and regression tests. Since this is your line of business or area of expertise, you should have the business logic correct when used in a benign environment. A hostile or toxic environment is much more interesting, and that's where you want to know how your library or program will fail in the field when under attack.

== Library Integration ==

You must properly integrate and utilize libraries in your code. Proper integration includes acceptance testing, configuring for your build system, identifying libraries you ''should'' be using, and correctly using the libraries.

Acceptance testing a library is practically non-existent. The testing can be a simple code review or can include additional measures, such as negative self tests. If the library is defective or does not meet standards, you must fix it or reject the library. An example of lack of acceptance testing is [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library], which resulted in [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525]. Another example is the 10's to 100's of millions of vulnerable embedded devices due to defects in <tt>libupnp</tt>. While its popular to lay blame on others, the bottom line is you chose the library so you are responsible for it.

You must also ensure the library is integrated into your build process. For example, the OpenSSL library should be configured '''without''' SSLv2, SSLv3 and compression since they are defective. That means <tt>config</tt> should be executed with <tt>-no-comp</tt> <tt>-no-sslv2</tt> and <tt>-no-sslv3</tt>. As an additional example, using STLPort your debug configuration should also define <tt>_STLP_DEBUG=1</tt>, <tt>_STLP_USE_DEBUG_LIB=1</tt>, <tt>_STLP_DEBUG_ALLOC=1</tt>, <tt>_STLP_DEBUG_UNINITIALIZED=1</tt> because the library offers the additional diagnostics during development.

Debug build present an opportunity to use additional libraries to help locate problems in the code. For example, you should be using a memory checker such as ''Debug Malloc Library (Dmalloc)'' during development. If you are not using Dmalloc, then ensure you have an equivalent checker, such as GCC 4.8's <tt>-fsanitize=memory</tt>. This is one area where one size clearly does not fit all.

Using a library properly is always difficult, especially when there is no documentation. Review any hardening documents available for the library, and be sure to visit the library's documentation to ensure proper API usage. If required, you might have to review code or step library code under the debugger to ensure there are no bugs or undocumented features.

== Static Analysis ==

Compiler writers do a fantastic job of generating object code from source code. The process creates a lot of additional information useful in analyzing code. Compilers use the analysis to offer programmers warnings to help detect problems in their code, but the catch is you have to ask for them. After you ask for them, you should take time to understand what the underlying issue is when a statement is flagged. For example, compilers will warn you when comparing a signed integer to an unsigned integer because <tt>-1 > 1</tt> after C/C++ promotion. At other times, you will need to back off some warnings to help separate the wheat from the chaff. For example, interface programming is a popular C++ paradigm, so <tt>-Wno-unused-parameter</tt> will probably be helpful with C++ code.

You should consider a clean compile as a security gate. If you find its painful to turn warnings on, then you have likely been overlooking some of the finer points in the details. In addition, you should strive for multiple compilers and platforms support since each has its own personality (and interpretation of the C/C++ standards). By the time your core modules clean compile under Clang, GCC, ICC, and Visual Studio on the Linux and Windows platforms, your code will have many stability obstacles removed.

When compiling programs with GCC, you should use the following flags to help detect errors in your programs. The options should be added to <tt>CFLAGS</tt> for a program with C source files, and <tt>CXXFLAGS</tt> for a program with C++ source files. Objective C developers should add their warnings to <tt>CFLAGS</tt>: <tt>-Wall -Wextra -Wconversion (or -Wsign-conversion), -Wcast-align, -Wformat=2 -Wformat-security, -fno-common, -fstack-protector-all (or -fstack-protector), -Wmissing-prototypes, -Wmissing-declarations, -Wstrict-prototypes, -Wstrict-overflow, and -Wtrampolines</tt>. If available, also use <tt>_FORTIFY_SOURCES=2</tt> (or <tt>_FORTIFY_SOURCES=1</tt> on Android 4.2), <tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt>.

C++ presents additional opportunities under GCC. The additional flags include: -Woverloaded-virtual, -Wreorder, -Wsign-promo, -Wnon-virtual-dtor and possibly -Weffc++. Finally, Objective C should include -Wstrict-selector-match and -Wundeclared-selector.

For a Microsoft platform, you should use: <tt>/W4</tt>, <tt>/Wall</tt>, <tt>/GS</tt>, and <tt>/analyze</tt>. <tt>/analyze</tt> is Enterprise Code Analysis, which is freely available with the [http://www.microsoft.com/en-us/download/details.aspx?id=24826 Windows SDK for Windows Server 2008 and .NET Framework 3.5 SDK] (you don't need Visual Studio Enterprise edition).

== Platform Security ==

Integrating with platform security is essential to a defensive posture. Platform security will be your safety umbrella if someone discovers a bug with security implications - and you should always have it with you. For example, if your parser fails, then no-execute stacks and heaps can turn a 0-day into an annoying crash. Not integrating often leaves your users and customers vulnerable to malicious code. See, for example, ''[http://www.kb.cert.org/vuls/id/922681 Portable SDK for UPnP Devices (libupnp) contains multiple buffer overflows in SSDP]'' and ''[https://developer.pidgin.im/ticket/15209 Pidgin for Windows - Missing DEP and ASLR]'').

When integrating with platform security on a Linux host, you should use the following flags: <tt>-fPIE</tt> (compiler) and <tt>-pie</tt> (linker), <tt>-z,noexecstack</tt>, <tt>-z,now</tt>, <tt>-z,relro</tt>. <tt>-z,nodlopen</tt> and <tt>-z,nodump</tt> might help in reducing an attacker's ability to load and manipulate a shared object. On Gentoo and other systems with no-exe heaps, you should also use <tt>-z,noexecheap</tt>. While you may not be familiar with some of the flags, you are probably familiar with the effects of omitting them. For example, Gingerbreak overwrote the Global Offset Table (GOT) in the ELF headers, and could have been avoided with <tt>-z,relro</tt>.

Windows programs should include <tt>/dynamicbase</tt>, <tt>/NXCOMPAT</tt>, and <tt>/SafeSEH</tt> to ensure address space layout randomizations (ASLR), data execution prevention (DEP), and thwart exception handler overwrites.

For additional details on the GCC and Windows options and flags, see ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html GCC Options to Request or Suppress Warnings]'' and ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]''.

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

== Other Cheat sheets ==

{{Cheatsheet_Navigation}}

[[Category:Cheatsheets]]

C-Based Toolchain Hardening

2013-03-08T18:55:31Z

Jeffrey Walton:

[[C-Based Toolchain Hardening]] is a treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at configuration and build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

This is a prescriptive article, and it will not debate semantics or speculate on behavior. Some information, such as the C/C++ committee's motivation and pedigree for [https://groups.google.com/a/isocpp.org/forum/?fromgroups=#!topic/std-discussion/ak8e1mzBhGs "program diagnostics", <tt>NDEBUG</tt>, <tt>assert</tt>, and <tt>abort()</tt>], appears to be lost like a tale in the Lord of the Rings. As such, the article will specify semantics (for example, the philosophy of 'debug' and 'release' build configurations), assign behaviors (for example, what an assert should do in a 'debug' and 'release' build configurations), and present a position. If you find the posture is too aggressive, then you should back off as required to suite your taste.

A secure toolchain is not a silver bullet. It is one piece of an overall strategy in the engineering process to help ensure success. It will compliment existing processes such as static analysis, dynamic analysis, secure coding, negative test suites, and the like. Tools such as Valgrind and Helgrind will still be needed. And a project will still require solid designs and architectures.

The OWASP [http://code.google.com/p/owasp-esapi-cplusplus/source ESAPI C++] project eats its own dog food. Many of the examples you will see in this article come directly from the ESAPI C++ project.

Finally, a [[Category:Cheat Sheet|cheat sheet]] is available for those who desire a terse treatment of the material. Please visit [[C-Based_Toolchain_Hardening_Cheat_Sheet|C-Based Toolchain Hardening Cheat Sheet]] for the abbreviated version.

== Wisdom ==

Code '''must''' be correct. It '''should''' be secure. It '''can''' be efficient.

[http://en.wikipedia.org/wiki/Jon_Bentley Dr. Jon Bentley]: ''"If it doesn't have to be correct, I can make it as fast as you'd like it to be"''.

[http://en.wikipedia.org/wiki/Gary_McGraw Dr. Gary McGraw]: ''"Thou shalt not rely solely on security features and functions to build secure software as security is an emergent property of the entire system and thus relies on building and integrating all parts properly"''.

== Configuration ==

Configuration is the first opportunity to configure your project for success. Not only do you have to configure your project to meet reliability and security goals, you must also configure integrated libraries properly. You typically have has three choices. First, you can use auto-configuration utilities if on Linux or Unix. Second, you can write a makefile by hand. This is predominant on Linux, Mac OS X, and Unix, but it applies to Windows as well. Finally, you can use an integrated development environment or IDE.

=== Build Configurations ===

At this stage in the process, you should concentrate on configuring for two builds: Debug and Release. Debug will be used for development and include full instrumentation. Release will be configured for production. The difference between the two settings is usually ''optimization level'' and ''debug level''. A third build configuration is Test, and its usually a special case of Release.

For debug and release builds, the settings are typically diametrically opposed. Debug configurations have no optimizations and full debug information; while Release builds have optimizations and minimal to moderate debug information. In addition, debug code has full assertions and additional library integration, such as mudflaps and malloc guards such as <tt>dmalloc</tt>.

The Test configuration is often a Release configuration that makes everything public for testing and builds a test harness. For example, all member functions public (C++ class) and all interfaces (library or shared object) should be made available for testing. Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

[http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8] introduced an optimization of <tt>-Og</tt>. Note that it is only an optimization, and still requires a customary debug level via <tt>-g</tt>.

==== Debug Builds ====

Debug builds are where developers spend most of their time when vetting problems, so this build should concentrate forces and tools or be a 'force multiplier'. Though many do not realize, debug code is more highly valued than release code because its adorned with additional instrumentation. The debug instrumentation will cause a program to become nearly "self-debugging", and help you catch mistakes such as bad parameters, failed API calls, and memory problems.

Self-debugging code reduces your time during trouble shooting and debugging. Reducing time under the debugger means you have more time for development and feature requests. If code is checked in without debug instrumentation, it should be fixed by adding instrumentation or rejected.

For GCC, optimizations and debug symbolication are controlled through two switches: <tt>-O</tt> and <tt>-g</tt>. You should use the following as part of your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for a minimal debug session:

<pre>-O0 -g3 -ggdb</pre>

<tt>-O0</tt> turns off optimizations and <tt>-g3</tt> ensures maximum debug information is available. You may need to use <tt>-O1</tt> so some analysis is performed. Otherwise, your debug build will be missing a number of warnings not present in release builds. <tt>-g3</tt> ensures maximum debugging information is available for the debug session, including symbolic constants and <tt>#defines</tt>. <tt>-ggdb</tt> includes extensions to help with a debug session under GDB. For completeness, Jan Krachtovil stated <tt>-ggdb</tt> currently has no effect in a private email.

Debug build should also define <tt>DEBUG</tt>, and ensure <tt>NDEBUG</tt> is not defined. <tt>NDEBUG</tt> removes "program diagnostics"; and has undesirable behavior and side effects which discussed below in more detail. The defines should be present for all code, and not just the program. You use it for all code (your program and included libraries) because you need to know how they fail too (remember, you take the bug report - not the third party library).

In addition, you should also use other relevant flags, such as <tt>-fno-omit-frame-pointer</tt> and <tt>-fsanitize=address</tt>. Finally, you should also ensure your project includes additional diagnostic libraries, such as <tt>dmalloc</tt>. The additional flags and libraries are discussed below in more detail.

==== Release Builds ====

Release builds are what your customer receives. They are meant to be run on production hardware and servers, and they should be reliable, secure, and efficient. A stable release build is the product of the hard work and effort during development.

For release builds, you should use the following as part of <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for release builds:

<pre>-On -g2</pre>

<tt>-O''n''</tt> sets optimizations for speed or size (for example, <tt>-Os</tt> or <tt>-O2</tt>), and <tt>-g2</tt> ensure debugging information is created.

Debugging information should be stripped and retained in case of symbolication for a crash report from the field. While not desired, debug information can be left in place without a performance penalty. See ''[http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]'' for details.

Release builds should also define <tt>NDEBUG</tt>, and ensure <tt>DEBUG</tt> is not defined. The time for debugging and diagnostics is over, so users get production code with full optimizations, no "programming diagnostics", and other efficiencies. If you can't optimize or your are performing excessive logging, it usually means the program is not ready for production.

If you have been relying on an <tt>assert</tt> and then a subsequent <tt>abort()</tt>, you have been abusing "program diagnostics" since it has no place in production code. If you want a memory dump, create one so users don't have to worry about secrets and other sensitive information being written to the filesystem and emailed in plain text.

For Windows, you would use <tt>/Od</tt> for debug builds; and <tt>/Ox</tt>, <tt>/O2</tt> or <tt>/Os</tt> for release builds. See Microsoft's [http://msdn.microsoft.com/en-us/library/k1ack8f1.aspx /O Options (Optimize Code)] for details.

==== Test Builds ====

Test builds are used to provide heuristic validation by way of positive and negative test suites. Under a test configuration, all interfaces are tested to ensure they perform to specification and satisfaction. "Satisfaction" is subjective, but it should include no crashing and no trashing of your memory arena, even when faced with negative tests.

Because all interfaces are tested (and not just the public ones), your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> should include:

<pre>-Dprotected=public -Dprivate=public</pre>

You should also change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>.

Nearly everyone gets a positive test right, so no more needs to be said. The negative self tests are much more interesting, and you should concentrate on trying to make your program fail so you can verify its fails gracefully. Remember, a bad guy is not going to be courteous when he attempts to cause your program to fail. And its your project that takes egg on the face by way of a bug report or guest appearance on [http://www.grok.org.uk/full-disclosure/ Full Disclosure] or [http://www.securityfocus.com/archive Bugtraq] - not ''<nowiki><some library></nowiki>'' you included.

=== Auto Tools ===

Auto configuration tools are popular on many Linux and Unix based systems, and the tools include ''Autoconf'', ''Automake'', ''config'', and ''Configure''. The tools work together to produce project files from scripts and template files. After the process completes, your project should be setup and ready to be made with <tt>make</tt>.

When using auto configuration tools, there are a few files of interest worth mentioning. The files are part of the auto tools chain and include <tt>m4</tt> and the various <tt>*.in</tt>, <tt>*.ac</tt> (autoconf), and <tt>*.am</tt> (automake) files. At times, you will have to open them, or the resulting makefiles, to tune the "stock" configuration.

There are three downsides to the command line configuration tools in the toolchain: (1) they often ignore user requests, (2) they cannot create configurations, and (3) security is often not a goal.

To demonstrate the first issue, confider your project with the following: <tt>configure CFLAGS="-Wall -fPIE" CXXFLAGS="-Wall -fPIE" LDFLAGS="-pie"</tt>. You will probably find the auto tools ignored your request, which means the command below will not produce expected results. As a work around, you will have to open an <tt>m4</tt> scripts, <tt>Makefile.in</tt> or <tt>Makefile.am</tt> and fix the configuration.

<pre>$ configure CFLAGS="-Wall -Wextra -Wconversion -fPIE -Wno-unused-parameter
-Wformat=2 -Wformat-security -fstack-protector-all -Wstrict-overflow"
LDFLAGS="-pie -z,noexecstack -z,noexecheap -z,relro -z,now"</pre>

For the second point, you will probably be disappointed to learn [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html Automake does not support the concept of configurations]. Its not entirely Autoconf's or Automake's fault - ''Make'' and its inability to detect changes is the underlying problem. Specifically, ''Make'' only [http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html checks modification times of prerequisites and targets], and does not check things like <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>. The net effect is you will not receive expected results when you issue <tt>make debug</tt> and then <tt>make test</tt> or <tt>make release</tt>.

Finally, you will probably be disappointed to learn tools such as Autoconf and Automake miss many security related opportunities and ship insecure out of the box. There are a number of compiler switches and linker flags that improve the defensive posture of a program, but they are not 'on' by default. Tools like Autoconf - which are supposed to handle this situation - often provides setting to serve the lowest of all denominators.

A recent discussion on the Automake mailing list illuminates the issue: ''[https://lists.gnu.org/archive/html/autoconf/2012-12/msg00038.html Enabling compiler warning flags]''. Attempts to improve default configurations were met with resistance and no action was taken. The resistance is often of the form, "<nowiki><some useful warning></nowiki> also produces false positives" or "<nowiki><some obscure platform></nowiki> does not support <nowiki><established security feature></nowiki>". Its noteworthy that David Wheeler, the author of ''[http://www.dwheeler.com/secure-programs/ Secure Programming for Linux and Unix HOWTO]'', was one of the folks trying to improve the posture.

=== Makefiles ===

Make is one of the earliest build systems dating back to the 1970s. Its available on Linux, Mac OS X and Unix, so you will frequently encounter projects using it. Unfortunately, Make has a number of short comings (''[http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful]'' and ''[http://www.conifersystems.com/whitepapers/gnu-make/ What’s Wrong With GNU make?]''), and can cause some discomfort. Despite issues with Make, ESAPI C++ uses Make primarily for three reasons: first, its omnipresent; second, its easier to manage than the Auto Tools family; and third, <tt>libtool</tt> was out of the question.

Consider what happens when you: (1) type <tt>make debug</tt>, and then type <tt>make release</tt>. Each build would require different <tt>CFLAGS</tt> due to optimizations and level of debug support. In your makefile, you would extract the relevant target and set <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> similar to below (taken from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/Makefile ESAPI C++ Makefile]):

<pre># Makefile
DEBUG_GOALS = $(filter $(MAKECMDGOALS), debug)
ifneq ($(DEBUG_GOALS),)
WANT_DEBUG := 1
WANT_TEST := 0
WANT_RELEASE := 0
endif
…

ifeq ($(WANT_DEBUG),1)
ESAPI_CFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
ESAPI_CXXFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
endif

ifeq ($(WANT_RELEASE),1)
ESAPI_CFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
ESAPI_CXXFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
endif

ifeq ($(WANT_TEST),1)
ESAPI_CFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
ESAPI_CXXFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
endif
…

# Merge ESAPI flags with user supplied flags. We perform the extra step to ensure
# user options follow our options, which should give user option's a preference.
override CFLAGS := $(ESAPI_CFLAGS) $(CFLAGS)
override CXXFLAGS := $(ESAPI_CXXFLAGS) $(CXXFLAGS)
override LDFLAGS := $(ESAPI_LDFLAGS) $(LDFLAGS)
…</pre>

Make will first build the program in a debug configuration for a session under the debugger using a rule similar to:

<pre>%.cpp:%.o:
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@</pre>

When you want the release build, Make will do nothing because it considers everything up to date despite the fact <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> have changed. Hence, your program will actually be in a debug configuration and risk a <tt>SIGABRT</tt> at runtime because debug instrumentation is present (recall <tt>assert</tt> calls <tt>abort()</tt> when <tt>NDEBUG</tt> is '''not''' defined). In essence, you have DoS'd yourself due to <tt>make</tt>.

In addition, many projects do not honor the user's command line. ESAPI C++ does its best to ensure a user's flags are honored via <tt>override</tt> as shown above, but other projects do not. For example, consider a project that should be built with Position Independent Executable (PIE or ASLR) enabled and data execution prevention (DEP) enabled. Dismissing user settings combined with insecure out of the box settings (and not picking them up during auto-setup or auto-configure) means a program built with the following will likely have neither defense:

<pre>$ make CFLAGS="-fPIE" CXXFLAGS="-fPIE" LDFLAGS="-pie -z,noexecstack, -z,noexecheap"</pre>

Defenses such as ASLR and DEP are especially important on Linux because [http://linux.die.net/man/5/elf Data Execution - not Prevention - is the norm].

=== Integration ===

Project level integration presents opportunities to harden your program or library with domain specific knowledge. For example, if the platform supports Position Independent Executables (PIE or ASLR) and data execution prevention (DEP), then you should integrate with it. The consequences of not doing so could result in exploitation. As a case in point, see KingCope's 0-days for MySQL in December, 2012 (CVE-2012-5579 and CVE-2012-5612, among others). Integration with platform security would have neutered a number of the 0-days.

You also have the opportunity to include helpful libraries that are not need for business logic support. For example, if you are working on a platform with [http://dmalloc.com DMalloc] or [http://code.google.com/p/address-sanitizer/ Address Sanitizer], you should probably use it in your debug builds. For Ubuntu, DMalloc available from the package manager and can be installed with <tt>sudo apt-get install libdmalloc5</tt>. For Apple platforms, its available as a scheme option (see [[#Clang/Xcode|Clang/Xcode]] below). Address Sanitizer is available in [http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8 and above] for many platforms.

In addition, project level integration is an opportunity to harden third party libraries you chose to include. Because you chose to include them, you and your users are responsible for them. If you or your users endure a SP800-53 audit, third party libraries will be in scope because the supply chain is included (specifically, item SA-12, Supply Chain Protection). The audits are not limited to those in the US Federal arena - financial institutions perform reviews too. A perfect example of violating this guidance is [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525], which was due to [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library].

Another example is including OpenSSL. You know (1) [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 is insecure], (2) [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 is insecure], and (3) [http://arstechnica.com/security/2012/09/crime-hijacks-https-sessions/ compression is insecure] (among others). In addition, suppose you don't use hardware and engines, and only allow static linking. Given the knowledge and specifications, you would configure the OpenSSL library as follows:

<pre>$ Configure darwin64-x86_64-cc -no-hw -no-engines -no-comp -no-shared -no-dso -no-sslv2 -no-sslv3 --openssldir=…</pre>

''Note Well'': you might want engines, especially on Ivy Bridge microarchitectures (3rd generation Intel Core i5 and i7 processors). To have OpenSSL use the processor's random number generator (via the of <tt>rdrand</tt> instruction), you will need to call OpenSSL's <tt>ENGINE_load_rdrand()</tt> function and then <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. See [http://wiki.opensslfoundation.com/index.php/Random_Numbers OpenSSL's Random Numbers] for details.

If you configure without the switches, then you will likely have vulnerable code/libraries and risk failing an audit. If the program is a remote server, then the following command will reveal if compression is active on the channel:

<pre>$ echo "GET / HTTP1.0" | openssl s_client -connect <nowiki>example.com:443</nowiki></pre>

<tt>nm</tt> or <tt>openssl s_client</tt> will show that compression is enabled in the client. In fact, any symbol within the <tt>OPENSSL_NO_COMP</tt> preprocessor macro will bear witness since <tt>-no-comp</tt> is translated into a <tt>CFLAGS</tt> define.

<pre>$ nm /usr/local/ssl/iphoneos/lib/libcrypto.a 2>/dev/null | egrep -i "(COMP_CTX_new|COMP_CTX_free)"
0000000000000110 T COMP_CTX_free
0000000000000000 T COMP_CTX_new</pre>

Even more egregious is the answer given to auditors who specifically ask about configurations and protocols: "we don't use weak/wounded/broken ciphers" or "we follow best practices." The use of compression tells the auditor that you are using wounded protocol in an insecure configuration and you don't follow best practices. That will likely set off alarm bells, and ensure the auditor dives deeper on more items.

== Preprocessor ==

The preprocessor is crucial to setting up a project for success. The C committee provided one macro - <tt>NDEBUG</tt> - and the macro can be used to derive a number of configurations and drive engineering processes. Unfortunately, the committee also left many related items to chance, which has resulted in programmers abusing builtin facilities. This section will help you set up you projects to integrate well with other projects and ensure reliability and security.

There are three topics to discuss when hardening the preprocessor. The first is well defined configurations which produce well defined behaviors, the second is useful behavior from assert, and the third is proper use of macros when integrating vendor code and third party libraries.

=== Configurations ===

To remove ambiguity, you should recognize two configurations: Release and Debug. Release is for production code on live servers, and its behavior is requested via the C/C++ <tt>NDEBUG</tt> macro. Its also the only macro observed by the C and C++ Committees and Posix. Diametrically opposed to release is Debug. While there is a compelling argument for <tt>!defined(NDEBUG)</tt>, you should have an explicit macro for the configuration and that macro should be <tt>DEBUG</tt>. This is because vendors and outside libraries use <tt>DEBUG</tt> (or similar) macro for their configuration. For example, Carnegie Mellon's Mach kernel uses <tt>DEBUG</tt>, Microsoft's CRT uses [http://msdn.microsoft.com/en-us/library/ww5t02fa%28v=vs.71%29.aspx<tt>_DEBUG</tt>], and Wind River Workbench uses <tt>DEBUG_MODE</tt>.

In addition to <tt>NDEBUG</tt> (Release) and <tt>DEBUG</tt> (Debug), you have two additional cross products: both are defined or neither are defined. Defining both should be an error, and defining neither should default to a release configuration. Below is from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/esapi/EsapiCommon.h ESAPI C++ EsapiCommon.h], which is the configuration file used by all source files:

<pre>// Only one or the other, but not both
#if (defined(DEBUG) || defined(_DEBUG)) && (defined(NDEBUG) || defined(_NDEBUG))
# error Both DEBUG and NDEBUG are defined.
#endif

// The only time we switch to debug is when asked. NDEBUG or {nothing} results
// in release build (fewer surprises at runtime).
#if defined(DEBUG) || defined(_DEBUG)
# define ESAPI_BUILD_DEBUG 1
#else
# define ESAPI_BUILD_RELEASE 1
#endif</pre>

When <tt>DEBUG</tt> is in effect, your code should receive full debug instrumentation, including the full force of assertions.

=== ASSERT ===

Asserts will help you create self-debugging code by helping you find the point of first failure quickly and easily. Asserts should be used throughout your program, including parameter validation, return value checking and program state. The <tt>assert</tt> will silently guard your code through its lifetime. It will always be there, even when not debugging a specific component of a module. If you have thorough code coverage, you will spend less time debugging and more time developing because programs will debug themselves.

To use asserts effectively, you should assert everything. That includes parameters upon entering a function, return values from function calls, and any program state. Everywhere you place an <tt>if</tt> statement for validation or checking, you should have an assert. Everywhere you have an <tt>assert</tt> for validation or checking, you should have an <tt>if</tt> statement. They go hand-in-hand.

If you are still using <tt>printf</tt>'s, then you have an opportunity for improvement. In the time it takes for you to write a <tt>printf</tt> or <tt>NSLog</tt> statement, you could have written an <tt>assert</tt>. Unlike the <tt>printf</tt> or <tt>NSLog</tt> which are often removed when no longer needed, the <tt>assert</tt> stays active forever. Remember, this is all about finding the point of first failure quickly so you can spend your time doing other things.

There is one problem with using asserts - [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html Posix states <tt>assert</tt> should call <tt>abort()</tt>] if <tt>NDEBUG</tt> is '''not''' defined. When debugging, <tt>NDEBUG</tt> will never be defined since you want the "program diagnostics" (quote from the Posix description). The behavior makes <tt>assert</tt> and its accompanying <tt>abort()</tt> completely useless for development. The result of "program diagnostics" calling <tt>abort()</tt> due to standard C/C++ behavior is disuse - developers simply don't use them. Its incredibly bad for the development community because self-debugging programs can help eradicate so many stability problems.

Since self-debugging programs are so powerful, you will have to have to supply your own assert and signal handler with improved behavior. Your assert will exchange auto-aborting behavior for auto-debugging behavior. The auto-debugging facility will ensure the debugger snaps when a problem is detected, and you will find the point of first failure quickly and easily.

ESAPI C++ supplies its own assert with the behavior described above. In the code below, <tt>ASSERT</tt> raises <tt>SIGTRAP</tt> when in effect or it evaluates to <tt>void</tt> in other cases.

<pre>// A debug assert which should be sprinkled liberally. This assert fires and then continues rather
// than calling abort(). Useful when examining negative test cases from the command line.
#if (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_STARNIX))
# define ESAPI_ASSERT1(exp) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
# define ESAPI_ASSERT2(exp, msg) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< ": \"" << (msg) << "\"" << std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
#elif (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_WINDOWS))
# define ESAPI_ASSERT1(exp) assert(exp)
# define ESAPI_ASSERT2(exp, msg) assert(exp)
#else
# define ESAPI_ASSERT1(exp) ((void)(exp))
# define ESAPI_ASSERT2(exp, msg) ((void)(exp))
#endif

#if !defined(ASSERT)
# define ASSERT(exp) ESAPI_ASSERT1(exp)
#endif</pre>

At program startup, a <tt>SIGTRAP</tt> handler will be installed if one is not provided by another component:

<pre>struct DebugTrapHandler
{
DebugTrapHandler()
{
struct sigaction new_handler, old_handler;

do
{
int ret = 0;

ret = sigaction (SIGTRAP, NULL, &old_handler);
if (ret != 0) break; // Failed

// Don't step on another's handler
if (old_handler.sa_handler != NULL) break;

new_handler.sa_handler = &DebugTrapHandler::NullHandler;
new_handler.sa_flags = 0;

ret = sigemptyset (&new_handler.sa_mask);
if (ret != 0) break; // Failed

ret = sigaction (SIGTRAP, &new_handler, NULL);
if (ret != 0) break; // Failed

} while(0);
}

static void NullHandler(int /*unused*/) { }

};

// We specify a relatively low priority, to make sure we run before other CTORs
// http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#C_002b_002b-Attributes
static const DebugTrapHandler g_dummyHandler __attribute__ ((init_priority (110)));</pre>

On a Windows platform, you would call <tt>_set_invalid_parameter_handler</tt> (and possibly <tt>set_unexpected</tt> or <tt>set_terminate</tt>) to install a new handler.

Live hosts running production code should always define <tt>NDEBUG</tt> (i.e., release configuration), which means they do not assert or auto-abort. Auto-abortion is not acceptable behavior, and anyone who asks for the behavior is completely abusing the functionality of "program diagnostics". If a program wants a core dump, then it should create the dump rather than crashing.

For more reading on asserting effectively, please see one of John Robbin's books, such as ''[http://www.amazon.com/dp/0735608865 Debugging Applications]''. John is a legendary bug slayer in Windows circles, and he will show you how to do nearly everything, from debugging a simple program to bug slaying in multithreaded programs.

=== Additional Macros ===

Additional macros include any macros needed to integrate properly and securely. It includes integrating the program with the platform (for example MFC or Cocoa/CocoaTouch) and libraries (for example, Crypto++ or OpenSSL). It can be a challenge because you have to have proficiency with your platform and all included libraries and frameworks. The list below illustrates the level of detail you will need when integrating.

Though Boost is missing from the list, it appears to lack recommendations, additional debug diagnostics, and a hardening guide. See ''[http://stackoverflow.com/questions/14927033/boost-hardening-guide-preprocessor-macros BOOST Hardening Guide (Preprocessor Macros)]'' for details. In addition, Tim Day points to ''[http://boost.2283326.n4.nabble.com/boost-build-should-we-not-define-SECURE-SCL-0-by-default-for-all-msvc-toolsets-td2654710.html <nowiki>[boost.build] should we not define _SECURE_SCL=0 by default for all msvc toolsets</nowiki>]'' for a recent discussion related to hardening (or lack thereof).

In addition to what you should define, defining some macros and undefining others should trigger a security related defect. For example, <tt>-U_FORTIFY_SOURCES</tt> on Linux and <tt>_CRT_SECURE_NO_WARNINGS=1</tt>, <tt>_SCL_SECURE_NO_WARNINGS</tt>, <tt>_ATL_SECURE_NO_WARNINGS</tt> or <tt>STRSAFE_NO_DEPRECATE</tt> on Windows.

{| border="1"

|-style="background:#DADADA"
!Platform/Library!!Debug!!Release
|+ Table 1: Additional Platform/Library Macros

|-
|width="175pt"|All
|width="250pt"|DEBUG=1
|width="250pt"|NDEBUG=1

|-
|Linux
|_GLIBCXX_DEBUG=1a
|_FORTIFY_SOURCE=2

|-
|Android
|NDK_DEBUG=1
|_FORTIFY_SOURCE=1 (4.2 and above) 
<tt>#define LOGI(...)</tt> (define to nothing, preempt logging)

|-
|Cocoa/CocoaTouch
|
|NS_BLOCK_ASSERTIONS=1 
<tt>#define NSLog(...)</tt> (define to nothing, preempt ASL)

|-
|SafeInt
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1

|-
|Microsoft
|_DEBUG=1, STRICT, 
_SECURE_SCL=1, _HAS_ITERATOR_DEBUGGING=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1
|STRICT 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1

|-
|Microsoft ATL & MFC
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS

|-
|STLPort
|_STLP_DEBUG=1, _STLP_USE_DEBUG_LIB=1 
_STLP_DEBUG_ALLOC=1, _STLP_DEBUG_UNINITIALIZED=1
|

|-
|SQLite
|SQLITE_DEBUG, SQLITE_MEMDEBUG 
SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc
|SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc

|-
|SQLCipher
|Remove '''<tt>NDEBUG</tt>''' from Debug builds (Xcode) 
SQLITE_HAS_CODEC=1
|SQLITE_HAS_CODEC=1

|-
|SQLite/SQLCipher
|SQLITE_TEMP_STORE=3d
|SQLITE_TEMP_STORE=3d

|}

a Be careful with <tt>_GLIBCXX_DEBUG</tt> when using pre-compiled libraries such as Boost from a distribution. There are ABI incompatibilities, and the result will likely be a crash. You will have to compile Boost with <tt>_GLIBCXX_DEBUG</tt> or omit <tt>_GLIBCXX_DEBUG</tt>.

b SQLite secure deletion zeroizes memory on destruction. Define as required, and always define in US Federal since zeroization is required for FIPS 140-2, Level 1.

c ''N'' is 0644 by default, which means everyone has some access.

d Force temporary tables into memory (no unencrypted data to disk).

== Compiler and Linker ==

Compiler writers provide a rich set of warnings from the analysis of code during compilation. Both GCC and Visual Studio have static analysis capabilities to help find mistakes early in the development process. The built in static analysis capabilities of GCC and Visual Studio are usually sufficient to ensure proper API usage and catch a number of mistakes such as using an uninitialized variable or comparing a negative signed int and a positive unsigned int.

As a concrete example, (and for those not familiar with C/C++ promotion rules), a warning will be issued if a signed integer is promoted to an unsigned integer and then compared because a side effect is <tt>-1 > 1</tt> after promotion! GCC and Visual Studio will not currently catch, for example, SQL injections and other tainted data usage. For that, you will need a tool designed to perform data flow analysis or taint analysis.

Some in the development community resist static analysis or refute its results. For example, when static analysis warned the Linux kernel's <tt>sys_prctl</tt> was comparing an unsigned value against less than zero, Jesper Juhl offered a patch to clean up the code. Linus Torvalds howled “No, you don't do this… GCC is crap” (referring to compiling with warnings). For the full discussion, see ''[http://linux.derkeiler.com/Mailing-Lists/Kernel/2006-11/msg08325.html <nowiki>[PATCH] Don't compare unsigned variable for <0 in sys_prctl()</nowiki>]'' from the Linux Kernel mailing list.

The following sections will detail steps for three platforms. First is a typical GNU Linux based distribution offering GCC and Binutils, second is Clang and Xcode, and third is modern Windows platforms.

=== Distribution Hardening ===

Before discussing GCC and Binutils, it would be a good time to point out some of the defenses discussed below are all ready present in a distribution. Unfortunately, its design by committee, so what is present is usually only a mild variation of what is available (this way, everyone is mildly offended). For those who are purely worried about performance, you might be surprised to learn you have already taken the small performance hint without even knowing.

Linux and BSD distributions often apply some hardening without intervention via ''[http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html GCC Spec Files]''. If you are using Debian, Ubuntu, Linux Mint and family, see ''[http://wiki.debian.org/Hardening Debian Hardening]''. For Red Hat and Fedora systems, see ''[http://lists.fedoraproject.org/pipermail/devel-announce/2011-August/000821.html New hardened build support (coming) in F16]''. Gentoo users should visit ''[http://www.gentoo.org/proj/en/hardened/ Hardened Gentoo]''.

You can see the settings being used by a distribution via <tt>gcc -dumpspecs</tt>. From Linux Mint 12 below, -fstack-protector (but not -fstack-protector-all) is used by default.

<pre>$ gcc -dumpspecs
…
*link_ssp: %{fstack-protector:}

*ssp_default: %{!fno-stack-protector:%{!fstack-protector-all: %{!ffreestanding:%{!nostdlib:-fstack-protector}}}}
…</pre>

The “SSP” above stands for Stack Smashing Protector. SSP is a reimplementation of Hiroaki Etoh's work on IBM Pro Police Stack Detector. See Hiroaki Etoh's patch ''[http://gcc.gnu.org/ml/gcc-patches/2001-06/msg01753.html gcc stack-smashing protector]'' and IBM's ''[http://www.research.ibm.com/trl/projects/security/ssp/ GCC extension for protecting applications from stack-smashing attacks]'' for details.

=== GCC/Binutils ===

GCC (the compiler collection) and Binutils (the assemblers, linkers, and other tools) are separate projects that work together to produce a final executable. Both the compiler and linker offer options to help you write safer and more secure code. The linker will produce code which takes advantage of platform security features offered by the kernel and PaX, such as no-exec stacks and heaps (NX) and Position Independent Executable (PIE).

The table below offers a set of compiler options to build your program. Static analysis warnings help catch mistakes early, while the linker options harden the executable at runtime. In the table below, “GCC” should be loosely taken as “non-ancient distributions.” While the GCC team considers 4.2 ancient, you will still encounter it on Apple and BSD platforms due to changes in GPL licensing around 2007. Refer to ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Option Summary]'', ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html Options to Request or Suppress Warnings]'' and ''[http://sourceware.org/binutils/docs-2.21/ld/Options.html Binutils (LD) Command Line Options]'' for usage details.

Noteworthy of special mention are <tt>-fno-strict-overflow</tt> and <tt>-fwrapv</tt>a. The flags ensure the compiler does not remove statements that result in overflow or wrap. If your program only runs correctly using the flags, it is likely violating C/C++ rules on overflow and illegal. If the program is illegal due to overflow or wrap checking, you should consider using [http://code.google.com/p/safe-iop/ safe-iop] for C or David LeBlanc's [http://safeint.codeplex.com SafeInt] in C++.

For a project compiled and linked with hardened settings, some of those settings can be verified with the [http://www.trapkit.de/tools/checksec.html Checksec] tool written by Tobias Klein. The <tt>checksec.sh</tt> script is designed to test standard Linux OS and PaX security features being used by an application. See the [http://www.trapkit.de/tools/checksec.html Trapkit] web page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 2: GCC C Warning Options

|-
|width="200pt"|<nowiki>-Wall -Wextra</nowiki>
|width="75t"|GCC
|width="425pt"|Enables many warnings (despite their names, all and extra do not turn on all warnings).a

|-
|<nowiki>-Wconversion</nowiki>
|GCC
|Warn for implicit conversions that may alter a value (includes -Wsign-conversion).

|-
|<nowiki>-Wsign-conversion</nowiki>
|GCC
|Warn for implicit conversions that may change the sign of an integer value, such as assigning a signed integer to an unsigned integer (<tt>-1 > 1</tt> after promotion!).

|-
|<nowiki>-Wcast-align</nowiki>
|GCC
|Warn for a pointer cast to a type which has a different size, causing an invalid alignment and subsequent bus error on ARM processors.

|-
|<nowiki>-Wformat=2 -Wformat-security</nowiki>
|GCC
|Increases warnings related to possible security defects, including incorrect format specifiers.

|-
|<nowiki>-fno-common</nowiki>
|GCC
|Prevent global variables being simultaneously defined in different object files.

|-
|<nowiki>-fstack-protector or -fstack-protector-all</nowiki>
|GCC
|Stack Smashing Protector (SSP). Improves stack layout and adds a guard to detect stack based buffer overflows.b

|-
|<nowiki>-fno-omit-frame-pointer</nowiki>
|GCC
|Improves backtraces for post-mortem analysis

|-
|<nowiki>-Wmissing-prototypes and -Wmissing-declarations</nowiki>
|GCC
|Warn if a global function is defined without a prototype or declaration.

|-
|<nowiki>-Wstrict-prototypes</nowiki>
|GCC
|Warn if a function is declared or defined without specifying the argument types.

|-
|<nowiki>-Wstrict-overflow</nowiki>
|GCC 4.2
|Warn about optimizations taken due to <nowiki>[undefined]</nowiki> signed integer overflow assumptions.

|-
|<nowiki>-Wtrampolines</nowiki>
|GCC 4.3
|Warn about trampolines generated for pointers to nested functions. Trampolines require executable stacks.

|-
|<nowiki>-fsanitize=address</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/address-sanitizer/ AddressSanitizer], a fast memory error detector. Memory access instructions will be instrumented to help detect heap, stack, and global buffer overflows; as well as use-after-free bugs.

|-
|<nowiki>-fsanitize=thread</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/data-race-test/wiki/ThreadSanitizer ThreadSanitizer], a fast data race detector. Memory access instructions will be instrumented to detect data race bugs.

|-
|<nowiki>-Wl,-z,nodlopen and -Wl,-z,nodump</nowiki>
|Binutils 2.10
|Reduces the ability of an attacker to load, manipulate, and dump shared objects.

|-
|<nowiki>-Wl,-z,noexecstack and -Wl,-z,noexecheap</nowiki>
|Binutils 2.14
|Data Execution Prevention (DEP). ELF headers are marked with PT_GNU_STACK and PT_GNU_HEAP.

|-
|<nowiki>-Wl,-z,relro</nowiki>
|Binutils 2.15
|Helps remediate Global Offset Table (GOT) attacks on executables.

|-
|<nowiki>-Wl,-z,now</nowiki>
|Binutils 2.15
|Helps remediate Procedure Linkage Table (PLT) attacks on executables.

|-
|<nowiki>-fPIC</nowiki>
|Binutils
|Position Independent Code. Used for libraries and shared objects. Both -fPIC (compiler) and -shared (linker) are required.

|-
|<nowiki>-fPIE</nowiki>
|Binutils 2.16
|Position Independent Executable (ASLR). Used for programs. Both -fPIE (compiler) and -pie (linker) are required.

|}

a Unlike Clang and -Weverything, GCC does not provide a switch to truly enable all warnings. 
b -fstack-protector guards functions with high risk objects such as C strings, while -fstack-protector-all guards all objects.

Additional C++ warnings which can be used include the following in Table 3. See ''[http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html GCC's Options Controlling C++ Dialect]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 3: GCC C++ Warning Options

|-
|width="200pt"|<nowiki>-Woverloaded-virtual</nowiki>
|width="425pt"|Warn when a function declaration hides virtual functions from a base class.

|-
|<nowiki>-Wreorder</nowiki>
|Warn when the order of member initializers given in the code does not match the order in which they must be executed.

|-
|<nowiki>-Wsign-promo</nowiki>
|Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size.

|-
|<nowiki>-Wnon-virtual-dtor</nowiki>
|Warn when a class has virtual functions and an accessible non-virtual destructor.

|-
|<nowiki>-Weffc++</nowiki>
|Warn about violations of the following style guidelines from Scott Meyers' ''[http://www.aristeia.com/books.html Effective C++, Second Edition]'' book.

|}

And additional Objective C warnings which are often useful include the following. See ''[http://gcc.gnu.org/onlinedocs/gcc/Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html Options Controlling Objective-C and Objective-C++ Dialects]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 4: GCC Objective C Warning Options

|-
|width="200pt"|<nowiki>-Wstrict-selector-match</nowiki>
|width="425pt"|Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type id or Class.

|-
|<nowiki>-Wundeclared-selector</nowiki>
|Warn if a <tt>@selector(…)</tt> expression referring to an undeclared selector is found.

|}

The use of aggressive warnings will produce spurious noise. The noise is a tradeoff - you can learn of potential problems at the cost of wading through some chaff. The following will help reduces spurious noise from the warning system:

* -Wno-unused-parameter (GCC)
* -Wno-type-limits (GCC 4.3)
* -Wno-tautological-compare (Clang)

Finally, a simple version based Makefile example is shown below. This is different than feature based makefile produced by auto tools (which will test for a particular feature and then define a symbol or configure a template file). Not all platforms use all options and flags. To address the issue you can pursue one of two strategies. First, you can ship with a weakened posture by servicing the lowest common denominator; or you can ship with everything in force. In the latter case, those who don't have a feature available will edit the makefile to accommodate their installation.

<pre>CXX=g++
EGREP = egrep
…

GCC_COMPILER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version')
GCC41_OR_LATER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version (4\.[1-9]|[5-9])')
…

GNU_LD210_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[0-9]|2\.[2-9])')
GNU_LD214_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[4-9]|2\.[2-9])')
…

ifeq ($(GCC_COMPILER),1)
MY_CC_FLAGS += -Wall -Wextra -Wconversion
MY_CC_FLAGS += -Wformat=2 -Wformat-security
MY_CC_FLAGS += -Wno-unused-parameter
endif

ifeq ($(GCC41_OR_LATER),1)
MY_CC_FLAGS += -fstack-protector-all
endif

ifeq ($(GCC42_OR_LATER),1)
MY_CC_FLAGS += -Wstrict-overflow
endif

ifeq ($(GCC43_OR_LATER),1)
MY_CC_FLAGS += -Wtrampolines
endif

ifeq ($(GNU_LD210_OR_LATER),1)
MY_LD_FLAGS += -z,nodlopen -z,nodump
endif

ifeq ($(GNU_LD214_OR_LATER),1)
MY_LD_FLAGS += -z,noexecstack -z,noexecheap
endif

ifeq ($(GNU_LD215_OR_LATER),1)
MY_LD_FLAGS += -z,relro -z,now
endif

ifeq ($(GNU_LD216_OR_LATER),1)
MY_CC_FLAGS += -fPIE
MY_LD_FLAGS += -pie
endif

# Use 'override' to honor the user's command line
override CFLAGS := $(MY_CC_FLAGS) $(CFLAGS)
override CXXFLAGS := $(MY_CC_FLAGS) $(CXXFLAGS)
override LDFLAGS := $(MY_LD_FLAGS) $(LDFLAGS)
…</pre>

=== Clang/Xcode ===

[http://clang.llvm.org Clang] and [http://llvm.org LLVM] have been aggressively developed since Apple lost its GPL compiler back in 2007 (due to Tivoization which resulted in GPLv3). Since that time, a number of developers and Goggle have joined the effort. While Clang will consume most (all?) GCC/Binutil flags and switches, the project supports a number of its own options, including a static analyzer. In addition, Clang is relatively easy to build with additional diagnostics, such as Dr. John Regher and Peng Li's [http://embed.cs.utah.edu/ioc/ Integer Overflow Checker (IOC)].

IOC is incredibly useful, and has found bugs in a number of projects, from the Linux Kernel (<tt>include/linux/bitops.h</tt>, still unfixed), SQLite, PHP, Firefox (many still unfixed), LLVM, and Python. Future version of Clang (Clang 3.3 and above) will allow you to enable the checks out of the box with <tt>-fsanitize=integer</tt> and <tt>-fsanitize=shift</tt>.

Clang options can be found at [http://clang.llvm.org/docs/UsersManual.html Clang Compiler User’s Manual]. Clang does include an option to turn on all warnings - <tt>-Weverything</tt>. Use it with care but use it regularly since you will get back a lot of noise and issues you missed. For example, add <tt>-Weverything</tt> for production builds and make non-spurious issues a quality gate. Under Xcode, simply add <tt>-Weverything</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>.

In addition to compiler warnings, both static analysis and additional security checks can be performed. Reading on Clang's static analysis capabilities can be found at [http://clang-analyzer.llvm.org Clang Static Analyzer]. Figure 1 below shows some of the security checks utilized by Xcode.

{| align="center"
| [[File:toolchan-hardening-11.png|thumb|450px|Figure 1: Clang/LLVM and Xcode options]]
|}

=== Visual Studio ===

Visual Studio offers a convenient Integrated Development Environment (IDE) for managing solutions and their settings. the section called “Visual Studio Options” discusses option which should be used with Visual Studio, and the section called “Project Properties” demonstrates incorporating those options into a solution's project.

The table below lists the compiler and linker switches which should be used under Visual Studio. Refer to Howard and LeBlanc's Writing Secure Code (Microsoft Press) for a detailed discussion; or ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]'' in Security Briefs by Michael Howard. In the table below, “Visual Studio” refers to nearly all versions of the development environment, including Visual Studio 5.0 and 6.0.

For a project compiled and linked with hardened settings, those settings can be verified with BinScope. BinScope is a verification tool from Microsoft that analyzes binaries to ensure that they have been built in compliance with Microsoft's Security Development Lifecycle (SDLC) requirements and recommendations. See the ''[https://www.microsoft.com/download/en/details.aspx?id=11910 BinScope Binary Analyzer]'' download page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 5: Visual Studio Warning Options

|-
|width="150pt"|<nowiki>/W4</nowiki>
|width="100pt"|Visual Studio
|width="350pt"|Warning level 4, which includes most warnings.

|-
|<nowiki>/WAll</nowiki>
|Visual Studio 2003
|Enable all warnings, including those off by default.a

|-
|<nowiki>/GS</nowiki>
|Visual Studio 2003
|Adds a security cookie (guard or canary) on the stack before the return address buffer stack based for overflow checks.a

|-
|<nowiki>/SafeSEH</nowiki>
|Visual Studio 2003
|Safe structured exception handling to remediate SEH overwrites.

|-
|<nowiki>/analyze</nowiki>
|Visual Studio 2005
|Enterprise code analysis (freely available with Windows SDK for Windows Server 2008 and .NET Framework 3.5).

|-
|<nowiki>/NXCOMPAT</nowiki>
|Visual Studio 2005
|Data Execution Prevention (DEP).

|-
|<nowiki>/dynamicbase</nowiki>
|Visual Studio 2005 SP1
|Address Space Layout Randomization (ASLR).

|-
|<nowiki>strict_gs_check</nowiki>
|Visual Studio 2005 SP1
|Aggressively applies stack protections to a source file to help detect some categories of stack based buffer overruns.b

|}

aSee Jon Sturgeon's discussion of the switch at ''[https://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx Off By Default Compiler Warnings in Visual C++]''. 
aWhen using /GS, there are a number of circumstances which affect the inclusion of a security cookie. For example, the guard is not used if there is no buffer in the stack frame, optimizations are disabled, or the function is declared naked or contains inline assembly. 
b<tt>#pragma strict_gs_check(on)</tt> should be used sparingly, but is recommend in high risk situations, such as when a source file parses input from the internet.

=== Warn Suppression ===

From the tables above, a lot of warnings have been enabled to help detect possible programming mistakes. The potential mistakes are detected via compiler which carries around a lot of contextual information during its code analysis phase. At times, you will receive spurious warnings because the compiler is not ''that'' smart. Its understandable and even a good thing (how would you like to be out of a job because a program writes its own programs?). At times you will have to learn how to work with the compiler's warning system to suppress warnings. Notice what was not said: turn off the warnings.

Suppressing warnings placates the compiler for spurious noise so you can get to the issues that matter (you are separating the wheat from the chaff). This section will offer some hints and point out some potential minefields. First is an unused parameter (for example, <tt>argc</tt> or <tt>argv</tt>). Suppressing unused parameter warnings is especially helpful for C++ and interface programming, where parameters are often unused. For this warning, simply define an "UNUSED" macro and warp the parameter:

<pre>#define UNUSED_PARAMETER(x) ((void)x)
…

int main(int argc, char* argv[])
{
UNUSED_PARAMETER(argc);
UNUSED_PARAMETER(argv);
…
}</pre>

A potential minefield lies near "comparing unsigned and signed" values, and <tt>-Wconversion</tt> will catch it for you. This is because C/C++ promotion rules state the signed value will be promoted to an unsigned value and then compared. That means <tt>-1 > 1</tt> after promotion! To fix this, you cannot blindly cast - you must first range test the value:

<pre>int x = GetX();
unsigned int y = GetY();

ASSERT(x >= 0);
if(!(x >= 0))
throw runtime_error("WTF??? X is negative.");

if(static_cast<unsigned int>(x) > y)
cout << "x is greater than y" << endl;
else
cout << "x is not greater than y" << endl;</pre>

Notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>x</tt>. Just run the program and wait for it to tell you there is a problem. If there is a problem, the program will snap the debugger (and more importantly, not call a useless <tt>abort()</tt> as specified by Posix). It beats the snot out of <tt>printf</tt> that are removed when no longer needed or pollute outputs.

Another conversion problem you will encounter conversion between types, and <tt>-Wconversion</tt> will also catch it for you. The following will always have an opportunity to fail, and should light up like a Christmas tree:

<pre>struct sockaddr_in addr;
…

addr.sin_port = htons(atoi(argv[2]));</pre>

The following would probably serve you much better. Notice <tt>atoi</tt> and fiends are not used because they can silently fail. In addition, the code is instrumented so you don't need to waste a lot of time debugging potential problems:

<pre>const char* cstr = GetPortString();

ASSERT(cstr != NULL);
if(!(cstr != NULL))
throw runtime_error("WTF??? Port string is not valid.");

istringstream iss(cstr);
long long t = 0;
iss >> t;

ASSERT(!(iss.fail()));
if(iss.fail())
throw runtime_error("WTF??? Failed to read port.");

// Should this be a port above the reserved range ([0-1024] on Unix)?
ASSERT(t > 0);
if(!(t > 0))
throw runtime_error("WTF??? Port is too small");

ASSERT(t < static_cast<long long>(numeric_limits<unsigned int>::max()));
if(!(t < static_cast<long long>(numeric_limits<unsigned int>::max())))
throw runtime_error("WTF??? Port is too large");

// OK to use port
unsigned short port = static_cast<unsigned short>(t);
…</pre>

Again, notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>port</tt>. This code will continue checking conditions, years after being instrumented (assuming to wrote code to read a config file early in the project). There's no need to remove the <tt>ASSERT</tt>s as with <tt>printf</tt> since they are silent guardians.

Another useful suppression trick is too avoid ignoring return values. Not only is it useful to suppress the warning, its required for correct code. For example, <tt>snprint</tt> will alert you to truncations through its return value. You should not make them silent truncations by ignoring the warning or casting to <tt>void</tt>:

<pre>char path[PATH_MAX];
…

int ret = snprintf(path, sizeof(path), "%s/%s", GetDirectory(), GetObjectName());
ASSERT(ret != -1);
ASSERT(!(ret >= sizeof(path)));

if(ret == -1 || ret >= sizeof(path))
throw runtime_error("WTF??? Unable to build full object name");

// OK to use path
…</pre>

The problem is pandemic, and not just boring user land programs. Projects which offer high integrity code, such as SELinux, suffer silent truncations. The following is from an approved SELinux patch even though a comment was made that it [http://permalink.gmane.org/gmane.comp.security.selinux/16845 suffered silent truncations in its <tt>security_compute_create_name</tt> function] from <tt>compute_create.c</tt>.

<pre>12 int security_compute_create_raw(security_context_t scon,
13 security_context_t tcon,
14 security_class_t tclass,
15 security_context_t * newcon)
16 {
17 char path[PATH_MAX];
18 char *buf;
19 size_t size;
20 int fd, ret;
21
22 if (!selinux_mnt) {
23 errno = ENOENT;
24 return -1;
25 }
26
27 snprintf(path, sizeof path, "%s/create", selinux_mnt);
28 fd = open(path, O_RDWR);</pre>

Unlike other examples, the above code will not debug itself, and you will have to set breakpoints and trace calls to determine the point of first failure. (And the code above gambles that the truncated file does not exist or is not under an adversary's control by blindly performing the <tt>open</tt>).

== Runtime ==

The previous sections concentrated on setting up your project for success. This section will examine additional hints for running with increased diagnostics and defenses. Not all platforms are created equal - GNU Linux is difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening to a program after compiling and static linking]; while Windows allows post-build hardening through a download. Remember, the goal is to find the point of first failure quickly so you can improve the reliability and security of the code.

=== Xcode ===

Xcode offers additional [http://developer.apple.com/library/mac/#recipes/xcode_help-scheme_editor/Articles/SchemeDiagnostics.html Application Diagnostics] that can help find memory errors and object use problems. Schemes can be managed through ''Products'' menu item, ''Scheme'' submenu item, and then ''Edit''. From the editor, navigate to the ''Diagnostics'' tab. In the figure below, four additional instruments are enabled for the debugging cycle: Scribble guards, Edge guards, Malloc guards, and Zombies.

{| align="center"
| [[File:toolchan-hardening-1.png|thumb|450px|Figure 2: Xcode Memory Diagnostics]]
|}

There is one caveat with using some of the guards: Apple only provides them for the simulator, and not a device. In the past, the guards were available for both devices and simulators.

=== Windows ===

Visual Studio offers a number of debugging aides for use during development. The aides are called [http://msdn.microsoft.com/en-us/library/d21c150d.aspx Managed Debugging Assistants (MDAs)]. You can find the MDAs on the ''Debug'' menu, then ''Exceptions'' submenu. MDAs allow you to tune your debugging experience by, for example, filter exceptions for which the debugger should snap. For more details, see Stephen Toub's ''[http://msdn.microsoft.com/en-us/magazine/cc163606.aspx Let The CLR Find Bugs For You With Managed Debugging Assistants]''.

{| align="center"
| [[File:toolchan-hardening-2.png|thumb|450px|Figure 3: Managed Debugging Assistants]]
|}

Finally, for runtime hardening, Microsoft has a helpful tool called EMET. EMET is the [http://support.microsoft.com/kb/2458544 Enhanced Mitigation Experience Toolkit], and allows you to apply runtime hardening to an executable which was built without. Its very useful for utilities and other programs that were built without an SDLC.

{| align="center"
| [[File:toolchan-hardening-3.png|thumb|450px|Figure 4: Windows and EMET]]
|}

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

C-Based Toolchain Hardening

2013-03-08T18:18:53Z

Jeffrey Walton:

[[C-Based Toolchain Hardening]] is a treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

This is a prescriptive article, and it will not debate semantics or speculate on behavior. Some information, such as the C/C++ committee's motivation and pedigree for [https://groups.google.com/a/isocpp.org/forum/?fromgroups=#!topic/std-discussion/ak8e1mzBhGs "program diagnostics", <tt>NDEBUG</tt>, <tt>assert</tt>, and <tt>abort()</tt>], appears to be lost like a tale in the Lord of the Rings. As such, the article will specify semantics (for example, the philosophy of 'debug' and 'release' build configurations), assign behaviors (for example, what an assert should do in a 'debug' and 'release' build configurations), and present a position. If you find the posture is too aggressive, then you should back off as required to suite your taste.

A secure toolchain is not a silver bullet. It is one piece of an overall strategy in the engineering process to help ensure success. It will compliment existing processes such as static analysis, dynamic analysis, secure coding, negative test suites, and the like. Tools such as Valgrind and Helgrind will still be needed. And a project will still require solid designs and architectures.

Finally, the OWASP [http://code.google.com/p/owasp-esapi-cplusplus/source ESAPI C++] project eats its own dog food. Many of the examples you will see in this article come directly from the ESAPI C++ project.

== Wisdom ==

Code '''must''' be correct. It '''should''' be secure. It '''can''' be efficient.

[http://en.wikipedia.org/wiki/Jon_Bentley Dr. Jon Bentley]: ''"If it doesn't have to be correct, I can make it as fast as you'd like it to be"''.

[http://en.wikipedia.org/wiki/Gary_McGraw Dr. Gary McGraw]: ''"Thou shalt not rely solely on security features and functions to build secure software as security is an emergent property of the entire system and thus relies on building and integrating all parts properly"''.

== Configuration ==

Configuration is the first opportunity to configure your project for success. Not only do you have to configure your project to meet reliability and security goals, you must also configure integrated libraries properly. You typically have has three choices. First, you can use auto-configuration utilities if on Linux or Unix. Second, you can write a makefile by hand. This is predominant on Linux, Mac OS X, and Unix, but it applies to Windows as well. Finally, you can use an integrated development environment or IDE.

=== Build Configurations ===

At this stage in the process, you should concentrate on configuring for two builds: Debug and Release. Debug will be used for development and include full instrumentation. Release will be configured for production. The difference between the two settings is usually ''optimization level'' and ''debug level''. A third build configuration is Test, and its usually a special case of Release.

For debug and release builds, the settings are typically diametrically opposed. Debug configurations have no optimizations and full debug information; while Release builds have optimizations and minimal to moderate debug information. In addition, debug code has full assertions and additional library integration, such as mudflaps and malloc guards such as <tt>dmalloc</tt>.

The Test configuration is often a Release configuration that makes everything public for testing and builds a test harness. For example, all member functions public (C++ class) and all interfaces (library or shared object) should be made available for testing. Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

[http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8] introduced an optimization of <tt>-Og</tt>. Note that it is only an optimization, and still requires a customary debug level via <tt>-g</tt>.

==== Debug Builds ====

Debug builds are where developers spend most of their time when vetting problems, so this build should concentrate forces and tools or be a 'force multiplier'. Though many do not realize, debug code is more highly valued than release code because its adorned with additional instrumentation. The debug instrumentation will cause a program to become nearly "self-debugging", and help you catch mistakes such as bad parameters, failed API calls, and memory problems.

Self-debugging code reduces your time during trouble shooting and debugging. Reducing time under the debugger means you have more time for development and feature requests. If code is checked in without debug instrumentation, it should be fixed by adding instrumentation or rejected.

For GCC, optimizations and debug symbolication are controlled through two switches: <tt>-O</tt> and <tt>-g</tt>. You should use the following as part of your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for a minimal debug session:

<pre>-O0 -g3 -ggdb</pre>

<tt>-O0</tt> turns off optimizations and <tt>-g3</tt> ensures maximum debug information is available. You may need to use <tt>-O1</tt> so some analysis is performed. Otherwise, your debug build will be missing a number of warnings not present in release builds. <tt>-g3</tt> ensures maximum debugging information is available for the debug session, including symbolic constants and <tt>#defines</tt>. <tt>-ggdb</tt> includes extensions to help with a debug session under GDB. For completeness, Jan Krachtovil stated <tt>-ggdb</tt> currently has no effect in a private email.

Debug build should also define <tt>DEBUG</tt>, and ensure <tt>NDEBUG</tt> is not defined. <tt>NDEBUG</tt> removes "program diagnostics"; and has undesirable behavior and side effects which discussed below in more detail. The defines should be present for all code, and not just the program. You use it for all code (your program and included libraries) because you need to know how they fail too (remember, you take the bug report - not the third party library).

In addition, you should also use other relevant flags, such as <tt>-fno-omit-frame-pointer</tt> and <tt>-fsanitize=address</tt>. Finally, you should also ensure your project includes additional diagnostic libraries, such as <tt>dmalloc</tt>. The additional flags and libraries are discussed below in more detail.

==== Release Builds ====

Release builds are what your customer receives. They are meant to be run on production hardware and servers, and they should be reliable, secure, and efficient. A stable release build is the product of the hard work and effort during development.

For release builds, you should use the following as part of <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for release builds:

<pre>-On -g2</pre>

<tt>-O''n''</tt> sets optimizations for speed or size (for example, <tt>-Os</tt> or <tt>-O2</tt>), and <tt>-g2</tt> ensure debugging information is created.

Debugging information should be stripped and retained in case of symbolication for a crash report from the field. While not desired, debug information can be left in place without a performance penalty. See ''[http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]'' for details.

Release builds should also define <tt>NDEBUG</tt>, and ensure <tt>DEBUG</tt> is not defined. The time for debugging and diagnostics is over, so users get production code with full optimizations, no "programming diagnostics", and other efficiencies. If you can't optimize or your are performing excessive logging, it usually means the program is not ready for production.

If you have been relying on an <tt>assert</tt> and then a subsequent <tt>abort()</tt>, you have been abusing "program diagnostics" since it has no place in production code. If you want a memory dump, create one so users don't have to worry about secrets and other sensitive information being written to the filesystem and emailed in plain text.

For Windows, you would use <tt>/Od</tt> for debug builds; and <tt>/Ox</tt>, <tt>/O2</tt> or <tt>/Os</tt> for release builds. See Microsoft's [http://msdn.microsoft.com/en-us/library/k1ack8f1.aspx /O Options (Optimize Code)] for details.

==== Test Builds ====

Test builds are used to provide heuristic validation by way of positive and negative test suites. Under a test configuration, all interfaces are tested to ensure they perform to specification and satisfaction. "Satisfaction" is subjective, but it should include no crashing and no trashing of your memory arena, even when faced with negative tests.

Because all interfaces are tested (and not just the public ones), your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> should include:

<pre>-Dprotected=public -Dprivate=public</pre>

You should also change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>.

Nearly everyone gets a positive test right, so no more needs to be said. The negative self tests are much more interesting, and you should concentrate on trying to make your program fail so you can verify its fails gracefully. Remember, a bad guy is not going to be courteous when he attempts to cause your program to fail. And its your project that takes egg on the face by way of a bug report or guest appearance on [http://www.grok.org.uk/full-disclosure/ Full Disclosure] or [http://www.securityfocus.com/archive Bugtraq] - not ''<nowiki><some library></nowiki>'' you included.

=== Auto Tools ===

Auto configuration tools are popular on many Linux and Unix based systems, and the tools include ''Autoconf'', ''Automake'', ''config'', and ''Configure''. The tools work together to produce project files from scripts and template files. After the process completes, your project should be setup and ready to be made with <tt>make</tt>.

When using auto configuration tools, there are a few files of interest worth mentioning. The files are part of the auto tools chain and include <tt>m4</tt> and the various <tt>*.in</tt>, <tt>*.ac</tt> (autoconf), and <tt>*.am</tt> (automake) files. At times, you will have to open them, or the resulting makefiles, to tune the "stock" configuration.

There are three downsides to the command line configuration tools in the toolchain: (1) they often ignore user requests, (2) they cannot create configurations, and (3) security is often not a goal.

To demonstrate the first issue, confider your project with the following: <tt>configure CFLAGS="-Wall -fPIE" CXXFLAGS="-Wall -fPIE" LDFLAGS="-pie"</tt>. You will probably find the auto tools ignored your request, which means the command below will not produce expected results. As a work around, you will have to open an <tt>m4</tt> scripts, <tt>Makefile.in</tt> or <tt>Makefile.am</tt> and fix the configuration.

<pre>$ configure CFLAGS="-Wall -Wextra -Wconversion -fPIE -Wno-unused-parameter
-Wformat=2 -Wformat-security -fstack-protector-all -Wstrict-overflow"
LDFLAGS="-pie -z,noexecstack -z,noexecheap -z,relro -z,now"</pre>

For the second point, you will probably be disappointed to learn [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html Automake does not support the concept of configurations]. Its not entirely Autoconf's or Automake's fault - ''Make'' and its inability to detect changes is the underlying problem. Specifically, ''Make'' only [http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html checks modification times of prerequisites and targets], and does not check things like <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>. The net effect is you will not receive expected results when you issue <tt>make debug</tt> and then <tt>make test</tt> or <tt>make release</tt>.

Finally, you will probably be disappointed to learn tools such as Autoconf and Automake miss many security related opportunities and ship insecure out of the box. There are a number of compiler switches and linker flags that improve the defensive posture of a program, but they are not 'on' by default. Tools like Autoconf - which are supposed to handle this situation - often provides setting to serve the lowest of all denominators.

A recent discussion on the Automake mailing list illuminates the issue: ''[https://lists.gnu.org/archive/html/autoconf/2012-12/msg00038.html Enabling compiler warning flags]''. Attempts to improve default configurations were met with resistance and no action was taken. The resistance is often of the form, "<nowiki><some useful warning></nowiki> also produces false positives" or "<nowiki><some obscure platform></nowiki> does not support <nowiki><established security feature></nowiki>". Its noteworthy that David Wheeler, the author of ''[http://www.dwheeler.com/secure-programs/ Secure Programming for Linux and Unix HOWTO]'', was one of the folks trying to improve the posture.

=== Makefiles ===

Make is one of the earliest build systems dating back to the 1970s. Its available on Linux, Mac OS X and Unix, so you will frequently encounter projects using it. Unfortunately, Make has a number of short comings (''[http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful]'' and ''[http://www.conifersystems.com/whitepapers/gnu-make/ What’s Wrong With GNU make?]''), and can cause some discomfort. Despite issues with Make, ESAPI C++ uses Make primarily for three reasons: first, its omnipresent; second, its easier to manage than the Auto Tools family; and third, <tt>libtool</tt> was out of the question.

Consider what happens when you: (1) type <tt>make debug</tt>, and then type <tt>make release</tt>. Each build would require different <tt>CFLAGS</tt> due to optimizations and level of debug support. In your makefile, you would extract the relevant target and set <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> similar to below (taken from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/Makefile ESAPI C++ Makefile]):

<pre># Makefile
DEBUG_GOALS = $(filter $(MAKECMDGOALS), debug)
ifneq ($(DEBUG_GOALS),)
WANT_DEBUG := 1
WANT_TEST := 0
WANT_RELEASE := 0
endif
…

ifeq ($(WANT_DEBUG),1)
ESAPI_CFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
ESAPI_CXXFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
endif

ifeq ($(WANT_RELEASE),1)
ESAPI_CFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
ESAPI_CXXFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
endif

ifeq ($(WANT_TEST),1)
ESAPI_CFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
ESAPI_CXXFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
endif
…

# Merge ESAPI flags with user supplied flags. We perform the extra step to ensure
# user options follow our options, which should give user option's a preference.
override CFLAGS := $(ESAPI_CFLAGS) $(CFLAGS)
override CXXFLAGS := $(ESAPI_CXXFLAGS) $(CXXFLAGS)
override LDFLAGS := $(ESAPI_LDFLAGS) $(LDFLAGS)
…</pre>

Make will first build the program in a debug configuration for a session under the debugger using a rule similar to:

<pre>%.cpp:%.o:
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@</pre>

When you want the release build, Make will do nothing because it considers everything up to date despite the fact <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> have changed. Hence, your program will actually be in a debug configuration and risk a <tt>SIGABRT</tt> at runtime because debug instrumentation is present (recall <tt>assert</tt> calls <tt>abort()</tt> when <tt>NDEBUG</tt> is '''not''' defined). In essence, you have DoS'd yourself due to <tt>make</tt>.

In addition, many projects do not honor the user's command line. ESAPI C++ does its best to ensure a user's flags are honored via <tt>override</tt> as shown above, but other projects do not. For example, consider a project that should be built with Position Independent Executable (PIE or ASLR) enabled and data execution prevention (DEP) enabled. Dismissing user settings combined with insecure out of the box settings (and not picking them up during auto-setup or auto-configure) means a program built with the following will likely have neither defense:

<pre>$ make CFLAGS="-fPIE" CXXFLAGS="-fPIE" LDFLAGS="-pie -z,noexecstack, -z,noexecheap"</pre>

Defenses such as ASLR and DEP are especially important on Linux because [http://linux.die.net/man/5/elf Data Execution - not Prevention - is the norm].

=== Integration ===

Project level integration presents opportunities to harden your program or library with domain specific knowledge. For example, if the platform supports Position Independent Executables (PIE or ASLR) and data execution prevention (DEP), then you should integrate with it. The consequences of not doing so could result in exploitation. As a case in point, see KingCope's 0-days for MySQL in December, 2012 (CVE-2012-5579 and CVE-2012-5612, among others). Integration with platform security would have neutered a number of the 0-days.

You also have the opportunity to include helpful libraries that are not need for business logic support. For example, if you are working on a platform with [http://dmalloc.com DMalloc] or [http://code.google.com/p/address-sanitizer/ Address Sanitizer], you should probably use it in your debug builds. For Ubuntu, DMalloc available from the package manager and can be installed with <tt>sudo apt-get install libdmalloc5</tt>. For Apple platforms, its available as a scheme option (see [[#Clang/Xcode|Clang/Xcode]] below). Address Sanitizer is available in [http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8 and above] for many platforms.

In addition, project level integration is an opportunity to harden third party libraries you chose to include. Because you chose to include them, you and your users are responsible for them. If you or your users endure a SP800-53 audit, third party libraries will be in scope because the supply chain is included (specifically, item SA-12, Supply Chain Protection). The audits are not limited to those in the US Federal arena - financial institutions perform reviews too. A perfect example of violating this guidance is [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525], which was due to [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library].

Another example is including OpenSSL. You know (1) [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 is insecure], (2) [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 is insecure], and (3) [http://arstechnica.com/security/2012/09/crime-hijacks-https-sessions/ compression is insecure] (among others). In addition, suppose you don't use hardware and engines, and only allow static linking. Given the knowledge and specifications, you would configure the OpenSSL library as follows:

<pre>$ Configure darwin64-x86_64-cc -no-hw -no-engines -no-comp -no-shared -no-dso -no-sslv2 -no-sslv3 --openssldir=…</pre>

''Note Well'': you might want engines, especially on Ivy Bridge microarchitectures (3rd generation Intel Core i5 and i7 processors). To have OpenSSL use the processor's random number generator (via the of <tt>rdrand</tt> instruction), you will need to call OpenSSL's <tt>ENGINE_load_rdrand()</tt> function and then <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. See [http://wiki.opensslfoundation.com/index.php/Random_Numbers OpenSSL's Random Numbers] for details.

If you configure without the switches, then you will likely have vulnerable code/libraries and risk failing an audit. If the program is a remote server, then the following command will reveal if compression is active on the channel:

<pre>$ echo "GET / HTTP1.0" | openssl s_client -connect <nowiki>example.com:443</nowiki></pre>

<tt>nm</tt> or <tt>openssl s_client</tt> will show that compression is enabled in the client. In fact, any symbol within the <tt>OPENSSL_NO_COMP</tt> preprocessor macro will bear witness since <tt>-no-comp</tt> is translated into a <tt>CFLAGS</tt> define.

<pre>$ nm /usr/local/ssl/iphoneos/lib/libcrypto.a 2>/dev/null | egrep -i "(COMP_CTX_new|COMP_CTX_free)"
0000000000000110 T COMP_CTX_free
0000000000000000 T COMP_CTX_new</pre>

Even more egregious is the answer given to auditors who specifically ask about configurations and protocols: "we don't use weak/wounded/broken ciphers" or "we follow best practices." The use of compression tells the auditor that you are using wounded protocol in an insecure configuration and you don't follow best practices. That will likely set off alarm bells, and ensure the auditor dives deeper on more items.

== Preprocessor ==

The preprocessor is crucial to setting up a project for success. The C committee provided one macro - <tt>NDEBUG</tt> - and the macro can be used to derive a number of configurations and drive engineering processes. Unfortunately, the committee also left many related items to chance, which has resulted in programmers abusing builtin facilities. This section will help you set up you projects to integrate well with other projects and ensure reliability and security.

There are three topics to discuss when hardening the preprocessor. The first is well defined configurations which produce well defined behaviors, the second is useful behavior from assert, and the third is proper use of macros when integrating vendor code and third party libraries.

=== Configurations ===

To remove ambiguity, you should recognize two configurations: Release and Debug. Release is for production code on live servers, and its behavior is requested via the C/C++ <tt>NDEBUG</tt> macro. Its also the only macro observed by the C and C++ Committees and Posix. Diametrically opposed to release is Debug. While there is a compelling argument for <tt>!defined(NDEBUG)</tt>, you should have an explicit macro for the configuration and that macro should be <tt>DEBUG</tt>. This is because vendors and outside libraries use <tt>DEBUG</tt> (or similar) macro for their configuration. For example, Carnegie Mellon's Mach kernel uses <tt>DEBUG</tt>, Microsoft's CRT uses [http://msdn.microsoft.com/en-us/library/ww5t02fa%28v=vs.71%29.aspx<tt>_DEBUG</tt>], and Wind River Workbench uses <tt>DEBUG_MODE</tt>.

In addition to <tt>NDEBUG</tt> (Release) and <tt>DEBUG</tt> (Debug), you have two additional cross products: both are defined or neither are defined. Defining both should be an error, and defining neither should default to a release configuration. Below is from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/esapi/EsapiCommon.h ESAPI C++ EsapiCommon.h], which is the configuration file used by all source files:

<pre>// Only one or the other, but not both
#if (defined(DEBUG) || defined(_DEBUG)) && (defined(NDEBUG) || defined(_NDEBUG))
# error Both DEBUG and NDEBUG are defined.
#endif

// The only time we switch to debug is when asked. NDEBUG or {nothing} results
// in release build (fewer surprises at runtime).
#if defined(DEBUG) || defined(_DEBUG)
# define ESAPI_BUILD_DEBUG 1
#else
# define ESAPI_BUILD_RELEASE 1
#endif</pre>

When <tt>DEBUG</tt> is in effect, your code should receive full debug instrumentation, including the full force of assertions.

=== ASSERT ===

Asserts will help you create self-debugging code by helping you find the point of first failure quickly and easily. Asserts should be used throughout your program, including parameter validation, return value checking and program state. The <tt>assert</tt> will silently guard your code through its lifetime. It will always be there, even when not debugging a specific component of a module. If you have thorough code coverage, you will spend less time debugging and more time developing because programs will debug themselves.

To use asserts effectively, you should assert everything. That includes parameters upon entering a function, return values from function calls, and any program state. Everywhere you place an <tt>if</tt> statement for validation or checking, you should have an assert. Everywhere you have an <tt>assert</tt> for validation or checking, you should have an <tt>if</tt> statement. They go hand-in-hand.

If you are still using <tt>printf</tt>'s, then you have an opportunity for improvement. In the time it takes for you to write a <tt>printf</tt> or <tt>NSLog</tt> statement, you could have written an <tt>assert</tt>. Unlike the <tt>printf</tt> or <tt>NSLog</tt> which are often removed when no longer needed, the <tt>assert</tt> stays active forever. Remember, this is all about finding the point of first failure quickly so you can spend your time doing other things.

There is one problem with using asserts - [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html Posix states <tt>assert</tt> should call <tt>abort()</tt>] if <tt>NDEBUG</tt> is '''not''' defined. When debugging, <tt>NDEBUG</tt> will never be defined since you want the "program diagnostics" (quote from the Posix description). The behavior makes <tt>assert</tt> and its accompanying <tt>abort()</tt> completely useless for development. The result of "program diagnostics" calling <tt>abort()</tt> due to standard C/C++ behavior is disuse - developers simply don't use them. Its incredibly bad for the development community because self-debugging programs can help eradicate so many stability problems.

Since self-debugging programs are so powerful, you will have to have to supply your own assert and signal handler with improved behavior. Your assert will exchange auto-aborting behavior for auto-debugging behavior. The auto-debugging facility will ensure the debugger snaps when a problem is detected, and you will find the point of first failure quickly and easily.

ESAPI C++ supplies its own assert with the behavior described above. In the code below, <tt>ASSERT</tt> raises <tt>SIGTRAP</tt> when in effect or it evaluates to <tt>void</tt> in other cases.

<pre>// A debug assert which should be sprinkled liberally. This assert fires and then continues rather
// than calling abort(). Useful when examining negative test cases from the command line.
#if (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_STARNIX))
# define ESAPI_ASSERT1(exp) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
# define ESAPI_ASSERT2(exp, msg) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< ": \"" << (msg) << "\"" << std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
#elif (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_WINDOWS))
# define ESAPI_ASSERT1(exp) assert(exp)
# define ESAPI_ASSERT2(exp, msg) assert(exp)
#else
# define ESAPI_ASSERT1(exp) ((void)(exp))
# define ESAPI_ASSERT2(exp, msg) ((void)(exp))
#endif

#if !defined(ASSERT)
# define ASSERT(exp) ESAPI_ASSERT1(exp)
#endif</pre>

At program startup, a <tt>SIGTRAP</tt> handler will be installed if one is not provided by another component:

<pre>struct DebugTrapHandler
{
DebugTrapHandler()
{
struct sigaction new_handler, old_handler;

do
{
int ret = 0;

ret = sigaction (SIGTRAP, NULL, &old_handler);
if (ret != 0) break; // Failed

// Don't step on another's handler
if (old_handler.sa_handler != NULL) break;

new_handler.sa_handler = &DebugTrapHandler::NullHandler;
new_handler.sa_flags = 0;

ret = sigemptyset (&new_handler.sa_mask);
if (ret != 0) break; // Failed

ret = sigaction (SIGTRAP, &new_handler, NULL);
if (ret != 0) break; // Failed

} while(0);
}

static void NullHandler(int /*unused*/) { }

};

// We specify a relatively low priority, to make sure we run before other CTORs
// http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#C_002b_002b-Attributes
static const DebugTrapHandler g_dummyHandler __attribute__ ((init_priority (110)));</pre>

On a Windows platform, you would call <tt>_set_invalid_parameter_handler</tt> (and possibly <tt>set_unexpected</tt> or <tt>set_terminate</tt>) to install a new handler.

Live hosts running production code should always define <tt>NDEBUG</tt> (i.e., release configuration), which means they do not assert or auto-abort. Auto-abortion is not acceptable behavior, and anyone who asks for the behavior is completely abusing the functionality of "program diagnostics". If a program wants a core dump, then it should create the dump rather than crashing.

For more reading on asserting effectively, please see one of John Robbin's books, such as ''[http://www.amazon.com/dp/0735608865 Debugging Applications]''. John is a legendary bug slayer in Windows circles, and he will show you how to do nearly everything, from debugging a simple program to bug slaying in multithreaded programs.

=== Additional Macros ===

Additional macros include any macros needed to integrate properly and securely. It includes integrating the program with the platform (for example MFC or Cocoa/CocoaTouch) and libraries (for example, Crypto++ or OpenSSL). It can be a challenge because you have to have proficiency with your platform and all included libraries and frameworks. The list below illustrates the level of detail you will need when integrating.

Though Boost is missing from the list, it appears to lack recommendations, additional debug diagnostics, and a hardening guide. See ''[http://stackoverflow.com/questions/14927033/boost-hardening-guide-preprocessor-macros BOOST Hardening Guide (Preprocessor Macros)]'' for details. In addition, Tim Day points to ''[http://boost.2283326.n4.nabble.com/boost-build-should-we-not-define-SECURE-SCL-0-by-default-for-all-msvc-toolsets-td2654710.html <nowiki>[boost.build] should we not define _SECURE_SCL=0 by default for all msvc toolsets</nowiki>]'' for a recent discussion related to hardening (or lack thereof).

In addition to what you should define, defining some macros and undefining others should trigger a security related defect. For example, <tt>-U_FORTIFY_SOURCES</tt> on Linux and <tt>_CRT_SECURE_NO_WARNINGS=1</tt>, <tt>_SCL_SECURE_NO_WARNINGS</tt>, <tt>_ATL_SECURE_NO_WARNINGS</tt> or <tt>STRSAFE_NO_DEPRECATE</tt> on Windows.

{| border="1"

|-style="background:#DADADA"
!Platform/Library!!Debug!!Release
|+ Table 1: Additional Platform/Library Macros

|-
|width="175pt"|All
|width="250pt"|DEBUG=1
|width="250pt"|NDEBUG=1

|-
|Linux
|_GLIBCXX_DEBUG=1a
|_FORTIFY_SOURCE=2

|-
|Android
|NDK_DEBUG=1
|_FORTIFY_SOURCE=1 (4.2 and above) 
<tt>#define LOGI(...)</tt> (define to nothing, preempt logging)

|-
|Cocoa/CocoaTouch
|
|NS_BLOCK_ASSERTIONS=1 
<tt>#define NSLog(...)</tt> (define to nothing, preempt ASL)

|-
|SafeInt
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1

|-
|Microsoft
|_DEBUG=1, STRICT, 
_SECURE_SCL=1, _HAS_ITERATOR_DEBUGGING=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1
|STRICT 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1

|-
|Microsoft ATL & MFC
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS

|-
|STLPort
|_STLP_DEBUG=1, _STLP_USE_DEBUG_LIB=1 
_STLP_DEBUG_ALLOC=1, _STLP_DEBUG_UNINITIALIZED=1
|

|-
|SQLite
|SQLITE_DEBUG, SQLITE_MEMDEBUG 
SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc
|SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc

|-
|SQLCipher
|Remove '''<tt>NDEBUG</tt>''' from Debug builds (Xcode) 
SQLITE_HAS_CODEC=1
|SQLITE_HAS_CODEC=1

|-
|SQLite/SQLCipher
|SQLITE_TEMP_STORE=3d
|SQLITE_TEMP_STORE=3d

|}

a Be careful with <tt>_GLIBCXX_DEBUG</tt> when using pre-compiled libraries such as Boost from a distribution. There are ABI incompatibilities, and the result will likely be a crash. You will have to compile Boost with <tt>_GLIBCXX_DEBUG</tt> or omit <tt>_GLIBCXX_DEBUG</tt>.

b SQLite secure deletion zeroizes memory on destruction. Define as required, and always define in US Federal since zeroization is required for FIPS 140-2, Level 1.

c ''N'' is 0644 by default, which means everyone has some access.

d Force temporary tables into memory (no unencrypted data to disk).

== Compiler and Linker ==

Compiler writers provide a rich set of warnings from the analysis of code during compilation. Both GCC and Visual Studio have static analysis capabilities to help find mistakes early in the development process. The built in static analysis capabilities of GCC and Visual Studio are usually sufficient to ensure proper API usage and catch a number of mistakes such as using an uninitialized variable or comparing a negative signed int and a positive unsigned int.

As a concrete example, (and for those not familiar with C/C++ promotion rules), a warning will be issued if a signed integer is promoted to an unsigned integer and then compared because a side effect is <tt>-1 > 1</tt> after promotion! GCC and Visual Studio will not currently catch, for example, SQL injections and other tainted data usage. For that, you will need a tool designed to perform data flow analysis or taint analysis.

Some in the development community resist static analysis or refute its results. For example, when static analysis warned the Linux kernel's <tt>sys_prctl</tt> was comparing an unsigned value against less than zero, Jesper Juhl offered a patch to clean up the code. Linus Torvalds howled “No, you don't do this… GCC is crap” (referring to compiling with warnings). For the full discussion, see ''[http://linux.derkeiler.com/Mailing-Lists/Kernel/2006-11/msg08325.html <nowiki>[PATCH] Don't compare unsigned variable for <0 in sys_prctl()</nowiki>]'' from the Linux Kernel mailing list.

The following sections will detail steps for three platforms. First is a typical GNU Linux based distribution offering GCC and Binutils, second is Clang and Xcode, and third is modern Windows platforms.

=== Distribution Hardening ===

Before discussing GCC and Binutils, it would be a good time to point out some of the defenses discussed below are all ready present in a distribution. Unfortunately, its design by committee, so what is present is usually only a mild variation of what is available (this way, everyone is mildly offended). For those who are purely worried about performance, you might be surprised to learn you have already taken the small performance hint without even knowing.

Linux and BSD distributions often apply some hardening without intervention via ''[http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html GCC Spec Files]''. If you are using Debian, Ubuntu, Linux Mint and family, see ''[http://wiki.debian.org/Hardening Debian Hardening]''. For Red Hat and Fedora systems, see ''[http://lists.fedoraproject.org/pipermail/devel-announce/2011-August/000821.html New hardened build support (coming) in F16]''. Gentoo users should visit ''[http://www.gentoo.org/proj/en/hardened/ Hardened Gentoo]''.

You can see the settings being used by a distribution via <tt>gcc -dumpspecs</tt>. From Linux Mint 12 below, -fstack-protector (but not -fstack-protector-all) is used by default.

<pre>$ gcc -dumpspecs
…
*link_ssp: %{fstack-protector:}

*ssp_default: %{!fno-stack-protector:%{!fstack-protector-all: %{!ffreestanding:%{!nostdlib:-fstack-protector}}}}
…</pre>

The “SSP” above stands for Stack Smashing Protector. SSP is a reimplementation of Hiroaki Etoh's work on IBM Pro Police Stack Detector. See Hiroaki Etoh's patch ''[http://gcc.gnu.org/ml/gcc-patches/2001-06/msg01753.html gcc stack-smashing protector]'' and IBM's ''[http://www.research.ibm.com/trl/projects/security/ssp/ GCC extension for protecting applications from stack-smashing attacks]'' for details.

=== GCC/Binutils ===

GCC (the compiler collection) and Binutils (the assemblers, linkers, and other tools) are separate projects that work together to produce a final executable. Both the compiler and linker offer options to help you write safer and more secure code. The linker will produce code which takes advantage of platform security features offered by the kernel and PaX, such as no-exec stacks and heaps (NX) and Position Independent Executable (PIE).

The table below offers a set of compiler options to build your program. Static analysis warnings help catch mistakes early, while the linker options harden the executable at runtime. In the table below, “GCC” should be loosely taken as “non-ancient distributions.” While the GCC team considers 4.2 ancient, you will still encounter it on Apple and BSD platforms due to changes in GPL licensing around 2007. Refer to ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Option Summary]'', ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html Options to Request or Suppress Warnings]'' and ''[http://sourceware.org/binutils/docs-2.21/ld/Options.html Binutils (LD) Command Line Options]'' for usage details.

Noteworthy of special mention are <tt>-fno-strict-overflow</tt> and <tt>-fwrapv</tt>a. The flags ensure the compiler does not remove statements that result in overflow or wrap. If your program only runs correctly using the flags, it is likely violating C/C++ rules on overflow and illegal. If the program is illegal due to overflow or wrap checking, you should consider using [http://code.google.com/p/safe-iop/ safe-iop] for C or David LeBlanc's [http://safeint.codeplex.com SafeInt] in C++.

For a project compiled and linked with hardened settings, some of those settings can be verified with the [http://www.trapkit.de/tools/checksec.html Checksec] tool written by Tobias Klein. The <tt>checksec.sh</tt> script is designed to test standard Linux OS and PaX security features being used by an application. See the [http://www.trapkit.de/tools/checksec.html Trapkit] web page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 2: GCC C Warning Options

|-
|width="200pt"|<nowiki>-Wall -Wextra</nowiki>
|width="75t"|GCC
|width="425pt"|Enables many warnings (despite their names, all and extra do not turn on all warnings).a

|-
|<nowiki>-Wconversion</nowiki>
|GCC
|Warn for implicit conversions that may alter a value (includes -Wsign-conversion).

|-
|<nowiki>-Wsign-conversion</nowiki>
|GCC
|Warn for implicit conversions that may change the sign of an integer value, such as assigning a signed integer to an unsigned integer (<tt>-1 > 1</tt> after promotion!).

|-
|<nowiki>-Wcast-align</nowiki>
|GCC
|Warn for a pointer cast to a type which has a different size, causing an invalid alignment and subsequent bus error on ARM processors.

|-
|<nowiki>-Wformat=2 -Wformat-security</nowiki>
|GCC
|Increases warnings related to possible security defects, including incorrect format specifiers.

|-
|<nowiki>-fno-common</nowiki>
|GCC
|Prevent global variables being simultaneously defined in different object files.

|-
|<nowiki>-fstack-protector or -fstack-protector-all</nowiki>
|GCC
|Stack Smashing Protector (SSP). Improves stack layout and adds a guard to detect stack based buffer overflows.b

|-
|<nowiki>-fno-omit-frame-pointer</nowiki>
|GCC
|Improves backtraces for post-mortem analysis

|-
|<nowiki>-Wmissing-prototypes and -Wmissing-declarations</nowiki>
|GCC
|Warn if a global function is defined without a prototype or declaration.

|-
|<nowiki>-Wstrict-prototypes</nowiki>
|GCC
|Warn if a function is declared or defined without specifying the argument types.

|-
|<nowiki>-Wstrict-overflow</nowiki>
|GCC 4.2
|Warn about optimizations taken due to <nowiki>[undefined]</nowiki> signed integer overflow assumptions.

|-
|<nowiki>-Wtrampolines</nowiki>
|GCC 4.3
|Warn about trampolines generated for pointers to nested functions. Trampolines require executable stacks.

|-
|<nowiki>-fsanitize=address</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/address-sanitizer/ AddressSanitizer], a fast memory error detector. Memory access instructions will be instrumented to help detect heap, stack, and global buffer overflows; as well as use-after-free bugs.

|-
|<nowiki>-fsanitize=thread</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/data-race-test/wiki/ThreadSanitizer ThreadSanitizer], a fast data race detector. Memory access instructions will be instrumented to detect data race bugs.

|-
|<nowiki>-Wl,-z,nodlopen and -Wl,-z,nodump</nowiki>
|Binutils 2.10
|Reduces the ability of an attacker to load, manipulate, and dump shared objects.

|-
|<nowiki>-Wl,-z,noexecstack and -Wl,-z,noexecheap</nowiki>
|Binutils 2.14
|Data Execution Prevention (DEP). ELF headers are marked with PT_GNU_STACK and PT_GNU_HEAP.

|-
|<nowiki>-Wl,-z,relro</nowiki>
|Binutils 2.15
|Helps remediate Global Offset Table (GOT) attacks on executables.

|-
|<nowiki>-Wl,-z,now</nowiki>
|Binutils 2.15
|Helps remediate Procedure Linkage Table (PLT) attacks on executables.

|-
|<nowiki>-fPIC</nowiki>
|Binutils
|Position Independent Code. Used for libraries and shared objects. Both -fPIC (compiler) and -shared (linker) are required.

|-
|<nowiki>-fPIE</nowiki>
|Binutils 2.16
|Position Independent Executable (ASLR). Used for programs. Both -fPIE (compiler) and -pie (linker) are required.

|}

a Unlike Clang and -Weverything, GCC does not provide a switch to truly enable all warnings. 
b -fstack-protector guards functions with high risk objects such as C strings, while -fstack-protector-all guards all objects.

Additional C++ warnings which can be used include the following in Table 3. See ''[http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html GCC's Options Controlling C++ Dialect]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 3: GCC C++ Warning Options

|-
|width="200pt"|<nowiki>-Woverloaded-virtual</nowiki>
|width="425pt"|Warn when a function declaration hides virtual functions from a base class.

|-
|<nowiki>-Wreorder</nowiki>
|Warn when the order of member initializers given in the code does not match the order in which they must be executed.

|-
|<nowiki>-Wsign-promo</nowiki>
|Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size.

|-
|<nowiki>-Wnon-virtual-dtor</nowiki>
|Warn when a class has virtual functions and an accessible non-virtual destructor.

|-
|<nowiki>-Weffc++</nowiki>
|Warn about violations of the following style guidelines from Scott Meyers' ''[http://www.aristeia.com/books.html Effective C++, Second Edition]'' book.

|}

And additional Objective C warnings which are often useful include the following. See ''[http://gcc.gnu.org/onlinedocs/gcc/Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html Options Controlling Objective-C and Objective-C++ Dialects]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 4: GCC Objective C Warning Options

|-
|width="200pt"|<nowiki>-Wstrict-selector-match</nowiki>
|width="425pt"|Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type id or Class.

|-
|<nowiki>-Wundeclared-selector</nowiki>
|Warn if a <tt>@selector(…)</tt> expression referring to an undeclared selector is found.

|}

The use of aggressive warnings will produce spurious noise. The noise is a tradeoff - you can learn of potential problems at the cost of wading through some chaff. The following will help reduces spurious noise from the warning system:

* -Wno-unused-parameter (GCC)
* -Wno-type-limits (GCC 4.3)
* -Wno-tautological-compare (Clang)

Finally, a simple version based Makefile example is shown below. This is different than feature based makefile produced by auto tools (which will test for a particular feature and then define a symbol or configure a template file). Not all platforms use all options and flags. To address the issue you can pursue one of two strategies. First, you can ship with a weakened posture by servicing the lowest common denominator; or you can ship with everything in force. In the latter case, those who don't have a feature available will edit the makefile to accommodate their installation.

<pre>CXX=g++
EGREP = egrep
…

GCC_COMPILER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version')
GCC41_OR_LATER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version (4\.[1-9]|[5-9])')
…

GNU_LD210_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[0-9]|2\.[2-9])')
GNU_LD214_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[4-9]|2\.[2-9])')
…

ifeq ($(GCC_COMPILER),1)
MY_CC_FLAGS += -Wall -Wextra -Wconversion
MY_CC_FLAGS += -Wformat=2 -Wformat-security
MY_CC_FLAGS += -Wno-unused-parameter
endif

ifeq ($(GCC41_OR_LATER),1)
MY_CC_FLAGS += -fstack-protector-all
endif

ifeq ($(GCC42_OR_LATER),1)
MY_CC_FLAGS += -Wstrict-overflow
endif

ifeq ($(GCC43_OR_LATER),1)
MY_CC_FLAGS += -Wtrampolines
endif

ifeq ($(GNU_LD210_OR_LATER),1)
MY_LD_FLAGS += -z,nodlopen -z,nodump
endif

ifeq ($(GNU_LD214_OR_LATER),1)
MY_LD_FLAGS += -z,noexecstack -z,noexecheap
endif

ifeq ($(GNU_LD215_OR_LATER),1)
MY_LD_FLAGS += -z,relro -z,now
endif

ifeq ($(GNU_LD216_OR_LATER),1)
MY_CC_FLAGS += -fPIE
MY_LD_FLAGS += -pie
endif

# Use 'override' to honor the user's command line
override CFLAGS := $(MY_CC_FLAGS) $(CFLAGS)
override CXXFLAGS := $(MY_CC_FLAGS) $(CXXFLAGS)
override LDFLAGS := $(MY_LD_FLAGS) $(LDFLAGS)
…</pre>

=== Clang/Xcode ===

[http://clang.llvm.org Clang] and [http://llvm.org LLVM] have been aggressively developed since Apple lost its GPL compiler back in 2007 (due to Tivoization which resulted in GPLv3). Since that time, a number of developers and Goggle have joined the effort. While Clang will consume most (all?) GCC/Binutil flags and switches, the project supports a number of its own options, including a static analyzer. In addition, Clang is relatively easy to build with additional diagnostics, such as Dr. John Regher and Peng Li's [http://embed.cs.utah.edu/ioc/ Integer Overflow Checker (IOC)].

IOC is incredibly useful, and has found bugs in a number of projects, from the Linux Kernel (<tt>include/linux/bitops.h</tt>, still unfixed), SQLite, PHP, Firefox (many still unfixed), LLVM, and Python. Future version of Clang (Clang 3.3 and above) will allow you to enable the checks out of the box with <tt>-fsanitize=integer</tt> and <tt>-fsanitize=shift</tt>.

Clang options can be found at [http://clang.llvm.org/docs/UsersManual.html Clang Compiler User’s Manual]. Clang does include an option to turn on all warnings - <tt>-Weverything</tt>. Use it with care but use it regularly since you will get back a lot of noise and issues you missed. For example, add <tt>-Weverything</tt> for production builds and make non-spurious issues a quality gate. Under Xcode, simply add <tt>-Weverything</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>.

In addition to compiler warnings, both static analysis and additional security checks can be performed. Reading on Clang's static analysis capabilities can be found at [http://clang-analyzer.llvm.org Clang Static Analyzer]. Figure 1 below shows some of the security checks utilized by Xcode.

{| align="center"
| [[File:toolchan-hardening-11.png|thumb|450px|Figure 1: Clang/LLVM and Xcode options]]
|}

=== Visual Studio ===

Visual Studio offers a convenient Integrated Development Environment (IDE) for managing solutions and their settings. the section called “Visual Studio Options” discusses option which should be used with Visual Studio, and the section called “Project Properties” demonstrates incorporating those options into a solution's project.

The table below lists the compiler and linker switches which should be used under Visual Studio. Refer to Howard and LeBlanc's Writing Secure Code (Microsoft Press) for a detailed discussion; or ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]'' in Security Briefs by Michael Howard. In the table below, “Visual Studio” refers to nearly all versions of the development environment, including Visual Studio 5.0 and 6.0.

For a project compiled and linked with hardened settings, those settings can be verified with BinScope. BinScope is a verification tool from Microsoft that analyzes binaries to ensure that they have been built in compliance with Microsoft's Security Development Lifecycle (SDLC) requirements and recommendations. See the ''[https://www.microsoft.com/download/en/details.aspx?id=11910 BinScope Binary Analyzer]'' download page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 5: Visual Studio Warning Options

|-
|width="150pt"|<nowiki>/W4</nowiki>
|width="100pt"|Visual Studio
|width="350pt"|Warning level 4, which includes most warnings.

|-
|<nowiki>/WAll</nowiki>
|Visual Studio 2003
|Enable all warnings, including those off by default.a

|-
|<nowiki>/GS</nowiki>
|Visual Studio 2003
|Adds a security cookie (guard or canary) on the stack before the return address buffer stack based for overflow checks.a

|-
|<nowiki>/SafeSEH</nowiki>
|Visual Studio 2003
|Safe structured exception handling to remediate SEH overwrites.

|-
|<nowiki>/analyze</nowiki>
|Visual Studio 2005
|Enterprise code analysis (freely available with Windows SDK for Windows Server 2008 and .NET Framework 3.5).

|-
|<nowiki>/NXCOMPAT</nowiki>
|Visual Studio 2005
|Data Execution Prevention (DEP).

|-
|<nowiki>/dynamicbase</nowiki>
|Visual Studio 2005 SP1
|Address Space Layout Randomization (ASLR).

|-
|<nowiki>strict_gs_check</nowiki>
|Visual Studio 2005 SP1
|Aggressively applies stack protections to a source file to help detect some categories of stack based buffer overruns.b

|}

aSee Jon Sturgeon's discussion of the switch at ''[https://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx Off By Default Compiler Warnings in Visual C++]''. 
aWhen using /GS, there are a number of circumstances which affect the inclusion of a security cookie. For example, the guard is not used if there is no buffer in the stack frame, optimizations are disabled, or the function is declared naked or contains inline assembly. 
b<tt>#pragma strict_gs_check(on)</tt> should be used sparingly, but is recommend in high risk situations, such as when a source file parses input from the internet.

=== Warn Suppression ===

From the tables above, a lot of warnings have been enabled to help detect possible programming mistakes. The potential mistakes are detected via compiler which carries around a lot of contextual information during its code analysis phase. At times, you will receive spurious warnings because the compiler is not ''that'' smart. Its understandable and even a good thing (how would you like to be out of a job because a program writes its own programs?). At times you will have to learn how to work with the compiler's warning system to suppress warnings. Notice what was not said: turn off the warnings.

Suppressing warnings placates the compiler for spurious noise so you can get to the issues that matter (you are separating the wheat from the chaff). This section will offer some hints and point out some potential minefields. First is an unused parameter (for example, <tt>argc</tt> or <tt>argv</tt>). Suppressing unused parameter warnings is especially helpful for C++ and interface programming, where parameters are often unused. For this warning, simply define an "UNUSED" macro and warp the parameter:

<pre>#define UNUSED_PARAMETER(x) ((void)x)
…

int main(int argc, char* argv[])
{
UNUSED_PARAMETER(argc);
UNUSED_PARAMETER(argv);
…
}</pre>

A potential minefield lies near "comparing unsigned and signed" values, and <tt>-Wconversion</tt> will catch it for you. This is because C/C++ promotion rules state the signed value will be promoted to an unsigned value and then compared. That means <tt>-1 > 1</tt> after promotion! To fix this, you cannot blindly cast - you must first range test the value:

<pre>int x = GetX();
unsigned int y = GetY();

ASSERT(x >= 0);
if(!(x >= 0))
throw runtime_error("WTF??? X is negative.");

if(static_cast<unsigned int>(x) > y)
cout << "x is greater than y" << endl;
else
cout << "x is not greater than y" << endl;</pre>

Notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>x</tt>. Just run the program and wait for it to tell you there is a problem. If there is a problem, the program will snap the debugger (and more importantly, not call a useless <tt>abort()</tt> as specified by Posix). It beats the snot out of <tt>printf</tt> that are removed when no longer needed or pollute outputs.

Another conversion problem you will encounter conversion between types, and <tt>-Wconversion</tt> will also catch it for you. The following will always have an opportunity to fail, and should light up like a Christmas tree:

<pre>struct sockaddr_in addr;
…

addr.sin_port = htons(atoi(argv[2]));</pre>

The following would probably serve you much better. Notice <tt>atoi</tt> and fiends are not used because they can silently fail. In addition, the code is instrumented so you don't need to waste a lot of time debugging potential problems:

<pre>const char* cstr = GetPortString();

ASSERT(cstr != NULL);
if(!(cstr != NULL))
throw runtime_error("WTF??? Port string is not valid.");

istringstream iss(cstr);
long long t = 0;
iss >> t;

ASSERT(!(iss.fail()));
if(iss.fail())
throw runtime_error("WTF??? Failed to read port.");

// Should this be a port above the reserved range ([0-1024] on Unix)?
ASSERT(t > 0);
if(!(t > 0))
throw runtime_error("WTF??? Port is too small");

ASSERT(t < static_cast<long long>(numeric_limits<unsigned int>::max()));
if(!(t < static_cast<long long>(numeric_limits<unsigned int>::max())))
throw runtime_error("WTF??? Port is too large");

// OK to use port
unsigned short port = static_cast<unsigned short>(t);
…</pre>

Again, notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>port</tt>. This code will continue checking conditions, years after being instrumented (assuming to wrote code to read a config file early in the project). There's no need to remove the <tt>ASSERT</tt>s as with <tt>printf</tt> since they are silent guardians.

Another useful suppression trick is too avoid ignoring return values. Not only is it useful to suppress the warning, its required for correct code. For example, <tt>snprint</tt> will alert you to truncations through its return value. You should not make them silent truncations by ignoring the warning or casting to <tt>void</tt>:

<pre>char path[PATH_MAX];
…

int ret = snprintf(path, sizeof(path), "%s/%s", GetDirectory(), GetObjectName());
ASSERT(ret != -1);
ASSERT(!(ret >= sizeof(path)));

if(ret == -1 || ret >= sizeof(path))
throw runtime_error("WTF??? Unable to build full object name");

// OK to use path
…</pre>

The problem is pandemic, and not just boring user land programs. Projects which offer high integrity code, such as SELinux, suffer silent truncations. The following is from an approved SELinux patch even though a comment was made that it [http://permalink.gmane.org/gmane.comp.security.selinux/16845 suffered silent truncations in its <tt>security_compute_create_name</tt> function] from <tt>compute_create.c</tt>.

<pre>12 int security_compute_create_raw(security_context_t scon,
13 security_context_t tcon,
14 security_class_t tclass,
15 security_context_t * newcon)
16 {
17 char path[PATH_MAX];
18 char *buf;
19 size_t size;
20 int fd, ret;
21
22 if (!selinux_mnt) {
23 errno = ENOENT;
24 return -1;
25 }
26
27 snprintf(path, sizeof path, "%s/create", selinux_mnt);
28 fd = open(path, O_RDWR);</pre>

Unlike other examples, the above code will not debug itself, and you will have to set breakpoints and trace calls to determine the point of first failure. (And the code above gambles that the truncated file does not exist or is not under an adversary's control by blindly performing the <tt>open</tt>).

== Runtime ==

The previous sections concentrated on setting up your project for success. This section will examine additional hints for running with increased diagnostics and defenses. Not all platforms are created equal - GNU Linux is difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening to a program after compiling and static linking]; while Windows allows post-build hardening through a download. Remember, the goal is to find the point of first failure quickly so you can improve the reliability and security of the code.

=== Xcode ===

Xcode offers additional [http://developer.apple.com/library/mac/#recipes/xcode_help-scheme_editor/Articles/SchemeDiagnostics.html Application Diagnostics] that can help find memory errors and object use problems. Schemes can be managed through ''Products'' menu item, ''Scheme'' submenu item, and then ''Edit''. From the editor, navigate to the ''Diagnostics'' tab. In the figure below, four additional instruments are enabled for the debugging cycle: Scribble guards, Edge guards, Malloc guards, and Zombies.

{| align="center"
| [[File:toolchan-hardening-1.png|thumb|450px|Figure 2: Xcode Memory Diagnostics]]
|}

There is one caveat with using some of the guards: Apple only provides them for the simulator, and not a device. In the past, the guards were available for both devices and simulators.

=== Windows ===

Visual Studio offers a number of debugging aides for use during development. The aides are called [http://msdn.microsoft.com/en-us/library/d21c150d.aspx Managed Debugging Assistants (MDAs)]. You can find the MDAs on the ''Debug'' menu, then ''Exceptions'' submenu. MDAs allow you to tune your debugging experience by, for example, filter exceptions for which the debugger should snap. For more details, see Stephen Toub's ''[http://msdn.microsoft.com/en-us/magazine/cc163606.aspx Let The CLR Find Bugs For You With Managed Debugging Assistants]''.

{| align="center"
| [[File:toolchan-hardening-2.png|thumb|450px|Figure 3: Managed Debugging Assistants]]
|}

Finally, for runtime hardening, Microsoft has a helpful tool called EMET. EMET is the [http://support.microsoft.com/kb/2458544 Enhanced Mitigation Experience Toolkit], and allows you to apply runtime hardening to an executable which was built without. Its very useful for utilities and other programs that were built without an SDLC.

{| align="center"
| [[File:toolchan-hardening-3.png|thumb|450px|Figure 4: Windows and EMET]]
|}

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org

C-Based Toolchain Hardening

2013-03-08T18:00:17Z

Jeffrey Walton:

[[C-Based Toolchain Hardening]] is a treatment of project settings that will help you deliver reliable and secure code when using C, C++ and Objective C languages in a number of development environments. This article will examine Microsoft and GCC toolchains for the C, C++ and Objective C languages. It will guide you through the steps you should take to create executables with firmer defensive postures and increased integration with the available platform security. Effectively configuring the toolchain also means your project will enjoy a number of benefits during development, including enhanced warnings and static analysis, and self-debugging code.

There are four areas to be examined when hardening the toolchain: configuration, preprocessor, compiler, and linker. Nearly all areas are overlooked or neglected when setting up a project. The neglect appears to be pandemic, and it applies to nearly all projects including Auto-configured projects, Makefile-based, Eclipse-based, Visual Studio-based, and Xcode-based. Its important to address the gaps at build time because its difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening on a distributed executable after the fact] on some platforms.

This is a prescriptive article, and it will not debate semantics or speculate on behavior. Some information, such as the C/C++ committee's motivation and pedigree for [https://groups.google.com/a/isocpp.org/forum/?fromgroups=#!topic/std-discussion/ak8e1mzBhGs "program diagnostics", <tt>NDEBUG</tt>, <tt>assert</tt>, and <tt>abort()</tt>], appears to be lost like a tale in the Lord of the Rings. As such, the article will specify semantics (for example, the philosophy of 'debug' and 'release' build configurations), assign behaviors (for example, what an assert should do in a 'debug' and 'release' build configurations), and present a position. If you find the posture is too aggressive, then you should back off as required to suite your taste.

A secure toolchain is not a silver bullet. It is one piece of an overall strategy in the engineering process to help ensure success. It will compliment existing processes such as static analysis, dynamic analysis, secure coding, negative test suites, and the like. Tools such as Valgrind and Helgrind will still be needed. And a project will still require solid designs and architectures.

Finally, the OWASP [http://code.google.com/p/owasp-esapi-cplusplus/source ESAPI C++] project eats its own dog food. Many of the examples you will see in this article come directly from the ESAPI C++ project.

== Wisdom ==

Code '''must''' be correct. It '''should''' be secure. It '''can''' be efficient.

[http://en.wikipedia.org/wiki/Jon_Bentley Dr. Jon Bentley]: ''"If it doesn't have to be correct, I can make it as fast as you'd like it to be"''.

[http://en.wikipedia.org/wiki/Gary_McGraw Dr. Gary McGraw]: ''"Thou shalt not rely solely on security features and functions to build secure software as security is an emergent property of the entire system and thus relies on building and integrating all parts properly"''.

== Configuration ==

Configuration is the first opportunity to configure your project for success. Not only do you have to configure your project to meet reliability and security goals, you must also configure integrated libraries properly. You typically have has three choices. First, you can use auto-configuration utilities if on Linux or Unix. Second, you can write a makefile by hand. This is predominant on Linux, Mac OS X, and Unix, but it applies to Windows as well. Finally, you can use an integrated development environment or IDE.

=== Build Configurations ===

At this stage in the process, you should concentrate on configuring for two builds: Debug and Release. Debug will be used for development and include full instrumentation. Release will be configured for production. The difference between the two settings is usually ''optimization level'' and ''debug level''. A third build configuration is Test, and its usually a special case of Release.

For debug and release builds, the settings are typically diametrically opposed. Debug configurations have no optimizations and full debug information; while Release builds have optimizations and minimal to moderate debug information. In addition, debug code has full assertions and additional library integration, such as mudflaps and malloc guards such as <tt>dmalloc</tt>.

The Test configuration is often a Release configuration that makes everything public for testing and builds a test harness. For example, all member functions public (C++ class) and all interfaces (library or shared object) should be made available for testing. Many Object Oriented purist oppose testing private interfaces, but this is not about object oriented-ness. This (''q.v.'') is about building reliable and secure software.

[http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8] introduced an optimization of <tt>-Og</tt>. Note that it is only an optimization, and still requires a customary debug level via <tt>-g</tt>.

==== Debug Builds ====

Debug builds are where developers spend most of their time when vetting problems, so this build should concentrate forces and tools or be a 'force multiplier'. Though many do not realize, debug code is more highly valued than release code because its adorned with additional instrumentation. The debug instrumentation will cause a program to become nearly "self-debugging", and help you catch mistakes such as bad parameters, failed API calls, and memory problems.

Self-debugging code reduces your time during trouble shooting and debugging. Reducing time under the debugger means you have more time for development and feature requests. If code is checked in without debug instrumentation, it should be fixed by adding instrumentation or rejected.

For GCC, optimizations and debug symbolication are controlled through two switches: <tt>-O</tt> and <tt>-g</tt>. You should use the following as part of your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for a minimal debug session:

<pre>-O0 -g3 -ggdb</pre>

<tt>-O0</tt> turns off optimizations and <tt>-g3</tt> ensures maximum debug information is available. You may need to use <tt>-O1</tt> so some analysis is performed. Otherwise, your debug build will be missing a number of warnings not present in release builds. <tt>-g3</tt> ensures maximum debugging information is available for the debug session, including symbolic constants and <tt>#defines</tt>. <tt>-ggdb</tt> includes extensions to help with a debug session under GDB. For completeness, Jan Krachtovil stated <tt>-ggdb</tt> currently has no effect in a private email.

Debug build should also define <tt>DEBUG</tt>, and ensure <tt>NDEBUG</tt> is not defined. <tt>NDEBUG</tt> removes "program diagnostics"; and has undesirable behavior and side effects which discussed below in more detail. The defines should be present for all code, and not just the program. You use it for all code (your program and included libraries) because you need to know how they fails too (remember, you take the bug report - not the third party library).

In addition, you should also use other relevant flags, such as <tt>-fno-omit-frame-pointer</tt> and <tt>-fsanitize=address</tt>. Finally, you should also ensure your project includes additional diagnostic libraries, such as <tt>dmalloc</tt>. The additional flags and libraries are discussed below in more detail.

==== Release Builds ====

Release builds are what your customer receives. They are meant to be run on production hardware and servers, and they should be reliable, secure, and efficient. A stable release build is the product of the hard work and effort during development.

For release builds, you should use the following as part of <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> for release builds:

<pre>-On -g2</pre>

<tt>-O''n''</tt> sets optimizations for speed or size (for example, <tt>-Os</tt> or <tt>-O2</tt>), and <tt>-g2</tt> ensure debugging information is created.

Debugging information should be stripped and retained in case of symbolication for a crash report from the field. While not desired, debug information can be left in place without a performance penalty. See ''[http://gcc.gnu.org/ml/gcc-help/2005-03/msg00032.html How does the gcc -g option affect performance?]'' for details.

Release builds should also define <tt>NDEBUG</tt>, and ensure <tt>DEBUG</tt> is not defined. The time for debugging and diagnostics is over, so users get production code with full optimizations, no "programming diagnostics", and other efficiencies. If you can't optimize or your are performing excessive logging, it usually means the program is not ready for production.

If you have been relying on an <tt>assert</tt> and then a subsequent <tt>abort()</tt>, you have been abusing "program diagnostics" since it has no place in production code. If you want a memory dump, create one so users don't have to worry about secrets and other sensitive information being written to the filesystem and emailed in plain text.

For Windows, you would use <tt>/Od</tt> for debug builds; and <tt>/Ox</tt>, <tt>/O2</tt> or <tt>/Os</tt> for release builds. See Microsoft's [http://msdn.microsoft.com/en-us/library/k1ack8f1.aspx /O Options (Optimize Code)] for details.

==== Test Builds ====

Test builds are used to provide heuristic validation by way of positive and negative test suites. Under a test configuration, all interfaces are tested to ensure they perform to specification and satisfaction. "Satisfaction" is subjective, but it should include no crashing and no trashing of your memory arena, even when faced with negative tests.

Because all interfaces are tested (and not just the public ones), your <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> should include:

<pre>-Dprotected=public -Dprivate=public</pre>

You should also change <tt>__attribute__ ((visibility ("hidden")))</tt> to <tt>__attribute__ ((visibility ("default")))</tt>.

Nearly everyone gets a positive test right, so no more needs to be said. The negative self tests are much more interesting, and you should concentrate on trying to make your program fail so you can verify its fails gracefully. Remember, a bad guy is not going to be courteous when he attempts to cause your program to fail. And its your project that takes egg on the face by way of a bug report or guest appearance on [http://www.grok.org.uk/full-disclosure/ Full Disclosure] or [http://www.securityfocus.com/archive Bugtraq] - not ''<nowiki><some library></nowiki>'' you included.

=== Auto Tools ===

Auto configuration tools are popular on many Linux and Unix based systems, and the tools include ''Autoconf'', ''Automake'', ''config'', and ''Configure''. The tools work together to produce project files from scripts and template files. After the process completes, your project should be setup and ready to be made with <tt>make</tt>.

When using auto configuration tools, there are a few files of interest worth mentioning. The files are part of the auto tools chain and include <tt>m4</tt> and the various <tt>*.in</tt>, <tt>*.ac</tt> (autoconf), and <tt>*.am</tt> (automake) files. At times, you will have to open them, or the resulting makefiles, to tune the "stock" configuration.

There are three downsides to the command line configuration tools in the toolchain: (1) they often ignore user requests, (2) they cannot create configurations, and (3) security is often not a goal.

To demonstrate the first issue, confider your project with the following: <tt>configure CFLAGS="-Wall -fPIE" CXXFLAGS="-Wall -fPIE" LDFLAGS="-pie"</tt>. You will probably find the auto tools ignored your request, which means the command below will not produce expected results. As a work around, you will have to open an <tt>m4</tt> scripts, <tt>Makefile.in</tt> or <tt>Makefile.am</tt> and fix the configuration.

<pre>$ configure CFLAGS="-Wall -Wextra -Wconversion -fPIE -Wno-unused-parameter
-Wformat=2 -Wformat-security -fstack-protector-all -Wstrict-overflow"
LDFLAGS="-pie -z,noexecstack -z,noexecheap -z,relro -z,now"</pre>

For the second point, you will probably be disappointed to learn [https://lists.gnu.org/archive/html/automake/2012-12/msg00019.html Automake does not support the concept of configurations]. Its not entirely Autoconf's or Automake's fault - ''Make'' and its inability to detect changes is the underlying problem. Specifically, ''Make'' only [http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html checks modification times of prerequisites and targets], and does not check things like <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>. The net effect is you will not receive expected results when you issue <tt>make debug</tt> and then <tt>make test</tt> or <tt>make release</tt>.

Finally, you will probably be disappointed to learn tools such as Autoconf and Automake miss many security related opportunities and ship insecure out of the box. There are a number of compiler switches and linker flags that improve the defensive posture of a program, but they are not 'on' by default. Tools like Autoconf - which are supposed to handle this situation - often provides setting to serve the lowest of all denominators.

A recent discussion on the Automake mailing list illuminates the issue: ''[https://lists.gnu.org/archive/html/autoconf/2012-12/msg00038.html Enabling compiler warning flags]''. Attempts to improve default configurations were met with resistance and no action was taken. The resistance is often of the form, "<nowiki><some useful warning></nowiki> also produces false positives" or "<nowiki><some obscure platform></nowiki> does not support <nowiki><established security feature></nowiki>". Its noteworthy that David Wheeler, the author of ''[http://www.dwheeler.com/secure-programs/ Secure Programming for Linux and Unix HOWTO]'', was one of the folks trying to improve the posture.

=== Makefiles ===

Make is one of the earliest build systems dating back to the 1970s. Its available on Linux, Mac OS X and Unix, so you will frequently encounter projects using it. Unfortunately, Make has a number of short comings (''[http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful]'' and ''[http://www.conifersystems.com/whitepapers/gnu-make/ What’s Wrong With GNU make?]''), and can cause some discomfort. Despite issues with Make, ESAPI C++ uses Make primarily for three reasons: first, its omnipresent; second, its easier to manage than the Auto Tools family; and third, <tt>libtool</tt> was out of the question.

Consider what happens when you: (1) type <tt>make debug</tt>, and then type <tt>make release</tt>. Each build would require different <tt>CFLAGS</tt> due to optimizations and level of debug support. In your makefile, you would extract the relevant target and set <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> similar to below (taken from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/Makefile ESAPI C++ Makefile]):

<pre># Makefile
DEBUG_GOALS = $(filter $(MAKECMDGOALS), debug)
ifneq ($(DEBUG_GOALS),)
WANT_DEBUG := 1
WANT_TEST := 0
WANT_RELEASE := 0
endif
…

ifeq ($(WANT_DEBUG),1)
ESAPI_CFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
ESAPI_CXXFLAGS += -DDEBUG=1 -UNDEBUG -g3 -ggdb -O0
endif

ifeq ($(WANT_RELEASE),1)
ESAPI_CFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
ESAPI_CXXFLAGS += -DNDEBUG=1 -UDEBUG -g -O2
endif

ifeq ($(WANT_TEST),1)
ESAPI_CFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
ESAPI_CXXFLAGS += -DESAPI_NO_ASSERT=1 -g2 -ggdb -O2 -Dprivate=public -Dprotected=public
endif
…

# Merge ESAPI flags with user supplied flags. We perform the extra step to ensure
# user options follow our options, which should give user option's a preference.
override CFLAGS := $(ESAPI_CFLAGS) $(CFLAGS)
override CXXFLAGS := $(ESAPI_CXXFLAGS) $(CXXFLAGS)
override LDFLAGS := $(ESAPI_LDFLAGS) $(LDFLAGS)
…</pre>

Make will first build the program in a debug configuration for a session under the debugger using a rule similar to:

<pre>%.cpp:%.o:
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@</pre>

When you want the release build, Make will do nothing because it considers everything up to date despite the fact <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt> have changed. Hence, your program will actually be in a debug configuration and risk a <tt>SIGABRT</tt> at runtime because debug instrumentation is present (recall <tt>assert</tt> calls <tt>abort()</tt> when <tt>NDEBUG</tt> is '''not''' defined). In essence, you have DoS'd yourself due to <tt>make</tt>.

In addition, many projects do not honor the user's command line. ESAPI C++ does its best to ensure a user's flags are honored via <tt>override</tt> as shown above, but other projects do not. For example, consider a project that should be built with Position Independent Executable (PIE or ASLR) enabled and data execution prevention (DEP) enabled. Dismissing user settings combined with insecure out of the box settings (and not picking them up during auto-setup or auto-configure) means a program built with the following will likely have neither defense:

<pre>$ make CFLAGS="-fPIE" CXXFLAGS="-fPIE" LDFLAGS="-pie -z,noexecstack, -z,noexecheap"</pre>

Defenses such as ASLR and DEP are especially important on Linux because [http://linux.die.net/man/5/elf Data Execution - not Prevention - is the norm].

=== Integration ===

Project level integration presents opportunities to harden your program or library with domain specific knowledge. For example, if the platform supports Position Independent Executables (PIE or ASLR) and data execution prevention (DEP), then you should integrate with it. The consequences of not doing so could result in exploitation. As a case in point, see KingCope's 0-days for MySQL in December, 2012 (CVE-2012-5579 and CVE-2012-5612, among others). Integration with platform security would have neutered a number of the 0-days.

You also have the opportunity to include helpful libraries that are not need for business logic support. For example, if you are working on a platform with [http://dmalloc.com DMalloc] or [http://code.google.com/p/address-sanitizer/ Address Sanitizer], you should probably use it in your debug builds. For Ubuntu, DMalloc available from the package manager and can be installed with <tt>sudo apt-get install libdmalloc5</tt>. For Apple platforms, its available as a scheme option (see [[#Clang/Xcode|Clang/Xcode]] below). Address Sanitizer is available in [http://gcc.gnu.org/gcc-4.8/changes.html GCC 4.8 and above] for many platforms.

In addition, project level integration is an opportunity to harden third party libraries you chose to include. Because you chose to include them, you and your users are responsible for them. If you or your users endure a SP800-53 audit, third party libraries will be in scope because the supply chain is included (specifically, item SA-12, Supply Chain Protection). The audits are not limited to those in the US Federal arena - financial institutions perform reviews too. A perfect example of violating this guidance is [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2012-1525 CVE-2012-1525], which was due to [http://www.agarri.fr/blog/index.html Adobe's inclusion of a defective Sablotron library].

Another example is including OpenSSL. You know (1) [http://www.schneier.com/paper-ssl-revised.pdf SSLv2 is insecure], (2) [http://www.yaksman.org/~lweith/ssl.pdf SSLv3 is insecure], and (3) [http://arstechnica.com/security/2012/09/crime-hijacks-https-sessions/ compression is insecure] (among others). In addition, suppose you don't use hardware and engines, and only allow static linking. Given the knowledge and specifications, you would configure the OpenSSL library as follows:

<pre>$ Configure darwin64-x86_64-cc -no-hw -no-engines -no-comp -no-shared -no-dso -no-sslv2 -no-sslv3 --openssldir=…</pre>

''Note Well'': you might want engines, especially on Ivy Bridge microarchitectures (3rd generation Intel Core i5 and i7 processors). To have OpenSSL use the processor's random number generator (via the of <tt>rdrand</tt> instruction), you will need to call OpenSSL's <tt>ENGINE_load_rdrand()</tt> function and then <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. See [http://wiki.opensslfoundation.com/index.php/Random_Numbers OpenSSL's Random Numbers] for details.

If you configure without the switches, then you will likely have vulnerable code/libraries and risk failing an audit. If the program is a remote server, then the following command will reveal if compression is active on the channel:

<pre>$ echo "GET / HTTP1.0" | openssl s_client -connect <nowiki>example.com:443</nowiki></pre>

<tt>nm</tt> or <tt>openssl s_client</tt> will show that compression is enabled in the client. In fact, any symbol within the <tt>OPENSSL_NO_COMP</tt> preprocessor macro will bear witness since <tt>-no-comp</tt> is translated into a <tt>CFLAGS</tt> define.

<pre>$ nm /usr/local/ssl/iphoneos/lib/libcrypto.a 2>/dev/null | egrep -i "(COMP_CTX_new|COMP_CTX_free)"
0000000000000110 T COMP_CTX_free
0000000000000000 T COMP_CTX_new</pre>

Even more egregious is the answer given to auditors who specifically ask about configurations and protocols: "we don't use weak/wounded/broken ciphers" or "we follow best practices." The use of compression tells the auditor that you are using wounded protocol in an insecure configuration and you don't follow best practices. That will likely set off alarm bells, and ensure the auditor dives deeper on more items.

== Preprocessor ==

The preprocessor is crucial to setting up a project for success. The C committee provided one macro - <tt>NDEBUG</tt> - and the macro can be used to derive a number of configurations and drive engineering processes. Unfortunately, the committee also left many related items to chance, which has resulted in programmers abusing builtin facilities. This section will help you set up you projects to integrate well with other projects and ensure reliability and security.

There are three topics to discuss when hardening the preprocessor. The first is well defined configurations which produce well defined behaviors, the second is useful behavior from assert, and the third is proper use of macros when integrating vendor code and third party libraries.

=== Configurations ===

To remove ambiguity, you should recognize two configurations: Release and Debug. Release is for production code on live servers, and its behavior is requested via the C/C++ <tt>NDEBUG</tt> macro. Its also the only macro observed by the C and C++ Committees and Posix. Diametrically opposed to release is Debug. While there is a compelling argument for <tt>!defined(NDEBUG)</tt>, you should have an explicit macro for the configuration and that macro should be <tt>DEBUG</tt>. This is because vendors and outside libraries use <tt>DEBUG</tt> (or similar) macro for their configuration. For example, Carnegie Mellon's Mach kernel uses <tt>DEBUG</tt>, Microsoft's CRT uses [http://msdn.microsoft.com/en-us/library/ww5t02fa%28v=vs.71%29.aspx<tt>_DEBUG</tt>], and Wind River Workbench uses <tt>DEBUG_MODE</tt>.

In addition to <tt>NDEBUG</tt> (Release) and <tt>DEBUG</tt> (Debug), you have two additional cross products: both are defined or neither are defined. Defining both should be an error, and defining neither should default to a release configuration. Below is from [http://code.google.com/p/owasp-esapi-cplusplus/source/browse/trunk/esapi/EsapiCommon.h ESAPI C++ EsapiCommon.h], which is the configuration file used by all source files:

<pre>// Only one or the other, but not both
#if (defined(DEBUG) || defined(_DEBUG)) && (defined(NDEBUG) || defined(_NDEBUG))
# error Both DEBUG and NDEBUG are defined.
#endif

// The only time we switch to debug is when asked. NDEBUG or {nothing} results
// in release build (fewer surprises at runtime).
#if defined(DEBUG) || defined(_DEBUG)
# define ESAPI_BUILD_DEBUG 1
#else
# define ESAPI_BUILD_RELEASE 1
#endif</pre>

When <tt>DEBUG</tt> is in effect, your code should receive full debug instrumentation, including the full force of assertions.

=== ASSERT ===

Asserts will help you create self-debugging code by helping you find the point of first failure quickly and easily. Asserts should be used throughout your program, including parameter validation, return value checking and program state. The <tt>assert</tt> will silently guard your code through its lifetime. It will always be there, even when not debugging a specific component of a module. If you have thorough code coverage, you will spend less time debugging and more time developing because programs will debug themselves.

To use asserts effectively, you should assert everything. That includes parameters upon entering a function, return values from function calls, and any program state. Everywhere you place an <tt>if</tt> statement for validation or checking, you should have an assert. Everywhere you have an <tt>assert</tt> for validation or checking, you should have an <tt>if</tt> statement. They go hand-in-hand.

If you are still using <tt>printf</tt>'s, then you have an opportunity for improvement. In the time it takes for you to write a <tt>printf</tt> or <tt>NSLog</tt> statement, you could have written an <tt>assert</tt>. Unlike the <tt>printf</tt> or <tt>NSLog</tt> which are often removed when no longer needed, the <tt>assert</tt> stays active forever. Remember, this is all about finding the point of first failure quickly so you can spend your time doing other things.

There is one problem with using asserts - [http://pubs.opengroup.org/onlinepubs/009604499/functions/assert.html Posix states <tt>assert</tt> should call <tt>abort()</tt>] if <tt>NDEBUG</tt> is '''not''' defined. When debugging, <tt>NDEBUG</tt> will never be defined since you want the "program diagnostics" (quote from the Posix description). The behavior makes <tt>assert</tt> and its accompanying <tt>abort()</tt> completely useless for development. The result of "program diagnostics" calling <tt>abort()</tt> due to standard C/C++ behavior is disuse - developers simply don't use them. Its incredibly bad for the development community because self-debugging programs can help eradicate so many stability problems.

Since self-debugging programs are so powerful, you will have to have to supply your own assert and signal handler with improved behavior. Your assert will exchange auto-aborting behavior for auto-debugging behavior. The auto-debugging facility will ensure the debugger snaps when a problem is detected, and you will find the point of first failure quickly and easily.

ESAPI C++ supplies its own assert with the behavior described above. In the code below, <tt>ASSERT</tt> raises <tt>SIGTRAP</tt> when in effect or it evaluates to <tt>void</tt> in other cases.

<pre>// A debug assert which should be sprinkled liberally. This assert fires and then continues rather
// than calling abort(). Useful when examining negative test cases from the command line.
#if (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_STARNIX))
# define ESAPI_ASSERT1(exp) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
# define ESAPI_ASSERT2(exp, msg) { \
if(!(exp)) { \
std::ostringstream oss; \
oss << "Assertion failed: " << (char*)(__FILE__) << "(" \
<< (int)__LINE__ << "): " << (char*)(__func__) \
<< ": \"" << (msg) << "\"" << std::endl; \
std::cerr << oss.str(); \
raise(SIGTRAP); \
} \
}
#elif (defined(ESAPI_BUILD_DEBUG) && defined(ESAPI_OS_WINDOWS))
# define ESAPI_ASSERT1(exp) assert(exp)
# define ESAPI_ASSERT2(exp, msg) assert(exp)
#else
# define ESAPI_ASSERT1(exp) ((void)(exp))
# define ESAPI_ASSERT2(exp, msg) ((void)(exp))
#endif

#if !defined(ASSERT)
# define ASSERT(exp) ESAPI_ASSERT1(exp)
#endif</pre>

At program startup, a <tt>SIGTRAP</tt> handler will be installed if one is not provided by another component:

<pre>struct DebugTrapHandler
{
DebugTrapHandler()
{
struct sigaction new_handler, old_handler;

do
{
int ret = 0;

ret = sigaction (SIGTRAP, NULL, &old_handler);
if (ret != 0) break; // Failed

// Don't step on another's handler
if (old_handler.sa_handler != NULL) break;

new_handler.sa_handler = &DebugTrapHandler::NullHandler;
new_handler.sa_flags = 0;

ret = sigemptyset (&new_handler.sa_mask);
if (ret != 0) break; // Failed

ret = sigaction (SIGTRAP, &new_handler, NULL);
if (ret != 0) break; // Failed

} while(0);
}

static void NullHandler(int /*unused*/) { }

};

// We specify a relatively low priority, to make sure we run before other CTORs
// http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#C_002b_002b-Attributes
static const DebugTrapHandler g_dummyHandler __attribute__ ((init_priority (110)));</pre>

On a Windows platform, you would call <tt>_set_invalid_parameter_handler</tt> (and possibly <tt>set_unexpected</tt> or <tt>set_terminate</tt>) to install a new handler.

Live hosts running production code should always define <tt>NDEBUG</tt> (i.e., release configuration), which means they do not assert or auto-abort. Auto-abortion is not acceptable behavior, and anyone who asks for the behavior is completely abusing the functionality of "program diagnostics". If a program wants a core dump, then it should create the dump rather than crashing.

For more reading on asserting effectively, please see one of John Robbin's books, such as ''[http://www.amazon.com/dp/0735608865 Debugging Applications]''. John is a legendary bug slayer in Windows circles, and he will show you how to do nearly everything, from debugging a simple program to bug slaying in multithreaded programs.

=== Additional Macros ===

Additional macros include any macros needed to integrate properly and securely. It includes integrating the program with the platform (for example MFC or Cocoa/CocoaTouch) and libraries (for example, Crypto++ or OpenSSL). It can be a challenge because you have to have proficiency with your platform and all included libraries and frameworks. The list below illustrates the level of detail you will need when integrating.

Though Boost is missing from the list, it appears to lack recommendations, additional debug diagnostics, and a hardening guide. See ''[http://stackoverflow.com/questions/14927033/boost-hardening-guide-preprocessor-macros BOOST Hardening Guide (Preprocessor Macros)]'' for details. In addition, Tim Day points to ''[http://boost.2283326.n4.nabble.com/boost-build-should-we-not-define-SECURE-SCL-0-by-default-for-all-msvc-toolsets-td2654710.html <nowiki>[boost.build] should we not define _SECURE_SCL=0 by default for all msvc toolsets</nowiki>]'' for a recent discussion related to hardening (or lack thereof).

In addition to what you should define, defining some macros and undefining others should trigger a security related defect. For example, <tt>-U_FORTIFY_SOURCES</tt> on Linux and <tt>_CRT_SECURE_NO_WARNINGS=1</tt>, <tt>_SCL_SECURE_NO_WARNINGS</tt>, <tt>_ATL_SECURE_NO_WARNINGS</tt> or <tt>STRSAFE_NO_DEPRECATE</tt> on Windows.

{| border="1"

|-style="background:#DADADA"
!Platform/Library!!Debug!!Release
|+ Table 1: Additional Platform/Library Macros

|-
|width="175pt"|All
|width="250pt"|DEBUG=1
|width="250pt"|NDEBUG=1

|-
|Linux
|_GLIBCXX_DEBUG=1a
|_FORTIFY_SOURCE=2

|-
|Android
|NDK_DEBUG=1
|_FORTIFY_SOURCE=1 (4.2 and above) 
<tt>#define LOGI(...)</tt> (define to nothing, preempt logging)

|-
|Cocoa/CocoaTouch
|
|NS_BLOCK_ASSERTIONS=1 
<tt>#define NSLog(...)</tt> (define to nothing, preempt ASL)

|-
|SafeInt
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1
|SAFEINT_DISALLOW_UNSIGNED_NEGATION=1

|-
|Microsoft
|_DEBUG=1, STRICT, 
_SECURE_SCL=1, _HAS_ITERATOR_DEBUGGING=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1
|STRICT 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1 
_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT=1

|-
|Microsoft ATL & MFC
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS
|_SECURE_ATL, _ATL_ALL_WARNINGS 
_ATL_CSTRING_EXPLICIT_CONSTRUCTORS

|-
|STLPort
|_STLP_DEBUG=1, _STLP_USE_DEBUG_LIB=1 
_STLP_DEBUG_ALLOC=1, _STLP_DEBUG_UNINITIALIZED=1
|

|-
|SQLite
|SQLITE_DEBUG, SQLITE_MEMDEBUG 
SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc
|SQLITE_SECURE_DELETEb 
SQLITE_DEFAULT_FILE_PERMISSIONS=Nc

|-
|SQLCipher
|Remove '''<tt>NDEBUG</tt>''' from Debug builds (Xcode) 
SQLITE_HAS_CODEC=1
|SQLITE_HAS_CODEC=1

|-
|SQLite/SQLCipher
|SQLITE_TEMP_STORE=3d
|SQLITE_TEMP_STORE=3d

|}

a Be careful with <tt>_GLIBCXX_DEBUG</tt> when using pre-compiled libraries such as Boost from a distribution. There are ABI incompatibilities, and the result will likely be a crash. You will have to compile Boost with <tt>_GLIBCXX_DEBUG</tt> or omit <tt>_GLIBCXX_DEBUG</tt>.

b SQLite secure deletion zeroizes memory on destruction. Define as required, and always define in US Federal since zeroization is required for FIPS 140-2, Level 1.

c ''N'' is 0644 by default, which means everyone has some access.

d Force temporary tables into memory (no unencrypted data to disk).

== Compiler and Linker ==

Compiler writers provide a rich set of warnings from the analysis of code during compilation. Both GCC and Visual Studio have static analysis capabilities to help find mistakes early in the development process. The built in static analysis capabilities of GCC and Visual Studio are usually sufficient to ensure proper API usage and catch a number of mistakes such as using an uninitialized variable or comparing a negative signed int and a positive unsigned int.

As a concrete example, (and for those not familiar with C/C++ promotion rules), a warning will be issued if a signed integer is promoted to an unsigned integer and then compared because a side effect is <tt>-1 > 1</tt> after promotion! GCC and Visual Studio will not currently catch, for example, SQL injections and other tainted data usage. For that, you will need a tool designed to perform data flow analysis or taint analysis.

Some in the development community resist static analysis or refute its results. For example, when static analysis warned the Linux kernel's <tt>sys_prctl</tt> was comparing an unsigned value against less than zero, Jesper Juhl offered a patch to clean up the code. Linus Torvalds howled “No, you don't do this… GCC is crap” (referring to compiling with warnings). For the full discussion, see ''[http://linux.derkeiler.com/Mailing-Lists/Kernel/2006-11/msg08325.html <nowiki>[PATCH] Don't compare unsigned variable for <0 in sys_prctl()</nowiki>]'' from the Linux Kernel mailing list.

The following sections will detail steps for three platforms. First is a typical GNU Linux based distribution offering GCC and Binutils, second is Clang and Xcode, and third is modern Windows platforms.

=== Distribution Hardening ===

Before discussing GCC and Binutils, it would be a good time to point out some of the defenses discussed below are all ready present in a distribution. Unfortunately, its design by committee, so what is present is usually only a mild variation of what is available (this way, everyone is mildly offended). For those who are purely worried about performance, you might be surprised to learn you have already taken the small performance hint without even knowing.

Linux and BSD distributions often apply some hardening without intervention via ''[http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html GCC Spec Files]''. If you are using Debian, Ubuntu, Linux Mint and family, see ''[http://wiki.debian.org/Hardening Debian Hardening]''. For Red Hat and Fedora systems, see ''[http://lists.fedoraproject.org/pipermail/devel-announce/2011-August/000821.html New hardened build support (coming) in F16]''. Gentoo users should visit ''[http://www.gentoo.org/proj/en/hardened/ Hardened Gentoo]''.

You can see the settings being used by a distribution via <tt>gcc -dumpspecs</tt>. From Linux Mint 12 below, -fstack-protector (but not -fstack-protector-all) is used by default.

<pre>$ gcc -dumpspecs
…
*link_ssp: %{fstack-protector:}

*ssp_default: %{!fno-stack-protector:%{!fstack-protector-all: %{!ffreestanding:%{!nostdlib:-fstack-protector}}}}
…</pre>

The “SSP” above stands for Stack Smashing Protector. SSP is a reimplementation of Hiroaki Etoh's work on IBM Pro Police Stack Detector. See Hiroaki Etoh's patch ''[http://gcc.gnu.org/ml/gcc-patches/2001-06/msg01753.html gcc stack-smashing protector]'' and IBM's ''[http://www.research.ibm.com/trl/projects/security/ssp/ GCC extension for protecting applications from stack-smashing attacks]'' for details.

=== GCC/Binutils ===

GCC (the compiler collection) and Binutils (the assemblers, linkers, and other tools) are separate projects that work together to produce a final executable. Both the compiler and linker offer options to help you write safer and more secure code. The linker will produce code which takes advantage of platform security features offered by the kernel and PaX, such as no-exec stacks and heaps (NX) and Position Independent Executable (PIE).

The table below offers a set of compiler options to build your program. Static analysis warnings help catch mistakes early, while the linker options harden the executable at runtime. In the table below, “GCC” should be loosely taken as “non-ancient distributions.” While the GCC team considers 4.2 ancient, you will still encounter it on Apple and BSD platforms due to changes in GPL licensing around 2007. Refer to ''[http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html GCC Option Summary]'', ''[http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html Options to Request or Suppress Warnings]'' and ''[http://sourceware.org/binutils/docs-2.21/ld/Options.html Binutils (LD) Command Line Options]'' for usage details.

Noteworthy of special mention are <tt>-fno-strict-overflow</tt> and <tt>-fwrapv</tt>a. The flags ensure the compiler does not remove statements that result in overflow or wrap. If your program only runs correctly using the flags, it is likely violating C/C++ rules on overflow and illegal. If the program is illegal due to overflow or wrap checking, you should consider using [http://code.google.com/p/safe-iop/ safe-iop] for C or David LeBlanc's [http://safeint.codeplex.com SafeInt] in C++.

For a project compiled and linked with hardened settings, some of those settings can be verified with the [http://www.trapkit.de/tools/checksec.html Checksec] tool written by Tobias Klein. The <tt>checksec.sh</tt> script is designed to test standard Linux OS and PaX security features being used by an application. See the [http://www.trapkit.de/tools/checksec.html Trapkit] web page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 2: GCC C Warning Options

|-
|width="200pt"|<nowiki>-Wall -Wextra</nowiki>
|width="75t"|GCC
|width="425pt"|Enables many warnings (despite their names, all and extra do not turn on all warnings).a

|-
|<nowiki>-Wconversion</nowiki>
|GCC
|Warn for implicit conversions that may alter a value (includes -Wsign-conversion).

|-
|<nowiki>-Wsign-conversion</nowiki>
|GCC
|Warn for implicit conversions that may change the sign of an integer value, such as assigning a signed integer to an unsigned integer (<tt>-1 > 1</tt> after promotion!).

|-
|<nowiki>-Wcast-align</nowiki>
|GCC
|Warn for a pointer cast to a type which has a different size, causing an invalid alignment and subsequent bus error on ARM processors.

|-
|<nowiki>-Wformat=2 -Wformat-security</nowiki>
|GCC
|Increases warnings related to possible security defects, including incorrect format specifiers.

|-
|<nowiki>-fno-common</nowiki>
|GCC
|Prevent global variables being simultaneously defined in different object files.

|-
|<nowiki>-fstack-protector or -fstack-protector-all</nowiki>
|GCC
|Stack Smashing Protector (SSP). Improves stack layout and adds a guard to detect stack based buffer overflows.b

|-
|<nowiki>-fno-omit-frame-pointer</nowiki>
|GCC
|Improves backtraces for post-mortem analysis

|-
|<nowiki>-Wmissing-prototypes and -Wmissing-declarations</nowiki>
|GCC
|Warn if a global function is defined without a prototype or declaration.

|-
|<nowiki>-Wstrict-prototypes</nowiki>
|GCC
|Warn if a function is declared or defined without specifying the argument types.

|-
|<nowiki>-Wstrict-overflow</nowiki>
|GCC 4.2
|Warn about optimizations taken due to <nowiki>[undefined]</nowiki> signed integer overflow assumptions.

|-
|<nowiki>-Wtrampolines</nowiki>
|GCC 4.3
|Warn about trampolines generated for pointers to nested functions. Trampolines require executable stacks.

|-
|<nowiki>-fsanitize=address</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/address-sanitizer/ AddressSanitizer], a fast memory error detector. Memory access instructions will be instrumented to help detect heap, stack, and global buffer overflows; as well as use-after-free bugs.

|-
|<nowiki>-fsanitize=thread</nowiki>
|GCC 4.8
|Enable [http://code.google.com/p/data-race-test/wiki/ThreadSanitizer ThreadSanitizer], a fast data race detector. Memory access instructions will be instrumented to detect data race bugs.

|-
|<nowiki>-Wl,-z,nodlopen and -Wl,-z,nodump</nowiki>
|Binutils 2.10
|Reduces the ability of an attacker to load, manipulate, and dump shared objects.

|-
|<nowiki>-Wl,-z,noexecstack and -Wl,-z,noexecheap</nowiki>
|Binutils 2.14
|Data Execution Prevention (DEP). ELF headers are marked with PT_GNU_STACK and PT_GNU_HEAP.

|-
|<nowiki>-Wl,-z,relro</nowiki>
|Binutils 2.15
|Helps remediate Global Offset Table (GOT) attacks on executables.

|-
|<nowiki>-Wl,-z,now</nowiki>
|Binutils 2.15
|Helps remediate Procedure Linkage Table (PLT) attacks on executables.

|-
|<nowiki>-fPIC</nowiki>
|Binutils
|Position Independent Code. Used for libraries and shared objects. Both -fPIC (compiler) and -shared (linker) are required.

|-
|<nowiki>-fPIE</nowiki>
|Binutils 2.16
|Position Independent Executable (ASLR). Used for programs. Both -fPIE (compiler) and -pie (linker) are required.

|}

a Unlike Clang and -Weverything, GCC does not provide a switch to truly enable all warnings. 
b -fstack-protector guards functions with high risk objects such as C strings, while -fstack-protector-all guards all objects.

Additional C++ warnings which can be used include the following in Table 3. See ''[http://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html GCC's Options Controlling C++ Dialect]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 3: GCC C++ Warning Options

|-
|width="200pt"|<nowiki>-Woverloaded-virtual</nowiki>
|width="425pt"|Warn when a function declaration hides virtual functions from a base class.

|-
|<nowiki>-Wreorder</nowiki>
|Warn when the order of member initializers given in the code does not match the order in which they must be executed.

|-
|<nowiki>-Wsign-promo</nowiki>
|Warn when overload resolution chooses a promotion from unsigned or enumerated type to a signed type, over a conversion to an unsigned type of the same size.

|-
|<nowiki>-Wnon-virtual-dtor</nowiki>
|Warn when a class has virtual functions and an accessible non-virtual destructor.

|-
|<nowiki>-Weffc++</nowiki>
|Warn about violations of the following style guidelines from Scott Meyers' ''[http://www.aristeia.com/books.html Effective C++, Second Edition]'' book.

|}

And additional Objective C warnings which are often useful include the following. See ''[http://gcc.gnu.org/onlinedocs/gcc/Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html Options Controlling Objective-C and Objective-C++ Dialects]'' for additional options and details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Discussion
|+ Table 4: GCC Objective C Warning Options

|-
|width="200pt"|<nowiki>-Wstrict-selector-match</nowiki>
|width="425pt"|Warn if multiple methods with differing argument and/or return types are found for a given selector when attempting to send a message using this selector to a receiver of type id or Class.

|-
|<nowiki>-Wundeclared-selector</nowiki>
|Warn if a <tt>@selector(…)</tt> expression referring to an undeclared selector is found.

|}

The use of aggressive warnings will produce spurious noise. The noise is a tradeoff - you can learn of potential problems at the cost of wading through some chaff. The following will help reduces spurious noise from the warning system:

* -Wno-unused-parameter (GCC)
* -Wno-type-limits (GCC 4.3)
* -Wno-tautological-compare (Clang)

Finally, a simple version based Makefile example is shown below. This is different than feature based makefile produced by auto tools (which will test for a particular feature and then define a symbol or configure a template file). Not all platforms use all options and flags. To address the issue you can pursue one of two strategies. First, you can ship with a weakened posture by servicing the lowest common denominator; or you can ship with everything in force. In the latter case, those who don't have a feature available will edit the makefile to accommodate their installation.

<pre>CXX=g++
EGREP = egrep
…

GCC_COMPILER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version')
GCC41_OR_LATER = $(shell $(CXX) -v 2>&1 | $(EGREP) -i -c '^gcc version (4\.[1-9]|[5-9])')
…

GNU_LD210_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[0-9]|2\.[2-9])')
GNU_LD214_OR_LATER = $(shell $(LD) -v 2>&1 | $(EGREP) -i -c '^gnu ld .* (2\.1[4-9]|2\.[2-9])')
…

ifeq ($(GCC_COMPILER),1)
MY_CC_FLAGS += -Wall -Wextra -Wconversion
MY_CC_FLAGS += -Wformat=2 -Wformat-security
MY_CC_FLAGS += -Wno-unused-parameter
endif

ifeq ($(GCC41_OR_LATER),1)
MY_CC_FLAGS += -fstack-protector-all
endif

ifeq ($(GCC42_OR_LATER),1)
MY_CC_FLAGS += -Wstrict-overflow
endif

ifeq ($(GCC43_OR_LATER),1)
MY_CC_FLAGS += -Wtrampolines
endif

ifeq ($(GNU_LD210_OR_LATER),1)
MY_LD_FLAGS += -z,nodlopen -z,nodump
endif

ifeq ($(GNU_LD214_OR_LATER),1)
MY_LD_FLAGS += -z,noexecstack -z,noexecheap
endif

ifeq ($(GNU_LD215_OR_LATER),1)
MY_LD_FLAGS += -z,relro -z,now
endif

ifeq ($(GNU_LD216_OR_LATER),1)
MY_CC_FLAGS += -fPIE
MY_LD_FLAGS += -pie
endif

# Use 'override' to honor the user's command line
override CFLAGS := $(MY_CC_FLAGS) $(CFLAGS)
override CXXFLAGS := $(MY_CC_FLAGS) $(CXXFLAGS)
override LDFLAGS := $(MY_LD_FLAGS) $(LDFLAGS)
…</pre>

=== Clang/Xcode ===

[http://clang.llvm.org Clang] and [http://llvm.org LLVM] have been aggressively developed since Apple lost its GPL compiler back in 2007 (due to Tivoization which resulted in GPLv3). Since that time, a number of developers and Goggle have joined the effort. While Clang will consume most (all?) GCC/Binutil flags and switches, the project supports a number of its own options, including a static analyzer. In addition, Clang is relatively easy to build with additional diagnostics, such as Dr. John Regher and Peng Li's [http://embed.cs.utah.edu/ioc/ Integer Overflow Checker (IOC)].

IOC is incredibly useful, and has found bugs in a number of projects, from the Linux Kernel (<tt>include/linux/bitops.h</tt>, still unfixed), SQLite, PHP, Firefox (many still unfixed), LLVM, and Python. Future version of Clang (Clang 3.3 and above) will allow you to enable the checks out of the box with <tt>-fsanitize=integer</tt> and <tt>-fsanitize=shift</tt>.

Clang options can be found at [http://clang.llvm.org/docs/UsersManual.html Clang Compiler User’s Manual]. Clang does include an option to turn on all warnings - <tt>-Weverything</tt>. Use it with care but use it regularly since you will get back a lot of noise and issues you missed. For example, add <tt>-Weverything</tt> for production builds and make non-spurious issues a quality gate. Under Xcode, simply add <tt>-Weverything</tt> to <tt>CFLAGS</tt> and <tt>CXXFLAGS</tt>.

In addition to compiler warnings, both static analysis and additional security checks can be performed. Reading on Clang's static analysis capabilities can be found at [http://clang-analyzer.llvm.org Clang Static Analyzer]. Figure 1 below shows some of the security checks utilized by Xcode.

{| align="center"
| [[File:toolchan-hardening-11.png|thumb|450px|Figure 1: Clang/LLVM and Xcode options]]
|}

=== Visual Studio ===

Visual Studio offers a convenient Integrated Development Environment (IDE) for managing solutions and their settings. the section called “Visual Studio Options” discusses option which should be used with Visual Studio, and the section called “Project Properties” demonstrates incorporating those options into a solution's project.

The table below lists the compiler and linker switches which should be used under Visual Studio. Refer to Howard and LeBlanc's Writing Secure Code (Microsoft Press) for a detailed discussion; or ''[http://msdn.microsoft.com/en-us/magazine/cc337897.aspx Protecting Your Code with Visual C++ Defenses]'' in Security Briefs by Michael Howard. In the table below, “Visual Studio” refers to nearly all versions of the development environment, including Visual Studio 5.0 and 6.0.

For a project compiled and linked with hardened settings, those settings can be verified with BinScope. BinScope is a verification tool from Microsoft that analyzes binaries to ensure that they have been built in compliance with Microsoft's Security Development Lifecycle (SDLC) requirements and recommendations. See the ''[https://www.microsoft.com/download/en/details.aspx?id=11910 BinScope Binary Analyzer]'' download page for details.

{| border="1"

|-style="background:#DADADA"
!Flag or Switch!!Version!!Discussion
|+ Table 5: Visual Studio Warning Options

|-
|width="150pt"|<nowiki>/W4</nowiki>
|width="100pt"|Visual Studio
|width="350pt"|Warning level 4, which includes most warnings.

|-
|<nowiki>/WAll</nowiki>
|Visual Studio 2003
|Enable all warnings, including those off by default.a

|-
|<nowiki>/GS</nowiki>
|Visual Studio 2003
|Adds a security cookie (guard or canary) on the stack before the return address buffer stack based for overflow checks.a

|-
|<nowiki>/SafeSEH</nowiki>
|Visual Studio 2003
|Safe structured exception handling to remediate SEH overwrites.

|-
|<nowiki>/analyze</nowiki>
|Visual Studio 2005
|Enterprise code analysis (freely available with Windows SDK for Windows Server 2008 and .NET Framework 3.5).

|-
|<nowiki>/NXCOMPAT</nowiki>
|Visual Studio 2005
|Data Execution Prevention (DEP).

|-
|<nowiki>/dynamicbase</nowiki>
|Visual Studio 2005 SP1
|Address Space Layout Randomization (ASLR).

|-
|<nowiki>strict_gs_check</nowiki>
|Visual Studio 2005 SP1
|Aggressively applies stack protections to a source file to help detect some categories of stack based buffer overruns.b

|}

aSee Jon Sturgeon's discussion of the switch at ''[https://blogs.msdn.com/b/vcblog/archive/2010/12/14/off-by-default-compiler-warnings-in-visual-c.aspx Off By Default Compiler Warnings in Visual C++]''. 
aWhen using /GS, there are a number of circumstances which affect the inclusion of a security cookie. For example, the guard is not used if there is no buffer in the stack frame, optimizations are disabled, or the function is declared naked or contains inline assembly. 
b<tt>#pragma strict_gs_check(on)</tt> should be used sparingly, but is recommend in high risk situations, such as when a source file parses input from the internet.

=== Warn Suppression ===

From the tables above, a lot of warnings have been enabled to help detect possible programming mistakes. The potential mistakes are detected via compiler which carries around a lot of contextual information during its code analysis phase. At times, you will receive spurious warnings because the compiler is not ''that'' smart. Its understandable and even a good thing (how would you like to be out of a job because a program writes its own programs?). At times you will have to learn how to work with the compiler's warning system to suppress warnings. Notice what was not said: turn off the warnings.

Suppressing warnings placates the compiler for spurious noise so you can get to the issues that matter (you are separating the wheat from the chaff). This section will offer some hints and point out some potential minefields. First is an unused parameter (for example, <tt>argc</tt> or <tt>argv</tt>). Suppressing unused parameter warnings is especially helpful for C++ and interface programming, where parameters are often unused. For this warning, simply define an "UNUSED" macro and warp the parameter:

<pre>#define UNUSED_PARAMETER(x) ((void)x)
…

int main(int argc, char* argv[])
{
UNUSED_PARAMETER(argc);
UNUSED_PARAMETER(argv);
…
}</pre>

A potential minefield lies near "comparing unsigned and signed" values, and <tt>-Wconversion</tt> will catch it for you. This is because C/C++ promotion rules state the signed value will be promoted to an unsigned value and then compared. That means <tt>-1 > 1</tt> after promotion! To fix this, you cannot blindly cast - you must first range test the value:

<pre>int x = GetX();
unsigned int y = GetY();

ASSERT(x >= 0);
if(!(x >= 0))
throw runtime_error("WTF??? X is negative.");

if(static_cast<unsigned int>(x) > y)
cout << "x is greater than y" << endl;
else
cout << "x is not greater than y" << endl;</pre>

Notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>x</tt>. Just run the program and wait for it to tell you there is a problem. If there is a problem, the program will snap the debugger (and more importantly, not call a useless <tt>abort()</tt> as specified by Posix). It beats the snot out of <tt>printf</tt> that are removed when no longer needed or pollute outputs.

Another conversion problem you will encounter conversion between types, and <tt>-Wconversion</tt> will also catch it for you. The following will always have an opportunity to fail, and should light up like a Christmas tree:

<pre>struct sockaddr_in addr;
…

addr.sin_port = htons(atoi(argv[2]));</pre>

The following would probably serve you much better. Notice <tt>atoi</tt> and fiends are not used because they can silently fail. In addition, the code is instrumented so you don't need to waste a lot of time debugging potential problems:

<pre>const char* cstr = GetPortString();

ASSERT(cstr != NULL);
if(!(cstr != NULL))
throw runtime_error("WTF??? Port string is not valid.");

istringstream iss(cstr);
long long t = 0;
iss >> t;

ASSERT(!(iss.fail()));
if(iss.fail())
throw runtime_error("WTF??? Failed to read port.");

// Should this be a port above the reserved range ([0-1024] on Unix)?
ASSERT(t > 0);
if(!(t > 0))
throw runtime_error("WTF??? Port is too small");

ASSERT(t < static_cast<long long>(numeric_limits<unsigned int>::max()));
if(!(t < static_cast<long long>(numeric_limits<unsigned int>::max())))
throw runtime_error("WTF??? Port is too large");

// OK to use port
unsigned short port = static_cast<unsigned short>(t);
…</pre>

Again, notice the code above will debug itself - you don't need to set a breakpoint to see if there is a problem with <tt>port</tt>. This code will continue checking conditions, years after being instrumented (assuming to wrote code to read a config file early in the project). There's no need to remove the <tt>ASSERT</tt>s as with <tt>printf</tt> since they are silent guardians.

Another useful suppression trick is too avoid ignoring return values. Not only is it useful to suppress the warning, its required for correct code. For example, <tt>snprint</tt> will alert you to truncations through its return value. You should not make them silent truncations by ignoring the warning or casting to <tt>void</tt>:

<pre>char path[PATH_MAX];
…

int ret = snprintf(path, sizeof(path), "%s/%s", GetDirectory(), GetObjectName());
ASSERT(ret != -1);
ASSERT(!(ret >= sizeof(path)));

if(ret == -1 || ret >= sizeof(path))
throw runtime_error("WTF??? Unable to build full object name");

// OK to use path
…</pre>

The problem is pandemic, and not just boring user land programs. Projects which offer high integrity code, such as SELinux, suffer silent truncations. The following is from an approved SELinux patch even though a comment was made that it [http://permalink.gmane.org/gmane.comp.security.selinux/16845 suffered silent truncations in its <tt>security_compute_create_name</tt> function] from <tt>compute_create.c</tt>.

<pre>12 int security_compute_create_raw(security_context_t scon,
13 security_context_t tcon,
14 security_class_t tclass,
15 security_context_t * newcon)
16 {
17 char path[PATH_MAX];
18 char *buf;
19 size_t size;
20 int fd, ret;
21
22 if (!selinux_mnt) {
23 errno = ENOENT;
24 return -1;
25 }
26
27 snprintf(path, sizeof path, "%s/create", selinux_mnt);
28 fd = open(path, O_RDWR);</pre>

Unlike other examples, the above code will not debug itself, and you will have to set breakpoints and trace calls to determine the point of first failure. (And the code above gambles that the truncated file does not exist or is not under an adversary's control by blindly performing the <tt>open</tt>).

== Runtime ==

The previous sections concentrated on setting up your project for success. This section will examine additional hints for running with increased diagnostics and defenses. Not all platforms are created equal - GNU Linux is difficult to impossible to [http://sourceware.org/ml/binutils/2012-03/msg00309.html add hardening to a program after compiling and static linking]; while Windows allows post-build hardening through a download. Remember, the goal is to find the point of first failure quickly so you can improve the reliability and security of the code.

=== Xcode ===

Xcode offers additional [http://developer.apple.com/library/mac/#recipes/xcode_help-scheme_editor/Articles/SchemeDiagnostics.html Application Diagnostics] that can help find memory errors and object use problems. Schemes can be managed through ''Products'' menu item, ''Scheme'' submenu item, and then ''Edit''. From the editor, navigate to the ''Diagnostics'' tab. In the figure below, four additional instruments are enabled for the debugging cycle: Scribble guards, Edge guards, Malloc guards, and Zombies.

{| align="center"
| [[File:toolchan-hardening-1.png|thumb|450px|Figure 2: Xcode Memory Diagnostics]]
|}

There is one caveat with using some of the guards: Apple only provides them for the simulator, and not a device. In the past, the guards were available for both devices and simulators.

=== Windows ===

Visual Studio offers a number of debugging aides for use during development. The aides are called [http://msdn.microsoft.com/en-us/library/d21c150d.aspx Managed Debugging Assistants (MDAs)]. You can find the MDAs on the ''Debug'' menu, then ''Exceptions'' submenu. MDAs allow you to tune your debugging experience by, for example, filter exceptions for which the debugger should snap. For more details, see Stephen Toub's ''[http://msdn.microsoft.com/en-us/magazine/cc163606.aspx Let The CLR Find Bugs For You With Managed Debugging Assistants]''.

{| align="center"
| [[File:toolchan-hardening-2.png|thumb|450px|Figure 3: Managed Debugging Assistants]]
|}

Finally, for runtime hardening, Microsoft has a helpful tool called EMET. EMET is the [http://support.microsoft.com/kb/2458544 Enhanced Mitigation Experience Toolkit], and allows you to apply runtime hardening to an executable which was built without. Its very useful for utilities and other programs that were built without an SDLC.

{| align="center"
| [[File:toolchan-hardening-3.png|thumb|450px|Figure 4: Windows and EMET]]
|}

== Authors and Editors ==

* Jeffrey Walton - jeffrey, owasp.org
* Jim Manico - jim, owasp.org
* Kevin Wall - kevin, owasp.org