x509sak
X.509 Swiss Army Knife (x509sak) is a toolkit written in Python that acts as a boilerplate on top of OpenSSL to ease creation of X.509 certificates, certificate signing requests and CAs. It can automatically find CA chains and output them in a specifically desired format, graph CA hierarchies and more.
The tool is used similarly to OpenSSL in its syntax. The help page is meant to be comprehensive and self-explanatory. These are the currently available commands:
$ ./x509sak.py
Error: No command supplied.
Syntax: ./x509sak.py [command] [options]
Available commands:
version: x509sak v0.0.2
Options vary from command to command. To receive further info, type
./x509sak.py [command] --help
buildchain Build a certificate chain
graph Graph a certificate pool
findcrt Find a specific certificate
createca Create a new certificate authority (CA)
createcsr Create a new certificate signing request (CSR) or
certificate
signcsr Make a certificate authority (CA) sign a certificate
signing request (CSR) and output the certificate
revokecrt Revoke a specific certificate
createcrl Generate a certificate revocation list (CRL)
genbrokenrsa Generate broken RSA keys for use in penetration testing
genbrokendsa Generate broken DSA parameters for use in penetration
testing
dumpkey Dump a key in text form
examinecert Examine an X.509 certificate
forgecert Forge an X.509 certificate
scrape Scrape input file for certificates, keys or signatures
hashpart Hash all substrings of a file and search for a
particular hash value
Dependencies
x509sak requires Python3, pyasn1 and pyasn1_modules support. It also relies on OpenSSL. If you want graph support, then you also need to install the Graphviz package as well. Note that pyasn1_modules inside the Ubuntu tree (up until 3'2018, Ubuntu Artful MATE, v0.0.7-0.1) is broken and you'll need to use a newer version (0.2.1 works). In later Ubuntu versions (Bionic) this is already included by default:
# apt-get install openssl python3-pyasn1 python3-pyasn1-modules graphviz
If you want to run all the tests, you should also have SoftHSM2, OpenSC and the PKCS#11 OpenSSL engine driver installed to be able to do PKCS#11 testing:
# apt-get install opensc softhsm2 libengine-pkcs11-openssl
Using x509sak with hardware tokens
x509sak works nicely with hardware tokens such as the NitroKey HSM. It does not allow key generation for these devices, but can use the pre-generated keys for CA management. For example, let's say you used a tool like nitrotool to generate an ECC keypair that is called "my_secure_key". You now want a CA that's based off that key. Quite an easy task:
$ ./x509sak.py createca -w "pkcs11:object=my_secure_key;type=private" -s "/CN=My Secure CA" my_secure_ca
Enter PKCS#11 token PIN for UserPIN (SmartCard-HSM): 123456
You enter your Pin, hit return and it's done! The CA has been created:
$ openssl x509 -in my_secure_ca/CA.crt -text -noout
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
c3:86:c2:43:4b:2d:62:12
Signature Algorithm: ecdsa-with-SHA256
Issuer: CN = My Secure CA
Validity
Not Before: Jul 14 10:47:49 2018 GMT
Not After : Jul 14 10:47:49 2019 GMT
Subject: CN = My Secure CA
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey
Public-Key: (256 bit)
pub:
04:8a:8f:c7:99:3b:b1:cf:63:5f:c7:c8:87:50:80:
26:4d:22:96:9f:2f:67:f8:ea:f6:f2:1b:96:e4:e2:
4b:af:15:fe:79:77:52:50:d1:f6:a3:20:7b:ca:ce:
5e:bc:25:5e:30:2d:1a:71:cb:8f:ff:79:46:4f:ec:
58:04:e1:f7:f0
ASN1 OID: prime256v1
NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints: critical
CA:TRUE
X509v3 Key Usage: critical
Digital Signature, Certificate Sign, CRL Sign
X509v3 Subject Key Identifier:
9B:4E:14:4E:0D:C5:23:D9:06:06:06:7D:39:8F:3C:88:1D:66:35:55
Signature Algorithm: ecdsa-with-SHA256
30:45:02:20:79:a2:91:1e:ca:2d:18:5b:26:59:14:b1:f1:0c:
2f:0f:41:d8:ab:bc:02:2f:e9:c2:dc:97:c1:19:67:9e:c7:8d:
02:21:00:ef:73:02:6a:a4:ad:e8:f0:ef:49:02:cf:34:08:b7:
2e:fa:82:16:47:8c:44:7f:bb:ad:f0:c0:be:7a:e6:e1:81
It's similarly easy to create certificates off this hardware-backed CA:
$ ./x509sak.py createcsr -s "/CN=Software Key Client" -t tls-client -c my_secure_ca client.key client.crt
Enter PKCS#11 token PIN for UserPIN (SmartCard-HSM):
Again, with one command you've created the client certificate:
$ openssl x509 -in client.crt -text -noout
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: ecdsa-with-SHA256
Issuer: CN = My Secure CA
Validity
Not Before: Jul 14 10:50:19 2018 GMT
Not After : Jul 14 10:50:19 2019 GMT
Subject: CN = Software Key Client
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey
Public-Key: (384 bit)
pub:
04:5a:68:1b:f2:ea:29:71:23:39:66:bd:b7:6a:9c:
0c:69:8d:a9:e8:7f:93:a8:32:21:d7:f2:93:e8:52:
c5:83:65:7b:13:62:04:9f:64:c6:54:fd:24:8a:64:
d2:49:cd:8d:27:61:b3:41:44:d3:89:51:39:78:29:
b2:ff:1a:3a:b6:e0:74:c6:15:92:26:f9:42:2b:0d:
04:74:1b:3d:13:f8:78:53:a5:be:6f:13:04:01:05:
f7:40:4b:6a:89:4c:54
ASN1 OID: secp384r1
NIST CURVE: P-384
X509v3 extensions:
X509v3 Authority Key Identifier:
keyid:9B:4E:14:4E:0D:C5:23:D9:06:06:06:7D:39:8F:3C:88:1D:66:35:55
X509v3 Basic Constraints: critical
CA:FALSE
X509v3 Extended Key Usage:
TLS Web Client Authentication
X509v3 Key Usage: critical
Digital Signature, Key Encipherment, Key Agreement
Netscape Cert Type:
SSL Client
X509v3 Subject Key Identifier:
0C:1F:31:4C:BA:E2:C6:33:65:9D:ED:DA:FC:16:29:27:E0:95:AF:E2
Signature Algorithm: ecdsa-with-SHA256
30:44:02:20:3f:84:40:bb:50:2e:7c:8c:3b:2f:51:80:f9:20:
a7:bb:7d:17:58:c6:44:70:20:eb:74:46:5a:ae:95:4e:9e:81:
02:20:0c:98:35:63:8d:2f:1b:ad:32:d4:06:2f:c8:e7:2c:8a:
79:b7:5a:e0:21:51:63:0b:39:82:9f:ff:8d:ee:c3:e2
For simplicity, you can specify either a full pkcs11-URI according to RFC7512 or you can use certain abbreviations that make it easier. All of the following work for a key that's named 'my key' and that has ID 0xabcd:
pkcs11:object=my%20key;type=private
pkcs11:id=%ab%cd;type=private
label=my key
id=0xabcd
id=43981
The latter variants (label=..., id=...) will automatically be converted to pkcs11 URIs internally.
buildchain
The "buildchain" command is useful if you want to have a complete (or partial) certificate chain from a given leaf certificate and a bundle of CAs. x509sak will figure out which of the CAs are appropriate (if any) and generate a chain in the order you want (root to leaf or leaf to root) including the certs you want (e.g., all certificates, all except root cert, etc.). This is useful if you have, for example, a webserver certificate and want to automatically find the chain of trust that you can use to deploy on your webserver.
usage: ./x509sak.py buildchain [-s path] [--inform {pem,der}]
[--order-leaf-to-root] [--allow-partial-chain]
[--dont-trust-crtfile]
[--outform {rootonly,intermediates,fullchain,all-except-root,multifile,pkcs12}]
[--private-key filename]
[--pkcs12-legacy-crypto]
[--pkcs12-no-passphrase | --pkcs12-passphrase-file filename]
[-o file] [-v] [--help]
crtfile
Build a certificate chain
positional arguments:
crtfile Certificate that a chain shall be build for, in PEM
format.
optional arguments:
-s path, --ca-source path
CA file (PEM format) or directory (containing
.pem/.crt files) to include when building the chain.
Can be specified multiple times to include multiple
locations.
--inform {pem,der} Specifies input file format for certificate. Possible
options are pem, der. Default is pem.
--order-leaf-to-root By default, certificates are ordered with the root CA
first and intermediate certificates following up to
the leaf. When this option is specified, the order is
inverted and go from leaf certificate to root.
--allow-partial-chain
When building the certificate chain, a full chain must
be found or the chain building fails. When this option
is specified, also partial chain matches are
permitted, i.e., not going up to a root CA. Note that
this can have undesired side effects when no root
certificates are found at all (the partial chain will
then consist of only the leaf certificate itself).
--dont-trust-crtfile When there's multiple certificates in the given
crtfile in PEM format, they're by default all added to
the truststore. With this option, only the leaf cert
is taken from the crtfile and they're not added to the
trusted pool.
--outform {rootonly,intermediates,fullchain,all-except-root,multifile,pkcs12}
Specifies what to write into the output file. Possible
options are rootonly, intermediates, fullchain, all-
except-root, multifile, pkcs12. Default is fullchain.
When specifying multifile, a %d format must be
included in the filename to serve as a template;
typical printf-style formatting can be used of course
(e.g., %02d).
--private-key filename
When creating a PKCS#12 output file, this private key
can also be included. By default, only the
certificates are exported.
--pkcs12-legacy-crypto
Use crappy crypto to encrypt a PKCS#12 exported
private key.
--pkcs12-no-passphrase
Do not use any passphrase to protect the PKCS#12
private key.
--pkcs12-passphrase-file filename
Read the PKCS#12 passphrase from the first line of the
given file. If omitted, by default a random passphrase
will be generated and printed on stderr.
-o file, --outfile file
Specifies the output filename. Defaults to stdout.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
graph
The graph utility can be used to plot multiple certificates and their certificate hierarchy. Some metadata is displayed within the graph as well. Here's an example of some certificates that I've plotted:
usage: ./x509sak.py graph [-c {certtype,expiration,keytype,sigtype}]
[--abbreviate-to charcnt] [-l text]
[-f {dot,png,ps,pdf}] -o file [-v] [--help]
crtsource [crtsource ...]
Graph a certificate pool
positional arguments:
crtsource Certificate file (in PEM format) or directory
(containting PEM-formatted .pem or .crt files) which
should be included in the graph.
optional arguments:
-c {certtype,expiration,keytype,sigtype}, --color-scheme {certtype,expiration,keytype,sigtype}
Color scheme to use when coloring the certificates.
Can either color by expiration date, by certificate
type (client/server/CA/...), key type (RSA/ECC/etc),
signature type (used hash function) or overall
security level. Defaults to expiration.
--abbreviate-to charcnt
Abbreviate each line to this amount of characters.
Defaults to 30 characters.
-l text, --label text
Label that is printed in the certificate nodes. Can be
given multiple times to specify multiple lines.
Substitutions that are supported are derhash,
filebasename, filename, subject, subject_rfc2253,
valid_not_after. Defaults to ['%(filebasename)s
(%(derhash)s)', '%(subject)s', '%(valid_not_after)s'].
-f {dot,png,ps,pdf}, --format {dot,png,ps,pdf}
Specifies the output file format. Can be one of dot,
png, ps, pdf. When unspecified, the file extension out
the output file is used to determine the file type.
-o file, --outfile file
Specifies the output filename. Mandatory argument.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
findcrt
When looking for a bunch of certificates (some of which might be in PEM format) by their authoritative hash (i.e., the SHA256 hash over their DER-representation), findcrt can help you out. You specify a bunch of certificates and the hash prefix you're looking for and x509sak will show it to you.
usage: ./x509sak.py findcrt [-h hash] [-v] [--help] crtsource [crtsource ...]
Find a specific certificate
positional arguments:
crtsource Certificate file (in PEM format) or directory
(containting PEM-formatted .pem or .crt files) which
should be included in the search.
optional arguments:
-h hash, --hashval hash
Find only certificates with a particular hash prefix.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
createca
Creating a CA structure that can be used with "openssl ca" is tedious. The "createca" command does exactly this for you in one simple command. The created OpenSSL config file directly works with "openssl ca" for manual operation but can also be used with other x509sak commands (e.g., creating or revoking certificates). x509sak takes care that you have all the necessary setup files in place (index, serial, etc.) and can just as easily create intermediate CAs as it can create root CAs.
usage: ./x509sak.py createca [-g keyspec | -w pkcs11uri]
[--pkcs11-so-search path]
[--pkcs11-module sofile] [-p capath] [-s subject]
[-d days] [-h alg] [--serial serial]
[--allow-duplicate-subjects]
[--extension key=value] [-f] [-v] [--help]
capath
Create a new certificate authority (CA)
positional arguments:
capath Directory to create the new CA in.
optional arguments:
-g keyspec, --gen-keyspec keyspec
Private key specification to generate. Examples are
rsa:1024 or ecc:secp256r1. Defaults to ecc:secp384r1.
-w pkcs11uri, --hardware-key pkcs11uri
Use a hardware token which stores the private key. The
parameter gives the pkcs11 URI, e.g.,
'pkcs11:object=mykey;type=private'
--pkcs11-so-search path
Gives the path that will be searched for the "dynamic"
and "module" shared objects. The "dynamic" shared
object is libpkcs11.so, the "module" shared object can
be changed by the --pkcs11-module option. The search
path defaults to
/usr/local/lib:/usr/lib:/usr/lib/x86_64-linux-
gnu:/usr/lib/x86_64-linux-
gnu/openssl-1.0.2/engines:/usr/lib/x86_64-linux-
gnu/engines-1.1.
--pkcs11-module sofile
Name of the "module" shared object when using PKCS#11
keys. Defaults to opensc-pkcs11.so.
-p capath, --parent-ca capath
Parent CA directory. If omitted, CA certificate will
be self-signed.
-s subject, --subject-dn subject
CA subject distinguished name. Defaults to /CN=Root
CA.
-d days, --validity-days days
Number of days that the newly created CA will be valid
for. Defaults to 365 days.
-h alg, --hashfnc alg
Hash function to use for signing the CA certificate.
Defaults to sha384.
--serial serial Serial number to use for root CA certificate.
Randomized by default.
--allow-duplicate-subjects
By default, subject distinguished names of all valid
certificates below one CA must be unique. This option
allows the CA to have duplicate distinguished names
for certificate subjects.
--extension key=value
Additional certificate X.509 extension to include on
top of the default CA extensions. Can be specified
multiple times.
-f, --force By default, the capath will not be overwritten if it
already exists. When this option is specified the
complete directory will be erased before creating the
new CA.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
createcsr
The "createcsr" command can (as the name suggests) create CSRs, but also can directly generate CRTs that are signed by a previously created CA. The advantage over using OpenSSL manually is that the API is quite simple to configure the certificate manually for most cases (e.g., webserver certificates with X.509 Subject Alternative Name set), but also is flexible enough for custom stuff by including your custom extensions directly into the extension file configuration used by OpenSSL.
usage: ./x509sak.py createcsr [-g keyspec] [-k {pem,der,hw}] [-s subject]
[-d days] [-h alg]
[-t {rootca,ca,tls-server,tls-client}]
[--san-dns FQDN] [--san-ip IP]
[--extension key=value] [-f] [-c capath] [-v]
[--help]
in_key_filename out_filename
Create a new certificate signing request (CSR) or certificate
positional arguments:
in_key_filename Filename of the input private key or PKCS#11 URI (as
specified in RFC7512 in case of a hardware key type.
out_filename Filename of the output certificate signing request or
certificate.
optional arguments:
-g keyspec, --gen-keyspec keyspec
Private key specification to generate for the
certificate or CSR when it doesn't exist. Examples are
rsa:1024 or ecc:secp256r1.
-k {pem,der,hw}, --keytype {pem,der,hw}
Private key type. Can be any of pem, der, hw. Defaults
to pem.
-s subject, --subject-dn subject
Certificate/CSR subject distinguished name. Defaults
to /CN=New Cert.
-d days, --validity-days days
When creating a certificate, number of days that the
certificate will be valid for. Defaults to 365 days.
-h alg, --hashfnc alg
Hash function to use for signing when creating a
certificate. Defaults to the default hash function
specified in the CA config.
-t {rootca,ca,tls-server,tls-client}, --template {rootca,ca,tls-server,tls-client}
Template to use for determining X.509 certificate
extensions. Can be one of rootca, ca, tls-server, tls-
client. By default, no extensions are included except
for SAN.
--san-dns FQDN Subject Alternative DNS name to include in the
certificate or CSR. Can be specified multiple times.
--san-ip IP Subject Alternative IP address to include in the
certificate or CSR. Can be specified multiple times.
--extension key=value
Additional certificate X.509 extension to include on
top of the extensions in the template and by the SAN
parameters. Can be specified multiple times.
-f, --force Overwrite the output file if it already exists.
-c capath, --create-crt capath
Instead of creating a certificate signing request,
directly create a certificate instead. Needs to supply
the CA path that should issue the certificate.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
signcsr
The signcsr command allows you to turn a CSR into a certificate by signing it by a CA private key.
usage: ./x509sak.py signcsr [-s subject] [-d days] [-h alg]
[-t {rootca,ca,tls-server,tls-client}]
[--san-dns FQDN] [--san-ip IP]
[--extension key=value] [-f] [-v] [--help]
capath in_csr_filename out_crt_filename
Make a certificate authority (CA) sign a certificate signing request (CSR) and
output the certificate
positional arguments:
capath Directory of the signing CA.
in_csr_filename Filename of the input certificate signing request.
out_crt_filename Filename of the output certificate.
optional arguments:
-s subject, --subject-dn subject
Certificate's subject distinguished name. Defaults to
the subject given in the CSR.
-d days, --validity-days days
Number of days that the newly created certificate will
be valid for. Defaults to 365 days.
-h alg, --hashfnc alg
Hash function to use for signing. Defaults to the
default hash function specified in the CA config.
-t {rootca,ca,tls-server,tls-client}, --template {rootca,ca,tls-server,tls-client}
Template to use for determining X.509 certificate
extensions. Can be one of rootca, ca, tls-server, tls-
client. By default, no extensions are included except
for SAN.
--san-dns FQDN Subject Alternative DNS name to include in the
certificate. Can be specified multiple times.
--san-ip IP Subject Alternative IP address to include in the CRT.
Can be specified multiple times.
--extension key=value
Additional certificate X.509 extension to include on
top of the extensions in the template and by the SAN
parameters. Can be specified multiple times.
-f, --force Overwrite the output certificate file if it already
exists.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
revokecrt
With revokecrt it's possible to easily revoke a certificate that you've previous generated. Simply specify the CA and the certificate that you want to revoke and you're set.
usage: ./x509sak.py revokecrt [-v] [--help] capath crt_filename
Revoke a specific certificate
positional arguments:
capath CA which created the certificate.
crt_filename Filename of the output certificate.
optional arguments:
-v, --verbose Increase verbosity level. Can be specified multiple times.
--help Show this help page.
createcrl
The createcrl command does what it suggests: It creates a CRL for a given CA that is valid for a specified duration and that's signed with a given hash function.
usage: ./x509sak.py createcrl [-d days] [-h alg] [-v] [--help]
capath crl_filename
Generate a certificate revocation list (CRL)
positional arguments:
capath CA which should generate the CRL.
crl_filename Filename of the output CRL.
optional arguments:
-d days, --validity-days days
Number of days until the CRLs 'nextUpdate' field will
expire. Defaults to 30 days.
-h alg, --hashfnc alg
Hash function to use for signing the CRL. Defaults to
sha256.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
genbrokenrsa
With genbrokenrsa it is possible to generate deliberately malformed or odd RSA keys. For example, RSA keys with a custom value for the public exponent e, or RSA keys which have a very small exponent d (e.g, 3) and a correspondingly large exponent e. Note that keys generated by this tool are exclusively for testing purposes and may not, under any circumstances, be used for actual cryptographic applications. They are not secure.
usage: ./x509sak.py genbrokenrsa [-d path] [-b bits] [-e exp] [--switch-e-d]
[--accept-unusable-key]
[--carmichael-totient] [--generator file]
[--gcd-n-phi-n | --close-q]
[--q-stepping int] [-o file] [-f] [-v]
[--help]
Generate broken RSA keys for use in penetration testing
optional arguments:
-d path, --prime-db path
Prime database directory. Defaults to . and searches
for files called primes_{bitlen}.txt in this
directory.
-b bits, --bitlen bits
Bitlength of modulus. Defaults to 2048 bits.
-e exp, --public-exponent exp
Public exponent e (or d in case --switch-e-d is
specified) to use. Defaults to 0x10001. Will be
randomly chosen from 2..n-1 if set to -1.
--switch-e-d Switch e with d when generating keypair.
--accept-unusable-key
Disregard integral checks, such as if gcd(e, phi(n))
== 1 before inverting e. Might lead to an unusable key
or might fail altogether.
--carmichael-totient By default, d is computed as the modular inverse of e
to phi(n), the Euler Totient function. This computes d
as the modular inverse of e to lambda(n), the
Carmichael Totient function, instead.
--generator file When prime database is exhausted, will call the prime
generator program as a subprocess to generate new
primes. Otherwise, and the default behavior, is to
fail.
--gcd-n-phi-n Generate a keypair in which gcd(n, phi(n)) != 1 by
specially constructing the prime q. This will lead to
a size disparity of p and q and requires 3-msb primes
as input.
--close-q Use a value for q that is very close to the value of p
so that search starting from sqrt(n) is
computationally feasible to factor the modulus. Note
that for this, the bitlength of the modulus must be
evenly divisible by two.
--q-stepping int When creating a close-q RSA keypair, q is chosen by
taking p and incrementing it repeatedly by a random
int from 2 to (2 * q-stepping). The larger q-stepping
is therefore chosen, the further apart p and q will
be. By default, q-stepping is the minimum value of 1.
-o file, --outfile file
Output filename. Defaults to broken_rsa.key.
-f, --force Overwrite output file if it already exists instead of
bailing out.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
genbrokendsa
Similar to the previous command, this can be used to create DSA domain parameters that are insecure and/or undesirable (e.g., because the generator is not verifiable).
usage: ./x509sak.py genbrokendsa [-d path] [--generator file] [-o file] [-f]
[-v] [--help]
L_bits N_bits
Generate broken DSA parameters for use in penetration testing
positional arguments:
L_bits Bitlength of the modulus p, also known as L.
N_bits Bitlength of q, also known as N.
optional arguments:
-d path, --prime-db path
Prime database directory. Defaults to . and searches
for files called primes_{bitlen}.txt in this
directory.
--generator file When prime database is exhausted, will call the prime
generator program as a subprocess to generate new
primes. Otherwise, and the default behavior, is to
fail.
-o file, --outfile file
Output filename. Defaults to broken_dsa.key.
-f, --force Overwrite output file if it already exists instead of
bailing out.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
dumpkey
The dumpkey facility can be used to dump the public/private key parameters of a given PEM keyfile into Python-code for further processing.
usage: ./x509sak.py dumpkey [-t {rsa,ecc,eddsa}] [-p] [-v] [--help]
key_filename
Dump a key in text form
positional arguments:
key_filename Filename of the input key file in PEM format.
optional arguments:
-t {rsa,ecc,eddsa}, --key-type {rsa,ecc,eddsa}
Type of private key to import. Can be one of rsa, ecc,
eddsa, defaults to rsa. Disregarded for public keys
and determined automatically.
-p, --public-key Input is a public key, not a private key.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
examinecert
Using the examinecert facility you can plausibilize certificates and check them for all kinds of errors that can happen. It also gives a security estimate of the used algorithms and highlights things that are unusual. For example, RSA with large exponents is something that is entirely safe, but definitely unusual. Missing key usage flags or important extensions will also be reported along with standards violations (mainly RFC5280) -- it also gives you the exact location of the RFC (including section) that has been violated.
usage: ./x509sak.py examinecert [-p {ca,tls-server,tls-client}] [-n fqdn]
[-f {ansitext,text,json}]
[-i {pemcrt,dercrt,json,host}] [-r pemfile]
[--no-automatic-host-check] [--fast-rsa]
[--include-raw-data] [--pretty-json]
[-o filename] [-v] [--help]
filename/uri [filename/uri ...]
Examine an X.509 certificate
positional arguments:
filename/uri Filename of the input certificate or certificates in
PEM format.
optional arguments:
-p {ca,tls-server,tls-client}, --purpose {ca,tls-server,tls-client}
Check if the certificate is fit for the given purpose.
Can be any of ca, tls-server, tls-client, can be
specified multiple times.
-n fqdn, --server-name fqdn
Check if the certificate is valid for the given
hostname.
-f {ansitext,text,json}, --out-format {ansitext,text,json}
Determine the output format. Can be one of ansitext,
text, json, defaults to ansitext.
-i {pemcrt,dercrt,json,host}, --in-format {pemcrt,dercrt,json,host}
Specifies the type of file that is read in. Can be
either certificate files in PEM or DER format, a pre-
processed JSON output from a previous run or a
hostname[:port] combination to query a TLS server
directly (port defaults to 443 if omitted). Valid
choices are pemcrt, dercrt, json, host, defaults to
pemcrt.
-r pemfile, --parent-certificate pemfile
Specifies a parent CA certificate that is used to run
additional checks against the certificate.
--no-automatic-host-check
By default, when the input format is a given hostname,
the server name is assumed as well and the purpose is
assumed to be a TLS server. When this option is
specified, these automatic checks are omitted.
--fast-rsa Skip some time-intensive number theoretical tests for
RSA moduli in order to speed up checking. Less
thorough, but much faster.
--include-raw-data Add the raw data such as base64-encoded certificate
and signatures into the result as well.
--pretty-json Prettyfy any generated JSON output.
-o filename, --output filename
Specify the output file. Defaults to stdout.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
forgecert
With the forgecert tool you can forge a certificate chain. The input PEM file must begin with a self-signed root certificate and each following certificate must descend from its predecessor. The functionality is rather simplistic currently. The purpose is to create certificates which look and feel like their "original" counterparts, but are obviously fakes. This is for white hat testing of implementations.
usage: ./x509sak.py forgecert [--key_template path] [--cert_template path]
[-r] [-f] [-v] [--help]
crt_filename
Forge an X.509 certificate
positional arguments:
crt_filename Filename of the input certificate or certificates PEM
format.
optional arguments:
--key_template path Output template for key files. Should contain '%d' to
indicate element in chain. Defaults to
'forged_%02d.key'.
--cert_template path Output template for certificate files. Should contain
'%d' to indicate element in chain. Defaults to
'forged_%02d.crt'.
-r, --recalculate-keyids
By default, Subject Key Identifier and Authority Key
Identifier X.509 extensions are kept as-is in the
forged certificates. Specifying this will recalculate
the IDs to fit the forged keys.
-f, --force Overwrite key/certificate files.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
scrape
With the scrape tool you can analyze binary blobs or whole disks and search them for PEM or DER-encoded blobs. This is interesting if, for example, you're doing firmware analysis. DER analysis is quite slow because for every potential sequence beginning (0x30), decoding of all supported schema is attempted. It can be sped up if you're only looking for a particular data type instead of all of them. In contrast, scanning for PEM data is much faster because PEM markers have a much smaller false positive rate. For every occurrence that is found inside the analyzed file, the contents are written to a own file in the output directory.
usage: ./x509sak.py scrape [--no-pem] [--no-der] [-i class] [-e class]
[--extract-nested] [--keep-original-der]
[--allow-non-unique-blobs]
[--disable-der-sanity-checks] [--outmask mask]
[-w filename] [-o path] [-f] [-s offset]
[-l length] [-v] [--help]
filename
Scrape input file for certificates, keys or signatures
positional arguments:
filename File that should be scraped for certificates or keys.
optional arguments:
--no-pem Do not search for any PEM encoded blobs.
--no-der Do not search for any DER encoded blobs.
-i class, --include-dertype class
Include the specified DER handler class in the search.
Defaults to all known classes if omitted. Can be
specified multiple times and must be one of crt,
dsa_key, dsa_sig, ec_key, pkcs12, pubkey, rsa_key.
-e class, --exclude-dertype class
Exclude the specified DER handler class in the search.
Can be specified multiple times and must be one of
crt, dsa_key, dsa_sig, ec_key, pkcs12, pubkey,
rsa_key.
--extract-nested By default, fully overlapping blobs will not be
extracted. For example, every X.509 certificate also
contains a public key inside that would otherwise be
found as well. When this option is given, any blobs
are extracted regardless if they're fully contained in
another blob or not.
--keep-original-der When finding DER blobs, do not convert them to PEM
format, but leave them as-is.
--allow-non-unique-blobs
For all matches, the SHA256 hash is used to determine
if the data is unique and findings are by default only
written to disk once. With this option, blobs that
very likely are duplicates are written to disk for
every occurrence.
--disable-der-sanity-checks
For DER serialization, not only is it checked that
deserialization is possible, but additional checks are
performed for some data types to ensure a low false-
positive rate. For example, DSA signatures with short
r/s pairs are discarded by default or implausible
version numbers for EC keys. With this option, these
sanity checks will be disabled and therefore
structurally correct (but implausible) false-positives
are also written.
--outmask mask Filename mask that's used for output. Defaults to
scrape_%(offset)07x_%(type)s.%(ext)s and can use
printf-style substitutions offset, type and ext.
-w filename, --write-json filename
Write the stats with detailed information about
matches into the given filename.
-o path, --outdir path
Output directory. Defaults to scrape.
-f, --force Overwrite key/certificate files and proceed even if
outdir already exists.
-s offset, --seek-offset offset
Offset to seek into file. Supports hex/octal/binary
prefixes and SI/binary SI (k, ki, M, Mi, etc.)
suffixes. Defaults to 0.
-l length, --analysis-length length
Amount of data to inspect at max. Supports
hex/octal/binary prefixes and SI/binary SI (k, ki, M,
Mi, etc.) suffixes. Defaults to everything until EOF
is hit.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
hashpart
The hashpart facility allows the user to have all substrings of a file hashed with different hash algorithms in a brute-force manner. So for example, if you have a three-byte file "ABC" then the strings "A", "AB", "ABC", "BC" and "C" would be hashed by all selected hash functions. A search parameter allows you to have the tool only print those hexadecimal hash values which have a substring match. This makes sense when you for example have a hash value of a blob contained inside a larger blob but are unsure which hash function was used starting from which offset and which length the hash is computed over. A simple example is that you know the Subject Key Identifier (SKI) of a DER-encoded certificate and want to bruteforce the offsets over which it is calculated.
usage: ./x509sak.py hashpart [-h alg] [-o offset] [--max-offset offset]
[-a length] [-l length] [-s hexpattern] [-v]
[--help]
filename
Hash all substrings of a file and search for a particular hash value
positional arguments:
filename File that should be hashed.
optional arguments:
-h alg, --hash-alg alg
Hash function(s) that should be tried. Can be
specified multiple times and defaults to all available
hash functions. Can be any of blake2b, blake2s, md4,
md5, md5-sha1, ripemd160, sha1, sha224, sha256,
sha384, sha3_224, sha3_256, sha3_384, sha3_512,
sha512, sha512_224, sha512_256, shake_128, shake_256,
sm3, whirlpool, all, but defaults to md5, sha1,
sha256, sha384, sha512. Special value 'all' means all
supported functions.
-o offset, --seek-offset offset
Offset to seek into file. Supports hex/octal/binary
prefixes and SI/binary SI (k, ki, M, Mi, etc.)
suffixes. Defaults to 0.
--max-offset offset Largest offset to consider. By default, this is end-
of-file. Supports hex/octal/binary prefixes and
SI/binary SI (k, ki, M, Mi, etc.) suffixes.
-a length, --variable-hash-length length
For hash functions which have a variable output
length, try all of these hash lenghts. Length is given
in bits and must be a multiple of 8. Can be supplied
multiple times. Defaults to 128, 256, 384.
-l length, --analysis-length length
Amount of data to inspect at max. Supports
hex/octal/binary prefixes and SI/binary SI (k, ki, M,
Mi, etc.) suffixes. Defaults to everything until EOF
is hit.
-s hexpattern, --search hexpattern
Hexadecimal pattern that is expected in the hashing.
-v, --verbose Increase verbosity level. Can be specified multiple
times.
--help Show this help page.
License
GNU GPL-3. Thanks to the x509test project for the excellent testsuite of broken certificates (included in the x509sak/tests/data/certs/google/ subdirectory).