Forem: Ian Spence

Securing Your GitHub Account

Ian Spence — Wed, 11 Mar 2020 18:38:51 +0000

Let's talk about some of the simple & practical steps you can take to improve your GitHub account security.

There's plenty of good reasons why you should try to keep any online account safe, but I feel that GitHub deserves special attention among developers. With automation through CI and CD taking center stage, it's not only important to you but also anybody who might rely on your code to ensure your GitHub account is secure.

The Basics

Let's start with the basics, things that don't just apply to GitHub but to nearly any online service.

Passwords

Let's face it, passwords freaking suck. We all know we're supposed to make them hard to guess and not to reuse them, but who has time to remember each and every password? Nobody, that's who.

But what if there was a solution where you could have unique passwords for each of your accounts, not have to remember them all, and have strong passwords that are difficult for both humans and computers alike to guess?

The solution is a Password Manager. A password manager is a bit of an abstract term that describes a way to record passwords for your accounts in a secure location. These managers can range from web-based services that tie in to your browser, or something as simple as a physical book you write in.

There are advantages and disadvantages to all of these options, but by properly using a manager you're protecting yourself from many common attack scenarios, the most common being password reuse.

If you're looking for a web-based solution, check out 1Password or LastPass. If you want something in-between consider KeepassX. If you want to kick it old school with a book, most office supply stores sell password books - but a good old fashioned phone book will work just as well.

Two-Factor Authentication

Two-Factor authentication, sometimes called "Two-Step" or "Multi-Factor" (MFA), is a security measure provided by some websites to enhance your accounts security.

To understand why Two-Factor authentication works, you first need to understand what a "Factor" is.

Authentication Factors

There are three common authentication factors: "What you know", "What you are", and "What you have".

Passwords and passphrases are things you know. Fingerprints and facial recognition are things your are. Lastly, your cell phone or a physical key are things you have.

One of the many problems with passwords is that while you may know them, other people can know them as well. To a website, it's very difficult to be sure who's who. With two-factor authentication, a website will require that you provide two forms of authentication. Most commonly this is your password, plus a one-time password generated by an app on your phone.

In the event somebody happens to have your password, with two-factor authentication they would also require your cell phone to get in to your account.

Enable Two-Factor Authentication

