inspec/docs/resources/x509_certificate.md

---
title: The x509_certificate Resource
---

# x509_certificate

Use the `x509_certificate` InSpec audit resource to test the fields and validity of an x.509 certificate.

X.509 certificates use public/private key pairs to sign and encrypt documents
or communications over a network. They may also be used for authentication.

Examples include SSL certificates, S/MIME certificates and VPN authentication
certificates.

## Syntax

An `x509_certificate` resource block declares a certificate `key file` to be tested.

    describe x509_certificate('mycertificate.pem') do
      its('days_remaining') { should be > 30 }
    end

It can optionally specify a private key file and a ca public key file for key verification

    describe x509_certificate('mycertificate.cert','mycertificate.key','ca_key.pub') do
      its('private_key_matches?') { should be true }
      its('ca_key_matches?') { should be true }
    end

## Supported Properties

### subject (String)

The `subject` string contains several fields seperated by forward slashes. The
field identifiers are the same ones used by OpenSSL to generate CSR's and certs.

e.g. `/C=US/L=Seattle/O=Chef Software Inc/OU=Chefs/CN=Richard Nixon`

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('subject') { should match "CN=www.mywebsite.com" }
    end

### parsed_subject.XX

`parsed_subject` property makes it easier to access individual subject elements.

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('parsed_subject.CN') { should eq "www.mywebsite.com" }
    end

### issuer (String)

The `issuer` string is copied from a CA (certificate authority) during the
certificate signing process. It describes which authority is guaranteeing the
identity of our certificate.

e.g. `/C=US/L=Seattle/CN=Acme Trust CA/emailAddress=support@acmetrust.org`

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('issuer') { should match "CN=Acme Trust CA" }
    end

### parsed_issuer.XX

`parsed_issuer` makes it easier to access individual issuer elements.

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('parsed_issuer.CN') { should eq "Acme Trust CA" }
    end

### public_key (String)

The `public_key` property returns a base64 encoded public key in PEM format.

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('public_key') { should match "-----BEGIN PUBLIC KEY-----\nblah blah blah..." }
    end

### key_length (Integer)

The `key_length` property calculates the number of bits in the public key.
More bits increase security, but at the cost of speed and in extreme cases, compatibility.

    describe x509_certificate('mycert.pem') do
      its('key_length') { should be 2048 }
    end

### signature_algorithm (String)

The `signature_algorithm` property describes which hash function was used by the CA to
sign the certificate.

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('signature_algorithm') { should be 'sha256WithRSAEncryption' }
    end

### private_key_matches?  (Boolean)   ca_key_matches?  (Boolean)

The `private_key_matches?` and `ca_key_matches?` methods check

* If the supplied private key matches the certificate
* If the CA public key belongs to the CA that signed the certificate


    describe x509_certificate('mycertificate.cert','mycertificate.key','ca_key.pub') do
      its('private_key_matches?') { should be true }
      its('ca_key_matches?') { should be true }
    end


### days_remaining (Float)

The `days_remaining` property can be used to check that certificates are not in
danger of expiring soon.

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('days_remaining') { should be > 30 }
    end

### not_before and not_after (Time)

The `not_before` and `not_after` properties expose the start and end dates of certificate
validity. They are exposed as ruby Time class so that date arithmetic can be easily performed.

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('not_before') { should be <= Time.utc.now }
      its('not_after')  { should be >= Time.utc.now }
    end

### serial (Integer)

The `serial` property exposes the serial number of the certificate. The serial number is set by the CA during the signing process and should be unique within that CA.

### version (Integer)

The `version` property exposes the certificate version.

### extensions (Hash)

The `extensions` hash property is mainly used to determine what the certificate can be used for.

    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
      its('extensions').length) {should eq 3 }

      # Check what extension categories we have
      its('extensions')) { should include 'keyUsage' }
      its('extensions')) { should include 'extendedKeyUsage' }
      its('extensions')) { should include 'subjectAltName' }

      # Check examples of basic 'keyUsage'
      its('extensions')['keyUsage']) { should include "Digital Signature" }
      its('extensions')['keyUsage']).must_include "Non Repudiation"
      its('extensions')['keyUsage']).must_include "Data Encipherment"

      # Check examples of newer 'extendedKeyUsage'
      its('extensions')['extendedKeyUsage']) { should include "TLS Web Server Authentication" }
      its('extensions')['extendedKeyUsage']) { should include "Code Signing" }

      # Check examples of 'subjectAltName'
      its('extensions')['subjectAltName']) { should include "email:support@chef.io" }
    end