Adobe Acrobat Reader – Tip to improve readability

If you are like me having tough time reading the text in Figure 1 using Adobe Acrobat Reader, well there is a way out. Following the below step to enable smooth rendering:

Edit -> Preferences -> Page Display -> Rendering -> Smooth Text -> Select ‘For Monitor’.

Voila

Without smooth rendering
Figure 1: Without smooth rendering
With smooth rendering
Figure 2: With smooth rendering

How to secure your REST service? Part 3 – Accessing SSL-secure service via cURL

If you access the HTTPS url via cURL, you will get the below error. This is curl’s way of warning you that the server certificate is self-signed and could not be validated against it’s ‘CA bundle’ (list of pre-downloaded certificates that are safe).

curl: (60) SSL certificate problem: self signed certificate
 More details here: http://curl.haxx.se/docs/sslcerts.html
curl performs SSL certificate verification by default, using a "bundle"
 of Certificate Authority (CA) public keys (CA certs). If the default
 bundle file isn't adequate, you can specify an alternate file
 using the --cacert option.
 If this HTTPS server uses a certificate signed by a CA represented in
 the bundle, the certificate verification probably failed due to a
 problem with the certificate (it might be expired, or the name might
 not match the domain name in the URL).
 If you'd like to turn off curl's verification of the certificate, use
 the -k (or --insecure) option.

In our case since it is a self-signed certificate we created for manual purposes, we need to let cUrl know that is ok to communicate with this URL. There are 2 ways to do it:

  1. Using curl -k option to connect to the SSL site without certificate. Of course, this in not safe.
  2. Add our self-signed certificate to the default CA certificate bundle. Curl’s default CA bundle is stored in a file called ca-bundle.crt. If you don’t find it in your machine, there are couple of ways to get it.

(A) Download the generic version from curl website.
curl http://curl.haxx.se/ca/cacert.pem -o C:\Fig\ca-bundle.crt
(B) If you are not comfortable using the generic version, you can download the source code for curl from github and generate it locally as follows: (Reference: https://gist.github.com/jjb/996292)

git clone https://github.com/bagder/curl.git
cd curl/lib

//edit mk-ca-bundle.pl and change http to https in the below line:
my $url = 'http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt?raw=1';

perl ./mk-ca-bundle.pl //creates the ca-bundle.crt file.

Before appending our certificate to the above ca-bundle.crt file, we need to first download the self-signed certificate from the server.
(1) Downloading server certificate locally

(a) From browser you can save the certificate directly in a .cer file. This file needs to be converted to PEM format using

C:\OpenSSL-Win64\bin\openssl x509 -inform DES -in c:\figserver.cer -out C:\figservercert.pem -text

(b) Via OpenSSL: enter below command with your own server name and HTTPS port. After the certificate details are printed on the console, type QUIT.

C:\apps\OpenSSL-Win64\bin\openssl s_client -connect localhost:8443]
(2) Copy & save the content between the BEGIN & END CERTIFICATE blocks (including BEGIN & END) and append it to ca-bundle.crt file.

Run the curl command now pointing to the local ca-bundle.crt file and access the SSL site.
curl -D- --cacert ./ca-bundle.crt -H "Authorization: Basic Zml6YWxhZG1pbjpmaXphbGFkbWlu" -X GET https://localhost:8443/Fig-0.0.1/fig/task/z4

How to secure your REST service? Part 2 – Using Certificates for encryption

As we saw in the previous article, a simple BASIC authentication over HTTP can protect your REST web service with a username and password. But since they are transmitted over the wire as Base64 encoded text, anybody could misuse it. Using encryption techniques like SSL, the data being sent on wire could be encrypted.

SSL stands for Secure Socket Layer, and it’s a protocol that does two things:

  1. Encrypts your data, which means no hacker can see what your browser sends to the server nor what the server sends to the browser.
  2. Authenticates your website, which means it tells your browser “This website really is who it claims to be.” For example, that when you type your username and password into your PayPal account, that the website really is PayPal, and not a hacker posing as PayPal.

HTTPS just means “HTTP with SSL.” Just as http:// means “this is a website,” seeing https:// means “this is a website, and it’s using SSL to encrypt data and authenticate the website.

