nbdkit_peer_tls_dn(3)

📦
version 1.48.1 · 10 versions
, in fedora 44

💖 nbdkit_peer_tls_dn(3) 💖

okay bestie, gather round, because this is the page for nbdkit_peer_tls_dn and nbdkit_peer_tls_issuer_dn — the two lil functions that let you read the client's TLS X.509 Distinguished Name. yes, the whole "who even are you" of certificate land. it's giving ✨identity crisis but make it cryptographically verified✨.

✨ NAME ✨

nbdkit_peer_tls_dn, nbdkit_peer_tls_issuer_dn — read the client TLS X.509 Distinguished Name

🌸 SYNOPSIS 🌸

#include <nbdkit-plugin.h>

char *nbdkit_peer_tls_dn (void);
char *nbdkit_peer_tls_issuer_dn (void);

like, that's it. two functions, zero arguments, maximum drama. 💅

🦋 DESCRIPTION 🦋

so here's the vibe check. these APIs only wake up and do their thing if ALL of these conditions are met:

  • the client connects over TLS (peep nbdkit-tls(1) for the deets)
  • the TLS connection is using X.509 certificates
  • the client actually presents a client certificate (no cert, no DN, sorry babe 😭)
  • the nbdkit --tls-verify-peer option is being used

when every single one of those boxes is ticked, you can use these APIs to get the Distinguished Name (DN) of the certificate, or the DN of the certificate's issuer. and what's an issuer, you ask? it's the Certificate Authority (CA) that issued the client certificate. the origin story. the parent figure. 👑

the DN comes back as a string shaped like "CN=xx,O=yy,[...]C=zz" — and if you want the exact format, go read RFC 4514, because we are not paraphrasing a spec, bestie.

if the DN is not available, you get "" back. and listen — that is not an error. it's just a shrug. it's fine. don't panic. 🫶

oh and btw, nbdkit-ip-filter(1) can filter client connections by the DN, so if you wanted to be picky about who gets in, that's your girl.

🎀 EXAMPLE CERTIFICATE AND DISTINGUISHED NAME 🎀

for the how-to on generating client certificates, go see nbdkit-tls(1). but let's do a lil worked example because examples ate and left no crumbs.

if you followed those instructions and generated a client certificate from this client.info input:

country = US
state = New York
locality = New York
organization = BigCo
cn = client.example.com
tls_www_client
encryption_key
signing_key

and then signed it with this Certificate Authority ca.info:

cn = BigCo
ca
cert_signing_key

then the client certificate DN would be:

CN=client.example.com,O=BigCo,L=New York,ST=New York,C=US

and the issuer DN would be:

CN=BigCo

see how the issuer is just... the CA? yeah. short and iconic. ⭐

💜 RETURN VALUE 💜

on success, both of these functions return a TLS Distinguished Name as a string, or "". and heads up: the caller must free this string. that memory is yours now, bestie, you gotta take it home and look after it. 🙈

if there's an error, they call nbdkit_error(3) and return NULL. so yeah, check for NULL, okay? don't be out here dereferencing vibes.

🧚 LANGUAGE BINDINGS 🧚

🐍 In nbdkit-ocaml-plugin(3):

NBDKit.peer_tls_dn : unit -> string
NBDKit.peer_tls_issuer_dn : unit -> string

💙 In nbdkit-python-plugin(3):

import nbdkit
dn = nbdkit.peer_tls_dn()
dn = nbdkit.peer_tls_issuer_dn()

not me giving you bindings in two languages because I love you. 🫶

⭐ HISTORY ⭐

"nbdkit_peer_tls_dn" and "nbdkit_peer_tls_issuer_dn" were added in nbdkit 1.40. so they're relatively new around here. fresh out the box. main character debut energy. 👑

🌈 SEE ALSO 🌈

nbdkit(1), nbdkit-plugin(3), nbdkit-filter(3), nbdkit-tls(1), nbdkit-ip-filter(1), nbdkit_is_tls(3), nbdkit_peer_name(3).

the whole friend group, honestly. iykyk. 💖

🎀 AUTHORS 🎀

Richard W.M. Jones — the icon, the legend, the one who wrote this. 💅

Copyright Red Hat

👑 LICENSE 👑

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
no cap, that's the whole legal situation, and yes it's all caps because legal text has zero chill. 😭

and that's the page, bestie!! 🎀 this whole thing is from nbdkit-1.48.1, dated 2026-08-29, so if you're reading a copy from some other timeline, that's on you. mwah, go forth and read those DNs. 💖✨🦋

📦 where this page comes from