xref: /freebsd/crypto/openssl/doc/man3/X509_get0_distinguishing_id.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1*b077aed3SPierre Pronchery=pod
2*b077aed3SPierre Pronchery
3*b077aed3SPierre Pronchery=head1 NAME
4*b077aed3SPierre Pronchery
5*b077aed3SPierre ProncheryX509_get0_distinguishing_id, X509_set0_distinguishing_id,
6*b077aed3SPierre ProncheryX509_REQ_get0_distinguishing_id, X509_REQ_set0_distinguishing_id
7*b077aed3SPierre Pronchery- get or set the Distinguishing ID for certificate operations
8*b077aed3SPierre Pronchery
9*b077aed3SPierre Pronchery=head1 SYNOPSIS
10*b077aed3SPierre Pronchery
11*b077aed3SPierre Pronchery #include <openssl/x509.h>
12*b077aed3SPierre Pronchery
13*b077aed3SPierre Pronchery ASN1_OCTET_STRING *X509_get0_distinguishing_id(X509 *x);
14*b077aed3SPierre Pronchery void X509_set0_distinguishing_id(X509 *x, ASN1_OCTET_STRING *distid);
15*b077aed3SPierre Pronchery ASN1_OCTET_STRING *X509_REQ_get0_distinguishing_id(X509_REQ *x);
16*b077aed3SPierre Pronchery void X509_REQ_set0_distinguishing_id(X509_REQ *x, ASN1_OCTET_STRING *distid);
17*b077aed3SPierre Pronchery
18*b077aed3SPierre Pronchery=head1 DESCRIPTION
19*b077aed3SPierre Pronchery
20*b077aed3SPierre ProncheryThe Distinguishing ID is defined in FIPS 196 as follows:
21*b077aed3SPierre Pronchery
22*b077aed3SPierre Pronchery=over 4
23*b077aed3SPierre Pronchery
24*b077aed3SPierre Pronchery=item I<Distinguishing  identifier>
25*b077aed3SPierre Pronchery
26*b077aed3SPierre ProncheryInformation which unambiguously distinguishes
27*b077aed3SPierre Proncheryan entity in the authentication process.
28*b077aed3SPierre Pronchery
29*b077aed3SPierre Pronchery=back
30*b077aed3SPierre Pronchery
31*b077aed3SPierre ProncheryThe SM2 signature algorithm requires a Distinguishing ID value when generating
32*b077aed3SPierre Proncheryand verifying a signature, but the Ddistinguishing ID may also find other uses.
33*b077aed3SPierre ProncheryIn the context of SM2, the Distinguishing ID is often referred to as the "SM2
34*b077aed3SPierre ProncheryID".
35*b077aed3SPierre Pronchery
36*b077aed3SPierre ProncheryFor the purpose off verifying a certificate or a certification request, a
37*b077aed3SPierre ProncheryDistinguishing ID may be attached to it, so functions like L<X509_verify(3)>
38*b077aed3SPierre Proncheryor L<X509_REQ_verify(3)> have easy access to that identity for signature
39*b077aed3SPierre Proncheryverification.
40*b077aed3SPierre Pronchery
41*b077aed3SPierre ProncheryX509_get0_distinguishing_id() gets the Distinguishing ID value of a certificate
42*b077aed3SPierre ProncheryB<x> by returning an B<ASN1_OCTET_STRING> object which should not be freed by
43*b077aed3SPierre Proncherythe caller.
44*b077aed3SPierre Pronchery
45*b077aed3SPierre ProncheryX509_set0_distinguishing_id() assigns B<distid> to the certificate B<x>.
46*b077aed3SPierre ProncheryCalling this function transfers the memory management of the value to the X509
47*b077aed3SPierre Proncheryobject, and therefore the value that has been passed in should not be freed by
48*b077aed3SPierre Proncherythe caller after this function has been called.
49*b077aed3SPierre Pronchery
50*b077aed3SPierre ProncheryX509_REQ_get0_distinguishing_id() and X509_REQ_set0_distinguishing_id()
51*b077aed3SPierre Proncheryhave the same functionality as X509_get0_distinguishing_id() and
52*b077aed3SPierre ProncheryX509_set0_distinguishing_id() except that they deal with  B<X509_REQ>
53*b077aed3SPierre Proncheryobjects instead of B<X509>.
54*b077aed3SPierre Pronchery
55*b077aed3SPierre Pronchery=head1 RETURN VALUES
56*b077aed3SPierre Pronchery
57*b077aed3SPierre ProncheryX509_set0_distinguishing_id() and X509_REQ_set0_distinguishing_id() do not
58*b077aed3SPierre Proncheryreturn a value.
59*b077aed3SPierre Pronchery
60*b077aed3SPierre Pronchery=head1 SEE ALSO
61*b077aed3SPierre Pronchery
62*b077aed3SPierre ProncheryL<X509_verify(3)>, L<SM2(7)>
63*b077aed3SPierre Pronchery
64*b077aed3SPierre Pronchery=head1 COPYRIGHT
65*b077aed3SPierre Pronchery
66*b077aed3SPierre ProncheryCopyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
67*b077aed3SPierre Pronchery
68*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
69*b077aed3SPierre Proncherythis file except in compliance with the License.  You can obtain a copy
70*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at
71*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>.
72*b077aed3SPierre Pronchery
73*b077aed3SPierre Pronchery=cut
74