One thing they handle well is the concept of certificate extensions. X.509 v3 certificates introduced the concept of these extensions, which are basically additional (potentially optional) fields containing information not contained in the older original X.509 specifications. Each extension is specified by an OID (Object Identifier); a good list of these extensions is available.

While it’s easy to read these extensions from an existing X.509 v3 certificate using the Bouncy Castle APIs it is a bit more involved to read these extensions from a Certificate Signing Request, or CSR; this is the data structure that is sent to a CA to request a certificate. The CA then reads the data from this and creates a signed certificate issued to the requester. In this guide I’ll present a brief way to extract X.509 extensions request from a CSR so that they may be included in the resulting issued certificate.

Code: The good stuff

Assuming you have added the Bouncy Castle JARs to your classpath, you should have access to the classes used here.

You must first have the CSR in the format of a Bouncy Castle data object, namely the PKCS10CertificationRequest. If all you have is the PEM-format of the CSR (i.e. Base64-encoded contents delimited by headers like ----- BEGIN CERTIFICATE REQUEST ----- and ----- END CERTIFICATE REQUEST -----) then you will need to convert this to the proper data structure using something like
PEMUtil from Commons-SSL like I have done below. (BC has a PEMUtil class as well, but it appears to be only for internal use)

// NOTE: Commons-SSL doesn't support generics.
final List pemItems = PEMUtil.decode( csrContent.getBytes() );

// Verify list isn't empty - uses Apache Commons Lang.
Validate.isTrue( !pemItems.isEmpty() );

// No support for generics, so have to cast. (Could have cast the entire List)
final PEMItem csrPemFormat = (PEMItem) pemItems.get( 0 );

// Verify the type.
Validate.isTrue( csrPemFormat.pemType.equals( "CERTIFICATE REQUEST" ),
  "This is not a CSR" );

final PKCS10CertificationRequest csr = new PKCS10CertificationRequest(
  csrPemFormat.getDerBytes() );

We first decode the PEM (Base64) CSR into List of PEMItems. Note that Commons-SSL doesn’t support generics, so you are going to get a cast warning somewhere in the code, no matter what. When calling getBytes() on the CSR string, you may want to specify the US-ASCII character set, since the no-arg method uses the platform default character set, which might give inconsistent results across different systems when converting from characters to bytes.

We then grab the first entry in the list, checking if it is a CSR. We can now convert this into the proper data structure by supplying the raw bytes (i.e. the DER-encoded format) to the constructor of PKCS10CertificationRequest.

The method to extract the X509Extensions structure from the PKCS10CertificationRequest is shown below.

   /**
    * Gets the X509 Extensions contained in a CSR (Certificate Signing Request).
    *
    * @param certificateSigningRequest the CSR.
    * @return the X509 Extensions in the request.
    * @throws CertificateException if the extensions could not be found.
    */
   X509Extensions getX509ExtensionsFromCsr(
         final PKCS10CertificationRequest certificateSigningRequest ) throws CertificateException
   {
      final CertificationRequestInfo certificationRequestInfo = certificateSigningRequest
            .getCertificationRequestInfo();

      final ASN1Set attributesAsn1Set = certificationRequestInfo.getAttributes();

      // The `Extension Request` attribute is contained within an ASN.1 Set,
      // usually as the first element.
      X509Extensions certificateRequestExtensions = null;
      for (int i = 0; i < attributesAsn1Set.size(); ++i)
      {
         // There should be only only one attribute in the set. (that is, only
         // the `Extension Request`, but loop through to find it properly)
         final DEREncodable derEncodable = attributesAsn1Set.getObjectAt( i );
         if (derEncodable instanceof DERSequence)
         {
            final Attribute attribute = new Attribute( (DERSequence) attributesAsn1Set
                  .getObjectAt( i ) );

            if (attribute.getAttrType().equals( PKCSObjectIdentifiers.pkcs_9_at_extensionRequest ))
            {
               // The `Extension Request` attribute is present.
               final ASN1Set attributeValues = attribute.getAttrValues();

               // The X509Extensions are contained as a value of the ASN.1 Set.
               // Assume that it is the first value of the set.
               if (attributeValues.size() >= 1)
               {
                  certificateRequestExtensions = new X509Extensions( (ASN1Sequence) attributeValues
                        .getObjectAt( 0 ) );

                  // No need to search any more.
                  break;
               }
            }
         }
      }

      if (null == certificateRequestExtensions)
      {
         throw new CertificateException( "Could not obtain X509 Extensions from the CSR" );
      }

      return certificateRequestExtensions;
   }

