D2I_DSAPUBLICKEY(3)

📦 version 4.1.0, in opensuse-leap 16.0

💅 NAME: the DSA codec squad 💅

okay bestie, welcome to the D2I_DSAPUBLICKEY(3) page from the Library Functions Manual — this is literally the group chat for decoding and encoding DSA keys. The whole name-drop list is:

  • d2i_DSAPublicKey, i2d_DSAPublicKey
  • d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSA_PUBKEY_bio, d2i_DSA_PUBKEY_fp, i2d_DSA_PUBKEY_bio, i2d_DSA_PUBKEY_fp
  • d2i_DSAPrivateKey, i2d_DSAPrivateKey, d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp, i2d_DSAPrivateKey_bio, i2d_DSAPrivateKey_fp
  • d2i_DSAparams, i2d_DSAparams, d2i_DSAparams_bio, i2d_DSAparams_bio, d2i_DSAparams_fp, i2d_DSAparams_fp, DSAparams_dup
  • d2i_DSA_SIG, i2d_DSA_SIG

— decode and encode DSA keys ✨

✨ SYNOPSIS: the receipts ✨

No cap, here are the exact signatures. Copy them character-for-character, because these are not a vibe to improvise:

#include <openssl/dsa.h>

DSA *
d2i_DSAPublicKey(DSA **val_out, const unsigned char **der_in,
    long length);

int
i2d_DSAPublicKey(const DSA *val_in, unsigned char **der_out);

#include <openssl/x509.h>

DSA *
d2i_DSA_PUBKEY(DSA **val_out, const unsigned char **der_in,
    long length);

int
i2d_DSA_PUBKEY(const DSA *val_in, unsigned char **der_out);

DSA *
d2i_DSA_PUBKEY_bio(BIO *in_bio, DSA **val_out);

DSA *
d2i_DSA_PUBKEY_fp(FILE *in_fp, DSA **val_out);

int
i2d_DSA_PUBKEY_bio(BIO *out_bio, DSA *val_in);

int
i2d_DSA_PUBKEY_fp(FILE *out_fp, DSA *val_in);

#include <openssl/dsa.h>

DSA *
d2i_DSAPrivateKey(DSA **val_out, const unsigned char **der_in,
    long length);

int
i2d_DSAPrivateKey(const DSA *val_in, unsigned char **der_out);

#include <openssl/x509.h>

DSA *
d2i_DSAPrivateKey_bio(BIO *in_bio, DSA **val_out);

DSA *
d2i_DSAPrivateKey_fp(FILE *in_fp, DSA **val_out);

int
i2d_DSAPrivateKey_bio(BIO *out_bio, DSA *val_in);

int
i2d_DSAPrivateKey_fp(FILE *out_fp, DSA *val_in);

#include <openssl/dsa.h>

DSA *
d2i_DSAparams(DSA **val_out, const unsigned char **der_in, long length);

int
i2d_DSAparams(const DSA *val_in, unsigned char **der_out);

DSA *
d2i_DSAparams_bio(BIO *in_bio, DSA **val_out);

int
i2d_DSAparams_bio(BIO *out_bio, DSA *val_in);

DSA *
d2i_DSAparams_fp(FILE *in_fp, DSA **val_out);

int
i2d_DSAparams_fp(FILE, *out_fp, DSA *val_in);

DSA *
DSAparams_dup(DSA *val_in);

DSA_SIG *
d2i_DSA_SIG(DSA_SIG **val_out, const unsigned char **der_in,
    long length);

int
i2d_DSA_SIG(const DSA_SIG *val_in, unsigned char **der_out);

🌸 DESCRIPTION: what these cuties actually do 🌸

First, the general tea: these functions decode and encode DSA keys and parameters. For the full semantics, examples, caveats, and bugs, go read ASN1_item_d2i(3) — it's the main character for all that.

d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key components using a non-standard format, so bestie, consider using d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() instead. The actual data encoded depends on the value of val_in->write_params. If val_in->write_params is zero, only the val_in->pub_key field is encoded as an ASN.1 INTEGER. If val_in->write_params is 1, then a SEQUENCE consisting of the val_in->p, val_in->q, val_in->g, and val_in->pub_key fields is encoded.