Click on your Avatar in the top right and select "Settings"
Click on "Security" on the left hand side
Click on "Enable" under "Two-factor Authentication"
Click on "Set up using an app"
Save the recovery codes (Protip: If you're using a password manager, record the codes in the notes section for the websites entry)
Scan the QR code using authenticator app of your choosing
Enter the one-time password from your phone to finish setting up two-factor authentication

Connected Apps

Like many online services, GitHub uses a technology known as OAuth to allow applications to interact with your GitHub account without requiring your username and password.

It's very important that you periodically review the applications you've authorized to use your GitHub account and remove any you no longer use.

Click on your Avatar in the top right and select "Settings"
Click on "Applications" on the left hand side
Click on the "Authorized OAuth Apps" tab
To revoke an app, tap on the "..." for the app and select "Revoke"

Active Sessions

GitHub lets you view active login sessions, and approximately where that computer or device is. It's always a good idea to periodically take a look at the list and ensure that only the devices you intend to use GitHub with are listed. If you see any login sessions from weird devices, or from the wrong country, it could be an indicator that your account is compromised.

To see your active sessions:

Click on your Avatar in the top right and select "Settings"
Click on "Security" on the left hand side
Scroll to the bottom of the page

Take the following example, where my current session is in Canada but a recent login occurred in Romania.

If you see something out of the ordinary here, change your password immediately.

GitHub as a Git Remote

Now that we've covered the basics, let's dive into the real reason why I'm writing this guide: GitHub is, obviously, a Git service.

Avoid using SSH

GitHub, like nearly all Git services, lets you connect to it either one of two ways: using SSH or HTTPS.

From a cryptographic perspective, both of these provide strong encryption and protection against tampering, but there's a huge benefit to using HTTPS that SSH lacks: Public Key Infrastructure, or PKI.

Quick Primer: How PKI works for HTTPS

When you connected to dev.to to read this article your browser performed a TLS Handshake and trust verification with the web server hosting this site. Part of this process is the web server presenting its certificate to your browser. Your browser then looked at the parents of the servers certificate. If the browser trusts the root (or top-level) of the certificate chain, it can mathematically prove that the certificate was issued from a trusted authority, and after performing some additional tests, confirm that the web server is who they say they are.

Why SSH is the wrong choice for Git

SSH lacks nearly all of this, especially all of those additional checks that are done.

When you connect to a host using SSH your computer only has the servers public key to go on to determine trust. If you've never connected to server before, it will prompt you if you want to trust their public key. The next time, if the public key matches it will connect without asking you, but if the public key changes it will show this scary warning at you.

The fatal flaw with SSH's trust mechanism is placing ultimate and permanent trust in the hosts key. Once you've trusted a key, that key can never change without causing errors as seen above. In GitHub's case changing their key would cause huge confusion among its users.

Whereas with HTTPS, GitHub's certificates are rotated regularly without you even realizing it.

SSH also lacks a large amount of other security enhancements that HTTPS has, such as: certificate lifespans, revocation and automatic status checks, transparency, and key usage restrictions.

Now that I've lectured you enough on why SSH is not the right choice, let's look at how we can go about using HTTPS.

Using Access Tokens

Git over HTTPS works just like Git over SSH, you just have to sign in to GitHub with your username and password instead of adding your SSH key to your account.

However, if you're using Two-Factor authentication (You are, right? See the section above). You won't be able to use Git over HTTPS since there's no way to prompt for your one-time password.

Not to worry though, GitHub has you covered with so-called "Access Tokens". These are sometimes called "Application Passwords" on other services and let you sign in on applications that don't support multi-factor authentication. The idea is that you sign in and generate these passwords but only use them for a specific application.

Here's how you generate an access token:

Click on your Avatar in the top right and select "Settings"
Click on "Developer Settings" on the left hand side
Click on "Personal Access Tokens" on the left hand side
Click on "Generate New Token"
Give the token a name and select only the required permissions for the token

Then, when you configure your git remote to use HTTPS you'll be asked to provide your username and password. Use the access token as your password and you've authenticated.

$ git fetch
Username for 'https://github.com': ecnepsnai
Password for 'https://ecnepsnai@github.com': <my access token>

Storing Access Tokens

There are 4 options to store your credentials if you don't want to type your access token every time (Who would?)

Option 1: Don't store them

Didn't I just ask who wants to type their access token out each time? With this, git doesn't remember your credentials. Each time you access the remote, you have to type in your credentials.

Option 2: Cache them for a limited time

This method is marginally better than option 1. Git will remember your username and access token for a limited period of time before requiring you to enter them again. This is similar to how sudo works if you've used that before.

You can enable this method using:

$ git config --global credential.helper 'cache --timeout=3600'

Where 3600 is the number of seconds to cache the credentials.

Option 3: Store them in a plain-text file

This method is the easiest to set up, but not the most secure. With this, git will store your username and access token in a plain-text file in your home directory. It won't prompt you for your username or access token once saved.

You can enable this method using:

$ git config --global credential.helper store

Option 4: Store them using a credential helper

This method can be tricky to set up but provides the best balance of convenience and security. A credential helper is an application that stores keys in a secure location that git can use.

On macOS you can use the systems Keychain, which is encrypted with your users password. See GitHub's documentation on how to setup and configure the credential helper.

On Linux you can use the gnome-keyring package, which is very similar to the Keychain from macOS. Setup varies depending on your distribution and isn't covered in this document.

Anything Else?

That's all for the tips I have in this guide. Do you have any other ideas on ways to protect your account? Let me know in the comments!

All About Apache Cassandra: Snapshots

Ian Spence — Sat, 27 Jul 2019 22:15:23 +0000

Welcome to the inaugural post of "All About Apache Cassandra", a new series of posts I'll be writing about Apache Cassandra exclusively on dev.to!

The concept of a "Snapshot"

In computing, a snapshot is a point-in-time copy of data or state of a machine.

You ever end up doing something like this?

Each one of these files is a snapshot, as it's a copy of your essay at the point-in-time when you saved it.

Snapshots provide us with an easy way to undo changes and backup systems.

How Cassandra Stores Data

Cassandra breaks its data down by Keyspace (which is like a Database in MySQL or Schema in PostgreSQL), and Column Family (a table). Data for the column families is stores on SSTables (Sorted String Tables).

When Cassandra writes to disk it does so by writing a new SSTable. Every SSTable is immutable, so it will always make a new SSTable each time it flushes. A process known as Compaction will automatically merge the tables into a single new table.

For example, if we have a column family named Users in the keyspace App, the data for that table would look like:



<Cassandra Data>/App/Users/
1-big-Data.db
2-big-Data.db
3-big-Data.db
4-big-Data.db

Each big-Data file is a SSTable. Compaction would take all of these tables and merge them into a single, new file 5-big-Data.db.

How Cassandra Takes Snapshots

When you take a snapshot with Apache Cassandra, it creates a Hard Link of all live SSTables. Easy, right? Well it's a little more complex than you might think

What's a hard link?

A hard link is a file that points to the same data as another file.

In UNIX-like systems (Linux, macOS, BSD), the system uses INodes to reference the data on disk, and files on your computer reference INodes. A hard link is a file that shares the same INode as another file.

Hard links are different than Soft Links, which tell the application reading that file where the actual file path is.

The Catch

There's a very important catch with hard links: The data on disk will only be deleted when all references to it are removed.

For example: Inode 1001 references 500MB of data on the disk and we have two files that point to Inode 1001. If we deleted the first link, the 500MB data will still be on disk because of the second link. We won't free up that 500MB from disk until all links have been deleted.

Where Cassandra Stores Snapshots

Since snapshots are hard links of existing files, these files must be on the same filesystem as your data. Therefor, snapshots are stored in the snapshots directory within your Column Family. If we took a snapshot named snapshot1 on our existing Users table, it would result in:



<Cassandra Data>/App/Users/
1-big-Data.db
2-big-Data.db
3-big-Data.db
4-big-Data.db
<Cassandra Data>/App/Users/snapshots/snapshot1
1-big-Data.db (Hard link)
2-big-Data.db (Hard link)
3-big-Data.db (Hard link)
4-big-Data.db (Hard link)

When compaction occurs and the SSTables are merged, our snapshot is unaffected:



<Cassandra Data>/App/Users/
5-big-Data.db
<Cassandra Data>/App/Users/snapshots/snapshot1
1-big-Data.db
2-big-Data.db
3-big-Data.db
4-big-Data.db

Because there is still at least one reference to the data of SSTables 1-4, the system will not delete that data from disk.

How Snapshots Affect Capacity

As with any distributed storage system, calculating your capacity is not as simple as just looking at how much free disk space you have.

Snapshots can have a very large impact on your clusters capacity, and great care is needed if you're considering taking snapshots on a schedule.

Because of that one important catch with hard links (see above), compaction jobs can dramatically increase the amount of data used by snapshots.

When you take a snapshot on a server with no activity whatsoever, that snapshot will not consume any (meaningful) amount of data on disk. But as soon as a new SSTable is written or compaction occurs, that snapshot will begin to take up space, potentially doubling the amount of data on your disk.

Let me try and break it down:

Let's assume you have a 100GB disk, and Cassandra is using 50GB of that for its data.

You take a new snapshot. This isn't going to use that much disk space. Still 50% full.
A major compaction occurs, something like a cleanup or a scrub, which re-writes all tables on disk.
That snapshot now references versions of SSTables that have been rewritten entirely, and is essentially duplicated data. Now 100% full.

Of course, this is a slightly exaggerated example, but the reality is that snapshots and compaction can wreck your disk capacity and ruin your day.

Restoring From a Snapshot

Restoring from a snapshot is a destructive action that will result in the loss of any new data created after the snapshot was taken. You should only restore from a snapshot when you have no other option. There is no automated way to restore Cassandra to a snapshot, it is a manual process.

While the cluster is running:

Truncate the table you need to restore
Stop the Cassandra service

Why truncate? If there are any tombstones remaining, they will be deleted after you restore. Truncating removes any tombstones from that table.

On all nodes in the cluster:

Navigate to the directory for the snapshot you wish to restore from
Copy over all SSTables in that directory into the data directory for the table

Finally:

Start up the service
Run a nodetool refresh

Command Line Reference

As with most operational tasks, you'll be using the nodetool application to manage snapshots on a server. These are some of the commands you might use.

Take a snapshots



nodetool snapshot [options] [keyspace]

Reference: https://cassandra.apache.org/doc/latest/tools/nodetool/snapshot.html

Take a snapshot with a specific name:
nodetool snapshot -t <name>

Take a snapshot on all tables in a specific keyspace:
nodetool snapshot <keyspace>

Take a snapshot on two specific tables:
nodetool snapshot -kt <comma separated list of keyspace.tableName>

List all snapshots



nodetool listsnapshots

Reference: https://cassandra.apache.org/doc/latest/tools/nodetool/listsnapshots.html

Remove one or more snapshots



nodetool clearsnapshot [options] [keyspaces]

Reference: https://cassandra.apache.org/doc/latest/tools/nodetool/clearsnapshot.html

Remove all snapshots:
nodetool clearsnapshot

Remove a snapshot named:
nodetool clearsnapshot -t <snapshot name>

Remove snapshots from a specific keyspace:
nodetool clearsnapshot <keyspace>

What the heck is OCSP?

Ian Spence — Fri, 10 May 2019 01:18:22 +0000

The online certificate status protocol, or OCSP for short, is a way for TLS clients (like your web browser) to check if a certificate has been revoked or not.

Certificate Revocation?

With asymmetrical encryption, your encryption is only as good as long as your private key remains private. This is often not the case and private keys end up exposed.

This is just one of the many possible reasons why a certificate may be revoked. And a certificate authority, or a certificate holder may revoke their certificate to mark it as untrusted. Since there's no way to change a certificate once its been created, status checks are used to see if its been revoked. This is where OCSP comes into play.

A basic example

Let's take a look at the certificate for dev.to, in it we'll see the URL for the OCSP server:

X509v3 extensions:
    Authority Information Access:
        CA Issuers - URI:http://secure.globalsign.com/cacert/cloudsslsha2g3.crt
        OCSP - URI:http://ocsp2.globalsign.com/cloudsslsha2g3

If OCSP is enabled in your web browser (which it probably isn't, we'll get to that later), when you browsed to dev.to your browser made a quick HTTP request to ocsp2.globalsign.com/cloudsslsha2g3 with the SHA1 fingerprint of the certificate. Globalsign, the CA for dev.to's certificate, will check its database for that certificate and if its been revoked or not, and respond back with a signed response.

Depending on the response from the OCSP server, the browser may either continue on to the site or consider the certificate revoked and untrustworthy.

HTTP? SHA-1? What year is this?

Yup, you read that right. OCSP requests are all in good-old insecure HTTP, and most clients use typically end up using SHA-1 fingerprints.

The reason OCSP operates over HTTP is because if it operated over HTTPS, then we'd have to check the status of the certificate used for the OCSP server, then that server, and the next one, and so on and so on. We'd end up in a forever loop of checking certificates. OCSP responses are signed to prevent tampering.

The OCSP specification mandates that SHA-1 must be the minimum required hashing algorithm for servers and clients, giving room for more secure hashing algorithms to be used. However, since status checks are meant to be fast, TLS Clients often don't want to get stuck in a retry loop trying to negotiate a algorithm with the server. Therefor, most clients use the default of SHA-1 and just live with it.

Are there privacy concerns?

You bet! With OCSP, an extra third-party is made aware of you browsing to a website that typically wouldn't know otherwise.

With our above example, GlobalSign knows that you visited dev.to from a specific IP, with a specific browser, at a specific time. All because of OCSP.

Thankfully, there is a commonly implemented and accepted solution: OCSP Stapling.

With OCSP stapling, the web server itself makes an OCSP request on your behalf and includes it with the connection information. This means that the third-party does not know who connected to that site at that time, only that somebody did.

Getting the OCSP URL from a X.509 Certificate

The OCSP URL for a certificate in within the “Certificate Authority Information Access” extension. To get the URL of the responder, get the information access extension, then iterate through each possible item for that extension and locate the OCSP object. It’s a IA4 ASN1 string value, so you’ll need to decode it to use it as a regular string.

X509 * cert;
char * ocspURL;

AUTHORITY_INFO_ACCESS * info = X509_get_ext_d2i(cert, NID_info_access, NULL, NULL);
int len = sk_ACCESS_DESCRIPTION_num(info);
for (int i = 0; i < len; i++) {
    // Look for the OCSP entry
    ACCESS_DESCRIPTION * description = sk_ACCESS_DESCRIPTION_value(info, i);
    if (OBJ_obj2nid(description->method) == NID_ad_OCSP) {
        if (description->location->type == GEN_URI) {
            // Hold on to this URL for later use
            ocspURL = i2s_ASN1_IA5STRING(NULL, description->location->d.ia5);
        }
    }
}

Generating a OCSP request

An OCSP request is one or more "Key IDs", which is a fingerprint of the certificate. Most clients typically only include one certificate per request, and there are no restrictions on servers refusing to respond to requests with multiple certificates.

X509 * certificate;
X509 * issuer;

// Passing NULL as the first parameter will use SHA-1
OCSP_CERTID * certID = OCSP_cert_to_id(NULL, certificate, issuer);
OCSP_REQUEST * request = OCSP_REQUEST_new();
OCSP_request_add0_id(request, certid);

// Hold on to request_data and len for later use.
unsigned char * request_data = NULL;
int len = i2d_OCSP_REQUEST(request, &request_data);

Making the OCSP Request

The actual request is just a simple HTTP POST to the responder URL, with the body being a ASN-encoded OCSP request.

Like with all HTTP POST requests, you'll need to provide the Content-Type and Accept headers. Most OCSP servers will refuse to respond without the correct header values, so make sure you don't forget these:

Content-Type: application/ocsp-request
Accept: application/ocsp-response

Note: This post does not cover actually making a HTTP POST request. libCURL works well for this.

An OCSP response contains an outer response object, and at least one inner certificate result. (One result per certificate requested).

Once you've gotten a response back from the OCSP responder, decode the response body as a OCSP_RESPONSE object.

const unsigned char * bytes; // Assuming this is the bytes of the HTTP response body
OCSP_RESPONSE * response = d2i_OCSP_RESPONSE(NULL, &bytes, data.length);

Then check to see if the OCSP request itself was successful. This does not indicate that the certificate is revoked or not:

int requestResponse = OCSP_response_status(ocspResponse);
if (requestResponse != OCSP_RESPONSE_STATUS_SUCCESSFUL) {
    // Uh oh!
}

Once you're sure that the OCSP request was successful, get the basic response object, which contains all of the certificate status results:

OCSP_BASICRESP * basicResp = OCSP_response_get1_basic(ocspResponse);
if (basicResp == NULL) {
    // Something bad happened!
}

Least but not last, get the result of your certificate!

int status; // If the certificate is revoked or not
int reason; // A CRL reason (if revoked)
ASN1_GENERALIZEDTIME * revocationTime; // When the certificate was revoked (if revoked)
ASN1_GENERALIZEDTIME * thisUP; // The last time this certificate was updated
ASN1_GENERALIZEDTIME * nextUP; // The time of the next update (how long you can cache until
if (!OCSP_resp_find_status(resp, certID, &status, &reason, &revocationTime, &thisUP, &nextUP)) {
    // There was a problem getting the status - probably the certificate wasnt found
}

Awesome, now we finally have the result of our certificate!

Verifying Certificate Status

Now that we have the status of our certificate, we need to see if our certificate is revoked or not.

With OCSP there are three possible status' for a certificate: GOOD, REVOKED, or UNKNOWN.

GOOD means that the certificate is not revoked according to this OCSP responder. It does not mean the certificate is valid otherwise (I.E. could still be expired).
REVOKED means that the certificate is revoked.
UNKNOWN means that the OCSP responder does not know about this certificate. You must be careful with unknown responses, as many applications consider UNKNOWN responses to be the same as GOOD.

If the certificate has a REVOKED status, then you'll want to check the reason why it's revoked. OCSP uses the reason codes defined in the certificate revocation list (CRL) specification. The reasons are:

– unspecified: can be used to revoke certificates for reasons other than the specific codes.
– keyCompromise: is used in revoking an end-entity certificate; it indicates that it is known or suspected that the subject's private key, or other aspects of the subject validated in the certificate, have been compromised.
– cACompromise: is used in revoking a CA-certificate; it indicates that it is known or suspected that the subject's private key, or other aspects of the subject validated in the certificate, have been compromised.
– affiliationChanged: indicates that the subject's name or other information in the certificate has been modified but there is no cause to suspect that the private key has been compromised.
– superseded: indicates that the certificate has been superseded but there is no cause to suspect that the private key has been compromised.
– cessationOfOperation: indicates that the certificate is no longer needed for the purpose for which it was issued but there is no cause to suspect that the private key has been compromised.
– privilegeWithdrawn: indicates that a certificate (public-key or attribute certificate) was revoked because a privilege contained within that certificate has been withdrawn.
– aACompromise: indicates that it is known or suspected that aspects of the AA validated in the attribute certificate have been compromised.

^source

All these reasons are well and good, and there's likely nothing your application has to do for any of them, but then there's two edge cases that really complicate matters:

certificateHold: indicates that a certificate authority no longer vouches for this certificate, but that may change at a later date.
removeFromCrl: indicates that a certificate was previously on hold, but is no longer on hold and considered not revoked.

So it's always important to check the reason, because even if the status is REVOKED, if the reason is removeFromCrl, then it's not actually revoked.

If you're looking for easily verify your certificates on-the-go using your iOS mobile device, check out one of my projects: TLS Inspector. The worlds first Free & Libre X509 Certificate Inspector on iOS (GitHub).

Pragmatically Generating a Self-Signed Certificate and Private Key using OpenSSL

Ian Spence — Wed, 22 Feb 2017 19:27:07 +0000

Recently I found myself needing to generate a HTTPS Server Certificate and Private Key for an iOS app using OpenSSL, what surprised me was the total lack of documentation for OpenSSL.

While there is plenty of function documentation, what OpenSSL really lacks is examples of how it all fits together. It's like having all of the pieces of a puzzle, but no picture of that the finished product will look like. Many online examples are insecure or make use of deprecated functions, a serious concern considering the consequences.

This tutorial will cover the basics for how to generate a RSA or ECDSA Private Key and a X509 Server Certificate for your application in C. For this tutorial, we will be using OpenSSL 1.1.0f.

Important note: This tutorial is written for the modern version of OpenSSL, 1.1.x, and is not backwards compatible with OpenSSL 1.0.x. If you are still on the 1.0.x train, it's highly recommended that you upgrade your application.

Generating the Private Key

A private key is required for any PKI encryption setup, and you generally have two choices for algorithms: RSA and ECDSA.

ECDSA V.S. RSA

RSA has been the defacto standard for private keys for quite a long time, and if used correctly is still secure. The security of an RSA key relies on how large the “big number is when the key is created. The recommended size of this number keeps going up and up as we're getting better and better at breaking smaller numbers.
ECDSA keys, however, are created differently than RSA keys, and are much harder to break. In fact, no tangible progress has been made on solving the problem that ECDSA keys use The Elliptic Curve Discrete Logarithm Problem (ECDLP) since 1985. Because of this, ECDSA keys provide much greater security without the need for larger numbers. For example: a 256-bit ECDSA key is equivalent to a 3,248-bit RSA key.
Not only are ECDSA keys more secure than most RSA keys, they're also much less CPU intensive. CloudFlare dissected the performance of the two in their write up on the algorithm.

                            sign/s
256 bit ecdsa (nistp256)    9516.8
rsa 2048 bits               1001.8

(openssl 1.0.2 beta on x86_64 with enable-ec_nistp_64_gcc_128)

To put it simply: ECDSA keys are 9x less CPU intensive while providing greater security than RSA keys.

Generating an RSA Private Key

#include <openssl/x509v3.h>
#include <openssl/rsa.h>

/* ... */

OPENSSL_init_ssl(0, NULL);
OPENSSL_init_crypto(0, NULL);

EVP_PKEY * pkey      = EVP_PKEY_new();
if (!pkey) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    return NULL;
}

