1<refentry id="refcert">
2
3  <refmeta>
4    <refentrytitle>ne_ssl_cert_identity</refentrytitle>
5    <manvolnum>3</manvolnum>
6  </refmeta>
7
8  <refnamediv>
9    <refname id="ne_ssl_cert_identity">ne_ssl_cert_identity</refname>
10    <refname id="ne_ssl_cert_signedby">ne_ssl_cert_signedby</refname>
11    <refname id="ne_ssl_cert_issuer">ne_ssl_cert_issuer</refname>
12    <refname id="ne_ssl_cert_subject">ne_ssl_cert_subject</refname>
13    <refpurpose>functions to access certificate properties</refpurpose>
14  </refnamediv>
15  
16  <refsynopsisdiv>
17
18    <funcsynopsis>
19
20      <funcsynopsisinfo>#include &lt;ne_ssl.h&gt;</funcsynopsisinfo>
21
22      <funcprototype>
23        <funcdef>const char *<function>ne_ssl_cert_identity</function></funcdef>
24        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
25      </funcprototype>
26
27      <funcprototype>
28        <funcdef>const ne_ssl_certificate *<function>ne_ssl_cert_signedby</function></funcdef>
29        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
30      </funcprototype>
31
32      <funcprototype>
33        <funcdef>const ne_ssl_dname *<function>ne_ssl_cert_subject</function></funcdef>
34        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
35      </funcprototype>
36
37      <funcprototype>
38        <funcdef>const ne_ssl_dname *<function>ne_ssl_cert_issuer</function></funcdef>
39        <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
40      </funcprototype>
41
42    </funcsynopsis>
43
44  </refsynopsisdiv>
45
46  <refsect1>
47    <title>Description</title>
48
49    <para>The function <function>ne_ssl_cert_identity</function>
50    retrieves the <quote>identity</quote> of a certificate; for an
51    SSL server certificate, this will be the hostname for which the
52    certificate was issued.  In PKI parlance, the identity is the
53    <emphasis>common name</emphasis> attribute of the distinguished name of
54    the certificate subject.</para>
55
56    <para>The functions <function>ne_ssl_cert_subject</function> and
57    <function>ne_ssl_cert_issuer</function> can be used to access the
58    objects representing the distinguished name of the subject and of
59    the issuer of a certificate, respectively.</para>
60
61    <para>If a certificate object is part of a certificate chain, then
62    <function>ne_ssl_cert_signedby</function> can be used to find the
63    certificate which signed a particular certificate. For a
64    self-signed certificate or a certificate for which the full chain
65    is not available, this function will return &null;.</para>
66
67  </refsect1>
68
69  <refsect1>
70    <title>Return value</title>
71
72    <para><function>ne_ssl_cert_issuer</function> and
73    <function>ne_ssl_cert_subject</function> are guaranteed to never
74    return &null;. <function>ne_ssl_cert_identity</function> may
75    return &null; if the certificate has no specific
76    <quote>identity</quote>. <function>ne_ssl_cert_signedby</function>
77    may return &null; as covered above.</para>
78  </refsect1>
79
80  <refsect1>
81    <title>Examples</title>
82
83    <para>The following function could be used to display information
84    about a given certificate:</para>
85
86    <programlisting>void dump_cert(const ne_ssl_certificate *cert) {
87  const char *id = ne_ssl_cert_identity(cert);
88  char *dn;
89
90  if (id) 
91    printf("Certificate was issued for '%s'.\n", id);
92
93  dn = ne_ssl_readable_dname(ne_ssl_cert_subject(cert));
94  printf("Subject: %s\n", dn);
95  free(dn);
96
97  dn = ne_ssl_readable_dname(ne_ssl_cert_issuer(cert));
98  printf("Issuer: %s\n", dn);
99  free(dn);
100}</programlisting>
101
102  </refsect1>
103
104  <refsect1>
105    <title>See also</title>
106
107    <para><xref linkend="ne_ssl_cert_cmp"/>, <xref linkend="ne_ssl_readable_dname"/></para>
108  </refsect1>
109
110</refentry>
111
112