1.\" $OpenBSD: X509_check_purpose.3,v 1.1 2019/08/22 15:15:35 schwarze Exp $ 2.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.Dd $Mdocdate: August 22 2019 $ 17.Dt X509_CHECK_PURPOSE 3 18.Os 19.Sh NAME 20.Nm X509_check_purpose 21.Nd check intended usage of a public key 22.Sh SYNOPSIS 23.In openssl/x509v3.h 24.Ft int 25.Fo X509_check_purpose 26.Fa "X509 *certificate" 27.Fa "int purpose" 28.Fa "int ca" 29.Fc 30.Sh DESCRIPTION 31If the 32.Fa ca 33flag is 0, 34.Fn X509_check_purpose 35checks whether the public key contained in the 36.Fa certificate 37is intended to be used for the given 38.Fa purpose , 39which can be one of the following integer constants. 40The check succeeds if none of the conditions given in the list below 41are violated. 42.Bl -tag -width 1n 43.It Dv X509_PURPOSE_SSL_CLIENT 44.Bl -dash -width 1n -compact 45.It 46If the 47.Fa certificate 48contains an Extended Key Usage extension, it contains the RFC 5280 49.Dq TLS WWW client authentication 50purpose 51.Pq Dv NID_client_auth . 52.It 53If the 54.Fa certificate 55contains a Key Usage extension, the 56.Dv digitalSignature 57bit is set. 58.It 59If the 60.Fa certificate 61contains a Netscape Cert Type extension, the 62.Dq SSL client certificate 63bit is set 64.Pq Dv NS_SSL_CLIENT . 65.El 66.It Dv X509_PURPOSE_SSL_SERVER 67.Bl -dash -width 1n -compact 68.It 69If the 70.Fa certificate 71contains an Extended Key Usage extension, it contains the RFC 5280 72.Dq TLS WWW server authentication 73purpose 74.Pq Dv NID_server_auth 75or the private 76.Dq Netscape Server Gated Crypto 77.Pq Dv NID_ns_sgc 78or 79.Dq Microsoft Server Gated Crypto 80.Pq Dv NID_ms_sgc 81purpose. 82.It 83If the 84.Fa certificate 85contains a Key Usage extension, at least one of the 86.Dv digitalSignature 87and 88.Dv keyEncipherment 89bits is set. 90.It 91If the 92.Fa certificate 93contains a Netscape Cert Type extension, the 94.Dq SSL server certificate 95bit is set 96.Pq Dv NS_SSL_SERVER 97.El 98.It Dv X509_PURPOSE_NS_SSL_SERVER 99.\" check_purpose_ns_ssl_server, "Netscape SSL server" 100This does the same checks as 101.Dv X509_PURPOSE_SSL_SERVER 102and additionally requires that a Key Usage extension, if present, 103has the 104.Dv keyEncipherment 105bit set. 106.It Dv X509_PURPOSE_SMIME_SIGN 107.\" check_purpose_smime_sign, "S/MIME signing" 108.Bl -dash -width 1n -compact 109.It 110If the 111.Fa certificate 112contains an Extended Key Usage extension, it contains the RFC 5280 113.Dq Email protection 114purpose 115.Pq Dv NID_email_protect . 116.It 117If the 118.Fa certificate 119contains a Key Usage extension, at least one of the 120.Dv digitalSignature 121and 122.Dv nonRepudiation 123bits is set. 124.It 125If the 126.Fa certificate 127contains a Netscape Cert Type extension, it has the 128.Dq S/MIME certificate 129bit set. 130If the 131.Dq SSL client certificate 132bit is set but the 133.Dq S/MIME certificate 134bit is not, no decision is made. 135.El 136.It Dv X509_PURPOSE_SMIME_ENCRYPT 137.\" check_purpose_smime_encrypt, "S/MIME encryption" 138.Bl -dash -width 1n -compact 139.It 140If the 141.Fa certificate 142contains an Extended Key Usage extension, it contains the RFC 5280 143.Dq Email protection 144purpose 145.Pq Dv NID_email_protect . 146.It 147If the 148.Fa certificate 149contains a Key Usage extension, the 150.Dv keyEncipherment 151bit is set. 152.It 153If the 154.Fa certificate 155contains a Netscape Cert Type extension, it has the 156.Dq S/MIME certificate 157bit set. 158If the 159.Dq SSL client certificate 160bit is set but the 161.Dq S/MIME certificate 162bit is not, no decision is made. 163.El 164.It Dv X509_PURPOSE_CRL_SIGN 165.\" check_purpose_crl_sign, "CRL signing" 166.Bl -dash -width 1n -compact 167.It 168If the 169.Fa certificate 170contains a Key Usage extension, the 171.Dv cRLSign 172bit is set. 173.El 174.It Dv X509_PURPOSE_ANY 175The check always succeeds. 176.It Dv X509_PURPOSE_OCSP_HELPER 177.\" ocsp_helper, "OCSP helper" 178The check always succeeds. 179The application program is expected 180to do the actual checking by other means. 181.It Dv X509_PURPOSE_TIMESTAMP_SIGN 182.\" check_purpose_timestamp_sign, "Time Stamp signing" 183.Bl -dash -width 1n -compact 184.It 185The 186.Fa certificate 187contains an Extended Key Usage extension containing the RFC 5280 188.Dq Time Stamping 189purpose and no other purpose. 190This extension is marked as critical. 191.It 192If the 193.Fa certificate 194contains a Key Usage extension, at least one of the 195.Dv digitalSignature 196and 197.Dv nonRepudiation 198bits is set, and no other bits are set. 199.El 200.El 201.Pp 202If the 203.Fa ca 204flag is non-zero, 205.Fn X509_check_purpose 206instead checks whether the 207.Fa certificate 208can be used as a certificate authority certificate 209in the context of the given 210.Fa purpose . 211To succeed, the check always requires that none of the following 212conditions are violated: 213.Pp 214.Bl -dash -width 1n -compact 215.It 216If the 217.Fa certificate 218contains a Key Usage extension, the 219.Dv keyCertSign 220bit is set. 221.It 222If the 223.Fa certificate 224contains a Basic Constraints extension, the 225.Fa cA 226field is set. 227.It 228If the 229.Fa certificate 230is a version 1 certificate, the subject name matches the issuer name 231and the certificate is self signed. 232.El 233.Pp 234The check succeeds if none of the additional conditions given in 235the list below are violated. 236.Bl -tag -width 1n 237.It Dv X509_PURPOSE_SSL_CLIENT 238.Bl -dash -width 1n -compact 239.It 240If the 241.Fa certificate 242contains an Extended Key Usage extension, it contains the RFC 5280 243.Dq TLS WWW client authentication 244purpose 245.Pq Dv NID_client_auth . 246.It 247If the 248.Fa certificate 249is not a version 1 certificate and does not contain a Basic Constraints 250extension, it contains a Key Usage extension with the 251.Dv keyCertSign 252bit set or a Netscape Cert Type extension with the 253.Dq SSL CA certificate 254bit set. 255.El 256.It Dv X509_PURPOSE_SSL_SERVER No or Dv X509_PURPOSE_NS_SSL_SERVER 257.Bl -dash -width 1n -compact 258.It 259If the 260.Fa certificate 261contains an Extended Key Usage extension, it contains the RFC 5280 262.Dq TLS WWW server authentication 263purpose 264.Pq Dv NID_server_auth 265or the private 266.Dq Netscape Server Gated Crypto 267.Pq Dv NID_ns_sgc 268or 269.Dq Microsoft Server Gated Crypto 270.Pq Dv NID_ms_sgc 271purpose. 272.It 273If the 274.Fa certificate 275is not a version 1 certificate and does not contain a Basic Constraints 276extension, it contains a Key Usage extension with the 277.Dv keyCertSign 278bit set or a Netscape Cert Type extension with the 279.Dq SSL CA certificate 280bit set. 281.El 282.It Dv X509_PURPOSE_SMIME_SIGN No or Dv X509_PURPOSE_SMIME_ENCRYPT 283.Bl -dash -width 1n -compact 284.It 285If the 286.Fa certificate 287contains an Extended Key Usage extension, it contains the RFC 5280 288.Dq Email protection 289purpose 290.Pq Dv NID_email_protect . 291.It 292If the 293.Fa certificate 294is not a version 1 certificate and does not contain a Basic Constraints 295extension, it contains a Key Usage extension with the 296.Dv keyCertSign 297bit set or a Netscape Cert Type extension with the 298.Dq S/MIME CA certificate 299bit set. 300.El 301.It Xo 302.Dv X509_PURPOSE_CRL_SIGN , 303.Dv X509_PURPOSE_OCSP_HELPER , 304or 305.Dv X509_PURPOSE_TIMESTAMP_SIGN 306.Xc 307.Bl -dash -width 1n -compact 308.It 309If the 310.Fa certificate 311is not a version 1 certificate and does not contain a Basic Constraints 312extension, it contains a Key Usage extension with the 313.Dv keyCertSign 314bit set or a Netscape Cert Type extension with at least one of the 315.Dq SSL CA certificate , 316.Dq S/MIME CA certificate , 317or 318.Dq Object-signing CA certificate 319bits set. 320.El 321.It Dv X509_PURPOSE_ANY 322The check always succeeds, even if the three common conditions 323cited above this list are violated. 324.El 325.Pp 326If the 327.Fa purpose 328is -1, 329.Fn X509_check_purpose 330always succeeds, no matter whether or not the 331.Fa ca 332flag is set. 333.Sh RETURN VALUES 334.Fn X509_check_purpose 335returns the following values: 336.Bl -column -1 Failure -compact 337.It -1 Ta Error Ta The 338.Fa purpose 339is invalid. 340.It 0 Ta Failure Ta The 341.Fa certificate 342cannot be used for the 343.Fa purpose . 344.El 345.Pp 346If 347.Fa ca 348is 0, the following values can also be returned: 349.Bl -column -1 Failure -compact 350.It 1 Ta Success Ta The 351.Fa certificate 352can be used for the 353.Fa purpose . 354.It 2 Ta Unknown Ta \&No decision can be made. 355.El 356.Pp 357If 358.Fa ca 359is non-zero, the following values can also be returned: 360.Bl -column -1 Failure -compact 361.It 1 Ta Success Ta The 362.Fa certificate 363can be used as a CA for the 364.Fa purpose . 365.It 3 Ta Success Ta The Fa certificate No is a version 1 CA. 366.It 4 Ta Success Ta The Key Usage allows Dv keyCertSign . 367.It 5 Ta Success Ta A Netscape Cert Type allows usage as a CA. 368.El 369.Sh SEE ALSO 370.Xr BASIC_CONSTRAINTS_new 3 , 371.Xr EXTENDED_KEY_USAGE_new 3 , 372.Xr X509_new 3 , 373.Xr X509V3_get_d2i 3 , 374.Xr x509v3.cnf 5 375.Sh STANDARDS 376RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 377Certificate Revocation List (CRL) Profile 378.Bl -dash -offset indent -compact 379.It 380section 4.2.1.3: Key Usage 381.It 382section 4.2.1.9: Basic Constraints 383.It 384section 4.2.1.12: Extended Key Usage 385.El 386.Sh HISTORY 387.Fn X509_check_purpose 388first appeared in OpenSSL 0.9.5 and has been available since 389.Ox 2.7 . 390