BIGNUM   * bigNumber = BN_new();
int        exponent  = RSA_F4;
RSA      * rsa       = RSA_new();

if (BN_set_word(bigNumber, exponent) < 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    goto cleanup;
}

if (RSA_generate_key_ex(rsa,
                        2048,
                        bigNumber,
                        NULL) < 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    goto cleanup;
}

if (!EVP_PKEY_set1_RSA(pkey, rsa)) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    goto cleanup;
}

cleanup:
    RSA_free(rsa);
    BN_free(bigNumber);

    return pkey;

Generating a ECDSA Private Key

#include <openssl/x509v3.h>
#include <openssl/ecdsa.h>

/* ... */

OPENSSL_init_ssl(0, NULL);
OPENSSL_init_crypto(0, NULL);

EVP_PKEY * pkey = EVP_PKEY_new();

EC_KEY * ecc = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
if (!ecc) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    return NULL;
}

EC_KEY_set_asn1_flag(ecc, OPENSSL_EC_NAMED_CURVE);
if (EC_KEY_generate_key(ecc) < 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    return NULL;
}

if (EVP_PKEY_assign_EC_KEY(pkey, ecc) < 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    return NULL;
}

return pkey;

Generating the Server Certificate

The server certificate is the client-facing piece of information that details the connection to the server. It tells the client what type of cipher to use, and validates the identity of the server. We're generating a self-signed certificate in this case, so your computer won't trust the certificate until you install it locally.

