crypto/heimdal/doc/doxyout/hx509/man/man3/hx509_cms.3

   1 .TH "hx509 CMS/pkcs7 functions" 3 "11 Jan 2012" "Version 1.5.2" "Heimdalx509library" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 hx509 CMS/pkcs7 functions \-
   6 .SS "Functions"
   7
   8 .in +1c
   9 .ti -1c
  10 .RI "int \fBhx509_cms_wrap_ContentInfo\fP (const heim_oid *oid, const heim_octet_string *buf, heim_octet_string *res)"
  11 .br
  12 .ti -1c
  13 .RI "int \fBhx509_cms_unwrap_ContentInfo\fP (const heim_octet_string *in, heim_oid *oid, heim_octet_string *out, int *have_data)"
  14 .br
  15 .ti -1c
  16 .RI "int \fBhx509_cms_unenvelope\fP (hx509_context context, hx509_certs certs, int flags, const void *data, size_t length, const heim_octet_string *encryptedContent, time_t time_now, heim_oid *contentType, heim_octet_string *content)"
  17 .br
  18 .ti -1c
  19 .RI "int \fBhx509_cms_envelope_1\fP (hx509_context context, int flags, hx509_cert cert, const void *data, size_t length, const heim_oid *encryption_type, const heim_oid *contentType, heim_octet_string *content)"
  20 .br
  21 .ti -1c
  22 .RI "int \fBhx509_cms_verify_signed\fP (hx509_context context, hx509_verify_ctx ctx, unsigned int flags, const void *data, size_t length, const heim_octet_string *signedContent, hx509_certs pool, heim_oid *contentType, heim_octet_string *content, hx509_certs *signer_certs)"
  23 .br
  24 .ti -1c
  25 .RI "int \fBhx509_cms_create_signed_1\fP (hx509_context context, int flags, const heim_oid *eContentType, const void *data, size_t length, const AlgorithmIdentifier *digest_alg, hx509_cert cert, hx509_peer_info peer, hx509_certs anchors, hx509_certs pool, heim_octet_string *signed_data)"
  26 .br
  27 .in -1c
  28 .SH "Detailed Description"
  29 .PP
  30 See the \fBCMS/PKCS7 message functions.\fP for description and examples.
  31 .SH "Function Documentation"
  32 .PP
  33 .SS "int hx509_cms_create_signed_1 (hx509_context context, int flags, const heim_oid * eContentType, const void * data, size_t length, const AlgorithmIdentifier * digest_alg, hx509_cert cert, hx509_peer_info peer, hx509_certs anchors, hx509_certs pool, heim_octet_string * signed_data)"
  34 .PP
  35 Decode SignedData and verify that the signature is correct.
  36 .PP
  37 \fBParameters:\fP
  38 .RS 4
  39 \fIcontext\fP A hx509 context.
  40 .br
  41 \fIflags\fP
  42 .br
  43 \fIeContentType\fP the type of the data.
  44 .br
  45 \fIdata\fP data to sign
  46 .br
  47 \fIlength\fP length of the data that data point to.
  48 .br
  49 \fIdigest_alg\fP digest algorithm to use, use NULL to get the default or the peer determined algorithm.
  50 .br
  51 \fIcert\fP certificate to use for sign the data.
  52 .br
  53 \fIpeer\fP info about the peer the message to send the message to, like what digest algorithm to use.
  54 .br
  55 \fIanchors\fP trust anchors that the client will use, used to polulate the certificates included in the message
  56 .br
  57 \fIpool\fP certificates to use in try to build the path to the trust anchors.
  58 .br
  59 \fIsigned_data\fP the output of the function, free with der_free_octet_string().
  60 .RE
  61 .PP
  62
  63 .SS "int hx509_cms_envelope_1 (hx509_context context, int flags, hx509_cert cert, const void * data, size_t length, const heim_oid * encryption_type, const heim_oid * contentType, heim_octet_string * content)"
  64 .PP
  65 Encrypt end encode EnvelopedData.
  66 .PP
  67 Encrypt and encode EnvelopedData. The data is encrypted with a random key and the the random key is encrypted with the certificates private key. This limits what private key type can be used to RSA.
  68 .PP
  69 \fBParameters:\fP
  70 .RS 4
  71 \fIcontext\fP A hx509 context.
  72 .br
  73 \fIflags\fP flags to control the behavior.
  74 .IP "\(bu" 2
  75 HX509_CMS_EV_NO_KU_CHECK - Dont check KU on certificate
  76 .IP "\(bu" 2
  77 HX509_CMS_EV_ALLOW_WEAK - Allow weak crytpo
  78 .IP "\(bu" 2
  79 HX509_CMS_EV_ID_NAME - prefer issuer name and serial number
  80 .PP
  81 .br
  82 \fIcert\fP Certificate to encrypt the EnvelopedData encryption key with.
  83 .br
  84 \fIdata\fP pointer the data to encrypt.
  85 .br
  86 \fIlength\fP length of the data that data point to.
  87 .br
  88 \fIencryption_type\fP Encryption cipher to use for the bulk data, use NULL to get default.
  89 .br
  90 \fIcontentType\fP type of the data that is encrypted
  91 .br
  92 \fIcontent\fP the output of the function, free with der_free_octet_string().
  93 .RE
  94 .PP
  95
  96 .SS "int hx509_cms_unenvelope (hx509_context context, hx509_certs certs, int flags, const void * data, size_t length, const heim_octet_string * encryptedContent, time_t time_now, heim_oid * contentType, heim_octet_string * content)"
  97 .PP
  98 Decode and unencrypt EnvelopedData.
  99 .PP
 100 Extract data and parameteres from from the EnvelopedData. Also supports using detached EnvelopedData.
 101 .PP
 102 \fBParameters:\fP
 103 .RS 4
 104 \fIcontext\fP A hx509 context.
 105 .br
 106 \fIcerts\fP Certificate that can decrypt the EnvelopedData encryption key.
 107 .br
 108 \fIflags\fP HX509_CMS_UE flags to control the behavior.
 109 .br
 110 \fIdata\fP pointer the structure the contains the DER/BER encoded EnvelopedData stucture.
 111 .br
 112 \fIlength\fP length of the data that data point to.
 113 .br
 114 \fIencryptedContent\fP in case of detached signature, this contains the actual encrypted data, othersize its should be NULL.
 115 .br
 116 \fItime_now\fP set the current time, if zero the library uses now as the date.
 117 .br
 118 \fIcontentType\fP output type oid, should be freed with der_free_oid().
 119 .br
 120 \fIcontent\fP the data, free with der_free_octet_string().
 121 .RE
 122 .PP
 123
 124 .SS "int hx509_cms_unwrap_ContentInfo (const heim_octet_string * in, heim_oid * oid, heim_octet_string * out, int * have_data)"
 125 .PP
 126 Decode an ContentInfo and unwrap data and oid it.
 127 .PP
 128 \fBParameters:\fP
 129 .RS 4
 130 \fIin\fP the encoded buffer.
 131 .br
 132 \fIoid\fP type of the content.
 133 .br
 134 \fIout\fP data to be wrapped.
 135 .br
 136 \fIhave_data\fP since the data is optional, this flags show dthe diffrence between no data and the zero length data.
 137 .RE
 138 .PP
 139 \fBReturns:\fP
 140 .RS 4
 141 Returns an hx509 error code.
 142 .RE
 143 .PP
 144
 145 .SS "int hx509_cms_verify_signed (hx509_context context, hx509_verify_ctx ctx, unsigned int flags, const void * data, size_t length, const heim_octet_string * signedContent, hx509_certs pool, heim_oid * contentType, heim_octet_string * content, hx509_certs * signer_certs)"
 146 .PP
 147 Decode SignedData and verify that the signature is correct.
 148 .PP
 149 \fBParameters:\fP
 150 .RS 4
 151 \fIcontext\fP A hx509 context.
 152 .br
 153 \fIctx\fP a hx509 verify context.
 154 .br
 155 \fIflags\fP to control the behaivor of the function.
 156 .IP "\(bu" 2
 157 HX509_CMS_VS_NO_KU_CHECK - Don't check KeyUsage
 158 .IP "\(bu" 2
 159 HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH - allow oid mismatch
 160 .IP "\(bu" 2
 161 HX509_CMS_VS_ALLOW_ZERO_SIGNER - no signer, see below.
 162 .PP
 163 .br
 164 \fIdata\fP pointer to CMS SignedData encoded data.
 165 .br
 166 \fIlength\fP length of the data that data point to.
 167 .br
 168 \fIsignedContent\fP external data used for signature.
 169 .br
 170 \fIpool\fP certificate pool to build certificates paths.
 171 .br
 172 \fIcontentType\fP free with der_free_oid().
 173 .br
 174 \fIcontent\fP the output of the function, free with der_free_octet_string().
 175 .br
 176 \fIsigner_certs\fP list of the cerficates used to sign this request, free with \fBhx509_certs_free()\fP.
 177 .RE
 178 .PP
 179
 180 .PP
 181 If HX509_CMS_VS_NO_KU_CHECK is set, allow more liberal search for matching certificates by not considering KeyUsage bits on the certificates.
 182 .PP
 183 If HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH, allow encapContentInfo mismatch with the oid in signedAttributes (or if no signedAttributes where use, pkcs7-data oid). This is only needed to work with broken CMS implementations that doesn't follow CMS signedAttributes rules.
 184 .PP
 185 If HX509_CMS_VS_NO_VALIDATE flags is set, do not verify the signing certificates and leave that up to the caller.
 186 .PP
 187 If HX509_CMS_VS_ALLOW_ZERO_SIGNER is set, allow empty SignerInfo (no signatures). If SignedData have no signatures, the function will return 0 with signer_certs set to NULL. Zero signers is allowed by the standard, but since its only useful in corner cases, it make into a flag that the caller have to turn on.
 188 .SS "int hx509_cms_wrap_ContentInfo (const heim_oid * oid, const heim_octet_string * buf, heim_octet_string * res)"
 189 .PP
 190 Wrap data and oid in a ContentInfo and encode it.
 191 .PP
 192 \fBParameters:\fP
 193 .RS 4
 194 \fIoid\fP type of the content.
 195 .br
 196 \fIbuf\fP data to be wrapped. If a NULL pointer is passed in, the optional content field in the ContentInfo is not going be filled in.
 197 .br
 198 \fIres\fP the encoded buffer, the result should be freed with der_free_octet_string().
 199 .RE
 200 .PP
 201 \fBReturns:\fP
 202 .RS 4
 203 Returns an hx509 error code.
 204 .RE
 205 .PP
 206