ossl_cmp_hdr_init.pod 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141
  1. =pod
  2. =head1 NAME
  3. ossl_cmp_hdr_set_pvno,
  4. ossl_cmp_hdr_get_pvno,
  5. ossl_cmp_hdr_get_protection_nid,
  6. ossl_cmp_hdr_get0_sendernonce,
  7. ossl_cmp_general_name_is_NULL_DN,
  8. ossl_cmp_hdr_set1_sender,
  9. ossl_cmp_hdr_set1_recipient,
  10. ossl_cmp_hdr_update_messagetime,
  11. ossl_cmp_hdr_set1_senderKID,
  12. ossl_cmp_hdr_push0_freeText,
  13. ossl_cmp_hdr_push1_freeText,
  14. ossl_cmp_hdr_generalinfo_item_push0,
  15. ossl_cmp_hdr_generalinfo_items_push1,
  16. ossl_cmp_hdr_set_implicitConfirm,
  17. ossl_cmp_hdr_has_implicitConfirm,
  18. ossl_cmp_hdr_init
  19. - functions manipulating CMP message headers
  20. =head1 SYNOPSIS
  21. #include "cmp_local.h"
  22. int ossl_cmp_hdr_set_pvno(OSSL_CMP_PKIHEADER *hdr, int pvno);
  23. int ossl_cmp_hdr_get_pvno(const OSSL_CMP_PKIHEADER *hdr);
  24. int ossl_cmp_hdr_get_protection_nid(const OSSL_CMP_PKIHEADER *hdr);
  25. ASN1_OCTET_STRING
  26. *ossl_cmp_hdr_get0_sendernonce(const OSSL_CMP_PKIHEADER *hdr);
  27. int ossl_cmp_general_name_is_NULL_DN(GENERAL_NAME *name);
  28. int ossl_cmp_hdr_set1_sender(OSSL_CMP_PKIHEADER *hdr, const X509_NAME *nm);
  29. int ossl_cmp_hdr_set1_recipient(OSSL_CMP_PKIHEADER *hdr, const X509_NAME *nm);
  30. int ossl_cmp_hdr_update_messagetime(OSSL_CMP_PKIHEADER *hdr);
  31. int ossl_cmp_hdr_set1_senderKID(OSSL_CMP_PKIHEADER *hdr,
  32. const ASN1_OCTET_STRING *senderKID);
  33. int ossl_cmp_hdr_generalinfo_item_push0(OSSL_CMP_PKIHEADER *hdr,
  34. OSSL_CMP_ITAV *itav);
  35. int ossl_cmp_hdr_generalinfo_items_push1(OSSL_CMP_PKIHEADER *hdr,
  36. STACK_OF(OSSL_CMP_ITAV) *itavs);
  37. int ossl_cmp_hdr_push0_freeText(OSSL_CMP_PKIHEADER *hdr,
  38. ASN1_UTF8STRING *text);
  39. int ossl_cmp_hdr_push1_freeText(OSSL_CMP_PKIHEADER *hdr,
  40. ASN1_UTF8STRING *text);
  41. int ossl_cmp_hdr_set_implicitConfirm(OSSL_CMP_PKIHEADER *hdr);
  42. int ossl_cmp_hdr_has_implicitConfirm(OSSL_CMP_PKIHEADER *hdr);
  43. int ossl_cmp_hdr_init(OSSL_CMP_CTX *ctx, OSSL_CMP_PKIHEADER *hdr);
  44. =head1 DESCRIPTION
  45. ossl_cmp_hdr_set_pvno() sets hdr->pvno to the given B<pvno>.
  46. ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error.
  47. ossl_cmp_hdr_get_protection_nid returns the NID of the protection algorithm
  48. in B<hdr> or NID_undef on error.
  49. ossl_cmp_hdr_get0_sendernonce() returns the sender nonce of the given PKIHeader.
  50. ossl_cmp_general_name_is_NULL_DN() determines if the given GENERAL_NAME
  51. is the NULL-DN.
  52. ossl_cmp_hdr_set1_sender() sets the sender field in the given PKIHeader
  53. to the given X509 Name value, without consuming the pointer.
  54. ossl_cmp_hdr_set1_recipient() sets the recipient field in the given
  55. PKIHeader to the given X509 Name value, without consuming the pointer.
  56. If B<nm> is NULL, recipient is set to the NULL DN (the empty list of strings).
  57. ossl_cmp_hdr_update_messagetime() (re-)sets the messageTime to the current
  58. system time. As written in RFC 4210, section 5.1.1:
  59. The messageTime field contains the time at which the sender created the message.
  60. This may be useful to allow end entities to correct/check their local time for
  61. consistency with the time on a central system.
  62. ossl_cmp_hdr_set1_senderKID() Sets hdr->senderKID to the given string.
  63. In an PBMAC-protected IR this usually is a reference number issued by the CA,
  64. else the subject key ID of the sender's protecting certificate.
  65. ossl_cmp_hdr_push0_freeText() pushes an ASN1_UTF8STRING to
  66. hdr->freeText and consumes the given pointer.
  67. ossl_cmp_hdr_push1_freeText() pushes an ASN1_UTF8STRING to
  68. hdr->freeText and does not consume the pointer.
  69. ossl_cmp_hdr_generalinfo_item_push0() adds the given InfoTypeAndValue
  70. item to the hdr->generalInfo stack. Consumes the B<itav> pointer.
  71. ossl_cmp_hdr_generalinfo_items_push1() adds a copy of the B<itavs> stack to
  72. the generalInfo field of PKIheader of the B<hdr>. Does not consume the B<itavs>
  73. pointer.
  74. ossl_cmp_hdr_set_implicitConfirm() sets implicitConfirm in the generalInfo field
  75. of the PKIMessage header.
  76. ossl_cmp_hdr_has_implicitConfirm() returns 1 if implicitConfirm is
  77. set int generalInfo field of the given PKIMessage header, 0 if not.
  78. ossl_cmp_hdr_init() initializes a PKIHeader structure based on the
  79. values in the given OSSL_CMP_CTX structure.
  80. This starts a new transaction in case ctx->transactionID is NULL.
  81. The sender name is copied from the subject of the client cert, if any,
  82. or else from the subject name provided for certification requests.
  83. As required by RFC 4210 section 5.1.1., if the sender name is not known
  84. to the client it set to the NULL-DN. In this case for identification at least
  85. the senderKID must be set, which we take from any referenceValue provided.
  86. =head1 NOTES
  87. CMP is defined in RFC 4210 (and CRMF in RFC 4211).
  88. =head1 RETURN VALUES
  89. ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error.
  90. ossl_cmp_hdr_get_protection_nid returns the respective NID, NID_undef on error.
  91. ossl_cmp_hdr_get0_sendernonce() returns the respective nonce, or NULL.
  92. ossl_cmp_general_name_is_NULL_DN() returns 1 given a NULL-DN, else 0.
  93. All other functions return 1 on success, 0 on error.
  94. See the individual functions above.
  95. =head1 HISTORY
  96. The OpenSSL CMP support was added in OpenSSL 3.0.
  97. =head1 COPYRIGHT
  98. Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved.
  99. Licensed under the Apache License 2.0 (the "License"). You may not use
  100. this file except in compliance with the License. You can obtain a copy
  101. in the file LICENSE in the source distribution or at
  102. L<https://www.openssl.org/source/license.html>.
  103. =cut