#include <openssl/x509v3.h>

/* ... */

OPENSSL_init_ssl(0, NULL);
OPENSSL_init_crypto(0, NULL);

X509 * x509;
x509 = X509_new();
// 2 means Version 3.
X509_set_version(x509, 2L);

// Generate your private key using one of the above methods
EVP_PKEY * pkey;
X509_set_pubkey(x509, pkey);
EVP_PKEY_free(pkey);

// Generate a random serial number for this certificate.
// There are various ways to do this, depending on the platform.
// I'll leave this up to you.
unsigned long random_serial_number;

// Set Serial Number
ASN1_INTEGER_set(X509_get_serialNumber(x509), random_serial_number);

// Set Validity Date Range
// These value is appended to the systems current time stamp meaning that 0 = now.
X509_gmtime_adj((ASN1_TIME *)X509_get0_notBefore(x509), 0);
// 60 * 60 * 24 * NUMBER_OF_DAYS_TO_BE_VALID
X509_gmtime_adj((ASN1_TIME *)X509_get0_notAfter(x509), 7776000);

X509_NAME * name;
name = X509_get_subject_name(x509);

// Now to add the subject name fields to the certificate
// I use a macro here to make it cleaner.
#define addName(field, value) X509_NAME_add_entry_by_txt(name, field,  MBSTRING_ASC, (unsigned char *)value, -1, -1, 0)