In order to enable SSL, we need a certificate which is either self-signed or signed by an external Certificate Authority like Verisign, Thawte, etc.. For testing purposes, let us create a self-signed certificate. For more details on SSL & Certificates, check Tomcat SSL Configuration How-To.

How to create a self-signed certificate?

"%JAVA_HOME%\bin"\keytool -genkeypair -alias fig -keyalg RSA -keypass fig_store_pass -storepass fig_store_pass -keystore C:\Fig\fig.keystore

After answering a few more questions about your name, organization, etc., the self-signed certificate named ‘fig.keystore’ is created.

Note that the keypass and storepass passwords should be same. Otherwise, you get the following error “java.io.IOException: Cannot recover key“.

Verify if the certificate is created properly by this command.

"%JAVA_HOME%\bin"\keytool -list -keystore C:\Fig\fig.keystore

<Enter storepass password from above command to list entries in the given keystore>

How to enable SSL in Tomcat?

Uncomment the below line in $TOMCAT_HOME/conf/server.xml and add the keystore file location and password.

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
 maxThreads="150" scheme="https" secure="true"
 clientAuth="false" sslProtocol="TLS" 
 keystoreFile="C:\Fig\fig.keystore"
 keystorePass="fig_store_pass" />

Also change the <transport-guarantee> value in web.xml to CONFIDENTIAL.

Now if you access the url in a browser, you will be asked for username and password. This is because of the BASIC authentication enabled in Tomcat. You may notice a crossed icon appear before the https protocol. This is because the server runs with a self-signed certificate and browser is warning the client that the server may not be whom it claims it is. In production environment, you should consider getting a signed certificate from trusted Certificate Authorities like Verisign or sign it with your own CA server.

Even if you try accessing the url via http protocol, you will be automatically redirected to https port.

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

Pros & Cons

(+): Using certificates is the most secure way of communicating between client and server.
(-): Involves more work to create and set up certificates and at times expensive. User credentials are stored in the server in plain text which could be potentially compromised.

How to secure your REST service? Part 1 – Using BASIC Authentication

In this series of articles, I will be explaining in detail about securing REST services. It includes configuring authentication, authorization and encryption. To begin with, this article talks about setting up BASIC authentication for a simple REST service running on Apache Tomcat.

Authentication is a process of validating the identity of a client who is trying to access the service. There are different authenticating a client, and the simplest protocol is the BASIC authentication over HTTP.

Steps involved in BASIC authentication

(1) Client sends a request without authentication details. e.g.,

Request: curl -D- -X GET localhost:8080/Fig-0.0.1/fig/task/123

(2) Server responds back with error code 401 which denotes unauthorized request. e.g.,

 HTTP/1.1 401 Unauthorized
 Server: Apache-Coyote/1.1
 WWW-Authenticate: Basic realm="jaxrs"
 Content-Type: text/html;charset=utf-8
 Content-Length: 951
 Date: Thu, 05 Dec 2013 00:12:37 GMT

(3) Client sends Base64-encoded username & password in request. e.g.,

curl -D- -H "Authorization: Basic bXl1c2VybmFtZTpteXBhc3Njb2Rl" -X GET localhost:8080/Fig-0.0.1/fig/task/123

(4) Server receives the request, decodes the credentials and compares it with the server version. If the credentials match, then it responds back with status code 200.

 HTTP/1.1 200 OK
 Server: Apache-Coyote/1.1
 Cache-Control: private
 Expires: Wed, 31 Dec 1969 19:00:00 EST
 Content-Type: text/plain
 Content-Length: 325
 Date: Thu, 05 Dec 2013 05:39:46 GMT

Steps to enable BASIC authentication in Apache Tomcat

How to add users, roles and passwords?

Under your tomcat installation, look for $TOMCAT_HOME/conf/tomcat-users.xml file. Add the below lines which defines 2 users and assigns specific roles to them.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
   <role rolename="admin"/>
   <role rolename="developer"/>
   <user username="dev1" password="devpassword1" roles="developer"/>
   <user username="admin1" password="adminpassword1" roles="admin"/>
