OPENSSL-TS(1SSL)

📦

version 4.0.3 · 13 versions

✨ openssl-ts — the Time Stamping Authority command, bestie 💅

okay so you found openssl-ts from the OpenSSL manual, section 1SSL, and honestly? it's giving notary public but make it cryptography. let's get into it 🫶

🌸 SYNOPSIS 🌸

like, here's the whole vibe of how you call it. copy-paste exact, no cap:

openssl ts -help

openssl ts -query [-config configfile] [-data file_to_hash] [-digest
digest_bytes] [-digest] [-tspolicy object_id] [-no_nonce] [-cert] [-in
request.tsq] [-out request.tsq] [-text] [-rand files] [-writerand file]
[-provider name] [-provider-path path] [-provparam [name:]key=value]
[-propquery propq]

openssl ts -reply [-config configfile] [-section tsa_section]
[-queryfile request.tsq] [-passin password_src] [-signer tsa_cert.pem]
[-inkey filename|uri] [-digest] [-chain certs_file.pem] [-tspolicy
object_id] [-in response.tsr] [-token_in] [-out response.tsr]
[-token_out] [-text] [-provider name] [-provider-path path] [-provparam
[name:]key=value] [-propquery propq]

openssl ts -verify [-data file_to_hash] [-digest digest_bytes]
[-queryfile request.tsq] [-in response.tsr] [-token_in] [-untrusted
files|uris] [-CAfile file] [-CApath dir] [-CAstore uri]
[-allow_proxy_certs] [-attime timestamp] [-no_check_time]
[-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy]
[-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map]
[-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose
purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first]
[-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num]
[-verify_email email] [-verify_hostname hostname] [-verify_ip ip]
[-verify_name name] [-x509_strict] [-issuer_checks] [-provider name]
[-provider-path path] [-provparam [name:]key=value] [-propquery propq]

🌈 DESCRIPTION 🌈