// The domain name or IP address that the certificate is issued for.
addName("CN", "ecn.io");

// The organizational unit for the cert. Usually this is a department.
addName("OU", "Certificate Authority");

// The organization of the cert.
addName("O",  "ecn.io Blog");

// The city of the organization.
addName("L",  "Vancouver");

// The state/province of the organization.
addName("S",  "British Columbia");

// The country (ISO 3166) of the organization
addName("C",  "CA");

X509_set_issuer_name(x509, name);

// Modern browsers ignore the CN subject field and refer only to the Subject
// Alternative Name extension, which allows you to specify
// multiple domain names, IP addresses, and more for a single certificate.
// The SAN value is in the following format:
// <TYPE>.<INDEX>:<VALUE>
// Common types are:
// - DNS
// - IP
// - email
// - URI
// Join multiple SAN entries using a comma.
// In this example, this certificate is for both the `ecn.io` and `*.ecn.io`
// domains. Which means it'll cover all single level subdomains for ecn.io
// (E.G. blog.ecn.io but not awesome.blog.ecn.io)
const char * san_value = "DNS.1:ecn.io,DNS.2:*.ecn.io";

X509_EXTENSION * extension = X509V3_EXT_conf_nid(NULL, NULL, NID_subject_alt_name, san_value);
if (X509_add_ext(x509, extension, -1) == 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    X509_EXTENSION_free(extension);
    return;
}
X509_EXTENSION_free(extension);