</tomcat-users>

How to enable BASIC authentication in Tomcat?

Now that the users and roles are added, let us activate the authentication in our web application. Open your application’s web.xml and add the following.

  <security-constraint>
    <!-- Specifies the part of the application to be authenticated --> 
    <web-resource-collection>
       <web-resource-name>Secure Task Services</web-resource-name>

       <!-- Denotes which URI patterns needs to be protected. -->
       <url-pattern>/task/*</url-pattern>

       <!-- Only POST, PUT & DELETE calls are authenticated. Omitting http-method tag 
       altogether will secure all access to the url-pattern above -->
       <http-method>POST</http-method>
       <http-method>PUT</http-method>
       <http-method>DELETE</http-method>
    </web-resource-collection>

    <!-- Specifies which roles defined in tomcat-users.xml have access to the resources. -->
    <auth-constraint>
       <role-name>admin</role-name>
    </auth-constraint>

    <!-- Requests are processed without encryption -->
    <user-data-constraint>
       <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
 </security-constraint>

 <!-- Denotes the authentication method, which in our case is BASIC -->
 <login-config>
    <auth-method>BASIC</auth-method>
 </login-config>

That’s about it. If you bounce the Tomcat and try to access the resources via POST/PUT/DELETE method, you will be access for credentials.

Advantages of BASIC authentication: Very easy to set up authentication.
Disadvantages of BASIC authentication: Username/password can be easily sniffed out by attackers since it is just encoded, and not encrypted.

Encrypted HTTP Request

Using an encrypted HTTP connection like HTTPS where packets are encrypted with SSL solves the downside of BASIC authentication. To enable HTTPS, uncomment the below lines in $TOMCAT_HOME/conf/server.xml .

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
 maxThreads="150" scheme="https" secure="true"
 clientAuth="false" sslProtocol="TLS" />

and change the <transport-guanrantee> value in web.xml to CONFIDENTIAL instead of NONE.

Markdown Syntax Quick Reference

To try out the below syntax: http://daringfireball.net/projects/markdown/dingus

_italics_

**bold**

_**bold and italic**_

# Header one

Header One
==========

## Header two

Header two
----------

### Header three

#### Header four

##### Header five

###### Header six

[Click here to Google](www.google.com)

![Image alternative text](http://octodex.github.com/images/octdrey-catburn.jpg)

> Following text is displayed in a blockquote. For multi-quotes, add > on each line.

Unordered list
 * item 1
 * item 2
 * item 3

Ordered list
 1. item 1
 2. item 2
 3. item 3

Paragraph
 Two spaces after each line..
 creates a paragraph structure..
 like the one showed here

Spock Specification Framework – My Study Notes

import spock.lang.Specification

class HelloWorldSpec extends Specification {

    /**
     * Following are the 4 fixture methods
     */
    def setup() { println '  setup' } // run before every feature method
    def cleanup() { println '  cleanup' } // run after every feature method
    def setupSpec() { println 'setupSpec' }// run before the first feature method 
    def cleanupSpec() { println 'cleanupSpec' } // run after the last feature method 

    //Feature method names are string literals. Give meaningful names to them.
    def "Example 1: expect-where model"() {
        expect: "stimulus. Use block descriptions like this to describe a block"
        a == b
        where: "response expected"
        a | b
        1 | 1
    }

    //Features methods should at least have one of the six blocks:
    //setup, expect, where, when, then, cleanup
    def "Example 2: expect-where model with explicit setup block"() {
        setup: "explicit set up block. should be 1st block in a feature. setup: label is optional."
        def stack = new Stack()
        expect: a == b
        where: "where block is always the last block and not repeated"
        a | b; 1 | 1;
    }

    def "Example 3: expect-where model with implicit setup block"() {
        println 'implicit set up' //should be 1st block in a feature. setup: label is optional.
        expect: a == b
        cleanup: 'custom clean up method'
        where: a | b; 1 | 1;
    }

    def "Example 4: when-then model"(){ //when and then always appear together
        setup: "create new stack"
        def stack = new Stack()
        when: "stimulus"
        //may contain any arbitrary code
        stack.pop()

        then: "response - only conditions, exception conditions, interactions, and variable definitions are allowed here"
        true != false //Condition: Evaluated according to Groovy truthness
        thrown(EmptyStackException) //Exception condition - only 1 is allowed in a block
        stack.empty //other conditions can follow exception condition

        cleanup: "custom clean up - should be the last block in when-then model."
    }

    def "Example 5: when-then model continued"(){
        setup:
        def stack = new Stack()
        when: "when and then always appear together"
        stack.pop()

        then: "Alternative exception condition. Another way is using notThrown(exception)"
        EmptyStackException e = thrown()
        e.cause == null
    }

    def "Example 6: given-when-then model "(){ //when and then always appear together
        given: "BDD stories are well described in given-when-then model. given: is just an alias for setup:"
        def stack = new Stack()
        and: "and: is used to describe individual parts of a block"
        when:
        stack.push(1)
        and: "another and: block inside when:"
        println 'hello'

        then: "Another way of exception condition is using notThrown(exception)"
        notThrown(NullPointerException)
    }

    def "Example 7: expect only model"(){
        expect: "more limited compared to 'then' block. may only contain conditions and variable definitions."
        12 > 10 // good for single line expressions. Use this model to express purely functional methods.
    }

    def "Directives"(){
        /*
        @Timeout - Sets a timeout for execution of a feature or fixture method.
        @Ignore - Ignores a feature method.
        @IgnoreRest - Ignores all feature methods not carrying this annotation. 
                      Useful for quickly running just a single method.
        @FailsWith - Expects a feature method to complete abruptly. 
                     It has two use cases:
                     First, to document known bugs that cannot be resolved immediately.
                    Second, to replace exception conditions in certain corner cases 
                    where the latter cannot be used (like specifying the behavior 
                    of exception conditions). 
                    In all other cases, exception conditions are preferable.
        */
    }

    def "Example 8: Simple Parameterization"(){
        expect: a + b == c
        where: "triggers 3 iterations with element (i) from each list"
        a << [1,2,3]
        b << [2,3,4]
        c << [3,5,7]
    }

    def "Example: Interactions example - events are published to all subscribers"() {
        setup: "Interactions outside of then: are global whose scope is within the feature method"
        def subscriber1 = Mock(Subscriber) //dynamic mocking
        Subscriber subscriber2 = Mock() //static mocking
        def publisher = new PublisherImpl()
        publisher.add(subscriber1)
        publisher.add(subscriber2)
        subscriber1.isAlive() >> true

        when:
        publisher.send("event")
        subscriber1.isAlive()

        then: "Optional and required interactions"

        //cardinality is mandatory for required interactions
        // n * subscriber.receive(event)      // exactly n times
        // (n.._) * subscriber.receive(event) // at least n times
        // (_..n) * subscriber.receive(event) // at most n times
        1 * subscriber1.receive("event") //asserts the required interaction happened exactly once
        1 * _.receive("event") // asserts the receive is called on any mock object

        subscriber1.isAlive() >> true // optional interaction
    }
}

