asn_public.h 57 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631
  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. WOLFSSL_API int wc_InitCert(Cert*);
  18. /*!
  19. \ingroup ASN
  20. \brief Used to make CA signed certs. Called after the subject information
  21. has been entered. This function makes an x509 Certificate v3 RSA or ECC
  22. from a cert input. It then writes this cert to derBuffer. It takes in
  23. either an rsaKey or an eccKey to generate the certificate. The certificate
  24. must be initialized with wc_InitCert before this method is called.
  25. \return Success On successfully making an x509 certificate from the
  26. specified input cert, returns the size of the cert generated.
  27. \return MEMORY_E Returned if there is an error allocating memory
  28. with XMALLOC
  29. \return BUFFER_E Returned if the provided derBuffer is too small to
  30. store the generated certificate
  31. \return Others Additional error messages may be returned if the cert
  32. generation is not successful.
  33. \param cert pointer to an initialized cert structure
  34. \param derBuffer pointer to the buffer in which to hold the generated cert
  35. \param derSz size of the buffer in which to store the cert
  36. \param rsaKey pointer to an RsaKey structure containing the rsa key used
  37. to generate the certificate
  38. \param eccKey pointer to an EccKey structure containing the ecc key used
  39. to generate the certificate
  40. \param rng pointer to the random number generator used to make the cert
  41. _Example_
  42. \code
  43. Cert myCert;
  44. wc_InitCert(&myCert);
  45. WC_RNG rng;
  46. //initialize rng;
  47. RsaKey key;
  48. //initialize key;
  49. byte * derCert = malloc(FOURK_BUF);
  50. word32 certSz;
  51. certSz = wc_MakeCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
  52. \endcode
  53. \sa wc_InitCert
  54. \sa wc_MakeCertReq
  55. */
  56. WOLFSSL_API int wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
  57. ecc_key*, WC_RNG*);
  58. /*!
  59. \ingroup ASN
  60. \brief This function makes a certificate signing request using the input
  61. certificate and writes the output to derBuffer. It takes in either an
  62. rsaKey or an eccKey to generate the certificate request. wc_SignCert()
  63. will need to be called after this function to sign the certificate request.
  64. Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an
  65. example usage of this function.
  66. \return Success On successfully making an X.509 certificate request from
  67. the specified input cert, returns the size of the certificate
  68. request 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 store
  72. the generated certificate
  73. \return Other Additional error messages may be returned if the certificate
  74. request 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
  77. certificate request
  78. \param derSz size of the buffer in which to store the certificate request
  79. \param rsaKey pointer to an RsaKey structure containing the rsa key used
  80. to generate the certificate request
  81. \param eccKey pointer to an EccKey structure containing the ecc key used
  82. to generate the certificate request
  83. _Example_
  84. \code
  85. Cert myCert;
  86. // initialize myCert
  87. EccKey key;
  88. //initialize key;
  89. byte* derCert = (byte*)malloc(FOURK_BUF);
  90. word32 certSz;
  91. certSz = wc_MakeCertReq(&myCert, derCert, FOURK_BUF, NULL, &key);
  92. \endcode
  93. \sa wc_InitCert
  94. \sa wc_MakeCert
  95. */
  96. WOLFSSL_API int wc_MakeCertReq(Cert*, byte* derBuffer, word32 derSz,
  97. RsaKey*, ecc_key*);
  98. /*!
  99. \ingroup ASN
  100. \brief This function signs buffer and adds the signature to the end of
  101. buffer. It takes in a signature type. Must be called after wc_MakeCert()
  102. or wc_MakeCertReq() if creating a CA signed cert.
  103. \return Success On successfully signing the certificate, returns the new
  104. size of the cert (including signature).
  105. \return MEMORY_E Returned if there is an error allocating
  106. memory with XMALLOC
  107. \return BUFFER_E Returned if the provided buffer is too small to store
  108. the generated certificate
  109. \return Other Additional error messages may be returned if the cert
  110. generation is not successful.
  111. \param requestSz the size of the certificate body we’re requesting
  112. to have signed
  113. \param sType Type of signature to create. Valid options are: CTC_MD5wRSA,
  114. CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, andCTC_SHA256wRSA
  115. \param buffer pointer to the buffer containing the certificate to be
  116. signed. On success: will hold the newly signed certificate
  117. \param buffSz the (total) size of the buffer in which to store the newly
  118. signed certificate
  119. \param rsaKey pointer to an RsaKey structure containing the rsa key
  120. to used to sign the certificate
  121. \param eccKey pointer to an EccKey structure containing the ecc key
  122. to used to sign the certificate
  123. \param rng pointer to the random number generator used to sign
  124. the certificate
  125. _Example_
  126. \code
  127. Cert myCert;
  128. byte* derCert = (byte*)malloc(FOURK_BUF);
  129. // initialize myCert, derCert
  130. RsaKey key;
  131. // initialize key;
  132. WC_RNG rng;
  133. // initialize rng
  134. word32 certSz;
  135. certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF,
  136. &key, NULL,
  137. &rng);
  138. \endcode
  139. \sa wc_InitCert
  140. \sa wc_MakeCert
  141. */
  142. WOLFSSL_API int wc_SignCert(int requestSz, int sigType, byte* derBuffer,
  143. word32 derSz, RsaKey*, ecc_key*, WC_RNG*);
  144. /*!
  145. \ingroup ASN
  146. \brief This function is a combination of the previous two functions,
  147. wc_MakeCert and wc_SignCert for self signing (the previous functions may
  148. be used for CA requests). It makes a certificate, and then signs it,
  149. generating a self-signed certificate.
  150. \return Success On successfully signing the certificate, returns the
  151. new size of the cert.
  152. \return MEMORY_E Returned if there is an error allocating memory
  153. with XMALLOC
  154. \return BUFFER_E Returned if the provided buffer is too small to store
  155. the generated certificate
  156. \return Other Additional error messages may be returned if the cert
  157. generation is not successful.
  158. \param cert pointer to the cert to make and sign
  159. \param buffer pointer to the buffer in which to hold the signed certificate
  160. \param buffSz size of the buffer in which to store the signed certificate
  161. \param key pointer to an RsaKey structure containing the rsa key to
  162. used to sign the certificate
  163. \param rng pointer to the random number generator used to generate
  164. and sign the certificate
  165. _Example_
  166. \code
  167. Cert myCert;
  168. byte* derCert = (byte*)malloc(FOURK_BUF);
  169. // initialize myCert, derCert
  170. RsaKey key;
  171. // initialize key;
  172. WC_RNG rng;
  173. // initialize rng
  174. word32 certSz;
  175. certSz = wc_MakeSelfCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
  176. \endcode
  177. \sa wc_InitCert
  178. \sa wc_MakeCert
  179. \sa wc_SignCert
  180. */
  181. WOLFSSL_API int wc_MakeSelfCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
  182. WC_RNG*);
  183. /*!
  184. \ingroup ASN
  185. \brief This function sets the issuer for a certificate to the issuer
  186. in the provided pem issuerFile. It also changes the certificate’s
  187. self-signed attribute to false. The issuer specified in issuerFile is
  188. verified prior to setting the cert issuer. This method is used to set
  189. fields prior to signing.
  190. \return 0 Returned on successfully setting the issuer for the certificate
  191. \return MEMORY_E Returned if there is an error allocating memory
  192. with XMALLOC
  193. \return ASN_PARSE_E Returned if there is an error parsing the
  194. cert header file
  195. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  196. encryption type from the cert
  197. \return ASN_EXPECT_0_E Returned if there is a formatting error in
  198. the encryption specification of the cert file
  199. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  200. start date
  201. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  202. expiration date
  203. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  204. from the certificate
  205. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  206. from the certificate
  207. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  208. from the certificate
  209. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  210. key object id
  211. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  212. defined and the certificate is a V1 or V2 certificate
  213. \return BAD_FUNC_ARG Returned if there is an error processing the
  214. certificate extension
  215. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  216. encountered in processing the certificate
  217. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  218. the same as the encryption type of the certificate in the provided file
  219. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  220. signature fails
  221. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  222. permitted by the CA name constraints
  223. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
  224. the certificate’s authenticity
  225. \param cert pointer to the cert for which to set the issuer
  226. \param issuerFile path of the file containing the pem formatted certificate
  227. _Example_
  228. \code
  229. Cert myCert;
  230. // initialize myCert
  231. if(wc_SetIssuer(&myCert, ”./path/to/ca-cert.pem”) != 0) {
  232. // error setting issuer
  233. }
  234. \endcode
  235. \sa wc_InitCert
  236. \sa wc_SetSubject
  237. \sa wc_SetIssuerBuffer
  238. */
  239. WOLFSSL_API int wc_SetIssuer(Cert*, const char*);
  240. /*!
  241. \ingroup ASN
  242. \brief This function sets the subject for a certificate to the subject
  243. in the provided pem subjectFile. This method is used to set fields prior
  244. to signing.
  245. \return 0 Returned on successfully setting the issuer for the certificate
  246. \return MEMORY_E Returned if there is an error allocating memory with XMALLOC
  247. \return ASN_PARSE_E Returned if there is an error parsing the cert
  248. header file
  249. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  250. encryption type from the cert
  251. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  252. encryption specification of the cert file
  253. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  254. start date
  255. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  256. expiration date
  257. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  258. from the certificate
  259. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  260. from the certificate
  261. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  262. from the certificate
  263. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  264. key object id
  265. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  266. defined and the certificate is a V1 or V2 certificate
  267. \return BAD_FUNC_ARG Returned if there is an error processing the
  268. certificate extension
  269. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  270. encountered in processing the certificate
  271. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  272. the same as the encryption type of the certificate in the provided file
  273. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  274. signature fails
  275. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  276. permitted by the CA name constraints
  277. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  278. certificate’s authenticity
  279. \param cert pointer to the cert for which to set the issuer
  280. \param subjectFile path of the file containing the pem formatted certificate
  281. _Example_
  282. \code
  283. Cert myCert;
  284. // initialize myCert
  285. if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
  286. // error setting subject
  287. }
  288. \endcode
  289. \sa wc_InitCert
  290. \sa wc_SetIssuer
  291. */
  292. WOLFSSL_API int wc_SetSubject(Cert*, const char*);
  293. /*!
  294. \ingroup ASN
  295. \brief This function sets the raw subject for a certificate from the
  296. subject in the provided der buffer. This method is used to set the raw
  297. subject field prior to signing.
  298. \return 0 Returned on successfully setting the subject for the certificate
  299. \return MEMORY_E Returned if there is an error allocating memory
  300. with XMALLOC
  301. \return ASN_PARSE_E Returned if there is an error parsing the cert
  302. header file
  303. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  304. encryption type from the cert
  305. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  306. encryption specification of the cert file
  307. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  308. start date
  309. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  310. expiration date
  311. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  312. from the certificate
  313. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  314. from the certificate
  315. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  316. from the certificate
  317. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  318. key object id
  319. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  320. defined and the certificate is a V1 or V2 certificate
  321. \return BAD_FUNC_ARG Returned if there is an error processing the
  322. certificate extension
  323. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  324. encountered in processing the certificate
  325. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  326. the same as the encryption type of the certificate in the provided file
  327. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  328. signature fails
  329. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  330. permitted by the CA name constraints
  331. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  332. certificate’s authenticity
  333. \param cert pointer to the cert for which to set the raw subject
  334. \param der pointer to the buffer containing the der formatted certificate
  335. from which to grab the subject
  336. \param derSz size of the buffer containing the der formatted certificate
  337. from which to grab the subject
  338. _Example_
  339. \code
  340. Cert myCert;
  341. // initialize myCert
  342. byte* der;
  343. der = (byte*)malloc(FOURK_BUF);
  344. // initialize der
  345. if(wc_SetSubjectRaw(&myCert, der, FOURK_BUF) != 0) {
  346. // error setting subject
  347. }
  348. \endcode
  349. \sa wc_InitCert
  350. \sa wc_SetSubject
  351. */
  352. WOLFSSL_API int wc_SetSubjectRaw(Cert* cert, const byte* der, int derSz);
  353. /*!
  354. \ingroup ASN
  355. \brief This function gets the raw subject from the certificate structure.
  356. \return 0 Returned on successfully getting the subject from the certificate
  357. \return BAD_FUNC_ARG Returned if there is an error processing the
  358. certificate extension
  359. \param subjectRaw pointer-pointer to the raw subject upon successful return
  360. \param cert pointer to the cert from which to get the raw subject
  361. _Example_
  362. \code
  363. Cert myCert;
  364. byte *subjRaw;
  365. // initialize myCert
  366. if(wc_GetSubjectRaw(&subjRaw, &myCert) != 0) {
  367. // error setting subject
  368. }
  369. \endcode
  370. \sa wc_InitCert
  371. \sa wc_SetSubjectRaw
  372. */
  373. WOLFSSL_API int wc_GetSubjectRaw(byte **subjectRaw, Cert *cert);
  374. /*!
  375. \ingroup ASN
  376. \brief This function sets the alternate names for a certificate to the
  377. alternate names in the provided pem file. This is useful in the case that
  378. one wishes to secure multiple domains with the same certificate. This
  379. method is used to set fields prior to signing.
  380. \return 0 Returned on successfully setting the alt names for the certificate
  381. \return MEMORY_E Returned if there is an error allocating memory
  382. with XMALLOC
  383. \return ASN_PARSE_E Returned if there is an error parsing the cert
  384. header file
  385. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  386. encryption type from the cert
  387. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  388. encryption specification of the cert file
  389. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  390. start date
  391. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  392. expiration date
  393. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  394. from the certificate
  395. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  396. from the certificate
  397. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  398. from the certificate
  399. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  400. key object id
  401. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  402. defined and the certificate is a V1 or V2 certificate
  403. \return BAD_FUNC_ARG Returned if there is an error processing the
  404. certificate extension
  405. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  406. encountered in processing the certificate
  407. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  408. the same as the encryption type of the certificate in the provided file
  409. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  410. signature fails
  411. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  412. permitted by the CA name constraints
  413. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  414. certificate’s authenticity
  415. \param cert pointer to the cert for which to set the alt names
  416. \param file path of the file containing the pem formatted certificate
  417. _Example_
  418. \code
  419. Cert myCert;
  420. // initialize myCert
  421. if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
  422. // error setting alt names
  423. }
  424. \endcode
  425. \sa wc_InitCert
  426. \sa wc_SetIssuer
  427. */
  428. WOLFSSL_API int wc_SetAltNames(Cert*, const char*);
  429. /*!
  430. \ingroup ASN
  431. \brief This function sets the issuer for a certificate from the issuer in
  432. the provided der buffer. It also changes the certificate’s self-signed
  433. attribute to false. This method is used to set fields prior to signing.
  434. \return 0 Returned on successfully setting the issuer for the certificate
  435. \return MEMORY_E Returned if there is an error allocating memory
  436. with XMALLOC
  437. \return ASN_PARSE_E Returned if there is an error parsing the cert
  438. header file
  439. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  440. encryption type from the cert
  441. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  442. encryption specification of the cert file
  443. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  444. start date
  445. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  446. expiration date
  447. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  448. from the certificate
  449. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU
  450. key from the certificate
  451. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC
  452. key from the certificate
  453. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  454. key object id
  455. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  456. defined and the certificate is a V1 or V2 certificate
  457. \return BAD_FUNC_ARG Returned if there is an error processing the
  458. certificate extension
  459. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  460. encountered in processing the certificate
  461. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  462. the same as the encryption type of the certificate in the provided file
  463. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  464. signature fails
  465. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  466. permitted by the CA name constraints
  467. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
  468. the certificate’s authenticity
  469. \param cert pointer to the cert for which to set the issuer
  470. \param der pointer to the buffer containing the der formatted certificate
  471. from which to grab the issuer
  472. \param derSz size of the buffer containing the der formatted certificate
  473. from which to grab the issuer
  474. _Example_
  475. \code
  476. Cert myCert;
  477. // initialize myCert
  478. byte* der;
  479. der = (byte*)malloc(FOURK_BUF);
  480. // initialize der
  481. if(wc_SetIssuerBuffer(&myCert, der, FOURK_BUF) != 0) {
  482. // error setting issuer
  483. }
  484. \endcode
  485. \sa wc_InitCert
  486. \sa wc_SetIssuer
  487. */
  488. WOLFSSL_API int wc_SetIssuerBuffer(Cert*, const byte*, int);
  489. /*!
  490. \ingroup ASN
  491. \brief This function sets the raw issuer for a certificate from the
  492. issuer in the provided der buffer. This method is used to set the raw
  493. issuer field prior to signing.
  494. \return 0 Returned on successfully setting the issuer for the certificate
  495. \return MEMORY_E Returned if there is an error allocating memory
  496. with XMALLOC
  497. \return ASN_PARSE_E Returned if there is an error parsing the cert
  498. header file
  499. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  500. encryption type from the cert
  501. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  502. encryption specification of the cert file
  503. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  504. start date
  505. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  506. expiration date
  507. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  508. from the certificate
  509. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  510. from the certificate
  511. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  512. from the certificate
  513. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  514. key object id
  515. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  516. defined and the certificate is a V1 or V2 certificate
  517. \return BAD_FUNC_ARG Returned if there is an error processing the
  518. certificate extension
  519. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  520. encountered in processing the certificate
  521. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  522. the same as the encryption type of the certificate in the provided file
  523. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  524. signature fails
  525. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  526. permitted by the CA name constraints
  527. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  528. certificate’s authenticity
  529. \param cert pointer to the cert for which to set the raw issuer
  530. \param der pointer to the buffer containing the der formatted certificate
  531. from which to grab the subject
  532. \param derSz size of the buffer containing the der formatted certificate
  533. from which to grab the subject
  534. _Example_
  535. \code
  536. Cert myCert;
  537. // initialize myCert
  538. byte* der;
  539. der = (byte*)malloc(FOURK_BUF);
  540. // initialize der
  541. if(wc_SetIssuerRaw(&myCert, der, FOURK_BUF) != 0) {
  542. // error setting subject
  543. }
  544. \endcode
  545. \sa wc_InitCert
  546. \sa wc_SetIssuer
  547. */
  548. WOLFSSL_API int wc_SetIssuerRaw(Cert* cert, const byte* der, int derSz);
  549. /*!
  550. \ingroup ASN
  551. \brief This function sets the subject for a certificate from the subject in
  552. the provided der buffer. This method is used to set fields prior to signing.
  553. \return 0 Returned on successfully setting the subject for the certificate
  554. \return MEMORY_E Returned if there is an error allocating memory
  555. with XMALLOC
  556. \return ASN_PARSE_E Returned if there is an error parsing the cert
  557. header file
  558. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  559. encryption type from the cert
  560. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  561. encryption specification of the cert file
  562. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  563. start date
  564. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  565. expiration date
  566. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  567. from the certificate
  568. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  569. from the certificate
  570. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  571. from the certificate
  572. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  573. key object id
  574. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  575. defined and the certificate is a V1 or V2 certificate
  576. \return BAD_FUNC_ARG Returned if there is an error processing the
  577. certificate extension
  578. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  579. encountered in processing the certificate
  580. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  581. the same as the encryption type of the certificate in the provided file
  582. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  583. signature fails
  584. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  585. permitted by the CA name constraints
  586. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  587. certificate’s authenticity
  588. \param cert pointer to the cert for which to set the subject
  589. \param der pointer to the buffer containing the der formatted certificate
  590. from which to grab the subject
  591. \param derSz size of the buffer containing the der formatted certificate
  592. from which to grab the subject
  593. _Example_
  594. \code
  595. Cert myCert;
  596. // initialize myCert
  597. byte* der;
  598. der = (byte*)malloc(FOURK_BUF);
  599. // initialize der
  600. if(wc_SetSubjectBuffer(&myCert, der, FOURK_BUF) != 0) {
  601. // error setting subject
  602. }
  603. \endcode
  604. \sa wc_InitCert
  605. \sa wc_SetSubject
  606. */
  607. WOLFSSL_API int wc_SetSubjectBuffer(Cert*, const byte*, int);
  608. /*!
  609. \ingroup ASN
  610. \brief This function sets the alternate names for a certificate from the
  611. alternate names in the provided der buffer. This is useful in the case that
  612. one wishes to secure multiple domains with the same certificate. This
  613. method is used to set fields prior to signing.
  614. \return 0 Returned on successfully setting the alternate names for the
  615. certificate
  616. \return MEMORY_E Returned if there is an error allocating memory with
  617. XMALLOC
  618. \return ASN_PARSE_E Returned if there is an error parsing the cert
  619. header file
  620. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  621. encryption type from the cert
  622. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  623. encryption specification of the cert file
  624. \return ASN_BEFORE_DATE_E Returned if the date is before the
  625. certificate start date
  626. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  627. expiration date
  628. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  629. from the certificate
  630. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  631. from the certificate
  632. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  633. from the certificate
  634. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  635. key object id
  636. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  637. defined and the certificate is a V1 or V2 certificate
  638. \return BAD_FUNC_ARG Returned if there is an error processing the
  639. certificate extension
  640. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  641. encountered in processing the certificate
  642. \return ASN_SIG_OID_E Returned if the signature encryption type is not the
  643. same as the encryption type of the certificate in the provided file
  644. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  645. signature fails
  646. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  647. permitted by the CA name constraints
  648. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  649. certificate’s authenticity
  650. \param cert pointer to the cert for which to set the alternate names
  651. \param der pointer to the buffer containing the der formatted certificate
  652. from which to grab the alternate names
  653. \param derSz size of the buffer containing the der formatted certificate
  654. from which to grab the alternate names
  655. _Example_
  656. \code
  657. Cert myCert;
  658. // initialize myCert
  659. byte* der;
  660. der = (byte*)malloc(FOURK_BUF);
  661. // initialize der
  662. if(wc_SetAltNamesBuffer(&myCert, der, FOURK_BUF) != 0) {
  663. // error setting subject
  664. }
  665. \endcode
  666. \sa wc_InitCert
  667. \sa wc_SetAltNames
  668. */
  669. WOLFSSL_API int wc_SetAltNamesBuffer(Cert*, const byte*, int);
  670. /*!
  671. \ingroup ASN
  672. \brief This function sets the dates for a certificate from the date range
  673. in the provided der buffer. This method is used to set fields prior
  674. to signing.
  675. \return 0 Returned on successfully setting the dates for the certificate
  676. \return MEMORY_E Returned if there is an error allocating memory
  677. with XMALLOC
  678. \return ASN_PARSE_E Returned if there is an error parsing the cert
  679. header file
  680. \return ASN_OBJECT_ID_E Returned if there is an error parsing the
  681. encryption type from the cert
  682. \return ASN_EXPECT_0_E Returned if there is a formatting error in the
  683. encryption specification of the cert file
  684. \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
  685. start date
  686. \return ASN_AFTER_DATE_E Returned if the date is after the certificate
  687. expiration date
  688. \return ASN_BITSTR_E Returned if there is an error parsing a bit string
  689. from the certificate
  690. \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key
  691. from the certificate
  692. \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key
  693. from the certificate
  694. \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
  695. key object id
  696. \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
  697. defined and the certificate is a V1 or V2 certificate
  698. \return BAD_FUNC_ARG Returned if there is an error processing the
  699. certificate extension
  700. \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
  701. encountered in processing the certificate
  702. \return ASN_SIG_OID_E Returned if the signature encryption type is not
  703. the same as the encryption type of the certificate in the provided file
  704. \return ASN_SIG_CONFIRM_E Returned if confirming the certification
  705. signature fails
  706. \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
  707. permitted by the CA name constraints
  708. \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the
  709. certificate’s authenticity
  710. \param cert pointer to the cert for which to set the dates
  711. \param der pointer to the buffer containing the der formatted certificate
  712. from which to grab the date range
  713. \param derSz size of the buffer containing the der formatted certificate
  714. from which to grab the date range
  715. _Example_
  716. \code
  717. Cert myCert;
  718. // initialize myCert
  719. byte* der;
  720. der = (byte*)malloc(FOURK_BUF);
  721. // initialize der
  722. if(wc_SetDatesBuffer(&myCert, der, FOURK_BUF) != 0) {
  723. // error setting subject
  724. }
  725. \endcode
  726. \sa wc_InitCert
  727. */
  728. WOLFSSL_API int wc_SetDatesBuffer(Cert*, const byte*, int);
  729. /*!
  730. \ingroup ASN
  731. \brief Set AKID from either an RSA or ECC public key. note: Only set one of
  732. rsakey or eckey, not both.
  733. \return 0 Success
  734. \return BAD_FUNC_ARG Either cert is null or both rsakey and eckey are null.
  735. \return MEMORY_E Error allocating memory.
  736. \return PUBLIC_KEY_E Error writing to the key.
  737. \param cert Pointer to the certificate to set the SKID.
  738. \param rsakey Pointer to the RsaKey struct to read from.
  739. \param eckey Pointer to the ecc_key to read from.
  740. _Example_
  741. \code
  742. Cert myCert;
  743. RsaKey keypub;
  744. wc_InitRsaKey(&keypub, 0);
  745. if (wc_SetAuthKeyIdFromPublicKey(&myCert, &keypub, NULL) != 0)
  746. {
  747. // Handle error
  748. }
  749. \endcode
  750. \sa wc_SetSubjectKeyId
  751. \sa wc_SetAuthKeyId
  752. \sa wc_SetAuthKeyIdFromCert
  753. */
  754. WOLFSSL_API int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
  755. ecc_key *eckey);
  756. /*!
  757. \ingroup ASN
  758. \brief Set AKID from from DER encoded certificate.
  759. \return 0 Success
  760. \return BAD_FUNC_ARG Error if any argument is null or derSz is less than 0.
  761. \return MEMORY_E Error if problem allocating memory.
  762. \return ASN_NO_SKID No subject key ID found.
  763. \param cert The Cert struct to write to.
  764. \param der The DER encoded certificate buffer.
  765. \param derSz Size of der in bytes.
  766. _Example_
  767. \code
  768. Cert some_cert;
  769. byte some_der[] = { // Initialize a DER buffer };
  770. wc_InitCert(&some_cert);
  771. if(wc_SetAuthKeyIdFromCert(&some_cert, some_der, sizeof(some_der) != 0)
  772. {
  773. // Handle error
  774. }
  775. \endcode
  776. \sa wc_SetAuthKeyIdFromPublicKey
  777. \sa wc_SetAuthKeyId
  778. */
  779. WOLFSSL_API int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz);
  780. /*!
  781. \ingroup ASN
  782. \brief Set AKID from certificate file in PEM format.
  783. \return 0 Success
  784. \return BAD_FUNC_ARG Error if cert or file is null.
  785. \return MEMORY_E Error if problem allocating memory.
  786. \param cert Cert struct you want to set the AKID of.
  787. \param file Buffer containing PEM cert file.
  788. _Example_
  789. \code
  790. char* file_name = "/path/to/file";
  791. cert some_cert;
  792. wc_InitCert(&some_cert);
  793. if(wc_SetAuthKeyId(&some_cert, file_name) != 0)
  794. {
  795. // Handle Error
  796. }
  797. \endcode
  798. \sa wc_SetAuthKeyIdFromPublicKey
  799. \sa wc_SetAuthKeyIdFromCert
  800. */
  801. WOLFSSL_API int wc_SetAuthKeyId(Cert *cert, const char* file);
  802. /*!
  803. \ingroup ASN
  804. \brief Set SKID from RSA or ECC public key.
  805. \return 0 Success
  806. \return BAD_FUNC_ARG Returned if cert or rsakey and eckey is null.
  807. \return MEMORY_E Returned if there is an error allocating memory.
  808. \return PUBLIC_KEY_E Returned if there is an error getting the public key.
  809. \param cert Pointer to a Cert structure to be used.
  810. \param rsakey Pointer to an RsaKey structure
  811. \param eckey Pointer to an ecc_key structure
  812. _Example_
  813. \code
  814. Cert some_cert;
  815. RsaKey some_key;
  816. wc_InitCert(&some_cert);
  817. wc_InitRsaKey(&some_key);
  818. if(wc_SetSubjectKeyIdFromPublicKey(&some_cert,&some_key, NULL) != 0)
  819. {
  820. // Handle Error
  821. }
  822. \endcode
  823. \sa wc_SetSubjectKeyId
  824. \sa wc_SetSubjectKeyIdFromNtruPublicKey
  825. */
  826. WOLFSSL_API int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
  827. ecc_key *eckey);
  828. /*!
  829. \ingroup ASN
  830. \brief Set SKID from public key file in PEM format. Both arguments
  831. are required.
  832. \return 0 Success
  833. \return BAD_FUNC_ARG Returns if cert or file is null.
  834. \return MEMORY_E Returns if there is a problem allocating memory for key.
  835. \return PUBLIC_KEY_E Returns if there is an error decoding the public key.
  836. \param cert Cert structure to set the SKID of.
  837. \param file Contains the PEM encoded file.
  838. _Example_
  839. \code
  840. const char* file_name = "path/to/file";
  841. Cert some_cert;
  842. wc_InitCert(&some_cert);
  843. if(wc_SetSubjectKeyId(&some_cert, file_name) != 0)
  844. {
  845. // Handle Error
  846. }
  847. \endcode
  848. \sa wc_SetSubjectKeyIdFromNtruPublicKey
  849. \sa wc_SetSubjectKeyIdFromPublicKey
  850. */
  851. WOLFSSL_API int wc_SetSubjectKeyId(Cert *cert, const char* file);
  852. /*!
  853. \ingroup ASN
  854. \brief Set SKID from NTRU public key.
  855. \return 0 Success
  856. \return BAD_FUNC_ARG Returned if cert or ntruKey is null.
  857. \return MEMORY_E Returned if there is an error allocating memory.
  858. \return PUBLIC_KEY_E Returned if there is an error getting the public key.
  859. \param cert Pointer to a Cert structure to be used.
  860. \param ntruKey Pointer to the NTRU public key in a byte array.
  861. \param ntruKeySz Size of the NTRU byte array.
  862. _Example_
  863. \code
  864. Cert some_cert;
  865. wc_InitCert(&some_cert);
  866. byte some_ntru_key[] = { // Load an NTRU key };
  867. word32 ntru_size = sizeof(some_ntru_key);
  868. if(wc_SetSubjectKeyIdFromNtruPublicKey(&some_cert,
  869. some_ntru_key, ntru_size) != 0)
  870. {
  871. // Handle error
  872. }
  873. \endcode
  874. \sa SetKeyIdFromPublicKey
  875. */
  876. WOLFSSL_API int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert, byte *ntruKey,
  877. word16 ntruKeySz);
  878. /*!
  879. \ingroup RSA
  880. \brief This function allows you to set the key usage using a comma
  881. delimited string of tokens. Accepted tokens are: digitalSignature,
  882. nonRepudiation, contentCommitment, keyCertSign, cRLSign, dataEncipherment,
  883. keyAgreement, keyEncipherment, encipherOnly, decipherOnly. Example:
  884. "digitalSignature,nonRepudiation" nonRepudiation and contentCommitment
  885. are for the same usage.
  886. \return 0 Success
  887. \return BAD_FUNC_ARG Returned when either arg is null.
  888. \return MEMORY_E Returned when there is an error allocating memory.
  889. \return KEYUSAGE_E Returned if an unrecognized token is entered.
  890. \param cert Pointer to initialized Cert structure.
  891. \param value Comma delimited string of tokens to set usage.
  892. _Example_
  893. \code
  894. Cert cert;
  895. wc_InitCert(&cert);
  896. if(wc_SetKeyUsage(&cert, "cRLSign,keyCertSign") != 0)
  897. {
  898. // Handle error
  899. }
  900. \endcode
  901. \sa wc_InitCert
  902. \sa wc_MakeRsaKey
  903. */
  904. WOLFSSL_API int wc_SetKeyUsage(Cert *cert, const char *value);
  905. /*!
  906. \ingroup ASN
  907. \brief Used to make CA signed certs. Called after the subject information
  908. has been entered. This function makes an NTRU Certificate from a cert
  909. input. It then writes this cert to derBuffer. It takes in an ntruKey and
  910. a rng to generate the certificate. The certificate must be initialized
  911. with wc_InitCert before this method is called.
  912. \return Success On successfully making a NTRU certificate from the
  913. specified input cert, returns the size of the cert generated.
  914. \return MEMORY_E Returned if there is an error allocating memory
  915. with XMALLOC
  916. \return BUFFER_E Returned if the provided derBuffer is too small to
  917. store the generated certificate
  918. \return Other Additional error messages may be returned if the cert
  919. generation is not successful.
  920. \param cert pointer to an initialized cert structure
  921. \param derBuffer pointer to the buffer in which to store
  922. the generated certificate
  923. \param derSz size of the buffer in which to store the generated
  924. certificate
  925. \param ntruKey pointer to the key to be used to generate the NTRU
  926. certificate
  927. \param keySz size of the key used to generate the NTRU certificate
  928. \param rng pointer to the random number generator used to generate
  929. the NTRU certificate
  930. _Example_
  931. \code
  932. Cert myCert;
  933. // initialize myCert
  934. WC_RNG rng;
  935. //initialize rng;
  936. byte ntruPublicKey[NTRU_KEY_SIZE];
  937. //initialize ntruPublicKey;
  938. byte * derCert = malloc(FOURK_BUF);
  939. word32 certSz;
  940. certSz = wc_MakeNtruCert(&myCert, derCert, FOURK_BUF, &ntruPublicKey,
  941. NTRU_KEY_SIZE, &rng);
  942. \endcode
  943. \sa wc_InitCert
  944. \sa wc_MakeCert
  945. */
  946. WOLFSSL_API int wc_MakeNtruCert(Cert*, byte* derBuffer, word32 derSz,
  947. const byte* ntruKey, word16 keySz,
  948. WC_RNG*);
  949. /*!
  950. \ingroup ASN
  951. \brief Loads a PEM key from a file and converts to a DER encoded buffer.
  952. \return 0 Success
  953. \return <0 Error
  954. \return SSL_BAD_FILE There is a problem with opening the file.
  955. \return MEMORY_E There is an error allocating memory for the file buffer.
  956. \return BUFFER_E derBuf is not large enough to hold the converted key.
  957. \param fileName Name of the file to load.
  958. \param derBuf Buffer for DER encoded key.
  959. \param derSz Size of DER buffer.
  960. _Example_
  961. \code
  962. char* some_file = "filename";
  963. unsigned char der[];
  964. if(wc_PemPubKeyToDer(some_file, der, sizeof(der)) != 0)
  965. {
  966. //Handle Error
  967. }
  968. \endcode
  969. \sa wc_PubKeyPemToDer
  970. */
  971. WOLFSSL_API int wc_PemPubKeyToDer(const char* fileName,
  972. unsigned char* derBuf, int derSz);
  973. /*!
  974. \ingroup ASN
  975. \brief Convert a PEM encoded public key to DER. Returns the number of
  976. bytes written to the buffer or a negative value for an error.
  977. \return >0 Success, number of bytes written.
  978. \return BAD_FUNC_ARG Returns if pem, buff, or buffSz are null
  979. \return <0 An error occurred in the function.
  980. \param pem PEM encoded key
  981. \param pemSz Size of pem
  982. \param buff Pointer to buffer for output.
  983. \param buffSz Size of buffer.
  984. _Example_
  985. \code
  986. byte some_pem[] = { Initialize with PEM key }
  987. unsigned char out_buffer[1024]; // Ensure buffer is large enough to fit DER
  988. if(wc_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer,
  989. sizeof(out_buffer)) < 0)
  990. {
  991. // Handle error
  992. }
  993. \endcode
  994. \sa wc_PemPubKeyToDer
  995. */
  996. WOLFSSL_API int wc_PubKeyPemToDer(const unsigned char*, int,
  997. unsigned char*, int);
  998. /*!
  999. \ingroup ASN
  1000. \brief This function converts a pem certificate to a der certificate,
  1001. and places the resulting certificate in the derBuf buffer provided.
  1002. \return Success On success returns the size of the derBuf generated
  1003. \return BUFFER_E Returned if the size of derBuf is too small to hold
  1004. the certificate generated
  1005. \return MEMORY_E Returned if the call to XMALLOC fails
  1006. \param fileName path to the file containing a pem certificate to
  1007. convert to a der certificate
  1008. \param derBuf pointer to a char buffer in which to store the
  1009. converted certificate
  1010. \param derSz size of the char buffer in which to store the
  1011. converted certificate
  1012. _Example_
  1013. \code
  1014. char * file = “./certs/client-cert.pem”;
  1015. int derSz;
  1016. byte * der = (byte*)XMALLOC(EIGHTK_BUF, NULL, DYNAMIC_TYPE_CERT);
  1017. derSz = wc_PemCertToDer(file, der, EIGHTK_BUF);
  1018. if(derSz <= 0) {
  1019. //PemCertToDer error
  1020. }
  1021. \endcode
  1022. \sa none
  1023. */
  1024. WOLFSSL_API
  1025. int wc_PemCertToDer(const char* fileName, unsigned char* derBuf, int derSz);
  1026. /*!
  1027. \ingroup ASN
  1028. \brief This function converts a der formatted input certificate, contained
  1029. in the der buffer, into a pem formatted output certificate, contained in
  1030. the output buffer. It should be noted that this is not an in place
  1031. conversion, and a separate buffer must be utilized to store the pem
  1032. formatted output.
  1033. \return Success On successfully making a pem certificate from the input
  1034. der cert, returns the size of the pem cert generated.
  1035. \return BAD_FUNC_ARG Returned if there is an error parsing the der file
  1036. and storing it as a pem file
  1037. \return MEMORY_E Returned if there is an error allocating memory
  1038. with XMALLOC
  1039. \return ASN_INPUT_E Returned in the case of a base 64 encoding error
  1040. \return BUFFER_E May be returned if the output buffer is too small to
  1041. store the pem formatted certificate
  1042. \param der pointer to the buffer of the certificate to convert
  1043. \param derSz size of the the certificate to convert
  1044. \param output pointer to the buffer in which to store the pem
  1045. formatted certificate
  1046. \param outSz size of the buffer in which to store the pem formatted
  1047. certificate
  1048. \param type the type of certificate to generate. Valid types are:
  1049. CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
  1050. _Example_
  1051. \code
  1052. byte* der;
  1053. // initialize der with certificate
  1054. byte* pemFormatted[FOURK_BUF];
  1055. word32 pemSz;
  1056. pemSz = wc_DerToPem(der, derSz,pemFormatted,FOURK_BUF, CERT_TYPE);
  1057. \endcode
  1058. \sa wc_PemCertToDer
  1059. */
  1060. WOLFSSL_API int wc_DerToPem(const byte* der, word32 derSz, byte* output,
  1061. word32 outputSz, int type);
  1062. /*!
  1063. \ingroup ASN
  1064. \brief This function converts a der formatted input certificate,
  1065. contained in the der buffer, into a pem formatted output certificate,
  1066. contained in the output buffer. It should be noted that this is not an
  1067. in place conversion, and a separate buffer must be utilized to store the
  1068. pem formatted output. Allows setting cipher info.
  1069. \return Success On successfully making a pem certificate from the input
  1070. der cert, returns the size of the pem cert generated.
  1071. \return BAD_FUNC_ARG Returned if there is an error parsing the der file
  1072. and storing it as a pem file
  1073. \return MEMORY_E Returned if there is an error allocating memory
  1074. with XMALLOC
  1075. \return ASN_INPUT_E Returned in the case of a base 64 encoding error
  1076. \return BUFFER_E May be returned if the output buffer is too small to
  1077. store the pem formatted certificate
  1078. \param der pointer to the buffer of the certificate to convert
  1079. \param derSz size of the the certificate to convert
  1080. \param output pointer to the buffer in which to store the pem
  1081. formatted certificate
  1082. \param outSz size of the buffer in which to store the pem formatted
  1083. certificate
  1084. \param cipher_inf Additional cipher information.
  1085. \param type the type of certificate to generate. Valid types are:
  1086. CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
  1087. _Example_
  1088. \code
  1089. byte* der;
  1090. // initialize der with certificate
  1091. byte* pemFormatted[FOURK_BUF];
  1092. word32 pemSz;
  1093. byte* cipher_info[] { Additional cipher info. }
  1094. pemSz = wc_DerToPemEx(der, derSz,pemFormatted,FOURK_BUF, ,CERT_TYPE);
  1095. \endcode
  1096. \sa wc_PemCertToDer
  1097. */
  1098. WOLFSSL_API int wc_DerToPemEx(const byte* der, word32 derSz, byte* output,
  1099. word32 outputSz, byte *cipherIno, int type);
  1100. /*!
  1101. \ingroup CertsKeys
  1102. \brief Converts a key in PEM format to DER format.
  1103. \return int the function returns the number of bytes written to
  1104. the buffer on successful execution.
  1105. \return int negative int returned indicating an error.
  1106. \param pem a pointer to the PEM encoded certificate.
  1107. \param pemSz the size of the PEM buffer (pem)
  1108. \param buff a pointer to the copy of the buffer member of the
  1109. DerBuffer struct.
  1110. \param buffSz size of the buffer space allocated in the DerBuffer struct.
  1111. \param pass password passed into the function.
  1112. _Example_
  1113. \code
  1114. byte* loadBuf;
  1115. long fileSz = 0;
  1116. byte* bufSz;
  1117. static int LoadKeyFile(byte** keyBuf, word32* keyBufSz,
  1118. const char* keyFile,
  1119. int typeKey, const char* password);
  1120. bufSz = wc_KeyPemToDer(loadBuf, (int)fileSz, saveBuf,
  1121. (int)fileSz, password);
  1122. if(saveBufSz > 0){
  1123. // Bytes were written to the buffer.
  1124. }
  1125. \endcode
  1126. \sa wc_PemToDer
  1127. */
  1128. WOLFSSL_API int wc_KeyPemToDer(const unsigned char*, int,
  1129. unsigned char*, int, const char*);
  1130. /*!
  1131. \ingroup CertsKeys
  1132. \brief This function converts a PEM formatted certificate to DER
  1133. format. Calls OpenSSL function PemToDer.
  1134. \return buffer returns the bytes written to the buffer.
  1135. \param pem pointer PEM formatted certificate.
  1136. \param pemSz size of the certificate.
  1137. \param buff buffer to be copied to DER format.
  1138. \param buffSz size of the buffer.
  1139. \param type Certificate file type found in asn_public.h enum CertType.
  1140. _Example_
  1141. \code
  1142. const unsigned char* pem;
  1143. int pemSz;
  1144. unsigned char buff[BUFSIZE];
  1145. int buffSz = sizeof(buff)/sizeof(char);
  1146. int type;
  1147. ...
  1148. if(wc_CertPemToDer(pem, pemSz, buff, buffSz, type) <= 0) {
  1149. // There were bytes written to buffer
  1150. }
  1151. \endcode
  1152. \sa wc_PemToDer
  1153. */
  1154. WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
  1155. unsigned char*, int, int);
  1156. /*!
  1157. \ingroup ASN
  1158. \brief This function reads in an ECC private key from the input buffer,
  1159. input, parses the private key, and uses it to generate an ecc_key object,
  1160. which it stores in key.
  1161. \return 0 On successfully decoding the private key and storing the result
  1162. in the ecc_key struct
  1163. \return ASN_PARSE_E: Returned if there is an error parsing the der file
  1164. and storing it as a pem file
  1165. \return MEMORY_E Returned if there is an error allocating memory
  1166. with XMALLOC
  1167. \return BUFFER_E Returned if the certificate to convert is large than
  1168. the specified max certificate size
  1169. \return ASN_OBJECT_ID_E Returned if the certificate encoding has an
  1170. invalid object id
  1171. \return ECC_CURVE_OID_E Returned if the ECC curve of the provided key is
  1172. not supported
  1173. \return ECC_BAD_ARG_E Returned if there is an error in the ECC key format
  1174. \return NOT_COMPILED_IN Returned if the private key is compressed, and no
  1175. compression key is provided
  1176. \return MP_MEM Returned if there is an error in the math library used
  1177. while parsing the private key
  1178. \return MP_VAL Returned if there is an error in the math library used
  1179. while parsing the private key
  1180. \return MP_RANGE Returned if there is an error in the math library used
  1181. while parsing the private key
  1182. \param input pointer to the buffer containing the input private key
  1183. \param inOutIdx pointer to a word32 object containing the index in
  1184. the buffer at which to start
  1185. \param key pointer to an initialized ecc object, on which to store
  1186. the decoded private key
  1187. \param inSz size of the input buffer containing the private key
  1188. _Example_
  1189. \code
  1190. int ret, idx=0;
  1191. ecc_key key; // to store key in
  1192. byte* tmp; // tmp buffer to read key from
  1193. tmp = (byte*) malloc(FOURK_BUF);
  1194. int inSz;
  1195. inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile);
  1196. // read key into tmp buffer
  1197. wc_ecc_init(&key); // initialize key
  1198. ret = wc_EccPrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
  1199. if(ret < 0) {
  1200. // error decoding ecc key
  1201. }
  1202. \endcode
  1203. \sa wc_RSA_PrivateKeyDecode
  1204. */
  1205. WOLFSSL_API int wc_EccPrivateKeyDecode(const byte*, word32*,
  1206. ecc_key*, word32);
  1207. /*!
  1208. \ingroup ASN
  1209. \brief This function writes a private ECC key to der format.
  1210. \return Success On successfully writing the ECC key to der format,
  1211. returns the length written to the buffer
  1212. \return BAD_FUNC_ARG Returned if key or output is null, or inLen equals zero
  1213. \return MEMORY_E Returned if there is an error allocating memory
  1214. with XMALLOC
  1215. \return BUFFER_E Returned if the converted certificate is too large
  1216. to store in the output buffer
  1217. \return ASN_UNKNOWN_OID_E Returned if the ECC key used is of an
  1218. unknown type
  1219. \return MP_MEM Returned if there is an error in the math library used
  1220. while parsing the private key
  1221. \return MP_VAL Returned if there is an error in the math library used
  1222. while parsing the private key
  1223. \return MP_RANGE Returned if there is an error in the math library used
  1224. while parsing the private key
  1225. \param key pointer to the buffer containing the input ecc key
  1226. \param output pointer to a buffer in which to store the der formatted key
  1227. \param inLen the length of the buffer in which to store the
  1228. der formatted key
  1229. _Example_
  1230. \code
  1231. int derSz;
  1232. ecc_key key;
  1233. // initialize and make key
  1234. byte der[FOURK_BUF];
  1235. // store der formatted key here
  1236. derSz = wc_EccKeyToDer(&key, der, FOURK_BUF);
  1237. if(derSz < 0) {
  1238. // error converting ecc key to der buffer
  1239. }
  1240. \endcode
  1241. \sa wc_RsaKeyToDer
  1242. */
  1243. WOLFSSL_API int wc_EccKeyToDer(ecc_key*, byte* output, word32 inLen);
  1244. /*!
  1245. \ingroup ASN
  1246. \brief Decodes an ECC public key from an input buffer. It will parse an
  1247. ASN sequence to retrieve the ECC key.
  1248. \return 0 Success
  1249. \return BAD_FUNC_ARG Returns if any arguments are null.
  1250. \return ASN_PARSE_E Returns if there is an error parsing
  1251. \return ASN_ECC_KEY_E Returns if there is an error importing the key.
  1252. See wc_ecc_import_x963 for possible reasons.
  1253. \param input Buffer containing DER encoded key to decode.
  1254. \param inOutIdx Index to start reading input buffer from. On output,
  1255. index is set to last position parsed of input buffer.
  1256. \param key Pointer to ecc_key struct to store the public key.
  1257. \param inSz Size of the input buffer.
  1258. _Example_
  1259. \code
  1260. int ret;
  1261. word32 idx = 0;
  1262. byte buff[] = { // initialize with key };
  1263. ecc_key pubKey;
  1264. wc_ecc_init(&pubKey);
  1265. if ( wc_EccPublicKeyDecode(buff, &idx, &pubKey, sizeof(buff)) != 0) {
  1266. // error decoding key
  1267. }
  1268. \endcode
  1269. \sa wc_ecc_import_x963
  1270. */
  1271. WOLFSSL_API int wc_EccPublicKeyDecode(const byte*, word32*,
  1272. ecc_key*, word32);
  1273. /*!
  1274. \ingroup ASN
  1275. \brief This function converts the ECC public key to DER format. It
  1276. returns the size of buffer used. The public ECC key in DER format is stored
  1277. in output buffer. with_AlgCurve is a flag for when to include a header that
  1278. has the Algorithm and Curve information.
  1279. \return >0 Success, size of buffer used
  1280. \return BAD_FUNC_ARG Returned if output or key is null.
  1281. \return LENGTH_ONLY_E Error in getting ECC public key size.
  1282. \return BUFFER_E Returned when output buffer is too small.
  1283. \param key Pointer to ECC key
  1284. \param output Pointer to output buffer to write to.
  1285. \param inLen Size of buffer.
  1286. \param with_AlgCurve a flag for when to include a header that has the
  1287. Algorithm and Curve information.
  1288. _Example_
  1289. \code
  1290. ecc_key key;
  1291. wc_ecc_init(&key);
  1292. WC_WC_RNG rng;
  1293. wc_InitRng(&rng);
  1294. wc_ecc_make_key(&rng, 24, &key);
  1295. int derSz = // Some appropriate size for der;
  1296. byte der[derSz];
  1297. if(wc_EccPublicKeyToDer(&key, der, derSz, 1) < 0)
  1298. {
  1299. // Error converting ECC public key to der
  1300. }
  1301. \endcode
  1302. \sa wc_EccKeyToDer
  1303. \sa wc_EccPrivateKeyDecode
  1304. */
  1305. WOLFSSL_API int wc_EccPublicKeyToDer(ecc_key*, byte* output,
  1306. word32 inLen, int with_AlgCurve);
  1307. /*!
  1308. \ingroup ASN
  1309. \brief This function encodes a digital signature into the output buffer,
  1310. and returns the size of the encoded signature created.
  1311. \return Success On successfully writing the encoded signature to output,
  1312. returns the length written to the buffer
  1313. \param out pointer to the buffer where the encoded signature will be written
  1314. \param digest pointer to the digest to use to encode the signature
  1315. \param digSz the length of the buffer containing the digest
  1316. \param hashOID OID identifying the hash type used to generate the
  1317. signature. Valid options, depending on build configurations, are: SHAh,
  1318. SHA256h, SHA384h, SHA512h, MD2h, MD5h, DESb, DES3b, CTC_MD5wRSA,
  1319. CTC_SHAwRSA, CTC_SHA256wRSA, CTC_SHA384wRSA, CTC_SHA512wRSA, CTC_SHAwECDSA,
  1320. CTC_SHA256wECDSA, CTC_SHA384wECDSA, and CTC_SHA512wECDSA.
  1321. \endcode
  1322. \code
  1323. int signSz;
  1324. byte encodedSig[MAX_ENCODED_SIG_SZ];
  1325. Sha256 sha256;
  1326. // initialize sha256 for hashing
  1327. byte* dig = = (byte*)malloc(SHA256_DIGEST_SIZE);
  1328. // perform hashing and hash updating so dig stores SHA-256 hash
  1329. // (see wc_InitSha256, wc_Sha256Update and wc_Sha256Final)
  1330. signSz = wc_EncodeSignature(encodedSig, dig, SHA256_DIGEST_SIZE,SHA256h);
  1331. \endcode
  1332. \sa none
  1333. */
  1334. WOLFSSL_API word32 wc_EncodeSignature(byte* out, const byte* digest,
  1335. word32 digSz, int hashOID);
  1336. /*!
  1337. \ingroup ASN
  1338. \brief This function returns the hash OID that corresponds to a hashing
  1339. type. For example, when given the type: SHA512, this function returns the
  1340. identifier corresponding to a SHA512 hash, SHA512h.
  1341. \return Success On success, returns the OID corresponding to the
  1342. appropriate hash to use with that encryption type.
  1343. \return 0 Returned if an unrecognized hash type is passed in as argument.
  1344. \param type the hash type for which to find the OID. Valid options,
  1345. depending on build configuration, include: MD2, MD5, SHA, SHA256, SHA512,
  1346. SHA384, and SHA512.
  1347. _Example_
  1348. \code
  1349. int hashOID;
  1350. hashOID = wc_GetCTC_HashOID(SHA512);
  1351. if (hashOID == 0) {
  1352. // WOLFSSL_SHA512 not defined
  1353. }
  1354. \endcode
  1355. \sa none
  1356. */
  1357. WOLFSSL_API int wc_GetCTC_HashOID(int type);
  1358. /*!
  1359. \ingroup ASN
  1360. \brief This function cleans up memory and resources used by the certificate
  1361. structure's decoded cert cache. When WOLFSSL_CERT_GEN_CACHE is defined the
  1362. decoded cert structure is cached in the certificate structure. This allows
  1363. subsequent calls to certificate set functions to avoid parsing the decoded
  1364. cert on each call.
  1365. \return 0 on success.
  1366. \return BAD_FUNC_ARG Returned if invalid pointer is passed in as argument.
  1367. \param cert pointer to an uninitialized certificate information structure.
  1368. _Example_
  1369. \code
  1370. Cert cert; // Initialized certificate structure
  1371. wc_SetCert_Free(&cert);
  1372. \endcode
  1373. \sa wc_SetAuthKeyIdFromCert
  1374. \sa wc_SetIssuerBuffer
  1375. \sa wc_SetSubjectBuffer
  1376. \sa wc_SetSubjectRaw
  1377. \sa wc_SetIssuerRaw
  1378. \sa wc_SetAltNamesBuffer
  1379. \sa wc_SetDatesBuffer
  1380. */
  1381. WOLFSSL_API void wc_SetCert_Free(Cert* cert);