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