Basically, we get the certificate request info from the CSR structure and then extract attributes from it. Then, we loop through to find the attribute with the “Extension Request” OID.

After that, I make an assumption that the actual extensions are contained in the first value of the place of the ASN.1 Set that makes up the “Extensions Request” structure - not a big assumption, and in my testing I haven’t encountered a situation where this wasn’t the case. It’s worthwhile to keep in mind that ASN.1 often prescribes Set or multi-value structures in places where the underlying data can only be single-valued.

After running through that code, we’ll have either found the extensions, and be returning them in a X509Extensions structure, or an exception will be thrown. You could modify the code to return null if that suits your style or purpose better.

A few more notes

Once you have the X509Extensions structure you can use the extensions contained within to create/issue a certificate with them. Check out the Bouncy Castle Guide on Certificate Generation for more details.

Note that a CA is not required to use any of the extension requests present in a CSR - hence the name “requests”. It is entirely up to the CA to decide what extensions are appropriate, along with their values, for the certificates that it issues.

Code Review

The code is a little complicated and could probably benefit from some refactoring. However, a lot of the complexity derives from the fact that the X.509 and associated standards are quite complex themselves. This is a reflection on the vision that the designers of X.509 had for the future of the standard. However, the complexity of X.509 is another topic for another article.

I hope you found this article useful, as while I found lots of information for generating CSRs, information on parsing and working with them was a little sparse. Please feel free to leave your comments below!

I had been using input validation, but my validation procedure was not stringent enough to detect the improper parameter. This was tied to the fact that before the implementation change, things worked perfectly fine even with the improper inputs. However, the implementation change “broke” this work flow. All of this has led me to believe in the great importance of:

1. Draconian validation: For inputs, only accept what you say you will accept. Nothing else should pass.
2. Proper unit testing: Test your method with a variety of inputs, both expected and unexpected or non-conforming. You never know what callers will pass into your methods.

Let me go into some more detail.

Unintended consequences

