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