d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode a DSA public key using an ASN.1 SubjectPublicKeyInfo structure defined in RFC 5280 section 4.1 and documented in X509_PUBKEY_new(3). d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), i2d_DSA_PUBKEY_bio(), and i2d_DSA_PUBKEY_fp() are similar except that they decode or encode using a BIO or FILE pointer. Slay.

d2i_DSAPrivateKey() and i2d_DSAPrivateKey() decode and encode the DSA private key components. The DSA object passed to the private key encoding functions should have all the private key components present. These functions use a non-standard structure consisting of a SEQUENCE containing the val_in->p, val_in->q, val_in->g, val_in->pub_key, and val_in->priv_key fields.

🚨 bestie, this data format is unencrypted. For private key security when writing private keys to files, consider using PEM_write_DSAPrivateKey(3) instead.

d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), i2d_DSAPrivateKey_bio(), and i2d_DSAPrivateKey_fp() are similar except that they decode or encode using a BIO or FILE pointer.

d2i_DSAparams() and i2d_DSAparams() decode and encode the DSA parameters using an ASN.1 Dss-Parms structure defined in RFC 3279 section 2.3.2 and used for the parameters field of the ASN.1 AlgorithmIdentifier structure defined in RFC 5280 section 4.1.1.2. d2i_DSAparams_bio(), i2d_DSAparams_bio(), d2i_DSAparams_fp(), i2d_DSAparams_fp() are similar except that they decode or encode using a BIO or FILE pointer.

DSAparams_dup() allocates and initializes an empty DSA object and copies the DSA parameters from val_in to it by calling i2d_DSAparams() and d2i_DSAparams(). If a private or public key are present in val_in, they are not copied. It's giving "parameters only, no key leaking into the dup" 💅.

d2i_DSA_SIG() and i2d_DSA_SIG() decode and encode a DSA signature using an ASN.1 Dss-Sig-Value structure as defined in RFC 3279 section 2.2.2 and used for the signatureValue field of the ASN.1 Certificate structure described in RFC 5280 sections 4.1.1.3 and 5.1.1.3.

🫶 RETURN VALUES: what you get back 🫶

  • d2i_DSAPublicKey(), d2i_DSA_PUBKEY(), d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), d2i_DSAPrivateKey(), d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), d2i_DSAparams(), d2i_DSAparams_bio(), d2i_DSAparams_fp(), and DSAparams_dup() return a valid DSA object or NULL if an error occurs.
  • d2i_DSA_SIG() returns a valid DSA_SIG object or NULL if an error occurs.

🦋 SEE ALSO: go read these next 🦋

🌈 STANDARDS: the official lore 🌈

  • RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, section 4.1: Basic Certificate Fields
  • RFC 3279: Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile:
    • section 2.2.2: DSA Signature Algorithm
    • section 2.3.2: DSA Signature Keys

💖 HISTORY: the origin story 💖

  • d2i_DSAPublicKey(), i2d_DSAPublicKey(), d2i_DSAPrivateKey(), and i2d_DSAPrivateKey() first appeared in SSLeay 0.6.0.
  • d2i_DSAPrivateKey_bio(), d2i_DSAPrivateKey_fp(), i2d_DSAPrivateKey_bio(), i2d_DSAPrivateKey_fp(), d2i_DSAparams(), i2d_DSAparams(), d2i_DSAparams_bio(), i2d_DSAparams_bio(), d2i_DSAparams_fp(), i2d_DSAparams_fp(), and DSAparams_dup() first appeared in SSLeay 0.8.0. These functions have been available since OpenBSD 2.4.
  • d2i_DSA_SIG() and i2d_DSA_SIG() first appeared in OpenSSL 0.9.3 and have been available since OpenBSD 2.6.
  • d2i_DSA_PUBKEY(), i2d_DSA_PUBKEY(), d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), i2d_DSA_PUBKEY_bio(), and i2d_DSA_PUBKEY_fp() first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7.

xoxo, served by Debian on August 26, 2018 — D2I_DSAPUBLICKEY(3) out 💅

📦 where this page comes from