interface Publisher{
    void add(Subscriber subscriber)
    void send(event)
}

interface Subscriber{
    void receive(event)
    boolean isAlive()
}

class PublisherImpl implements Publisher{
    def subscribers = []
    @Override
    void add(Subscriber subscriber) {
        subscribers.add(subscriber)
    }

    @Override
    void send(Object event) {
        subscribers.each {subscriber -> subscriber.receive(event)}
    }
}

Groovy – My Study Notes – Part 1

Overview

  • Use Groovy for flexibility and readability. Use Java for performance
  • Runs on JVM – Groovy is nothing but a new way of creating Java classes – Java code can be called from Groovy and vice-versa
  • Every Groovy type is a subtype of java.lang.Object – Every Groovy object is an instance of a type in the normal way
  • Groovy class IS A Java class
  • Groovy supports dynamic typing
  • To compile a Groovy script – { groovyc –d classes Foo.groovy }
  • To run a compiled Groovy class in Java – { java -cp $GROOVY_HOME/embeddable/groovy-all-1.0.jar:classes Foo }
  • To run a Groovy script – {groovy Foo.groovy}
  • Behind the scenes it compiles to a Java class and executes
  • Any Groovy code can be executed this way as long as it can be run; that is, it is either a script, a class with a main method, a Runnable, or a GroovyTestCase.
  • Groovy is purely object-oriented
    • everything is an object. E.g 2*3 //though they look like primitives, they are actually java.lang.Integer objects
    • every operator is a method call. E.g. a+b //logic for the + operator is implemented in method plus() on the object
  • Groovy automatically imports following packages: groovy.lang.*, groovy.util.*, java.lang.*, java.util.*, java.net.*, and java.io.* as well as the classes java.math.BigInteger and BigDecimal.
  • Say there is a Groovy class called Foo, we can use Foo objects without explicitly compiling the Book class as long as Foo.groovy is on the classpath.
  • A Groovy script can also have class definitions inside them. 

