pki(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

pki(n) — public key encryption, but make it ✨iconic✨

okay so bestie, welcome to pki(n) — the public key encryption manual, but make it ✨iconic✨. no cap.

🌸 NAME 🌸

pki — it's the implementation of the public key cipher. periodt. 💅

✨ SYNOPSIS ✨

first things first, you gotta have these lines, bestie:

package require Tcl 8.5 9

package require pki ?0.22?

::pki::encrypt  ?-binary?  ?-hex?  ?-pad?  ?-nopad?  ?-priv? ?-pub? ?--?
input key

::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub?  ?--?
input key

::pki::sign input key ?algo?

::pki::verify signedmessage plaintext key ?algo?

::pki::key key ?password? ?encodePem?

::pki::pkcs::parse_key key ?password?

::pki::x509::parse_cert cert

::pki::rsa::generate bitlength ?exponent?

::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?

::pki::x509::validate_cert     cert     ?-sign_message     dn_of_signer?
?-encrypt_message dn_of_signer?  ?-sign_cert  dn_to_be_signed  ca_depth?
?-ssl dn?

::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?

::pki::pkcs::parse_csr csr

::pki::x509::create_cert  signreqlist  cakeylist serial_number notBefore
notAfter isCA extensions ?encodePem? ?algo?

💖 DESCRIPTION 💖

okay so this is where the description would spill the tea, but bestie, that part is coming in the next chunks — don't go anywhere, we're just getting started 💅✨

💖 the actual commands 💖

Bestie. Sit down. Hydrate. We're doing the commands now and there are a lot of them, but every single one is gonna make sense by the end, I promise. 🫶

`::pki::encrypt`

::pki::encrypt ?-binary? ?-hex? ?-pad? ?-nopad? ?-priv? ?-pub? ?--? input key

Encrypt a message using PKI (probably RSA, let's be honest). ✨

The way this works: you have to tell it which key you're using — -priv to encrypt with the private key, or -pub to encrypt with the public key. There's no "figure it out yourself" mode. One of -pub or -priv must be specified. The default behaviour is to pad and hand you back hex.

-hex — the data comes back encoded as a hexidecimal string. 💅
-binary — the data comes back as a binary string.
-pad — the data gets padded per PKCS#1 before it's encrypted. 🎀
-nopad — blocks the padding, no padding for you.

Heads up: if you pass -hex / -binary more than once, or -pad / -nopad more than once, the last one you said wins. No merging, no arguing, last one slays. 👑

The thing you're encrypting goes in the input argument.

The key argument — that's the key you're using, and it's a return value from one of these three:

::pki::pkcs::parse_key
::pki::x509::parse_cert
::pki::rsa::generate

Mapping to OpenSSL's openssl application:

"openssl rsautl -encrypt" == "::pki::encrypt -binary -pub"
"openssl rsautl -sign" == "::pki::encrypt -binary -priv"

`::pki::decrypt`

::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--? input key

Decrypt a message using PKI (again, probably RSA). For how all the options behave, go read ::pki::encrypt — same energy, same handling. 🦋

Mapping to OpenSSL's openssl application:

"openssl rsautl -decrypt" == "::pki::decrypt -binary -priv"
"openssl rsautl -verify" == "::pki::decrypt -binary -pub"

`::pki::sign`

::pki::sign input key ?algo?

Digitally sign the message input using the private key. ✍️

If algo is ommited, "sha1" is assumed. The possible values for algo include "md5", "sha1", "sha256", and "raw". 🎀

Attention, this one actually matters: if you specify "raw" for algo, it inhibits the building of an ASN.1 structure that would encode which hashing algorithm was chosen. In that case, the corresponding pkgi::verify must be called with algorithm information. And conversely — if you specify a non-"raw" algorithm here, then the corresponding pkgi::verify invokation has to be made without algorithm information. It's a matched set, bestie. Don't split them up. 😭

The input should be the plain text — hashing happens on it.

The key should include the private key. 🔑

`::pki::verify`

::pki::verify signedmessage plaintext key ?algo?

Verify a digital signature</purl> using a public key. Returns true or false. That's it, that's the whole vibe check. ✅

Attention: the algorithm information algo has to be specified if and only if the pki::sign that generated the signedmessage was called with the algorithm "raw" — because that's what inhibited the building of the ASN.1 structure encoding the chosen hashing algorithm. And conversely, if a proper algorithm was specified during signing, then you must not specify an algorithm here. Matching game, fr fr. 🧚

`::pki::key`

::pki::key key ?password? ?encodePem?

Convert a key structure into a serialized PEM (that's the default) or DER encoded private key, suitable for other applications. 💫 For RSA keys, this means PKCS#1.

`::pki::pkcs::parse_key`

::pki::pkcs::parse_key key ?password?

Convert a PKCS#1 private key into a usable key — and by usable I mean one you can actually hand to ::pki::encrypt, ::pki::decrypt, ::pki::sign, and ::pki::verify. 🔥

`::pki::x509::parse_cert`

::pki::x509::parse_cert cert

Convert an X.509 certificate into a usable (public) key. The dictionary you get back can be used as an argument for ::pki:encrypt, ::pki::decrypt, and ::pki::verify. 🌈

The cert argument can be either PEM or DER encoded.

On top of all the public keying info, the dictionary also contains these keys, holding certificate content as defined in RFC5280 (https://www.rfc-editor.org/rfc/rfc5280#section-4.1):

subject holds the name of the subject from the certificate. 🎀
issuer holds the name of the issuing CA.
serial_number holds the serial number of the certificate.
notBefore holds the starting date for certificate validity.
notAfter holds the ending date for certificate validity.
version holds the X.509 version format.
extensions holds a dictionary containing the extensions included in the certificate (more on that below 👇).

The dictionary holds additional entries related to keying, too. Those are intended for use with the commands mentioned above for cryptographic operations. 🔐

The extensions key in the returned dictionary holds a nested dictionary whose keys correspond to the names (with the same exact case 👀) in Certificate Extensions (https://www.rfc-editor.org/rfc/rfc5280#section-4.2) in RFC5280. The format of each value is also based on the ASN.1 structures defined there. See the Examples (#section3) for an illustration. ✨

`::pki::rsa::generate`

::pki::rsa::generate bitlength ?exponent?

Generate a brand new RSA key pair, the parts of which can be used as arguments for ::pki::encrypt, ::pki::decrypt, ::pki::sign, and ::pki::verify. 🗝️✨

The bitlength argument is the length of the public key modulus.

The exponent argument should generally not be specified unless you really know what you are doing. Like genuinely. Not "I read a blog post" know. Actually know. 💀

`::pki::x509::verify_cert`

::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?

Verify that a trust can be found between the certificate specified in the cert argument and one of the certificates specified in the list of certificates in the trustedcerts argument. 🫶

Note: eventually the chain can be through untrusted certificates listed in the intermediatecerts argument, but this is currently unimplemented. 🙈

The certificates specified in the cert and trustedcerts option should be parsed — from ::pki::x509::parse_cert. 📜

`::pki::x509::validate_cert`

::pki::x509::validate_cert cert ?-sign_message dn_of_signer? ?-encrypt_message dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl dn?

Validate that a certificate is valid to be used in some capacity. If you specify multiple options, they all have to be met for this procedure to return "true". It's giving all-or-nothing. 👑

Currently, only the -sign_cert option is functional. The rest are just... there. Manifesting, bestie. 🕯️

The -sign_cert arguments are dn_to_be_signed and ca_depth.

dn_to_be_signed is the distinguished from the subject of a certificate, used to verify that the certificate specified in the cert argument can sign. ✍️
ca_depth is used to indicate at which depth the verification should be done at. Some certificates are limited to how far down the chain they can be used to verify a given certificate. 🪜

`::pki::pkcs::create_csr`

::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?

Generate a certificate signing request from a key pair specified in the keylist argument. 📝

The namelist argument is a list of "name" followed by "value" pairs, to encoding as the requested distinguished name in the CSR.

The encodePem option specifies whether the result should be PEM encoded or DER encoded. A "true" value means the result is PEM encoded, while any other value results in the result being DER encoded. DER encoding is the default. 🎀

The algo argument specifies the hashing algorithm we should use to sign this certificate signing request with. The default is "sha1". Other possible values include "md5" and "sha256". 💅

`::pki::pkcs::parse_csr`

::pki::pkcs::parse_csr csr

Parse a Certificate Signing Request. The csr argument can be either PEM or DER encoded. 🌈

The command returns a dictionary that includes the following keys:

subject — contains the subject name from the CSR. 🎀
type — contains the public key algorithm name. Currently only rsa is supported.
extensionRequest — contains a dictionary with the contents of the extensionRequest (https://datatracker.ietf.org/doc/html/rfc2986#page-5) information in the CSR. This has the same form as described for the extensions dictionary in the documentation for parse_cert. 🦋

There may be other keys in the dictionary related to the public key algorithm in use. iykyk. ✨

`::pki::x509::create_cert`

::pki::x509::create_cert signreqlist cakeylist serial_number notBefore notAfter isCA extensions ?encodePem? ?algo?

Sign a signing request (usually from ::pki::pkcs::create_csr or ::pki::pkcs::parse_csr) with a Certificate Authority (CA) certificate. 👑

signreqlist — should be the parsed signing request. 📜
cakeylist — should be the parsed CA certificate. 🍰 (sorry, the name is right there, I had to)
serial_number — should be a serial number unique to this certificate from this certificate authority. 🔢
notBefore and notAfter — should contain the time before and after which (respectively) the certificate should be considered invalid. The time should be encoded as something clock format will accept — i.e., the results of clock seconds and clock add. ⏰
isCA — a boolean argument describing whether or not the signed certificate should be a a CA certificate. If specified as true, the "id-ce-basicConstraints" extension is added, with the arguments of "critical" being true, "allowCA" being true, and caDepth being -1 (infinite). ♾️
extensions — a list of extensions and their parameters that should be encoded into the created certificate. ✨

Currently only one extension is understood: "id-ce-basicConstraints". It accepts three arguments: critical, allowCA, caDepth.

critical — for this extension (and any extension, tbh) it says whether or not the validator should reject the certificate as invalid if it does not understand the extension (if set to "true") or should ignore the extension (if set to "false"). 🚨
allowCA — a boolean value specifying whether or not we can be used as a certificate authority (CA). 👑
caDepth — indicates how many children CAs can be children of this CA, in a depth-wise fashion. A value of "0" means this CA cannot sign a CA certificate and have the result be valid. A value of "-1" indicates infinite depth. ♾️

and bestie we are SO not done yet — keep scrolling, the rest is coming 💜

💖 EXAMPLES 💖

Okay bestie, this is the glow-up moment ✨ — here's how you actually pull a cert off a real live server, using the TLS extension, and then dump everything inside it. Watch and learn 🎀

% set so [tls::socket www.example.com 443]
sock00000229EB84E710
% tls::handshake $so
1
% set status [tls::status $so]
...output not shown...
% set cert_pem [dict get $status certificate]
...output not shown...
% set cert [::pki::x509::parse_cert $cert_pem]
...output not shown...
% dict get $cert subject
C=US, ST=California, L=Los Angeles, O=Internet Corporation for Assigned Names and Numbers, CN=www.example.org
% dict get $cert issuer
C=US, O=DigiCert Inc, CN=DigiCert TLS RSA SHA256 2020 CA1
% clock format [dict get $cert notAfter]
Sun Dec 26 05:29:59 +0530 2021
% set extensions [dict get $cert extensions]
...output not shown...
% dict keys $extensions
authorityKeyIdentifier subjectKeyIdentifier subjectAltName keyUsage extKeyUsage cRLDistributionPoints certificatePolicies authorityInfoAccess id-ce-basicConstraints basicConstraints 1.3.6.1.4.1.11129.2.4.2
dict get $extensions basicConstraints
1 {0 -1}
% dict get $extensions keyUsage
1 {5 digitalSignature keyEncipherment}
% dict get $extensions extKeyUsage
0 {serverAuth clientAuth}
% dict get $extensions subjectAltName
0 {dNSName www.example.org dNSName example.com dNSName example.edu dNSName example.net dNSName example.org dNSName www.example.com dNSName www.example.edu dNSName www.example.net}
% dict get $extensions basicConstraints
1 {0 -1}
% dict get $extensions keyUsage
1 {5 digitalSignature keyEncipherment}
% dict get $extensions extKeyUsage
0 {serverAuth clientAuth}

Like… the way tls::handshake just returns 1 and then you've got the whole tls::status dict sitting there with a certificate key in it? iconic. You grab the PEM, hand it to ::pki::x509::parse_cert, and suddenly you're reading the subject, the issuer, the notAfter (formatted all pretty with clock format), and the whole extensions dict. no cap, it ate 💅

📚 REFERENCES 📚

The lore, the canon, the required reading 🧚 — all the specs this whole thing is built on:

Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile [https://www.rfc-editor.org/rfc/rfc5280]
New ASN.1 Modules for the Public Key Infrastructure Using X.509 (PKIX) [https://www.rfc-editor.org/rfc/rfc5912]
PKCS #10: Certification Request Syntax Specification [https://www.rfc-editor.org/rfc/rfc2986]

👑 AUTHORS 👑

The main characters, fr fr:

Roy Keene, Ashok P. Nadkarni

🫶 BUGS, IDEAS, FEEDBACK 🫶

Okay so real talk 💀 — this document, and the package it describes, will undoubtedly contain bugs and other problems. Not even being dramatic, that's just how it is. Please report such in the category rsa of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. And if you've got ideas for enhancements for either the package and/or the documentation, please report those too — we want them 🥺

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. ✨

🌸 SEE ALSO 🌸

Go read these too, bestie, they're part of the family:

aes(n), blowfish(n), des(n), md5(n), sha1(n)

⭐ KEYWORDS ⭐

cipher, data integrity, encryption, public key cipher, rsa, security

🎀 CATEGORY 🎀

Hashes, checksums, and encryption

💜 COPYRIGHT 💜

And that's the whole page, bestie 🦋 — brought to you by tcllib, version 0.22, the pki(n) page itself 💖 Stay encrypted, stay iconic, mwah 💅

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
Copyright (c) 2010, 2011, 2012, 2013, 2021 - 2024 Roy Keene, Andreas Kupries, Ashok P\&. Nadkarni
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms