asn_public.h 79 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314
  1. /*!
  2. \ingroup ASN
  3. \brief This function initializes a default cert, with the default options:
  4. version = 3 (0x2), serial = 0, sigType = SHA_WITH_RSA, issuer = blank,
  5. daysValid = 500, selfSigned = 1 (true) use subject as issuer,
  6. subject = blank
  7. \return none No returns.
  8. \param cert pointer to an uninitialized cert structure to initialize
  9. _Example_
  10. \code
  11. Cert myCert;
  12. wc_InitCert(&myCert);
  13. \endcode
  14. \sa wc_MakeCert
  15. \sa wc_MakeCertReq
  16. */
  17. int wc_InitCert(Cert*);
  18. /*!
  19. \ingroup ASN
  20. \brief This function allocates a new Cert structure for use during
  21. cert operations without the application having to allocate the structure
  22. itself. The Cert structure is also initialized by this function thus
  23. removing the need to call wc_InitCert(). When the application is finished
  24. using the allocated Cert structure wc_CertFree() must be called.
  25. \return pointer If successful the call will return a pointer to the
  26. newly allocated and initialized Cert.
  27. \return NULL On a memory allocation failure.
  28. \param A pointer to the heap used for dynamic allocation. Can be NULL.
  29. _Example_
  30. \code
  31. Cert* myCert;
  32. myCert = wc_CertNew(NULL);
  33. if (myCert == NULL) {
  34. // Cert creation failure
  35. }
  36. \endcode
  37. \sa wc_InitCert
  38. \sa wc_MakeCert
  39. \sa wc_CertFree
  40. */
  41. Cert* wc_CertNew(void* heap);
  42. /*!
  43. \ingroup ASN
  44. \brief This function frees the memory allocated for a cert structure
  45. by a previous call to wc_CertNew().
  46. \return None.
  47. \param A pointer to the cert structure to free.
  48. _Example_
  49. \code
  50. Cert* myCert;
  51. myCert = wc_CertNew(NULL);
  52. // Perform cert operations.
  53. wc_CertFree(myCert);
  54. \endcode
  55. \sa wc_InitCert
  56. \sa wc_MakeCert
  57. \sa wc_CertNew
  58. */
  59. void wc_CertFree(Cert* cert);
  60. /*!
  61. \ingroup ASN
  62. \brief Used to make CA signed certs. Called after the subject information
  63. has been entered. This function makes an x509 Certificate v3 RSA or ECC
  64. from a cert input. It then writes this cert to derBuffer. It takes in
  65. either an rsaKey or an eccKey to generate the certificate. The certificate
  66. must be initialized with wc_InitCert before this method is called.
  67. \return Success On successfully making an x509 certificate from the
  68. specified input cert, returns the size of the cert generated.
  69. \return MEMORY_E Returned if there is an error allocating memory
  70. with XMALLOC
  71. \return BUFFER_E Returned if the provided derBuffer is too small to
  72. store the generated certificate
  73. \return Others Additional error messages may be returned if the cert
  74. generation is not successful.
  75. \param cert pointer to an initialized cert structure
  76. \param derBuffer pointer to the buffer in which to hold the generated cert
  77. \param derSz size of the buffer in which to store the cert
  78. \param rsaKey pointer to an RsaKey structure containing the rsa key used
  79. to generate the certificate
  80. \param eccKey pointer to an EccKey structure containing the ecc key used
  81. to generate the certificate
  82. \param rng pointer to the random number generator used to make the cert
  83. _Example_
  84. \code
  85. Cert myCert;
  86. wc_InitCert(&myCert);
  87. WC_RNG rng;
  88. //initialize rng;
  89. RsaKey key;
  90. //initialize key;
  91. byte * derCert = malloc(FOURK_BUF);
  92. word32 certSz;
  93. certSz = wc_MakeCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
  94. \endcode
  95. \sa wc_InitCert
  96. \sa wc_MakeCertReq
  97. */
  98. int wc_MakeCert(Cert* cert, byte* derBuffer, word32 derSz, RsaKey* rsaKey,
  99. ecc_key* eccKey, WC_RNG* rng);
  100. /*!
  101. \ingroup ASN
  102. \brief This function makes a certificate signing request using the input
  103. certificate and writes the output to derBuffer. It takes in either an
  104. rsaKey or an eccKey to generate the certificate request. wc_SignCert()
  105. will need to be called after this function to sign the certificate request.
  106. Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an
  107. example usage of this function.
  108. \return Success On successfully making an X.509 certificate request from
  109. the specified input cert, returns the size of the certificate
  110. request generated.
  111. \return MEMORY_E Returned if there is an error allocating memory
  112. with XMALLOC
  113. \return BUFFER_E Returned if the provided derBuffer is too small to store
  114. the generated certificate
  115. \return Other Additional error messages may be returned if the certificate
  116. request generation is not successful.
  117. \param cert pointer to an initialized cert structure
  118. \param derBuffer pointer to the buffer in which to hold the generated
  119. certificate request
  120. \param derSz size of the buffer in which to store the certificate request
  121. \param rsaKey pointer to an RsaKey structure containing the rsa key used
  122. to generate the certificate request
  123. \param eccKey pointer to an EccKey structure containing the ecc key used
  124. to generate the certificate request
  125. _Example_
  126. \code
  127. Cert myCert;
  128. // initialize myCert
  129. EccKey key;
  130. //initialize key;
  131. byte* derCert = (byte*)malloc(FOURK_BUF);
  132. word32 certSz;
  133. certSz = wc_MakeCertReq(&myCert, derCert, FOURK_BUF, NULL, &key);
  134. \endcode
  135. \sa wc_InitCert
  136. \sa wc_MakeCert
  137. */
  138. int wc_MakeCertReq(Cert* cert, byte* derBuffer, word32 derSz,
  139. RsaKey* rsaKey, ecc_key* eccKey);
  140. /*!
  141. \ingroup ASN
  142. \brief This function signs buffer and adds the signature to the end of
  143. buffer. It takes in a signature type. Must be called after wc_MakeCert()
  144. or wc_MakeCertReq() if creating a CA signed cert.
  145. \return Success On successfully signing the certificate, returns the new
  146. size of the cert (including signature).
  147. \return MEMORY_E Returned if there is an error allocating
  148. memory with XMALLOC
  149. \return BUFFER_E Returned if the provided buffer is too small to store
  150. the generated certificate
  151. \return Other Additional error messages may be returned if the cert
  152. generation is not successful.
  153. \param requestSz the size of the certificate body we’re requesting
  154. to have signed
  155. \param sType Type of signature to create. Valid options are: CTC_MD5wRSA,
  156. CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, and CTC_SHA256wRSA
  157. \param buffer pointer to the buffer containing the certificate to be
  158. signed. On success: will hold the newly signed certificate
  159. \param buffSz the (total) size of the buffer in which to store the newly
  160. signed certificate
  161. \param rsaKey pointer to an RsaKey structure containing the rsa key
  162. to used to sign the certificate
  163. \param eccKey pointer to an EccKey structure containing the ecc key
  164. to used to sign the certificate
  165. \param rng pointer to the random number generator used to sign
  166. the certificate
  167. _Example_
  168. \code
  169. Cert myCert;
  170. byte* derCert = (byte*)malloc(FOURK_BUF);
  171. // initialize myCert, derCert
  172. RsaKey key;
  173. // initialize key;
  174. WC_RNG rng;
  175. // initialize rng
  176. word32 certSz;
  177. certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF,
  178. &key, NULL,
  179. &rng);
  180. \endcode
  181. \sa wc_InitCert
  182. \sa wc_MakeCert
  183. */
  184. int wc_SignCert(int requestSz, int sigType, byte* derBuffer,
  185. word32 derSz, RsaKey* rsaKey, ecc_key* eccKey, WC_RNG* rng);
  186. /*!
  187. \ingroup ASN
  188. \brief This function is a combination of the previous two functions,
  189. wc_MakeCert and wc_SignCert for self signing (the previous functions may
  190. be used for CA requests). It makes a certificate, and then signs it,
  191. generating a self-signed certificate.
  192. \return Success On successfully signing the certificate, returns the
  193. new size of the cert.
  194. \return MEMORY_E Returned if there is an error allocating memory
  195. with XMALLOC
  196. \return BUFFER_E Returned if the provided buffer is too small to store
  197. the generated certificate
  198. \return Other Additional error messages may be returned if the cert
  199. generation is not successful.
  200. \param cert pointer to the cert to make and sign
  201. \param buffer pointer to the buffer in which to hold the signed certificate
  202. \param buffSz size of the buffer in which to store the signed certificate
  203. \param key pointer to an RsaKey structure containing the rsa key to
  204. used to sign the certificate
  205. \param rng pointer to the random number generator used to generate
  206. and sign the certificate
  207. _Example_
  208. \code
  209. Cert myCert;
  210. byte* derCert = (byte*)malloc(FOURK_BUF);
  211. // initialize myCert, derCert
  212. RsaKey key;
  213. // initialize key;
  214. WC_RNG rng;
  215. // initialize rng
  216. word32 certSz;
  217. certSz = wc_MakeSelfCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
  218. \endcode
  219. \sa wc_InitCert
  220. \sa wc_MakeCert
  221. \sa wc_SignCert
  222. */
  223. int wc_MakeSelfCert(Cert* cert, byte* derBuffer, word32 derSz, RsaKey* key,
  224. WC_RNG* rng);
  225. /*!
  226. \ingroup ASN
  227. \brief This function sets the issuer for a certificate to the issuer
  228. in the provided pem issuerFile. It also changes the certificate’s
  229. self-signed attribute to false. The issuer specified in issuerFile is
  230. verified prior to setting the cert issuer. This method is used to set
  231. fields prior to signing.
  232. \return 0 Returned on successfully setting the issuer for the certificate
  233. \return MEMORY_E Returned if there is an error allocating memory
  234. with XMALLOC
  235. \return ASN_PARSE_E Returned if there is an error parsing the
  236. cert header file
  237. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  238. encryption type from the cert
  239. \return ASN_EXPECT_0_E Returned if there is a formatting error in
  240. the encryption specification of the cert file
  241. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  242. start date
  243. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  244. expiration date
  245. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  246. from the certificate
  247. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  248. from the certificate
  249. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  250. key object id
  251. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  252. defined and the certificate is a V1 or V2 certificate
  253. \return BAD_FUNC_ARG Returned if there is an error processing the
  254. certificate extension
  255. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  256. encountered in processing the certificate
  257. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  258. the same as the encryption type of the certificate in the provided file
  259. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  260. signature fails
  261. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  262. permitted by the CA name constraints
  263. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
  264. the certificate’s authenticity
  265. \param cert pointer to the cert for which to set the issuer
  266. \param issuerFile path of the file containing the pem formatted certificate
  267. _Example_
  268. \code
  269. Cert myCert;
  270. // initialize myCert
  271. if(wc_SetIssuer(&myCert, ”./path/to/ca-cert.pem”) != 0) {
  272. // error setting issuer
  273. }
  274. \endcode
  275. \sa wc_InitCert
  276. \sa wc_SetSubject
  277. \sa wc_SetIssuerBuffer
  278. */
  279. int wc_SetIssuer(Cert* cert, const char* issuerFile);
  280. /*!
  281. \ingroup ASN
  282. \brief This function sets the subject for a certificate to the subject
  283. in the provided pem subjectFile. This method is used to set fields prior
  284. to signing.
  285. \return 0 Returned on successfully setting the issuer for the certificate
  286. \return MEMORY_E Returned if there is an error allocating memory with XMALLOC
  287. \return ASN_PARSE_E Returned if there is an error parsing the cert
  288. header file
  289. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  290. encryption type from the cert
  291. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  292. encryption specification of the cert file
  293. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  294. start date
  295. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  296. expiration date
  297. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  298. from the certificate
  299. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  300. from the certificate
  301. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  302. key object id
  303. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  304. defined and the certificate is a V1 or V2 certificate
  305. \return BAD_FUNC_ARG Returned if there is an error processing the
  306. certificate extension
  307. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  308. encountered in processing the certificate
  309. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  310. the same as the encryption type of the certificate in the provided file
  311. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  312. signature fails
  313. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  314. permitted by the CA name constraints
  315. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  316. certificate’s authenticity
  317. \param cert pointer to the cert for which to set the issuer
  318. \param subjectFile path of the file containing the pem formatted certificate
  319. _Example_
  320. \code
  321. Cert myCert;
  322. // initialize myCert
  323. if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
  324. // error setting subject
  325. }
  326. \endcode
  327. \sa wc_InitCert
  328. \sa wc_SetIssuer
  329. */
  330. int wc_SetSubject(Cert* cert, const char* subjectFile);
  331. /*!
  332. \ingroup ASN
  333. \brief This function sets the raw subject for a certificate from the
  334. subject in the provided der buffer. This method is used to set the raw
  335. subject field prior to signing.
  336. \return 0 Returned on successfully setting the subject for the certificate
  337. \return MEMORY_E Returned if there is an error allocating memory
  338. with XMALLOC
  339. \return ASN_PARSE_E Returned if there is an error parsing the cert
  340. header file
  341. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  342. encryption type from the cert
  343. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  344. encryption specification of the cert file
  345. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  346. start date
  347. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  348. expiration date
  349. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  350. from the certificate
  351. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  352. from the certificate
  353. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  354. key object id
  355. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  356. defined and the certificate is a V1 or V2 certificate
  357. \return BAD_FUNC_ARG Returned if there is an error processing the
  358. certificate extension
  359. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  360. encountered in processing the certificate
  361. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  362. the same as the encryption type of the certificate in the provided file
  363. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  364. signature fails
  365. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  366. permitted by the CA name constraints
  367. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  368. certificate’s authenticity
  369. \param cert pointer to the cert for which to set the raw subject
  370. \param der pointer to the buffer containing the der formatted certificate
  371. from which to grab the subject
  372. \param derSz size of the buffer containing the der formatted certificate
  373. from which to grab the subject
  374. _Example_
  375. \code
  376. Cert myCert;
  377. // initialize myCert
  378. byte* der;
  379. der = (byte*)malloc(FOURK_BUF);
  380. // initialize der
  381. if(wc_SetSubjectRaw(&myCert, der, FOURK_BUF) != 0) {
  382. // error setting subject
  383. }
  384. \endcode
  385. \sa wc_InitCert
  386. \sa wc_SetSubject
  387. */
  388. int wc_SetSubjectRaw(Cert* cert, const byte* der, int derSz);
  389. /*!
  390. \ingroup ASN
  391. \brief This function gets the raw subject from the certificate structure.
  392. \return 0 Returned on successfully getting the subject from the certificate
  393. \return BAD_FUNC_ARG Returned if there is an error processing the
  394. certificate extension
  395. \param subjectRaw pointer-pointer to the raw subject upon successful return
  396. \param cert pointer to the cert from which to get the raw subject
  397. _Example_
  398. \code
  399. Cert myCert;
  400. byte *subjRaw;
  401. // initialize myCert
  402. if(wc_GetSubjectRaw(&subjRaw, &myCert) != 0) {
  403. // error setting subject
  404. }
  405. \endcode
  406. \sa wc_InitCert
  407. \sa wc_SetSubjectRaw
  408. */
  409. int wc_GetSubjectRaw(byte **subjectRaw, Cert *cert);
  410. /*!
  411. \ingroup ASN
  412. \brief This function sets the alternate names for a certificate to the
  413. alternate names in the provided pem file. This is useful in the case that
  414. one wishes to secure multiple domains with the same certificate. This
  415. method is used to set fields prior to signing.
  416. \return 0 Returned on successfully setting the alt names for the certificate
  417. \return MEMORY_E Returned if there is an error allocating memory
  418. with XMALLOC
  419. \return ASN_PARSE_E Returned if there is an error parsing the cert
  420. header file
  421. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  422. encryption type from the cert
  423. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  424. encryption specification of the cert file
  425. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  426. start date
  427. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  428. expiration date
  429. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  430. from the certificate
  431. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  432. from the certificate
  433. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  434. key object id
  435. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  436. defined and the certificate is a V1 or V2 certificate
  437. \return BAD_FUNC_ARG Returned if there is an error processing the
  438. certificate extension
  439. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  440. encountered in processing the certificate
  441. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  442. the same as the encryption type of the certificate in the provided file
  443. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  444. signature fails
  445. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  446. permitted by the CA name constraints
  447. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  448. certificate’s authenticity
  449. \param cert pointer to the cert for which to set the alt names
  450. \param file path of the file containing the pem formatted certificate
  451. _Example_
  452. \code
  453. Cert myCert;
  454. // initialize myCert
  455. if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
  456. // error setting alt names
  457. }
  458. \endcode
  459. \sa wc_InitCert
  460. \sa wc_SetIssuer
  461. */
  462. int wc_SetAltNames(Cert* cert, const char* file);
  463. /*!
  464. \ingroup ASN
  465. \brief This function sets the issuer for a certificate from the issuer in
  466. the provided der buffer. It also changes the certificate’s self-signed
  467. attribute to false. This method is used to set fields prior to signing.
  468. \return 0 Returned on successfully setting the issuer for the certificate
  469. \return MEMORY_E Returned if there is an error allocating memory
  470. with XMALLOC
  471. \return ASN_PARSE_E Returned if there is an error parsing the cert
  472. header file
  473. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  474. encryption type from the cert
  475. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  476. encryption specification of the cert file
  477. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  478. start date
  479. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  480. expiration date
  481. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  482. from the certificate
  483. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC
  484. key from the certificate
  485. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  486. key object id
  487. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  488. defined and the certificate is a V1 or V2 certificate
  489. \return BAD_FUNC_ARG Returned if there is an error processing the
  490. certificate extension
  491. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  492. encountered in processing the certificate
  493. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  494. the same as the encryption type of the certificate in the provided file
  495. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  496. signature fails
  497. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  498. permitted by the CA name constraints
  499. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
  500. the certificate’s authenticity
  501. \param cert pointer to the cert for which to set the issuer
  502. \param der pointer to the buffer containing the der formatted certificate
  503. from which to grab the issuer
  504. \param derSz size of the buffer containing the der formatted certificate
  505. from which to grab the issuer
  506. _Example_
  507. \code
  508. Cert myCert;
  509. // initialize myCert
  510. byte* der;
  511. der = (byte*)malloc(FOURK_BUF);
  512. // initialize der
  513. if(wc_SetIssuerBuffer(&myCert, der, FOURK_BUF) != 0) {
  514. // error setting issuer
  515. }
  516. \endcode
  517. \sa wc_InitCert
  518. \sa wc_SetIssuer
  519. */
  520. int wc_SetIssuerBuffer(Cert* cert, const byte* der, int derSz);
  521. /*!
  522. \ingroup ASN
  523. \brief This function sets the raw issuer for a certificate from the
  524. issuer in the provided der buffer. This method is used to set the raw
  525. issuer field prior to signing.
  526. \return 0 Returned on successfully setting the issuer for the certificate
  527. \return MEMORY_E Returned if there is an error allocating memory
  528. with XMALLOC
  529. \return ASN_PARSE_E Returned if there is an error parsing the cert
  530. header file
  531. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  532. encryption type from the cert
  533. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  534. encryption specification of the cert file
  535. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  536. start date
  537. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  538. expiration date
  539. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  540. from the certificate
  541. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  542. from the certificate
  543. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  544. key object id
  545. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  546. defined and the certificate is a V1 or V2 certificate
  547. \return BAD_FUNC_ARG Returned if there is an error processing the
  548. certificate extension
  549. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  550. encountered in processing the certificate
  551. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  552. the same as the encryption type of the certificate in the provided file
  553. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  554. signature fails
  555. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  556. permitted by the CA name constraints
  557. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  558. certificate’s authenticity
  559. \param cert pointer to the cert for which to set the raw issuer
  560. \param der pointer to the buffer containing the der formatted certificate
  561. from which to grab the subject
  562. \param derSz size of the buffer containing the der formatted certificate
  563. from which to grab the subject
  564. _Example_
  565. \code
  566. Cert myCert;
  567. // initialize myCert
  568. byte* der;
  569. der = (byte*)malloc(FOURK_BUF);
  570. // initialize der
  571. if(wc_SetIssuerRaw(&myCert, der, FOURK_BUF) != 0) {
  572. // error setting subject
  573. }
  574. \endcode
  575. \sa wc_InitCert
  576. \sa wc_SetIssuer
  577. */
  578. int wc_SetIssuerRaw(Cert* cert, const byte* der, int derSz);
  579. /*!
  580. \ingroup ASN
  581. \brief This function sets the subject for a certificate from the subject in
  582. the provided der buffer. This method is used to set fields prior to signing.
  583. \return 0 Returned on successfully setting the subject for the certificate
  584. \return MEMORY_E Returned if there is an error allocating memory
  585. with XMALLOC
  586. \return ASN_PARSE_E Returned if there is an error parsing the cert
  587. header file
  588. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  589. encryption type from the cert
  590. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  591. encryption specification of the cert file
  592. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  593. start date
  594. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  595. expiration date
  596. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  597. from the certificate
  598. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  599. from the certificate
  600. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  601. key object id
  602. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  603. defined and the certificate is a V1 or V2 certificate
  604. \return BAD_FUNC_ARG Returned if there is an error processing the
  605. certificate extension
  606. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  607. encountered in processing the certificate
  608. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  609. the same as the encryption type of the certificate in the provided file
  610. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  611. signature fails
  612. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  613. permitted by the CA name constraints
  614. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  615. certificate’s authenticity
  616. \param cert pointer to the cert for which to set the subject
  617. \param der pointer to the buffer containing the der formatted certificate
  618. from which to grab the subject
  619. \param derSz size of the buffer containing the der formatted certificate
  620. from which to grab the subject
  621. _Example_
  622. \code
  623. Cert myCert;
  624. // initialize myCert
  625. byte* der;
  626. der = (byte*)malloc(FOURK_BUF);
  627. // initialize der
  628. if(wc_SetSubjectBuffer(&myCert, der, FOURK_BUF) != 0) {
  629. // error setting subject
  630. }
  631. \endcode
  632. \sa wc_InitCert
  633. \sa wc_SetSubject
  634. */
  635. int wc_SetSubjectBuffer(Cert* cert, const byte* der, int derSz);
  636. /*!
  637. \ingroup ASN
  638. \brief This function sets the alternate names for a certificate from the
  639. alternate names in the provided der buffer. This is useful in the case that
  640. one wishes to secure multiple domains with the same certificate. This
  641. method is used to set fields prior to signing.
  642. \return 0 Returned on successfully setting the alternate names for the
  643. certificate
  644. \return MEMORY_E Returned if there is an error allocating memory with
  645. XMALLOC
  646. \return ASN_PARSE_E Returned if there is an error parsing the cert
  647. header file
  648. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  649. encryption type from the cert
  650. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  651. encryption specification of the cert file
  652. \return ASN_BEFORE_DATE_E Returned if the date is before the
  653. certificate start date
  654. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  655. expiration date
  656. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  657. from the certificate
  658. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  659. from the certificate
  660. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  661. key object id
  662. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  663. defined and the certificate is a V1 or V2 certificate
  664. \return BAD_FUNC_ARG Returned if there is an error processing the
  665. certificate extension
  666. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  667. encountered in processing the certificate
  668. \return ASN_SIG_OID_E Returned if the signature encryption type is not the
  669. same as the encryption type of the certificate in the provided file
  670. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  671. signature fails
  672. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  673. permitted by the CA name constraints
  674. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  675. certificate’s authenticity
  676. \param cert pointer to the cert for which to set the alternate names
  677. \param der pointer to the buffer containing the der formatted certificate
  678. from which to grab the alternate names
  679. \param derSz size of the buffer containing the der formatted certificate
  680. from which to grab the alternate names
  681. _Example_
  682. \code
  683. Cert myCert;
  684. // initialize myCert
  685. byte* der;
  686. der = (byte*)malloc(FOURK_BUF);
  687. // initialize der
  688. if(wc_SetAltNamesBuffer(&myCert, der, FOURK_BUF) != 0) {
  689. // error setting subject
  690. }
  691. \endcode
  692. \sa wc_InitCert
  693. \sa wc_SetAltNames
  694. */
  695. int wc_SetAltNamesBuffer(Cert* cert, const byte* der, int derSz);
  696. /*!
  697. \ingroup ASN
  698. \brief This function sets the dates for a certificate from the date range
  699. in the provided der buffer. This method is used to set fields prior
  700. to signing.
  701. \return 0 Returned on successfully setting the dates for the certificate
  702. \return MEMORY_E Returned if there is an error allocating memory
  703. with XMALLOC
  704. \return ASN_PARSE_E Returned if there is an error parsing the cert
  705. header file
  706. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  707. encryption type from the cert
  708. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  709. encryption specification of the cert file
  710. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  711. start date
  712. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  713. expiration date
  714. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  715. from the certificate
  716. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  717. from the certificate
  718. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  719. key object id
  720. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  721. defined and the certificate is a V1 or V2 certificate
  722. \return BAD_FUNC_ARG Returned if there is an error processing the
  723. certificate extension
  724. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  725. encountered in processing the certificate
  726. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  727. the same as the encryption type of the certificate in the provided file
  728. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  729. signature fails
  730. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  731. permitted by the CA name constraints
  732. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  733. certificate’s authenticity
  734. \param cert pointer to the cert for which to set the dates
  735. \param der pointer to the buffer containing the der formatted certificate
  736. from which to grab the date range
  737. \param derSz size of the buffer containing the der formatted certificate
  738. from which to grab the date range
  739. _Example_
  740. \code
  741. Cert myCert;
  742. // initialize myCert
  743. byte* der;
  744. der = (byte*)malloc(FOURK_BUF);
  745. // initialize der
  746. if(wc_SetDatesBuffer(&myCert, der, FOURK_BUF) != 0) {
  747. // error setting subject
  748. }
  749. \endcode
  750. \sa wc_InitCert
  751. */
  752. int wc_SetDatesBuffer(Cert* cert, const byte* der, int derSz);
  753. /*!
  754. \ingroup ASN
  755. \brief Set AKID from either an RSA or ECC public key. note: Only set one of
  756. rsakey or eckey, not both.
  757. \return 0 Success
  758. \return BAD_FUNC_ARG Either cert is null or both rsakey and eckey are null.
  759. \return MEMORY_E Error allocating memory.
  760. \return PUBLIC_KEY_E Error writing to the key.
  761. \param cert Pointer to the certificate to set the SKID.
  762. \param rsakey Pointer to the RsaKey struct to read from.
  763. \param eckey Pointer to the ecc_key to read from.
  764. _Example_
  765. \code
  766. Cert myCert;
  767. RsaKey keypub;
  768. wc_InitRsaKey(&keypub, 0);
  769. if (wc_SetAuthKeyIdFromPublicKey(&myCert, &keypub, NULL) != 0)
  770. {
  771. // Handle error
  772. }
  773. \endcode
  774. \sa wc_SetSubjectKeyId
  775. \sa wc_SetAuthKeyId
  776. \sa wc_SetAuthKeyIdFromCert
  777. */
  778. int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
  779. ecc_key *eckey);
  780. /*!
  781. \ingroup ASN
  782. \brief Set AKID from from DER encoded certificate.
  783. \return 0 Success
  784. \return BAD_FUNC_ARG Error if any argument is null or derSz is less than 0.
  785. \return MEMORY_E Error if problem allocating memory.
  786. \return ASN_NO_SKID No subject key ID found.
  787. \param cert The Cert struct to write to.
  788. \param der The DER encoded certificate buffer.
  789. \param derSz Size of der in bytes.
  790. _Example_
  791. \code
  792. Cert some_cert;
  793. byte some_der[] = { // Initialize a DER buffer };
  794. wc_InitCert(&some_cert);
  795. if(wc_SetAuthKeyIdFromCert(&some_cert, some_der, sizeof(some_der) != 0)
  796. {
  797. // Handle error
  798. }
  799. \endcode
  800. \sa wc_SetAuthKeyIdFromPublicKey
  801. \sa wc_SetAuthKeyId
  802. */
  803. int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz);
  804. /*!
  805. \ingroup ASN
  806. \brief Set AKID from certificate file in PEM format.
  807. \return 0 Success
  808. \return BAD_FUNC_ARG Error if cert or file is null.
  809. \return MEMORY_E Error if problem allocating memory.
  810. \param cert Cert struct you want to set the AKID of.
  811. \param file Buffer containing PEM cert file.
  812. _Example_
  813. \code
  814. char* file_name = "/path/to/file";
  815. cert some_cert;
  816. wc_InitCert(&some_cert);
  817. if(wc_SetAuthKeyId(&some_cert, file_name) != 0)
  818. {
  819. // Handle Error
  820. }
  821. \endcode
  822. \sa wc_SetAuthKeyIdFromPublicKey
  823. \sa wc_SetAuthKeyIdFromCert
  824. */
  825. int wc_SetAuthKeyId(Cert *cert, const char* file);
  826. /*!
  827. \ingroup ASN
  828. \brief Set SKID from RSA or ECC public key.
  829. \return 0 Success
  830. \return BAD_FUNC_ARG Returned if cert or rsakey and eckey are null.
  831. \return MEMORY_E Returned if there is an error allocating memory.
  832. \return PUBLIC_KEY_E Returned if there is an error getting the public key.
  833. \param cert Pointer to a Cert structure to be used.
  834. \param rsakey Pointer to an RsaKey structure
  835. \param eckey Pointer to an ecc_key structure
  836. _Example_
  837. \code
  838. Cert some_cert;
  839. RsaKey some_key;
  840. wc_InitCert(&some_cert);
  841. wc_InitRsaKey(&some_key);
  842. if(wc_SetSubjectKeyIdFromPublicKey(&some_cert,&some_key, NULL) != 0)
  843. {
  844. // Handle Error
  845. }
  846. \endcode
  847. \sa wc_SetSubjectKeyId
  848. */
  849. int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
  850. ecc_key *eckey);
  851. /*!
  852. \ingroup ASN
  853. \brief Set SKID from public key file in PEM format. Both arguments
  854. are required.
  855. \return 0 Success
  856. \return BAD_FUNC_ARG Returns if cert or file is null.
  857. \return MEMORY_E Returns if there is a problem allocating memory for key.
  858. \return PUBLIC_KEY_E Returns if there is an error decoding the public key.
  859. \param cert Cert structure to set the SKID of.
  860. \param file Contains the PEM encoded file.
  861. _Example_
  862. \code
  863. const char* file_name = "path/to/file";
  864. Cert some_cert;
  865. wc_InitCert(&some_cert);
  866. if(wc_SetSubjectKeyId(&some_cert, file_name) != 0)
  867. {
  868. // Handle Error
  869. }
  870. \endcode
  871. \sa wc_SetSubjectKeyIdFromPublicKey
  872. */
  873. int wc_SetSubjectKeyId(Cert *cert, const char* file);
  874. /*!
  875. \ingroup RSA
  876. \brief This function allows you to set the key usage using a comma
  877. delimited string of tokens. Accepted tokens are: digitalSignature,
  878. nonRepudiation, contentCommitment, keyCertSign, cRLSign, dataEncipherment,
  879. keyAgreement, keyEncipherment, encipherOnly, decipherOnly. Example:
  880. "digitalSignature,nonRepudiation" nonRepudiation and contentCommitment
  881. are for the same usage.
  882. \return 0 Success
  883. \return BAD_FUNC_ARG Returned when either arg is null.
  884. \return MEMORY_E Returned when there is an error allocating memory.
  885. \return KEYUSAGE_E Returned if an unrecognized token is entered.
  886. \param cert Pointer to initialized Cert structure.
  887. \param value Comma delimited string of tokens to set usage.
  888. _Example_
  889. \code
  890. Cert cert;
  891. wc_InitCert(&cert);
  892. if(wc_SetKeyUsage(&cert, "cRLSign,keyCertSign") != 0)
  893. {
  894. // Handle error
  895. }
  896. \endcode
  897. \sa wc_InitCert
  898. \sa wc_MakeRsaKey
  899. */
  900. int wc_SetKeyUsage(Cert *cert, const char *value);
  901. /*!
  902. \ingroup ASN
  903. \brief Loads a PEM key from a file and converts to a DER encoded buffer.
  904. \return 0 Success
  905. \return <0 Error
  906. \return SSL_BAD_FILE There is a problem with opening the file.
  907. \return MEMORY_E There is an error allocating memory for the file buffer.
  908. \return BUFFER_E derBuf is not large enough to hold the converted key.
  909. \param fileName Name of the file to load.
  910. \param derBuf Buffer for DER encoded key.
  911. \param derSz Size of DER buffer.
  912. _Example_
  913. \code
  914. char* some_file = "filename";
  915. unsigned char der[];
  916. if(wc_PemPubKeyToDer(some_file, der, sizeof(der)) != 0)
  917. {
  918. //Handle Error
  919. }
  920. \endcode
  921. \sa wc_PubKeyPemToDer
  922. */
  923. int wc_PemPubKeyToDer(const char* fileName,
  924. unsigned char* derBuf, int derSz);
  925. /*!
  926. \ingroup ASN
  927. \brief Convert a PEM encoded public key to DER. Returns the number of
  928. bytes written to the buffer or a negative value for an error.
  929. \return >0 Success, number of bytes written.
  930. \return BAD_FUNC_ARG Returns if pem, buff, or buffSz are null
  931. \return <0 An error occurred in the function.
  932. \param pem PEM encoded key
  933. \param pemSz Size of pem
  934. \param buff Pointer to buffer for output.
  935. \param buffSz Size of buffer.
  936. _Example_
  937. \code
  938. byte some_pem[] = { Initialize with PEM key }
  939. unsigned char out_buffer[1024]; // Ensure buffer is large enough to fit DER
  940. if(wc_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer,
  941. sizeof(out_buffer)) < 0)
  942. {
  943. // Handle error
  944. }
  945. \endcode
  946. \sa wc_PemPubKeyToDer
  947. */
  948. int wc_PubKeyPemToDer(const unsigned char* pem, int pemSz,
  949. unsigned char* buff, int buffSz);
  950. /*!
  951. \ingroup ASN
  952. \brief This function converts a pem certificate to a der certificate,
  953. and places the resulting certificate in the derBuf buffer provided.
  954. \return Success On success returns the size of the derBuf generated
  955. \return BUFFER_E Returned if the size of derBuf is too small to hold
  956. the certificate generated
  957. \return MEMORY_E Returned if the call to XMALLOC fails
  958. \param fileName path to the file containing a pem certificate to
  959. convert to a der certificate
  960. \param derBuf pointer to a char buffer in which to store the
  961. converted certificate
  962. \param derSz size of the char buffer in which to store the
  963. converted certificate
  964. _Example_
  965. \code
  966. char * file = “./certs/client-cert.pem”;
  967. int derSz;
  968. byte* der = (byte*)XMALLOC((8*1024), NULL, DYNAMIC_TYPE_CERT);
  969. derSz = wc_PemCertToDer(file, der, (8*1024));
  970. if (derSz <= 0) {
  971. //PemCertToDer error
  972. }
  973. \endcode
  974. \sa none
  975. */
  976. int wc_PemCertToDer(const char* fileName, unsigned char* derBuf, int derSz);
  977. /*!
  978. \ingroup ASN
  979. \brief This function converts a der formatted input certificate, contained
  980. in the der buffer, into a pem formatted output certificate, contained in
  981. the output buffer. It should be noted that this is not an in place
  982. conversion, and a separate buffer must be utilized to store the pem
  983. formatted output.
  984. \return Success On successfully making a pem certificate from the input
  985. der cert, returns the size of the pem cert generated.
  986. \return BAD_FUNC_ARG Returned if there is an error parsing the der file
  987. and storing it as a pem file
  988. \return MEMORY_E Returned if there is an error allocating memory
  989. with XMALLOC
  990. \return ASN_INPUT_E Returned in the case of a base64 encoding error
  991. \return BUFFER_E May be returned if the output buffer is too small to
  992. store the pem formatted certificate
  993. \param der pointer to the buffer of the certificate to convert
  994. \param derSz size of the the certificate to convert
  995. \param output pointer to the buffer in which to store the pem
  996. formatted certificate
  997. \param outSz size of the buffer in which to store the pem formatted
  998. certificate
  999. \param type the type of certificate to generate. Valid types are:
  1000. CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
  1001. _Example_
  1002. \code
  1003. byte* der;
  1004. // initialize der with certificate
  1005. byte* pemFormatted[FOURK_BUF];
  1006. word32 pemSz;
  1007. pemSz = wc_DerToPem(der, derSz,pemFormatted,FOURK_BUF, CERT_TYPE);
  1008. \endcode
  1009. \sa wc_PemCertToDer
  1010. */
  1011. int wc_DerToPem(const byte* der, word32 derSz, byte* output,
  1012. word32 outputSz, int type);
  1013. /*!
  1014. \ingroup ASN
  1015. \brief This function converts a der formatted input certificate,
  1016. contained in the der buffer, into a pem formatted output certificate,
  1017. contained in the output buffer. It should be noted that this is not an
  1018. in place conversion, and a separate buffer must be utilized to store the
  1019. pem formatted output. Allows setting cipher info.
  1020. \return Success On successfully making a pem certificate from the input
  1021. der cert, returns the size of the pem cert generated.
  1022. \return BAD_FUNC_ARG Returned if there is an error parsing the der file
  1023. and storing it as a pem file
  1024. \return MEMORY_E Returned if there is an error allocating memory
  1025. with XMALLOC
  1026. \return ASN_INPUT_E Returned in the case of a base64 encoding error
  1027. \return BUFFER_E May be returned if the output buffer is too small to
  1028. store the pem formatted certificate
  1029. \param der pointer to the buffer of the certificate to convert
  1030. \param derSz size of the the certificate to convert
  1031. \param output pointer to the buffer in which to store the pem
  1032. formatted certificate
  1033. \param outSz size of the buffer in which to store the pem formatted
  1034. certificate
  1035. \param cipher_inf Additional cipher information.
  1036. \param type the type of certificate to generate. Valid types are:
  1037. CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
  1038. _Example_
  1039. \code
  1040. byte* der;
  1041. // initialize der with certificate
  1042. byte* pemFormatted[FOURK_BUF];
  1043. word32 pemSz;
  1044. byte* cipher_info[] { Additional cipher info. }
  1045. pemSz = wc_DerToPemEx(der, derSz, pemFormatted, FOURK_BUF, cipher_info, CERT_TYPE);
  1046. \endcode
  1047. \sa wc_PemCertToDer
  1048. */
  1049. int wc_DerToPemEx(const byte* der, word32 derSz, byte* output,
  1050. word32 outputSz, byte *cipherIno, int type);
  1051. /*!
  1052. \ingroup CertsKeys
  1053. \brief Converts a key in PEM format to DER format.
  1054. \return int the function returns the number of bytes written to
  1055. the buffer on successful execution.
  1056. \return int negative int returned indicating an error.
  1057. \param pem a pointer to the PEM encoded certificate.
  1058. \param pemSz the size of the PEM buffer (pem)
  1059. \param buff a pointer to the copy of the buffer member of the
  1060. DerBuffer struct.
  1061. \param buffSz size of the buffer space allocated in the DerBuffer struct.
  1062. \param pass password passed into the function.
  1063. _Example_
  1064. \code
  1065. byte* loadBuf;
  1066. long fileSz = 0;
  1067. byte* bufSz;
  1068. static int LoadKeyFile(byte** keyBuf, word32* keyBufSz,
  1069. const char* keyFile,
  1070. int typeKey, const char* password);
  1071. bufSz = wc_KeyPemToDer(loadBuf, (int)fileSz, saveBuf,
  1072. (int)fileSz, password);
  1073. if(saveBufSz > 0){
  1074. // Bytes were written to the buffer.
  1075. }
  1076. \endcode
  1077. \sa wc_PemToDer
  1078. */
  1079. int wc_KeyPemToDer(const unsigned char* pem, int pemSz,
  1080. unsigned char* buff, int buffSz, const char* pass);
  1081. /*!
  1082. \ingroup CertsKeys
  1083. \brief This function converts a PEM formatted certificate to DER
  1084. format. Calls OpenSSL function PemToDer.
  1085. \return buffer returns the bytes written to the buffer.
  1086. \param pem pointer PEM formatted certificate.
  1087. \param pemSz size of the certificate.
  1088. \param buff buffer to be copied to DER format.
  1089. \param buffSz size of the buffer.
  1090. \param type Certificate file type found in asn_public.h enum CertType.
  1091. _Example_
  1092. \code
  1093. const unsigned char* pem;
  1094. int pemSz;
  1095. unsigned char buff[BUFSIZE];
  1096. int buffSz = sizeof(buff)/sizeof(char);
  1097. int type;
  1098. ...
  1099. if(wc_CertPemToDer(pem, pemSz, buff, buffSz, type) <= 0) {
  1100. // There were bytes written to buffer
  1101. }
  1102. \endcode
  1103. \sa wc_PemToDer
  1104. */
  1105. int wc_CertPemToDer(const unsigned char* pem, int pemSz,
  1106. unsigned char* buff, int buffSz, int type);
  1107. /*!
  1108. \ingroup CertsKeys
  1109. \brief This function gets the public key in DER format from a populated
  1110. DecodedCert struct. Users must call wc_InitDecodedCert() and wc_ParseCert()
  1111. before calling this API. wc_InitDecodedCert() accepts a DER/ASN.1 encoded
  1112. certificate. To convert a PEM cert to DER, first use wc_CertPemToDer()
  1113. before calling wc_InitDecodedCert().
  1114. \return 0 on success, negative on error. LENGTH_ONLY_E if derKey is NULL
  1115. and returning length only.
  1116. \param cert populated DecodedCert struct holding X.509 certificate
  1117. \param derKey output buffer to place DER encoded public key
  1118. \param derKeySz [IN/OUT] size of derKey buffer on input, size of public key
  1119. on return. If derKey is passed in as NULL, derKeySz will be set to required
  1120. buffer size for public key and LENGTH_ONLY_E will be returned from function.
  1121. \sa wc_GetPubKeyDerFromCert
  1122. */
  1123. int wc_GetPubKeyDerFromCert(struct DecodedCert* cert,
  1124. byte* derKey, word32* derKeySz);
  1125. /*!
  1126. \ingroup ASN
  1127. \brief This function reads in an ECC private key from the input buffer,
  1128. input, parses the private key, and uses it to generate an ecc_key object,
  1129. which it stores in key.
  1130. \return 0 On successfully decoding the private key and storing the result
  1131. in the ecc_key struct
  1132. \return ASN_PARSE_E: Returned if there is an error parsing the der file
  1133. and storing it as a pem file
  1134. \return MEMORY_E Returned if there is an error allocating memory
  1135. with XMALLOC
  1136. \return BUFFER_E Returned if the certificate to convert is large than
  1137. the specified max certificate size
  1138. \return ASN_OBJECT_ID_E Returned if the certificate encoding has an
  1139. invalid object id
  1140. \return ECC_CURVE_OID_E Returned if the ECC curve of the provided key is
  1141. not supported
  1142. \return ECC_BAD_ARG_E Returned if there is an error in the ECC key format
  1143. \return NOT_COMPILED_IN Returned if the private key is compressed, and no
  1144. compression key is provided
  1145. \return MP_MEM Returned if there is an error in the math library used
  1146. while parsing the private key
  1147. \return MP_VAL Returned if there is an error in the math library used
  1148. while parsing the private key
  1149. \return MP_RANGE Returned if there is an error in the math library used
  1150. while parsing the private key
  1151. \param input pointer to the buffer containing the input private key
  1152. \param inOutIdx pointer to a word32 object containing the index in
  1153. the buffer at which to start
  1154. \param key pointer to an initialized ecc object, on which to store
  1155. the decoded private key
  1156. \param inSz size of the input buffer containing the private key
  1157. _Example_
  1158. \code
  1159. int ret, idx=0;
  1160. ecc_key key; // to store key in
  1161. byte* tmp; // tmp buffer to read key from
  1162. tmp = (byte*) malloc(FOURK_BUF);
  1163. int inSz;
  1164. inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile);
  1165. // read key into tmp buffer
  1166. wc_ecc_init(&key); // initialize key
  1167. ret = wc_EccPrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
  1168. if(ret < 0) {
  1169. // error decoding ecc key
  1170. }
  1171. \endcode
  1172. \sa wc_RSA_PrivateKeyDecode
  1173. */
  1174. int wc_EccPrivateKeyDecode(const byte* input, word32* inOutIdx,
  1175. ecc_key* key, word32 inSz);
  1176. /*!
  1177. \ingroup ASN
  1178. \brief This function writes a private ECC key to der format.
  1179. \return Success On successfully writing the ECC key to der format,
  1180. returns the length written to the buffer
  1181. \return BAD_FUNC_ARG Returned if key or output is null, or inLen equals zero
  1182. \return MEMORY_E Returned if there is an error allocating memory
  1183. with XMALLOC
  1184. \return BUFFER_E Returned if the converted certificate is too large
  1185. to store in the output buffer
  1186. \return ASN_UNKNOWN_OID_E Returned if the ECC key used is of an
  1187. unknown type
  1188. \return MP_MEM Returned if there is an error in the math library used
  1189. while parsing the private key
  1190. \return MP_VAL Returned if there is an error in the math library used
  1191. while parsing the private key
  1192. \return MP_RANGE Returned if there is an error in the math library used
  1193. while parsing the private key
  1194. \param key pointer to the buffer containing the input ecc key
  1195. \param output pointer to a buffer in which to store the der formatted key
  1196. \param inLen the length of the buffer in which to store the
  1197. der formatted key
  1198. _Example_
  1199. \code
  1200. int derSz;
  1201. ecc_key key;
  1202. // initialize and make key
  1203. byte der[FOURK_BUF];
  1204. // store der formatted key here
  1205. derSz = wc_EccKeyToDer(&key, der, FOURK_BUF);
  1206. if(derSz < 0) {
  1207. // error converting ecc key to der buffer
  1208. }
  1209. \endcode
  1210. \sa wc_RsaKeyToDer
  1211. */
  1212. int wc_EccKeyToDer(ecc_key* key, byte* output, word32 inLen);
  1213. /*!
  1214. \ingroup ASN
  1215. \brief Decodes an ECC public key from an input buffer. It will parse an
  1216. ASN sequence to retrieve the ECC key.
  1217. \return 0 Success
  1218. \return BAD_FUNC_ARG Returns if any arguments are null.
  1219. \return ASN_PARSE_E Returns if there is an error parsing
  1220. \return ASN_ECC_KEY_E Returns if there is an error importing the key.
  1221. See wc_ecc_import_x963 for possible reasons.
  1222. \param input Buffer containing DER encoded key to decode.
  1223. \param inOutIdx Index to start reading input buffer from. On output,
  1224. index is set to last position parsed of input buffer.
  1225. \param key Pointer to ecc_key struct to store the public key.
  1226. \param inSz Size of the input buffer.
  1227. _Example_
  1228. \code
  1229. int ret;
  1230. word32 idx = 0;
  1231. byte buff[] = { // initialize with key };
  1232. ecc_key pubKey;
  1233. wc_ecc_init(&pubKey);
  1234. if ( wc_EccPublicKeyDecode(buff, &idx, &pubKey, sizeof(buff)) != 0) {
  1235. // error decoding key
  1236. }
  1237. \endcode
  1238. \sa wc_ecc_import_x963
  1239. */
  1240. int wc_EccPublicKeyDecode(const byte* input, word32* inOutIdx,
  1241. ecc_key* key, word32 inSz);
  1242. /*!
  1243. \ingroup ASN
  1244. \brief This function converts the ECC public key to DER format. It
  1245. returns the size of buffer used. The public ECC key in DER format is stored
  1246. in output buffer. The with_AlgCurve flag will include a header that
  1247. has the Algorithm and Curve information
  1248. \return >0 Success, size of buffer used
  1249. \return BAD_FUNC_ARG Returned if output or key is null.
  1250. \return LENGTH_ONLY_E Error in getting ECC public key size.
  1251. \return BUFFER_E Returned when output buffer is too small.
  1252. \param key Pointer to ECC key
  1253. \param output Pointer to output buffer to write to.
  1254. \param inLen Size of buffer.
  1255. \param with_AlgCurve a flag for when to include a header that has the
  1256. Algorithm and Curve information.
  1257. _Example_
  1258. \code
  1259. ecc_key key;
  1260. wc_ecc_init(&key);
  1261. WC_RNG rng;
  1262. wc_InitRng(&rng);
  1263. wc_ecc_make_key(&rng, 32, &key);
  1264. int derSz = // Some appropriate size for der;
  1265. byte der[derSz];
  1266. if(wc_EccPublicKeyToDer(&key, der, derSz, 1) < 0)
  1267. {
  1268. // Error converting ECC public key to der
  1269. }
  1270. \endcode
  1271. \sa wc_EccKeyToDer
  1272. \sa wc_EccPrivateKeyDecode
  1273. */
  1274. int wc_EccPublicKeyToDer(ecc_key* key, byte* output,
  1275. word32 inLen, int with_AlgCurve);
  1276. /*!
  1277. \ingroup ASN
  1278. \brief This function converts the ECC public key to DER format. It
  1279. returns the size of buffer used. The public ECC key in DER format is stored
  1280. in output buffer. The with_AlgCurve flag will include a header that
  1281. has the Algorithm and Curve information. The comp parameter determines if
  1282. the public key will be exported as compressed.
  1283. \return >0 Success, size of buffer used
  1284. \return BAD_FUNC_ARG Returned if output or key is null.
  1285. \return LENGTH_ONLY_E Error in getting ECC public key size.
  1286. \return BUFFER_E Returned when output buffer is too small.
  1287. \param key Pointer to ECC key
  1288. \param output Pointer to output buffer to write to.
  1289. \param inLen Size of buffer.
  1290. \param with_AlgCurve a flag for when to include a header that has the
  1291. Algorithm and Curve information.
  1292. \param comp If 1 (non-zero) the ECC public key will be written in
  1293. compressed form. If 0 it will be written in an uncompressed format.
  1294. _Example_
  1295. \code
  1296. ecc_key key;
  1297. wc_ecc_init(&key);
  1298. WC_RNG rng;
  1299. wc_InitRng(&rng);
  1300. wc_ecc_make_key(&rng, 32, &key);
  1301. int derSz = // Some appropriate size for der;
  1302. byte der[derSz];
  1303. // Write out a compressed ECC key
  1304. if(wc_EccPublicKeyToDer_ex(&key, der, derSz, 1, 1) < 0)
  1305. {
  1306. // Error converting ECC public key to der
  1307. }
  1308. \endcode
  1309. \sa wc_EccKeyToDer
  1310. \sa wc_EccPublicKeyDecode
  1311. */
  1312. int wc_EccPublicKeyToDer_ex(ecc_key* key, byte* output,
  1313. word32 inLen, int with_AlgCurve, int comp);
  1314. /*!
  1315. \ingroup ASN
  1316. \brief This function encodes a digital signature into the output buffer,
  1317. and returns the size of the encoded signature created.
  1318. \return Success On successfully writing the encoded signature to output,
  1319. returns the length written to the buffer
  1320. \param out pointer to the buffer where the encoded signature will be written
  1321. \param digest pointer to the digest to use to encode the signature
  1322. \param digSz the length of the buffer containing the digest
  1323. \param hashOID OID identifying the hash type used to generate the
  1324. signature. Valid options, depending on build configurations, are: SHAh,
  1325. SHA256h, SHA384h, SHA512h, MD2h, MD5h, DESb, DES3b, CTC_MD5wRSA,
  1326. CTC_SHAwRSA, CTC_SHA256wRSA, CTC_SHA384wRSA, CTC_SHA512wRSA, CTC_SHAwECDSA,
  1327. CTC_SHA256wECDSA, CTC_SHA384wECDSA, and CTC_SHA512wECDSA.
  1328. \endcode
  1329. \code
  1330. int signSz;
  1331. byte encodedSig[MAX_ENCODED_SIG_SZ];
  1332. Sha256 sha256;
  1333. // initialize sha256 for hashing
  1334. byte* dig = = (byte*)malloc(WC_SHA256_DIGEST_SIZE);
  1335. // perform hashing and hash updating so dig stores SHA-256 hash
  1336. // (see wc_InitSha256, wc_Sha256Update and wc_Sha256Final)
  1337. signSz = wc_EncodeSignature(encodedSig, dig, WC_SHA256_DIGEST_SIZE, SHA256h);
  1338. \endcode
  1339. \sa none
  1340. */
  1341. word32 wc_EncodeSignature(byte* out, const byte* digest,
  1342. word32 digSz, int hashOID);
  1343. /*!
  1344. \ingroup ASN
  1345. \brief This function returns the hash OID that corresponds to a hashing
  1346. type. For example, when given the type: WC_SHA512, this function returns the
  1347. identifier corresponding to a SHA512 hash, SHA512h.
  1348. \return Success On success, returns the OID corresponding to the
  1349. appropriate hash to use with that encryption type.
  1350. \return 0 Returned if an unrecognized hash type is passed in as argument.
  1351. \param type the hash type for which to find the OID. Valid options,
  1352. depending on build configuration, include: WC_MD5, WC_SHA, WC_SHA256,
  1353. WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
  1354. _Example_
  1355. \code
  1356. int hashOID;
  1357. hashOID = wc_GetCTC_HashOID(WC_SHA512);
  1358. if (hashOID == 0) {
  1359. // WOLFSSL_SHA512 not defined
  1360. }
  1361. \endcode
  1362. \sa none
  1363. */
  1364. int wc_GetCTC_HashOID(int type);
  1365. /*!
  1366. \ingroup ASN
  1367. \brief This function cleans up memory and resources used by the certificate
  1368. structure's decoded cert cache. When WOLFSSL_CERT_GEN_CACHE is defined the
  1369. decoded cert structure is cached in the certificate structure. This allows
  1370. subsequent calls to certificate set functions to avoid parsing the decoded
  1371. cert on each call.
  1372. \return 0 on success.
  1373. \return BAD_FUNC_ARG Returned if invalid pointer is passed in as argument.
  1374. \param cert pointer to an uninitialized certificate information structure.
  1375. _Example_
  1376. \code
  1377. Cert cert; // Initialized certificate structure
  1378. wc_SetCert_Free(&cert);
  1379. \endcode
  1380. \sa wc_SetAuthKeyIdFromCert
  1381. \sa wc_SetIssuerBuffer
  1382. \sa wc_SetSubjectBuffer
  1383. \sa wc_SetSubjectRaw
  1384. \sa wc_SetIssuerRaw
  1385. \sa wc_SetAltNamesBuffer
  1386. \sa wc_SetDatesBuffer
  1387. */
  1388. void wc_SetCert_Free(Cert* cert);
  1389. /*!
  1390. \ingroup ASN
  1391. \brief This function finds the beginning of the traditional private key
  1392. inside a PKCS#8 unencrypted buffer.
  1393. \return Length of traditional private key on success.
  1394. \return Negative values on failure.
  1395. \param input Buffer containing unencrypted PKCS#8 private key.
  1396. \param inOutIdx Index into the input buffer. On input, it should be a byte
  1397. offset to the beginning of the the PKCS#8 buffer. On output, it will be the
  1398. byte offset to the traditional private key within the input buffer.
  1399. \param sz The number of bytes in the input buffer.
  1400. _Example_
  1401. \code
  1402. byte* pkcs8Buf; // Buffer containing PKCS#8 key.
  1403. word32 idx = 0;
  1404. word32 sz; // Size of pkcs8Buf.
  1405. ...
  1406. ret = wc_GetPkcs8TraditionalOffset(pkcs8Buf, &idx, sz);
  1407. // pkcs8Buf + idx is now the beginning of the traditional private key bytes.
  1408. \endcode
  1409. \sa wc_CreatePKCS8Key
  1410. \sa wc_EncryptPKCS8Key
  1411. \sa wc_DecryptPKCS8Key
  1412. \sa wc_CreateEncryptedPKCS8Key
  1413. */
  1414. int wc_GetPkcs8TraditionalOffset(byte* input,
  1415. word32* inOutIdx, word32 sz);
  1416. /*!
  1417. \ingroup ASN
  1418. \brief This function takes in a DER private key and converts it to PKCS#8
  1419. format. Also used in creating PKCS#12 shrouded key bags. See RFC 5208.
  1420. \return The size of the PKCS#8 key placed into out on success.
  1421. \return LENGTH_ONLY_E if out is NULL, with required output buffer size in
  1422. outSz.
  1423. \return Other negative values on failure.
  1424. \param out Buffer to place result in. If NULL, required out buffer size
  1425. returned in outSz.
  1426. \param outSz Size of out buffer.
  1427. \param key Buffer with traditional DER key.
  1428. \param keySz Size of key buffer.
  1429. \param algoID Algorithm ID (e.g. RSAk).
  1430. \param curveOID ECC curve OID if used. Should be NULL for RSA keys.
  1431. \param oidSz Size of curve OID. Is set to 0 if curveOID is NULL.
  1432. _Example_
  1433. \code
  1434. ecc_key eccKey; // wolfSSL ECC key object.
  1435. byte* der; // DER-encoded ECC key.
  1436. word32 derSize; // Size of der.
  1437. const byte* curveOid = NULL; // OID of curve used by eccKey.
  1438. word32 curveOidSz = 0; // Size of curve OID.
  1439. byte* pkcs8; // Output buffer for PKCS#8 key.
  1440. word32 pkcs8Sz; // Size of output buffer.
  1441. derSize = wc_EccKeyDerSize(&eccKey, 1);
  1442. ...
  1443. derSize = wc_EccKeyToDer(&eccKey, der, derSize);
  1444. ...
  1445. ret = wc_ecc_get_oid(eccKey.dp->oidSum, &curveOid, &curveOidSz);
  1446. ...
  1447. ret = wc_CreatePKCS8Key(NULL, &pkcs8Sz, der,
  1448. derSize, ECDSAk, curveOid, curveOidSz); // Get size needed in pkcs8Sz.
  1449. ...
  1450. ret = wc_CreatePKCS8Key(pkcs8, &pkcs8Sz, der,
  1451. derSize, ECDSAk, curveOid, curveOidSz);
  1452. \endcode
  1453. \sa wc_GetPkcs8TraditionalOffset
  1454. \sa wc_EncryptPKCS8Key
  1455. \sa wc_DecryptPKCS8Key
  1456. \sa wc_CreateEncryptedPKCS8Key
  1457. */
  1458. int wc_CreatePKCS8Key(byte* out, word32* outSz,
  1459. byte* key, word32 keySz, int algoID, const byte* curveOID,
  1460. word32 oidSz);
  1461. /*!
  1462. \ingroup ASN
  1463. \brief This function takes in an unencrypted PKCS#8 DER key (e.g. one
  1464. created by wc_CreatePKCS8Key) and converts it to PKCS#8 encrypted format.
  1465. The resulting encrypted key can be decrypted using wc_DecryptPKCS8Key. See
  1466. RFC 5208.
  1467. \return The size of the encrypted key placed in out on success.
  1468. \return LENGTH_ONLY_E if out is NULL, with required output buffer size in
  1469. outSz.
  1470. \return Other negative values on failure.
  1471. \param key Buffer with traditional DER key.
  1472. \param keySz Size of key buffer.
  1473. \param out Buffer to place result in. If NULL, required out buffer size
  1474. returned in outSz.
  1475. \param outSz Size of out buffer.
  1476. \param password The password to use for the password-based encryption
  1477. algorithm.
  1478. \param passwordSz The length of the password (not including the NULL
  1479. terminator).
  1480. \param vPKCS The PKCS version to use. Can be 1 for PKCS12 or PKCS5.
  1481. \param pbeOid The OID of the PBE scheme to use (e.g. PBES2 or one of the
  1482. OIDs for PBES1 in RFC 2898 A.3).
  1483. \param encAlgId The encryption algorithm ID to use (e.g. AES256CBCb).
  1484. \param salt The salt buffer to use. If NULL, a random salt will be used.
  1485. \param saltSz The length of the salt buffer. Can be 0 if passing NULL for
  1486. salt.
  1487. \param itt The number of iterations to use for the KDF.
  1488. \param rng A pointer to an initialized WC_RNG object.
  1489. \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
  1490. _Example_
  1491. \code
  1492. byte* pkcs8; // Unencrypted PKCS#8 key.
  1493. word32 pkcs8Sz; // Size of pkcs8.
  1494. byte* pkcs8Enc; // Encrypted PKCS#8 key.
  1495. word32 pkcs8EncSz; // Size of pkcs8Enc.
  1496. const char* password; // Password to use for encryption.
  1497. int passwordSz; // Length of password (not including NULL terminator).
  1498. WC_RNG rng;
  1499. // The following produces an encrypted version of pkcs8 in pkcs8Enc. The
  1500. // encryption uses password-based encryption scheme 2 (PBE2) from PKCS#5 and
  1501. // the AES cipher in CBC mode with a 256-bit key. See RFC 8018 for more on
  1502. // PKCS#5.
  1503. ret = wc_EncryptPKCS8Key(pkcs8, pkcs8Sz, pkcs8Enc, &pkcs8EncSz, password,
  1504. passwordSz, PKCS5, PBES2, AES256CBCb, NULL, 0,
  1505. WC_PKCS12_ITT_DEFAULT, &rng, NULL);
  1506. \endcode
  1507. \sa wc_GetPkcs8TraditionalOffset
  1508. \sa wc_CreatePKCS8Key
  1509. \sa wc_DecryptPKCS8Key
  1510. \sa wc_CreateEncryptedPKCS8Key
  1511. */
  1512. int wc_EncryptPKCS8Key(byte* key, word32 keySz, byte* out,
  1513. word32* outSz, const char* password, int passwordSz, int vPKCS,
  1514. int pbeOid, int encAlgId, byte* salt, word32 saltSz, int itt,
  1515. WC_RNG* rng, void* heap);
  1516. /*!
  1517. \ingroup ASN
  1518. \brief This function takes an encrypted PKCS#8 DER key and decrypts it to
  1519. PKCS#8 unencrypted DER. Undoes the encryption done by wc_EncryptPKCS8Key.
  1520. See RFC5208. The input buffer is overwritten with the decrypted data.
  1521. \return The length of the decrypted buffer on success.
  1522. \return Negative values on failure.
  1523. \param input On input, buffer containing encrypted PKCS#8 key. On successful
  1524. output, contains the decrypted key.
  1525. \param sz Size of the input buffer.
  1526. \param password The password used to encrypt the key.
  1527. \param passwordSz The length of the password (not including NULL
  1528. terminator).
  1529. _Example_
  1530. \code
  1531. byte* pkcs8Enc; // Encrypted PKCS#8 key made with wc_EncryptPKCS8Key.
  1532. word32 pkcs8EncSz; // Size of pkcs8Enc.
  1533. const char* password; // Password to use for decryption.
  1534. int passwordSz; // Length of password (not including NULL terminator).
  1535. ret = wc_DecryptPKCS8Key(pkcs8Enc, pkcs8EncSz, password, passwordSz);
  1536. \endcode
  1537. \sa wc_GetPkcs8TraditionalOffset
  1538. \sa wc_CreatePKCS8Key
  1539. \sa wc_EncryptPKCS8Key
  1540. \sa wc_CreateEncryptedPKCS8Key
  1541. */
  1542. int wc_DecryptPKCS8Key(byte* input, word32 sz, const char* password,
  1543. int passwordSz);
  1544. /*!
  1545. \ingroup ASN
  1546. \brief This function takes a traditional, DER key, converts it to PKCS#8
  1547. format, and encrypts it. It uses wc_CreatePKCS8Key and wc_EncryptPKCS8Key
  1548. to do this.
  1549. \return The size of the encrypted key placed in out on success.
  1550. \return LENGTH_ONLY_E if out is NULL, with required output buffer size in
  1551. outSz.
  1552. \return Other negative values on failure.
  1553. \param key Buffer with traditional DER key.
  1554. \param keySz Size of key buffer.
  1555. \param out Buffer to place result in. If NULL, required out buffer size
  1556. returned in outSz.
  1557. \param outSz Size of out buffer.
  1558. \param password The password to use for the password-based encryption
  1559. algorithm.
  1560. \param passwordSz The length of the password (not including the NULL
  1561. terminator).
  1562. \param vPKCS The PKCS version to use. Can be 1 for PKCS12 or PKCS5.
  1563. \param pbeOid The OID of the PBE scheme to use (e.g. PBES2 or one of the
  1564. OIDs for PBES1 in RFC 2898 A.3).
  1565. \param encAlgId The encryption algorithm ID to use (e.g. AES256CBCb).
  1566. \param salt The salt buffer to use. If NULL, a random salt will be used.
  1567. \param saltSz The length of the salt buffer. Can be 0 if passing NULL for
  1568. salt.
  1569. \param itt The number of iterations to use for the KDF.
  1570. \param rng A pointer to an initialized WC_RNG object.
  1571. \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
  1572. _Example_
  1573. \code
  1574. byte* key; // Traditional private key (DER formatted).
  1575. word32 keySz; // Size of key.
  1576. byte* pkcs8Enc; // Encrypted PKCS#8 key.
  1577. word32 pkcs8EncSz; // Size of pkcs8Enc.
  1578. const char* password; // Password to use for encryption.
  1579. int passwordSz; // Length of password (not including NULL terminator).
  1580. WC_RNG rng;
  1581. // The following produces an encrypted, PKCS#8 version of key in pkcs8Enc.
  1582. // The encryption uses password-based encryption scheme 2 (PBE2) from PKCS#5
  1583. // and the AES cipher in CBC mode with a 256-bit key. See RFC 8018 for more
  1584. // on PKCS#5.
  1585. ret = wc_CreateEncryptedPKCS8Key(key, keySz, pkcs8Enc, &pkcs8EncSz,
  1586. password, passwordSz, PKCS5, PBES2, AES256CBCb, NULL, 0,
  1587. WC_PKCS12_ITT_DEFAULT, &rng, NULL);
  1588. \endcode
  1589. \sa wc_GetPkcs8TraditionalOffset
  1590. \sa wc_CreatePKCS8Key
  1591. \sa wc_EncryptPKCS8Key
  1592. \sa wc_DecryptPKCS8Key
  1593. */
  1594. int wc_CreateEncryptedPKCS8Key(byte* key, word32 keySz, byte* out,
  1595. word32* outSz, const char* password, int passwordSz, int vPKCS,
  1596. int pbeOid, int encAlgId, byte* salt, word32 saltSz, int itt,
  1597. WC_RNG* rng, void* heap);
  1598. /*!
  1599. \ingroup ASN
  1600. \brief This function initializes the DecodedCert pointed to by the "cert"
  1601. parameter. It saves the "source" pointer to a DER-encoded certificate of
  1602. length "inSz." This certificate can be parsed by a subsequent call to
  1603. wc_ParseCert.
  1604. \param cert Pointer to an allocated DecodedCert object.
  1605. \param source Pointer to a DER-encoded certificate.
  1606. \param inSz Length of the DER-encoded certificate in bytes.
  1607. \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
  1608. _Example_
  1609. \code
  1610. DecodedCert decodedCert; // Decoded certificate object.
  1611. byte* certBuf; // DER-encoded certificate buffer.
  1612. word32 certBufSz; // Size of certBuf in bytes.
  1613. wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
  1614. \endcode
  1615. \sa wc_ParseCert
  1616. \sa wc_FreeDecodedCert
  1617. */
  1618. void wc_InitDecodedCert(struct DecodedCert* cert,
  1619. const byte* source, word32 inSz, void* heap);
  1620. /*!
  1621. \ingroup ASN
  1622. \brief This function parses the DER-encoded certificate saved in the
  1623. DecodedCert object and populates the fields of that object. The DecodedCert
  1624. must have been initialized with a prior call to wc_InitDecodedCert. This
  1625. function takes an optional pointer to a CertificateManager object, which
  1626. is used to populate the certificate authority information of the
  1627. DecodedCert, if the CA is found in the CertificateManager.
  1628. \return 0 on success.
  1629. \return Other negative values on failure.
  1630. \param cert Pointer to an initialized DecodedCert object.
  1631. \param type Type of certificate. See the CertType enum in asn_public.h.
  1632. \param verify Flag that, if set, indicates the user wants to verify the
  1633. validity of the certificate.
  1634. \param cm An optional pointer to a CertificateManager. Can be NULL.
  1635. _Example_
  1636. \code
  1637. int ret;
  1638. DecodedCert decodedCert; // Decoded certificate object.
  1639. byte* certBuf; // DER-encoded certificate buffer.
  1640. word32 certBufSz; // Size of certBuf in bytes.
  1641. wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
  1642. ret = wc_ParseCert(&decodedCert, CERT_TYPE, NO_VERIFY, NULL);
  1643. if (ret != 0) {
  1644. fprintf(stderr, "wc_ParseCert failed.\n");
  1645. }
  1646. \endcode
  1647. \sa wc_InitDecodedCert
  1648. \sa wc_FreeDecodedCert
  1649. */
  1650. int wc_ParseCert(DecodedCert* cert, int type, int verify, void* cm);
  1651. /*!
  1652. \ingroup ASN
  1653. \brief This function frees a DecodedCert that was previously initialized
  1654. with wc_InitDecodedCert.
  1655. \param cert Pointer to an initialized DecodedCert object.
  1656. _Example_
  1657. \code
  1658. int ret;
  1659. DecodedCert decodedCert; // Decoded certificate object.
  1660. byte* certBuf; // DER-encoded certificate buffer.
  1661. word32 certBufSz; // Size of certBuf in bytes.
  1662. wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
  1663. ret = wc_ParseCert(&decodedCert, CERT_TYPE, NO_VERIFY, NULL);
  1664. if (ret != 0) {
  1665. fprintf(stderr, "wc_ParseCert failed.\n");
  1666. }
  1667. wc_FreeDecodedCert(&decodedCert);
  1668. \endcode
  1669. \sa wc_InitDecodedCert
  1670. \sa wc_ParseCert
  1671. */
  1672. void wc_FreeDecodedCert(struct DecodedCert* cert);
  1673. /*!
  1674. \ingroup ASN
  1675. \brief This function registers a time callback that will be used anytime
  1676. wolfSSL needs to get the current time. The prototype of the callback should
  1677. be the same as the "time" function from the C standard library.
  1678. \return 0 Returned on success.
  1679. \param f function to register as the time callback.
  1680. _Example_
  1681. \code
  1682. int ret = 0;
  1683. // Time callback prototype
  1684. time_t my_time_cb(time_t* t);
  1685. // Register it
  1686. ret = wc_SetTimeCb(my_time_cb);
  1687. if (ret != 0) {
  1688. // failed to set time callback
  1689. }
  1690. time_t my_time_cb(time_t* t)
  1691. {
  1692. // custom time function
  1693. }
  1694. \endcode
  1695. \sa wc_Time
  1696. */
  1697. int wc_SetTimeCb(wc_time_cb f);
  1698. /*!
  1699. \ingroup ASN
  1700. \brief This function gets the current time. By default, it uses the XTIME
  1701. macro, which varies between platforms. The user can use a function of their
  1702. choosing instead via the wc_SetTimeCb function.
  1703. \return Time Current time returned on success.
  1704. \param t Optional time_t pointer to populate with current time.
  1705. _Example_
  1706. \code
  1707. time_t currentTime = 0;
  1708. currentTime = wc_Time(NULL);
  1709. wc_Time(&currentTime);
  1710. \endcode
  1711. \sa wc_SetTimeCb
  1712. */
  1713. time_t wc_Time(time_t* t);
  1714. /*!
  1715. \ingroup ASN
  1716. \brief This function injects a custom extension in to an X.509 certificate.
  1717. note: The content at the address pointed to by any of the parameters that
  1718. are pointers must not be modified until the certificate is generated
  1719. and you have the der output. This function does NOT copy the
  1720. contents to another buffer.
  1721. \return 0 Returned on success.
  1722. \return Other negative values on failure.
  1723. \param cert Pointer to an initialized DecodedCert object.
  1724. \param critical If 0, the extension will not be marked critical, otherwise
  1725. it will be marked critical.
  1726. \param oid Dot separated oid as a string. For example "1.2.840.10045.3.1.7"
  1727. \param der The der encoding of the content of the extension.
  1728. \param derSz The size in bytes of the der encoding.
  1729. _Example_
  1730. \code
  1731. int ret = 0;
  1732. Cert newCert;
  1733. wc_InitCert(&newCert);
  1734. // Code to setup subject, public key, issuer, and other things goes here.
  1735. ret = wc_SetCustomExtension(&newCert, 1, "1.2.3.4.5",
  1736. (const byte *)"This is a critical extension", 28);
  1737. if (ret < 0) {
  1738. // Failed to set the extension.
  1739. }
  1740. ret = wc_SetCustomExtension(&newCert, 0, "1.2.3.4.6",
  1741. (const byte *)"This is NOT a critical extension", 32)
  1742. if (ret < 0) {
  1743. // Failed to set the extension.
  1744. }
  1745. // Code to sign the certificate and then write it out goes here.
  1746. \endcode
  1747. \sa wc_InitCert
  1748. \sa wc_SetUnknownExtCallback
  1749. */
  1750. int wc_SetCustomExtension(Cert *cert, int critical, const char *oid,
  1751. const byte *der, word32 derSz);
  1752. /*!
  1753. \ingroup ASN
  1754. \brief This function registers a callback that will be used anytime
  1755. wolfSSL encounters an unknown X.509 extension in a certificate while parsing
  1756. a certificate. The prototype of the callback should be:
  1757. \return 0 Returned on success.
  1758. \return Other negative values on failure.
  1759. \param cert the DecodedCert struct that is to be associated with this
  1760. callback.
  1761. \param cb function to register as the time callback.
  1762. _Example_
  1763. \code
  1764. int ret = 0;
  1765. // Unknown extension callback prototype
  1766. int myUnknownExtCallback(const word16* oid, word32 oidSz, int crit,
  1767. const unsigned char* der, word32 derSz);
  1768. // Register it
  1769. ret = wc_SetUnknownExtCallback(cert, myUnknownExtCallback);
  1770. if (ret != 0) {
  1771. // failed to set the callback
  1772. }
  1773. // oid: Array of integers that are the dot separated values in an oid.
  1774. // oidSz: Number of values in oid.
  1775. // crit: Whether the extension was mark critical.
  1776. // der: The der encoding of the content of the extension.
  1777. // derSz: The size in bytes of the der encoding.
  1778. int myCustomExtCallback(const word16* oid, word32 oidSz, int crit,
  1779. const unsigned char* der, word32 derSz) {
  1780. // Logic to parse extension goes here.
  1781. // NOTE: by returning zero, we are accepting this extension and
  1782. // informing wolfSSL that it is acceptable. If you find an extension
  1783. // that you do not find acceptable, you should return an error. The
  1784. // standard behavior upon encountering an unknown extension with the
  1785. // critical flag set is to return ASN_CRIT_EXT_E. For the sake of
  1786. // brevity, this example is always accepting every extension; you
  1787. // should use different logic.
  1788. return 0;
  1789. }
  1790. \endcode
  1791. \sa ParseCert
  1792. \sa wc_SetCustomExtension
  1793. */
  1794. int wc_SetUnknownExtCallback(DecodedCert* cert,
  1795. wc_UnknownExtCallback cb);
  1796. /*!
  1797. \ingroup ASN
  1798. \brief This function verifies the signature in the der form of an X.509
  1799. certificate against a public key. The public key is expected to be the full
  1800. subject public key info in der form.
  1801. \return 0 Returned on success.
  1802. \return Other negative values on failure.
  1803. \param cert The der encoding of the X.509 certificate.
  1804. \param certSz The size in bytes of cert.
  1805. \param heap A pointer to the heap used for dynamic allocation. Can be NULL.
  1806. \param pubKey The der encoding of the public key.
  1807. \param pubKeySz The size in bytes of pubKey.
  1808. \param pubKeyOID OID identifying the algorithm of the public key.
  1809. (ie: ECDSAk, DSAk or RSAk)
  1810. */
  1811. int wc_CheckCertSigPubKey(const byte* cert, word32 certSz,
  1812. void* heap, const byte* pubKey,
  1813. word32 pubKeySz, int pubKeyOID);
  1814. /*!
  1815. \ingroup ASN
  1816. \brief This function initializes the ASN.1 print options.
  1817. \return 0 on success.
  1818. \return BAD_FUNC_ARG when asn1 is NULL.
  1819. \param opts The ASN.1 options for printing.
  1820. _Example_
  1821. \code
  1822. Asn1PrintOptions opt;
  1823. // Initialize ASN.1 print options before use.
  1824. wc_Asn1PrintOptions_Init(&opt);
  1825. \endcode
  1826. \sa wc_Asn1PrintOptions_Set
  1827. \sa wc_Asn1_PrintAll
  1828. */
  1829. int wc_Asn1PrintOptions_Init(Asn1PrintOptions* opts);
  1830. /*!
  1831. \ingroup ASN
  1832. \brief This function sets a print option into an ASN.1 print options object.
  1833. \return 0 on success.
  1834. \return BAD_FUNC_ARG when asn1 is NULL.
  1835. \return BAD_FUNC_ARG when val is out of range for option.
  1836. \param opts The ASN.1 options for printing.
  1837. \param opt An option to set value for.
  1838. \param val The value to set.
  1839. _Example_
  1840. \code
  1841. Asn1PrintOptions opt;
  1842. // Initialize ASN.1 print options before use.
  1843. wc_Asn1PrintOptions_Init(&opt);
  1844. // Set the number of indents when printing tag name to be 1.
  1845. wc_Asn1PrintOptions_Set(&opt, ASN1_PRINT_OPT_INDENT, 1);
  1846. \endcode
  1847. \sa wc_Asn1PrintOptions_Init
  1848. \sa wc_Asn1_PrintAll
  1849. */
  1850. int wc_Asn1PrintOptions_Set(Asn1PrintOptions* opts, enum Asn1PrintOpt opt,
  1851. word32 val);
  1852. /*!
  1853. \ingroup ASN
  1854. \brief This function initializes an ASN.1 parsing object.
  1855. \return 0 on success.
  1856. \return BAD_FUNC_ARG when asn1 is NULL.
  1857. \param asn1 ASN.1 parse object.
  1858. _Example_
  1859. \code
  1860. Asn1 asn1;
  1861. // Initialize ASN.1 parse object before use.
  1862. wc_Asn1_Init(&asn1);
  1863. \endcode
  1864. \sa wc_Asn1_SetFile
  1865. \sa wc_Asn1_PrintAll
  1866. */
  1867. int wc_Asn1_Init(Asn1* asn1);
  1868. /*!
  1869. \ingroup ASN
  1870. \brief This function sets the file to use when printing into an ASN.1
  1871. parsing object.
  1872. \return 0 on success.
  1873. \return BAD_FUNC_ARG when asn1 is NULL.
  1874. \return BAD_FUNC_ARG when file is XBADFILE.
  1875. \param asn1 The ASN.1 parse object.
  1876. \param file File to print to.
  1877. _Example_
  1878. \code
  1879. Asn1 asn1;
  1880. // Initialize ASN.1 parse object before use.
  1881. wc_Asn1_Init(&asn1);
  1882. // Set standard out to be the file descriptor to write to.
  1883. wc_Asn1_SetFile(&asn1, stdout);
  1884. \endcode
  1885. \sa wc_Asn1_Init
  1886. \sa wc_Asn1_PrintAll
  1887. */
  1888. int wc_Asn1_SetFile(Asn1* asn1, XFILE file);
  1889. /*!
  1890. \ingroup ASN
  1891. \brief Print all ASN.1 items.
  1892. \return 0 on success.
  1893. \return BAD_FUNC_ARG when asn1 or opts is NULL.
  1894. \return ASN_LEN_E when ASN.1 item's length too long.
  1895. \return ASN_DEPTH_E when end offset invalid.
  1896. \return ASN_PARSE_E when not all of an ASN.1 item parsed.
  1897. \param asn1 The ASN.1 parse object.
  1898. \param opts The ASN.1 print options.
  1899. \param data Buffer containing BER/DER data to print.
  1900. \param len Length of data to print in bytes.
  1901. \code
  1902. Asn1PrintOptions opts;
  1903. Asn1 asn1;
  1904. unsigned char data[] = { Initialize with DER/BER data };
  1905. word32 len = sizeof(data);
  1906. // Initialize ASN.1 print options before use.
  1907. wc_Asn1PrintOptions_Init(&opt);
  1908. // Set the number of indents when printing tag name to be 1.
  1909. wc_Asn1PrintOptions_Set(&opt, ASN1_PRINT_OPT_INDENT, 1);
  1910. // Initialize ASN.1 parse object before use.
  1911. wc_Asn1_Init(&asn1);
  1912. // Set standard out to be the file descriptor to write to.
  1913. wc_Asn1_SetFile(&asn1, stdout);
  1914. // Print all ASN.1 items in buffer with the specified print options.
  1915. wc_Asn1_PrintAll(&asn1, &opts, data, len);
  1916. \endcode
  1917. \sa wc_Asn1_Init
  1918. \sa wc_Asn1_SetFile
  1919. */
  1920. int wc_Asn1_PrintAll(Asn1* asn1, Asn1PrintOptions* opts, unsigned char* data,
  1921. word32 len);