so basically this command is a whole Time Stamping Authority (TSA) situation — both the client and the server side — exactly as specified in RFC 3161 (that's the Time-Stamp Protocol, aka TSP). a TSA can be part of a PKI deployment, and its whole job is to give you long term proof that a certain datum existed before a particular time. iconic, honestly. 🕰️✨

here's the protocol in three lil steps, bestie:

The TSA client computes a one-way hash value for a data file and sends that hash over to the TSA. 💌
The TSA attaches the current date and time to the hash it received, signs the whole thing, and sends the timestamp token back to the client. by creating this token, the TSA certifies that the original data file existed at the moment the response was generated. periodt. 🔥
The TSA client receives the timestamp token and verifies the signature on it. it also checks whether the token contains the same hash value it originally sent to the TSA. vibe check passed or not, we love a verification step. ✅

there's one DER encoded protocol data unit defined for transporting a timestamp request to the TSA, and one for sending the timestamp response back to the client. so this command has three main functions, and they are:

creating a timestamp request based on a data file
creating a timestamp response based on a request
verifying if a response corresponds to a particular request or a data file

and ngl, there is no support for sending the requests/responses automatically over HTTP or TCP yet, even though RFC 3161 suggests it. so if you were hoping for an auto-fire-off situation? not here, bestie. 😭 the users must send the requests either by ftp or by e-mail.

fr fr: no HTTP, no TCP — you're manually shipping these PDU-lil-things yourself.

✨ OPTIONS ✨

okay bestie, gather round, here's the whole menu of flags 🎀

-help — prints a usage message, that's it, that's the whole vibe 💅
-query — makes a TS query. the deets live down in "Timestamp Request generation" ✨
-reply — makes a TS reply. deets down in "Timestamp Response generation" 💖
-verify — checks a TS response. deets down in "Timestamp Response verification" 🦋

🌸 Timestamp Request generation 🌸

so the -query command is your girl for creating AND printing a timestamp request, and here's every knob she comes with:

-config configfile — the config file she should use. optional! for what the default value is, go peek at "COMMAND SUMMARY" in openssl(1) 🫶
-data file_to_hash — the data file you need the timestamp request built for. if you specify neither -data nor -digest, then stdin is the default. (optional) 😌
-digest digest_bytes — yes you can hand over the message imprint yourself without any data file at all. it has to be in hexadecimal, two characters per byte, and the bytes may be separated by colons (like 1A:F6:01:... or 1AF601...). the number of bytes has to match whatever message digest algorithm is in play, no cap. (optional) 🔥
-digest — the message digest to apply to the data file. literally any digest that openssl-dgst(1) supports works here. default is SHA-256. (optional) ⭐
-tspolicy object_id — the policy the client expects the TSA to use when it builds the timestamp token. you can use either the dotted OID notation or OID names defined in the config file. if you request no policy at all, the TSA just falls back on its own default policy. (optional) 👑
-no_nonce — hand this flag over and no nonce gets put in the request. otherwise a 64-bit long pseudo-random nonce is included. bestie, use a nonce, it protects you against replay attacks, it's giving self-care. (optional) 🛡️
-cert — the TSA is expected to include its signing certificate in the response. (optional) 🎀
-in request.tsq — points at a previously created timestamp request in DER format that'll be printed into the output file. so useful when you need to examine the content of a request in human-readable format. (optional) 🦋
-out request.tsq — name of the output file the request gets written to. default is stdout. (optional) 💖
-text — give this one and the output is human-readable text format instead of DER. (optional) ✨
-rand files, -writerand file — see "Random State Options" in openssl(1) for the deets. 🌈

💜 Timestamp Response generation 💜

okay so a timestamp response (TimeStampResp) is literally two things: a response status, plus the timestamp token itself (ContentInfo) — that second part only shows up if the token generation actually worked out. the -reply command creates a timestamp response or timestamp token based on a request, and prints the response/token in human-readable format. heads up: if -token_out is not specified, the output is always a timestamp response (TimeStampResp); otherwise it's a timestamp token (ContentInfo). periodt 💅

-config configfile — the config file to use. optional! for a description of the default value see "COMMAND SUMMARY" in openssl(1). and see "CONFIGURATION FILE OPTIONS" for the variables you can configure. 🫶
-section tsa_section — the name of the config file section holding the settings for response generation. if you don't specify one, the default TSA section gets used — see "CONFIGURATION FILE OPTIONS" for the details. (optional) 🌸
-queryfile request.tsq — name of the file containing a DER encoded timestamp request. (optional) 📄
-passin password_src — sets the password source for the TSA's private key. the description lives in openssl(1). (optional) 🔐
-signer tsa_cert.pem — the TSA's signer certificate, PEM format. and okay this matters a lot: the TSA signing certificate must have exactly one extended key usage assigned to it: timeStamping. that extended key usage also has to be critical, otherwise the certificate is getting refused, no exceptions. this option overrides the signer_cert variable from the config file. (optional) 💀
-inkey filename|uri — the TSA's signer private key, PEM format. overrides the signer_key config file option. (optional) 🔑
-digest — the signing digest to use. overrides the signer_digest config file option. mandatory unless it's specified in the config file. bestie you cannot skip this one 😭
-chain certs_file.pem — a whole collection of certificates in PEM format that all get included in the response in addition to the signer certificate, but only if -cert was used for the request. this file is supposed to hold the certificate chain for the signer certificate, from its issuer upwards. real talk: -reply does not build a certificate chain automatically. (optional) ⛓️
-tspolicy object_id — the default policy used for the response, unless the client explicitly demands a particular TSA policy. the OID goes in either dotted notation or by its name. overrides the default_policy config file option. (optional) 👑
-in response.tsr — specifies a previously created timestamp response, or a timestamp token (if -token_in is also specified), in DER format, that gets written to the output file. this one doesn't need a request at all — super handy when you need to examine the content of a response or token, or when you wanna extract the timestamp token out of a response. oh and if the input is a token and the output is a timestamp response, a default 'granted' status info gets added to the token. (optional) 🦋
-token_in — this flag pairs with the -in option and says: hey, the input is a DER encoded timestamp token (ContentInfo), not a timestamp response (TimeStampResp). (optional) 🎀
-out response.tsr — the response gets written to this file. the format and content of that file depends on the other options (peep -text and -token_out). default is stdout. (optional) 💖
-token_out — the output becomes a timestamp token (ContentInfo) instead of a timestamp response (TimeStampResp). (optional) ✨
-text — specify this and the output is human-readable text format instead of DER. (optional) 📝
-provider name
-provider-path path
-provparam [name:]key=value
-propquery propq — go see "Provider Options" in openssl(1), plus provider(7) and property(7). 🌈

🦋 Timestamp Response verification 🦋

the -verify command checks whether a timestamp response or timestamp token is valid and matches a particular timestamp request or data file. important note, bestie: -verify does not use the configuration file. at all. 💅

-data file_to_hash — the response or token has to be verified against file_to_hash. the file gets hashed with the message digest algorithm specified in the token. and psst — the -digest and -queryfile options must not be specified alongside this one. (optional) 📄
-digest digest_bytes — the response or token has to be verified against the message digest you pass in here. the number of bytes must match the message digest algorithm specified in the token. and again — -data and -queryfile must not be specified alongside this one. (optional) 🔥
-queryfile request.tsq — the original timestamp request, DER format. -data and -digest must not be specified alongside this one. (optional) 🎀
-in response.tsr — the timestamp response that needs verifying, DER format. (Mandatory) — yeah she's required, no skipping 💀
-token_in — pairs with the -in option, meaning the input is a DER encoded timestamp token (ContentInfo) rather than a timestamp response (TimeStampResp). (optional) 🦋
-untrusted files|uris — a set of extra untrusted certificates that might be needed while building the certificate chain for the TSA's signing certificate. these don't have to contain the TSA signing certificate or the intermediate CA certificates, as long as the response already includes them. (optional)
- multiple sources are allowed, separated by commas and/or whitespace. each file may contain multiple certificates. 💖
-CAfile file, -CApath dir, -CAstore uri — see "Trusted Certificate Options" in openssl-verification-options(1) for the deets. at least one of -CAfile, -CApath or -CAstore must be specified. 🔐
-allow_proxy_certs, -attime, -no_check_time, -check_ss_sig, -crl_check, -crl_check_all, -explicit_policy, -extended_crl, -ignore_critical, -inhibit_any, -inhibit_map, -no_alt_chains, -partial_chain, -policy, -policy_check, -policy_print, -purpose, -suiteB_128, -suiteB_128_only, -suiteB_192, -trusted_first, -use_deltas, -auth_level, -verify_depth, -verify_email, -verify_hostname, -verify_ip, -verify_name, -x509_strict, -issuer_checks — these set all sorts of certificate chain verification options. see "Verification Options" in openssl-verification-options(1) for the details.

any verification errors cause the command to exit. like, it's out. gone. ✌️

💖 CONFIGURATION FILE OPTIONS 💖

okay so -query and -reply are the two commands that actually read a config file, bestie. If you wanna know how the config file syntax works in general, go peek at config(5). Here's the tea tho: -query only uses the symbolic OID names section, and it can literally work without one. But -reply? She NEEDS that config file to function. No config, no reply, periodt. 💅

And listen — when a command line switch exists that matches a variable, the switch ALWAYS overrides the config file. Every single time. The command line is the main character here. 👑

🌸 `tsa` section, `default_tsa`

This is THE main section, and it names another section that holds all the options for the -reply command. You can override this default section with the -section command line switch. (Optional)

🌸 `oid_file`

Points to a file full of extra OBJECT IDENTIFIERS. Each line is: the numerical form of the object identifier, then whitespace, then the short name, then whitespace, then the long name. (Optional)

🌸 `oid_section`

Names a section inside the config file that has extra object identifiers in it. Each line is the short name of the object identifier, then =, then the numerical form. When you use this option the short and long names are the same. (Optional)

🌸 `RANDFILE`

At startup, the file you name here gets loaded into the random number generator, and at exit 256 bytes get written back to it. (Heads up: using a RANDFILE isn't necessary anymore, go look at the "HISTORY" section below.)

🌸 `serial`

The name of the file holding the hexadecimal serial number of the last timestamp response that got created. This number increments by 1 for every response. And if the file doesn't exist when you generate a response, a new file gets created with serial number 1. (Mandatory) ✨

🌸 `signer_cert`

TSA signing certificate in PEM format. Same thing as the -signer command line option. (Optional)

🌸 `certs`

A file with a set of PEM encoded certificates that need to be included in the response. Same thing as the -chain command line option. (Optional)

🌸 `signer_key`

The private key of the TSA, in PEM format. Same thing as the -inkey command line option. (Optional)

🌸 `signer_digest`

The signing digest to use. Same thing as the -digest command line option. (Mandatory unless you specified it on the command line)

🌸 `default_policy`

The default policy to use when the request doesn't mandate any policy. Same thing as the -tspolicy command line option. (Optional)

🌸 `other_policies`

A comma separated list of policies that the TSA also finds acceptable — but these only get used if the request explicitly specifies one of them. (Optional)

🌸 `digests`

The list of message digest algorithms the TSA accepts. You gotta specify at least one algorithm. (Mandatory)

🌸 `accuracy`

The accuracy of the time source of the TSA, given in seconds, milliseconds and microseconds. Like secs:1, millisecs:500, microsecs:100. If any component is missing, zero is assumed for that field. (Optional)

🌸 `clock_precision_digits`

Specifies the max number of digits — the ones representing the fraction of seconds — that need to be included in the time field. Trailing zeros must be removed from the time, so there might actually be fewer digits, or maybe no fraction of seconds at all. Only supported on UNIX platforms. Max value is 6, default is 0. (Optional)

🌸 `ordering`

Set this to yes and the responses this TSA generates can always be ordered, even when the time difference between two responses is less than the sum of their accuracies. Default is no. (Optional)

🌸 `tsa_name`

Set this option to yes if the subject name of the TSA must be included in the TSA name field of the response. Default is no. (Optional)

🌸 `ess_cert_id_chain`

The SignedData objects the TSA creates always contain the certificate identifier of the signing certificate in a signed attribute (see RFC 2634, Enhanced Security Services). If this variable is set to no, only that signing certificate identifier goes into the SigningCertificate signed attribute. If it's set to yes AND the certs variable or the -chain option is specified, then the certificate identifiers of the chain get included too — and the -chain option overrides the certs variable. Default is no. (Optional)

🌸 `ess_cert_id_alg`

This one specifies the hash function used to calculate the TSA's public key certificate identifier. Default is sha256. (Optional)

✨ EXAMPLES ✨

Every single example below assumes OPENSSL_CONF is set to a proper configuration file — like, the example config file openssl/apps/openssl.cnf will do the job. 🦋

🎀 Timestamp Request

Wanna create a timestamp request for design1.txt with SHA-256 digest, no nonce, no policy, and no requirement for a certificate in the response? Slay, here you go:

openssl ts -query -data design1.txt -no_nonce \
      -out design1.tsq

To make a similar timestamp request but with the message imprint specified explicitly:

openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
       -no_nonce -out design1.tsq

To print the content of that previous request in human readable format:

openssl ts -query -in design1.tsq -text

To create a timestamp request that includes the SHA-512 digest of design2.txt, requests the signer certificate and a nonce, and specifies a policy id (this assumes the tsa_policy1 name is defined in the OID section of the config file):

openssl ts -query -data design2.txt -sha512 \
      -tspolicy tsa_policy1 -cert -out design2.tsq

🎀 Timestamp Response

okay before you generate a response, you MUST create a signing certificate for the TSA that contains the timeStamping critical extended key usage extension and no other key usage extensions. Add this line to the user certificate section of the config file to generate a proper certificate:

extendedKeyUsage = critical,timeStamping

Check out openssl-req(1), openssl-ca(1), and openssl-x509(1) for the instructions. The examples below all assume cacert.pem contains the certificate of the CA, tsacert.pem is the signing certificate issued by cacert.pem, and tsakey.pem is the private key of the TSA. 💜

To create a timestamp response for a request:

openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
      -signer tsacert.pem -out design1.tsr

If you'd rather use the settings in the config file, you could literally just write:

openssl ts -reply -queryfile design1.tsq -out design1.tsr

To print a timestamp reply to stdout in human readable format:

openssl ts -reply -in design1.tsr -text

To create a timestamp token instead of a timestamp response:

openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out

To print a timestamp token to stdout in human readable format:

openssl ts -reply -in design1_token.der -token_in -text -token_out

To extract the timestamp token out of a response:

openssl ts -reply -in design1.tsr -out design1_token.der -token_out

To add granted status info to a timestamp token and thereby create a valid response:

openssl ts -reply -in design1_token.der -token_in -out design1.tsr

🎀 Timestamp Verification

To verify a timestamp reply against a request:

openssl ts -verify -queryfile design1.tsq -in design1.tsr \
      -CAfile cacert.pem -untrusted tsacert.pem

To verify a timestamp reply that includes the certificate chain:

openssl ts -verify -queryfile design2.tsq -in design2.tsr \
      -CAfile cacert.pem

To verify a timestamp token against the original data file:

openssl ts -verify -data design2.txt -in design2.tsr \
      -CAfile cacert.pem

To verify a timestamp token against a message imprint:

openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
       -in design2.tsr -CAfile cacert.pem

You could also go look at the 'test' directory for more examples. 🧚

💀 BUGS 💀

No support for timestamps over SMTP, even though it's actually quite easy to implement an automatic e-mail based TSA with procmail(1) and perl(1). HTTP server support comes in the form of a separate apache module. HTTP client support is provided by tsget(1). Pure TCP/IP protocol is not supported.
The file containing the last serial number of the TSA is not locked when it's being read or written. That's a whole problem if more than one instance of openssl(1) is trying to create a timestamp response at the same time. Not an issue when you're using the apache server module tho — it does proper locking. 🫶
Look for the FIXME word in the source files. 🙈
The source code should really be reviewed by somebody else, too. 😭
More testing is needed — only some basic tests have been done (see test/testtsa).

🌈 HISTORY 🌈

OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an improved seeding mechanism. That new seeding mechanism makes it unnecessary to define a RANDFILE for saving and restoring randomness. This option sticks around mainly for compatibility reasons. ⭐

The -engine option and the crypto_device configuration option were removed in OpenSSL 4.0.

💅 COPYRIGHT 💅

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page bestie, you read every single crumb of it 🍓 — this was OpenSSL 4.0.3, dated 2026-09-29, and it's the OPENSSL-TS(1SSL) manual page. go forth and timestamp responsibly, ily 💖🦋✨

📦 where this page comes from

ubuntu stonking: openssl 4.0.3-1ubuntu1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

OPENSSL-TS(1SSL)

✨ openssl-ts — the Time Stamping Authority command, bestie 💅

🌸 SYNOPSIS 🌸

🌈 DESCRIPTION 🌈

✨ OPTIONS ✨

🌸 Timestamp Request generation 🌸

💜 Timestamp Response generation 💜

🦋 Timestamp Response verification 🦋

💖 CONFIGURATION FILE OPTIONS 💖

🌸 tsa section, default_tsa

🌸 oid_file

🌸 oid_section

🌸 RANDFILE

🌸 serial

🌸 signer_cert

🌸 certs

🌸 signer_key

🌸 signer_digest

🌸 default_policy

🌸 other_policies

🌸 digests

🌸 accuracy

🌸 clock_precision_digits

🌸 ordering

🌸 tsa_name

🌸 ess_cert_id_chain

🌸 ess_cert_id_alg