I had written a method that would accept a FQDN (Fully-Qualified Domain Name) as its argument. The purpose of this method was to retrieve some information over HTTPs from the web server running on the server with the specified domain. Since domain names are protocol-neutral (i.e. they aren’t preceded by something like “http://”), I ended up forming a URL object based on the FQDN, since eventually I’d be retrieving information over HTTPs anyways:

final URL url = new URL("https://" + fqdn + "/path_to_service");

I figured that this was enough protection in terms of input validation, since the constructor for URL throws a MalformedURLException if something goes wrong. (There was other code to check if the web server at the specified URL could actually be contacted and this was contained in the actual retrieval)

However, it turned out that callers had started using this method by passing in not just an FQDN, but an FQDN followed by a port number in the following format: host.name:portNumber. This was being used so that servers operating on non-default HTTPs ports could be contacted.

Initially, this worked, as then the statement above was executed with something like this:

// With fqdn == "some.host.name:portNumber", nothing fails.
final URL url = new URL("https://" + fqdn + "/path_to_service");

This was because the URL formed was still valid. However, this was an invalid use of my method because we had never specified that this sort of input was allowed. It just happened to work. The issue of non-default HTTPs ports and the usage here was never discussed and because it seemingly worked, nothing was done about it.

Changing times

Some time went on until I decided to make an implementation change. Instead of retrieving the information from the web server itself, I would instead retrieve it directly from the TLS handshake process using a API provided to me. (The information was related to the certificates)

This API accepted two parameters: The server host name or FQDN, and a separate port number. Not realizing that callers were passing in non-default port numbers in the first place, I ignorantly just passed the FQDN supplied to me into this API along with the default HTTPs port. (443)

As expected, this broke the functionality that callers had come to expect of my API, namely, custom HTTPs ports specified alongside the FQDN in the argument. It was only after these complaints were filed that I realized my API was expected to take not just the FQDN, but something like “server.host.name:8080″.

The causes

The problem was quickly fixed as the solution was fairly trivial, but the causes have taught me several lessons.

1. Be Draconian in your input validation

   Or, don’t trust your callers to read your documentation. Initially, I thought my method was to accept only an FQDN. Even though I was wrong in this respect, the problem could’ve been identified earlier if I had coded my method to fail (i.e. throw an exception) if anything that was not an FQDN was passed in. (Simply forming a URL object around it was not stringent enough) This way, things wouldn’t have initially worked by coincidence and I would’ve had an earlier opportunity to correct my mistake.

2. Unit test for exceptional cases

   My unit testing of my method was not extensive enough. Though I coded both pass and fail tests using JUnit, I did not test for cases where someone would (very likely) try to pass in a port number along with the FQDN. This step goes hand-in-hand with the above: Code your methods to accept only what you’ve said they’d accept, and fail on everything else. Then, unit test to make sure this contract is fulfilled.

While the problem was frustrating, I’m glad to have learned these lessons.

* Sensationalist headline inspired by previous posts

Eclipse is my IDE of choice, as you’l probably have noticed from some of my previous articles. I had been wanting to write an article about why I use it (and why I switched to it), but kept putting it off. Recently, Matt Mullenweg wrote about his problems with Dreamweaver, and this perhaps prompted me to organize my notes on why I’ve chosen to use Eclipse. Don’t get me wrong - I’m not advocating that you immediately switch and throw out your current editing tool (the headline above, as noted, is purely for sensationalism) - but rather I’m just urging you to consider Eclipse for your next project.

Changing Gears

Like many, before switching to Eclipse I had been using a pure text editor, Ultraedit, for most of my web-development activities. Ultraedit seemed fine for most things, offering basic features like code highlight and autocompletion. However, it lacked a certain finesse when it came to dealing with larger projects. For example, if you’d defined a class, its members wouldn’t be available for autocompletion. Something else was needed. I finally decided to take the plunge, and switch over to Eclipse for all my development towards the end of the summer last year.

Some might wonder why I was even using a text-editor in the first place for development. For those coming from a traditional programming/development background, the idea of not using an IDE (Integrated Development Environment) is silly. This is because a lot of programming languages are compiled, and in this case, it just makes sense to use an IDE since it’s easier to write code, compile and debug using one tool instead of multiple ones.

However, for scripting languages, especially those meant to run on a web server, one can “get away” with not using an IDE quite easily. This is because the scripts are not run standalone but are almost always executed in the context of a web server; thus you’re usually editing code that you then run on a development web server, without the need for a special tool like a compiler. Additionally, it’s easy to view the output using any web browser. These reasons are what allowed me to persist in using a text-editor for so long.

No turning back

However, once I started using Eclipse, I was hooked. I downloaded Eclipse PDT (PHP Development Tools), which is basically a version of Eclipse bundled with the tools/plugins necessary for setting up a PHP development environment. Besides offering everything Ultraedit did, it also offered nice features like easy ‘Todo’ lists, (just type ‘todo’ anywhere in a comment and it’s automatically indexed by Eclipse into a list), code completion for built-in PHP functions and your own as well as a multitude of other advanced features that IDEs have. Oh, and it’s also FOSS. (Free and Open Source Software)

However, perhaps the best part about Eclipse is its robust and well-supported plugin system. This allows Eclipse to pretty much assume any feature that someone is willing to write a plugin for. This is what really sold me on Eclipse, because this almost makes its abilities endless. Some of the plugins I use are Subclipse for SVN integration, Mylyn for Trac integration and JSEclipse for JavaScript editing. This is part of the reason why Eclipse is the basis for many other IDEs out there.

Some other nice features are the ability to link the IDE in with the Zend Debugger, thus allowing for proper debugging sessions with PHP.

Spoiled

However, I’ve been pampered somewhat and have found a few things to complain about, at least when it comes to Eclipse PDT. I use Eclipse JDT (Java) a work and its advanced refactoring abilities are a feature I find myself wanting in the PDT version. Have you ever found yourself wanting to rename a variable to something more descriptive but putting it off because you’re afraid you’ll mess something up by forgetting to change the name somewhere?

With some IDEs, you’re left having to just do a search-and-replace in order to accomplish what should be a trivial name refactor. Even if your editor supports regex searches, things can still be tricky - what if you’ve used the same name, but in a different context, and thus shouldn’t change the variable there? The point is, the process still has to be human-supervised and is tedious. With Eclipse JDT’s advanced refactoring, you can rename the variable once - and the IDE is smart enough to know where else to change it to keep the code consistent - very neat, and I was amazed when I first used it. Other refactoring abilities include extracting methods out of blocks of code in order to clean up lengthy methods. All of this makes your life 10 times easier and allows you focus on real programming rather than annoying tasks.

However, Eclipse PDT doesn’t support this for PHP code, yet. I hear that it may be supported in a later release, so I have my fingers crossed. Perhaps accomplishing these refactoring tasks is easier in Java because of its compiled nature or because the JDT project has received more attention. It’s definitely possible in PHP, as some IDEs, such as the Zend Studio (which is based on Eclipse) support this ability. Zend Studio, however, is a commercial solution and I haven’t tried it out yet.

Nothing’s perfect

Eclipse does have its downsides as compared to a traditional text editor. First of all, it’s a memory hog - though most IDEs are. I have regularly seen Eclipse eat up 300-400 MB of RAM if I’ve been using it for a long time. However, it should be noted that I have not had it crash once, so it’s been rock-solid as far as stability goes. Nonetheless, I recommend you to have at least 2 GB of memory if you really want to use it properly, since you’re likely to have other programs open. This is especially important if you’re running Windows Vista. RAM is quiet cheap nowadays, and you can easily pick up 2 GB for $50 or less and upgrading is a painless process, so there’s no reason not to.

Finishing up

Eclipse has changed my life. Okay, so perhaps I’m exaggerating a bit. But, I can say that development, at least for me, would be much harder without Eclipse. If you’re still using a text editor for development, I urge you to give Eclipse a try - just for 30 days, and see how you like it. I don’t guarantee results as good as mine, but you may be pleasantly surprised.

Software is only a piece of the puzzle

While MySQL is indeed open-source - licensed under the GPL - MySQL AB, the company in control of the project, sells services and support relating to their flagship product. Furthermore, the software is dual-licensed (as are many projects, such as the JavaScript library, jQuery), allowing the company to sell the product to clients that may not want the provisions of the GPL to be imposed upon their usage of the software.

With the traditional model of software, customers and clients pay for the software or a license to use it. In these newer models, almost all based around open-source, it is the value-added service and support that are at the heart of the business model. Note that MySQL AB is not the only company to do this; Red Hat has been around for years and they are certainly profitable. With the success of open-source software, I have to believe that this, at least in part, is the future of software development.

A great learning tool

Open-source software also highlights another point - the value it brings by easing learning. I remember when I was back in high school and starting to get into PHP and other web technologies. Naturally, with PHP came MySQL (back then at version 3.23), and it was the availability of this quality, open-source and easy-to-setup DBMS that prompted me to learn SQL. In my first real software project, creating the Cool Case Gallery for Virtual-Hideout, I used both of these languages, which have since become valuable assets for me. Kudos to MySQL and the open-source community for providing such great tools.