// Specify the encryption algorithm of the signature.
// SHA256 should suit your needs.
if (X509_sign(x509, pkey, EVP_sha256()) < 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    return;
}

Saving your private key and certificate

OpenSSL provides you with the mechanisms to save your private key and certificate to disk, in various formats. There are many ways to encode certificate and keys, I'm going to show you how to use the most common two, PKCS12 (P12), and PEM.

The security of the private key is the most critical component of PKI, and all of your work can easily be wasted if you don't take good care to ensure your private key is safe. There are many things you can do to keep your private key safe, but at a minimum you should be changing the file permissions to not be world-readable. Jeff Atwood has a good write-up on Keeping Private Keys Private.

PKCS12 V.S. PEM

As mentioned above, theres many ways to encode keys, but the two that I'll go over are PKCS12 and PEM. PKCS12 (also known as P12) is the successor to Microsoft's PFX format, which was criticized for being overly complex and difficult to use, and while P12 is still quite complex thankfully OpenSSL does nearly all of the heavy lifting for you, leaving you to only implement a handful of commands.

The largest advantage to using P12 is that they are always encrypted using a pass phrase, and can contain multiple certificates and keys, in so called "buckets", within a single file.

The common alternative to P12 is Privacy Enhanced Mail (PEM). PEM is a very simple standard for encoding certificates and keys using base64, which can be easily moved around as ASCII text, as opposed to binary data like with DER and P12.

