X.509 Certificate Builder

A certificate looks like a credential, and people treat it like one. It is something plainer: a signed statement that a public key belongs to a name, between two moments. The rest comes from somewhere else.

The Internet profile for certificates describes the outer shape in one line. A certificate is a sequence of three things: the data to be signed, the name of the signature algorithm, and the signature. By making that signature, the profile says, the issuer certifies the binding between the public key and the subject. That sentence is the whole claim. It does not say the subject is honest or competent, that the server behind the name is safe, or that the private key is still secret today.

What the signed part holds

The signed part is a short list: a version, a serial number, the signature algorithm again, the issuer, a validity period, the subject, the subject’s public key and, in version 3, extensions. The serial number must be a positive integer, unique for each certificate an issuer signs, and no longer than 20 octets. Public certificate authorities are further required to fill it with at least 64 bits from a secure random source.

Issuer and subject are distinguished names, an older directory idea: a sequence of attributes such as country, organization and common name. Their limits are modest. A country is two letters, and a common name has an upper bound of 64 characters. Each value travels either as PrintableString, a small set of letters, digits and a few punctuation marks, or as UTF8String for everything else.

The validity period is two times, both included. It hides a small trap for parsers. Dates through 2049 must be written in a form with a two-digit year, where 50 and above mean the 1900s. Dates in 2050 or later must use a second form with four digits. A certificate that expires on the first day of 2050 therefore carries two different time types side by side.

What the period means is narrower than it sounds. The profile defines it as the interval during which the issuer warrants that it will keep information about the status of the certificate. Status is the important word. A key can be stolen long before its certificate expires, which is why issuers also publish signed revocation lists that name withdrawn certificates by serial number.

Then comes the key itself, wrapped with an identifier that says what kind it is. An elliptic curve key names its curve and gives the point as one marker byte followed by two coordinates, 65 octets on the 256-bit curve. An RSA key is a modulus and an exponent. An Ed25519 key is just 32 octets with no parameters at all. NIST rates a 2048-bit RSA key at 112 bits of security strength, and a 3072-bit RSA key level with a 256-bit curve at 128.

The signature covers the exact encoded bytes of the signed part, not some abstract reading of them. For RSA it is as long as the modulus. For ECDSA it is two integers inside a small sequence, which is not how a browser hands them over: the web cryptography interface returns the pair as two fixed-width numbers, and they must be rewritten before they fit in a certificate.

Why the host name moved out of the common name

For years a web server’s name lived in the common name. It worked, and it was a mistake. A common name is free text. It can hold a person, a company, a department or a host, and nothing in the field says which.

The specification of HTTP over TLS said so in May 2000. If a certificate carries a subject alternative name of the DNS type, that name must be used as the identity. The common name was to be used only otherwise, and the document called the practice deprecated while encouraging issuers to use the DNS name instead.

It took two more rounds to finish the job. A 2011 specification let a client look at the common name only as a last resort, when the certificate offered none of the typed names the client understood. Its 2023 successor closes the door: the common name must not be used to identify a service, because it is not strongly typed and so suffers from ambiguities in interpretation.

Alternative names are typed, and that is their whole advantage. Each entry is tagged as a DNS name, an IP address, an email address or a URI. An IPv4 address is exactly four octets and an IPv6 address exactly 16 octets, never text. A wildcard is allowed only once and only as the complete left-most label. For a development machine this means a certificate should list localhost, 127.0.0.1 and ::1, since the name localhost is reserved to resolve to the loopback addresses.

The other extensions answer narrower questions. Basic constraints says whether the key may sign other certificates. Key usage is a row of nine bits such as digital signature and certificate signing, and a key may sign certificates only if the certificate also says it is an authority. Extended key usage names purposes like server or client authentication. Each extension carries a critical flag: a reader that meets a critical extension it does not understand must reject the certificate.

Self-signed, and what a signature cannot supply

A self-signed certificate is one whose signature verifies with the key inside it. The profile notes dryly what this proves: that the issuer possesses both the public and the private key. Nothing more. Anyone can make one, for any name, in a fraction of a second.

Trust enters from outside. A verifier starts from a trust anchor it already holds and follows signatures from there to the certificate in front of it. The choice of anchor, the profile says, is a matter of policy. A certificate from a public authority chains to an anchor that ships in browsers and operating systems. One you made yourself chains to nothing on anybody else’s machine, and no amount of careful encoding changes that.

So a self-signed certificate is honest work in exactly the places where you control both ends: a local server, a test rig, a lesson. Public authorities live under rules that such certificates do not. Their TLS certificates could run 398 days until March 2026, may run 200 days now, and are due to drop to 100 days in 2027 and 47 in 2029. None of that binds a private test certificate.

There are things no builder can do, however correct its output. It cannot check that you control the names you type. It cannot revoke anything. It cannot guard a private key the way dedicated hardware does: a key made in a web page is an object in that page’s memory, marked extractable or not, and it is gone when the page closes. Saved to disk, it is only as safe as the file, which is why private key files can be encrypted under a passphrase.

A closer rehearsal of the real thing is a small authority of your own. Make a root certificate that is marked as an authority and allowed to sign certificates, then a second certificate signed by the root’s key. The leaf names the root as its issuer and carries the root’s key identifier. Only the root then needs to be trusted on the test machines.

Reading the bytes

Certificates are written in DER, a strict encoding in which every element is a tag, a length and a value. A length under 128 takes one octet. A longer one starts with an octet that says how many length octets follow. Elements nest, so a certificate is a tree, and its outermost element usually begins 30 82: a sequence whose length needs two more octets.

Build the localhost example in the tool above and look at offset 8. The five octets there are a0 03 02 01 02. The tag a0 is a wrapper numbered zero, and its length is 3. Inside sits 02 01 02, an integer of one octet with the value 2, which means version 3 because counting starts at zero. Further on, the common name is announced by 06 03 55 04 03, the identifier 2.5.4.3, whose first two numbers are packed as 40 times 2 plus 5: 85, or 55 in hexadecimal. The tree lists every element with its offset, so each of these claims can be checked against the bytes.

The alternative names show the typing at work. The DNS name is 82 09 followed by the nine letters of localhost. The address 127.0.0.1 is 87 04 7f 00 00 01. The IPv6 loopback is 87 10, then fifteen zero octets and a final 01. With a 256-bit curve key the whole certificate comes to about 450 octets.

Integers hold one more surprise. They are signed, so a positive number whose first bit is set gets a zero octet in front. A random serial of sixteen octets is therefore written as seventeen about half the time, and the two numbers of an ECDSA signature change length from one signature to the next.

DER permits exactly one encoding of any value: lengths are minimal, defaults are left out, and the members of a set are sorted. That is what lets a signature be checked at all, since two parties must arrive at the same bytes. For transport the bytes are usually wrapped as text, Base64 in lines of 64 characters between a begin line and an end line that carry a label.

Read this way, a certificate stops being mysterious. A name, a key, two dates, a few typed promises about use, and a signature over all of it. Whether to believe it was always decided somewhere else.