Control Structure

Boolean Evaluation

Groovy’s == Is Equal to Java’s equals only if the class does not implement the Comparable interface. If it does, then it maps to the class’s compareTo() method.. Reference comparison is done via is() method. Custom truth conventions can be added by implementing asBoolean() method.
str = 'Hello'
if(str) println str + 'World' //Groovy checks if the object reference is null
list = [1]
if(list) println list //Groovy checks if list is not-null and not empty

Safe-navigation operator (?.) 

eliminates the mundane null check. If input is null, returns null instead NPE
def foo(str) { if (str != null) { str.reverse() } } //Before
def foo(str) { str?.reverse() } //After

Looping methods

Using Ranges: for(i in 0..5){println i}  //prints 0,1,2,3,4
Using times function: 5.times { println "$it" } //prints 0,1,2,3,4
Using upto function: 0.upto(5) { println "$it" } //prints 0,1,2,3,4
Using step function: 0.step(5, 2) { println "$it" } //prints 0,2,4

Static imports

import static Math.random as rand 
double value = rand() // alias name is used here to avoid confusion among static imports

OOPS

  • All methods and classes are public by default.
  • Getters and setters are automatically created by Groovy. No setters created for final fields. To prevent non-final fields from modification, implement setter method manually and throw an error.
  • “hello”.class.name instead of “hello”.getClass().getName(). This class property has special meaning in Map and Builders so it won’t work.
  • We can use ‘this’ within static methods to refer to the Class object.

Basics

Optional Parameters

  • With Default value
def log(x, base=10) { Math.log(x) / Math.log(base) }
log(1024) //default base 10 is used
log(1024, 2)
  • Trailing array parameter as optional. Much like Java varargs.
def task(name, String[] details) { println "$name - $details" }
task 'name1'
task 'name2', 'blah..'
task 'name3', 'blah..blah..'

Named arguments in method calls

  • Class with no-argument constructor
class Robot { def type, height, width }
robot = new Robot(type: 'arm', width: 10, height: 40)
println "$robot.type, $robot.height, $robot.width"
  • Excess Parameters as Map – If the number of arguments sent is more than what the method parameters, and if the excess arguments are in name-value pair, then Groovy treats the name-value pairs as a Map.
class Robot { 
  def access(location, weight, fragile) {
    println "Received fragile? $fragile, weight: $weight, loc: $location"
  }
}
new Robot().access(x: 30, y: 20, z: 10, 50, true)
//You can change the order
new Robot().access(50, true, x: 30, y: 20, z: 10, a:5)

Multiple Assignments

  • Method returning an array is assigned to multiple variables 
def splitName(fullName) { fullName.split(' ') }
def (firstName, lastName) = splitName('James Bond')
println "$lastName, $firstName $lastName"
  • Swapping two variables without a temporary variable using above technique
def (first, last) = ["James", "Bond"]
(first, last) = [last, first]
println "$first $last"

Implementing Interface

Block of code morphed as the implementation of an interface

interface Greeting { void greet(greeting) }
interface WellWisher { void wish(wish) }
void greeter(Greeting greeting){ greeting.greet()}
void wellwisher(WellWisher wellwisher){ wellwisher.wish()}