As PEM is strictly just an encoding, it does not require encrypting any data, and therefor is commonly used on Web Servers so no hard-coded passwords need to be added to configuration files. As well, unlike P12, PEM encoding is 1 object per file, meaning 1 certificate file and 1 key file.

Save using PKCS12

#include <openssl/x509v3.h>
#include <openssl/pkcs12.h>

/* ... */

OPENSSL_init_ssl(0, NULL);
OPENSSL_init_crypto(0, NULL);

// Prompt the user for the password to encrypt the P12 file using
// DON'T USE A HARD-CODED PASSWORD OR I WILL PERSONALLY COME OVER
// THERE AND SCREAM AT YOU
const char * export_password;

PKCS12 * p12 = PKCS12_create(export_password, NULL, pkey, x509, NULL, 0, 0, PKCS12_DEFAULT_ITER, 1, NID_key_usage);

// The full path of the P12 file that you'll create
const char * save_path = "./server.p12";

FILE * f = fopen(save_path, "wb");

if (i2d_PKCS12_fp(f, p12) != 1) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    fclose(f);
    return;
}
fclose(f);
finished(path, nil);

Save using PEM

#include <openssl/x509v3.h>
#include <openssl/pem.h>

/* ... */

// The full path of the key and crt file that you'll create
const char * key_path = "./server.key";
const char * crt_path = "./server.crt";

