1 /* 2 3 silcauth.h 4 5 Author: Pekka Riikonen <priikone@silcnet.org> 6 7 Copyright (C) 2001 - 2007 Pekka Riikonen 8 9 The contents of this file are subject to one of the Licenses specified 10 in the COPYING file; You may not use this file except in compliance 11 with the License. 12 13 The software distributed under the License is distributed on an "AS IS" 14 basis, in the hope that it will be useful, but WITHOUT WARRANTY OF ANY 15 KIND, either expressed or implied. See the COPYING file for more 16 information. 17 18 */ 19 20 /****h* silccore/SILC Authentication Interface 21 * 22 * DESCRIPTION 23 * 24 * Implementations of the SILC Authentication Payload and authentication 25 * routines. The SILC Authentication Payload is used to deliver 26 * authentication data usually from client to server in purpose of 27 * gaining access to some service. The Payload and the authentication 28 * routines supports both passphrase and public key (signature) based 29 * authentication. 30 * 31 * This interface defines also the SILC Key Agreement Payload that is 32 * used by client to agree on key material usually with another client 33 * in the network. 34 * 35 ***/ 36 37 #ifndef SILCAUTH_H 38 #define SILCAUTH_H 39 40 /****d* silccore/SilcAuthAPI/SilcAuthMethod 41 * 42 * NAME 43 * 44 * typedef SilcUInt16 SilcAuthMethod; 45 * 46 * DESCRIPTION 47 * 48 * Authentication method type definition, the authentication methods 49 * and the authentication status'. The status defines are used by 50 * all authentication protocols in the SILC. 51 * 52 * SOURCE 53 */ 54 typedef SilcUInt16 SilcAuthMethod; 55 56 #define SILC_AUTH_NONE 0 /* No authentication */ 57 #define SILC_AUTH_PASSWORD 1 /* Passphrase authentication */ 58 #define SILC_AUTH_PUBLIC_KEY 2 /* Public key authentication */ 59 60 /****d* silccore/SilcAuthAPI/SilcAuthResult 61 * 62 * NAME 63 * 64 * typedef SilcUInt32 SilcAuthResult; 65 * 66 * DESCRIPTION 67 * 68 * Authentication protocol status. Used by all authentication protocols 69 * in SILC. 70 * 71 * SOURCE 72 */ 73 typedef SilcUInt32 SilcAuthResult; 74 75 #define SILC_AUTH_OK 0 /* Authentication successful */ 76 #define SILC_AUTH_FAILED 1 /* Authentication failed */ 77 /***/ 78 79 /****s* silccore/SilcAuthAPI/SilcAuthPayload 80 * 81 * NAME 82 * 83 * typedef struct SilcAuthPayloadStruct *SilcAuthPayload; 84 * 85 * 86 * DESCRIPTION 87 * 88 * This context is the actual Authentication Payload and is allocated 89 * by silc_auth_payload_parse and given as argument usually to all 90 * silc_auth_payload_* functions. It is freed by silc_auth_payload_free 91 * function. 92 * 93 ***/ 94 typedef struct SilcAuthPayloadStruct *SilcAuthPayload; 95 96 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse 97 * 98 * SYNOPSIS 99 * 100 * SilcAuthPayload silc_auth_payload_parse(const unsigned char *data, 101 * SilcUInt32 data_len); 102 * 103 * DESCRIPTION 104 * 105 * Parses and returns Authentication Payload. The `data' and the 106 * `data_len' are the raw payload buffer. 107 * 108 ***/ 109 SilcAuthPayload silc_auth_payload_parse(const unsigned char *data, 110 SilcUInt32 data_len); 111 112 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode 113 * 114 * SYNOPSIS 115 * 116 * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method, 117 * const unsigned char *random_data, 118 * SilcUInt16 random_len, 119 * const unsigned char *auth_data, 120 * SilcUInt16 auth_len); 121 * 122 * DESCRIPTION 123 * 124 * Encodes authentication payload into buffer and returns it. 125 * The `random_data' is provided only if doing public key authentication. 126 * The `auth_data' is the actual authentication data. If the 127 * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as 128 * argument SHOULD be UTF-8 encoded, if not library will attempt to 129 * encode it. 130 * 131 ***/ 132 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method, 133 const unsigned char *random_data, 134 SilcUInt16 random_len, 135 const unsigned char *auth_data, 136 SilcUInt16 auth_len); 137 138 /****f* silccore/SilcAuthAPI/silc_auth_payload_free 139 * 140 * SYNOPSIS 141 * 142 * void silc_auth_payload_free(SilcAuthPayload payload); 143 * 144 * DESCRIPTION 145 * 146 * Frees authentication payload and all data in it. 147 * 148 ***/ 149 void silc_auth_payload_free(SilcAuthPayload payload); 150 151 /****f* silccore/SilcAuthAPI/silc_auth_get_method 152 * 153 * SYNOPSIS 154 * 155 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload); 156 * 157 * DESCRIPTION 158 * 159 * Get authentication method. 160 * 161 ***/ 162 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload); 163 164 /****f* silccore/SilcAuthAPI/silc_auth_get_public_data 165 * 166 * SYNOPSIS 167 * 168 * unsigned char *silc_auth_get_public_data(SilcAuthPayload payload, 169 * SilcUInt32 *pubdata_len); 170 * 171 * DESCRIPTION 172 * 173 * Returns the public data (usually random data) from the payload. 174 * Caller must not free the returned data. 175 * 176 ***/ 177 unsigned char *silc_auth_get_public_data(SilcAuthPayload payload, 178 SilcUInt32 *pubdata_len); 179 180 /****f* silccore/SilcAuthAPI/silc_auth_get_data 181 * 182 * SYNOPSIS 183 * 184 * unsigned char *silc_auth_get_data(SilcAuthPayload payload, 185 * SilcUInt32 *auth_len); 186 * 187 * DESCRIPTION 188 * 189 * Get the authentication data. The caller must not free the data. If 190 * the authentication method is passphrase, then the returned string 191 * is UTF-8 encoded passphrase. 192 * 193 ***/ 194 unsigned char *silc_auth_get_data(SilcAuthPayload payload, 195 SilcUInt32 *auth_len); 196 197 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate 198 * 199 * SYNOPSIS 200 * 201 * SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key, 202 * SilcPrivateKey private_key, 203 * SilcRng rng, 204 * SilcHash hash, 205 * const void *id, 206 * SilcIdType type); 207 * 208 * DESCRIPTION 209 * 210 * Generates Authentication Payload with authentication data. This is used 211 * to do public key based authentication. This generates the random data 212 * and the actual authentication data. Returns NULL on error and the 213 * encoded Authentication Payload on success. 214 * 215 * The `private_key' is used to sign the payload. The `public_key', the 216 * and the `id' is encoded in the payload and signed. If the `rng' is 217 * NULL then global RNG is used, if non-NULL then `rng' is used as 218 * random number generator. Also random number is encoded in the 219 * payload before signing it with `private_key'. 220 * 221 ***/ 222 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key, 223 SilcPrivateKey private_key, 224 SilcRng rng, SilcHash hash, 225 const void *id, SilcIdType type); 226 227 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub 228 * 229 * SYNOPSIS 230 * 231 * SilcBuffer 232 * silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key, 233 * SilcPrivateKey private_key, 234 * const unsigned char *pubdata, 235 * SilcUInt32 pubdata_len, 236 * SilcHash hash, 237 * const void *id, 238 * SilcIdType type); 239 * 240 * DESCRIPTION 241 * 242 * Same as silc_auth_public_key_auth_generate but takes the public data 243 * (usually random data) as argument. This function can be used when 244 * the public data must be something else than purely random or its 245 * structure mut be set before signing. 246 * 247 ***/ 248 SilcBuffer 249 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key, 250 SilcPrivateKey private_key, 251 const unsigned char *pubdata, 252 SilcUInt32 pubdata_len, 253 SilcHash hash, 254 const void *id, SilcIdType type); 255 256 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify 257 * 258 * SYNOPSIS 259 * 260 * SilcBool silc_auth_public_key_auth_verify(SilcAuthPayload payload, 261 * SilcPublicKey public_key, 262 * SilcHash hash, 263 * const void *id, SilcIdType type); 264 * 265 * DESCRIPTION 266 * 267 * Verifies the authentication data. Returns TRUE if authentication was 268 * successful. 269 * 270 ***/ 271 SilcBool silc_auth_public_key_auth_verify(SilcAuthPayload payload, 272 SilcPublicKey public_key, 273 SilcHash hash, 274 const void *id, 275 SilcIdType type); 276 277 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data 278 * 279 * SYNOPSIS 280 * 281 * SilcBool silc_auth_public_key_auth_verify_data(const unsigned char *payload, 282 * SilcUInt32 payload_len, 283 * SilcPublicKey public_key, 284 * SilcHash hash, 285 * const void *id, 286 * SilcIdType type); 287 * 288 * DESCRIPTION 289 * 290 * Same as silc_auth_public_key_auth_verify but the payload has not 291 * been parsed yet. This will parse it. Returns TRUE if authentication 292 * was successful. 293 * 294 ***/ 295 SilcBool silc_auth_public_key_auth_verify_data(const unsigned char *payload, 296 SilcUInt32 payload_len, 297 SilcPublicKey public_key, 298 SilcHash hash, 299 const void *id, 300 SilcIdType type); 301 302 /****f* silccore/SilcAuthAPI/silc_auth_verify 303 * 304 * SYNOPSIS 305 * 306 * SilcBool silc_auth_verify(SilcAuthPayload payload, 307 * SilcAuthMethod auth_method, 308 * const void *auth_data, SilcUInt32 auth_data_len, 309 * SilcHash hash, const void *id, SilcIdType type); 310 * 311 * DESCRIPTION 312 * 313 * Verifies the authentication data directly from the Authentication 314 * Payload. Supports all authentication methods. If the authentication 315 * method is passphrase based then the `auth_data' and `auth_data_len' 316 * are the passphrase and its length. The passphrase MUST be UTF-8 317 * encoded. If the method is public key authentication then the 318 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored. 319 * 320 ***/ 321 SilcBool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method, 322 const void *auth_data, SilcUInt32 auth_data_len, 323 SilcHash hash, const void *id, SilcIdType type); 324 325 /****f* silccore/SilcAuthAPI/silc_auth_verify_data 326 * 327 * SYNOPSIS 328 * 329 * SilcBool silc_auth_verify_data(const unsigned char *payload, 330 * SilcUInt32 payload_len, 331 * SilcAuthMethod auth_method, 332 * const void *auth_data, 333 * SilcUInt32 auth_data_len, SilcHash hash, 334 * const void *id, SilcIdType type); 335 * 336 * DESCRIPTION 337 * 338 * Same as silc_auth_verify but the payload has not been parsed yet. 339 * Verifies the authentication data directly from the Authentication 340 * Payload. Supports all authentication methods. If the authentication 341 * method is passphrase based then the `auth_data' and `auth_data_len' 342 * are the passphrase and its length. The passphrase MUST be UTF-8 343 * encoded. If the method is public key authentication then the 344 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored. 345 * 346 ***/ 347 SilcBool silc_auth_verify_data(const unsigned char *payload, 348 SilcUInt32 payload_len, 349 SilcAuthMethod auth_method, 350 const void *auth_data, 351 SilcUInt32 auth_data_len, SilcHash hash, 352 const void *id, SilcIdType type); 353 354 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload 355 * 356 * NAME 357 * 358 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; 359 * 360 * DESCRIPTION 361 * 362 * This context is the actual Key Agreement Payload and is allocated 363 * by silc_key_agreement_payload_parse and given as argument usually to all 364 * silc_key_agreement_* functions. It is freed by the function 365 * silc_key_agreement_payload_free. 366 * 367 ***/ 368 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; 369 370 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse 371 * 372 * SYNOPSIS 373 * 374 * SilcKeyAgreementPayload 375 * silc_key_agreement_payload_parse(const unsigned char *payload, 376 * SilcUInt32 payload_len); 377 * 378 * DESCRIPTION 379 * 380 * Parses and returns an allocated Key Agreement payload. 381 * 382 ***/ 383 SilcKeyAgreementPayload 384 silc_key_agreement_payload_parse(const unsigned char *payload, 385 SilcUInt32 payload_len); 386 387 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode 388 * 389 * SYNOPSIS 390 * 391 * SilcBuffer silc_key_agreement_payload_encode(char *hostname, 392 * SilcUInt16 protocol, 393 * SilcUInt16 port); 394 * 395 * DESCRIPTION 396 * 397 * Encodes the Key Agreement payload and returns the encoded buffer. 398 * The `protocol' is 0 for TCP and 1 for UDP. 399 * 400 ***/ 401 SilcBuffer silc_key_agreement_payload_encode(const char *hostname, 402 SilcUInt16 protocol, 403 SilcUInt16 port); 404 405 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free 406 * 407 * SYNOPSIS 408 * 409 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload); 410 * 411 * DESCRIPTION 412 * 413 * Frees the Key Agreement payload and all data in it. 414 * 415 ***/ 416 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload); 417 418 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname 419 * 420 * SYNOPSIS 421 * 422 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload); 423 * 424 * DESCRIPTION 425 * 426 * Returns the hostname in the payload. Caller must not free it. 427 * The hostname is the host that is able to accept key negotiation 428 * using the SILC Key Exchange protocol. 429 * 430 ***/ 431 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload); 432 433 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol 434 * 435 * SYNOPSIS 436 * 437 * SilcUInt16 438 * silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload); 439 * 440 * DESCRIPTION 441 * 442 * Returns the protocol in the payload. The protocol is either TCP (0) 443 * or UDP (1). 444 * 445 ***/ 446 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload); 447 448 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port 449 * 450 * SYNOPSIS 451 * 452 * SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); 453 * 454 * DESCRIPTION 455 * 456 * Returns the port in the payload. The port is the port on the 457 * host returned by silc_key_agreement_get_hostname that is running 458 * the SILC Key Exchange protocol. 459 * 460 ***/ 461 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); 462 463 #endif 464