greeter(new Greeting(){ void greet(greeting){println 'Java style'}}) 
groovyStyle = {println 'Groovy style'}
greeter(groovyStyle as Greeting) 
//block of code is morphed into an implementation of the
// interface via 'as' operator
wellwisher(groovyStyle as WellWisher)
  • Groovy does not force us to implement all the methods in an interface. Very useful while mocking for unit testing.
  • Implementation of multi-method interface as a Map
interface Greeting { void greet(greeting); void wish(wish); void regard(regard); }
void callMe(Greeting greeting){ greeting.greet(); greeting.wish()}
//method name as key, implementation as value. Not all methods are implemented
greetingsMap = [ greet: {println 'Greet Hello World'}, wish: {println 'Wish Hello World'} ] 
callMe(greetingsMap as Greeting)

Operator Overloading

Each operator has a standard mapping to methods.

== equals
+ plus
- minus
++ next
.. next (for-each syntax)
-- previous
<< leftShift
<=> compareTo
  • Example 1: for (ch in ‘a’..’c’) { println ch }
  • Example 2: lst = [‘hello’]; lst << ‘there’; println lst
  • Example 3: Custom class and operator overriding
class Name{
  def name; 
  def plus(other){
    new Name(name: name + "~~" + other.name)
  }
  String toString() { "name: " + name}
}
def name1 = new Name(name: "Hello")
def name2 = new Name(name: "World")
println name1 + name2

Annotations

  • groovyc ignores @Override
  • @Canonical – auto-generates toString() implementation as comma-separated field values
import groovy.transform.*
@Canonical(excludes="age, password")
class Person {
  String firstName, lastName, password
  int age
}
def sara = new Person(firstName: "Sara", lastName: "Walker", age: 49, password: "passw0rd")
println sara
  • @Delegate
import groovy.transform.*
class Worker {
  def work() { println 'get work done' }
  def analyze() { println 'analyze...' }
  def writeReport() { println 'get report written' }
}
class Expert {
  def analyze() { println "expert analysis..." }
}
class Manager {
  //At compile time, Groovy examines the Manager class and brings 
  // in methods from the delegated classes only if those methods 
  // don’t already exist
  @Delegate Expert expert = new Expert() 
  //only work() and writeReport() methods are brought here
  @Delegate Worker worker = new Worker()
}
def bernie = new Manager()
bernie.analyze()      //invokes Expert.analyze()
bernie.work()         //invokes Worker.work()
bernie.writeReport()  //invokes Worker.writeReport
  • @Immutable – Groovy adds the hashCode(), equals(), and toString() methods
import groovy.transform.*
@Immutable
class CreditCard { String cardNumber; int creditLimit }
println new CreditCard("4000-1111-2222-3333", 1000)
  • @Lazy – provides a painless way to implement the virtual proxy pattern with thread safety as a bonus
class AsNeeded {
def value
  //heavy1 and heavy2 are lazy-initialized only at the time of invocation
  @Lazy Heavy heavy1 = new Heavy()
  @Lazy Heavy heavy2 = { new Heavy(size: value) }()
  AsNeeded() { println "Created AsNeeded" }
}
  • @Newify – Create objects via Ruby-like and Python-like constructors without using ‘new Foo()’ style. Comes handy in DSL creation.
@Newify([CreditCard, Person]) //specify the list of types here. 
def fluentCreate() {
  println CreditCard("1234-5678-1234-5678", 2000) //Python-like constructor invocation with new keyword
  println Person.new("John", "Doe") //Ruby-like constructor invocation where new() is a method
}
fluentCreate()
  • @Singleton
@Singleton(lazy = true)
class TheUnique {
  private TheUnique() { println 'Instance created' }
  def hello() { println 'hello' }
}
TheUnique.instance.hello()
TheUnique.instance.hello()
new TheUnique().hello() //Caveat: since Groovy does not honor private methods, clients can still do this.
  • @InheritConstructors
@Canonical
class Car {
  def make, model, year
  Car(make, model){ this.make = make; this.model = model; this.year = 2000; }
  Car(make, model, year){ this.make = make; this.model = model; this.year = year; }
}
@InheritConstructors
class Honda extends Car{
  //no need to explicitly override all the constructors here
}
println new Car("Honda", "Accord")