FILE * f = fopen(key_path, "wb");

// Prompt the user for the password to encrypt the key file using
// DON'T USE A HARD-CODED PASSWORD OR I WILL PERSONALLY COME OVER
// THERE AND SCREAM AT YOU
const char * export_password;

// Here you write the private key (pkey) to disk. OpenSSL will encrypt the
// file using the password and cipher you provide.
if (PEM_write_PrivateKey(f,
                         pkey,
                         EVP_des_ede3_cbc(),
                         (unsigned char *)export_password,
                         (int)strlen(export_password),
                         NULL,
                         NULL) < 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    fclose(f);
}
fclose(f);

f = fopen(crt_path, "wb");

// Here you write the certificate to the disk. No encryption is needed here
// since this is public facing information
if (PEM_write_X509(f, x509) < 0) {
    // OpenSSL Error. Use `ERR_peek_last_error_line` to find out more.
    fclose(f);
}
fclose(f);

Verifying our Server Certificate

OpenSSL has a nifty little function that lets you quickly print out the summary of a X509 certificate to a file (or stdout):

X509 * cert = ...
X509_print_fp(stdout, cert);

Inspecting the certificate created with a RSA private key:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1365365151 (0x5161d19f)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN=ecn.io, OU=Certificate Authority, O=ecn.io, L=Vancouver, C=CA
        Validity
            Not Before: Oct 30 20:33:01 2017 GMT
            Not After : Oct 31 02:33:00 2018 GMT
        Subject: CN=ecn.io, OU=Certificate Authority, O=ecn.io, L=Vancouver, C=CA
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    ...omitted...
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:ecn.io, DNS:*.ecn.io
    Signature Algorithm: sha256WithRSAEncryption
         ...omitted...

And with the ECDSA key:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1365365151 (0x5161d19f)
    Signature Algorithm: ecdsa-with-SHA256
        Issuer: CN=ecn.io, OU=Certificate Authority, O=ecn.io, L=Vancouver, C=CA
        Validity
            Not Before: Oct 30 20:33:01 2017 GMT
            Not After : Oct 31 02:33:00 2018 GMT
        Subject: CN=ecn.io, OU=Certificate Authority, O=ecn.io, L=Vancouver, C=CA
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub:
                    ...omitted...
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:ecn.io, DNS:*.ecn.io
    Signature Algorithm: ecdsa-with-SHA256
         ...omitted...

If you're looking for easily verify your new X509 certificate on-the-go using your iOS mobile device, check out one of my projects: TLS Inspector. The worlds first Free & Libre X509 Certificate Inspector on iOS (GitHub).

Hi, I'm Ian Spence

Ian Spence — Sat, 04 Feb 2017 18:46:26 +0000

I have been coding for 7 years.

You can find me on GitHub as ecnepsnai

I live in Vancouver, BC.

I mostly program in these languages: Objective-C, C, Golang, Javascript

I am currently learning more about TLS, OpenSSL/LibreSSL.

Nice to meet you.