jpayne@69: /* keyutils.h: key utility library interface
jpayne@69:  *
jpayne@69:  * Copyright (C) 2005,2011 Red Hat, Inc. All Rights Reserved.
jpayne@69:  * Written by David Howells (dhowells@redhat.com)
jpayne@69:  *
jpayne@69:  * This program is free software; you can redistribute it and/or
jpayne@69:  * modify it under the terms of the GNU Lesser General Public License
jpayne@69:  * as published by the Free Software Foundation; either version
jpayne@69:  * 2 of the License, or (at your option) any later version.
jpayne@69:  */
jpayne@69: 
jpayne@69: #ifndef KEYUTILS_H
jpayne@69: #define KEYUTILS_H
jpayne@69: 
jpayne@69: #include <sys/types.h>
jpayne@69: #include <stdint.h>
jpayne@69: 
jpayne@69: extern const char keyutils_version_string[];
jpayne@69: extern const char keyutils_build_string[];
jpayne@69: 
jpayne@69: /* key serial number */
jpayne@69: typedef int32_t key_serial_t;
jpayne@69: 
jpayne@69: /* special process keyring shortcut IDs */
jpayne@69: #define KEY_SPEC_THREAD_KEYRING		-1	/* - key ID for thread-specific keyring */
jpayne@69: #define KEY_SPEC_PROCESS_KEYRING	-2	/* - key ID for process-specific keyring */
jpayne@69: #define KEY_SPEC_SESSION_KEYRING	-3	/* - key ID for session-specific keyring */
jpayne@69: #define KEY_SPEC_USER_KEYRING		-4	/* - key ID for UID-specific keyring */
jpayne@69: #define KEY_SPEC_USER_SESSION_KEYRING	-5	/* - key ID for UID-session keyring */
jpayne@69: #define KEY_SPEC_GROUP_KEYRING		-6	/* - key ID for GID-specific keyring */
jpayne@69: #define KEY_SPEC_REQKEY_AUTH_KEY	-7	/* - key ID for assumed request_key auth key */
jpayne@69: 
jpayne@69: /* request-key default keyrings */
jpayne@69: #define KEY_REQKEY_DEFL_NO_CHANGE		-1
jpayne@69: #define KEY_REQKEY_DEFL_DEFAULT			0
jpayne@69: #define KEY_REQKEY_DEFL_THREAD_KEYRING		1
jpayne@69: #define KEY_REQKEY_DEFL_PROCESS_KEYRING		2
jpayne@69: #define KEY_REQKEY_DEFL_SESSION_KEYRING		3
jpayne@69: #define KEY_REQKEY_DEFL_USER_KEYRING		4
jpayne@69: #define KEY_REQKEY_DEFL_USER_SESSION_KEYRING	5
jpayne@69: #define KEY_REQKEY_DEFL_GROUP_KEYRING		6
jpayne@69: 
jpayne@69: /* key handle permissions mask */
jpayne@69: typedef uint32_t key_perm_t;
jpayne@69: 
jpayne@69: #define KEY_POS_VIEW	0x01000000	/* possessor can view a key's attributes */
jpayne@69: #define KEY_POS_READ	0x02000000	/* possessor can read key payload / view keyring */
jpayne@69: #define KEY_POS_WRITE	0x04000000	/* possessor can update key payload / add link to keyring */
jpayne@69: #define KEY_POS_SEARCH	0x08000000	/* possessor can find a key in search / search a keyring */
jpayne@69: #define KEY_POS_LINK	0x10000000	/* possessor can create a link to a key/keyring */
jpayne@69: #define KEY_POS_SETATTR	0x20000000	/* possessor can set key attributes */
jpayne@69: #define KEY_POS_ALL	0x3f000000
jpayne@69: 
jpayne@69: #define KEY_USR_VIEW	0x00010000	/* user permissions... */
jpayne@69: #define KEY_USR_READ	0x00020000
jpayne@69: #define KEY_USR_WRITE	0x00040000
jpayne@69: #define KEY_USR_SEARCH	0x00080000
jpayne@69: #define KEY_USR_LINK	0x00100000
jpayne@69: #define KEY_USR_SETATTR	0x00200000
jpayne@69: #define KEY_USR_ALL	0x003f0000
jpayne@69: 
jpayne@69: #define KEY_GRP_VIEW	0x00000100	/* group permissions... */
jpayne@69: #define KEY_GRP_READ	0x00000200
jpayne@69: #define KEY_GRP_WRITE	0x00000400
jpayne@69: #define KEY_GRP_SEARCH	0x00000800
jpayne@69: #define KEY_GRP_LINK	0x00001000
jpayne@69: #define KEY_GRP_SETATTR	0x00002000
jpayne@69: #define KEY_GRP_ALL	0x00003f00
jpayne@69: 
jpayne@69: #define KEY_OTH_VIEW	0x00000001	/* third party permissions... */
jpayne@69: #define KEY_OTH_READ	0x00000002
jpayne@69: #define KEY_OTH_WRITE	0x00000004
jpayne@69: #define KEY_OTH_SEARCH	0x00000008
jpayne@69: #define KEY_OTH_LINK	0x00000010
jpayne@69: #define KEY_OTH_SETATTR	0x00000020
jpayne@69: #define KEY_OTH_ALL	0x0000003f
jpayne@69: 
jpayne@69: /* keyctl commands */
jpayne@69: #define KEYCTL_GET_KEYRING_ID		0	/* ask for a keyring's ID */
jpayne@69: #define KEYCTL_JOIN_SESSION_KEYRING	1	/* join or start named session keyring */
jpayne@69: #define KEYCTL_UPDATE			2	/* update a key */
jpayne@69: #define KEYCTL_REVOKE			3	/* revoke a key */
jpayne@69: #define KEYCTL_CHOWN			4	/* set ownership of a key */
jpayne@69: #define KEYCTL_SETPERM			5	/* set perms on a key */
jpayne@69: #define KEYCTL_DESCRIBE			6	/* describe a key */
jpayne@69: #define KEYCTL_CLEAR			7	/* clear contents of a keyring */
jpayne@69: #define KEYCTL_LINK			8	/* link a key into a keyring */
jpayne@69: #define KEYCTL_UNLINK			9	/* unlink a key from a keyring */
jpayne@69: #define KEYCTL_SEARCH			10	/* search for a key in a keyring */
jpayne@69: #define KEYCTL_READ			11	/* read a key or keyring's contents */
jpayne@69: #define KEYCTL_INSTANTIATE		12	/* instantiate a partially constructed key */
jpayne@69: #define KEYCTL_NEGATE			13	/* negate a partially constructed key */
jpayne@69: #define KEYCTL_SET_REQKEY_KEYRING	14	/* set default request-key keyring */
jpayne@69: #define KEYCTL_SET_TIMEOUT		15	/* set timeout on a key */
jpayne@69: #define KEYCTL_ASSUME_AUTHORITY		16	/* assume authority to instantiate key */
jpayne@69: #define KEYCTL_GET_SECURITY		17	/* get key security label */
jpayne@69: #define KEYCTL_SESSION_TO_PARENT	18	/* set my session keyring on my parent process */
jpayne@69: #define KEYCTL_REJECT			19	/* reject a partially constructed key */
jpayne@69: #define KEYCTL_INSTANTIATE_IOV		20	/* instantiate a partially constructed key */
jpayne@69: #define KEYCTL_INVALIDATE		21	/* invalidate a key */
jpayne@69: #define KEYCTL_GET_PERSISTENT		22	/* get a user's persistent keyring */
jpayne@69: #define KEYCTL_DH_COMPUTE		23	/* Compute Diffie-Hellman values */
jpayne@69: #define KEYCTL_PKEY_QUERY		24	/* Query public key parameters */
jpayne@69: #define KEYCTL_PKEY_ENCRYPT		25	/* Encrypt a blob using a public key */
jpayne@69: #define KEYCTL_PKEY_DECRYPT		26	/* Decrypt a blob using a public key */
jpayne@69: #define KEYCTL_PKEY_SIGN		27	/* Create a public key signature */
jpayne@69: #define KEYCTL_PKEY_VERIFY		28	/* Verify a public key signature */
jpayne@69: #define KEYCTL_RESTRICT_KEYRING		29	/* Restrict keys allowed to link to a keyring */
jpayne@69: #define KEYCTL_MOVE			30	/* Move keys between keyrings */
jpayne@69: #define KEYCTL_CAPABILITIES		31	/* Find capabilities of keyrings subsystem */
jpayne@69: 
jpayne@69: /* keyctl structures */
jpayne@69: struct keyctl_dh_params {
jpayne@69: 	key_serial_t priv;
jpayne@69: 	key_serial_t prime;
jpayne@69: 	key_serial_t base;
jpayne@69: };
jpayne@69: 
jpayne@69: struct keyctl_kdf_params {
jpayne@69: 	char *hashname;
jpayne@69: 	char *otherinfo;
jpayne@69: 	uint32_t otherinfolen;
jpayne@69: 	uint32_t __spare[8];
jpayne@69: };
jpayne@69: 
jpayne@69: #define KEYCTL_SUPPORTS_ENCRYPT		0x01
jpayne@69: #define KEYCTL_SUPPORTS_DECRYPT		0x02
jpayne@69: #define KEYCTL_SUPPORTS_SIGN		0x04
jpayne@69: #define KEYCTL_SUPPORTS_VERIFY		0x08
jpayne@69: 
jpayne@69: struct keyctl_pkey_query {
jpayne@69: 	unsigned int	supported_ops;	/* Which ops are supported */
jpayne@69: 	unsigned int	key_size;	/* Size of the key in bits */
jpayne@69: 	unsigned short	max_data_size;	/* Maximum size of raw data to sign in bytes */
jpayne@69: 	unsigned short	max_sig_size;	/* Maximum size of signature in bytes */
jpayne@69: 	unsigned short	max_enc_size;	/* Maximum size of encrypted blob in bytes */
jpayne@69: 	unsigned short	max_dec_size;	/* Maximum size of decrypted blob in bytes */
jpayne@69: 	unsigned int	__spare[10];
jpayne@69: };
jpayne@69: 
jpayne@69: struct keyctl_pkey_params {
jpayne@69: 	key_serial_t	key_id;		/* Serial no. of public key to use */
jpayne@69: 	unsigned int	in_len;		/* Input data size */
jpayne@69: 	union {
jpayne@69: 		unsigned int	out_len; /* Output buffer size (encrypt/decrypt/sign) */
jpayne@69: 		unsigned int	in2_len; /* Second input data size (verify) */
jpayne@69: 	};
jpayne@69: 	unsigned int	__spare[7];
jpayne@69: };
jpayne@69: 
jpayne@69: #define KEYCTL_MOVE_EXCL	0x00000001 /* Do not displace from the to-keyring */
jpayne@69: 
jpayne@69: /*
jpayne@69:  * Capabilities flags.  The capabilities list is an array of 8-bit integers;
jpayne@69:  * each integer can carry up to 8 flags.
jpayne@69:  */
jpayne@69: #define KEYCTL_CAPS0_CAPABILITIES	0x01 /* KEYCTL_CAPABILITIES supported */
jpayne@69: #define KEYCTL_CAPS0_PERSISTENT_KEYRINGS 0x02 /* Persistent keyrings enabled */
jpayne@69: #define KEYCTL_CAPS0_DIFFIE_HELLMAN	0x04 /* Diffie-Hellman ops enabled */
jpayne@69: #define KEYCTL_CAPS0_PUBLIC_KEY		0x08 /* Public key ops enabled */
jpayne@69: #define KEYCTL_CAPS0_BIG_KEY		0x10 /* big_key-type enabled */
jpayne@69: #define KEYCTL_CAPS0_INVALIDATE		0x20 /* KEYCTL_INVALIDATE supported */
jpayne@69: #define KEYCTL_CAPS0_RESTRICT_KEYRING	0x40 /* KEYCTL_RESTRICT_KEYRING supported */
jpayne@69: #define KEYCTL_CAPS0_MOVE		0x80 /* KEYCTL_MOVE supported */
jpayne@69: 
jpayne@69: /*
jpayne@69:  * syscall wrappers
jpayne@69:  */
jpayne@69: extern key_serial_t add_key(const char *type,
jpayne@69: 			    const char *description,
jpayne@69: 			    const void *payload,
jpayne@69: 			    size_t plen,
jpayne@69: 			    key_serial_t ringid);
jpayne@69: 
jpayne@69: extern key_serial_t request_key(const char *type,
jpayne@69: 				const char *description,
jpayne@69: 				const char *callout_info,
jpayne@69: 				key_serial_t destringid);
jpayne@69: 
jpayne@69: extern long keyctl(int cmd, ...);
jpayne@69: 
jpayne@69: /*
jpayne@69:  * keyctl function wrappers
jpayne@69:  */
jpayne@69: extern key_serial_t keyctl_get_keyring_ID(key_serial_t id, int create);
jpayne@69: extern key_serial_t keyctl_join_session_keyring(const char *name);
jpayne@69: extern long keyctl_update(key_serial_t id, const void *payload, size_t plen);
jpayne@69: extern long keyctl_revoke(key_serial_t id);
jpayne@69: extern long keyctl_chown(key_serial_t id, uid_t uid, gid_t gid);
jpayne@69: extern long keyctl_setperm(key_serial_t id, key_perm_t perm);
jpayne@69: extern long keyctl_describe(key_serial_t id, char *buffer, size_t buflen);
jpayne@69: extern long keyctl_clear(key_serial_t ringid);
jpayne@69: extern long keyctl_link(key_serial_t id, key_serial_t ringid);
jpayne@69: extern long keyctl_unlink(key_serial_t id, key_serial_t ringid);
jpayne@69: extern long keyctl_search(key_serial_t ringid,
jpayne@69: 			  const char *type,
jpayne@69: 			  const char *description,
jpayne@69: 			  key_serial_t destringid);
jpayne@69: extern long keyctl_read(key_serial_t id, char *buffer, size_t buflen);
jpayne@69: extern long keyctl_instantiate(key_serial_t id,
jpayne@69: 			       const void *payload,
jpayne@69: 			       size_t plen,
jpayne@69: 			       key_serial_t ringid);
jpayne@69: extern long keyctl_negate(key_serial_t id, unsigned timeout, key_serial_t ringid);
jpayne@69: extern long keyctl_set_reqkey_keyring(int reqkey_defl);
jpayne@69: extern long keyctl_set_timeout(key_serial_t key, unsigned timeout);
jpayne@69: extern long keyctl_assume_authority(key_serial_t key);
jpayne@69: extern long keyctl_get_security(key_serial_t key, char *buffer, size_t buflen);
jpayne@69: extern long keyctl_session_to_parent(void);
jpayne@69: extern long keyctl_reject(key_serial_t id, unsigned timeout, unsigned error,
jpayne@69: 			  key_serial_t ringid);
jpayne@69: struct iovec;
jpayne@69: extern long keyctl_instantiate_iov(key_serial_t id,
jpayne@69: 				   const struct iovec *payload_iov,
jpayne@69: 				   unsigned ioc,
jpayne@69: 				   key_serial_t ringid);
jpayne@69: extern long keyctl_invalidate(key_serial_t id);
jpayne@69: extern long keyctl_get_persistent(uid_t uid, key_serial_t id);
jpayne@69: extern long keyctl_dh_compute(key_serial_t priv, key_serial_t prime,
jpayne@69: 			      key_serial_t base, char *buffer, size_t buflen);
jpayne@69: extern long keyctl_dh_compute_kdf(key_serial_t private, key_serial_t prime,
jpayne@69: 				  key_serial_t base, char *hashname,
jpayne@69: 				  char *otherinfo, size_t otherinfolen,
jpayne@69: 				  char *buffer, size_t buflen);
jpayne@69: extern long keyctl_restrict_keyring(key_serial_t keyring, const char *type,
jpayne@69: 				    const char *restriction);
jpayne@69: 
jpayne@69: extern long keyctl_pkey_query(key_serial_t key_id,
jpayne@69: 			      const char *info,
jpayne@69: 			      struct keyctl_pkey_query *result);
jpayne@69: extern long keyctl_pkey_encrypt(key_serial_t key_id,
jpayne@69: 				const char *info,
jpayne@69: 				const void *data, size_t data_len,
jpayne@69: 				void *enc, size_t enc_len);
jpayne@69: extern long keyctl_pkey_decrypt(key_serial_t key_id,
jpayne@69: 				const char *info,
jpayne@69: 				const void *enc, size_t enc_len,
jpayne@69: 				void *data, size_t data_len);
jpayne@69: extern long keyctl_pkey_sign(key_serial_t key_id,
jpayne@69: 			     const char *info,
jpayne@69: 			     const void *data, size_t data_len,
jpayne@69: 			     void *sig, size_t sig_len);
jpayne@69: extern long keyctl_pkey_verify(key_serial_t key_id,
jpayne@69: 			       const char *info,
jpayne@69: 			       const void *data, size_t data_len,
jpayne@69: 			       const void *sig, size_t sig_len);
jpayne@69: extern long keyctl_move(key_serial_t id,
jpayne@69: 			key_serial_t from_ringid,
jpayne@69: 			key_serial_t to_ringid,
jpayne@69: 			unsigned int flags);
jpayne@69: extern long keyctl_capabilities(unsigned char *buffer, size_t buflen);
jpayne@69: 
jpayne@69: /*
jpayne@69:  * utilities
jpayne@69:  */
jpayne@69: extern int keyctl_describe_alloc(key_serial_t id, char **_buffer);
jpayne@69: extern int keyctl_read_alloc(key_serial_t id, void **_buffer);
jpayne@69: extern int keyctl_get_security_alloc(key_serial_t id, char **_buffer);
jpayne@69: extern int keyctl_dh_compute_alloc(key_serial_t priv, key_serial_t prime,
jpayne@69: 				   key_serial_t base, void **_buffer);
jpayne@69: 
jpayne@69: typedef int (*recursive_key_scanner_t)(key_serial_t parent, key_serial_t key,
jpayne@69: 				       char *desc, int desc_len, void *data);
jpayne@69: extern int recursive_key_scan(key_serial_t key, recursive_key_scanner_t func, void *data);
jpayne@69: extern int recursive_session_key_scan(recursive_key_scanner_t func, void *data);
jpayne@69: extern key_serial_t find_key_by_type_and_desc(const char *type, const char *desc,
jpayne@69: 					      key_serial_t destringid);
jpayne@69: 
jpayne@69: #endif /* KEYUTILS_H */