github Download

extract-client-id #

extract-client-id is acra-keys subcommand used for generating ClientID from TLS certificate.

Command line flags #

General flags #

  • --tls_cert=<path> (deprecated since 0.96.0) 🔴

    Path to TLS certificate to use as client_id identifier. Use --tls_client_id_cert instead.

  • --tls_client_id_cert=<path>

    Path to TLS certificate to use as ClientID identifier. Works only when passed empty ClientID: --client_id="". Should be used instead of --tls_cert.

  • --tls_identifier_extractor_type={distinguished_name|serial_number}

    Decide which field of TLS certificate to use as ClientID.

    • distinguished_name — certificate Distinguished Name (DN)
    • serial_number — certificate serial number
  • --print_json

    Use machine-readable JSON output.

    🔴 - flags required to be specified.

Usage example #

extract-client-id subcommand could be used to generate ClientID to reference some keys generated by export subcommand of acra-keys via tls_cert flag and empty client_id.

Suppose you have a certificate that application will send to AcraServer/AcraTranslator during TLS handshake:

$ openssl x509 -noout -text -in /path/to/certificate/application.crt.pem
        Version: 3 (0x2)
        Serial Number:
        ### skipped irrelevant part ###
        Subject: C = GB, ST = London, L = London, O = Global Security, OU = IT, CN = Test leaf certificate
        ### skipped irrelevant part ###

and you want AcraServer/AcraTranslator to use specific encryption keys to process this application requests. For this you will need to transform the certificate serial number or Distinguished Name using the same algorithm AcraServer/AcraTranslator will use.

Here’s how to use distinguished_name (which uses subject from the certificate):

$ acra-keys extract-client-id \
    --tls_cert=/path/to/certificate/application.crt.pem \

And here’s how to use serial_number (which, obviously, uses serial number of given certificate):

$ acra-keys extract-client-id \
    --tls_cert=/path/to/certificate/application.crt.pem \

extract-client-id will not only use the specified field(s), but will also perform SHA512 hashing of it to make sure all generated Client IDs are the same, acceptable length. Here’s how you can get the same result manually:

# take serial number of the example certificate from above,
# remove anything except hex digits,
# transform it into raw bytes (kind of reverse hexdump),
# and finally hash it with sha512
$ echo -n 07:ea:07:47:5c:85:ec:55:49:b3:44:42:18:08:5e:a7:6a:30:1d:4d \
    | tr -d ':' \
    | xxd -ps -r \
    | sha512sum

Additionally, you can specify --print_json to get output in machine-readable JSON format.

$ acra-keys extract-client-id \
    --tls_cert=/path/to/certificate/application.crt.pem \

The future steps would be like these:

  • Generate keys (acra-keys generate or acra-keymaker) for your application, for the --client_id option use ClientID provided by extract-client-id
  • Tell AcraServer/AcraTranslator to use the same --tls_identifier_extractor_type as you used during ClientID extraction
  • Make application use that same certificates you extracted ClientID from

AcraServer/AcraTranslator will automagically use proper encryption keys to process this application requests. Of course, you can have as many ClientID/certificate pairs as you like.