winscp/libs/neon/doc/ref/sslcert.xml

<refentry id="refcert">

  <refmeta>
    <refentrytitle>ne_ssl_cert_identity</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname id="ne_ssl_cert_identity">ne_ssl_cert_identity</refname>
    <refname id="ne_ssl_cert_signedby">ne_ssl_cert_signedby</refname>
    <refname id="ne_ssl_cert_issuer">ne_ssl_cert_issuer</refname>
    <refname id="ne_ssl_cert_subject">ne_ssl_cert_subject</refname>
    <refpurpose>functions to access certificate properties</refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>

    <funcsynopsis>

      <funcsynopsisinfo>#include &lt;ne_ssl.h&gt;</funcsynopsisinfo>

      <funcprototype>
        <funcdef>const char *<function>ne_ssl_cert_identity</function></funcdef>
        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>const ne_ssl_certificate *<function>ne_ssl_cert_signedby</function></funcdef>
        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>const ne_ssl_dname *<function>ne_ssl_cert_subject</function></funcdef>
        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>const ne_ssl_dname *<function>ne_ssl_cert_issuer</function></funcdef>
        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
      </funcprototype>

    </funcsynopsis>

  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>The function <function>ne_ssl_cert_identity</function>
    retrieves the <quote>identity</quote> of a certificate; for an
    SSL server certificate, this will be the hostname for which the
    certificate was issued.  In PKI parlance, the identity is the
    <emphasis>common name</emphasis> attribute of the distinguished name of
    the certificate subject.</para>

    <para>The functions <function>ne_ssl_cert_subject</function> and
    <function>ne_ssl_cert_issuer</function> can be used to access the
    objects representing the distinguished name of the subject and of
    the issuer of a certificate, respectively.</para>

    <para>If a certificate object is part of a certificate chain, then
    <function>ne_ssl_cert_signedby</function> can be used to find the
    certificate which signed a particular certificate. For a
    self-signed certificate or a certificate for which the full chain
    is not available, this function will return &null;.</para>

  </refsect1>

  <refsect1>
    <title>Return value</title>

    <para><function>ne_ssl_cert_issuer</function> and
    <function>ne_ssl_cert_subject</function> are guaranteed to never
    return &null;. <function>ne_ssl_cert_identity</function> may
    return &null; if the certificate has no specific
    <quote>identity</quote>. <function>ne_ssl_cert_signedby</function>
    may return &null; as covered above.</para>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <para>The following function could be used to display information
    about a given certificate:</para>

    <programlisting>void dump_cert(const ne_ssl_certificate *cert) {
  const char *id = ne_ssl_cert_identity(cert);
  char *dn;

  if (id) 
    printf("Certificate was issued for '%s'.\n", id);

  dn = ne_ssl_readable_dname(ne_ssl_cert_subject(cert));
  printf("Subject: %s\n", dn);
  free(dn);

  dn = ne_ssl_readable_dname(ne_ssl_cert_issuer(cert));
  printf("Issuer: %s\n", dn);
  free(dn);
}</programlisting>

  </refsect1>

  <refsect1>
    <title>See also</title>

    <para><xref linkend="ne_ssl_cert_cmp"/>, <xref linkend="ne_ssl_readable_dname"/></para>
  </refsect1>

</refentry>